@akinet/akidevrule 3.1.1 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [Unreleased]
+
+## [3.3.0] - 2026-09-19
+
+### Changed
+- **`/akiship` and `release` are hardened: mandatory rule load, fail-closed checklist receipts, a migration doctrine, and post-deploy functional verification (`release.B5`, `B7`, `B11`; `akiship`).** Evidence: a release passed the full ritual and shipped an index on a new column created inside a constructor before the column existed, so the store failed to open on the upgraded production database; every gate stayed green because the migration was startup code (not a script the gate looked for), every test started from an empty database, the post-deploy check read only the version, and the health endpoint returned a hardcoded `ok`. Separately, the ritual has been run loosely on several recent releases, and an advisory checklist cannot be audited. Root cause: the gate modelled migration as a separate script, checked only by location; nothing forced upgrade-path rehearsal, function-level post-deploy verification, or proof that each step ran. Mechanism: `akiship` now opens with a CRITICAL mandatory `Read` of `RULE-release.md` and `RULE-docs.md` (a run without it is invalid); `B7` becomes fail-closed: one `S<n>` receipt line with quoted evidence per step, a missing line means NOT RUN and forbids commit/mint/tag/push/deploy, hedge words are scored unverified, and four self-interrogation questions are answered in the report; `B5` adds a five-point migration doctrine (detect by effect with a diff detector run every release, separate artifact, expand → migrate → deploy code → contract, rehearse from the previous state never from empty, asserted postconditions and a named rollback); new `B11` requires exercising a data path after every deploy and calls a constant-`ok` health endpoint a false instrument. Rejected: making the health endpoint fail the process on any subsystem error (a non-critical component would then take the whole service down; degrade visibly instead), and a per-project patch (the gap is in the shared gate). Tradeoff: every release now writes more evidence; that is the intended cost. `akirule` routes `migration`, `/health` and `post-deploy` signals to `RULE-release.md`.
+- **`agent.A2`/`agent.A5` now narrow exploration at the source before crossing a worker boundary.** Evidence: three independent over-exploration incidents spent approximately 92k tokens and 30 minutes on the Gegrok/checkjoin investigation, 67,329 tokens with 16 tool uses over 568,376 ms on the first delegation-rule review, and 56,965 tokens with 8 tool uses over 442,002 ms on the ladder stress test. Root cause: A2 and A5 each established an asymmetric default-to-delegate policy, while the inline exception was limited to one already-known file and worker startup, briefing, latency, observability, and invisible cross-process spend arrived only after the license. Mechanism: A2 now owns direct batching and source narrowing and points to A5 as the sole route decision; A5 runs a bounded command, restricted read, pipeline, or batch when it can return the answer or a lossless decision digest, permits one bounded probe when the route is unclear and lets that probe finish the task, delegates only unavoidable context flooding with an exact brief, keeps conversation-dependent or ambiguous judgment in the caller, prefers a fresh worker over a fork, and denies recursive delegation without explicit depth and width. Rejected: fixed token/time/file thresholds (not reliably measurable or portable), automatic delegation on a third discovery operation (detects drift but chooses the wrong route for small work), and a penalty card (this is a pre-action decision defect, not a locally repairable output defect). Full evidence and six-round critique: `docs/plan/done/rebalance-exploration-delegation.md`.
+
+## [3.2.0] - 2026-09-15
+
+### Added
+- **Installer auto-discovers and deploys to all Claude config directory profiles (`~/.claude*`, `$CLAUDE_CONFIG_DIR`, `--claude-dir`).**
+  - **Evidence:** Users running alternate Claude Code profiles (such as `CLAUDE_CONFIG_DIR=~/.claude-9rt` or `~/.claude-prx` for proxy routing or multi-account quotas) noticed that running `./install.sh` / `node install.mjs` only installed skills, agents, hooks, and CLAUDE.md into the default `~/.claude/`. Alternate profiles were missing new agents, updated skills, and update hooks unless manually symlinked or copied per folder.
+  - **Root cause:** `install.mjs` hardcoded `CLAUDE_DIR = join(HOME, ".claude")` with no auto-detection, no `$CLAUDE_CONFIG_DIR` awareness, and no CLI parameter for alternate profile roots.
+  - **Mechanism:** `getClaudeDirs()` auto-discovers all `~/.claude*` directories under `$HOME`, respects `$CLAUDE_CONFIG_DIR` and `--claude-dir <path>`, deduplicates canonical paths across symlinks, and synchronizes skills, agents, hooks, `CLAUDE.md`, and `settings.json` across all detected profiles in a single install pass. New variant profiles automatically seed `CLAUDE.local.md` importing `@~/.claude/CLAUDE.local.md` to inherit machine-local facts. Antigravity and Kiro permission allowlists now expand to cover skill scripts across all detected Claude roots.
+  - **Tradeoff / rejected alternative:** Requiring the user to run `CLAUDE_CONFIG_DIR=... ./install.sh` separately for each profile was rejected — it is tedious, easy to forget, and leaves profiles silently drifting out of sync. Auto-discovering all sibling `~/.claude*` profiles by default makes a single install update the entire machine's Claude environments simultaneously.
+
+### Fixed
+- **Installer preflight now prevents partial installs, legacy migration follows confirmation, and Antigravity permission-only updates persist.** Evidence: malformed Claude, Gemini skills, or Antigravity settings could be handled during mutation; legacy root migration could run before an interactive cancellation; and Antigravity's `allowNonWorkspaceAccess`, `agentMode`, and `trustedWorkspaces` did not save when they were the only differences. Root cause: not every later-mutated JSON file was validated up front, malformed Gemini files were silently replaced or skipped, migration preceded confirmation, and those Antigravity fields did not update change tracking. Mechanism: before the prompt or any mutation, the installer requires every existing Claude `settings.json`, Gemini `config/skills.json`, Antigravity CLI settings, and Gemini settings to parse as an object; cancellation precedes migration; later merges parse directly and Antigravity fields mark their settings file changed. Tradeoff / rejected alternative: continuing with valid profiles or silently replacing malformed JSON was rejected because partial machine configuration and lost user configuration are harder to repair than one explicit failed install.
+
 ## [3.1.1] - 2026-09-15
 
 ### Fixed

package/README.md

@@ -72,7 +72,7 @@ Interpreter convention (documented once): the installer and hooks run on `node`
 | `aki-article-writer` | `/aki-article-writer` or natural language | Per-project article writing pipeline: research & fact-verification, SEO metadata, JSON-LD schema, UX-psychology-aware content, and a dedicated Image Scout subagent (Gemini Flash / Haiku) for search → download → visual inspection → ffmpeg processing → slug-named WebP output. One subagent per article; image work is always isolated to a separate lightweight subagent. |
 | `akidevsync-notes` | natural language | Reads/edits a project's `.akidevsync/notes.json` — the per-project task list the Aki-Dev-Sync app itself writes (list/add/pin/mark-done/edit/delete tasks) via a bundled script that preserves the app's own JSON formatting, plus a workflow for cross-checking pinned notes against a shipped release (CHANGELOG + code) before marking them done. |
 | `akilint` | `/akilint` or a penalty card | Mechanical format lint for the penalty-card classes of `RULE-agent-behavior.md` §0: hard-wrapped code comments and markdown prose (`[WRAP]`) and oversize comments (`[YAP]`, always labeled *review* — a flag for judgment against `coding.B4`, never an auto-delete verdict). Thin wrapper over the shared `scythe.py` detector (deterministic line matching, exit-code aware, cannot fabricate evidence) — the same script akiflow's `aki-conduct` seat uses, so a card name means the same thing everywhere. `[FLUFF]` (density) is content judgment and explicitly out of a script's reach. |
-| `akiship` | `/akiship` | One-command full release: front-loads every check (release state, tree triage), then runs `RULE-release.md` B7's checklist unattended — diff-scoped hygiene (scythe, dead code, comment doc-refs on the accumulation only), external-action completeness, record truthfulness, build & test mirroring CI (B7 step 6), doc sync across every record surface (plans, `arch`/`feat`, README, task notes, bound standards docs), version mint or defer, registry publish for npm/crates/PyPI packages (`RULE-release.md` B9 — an OTP-gated publish is the single hand-off) — committing via `akigitcommit` with confirmation pre-answered. **Activation is an explicit release order**: the literal token `/akiship`, or an equally explicit imperative naming the ritual for this repo ("release trọn vẹn đi") — a completion word with no release object ("làm cho trọn vẹn"), or `/akiship` inside a question, activates nothing and gets a consult (answer in chat, change nothing). Governed by the B8 contract: that order is the authorization, blockers are reported once as a batch or the run completes with zero mid-run questions, and it stops only for public-history ambiguity, unclassifiable work, or a design contradiction — an owner-worded completion criterion is derived from the anchor plus the repo's own records and decided/reported (`Decided: X · because Y · rejected Z (why) · reopen if W`), escalated only when competing readings would produce different irreversible artifacts. Push/deploy stay opt-in — named explicitly, or via completion-intensity phrasing (canonical list in `RULE-release.md` B8, e.g. "trọn vẹn") — and after any push, CI is watched to green (`RULE-release.md` B10) regardless of whether the stack deploys. |
+| `akiship` | `/akiship` | One-command full release: front-loads every check (release state, tree triage), then runs `RULE-release.md` B7's fail-closed checklist unattended (CRITICAL mandatory `Read` of `RULE-release.md` and `RULE-docs.md` first; a `S0`–`S8` receipt line with quoted evidence per step or the step counts as NOT RUN; written self-interrogation) — diff-scoped hygiene (scythe, dead code, comment doc-refs on the accumulation only), migration doctrine (`RULE-release.md` B5: detector over the diff on every release, startup-embedded migration counts, rehearsal from the PREVIOUS state) and external-action completeness, record truthfulness, build & test mirroring CI (B7 step 6), doc sync across every record surface (plans, `arch`/`feat`, README, task notes, bound standards docs), version mint or defer, registry publish for npm/crates/PyPI packages (`RULE-release.md` B9 — an OTP-gated publish is the single hand-off) — committing via `akigitcommit` with confirmation pre-answered. **Activation is an explicit release order**: the literal token `/akiship`, or an equally explicit imperative naming the ritual for this repo ("release trọn vẹn đi") — a completion word with no release object ("làm cho trọn vẹn"), or `/akiship` inside a question, activates nothing and gets a consult (answer in chat, change nothing). Governed by the B8 contract: that order is the authorization, blockers are reported once as a batch or the run completes with zero mid-run questions, and it stops only for public-history ambiguity, unclassifiable work, or a design contradiction — an owner-worded completion criterion is derived from the anchor plus the repo's own records and decided/reported (`Decided: X · because Y · rejected Z (why) · reopen if W`), escalated only when competing readings would produce different irreversible artifacts. Push/deploy stay opt-in — named explicitly, or via completion-intensity phrasing (canonical list in `RULE-release.md` B8, e.g. "trọn vẹn") — and after any push, CI is watched to green (`RULE-release.md` B10) regardless of whether the stack deploys, and after any deploy a data path the release touched is exercised (`RULE-release.md` B11). |
 
 ### Five agent definitions
 
@@ -267,8 +267,8 @@ flowchart TD
         R_META[".source-repo & .version"]
     end
 
-    %% TARGET 2: ~/.claude/
-    subgraph T2["🤖 2. Claude Code Agent (~/.claude/)"]
+    %% TARGET 2: ~/.claude/ and ~/.claude-*
+    subgraph T2["🤖 2. Claude Code Agent (~/.claude/ & ~/.claude-*)"]
         C_MD["CLAUDE.md (Managed prompt)"]
         C_LOCAL["CLAUDE.local.md (Machine local)"]
         C_SKILLS["skills/<skill_name>/SKILL.md"]
@@ -308,14 +308,16 @@ flowchart TD
 Targets 4-6 only get the shared skill corpus (no rule corpus / no `CLAUDE.md`/`GEMINI.md`-style overrides — those CLIs have no equivalent hard-load hook this baseline plugs into yet). Each sync is scoped per skill folder name via a Node `fs` copy plus a managed-names-only prune, same never-touch-the-rest guarantee as targets 2 and 3, and runs unconditionally — harmless if that CLI isn't installed on the machine, picked up the moment it is.
 
 1. Syncs `payload/*` into `~/.aki/akidevrule/` (Node `fs` copy, excludes `ref-ECC/`), removes stale files left by renames, syncs `agskills/` for Antigravity skill inheritance, and deploys the full TCC lookup to `~/.aki/akidevrule/docs/ref/macos-codesign-tcc.md`.
-2. Syncs every skill folder under `skills/*/` (whole directory, including any `references/` or `scripts/`) into `~/.claude/skills/`, one named folder at a time (copy + managed-names-only prune), removing only Aki's own old/renamed skill directories (`akidoc-*`, `akiadvise`) — any other skill you already have is never touched. `skills/` is a top-level, agent-neutral folder (siblings with `payload/`, not nested under `claude/`) because SKILL.md is a shared open standard both Claude Code and Antigravity/AGY consume identically — see [docs/ref/agent-skills-standard.md](docs/ref/agent-skills-standard.md).
-3. Copies `claude/agents/*.md` into `~/.claude/agents/` **file by file, never a directory mirror with `--delete`** — that folder is a shared namespace where your own agent definitions sit beside Aki's, exactly like `~/.claude/skills/`, so nothing you did not install is ever removed.
-4. Replaces `~/.claude/CLAUDE.md` with the packaged guidance (timestamped backup first), appending this machine's source-repo path and an `@~/.claude/CLAUDE.local.md` import.
-5. Creates `~/.claude/CLAUDE.local.md` **only if missing** — never overwritten afterward. Put per-machine rules there (build constraints, IDE paths, remote flags); they survive every reinstall.
-6. Updates `~/.claude/settings.json` (timestamped backup first): read permission for `~/.aki/akidevrule/**`, skill script execution permissions (`Bash(python3 ~/.claude/skills/**)`), `skillOverrides.akirule = "on"`, idempotent registration of the `SessionStart` update-check hook.
-7. Installs `~/.claude/hooks/aki-update-check.mjs` plus its shared parser `~/.claude/hooks/aki_version_check.mjs`, and records the source-repo path in `~/.aki/akidevrule/.source-repo`. Writes `~/.aki/akidevrule/.version` with `installed=`/`version=`/`commit=`/`branch=` — `version=` is the just-installed CHANGELOG's latest released semver, the same value `install.mjs --check` and the hook compare against remote.
-8. Installs `payload/GEMINI.md` to `~/.gemini/GEMINI.md` — Antigravity global behavior overrides, stamped with a version marker (`[AKIRULE-AG-OVERRIDES-…]`) on line 1. Generates 18 native rule files under `~/.gemini/config/rules/` with YAML `trigger` frontmatter. Deploys 10 skills directly to `~/.gemini/config/skills/` for native auto-discovery (synced per skill folder, same never-touch-the-rest guarantee as step 2), configures `~/.gemini/config/skills.json` with absolute paths as secondary, and merges skill execution permissions into `~/.gemini/antigravity-cli/settings.json` and `~/.gemini/settings.json` — a `command()` prefix rule for each of akiflow's five scripts (the only skill whose scripts agy invokes directly) per skill root, in both the expanded and the tilde-literal rendering (agy's matcher compares command strings literally — no glob expansion, and no tilde expansion in either direction — so a directory wildcard never matches and a rule only matches a command written the same way; see [docs/ref/cli-permission-allowlist-standard.md](docs/ref/cli-permission-allowlist-standard.md) §1.2) plus scoped `write_file`/`read_file` rules for the council workspace and rule corpus.
-9. Syncs the same skill folders to `~/.agents/skills/` (Codex CLI), `~/.kiro/skills/` (Kiro CLI, plus pre-allowed shell permissions in `~/.kiro/settings/permissions.yaml`), and `~/.grok/skills/` (Grok CLI) — each a plain global skills root these CLIs read natively, synced per skill folder name exactly like step 2. Skills-only: no rule corpus is generated for these targets.
+2. Deploys to **all detected Claude config directories** — `~/.claude` (default primary), all existing `~/.claude*` profile variants (e.g. `~/.claude-9rt`, `~/.claude-prx`), plus `$CLAUDE_CONFIG_DIR` or `--claude-dir <path>` if provided:
+   - Syncs every skill folder under `skills/*/` (whole directory, including any `references/` or `scripts/`) into `<target>/skills/`, one named folder at a time (copy + managed-names-only prune), removing only Aki's own old/renamed skill directories (`akidoc-*`, `akiadvise`) — any other skill you already have is never touched. `skills/` is a top-level, agent-neutral folder (siblings with `payload/`, not nested under `claude/`) because SKILL.md is a shared open standard both Claude Code and Antigravity/AGY consume identically — see [docs/ref/agent-skills-standard.md](docs/ref/agent-skills-standard.md).
+   - Copies `claude/agents/*.md` into `<target>/agents/` **file by file, never a directory mirror with `--delete`** — that folder is a shared namespace where your own agent definitions sit beside Aki's, exactly like `<target>/skills/`, so nothing you did not install is ever removed.
+   - Replaces `<target>/CLAUDE.md` with the packaged guidance (timestamped backup first), appending this machine's source-repo path and an `@<target>/CLAUDE.local.md` import.
+   - Creates `<target>/CLAUDE.local.md` **only if missing** — never overwritten afterward. On profile variants (`~/.claude-*`), the template imports `@~/.claude/CLAUDE.local.md` by default so machine-wide facts are inherited. Put per-machine/per-profile rules there; they survive every reinstall.
+   - Before the confirmation prompt or any mutation, preflights every existing JSON file it may update: each detected profile's `settings.json`, `~/.gemini/config/skills.json`, `~/.gemini/antigravity-cli/settings.json`, and `~/.gemini/settings.json`. A malformed file or non-object root aborts the install with originals untouched. After preflight, updates `<target>/settings.json` with a timestamped backup: read permission for `~/.aki/akidevrule/**`, skill script execution permissions (`Bash(python3 <target>/skills/*)` and `Bash(python3 ~/.claude/skills/*)`), `skillOverrides.akirule = "on"`, idempotent registration of the `SessionStart` update-check hook.
+   - Installs `<target>/hooks/aki-update-check.mjs` plus its shared parser `<target>/hooks/aki_version_check.mjs`.
+3. Writes `~/.aki/akidevrule/.version` with `installed=`/`version=`/`commit=`/`branch=` and records the source-repo path in `~/.aki/akidevrule/.source-repo` — `version=` is the just-installed CHANGELOG's latest released semver, the same value `install.mjs --check` and the hook compare against remote.
+4. Installs `payload/GEMINI.md` to `~/.gemini/GEMINI.md` — Antigravity global behavior overrides, stamped with a version marker (`[AKIRULE-AG-OVERRIDES-…]`) on line 1. Generates 18 native rule files under `~/.gemini/config/rules/` with YAML `trigger` frontmatter. Deploys 10 skills directly to `~/.gemini/config/skills/` for native auto-discovery (synced per skill folder, same never-touch-the-rest guarantee as step 2), configures `~/.gemini/config/skills.json` with absolute paths as secondary, and merges skill execution permissions into `~/.gemini/antigravity-cli/settings.json` and `~/.gemini/settings.json` — a `command()` prefix rule for each of akiflow's five scripts (the only skill whose scripts agy invokes directly) per skill root, in both the expanded and the tilde-literal rendering (agy's matcher compares command strings literally — no glob expansion, and no tilde expansion in either direction — so a directory wildcard never matches and a rule only matches a command written the same way; see [docs/ref/cli-permission-allowlist-standard.md](docs/ref/cli-permission-allowlist-standard.md) §1.2) plus scoped `write_file`/`read_file` rules for the council workspace and rule corpus.
+5. Syncs the same skill folders to `~/.agents/skills/` (Codex CLI), `~/.kiro/skills/` (Kiro CLI, plus pre-allowed shell permissions in `~/.kiro/settings/permissions.yaml`), and `~/.grok/skills/` (Grok CLI) — each a plain global skills root these CLIs read natively, synced per skill folder name exactly like step 2. Skills-only: no rule corpus is generated for these targets.
 
 Re-running the installer updates the same managed files cleanly.
 

package/install.mjs

@@ -10,6 +10,7 @@ import {
   copyFileSync,
   rmSync,
   renameSync,
+  realpathSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname, basename, extname, relative, isAbsolute, sep } from "node:path";
@@ -37,7 +38,7 @@ const HOME = homedir();
 const INSTALL_ROOT = join(HOME, ".aki", "akidevrule");
 
 const LEGACY_INSTALL_ROOT = join(HOME, ".aki", "claudedoc");
-const CLAUDE_DIR = join(HOME, ".claude");
+const PRIMARY_CLAUDE_DIR = join(HOME, ".claude");
 const GEMINI_DIR = join(HOME, ".gemini");
 const GEMINI_RULES_DIR = join(GEMINI_DIR, "config", "rules");
 const GEMINI_SKILLS_DIR = join(GEMINI_DIR, "config", "skills");
@@ -50,6 +51,83 @@ const OLD_SKILLS = ["akidoc-rules", "akidoc-flow-audit", "akidoc-techbiz-optimiz
 
 const IS_WIN = process.platform === "win32";
 
+if (Number(process.versions.node.split(".")[0]) < 18) {
+  console.error("akidevrule requires Node.js 18 or later.");
+  process.exit(1);
+}
+
+function expandTilde(p) {
+  if (!p) return "";
+  if (p === "~") return HOME;
+  if (p.startsWith("~" + sep) || p.startsWith("~/")) {
+    return join(HOME, p.slice(2));
+  }
+  return p;
+}
+
+function toTildePath(p) {
+  if (!p) return "";
+  if (p === HOME) return "~";
+  if (p.startsWith(HOME + sep) || p.startsWith(HOME + "/")) {
+    return "~" + p.slice(HOME.length).replace(/\\/g, "/");
+  }
+  return p.replace(/\\/g, "/");
+}
+
+function getClaudeDirs(argv = []) {
+  const dirs = new Set();
+  dirs.add(PRIMARY_CLAUDE_DIR);
+
+  // 1. Explicit CLI arguments: --claude-dir <path> or --claude-dir=<path>
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--claude-dir" && argv[i + 1]) {
+      const p = expandTilde(argv[i + 1].trim());
+      dirs.add(isAbsolute(p) ? p : join(HOME, p));
+    } else if (arg.startsWith("--claude-dir=")) {
+      const p = expandTilde(arg.slice("--claude-dir=".length).trim());
+      dirs.add(isAbsolute(p) ? p : join(HOME, p));
+    }
+  }
+
+  // 2. Environment variable: CLAUDE_CONFIG_DIR
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    const p = expandTilde(process.env.CLAUDE_CONFIG_DIR.trim());
+    if (p) dirs.add(isAbsolute(p) ? p : join(HOME, p));
+  }
+
+  // 3. Auto-discover all ~/.claude* directories in HOME
+  try {
+    for (const name of listDir(HOME)) {
+      if (!name.startsWith(".claude")) continue;
+      const full = join(HOME, name);
+      if (!isDir(full)) continue;
+      if (name.includes("backup") || name.endsWith(".bak")) continue;
+      dirs.add(full);
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // 4. Deduplicate symlinks resolving to the same real directory
+  const canonicalMap = new Map();
+  for (const d of dirs) {
+    let canonical = d;
+    try {
+      canonical = realpathSync(d);
+    } catch {
+      /* directory might not exist yet */
+    }
+    if (!canonicalMap.has(canonical)) {
+      canonicalMap.set(canonical, d);
+    } else if (d === canonical) {
+      canonicalMap.set(canonical, d);
+    }
+  }
+
+  return Array.from(canonicalMap.values()).sort();
+}
+
 function pad2(n) {
   return String(n).padStart(2, "0");
 }
@@ -185,10 +263,10 @@ function syncAkiSkills(destRoot) {
   }
 }
 
-function syncAkiAgents() {
+function syncAkiAgents(destClaudeDir) {
   const agentsSrc = join(REPO_ROOT, "claude", "agents");
   if (!isDir(agentsSrc)) return;
-  const dest = join(CLAUDE_DIR, "agents");
+  const dest = join(destClaudeDir, "agents");
   mkdirSync(dest, { recursive: true });
   for (const name of listDir(agentsSrc).sort()) {
     if (name.endsWith(".md")) copyFileSync(join(agentsSrc, name), join(dest, name));
@@ -396,6 +474,22 @@ function installAgRules() {
 // settings.json merge (Claude Code)
 // ---------------------------------------------------------------------------
 
+function validateJsonObject(path, label) {
+  if (!isFile(path)) return;
+  const data = JSON.parse(readFileSync(path, "utf-8"));
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error(`${label} must be a JSON object: ${path}`);
+  }
+}
+
+function preflightInstallSettings(claudeDirs) {
+  for (const claudeDir of claudeDirs) validateJsonObject(join(claudeDir, "settings.json"), "Claude settings");
+  if (!isDir(GEMINI_DIR)) return;
+  validateJsonObject(join(GEMINI_DIR, "config", "skills.json"), "Gemini skills config");
+  validateJsonObject(join(GEMINI_DIR, "antigravity-cli", "settings.json"), "Antigravity settings");
+  validateJsonObject(join(GEMINI_DIR, "settings.json"), "Antigravity settings");
+}
+
 function mergeSettings(settingsPath, installRoot, claudeDir) {
   const data = JSON.parse(readFileSync(settingsPath, "utf-8"));
 
@@ -419,6 +513,11 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
     "Bash(python3 ~/.claude/skills/*)",
     "Bash(python3 ~/.aki/akidevrule/agskills/*)",
   ];
+  const variantBashRule = `Bash(python3 ${toTildePath(join(claudeDir, "skills"))}/*)`;
+  if (!managedBashRules.includes(variantBashRule)) {
+    managedBashRules.push(variantBashRule);
+  }
+
   perms.allow = perms.allow.filter((x) => !legacyBashRules.includes(x));
   for (const rule of managedBashRules) if (!perms.allow.includes(rule)) perms.allow.push(rule);
 
@@ -462,7 +561,7 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
 // Antigravity permissions merge
 // ---------------------------------------------------------------------------
 
-function mergeAntigravityPermissions() {
+function mergeAntigravityPermissions(claudeDirs = []) {
   if (!isDir(GEMINI_DIR)) return;
 
   const scriptsDir = join(REPO_ROOT, "skills", "akiflow", "scripts");
@@ -470,7 +569,8 @@ function mergeAntigravityPermissions() {
     .filter((n) => n.endsWith(".py"))
     .map((n) => `akiflow/scripts/${n}`)
     .sort();
-  const skillRoots = [GEMINI_SKILLS_DIR, join(CLAUDE_DIR, "skills")];
+  const claudeRoots = claudeDirs.map((d) => join(d, "skills"));
+  const skillRoots = [GEMINI_SKILLS_DIR, ...claudeRoots];
   const launchers = IS_WIN ? ["py -3", "python", "python3"] : ["python3"];
 
   const managedCommands = [];
@@ -506,18 +606,7 @@ function mergeAntigravityPermissions() {
 
   for (const target of targetFiles) {
     let data = {};
-    if (isFile(target)) {
-      try {
-        data = JSON.parse(readFileSync(target, "utf-8"));
-      } catch (e) {
-        console.log(`  \u26a0\ufe0f  Antigravity: ${target} is not parseable JSON (${e}) \u2014 skipped, re-run the installer to retry.`);
-        continue;
-      }
-      if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        console.log(`  \u26a0\ufe0f  Antigravity: ${target} top-level is not an object \u2014 skipped, fix it manually.`);
-        continue;
-      }
-    }
+    if (isFile(target)) data = JSON.parse(readFileSync(target, "utf-8"));
 
     if (typeof data.permissions !== "object" || data.permissions === null || Array.isArray(data.permissions))
       data.permissions = {};
@@ -539,6 +628,23 @@ function mergeAntigravityPermissions() {
       }
     }
 
+    if (perms.allowNonWorkspaceAccess !== true) {
+      perms.allowNonWorkspaceAccess = true;
+      changed = true;
+    }
+    if (perms.agentMode !== true) {
+      perms.agentMode = true;
+      changed = true;
+    }
+    if (!Array.isArray(perms.trustedWorkspaces)) {
+      perms.trustedWorkspaces = [];
+      changed = true;
+    }
+    if (!perms.trustedWorkspaces.includes(HOME)) {
+      perms.trustedWorkspaces.push(HOME);
+      changed = true;
+    }
+
     if (changed || !isFile(target)) {
       mkdirSync(dirname(target), { recursive: true });
       if (isFile(target)) {
@@ -554,7 +660,7 @@ function mergeAntigravityPermissions() {
 // Kiro permissions merge
 // ---------------------------------------------------------------------------
 
-function mergeKiroPermissions() {
+function mergeKiroPermissions(claudeDirs = []) {
   const kiroDir = join(HOME, ".kiro");
   if (!isDir(kiroDir)) return;
 
@@ -564,10 +670,13 @@ function mergeKiroPermissions() {
 
   const managedMatches = [
     "python3 ~/.kiro/skills/*",
-    "python3 ~/.claude/skills/*",
     "python3 ~/.gemini/config/skills/*",
     "python3 ~/.aki/akidevrule/agskills/*",
   ];
+  for (const cDir of claudeDirs) {
+    const m = `python3 ${toTildePath(join(cDir, "skills"))}/*`;
+    if (!managedMatches.includes(m)) managedMatches.push(m);
+  }
 
   if (!isFile(yamlPath)) {
     const lines = [
@@ -593,6 +702,76 @@ function mergeKiroPermissions() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Deploy single Claude target
+// ---------------------------------------------------------------------------
+
+function installClaudeDir(claudeDir) {
+  mkdirSync(claudeDir, { recursive: true });
+
+  // 1. Skills
+  syncAkiSkills(join(claudeDir, "skills"));
+
+  // 2. Agents
+  syncAkiAgents(claudeDir);
+
+  // 3. Hooks
+  const hooksDest = join(claudeDir, "hooks");
+  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"));
+  for (const legacy of ["aki-update-check.py", "aki_version_check.py"]) {
+    const p = join(hooksDest, legacy);
+    if (existsSync(p)) rmrf(p);
+  }
+  const pyCache = join(hooksDest, "__pycache__");
+  if (isDir(pyCache)) {
+    for (const n of readdirSync(pyCache)) if (n.startsWith("aki_version_check.")) rmrf(join(pyCache, n));
+    if (readdirSync(pyCache).length === 0) rmrf(pyCache);
+  }
+
+  // 4. CLAUDE.md
+  const claudeMd = join(claudeDir, "CLAUDE.md");
+  backup(claudeMd);
+  pruneBackups(claudeMd);
+
+  const claudeMdSrc = readFileSync(join(REPO_ROOT, "claude", "CLAUDE.md"), "utf-8");
+  const propagateCmd = `node "${join(REPO_ROOT, "install.mjs")}"`;
+  const localMd = join(claudeDir, "CLAUDE.local.md");
+  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` +
+    `@${localMdTilde}\n`;
+  writeTextLf(claudeMd, claudeMdSrc + ruleSourceBlock);
+
+  // 5. CLAUDE.local.md (create-only if missing)
+  if (!isFile(localMd)) {
+    const isPrimary = claudeDir === PRIMARY_CLAUDE_DIR;
+    const templateContent = isPrimary
+      ? "# Machine-local Claude instructions\n\n" +
+        "This file is machine-specific and never touched by akidevrule installs.\n" +
+        "Add any per-machine rules here (e.g. build constraints, IDE paths, remote flags).\n"
+      : "# Machine-local Claude instructions (profile variant)\n\n" +
+        "This file is machine-specific and never touched by akidevrule installs.\n" +
+        "@~/.claude/CLAUDE.local.md\n\n" +
+        "# Add any profile-specific instructions below:\n";
+    writeTextLf(localMd, templateContent);
+    console.log(`📝 Created ${localMd} (machine-local template)`);
+  }
+
+  // 6. settings.json
+  const settingsPath = join(claudeDir, "settings.json");
+  if (!isFile(settingsPath)) writeTextLf(settingsPath, "{}\n");
+  backup(settingsPath);
+  pruneBackups(settingsPath);
+  mergeSettings(settingsPath, INSTALL_ROOT, claudeDir);
+}
+
 // ---------------------------------------------------------------------------
 // skills.json for Antigravity
 // ---------------------------------------------------------------------------
@@ -600,14 +779,7 @@ function mergeKiroPermissions() {
 function updateSkillsJson() {
   const skillsJson = join(GEMINI_DIR, "config", "skills.json");
   mkdirSync(dirname(skillsJson), { recursive: true });
-  let data = {};
-  if (existsSync(skillsJson)) {
-    try {
-      data = JSON.parse(readFileSync(skillsJson, "utf-8"));
-    } catch {
-      data = {};
-    }
-  }
+  const data = isFile(skillsJson) ? JSON.parse(readFileSync(skillsJson, "utf-8")) : {};
   if (!Array.isArray(data.entries)) data.entries = [];
   const absPath = join(INSTALL_ROOT, "agskills");
   const tildePath = "~/.aki/akidevrule/agskills";
@@ -663,78 +835,71 @@ async function printVersionCheck() {
 // inspect_status (pre-install preview)
 // ---------------------------------------------------------------------------
 
-async function inspectStatus() {
+async function inspectStatus(claudeDirs) {
   console.log(cyanBold("=== SYSTEM STATUS CHECK BEFORE INSTALL ==="));
 
   const head = gitShortHash(REPO_ROOT);
   const sameCheckout = !!head && installedCommit() === head && gitTreeClean(REPO_ROOT);
   if (sameCheckout)
-    console.log(`\u2705 Already installed from this exact commit (${head}, clean tree) \u2014 reinstalling refreshes identical content.`);
+    console.log(`✅ Already installed from this exact commit (${head}, clean tree) — reinstalling refreshes identical content.`);
 
   const { state, localVersion, remoteVersion } = await getVersionStatus();
   if (state === STATE_CURRENT)
-    console.log(`\u2139\ufe0f  Installed release ${localVersion} matches remote; the overwrite below comes from this checkout, which may carry [Unreleased] work.`);
+    console.log(`ℹ️  Installed release ${localVersion} matches remote; the overwrite below comes from this checkout, which may carry [Unreleased] work.`);
   else if (state === STATE_UPDATE)
-    console.log(`\ud83d\udd14 A newer akidevrule is available: ${localVersion} \u2192 ${remoteVersion} (this install only refreshes local files at the current repo checkout's version).`);
+    console.log(`🔔 A newer akidevrule is available: ${localVersion} → ${remoteVersion} (this install only refreshes local files at the current repo checkout's version).`);
   else if (state === STATE_MISSING)
-    console.log("\ud83d\udce6 Fresh install \u2014 akidevrule is not currently installed on this machine.");
+    console.log("📦 Fresh install — akidevrule is not currently installed on this machine.");
   else if (state === STATE_UNKNOWN)
-    console.log("\u26a0\ufe0f  Could not reach the remote CHANGELOG to compare versions (network/parse error) \u2014 proceeding with local install only.");
+    console.log("⚠️  Could not reach the remote CHANGELOG to compare versions (network/parse error) — proceeding with local install only.");
   else if (state === STATE_AHEAD)
-    console.log(`\u2139\ufe0f  Local install (${localVersion || "Unreleased-only"}) is ahead of or diverged from remote (${remoteVersion}).`);
+    console.log(`ℹ️  Local install (${localVersion || "Unreleased-only"}) is ahead of or diverged from remote (${remoteVersion}).`);
 
-  if (isDir(INSTALL_ROOT)) console.log(`\ud83d\udce6 Payload rules: will ${yellowBold("OVERWRITE")} ${INSTALL_ROOT}`);
-  else console.log(`\ud83d\udce6 Payload rules: will ${greenBold("CREATE")} at ${INSTALL_ROOT}`);
+  if (isDir(INSTALL_ROOT)) console.log(`📦 Payload rules: will ${yellowBold("OVERWRITE")} ${INSTALL_ROOT}`);
+  else console.log(`📦 Payload rules: will ${greenBold("CREATE")} at ${INSTALL_ROOT}`);
 
-  const claudeMd = join(CLAUDE_DIR, "CLAUDE.md");
-  if (isFile(claudeMd)) console.log(`\ud83d\udcdd Global CLAUDE.md: will ${yellowBold("OVERWRITE")} ${claudeMd} (backed up)`);
-  else console.log(`\ud83d\udcdd Global CLAUDE.md: will ${greenBold("CREATE")} ${claudeMd}`);
+  console.log(`🤖 Claude config targets (${claudeDirs.length}): ${claudeDirs.map(toTildePath).join(", ")}`);
+  for (const claudeDir of claudeDirs) {
+    const claudeMd = join(claudeDir, "CLAUDE.md");
+    if (isFile(claudeMd)) console.log(`  📝 Global CLAUDE.md (${toTildePath(claudeDir)}): will ${yellowBold("OVERWRITE")} (backed up)`);
+    else console.log(`  📝 Global CLAUDE.md (${toTildePath(claudeDir)}): will ${greenBold("CREATE")}`);
+
+    const oldPresent = OLD_SKILLS.filter((s) => isDir(join(claudeDir, "skills", s)));
+    if (oldPresent.length) console.log(`  🗑️  Old skills in ${toTildePath(claudeDir)} will be REMOVED: ${redBold(oldPresent.join(" "))}`);
+  }
 
   const skillsSrc = join(REPO_ROOT, "skills");
   if (isDir(skillsSrc)) {
-    for (const name of listDir(skillsSrc).sort()) {
-      const skillDir = join(skillsSrc, name);
-      if (!isDir(skillDir)) continue;
-      const destSkill = join(CLAUDE_DIR, "skills", name, "SKILL.md");
-      if (isFile(destSkill)) console.log(`\ud83d\udd27 Skill ${name}: will ${yellowBold("OVERWRITE")} ${destSkill}`);
-      else console.log(`\ud83d\udd27 Skill ${name}: will ${greenBold("CREATE")} ${destSkill}`);
-    }
+    const skillList = listDir(skillsSrc).filter((n) => isDir(join(skillsSrc, n))).sort();
+    console.log(`🔧 Skills (${skillList.length}): will sync to all Claude targets (${skillList.join(", ")})`);
   }
 
   const agentsSrc = join(REPO_ROOT, "claude", "agents");
   if (isDir(agentsSrc)) {
-    for (const name of listDir(agentsSrc).sort()) {
-      if (!name.endsWith(".md")) continue;
-      const destAgent = join(CLAUDE_DIR, "agents", name);
-      if (isFile(destAgent)) console.log(`\ud83e\udde0 Agent ${name}: will ${yellowBold("OVERWRITE")} ${destAgent}`);
-      else console.log(`\ud83e\udde0 Agent ${name}: will ${greenBold("CREATE")} ${destAgent}`);
-    }
+    const agentList = listDir(agentsSrc).filter((n) => n.endsWith(".md")).sort();
+    console.log(`🧠 Agents (${agentList.length}): will sync to all Claude targets (${agentList.map((n) => basename(n, ".md")).join(", ")})`);
   }
 
-  const oldPresent = OLD_SKILLS.filter((s) => isDir(join(CLAUDE_DIR, "skills", s)));
-  if (oldPresent.length) console.log(`\ud83d\uddd1\ufe0f  Old skills will be REMOVED: ${redBold(oldPresent.join(" "))}`);
-
-  console.log("\u2699\ufe0f  settings: checking permissions and skill overrides across platforms...");
-  const settingsPath = join(CLAUDE_DIR, "settings.json");
-  if (isFile(settingsPath)) {
-    try {
-      const data = JSON.parse(readFileSync(settingsPath, "utf-8"));
-      const readRule = `Read(//${INSTALL_ROOT.replace(/^\/+/, "")}/**)`;
-      const allow = (data.permissions && data.permissions.allow) || [];
-      if (allow.includes(readRule)) console.log("  \u2705 Claude Code: Read permission for payload already granted.");
-      else console.log("  \u26a0\ufe0f  Claude Code: Read permission MISSING. Will be added automatically.");
-      if (allow.includes("Bash(python3 ~/.claude/skills/*)")) console.log("  \u2705 Claude Code: Skill scripts Bash execution permission already granted.");
-      else console.log("  \u26a0\ufe0f  Claude Code: Skill scripts Bash execution permission will be added.");
-      const overrides = data.skillOverrides || {};
-      if (overrides.akirule === "on") console.log("  \u2705 Claude Code: akirule skill is already enabled (on).");
-      else console.log("  \u26a0\ufe0f  Claude Code: Will auto-enable skill: akirule");
-      const stale = ["akidoc-rules", "akidoc-flow-audit", "akidoc-techbiz-optimizer"].filter((s) => s in overrides);
-      if (stale.length) console.log(`  \ud83d\uddd1\ufe0f  Claude Code: Stale skillOverrides will be REMOVED: ${stale.join(", ")}`);
-    } catch (e) {
-      console.log(`  \u274c Error reading Claude settings.json: ${e}`);
+  console.log("⚙️  settings: checking permissions and skill overrides across platforms...");
+  for (const claudeDir of claudeDirs) {
+    const settingsPath = join(claudeDir, "settings.json");
+    if (isFile(settingsPath)) {
+      try {
+        const data = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        const readRule = `Read(//${INSTALL_ROOT.replace(/^\/+/, "")}/**)`;
+        const allow = (data.permissions && data.permissions.allow) || [];
+        const bashRule = `Bash(python3 ${toTildePath(join(claudeDir, "skills"))}/*)`;
+        const bashOk = allow.includes(bashRule) || allow.includes("Bash(python3 ~/.claude/skills/*)");
+        const readOk = allow.includes(readRule);
+        const overrides = data.skillOverrides || {};
+        const akiOk = overrides.akirule === "on";
+        console.log(`  Claude (${toTildePath(claudeDir)}): Read=${readOk ? "✅" : "⚠️ missing"}, Bash=${bashOk ? "✅" : "⚠️ missing"}, akirule=${akiOk ? "✅" : "⚠️ will enable"}`);
+      } catch (e) {
+        console.log(`  ❌ Error reading ${settingsPath}: ${e}`);
+      }
+    } else {
+      console.log(`  ⚠️  Claude (${toTildePath(claudeDir)}): No settings.json yet. Will be CREATED.`);
     }
-  } else {
-    console.log("  \u26a0\ufe0f  Claude Code: No settings.json yet. Will be CREATED.");
   }
 
   if (isDir(GEMINI_DIR)) {
@@ -744,13 +909,13 @@ async function inspectStatus() {
         const data = JSON.parse(readFileSync(agSettings, "utf-8"));
         const allow = (data.permissions && data.permissions.allow) || [];
         const probeRule = `command(python3 ${join(GEMINI_SKILLS_DIR, "akiflow", "scripts", "council_open.py")})`;
-        if (allow.includes(probeRule)) console.log("  \u2705 Antigravity CLI: per-script skill permissions already granted.");
-        else console.log("  \u26a0\ufe0f  Antigravity CLI: per-script skill permissions will be added.");
+        if (allow.includes(probeRule)) console.log("  ✅ Antigravity CLI: per-script skill permissions already granted.");
+        else console.log("  ⚠️  Antigravity CLI: per-script skill permissions will be added.");
       } catch (e) {
-        console.log(`  \u274c Error reading Antigravity settings: ${e}`);
+        console.log(`  ❌ Error reading Antigravity settings: ${e}`);
       }
     } else {
-      console.log("  \u26a0\ufe0f  Antigravity CLI: settings.json will be updated with skill permissions.");
+      console.log("  ⚠️  Antigravity CLI: settings.json will be updated with skill permissions.");
     }
   }
 
@@ -762,14 +927,17 @@ async function inspectStatus() {
 // print_summary (post-install)
 // ---------------------------------------------------------------------------
 
-function printSummary() {
+function printSummary(claudeDirs) {
   console.log(`\n${greenBold("=== INSTALL SUCCEEDED ===")}`);
 
   const gitHash = gitShortHash(REPO_ROOT);
   const hashSuffix = gitHash ? ` (${gitHash})` : "";
-  console.log(`\ud83d\udcc5 Time    : ${dateTimeNow()}${hashSuffix}`);
-  console.log(`\ud83d\udcc2 Payload : ${INSTALL_ROOT}`);
-  console.log(`\ud83d\udd27 Skills  : ${join(CLAUDE_DIR, "skills")}${sep}`);
+  console.log(`📅 Time    : ${dateTimeNow()}${hashSuffix}`);
+  console.log(`📁 Payload : ${INSTALL_ROOT}`);
+  console.log(`🤖 Claude targets (${claudeDirs.length}):`);
+  for (const dir of claudeDirs) {
+    console.log(`   - ${toTildePath(dir)} (skills, agents, hooks, CLAUDE.md, settings.json)`);
+  }
   console.log();
 
   console.log(cyanBold("Rules deployed:"));
@@ -791,39 +959,39 @@ function printSummary() {
 
   console.log();
   console.log(cyanBold("Skills deployed:"));
-  const claudeSkills = join(CLAUDE_DIR, "skills");
-  if (isDir(claudeSkills)) {
-    for (const name of listDir(claudeSkills).sort()) {
-      if (isDir(join(claudeSkills, name))) console.log(`  \ud83d\udd27 ${name}`);
+  const primarySkills = join(PRIMARY_CLAUDE_DIR, "skills");
+  if (isDir(primarySkills)) {
+    for (const name of listDir(primarySkills).sort()) {
+      if (isDir(join(primarySkills, name))) console.log(`  🔧 ${name}`);
     }
   }
 
   const agentsSrc = join(REPO_ROOT, "claude", "agents");
   if (isDir(agentsSrc)) {
     console.log();
-    console.log(cyanBold(`Agents deployed (${join(CLAUDE_DIR, "agents")} \u2014 your own agents there are untouched):`));
+    console.log(cyanBold(`Agents deployed (${claudeDirs.map(toTildePath).join(", ")} — your own agents there are untouched):`));
     for (const name of listDir(agentsSrc).sort()) {
-      if (name.endsWith(".md")) console.log(`  \ud83e\udde0 ${basename(name, ".md")}`);
+      if (name.endsWith(".md")) console.log(`  🧠 ${basename(name, ".md")}`);
     }
   }
 
   console.log();
   console.log(cyanBold("Other CLI skill roots synced (harmless if that CLI isn't installed):"));
-  console.log(`  \ud83e\udd16 Codex CLI : ${CODEX_SKILLS_DIR}`);
-  console.log(`  \ud83e\udd16 Kiro CLI  : ${KIRO_SKILLS_DIR}`);
-  console.log(`  \ud83e\udd16 Grok CLI  : ${GROK_SKILLS_DIR}`);
+  console.log(`  🤖 Codex CLI : ${CODEX_SKILLS_DIR}`);
+  console.log(`  🤖 Kiro CLI  : ${KIRO_SKILLS_DIR}`);
+  console.log(`  🤖 Grok CLI  : ${GROK_SKILLS_DIR}`);
 
   console.log();
   console.log(cyanBold("Permissions configured:"));
-  console.log("  \u2699\ufe0f  Claude Code     : Read(~/.aki/akidevrule/**), Bash(python3 ~/.claude/skills/*)");
+  console.log("  ⚙️  Claude Code     : Read(~/.aki/akidevrule/**), Bash(python3 <target>/skills/*)");
   if (isDir(GEMINI_DIR))
-    console.log("  \u2699\ufe0f  Antigravity     : per-script command() rules (akiflow scripts \u00d72 roots \u00d72 path renderings \u00d7the platform's python launchers), write_file(~/.aki/agent-council/), read_file(~/.aki/akidevrule/)");
+    console.log("  ⚙️  Antigravity     : per-script command() rules (akiflow scripts ×all roots ×2 path renderings ×the platform's python launchers), write_file(~/.aki/agent-council/), read_file(~/.aki/akidevrule/)");
   if (isDir(join(HOME, ".kiro")))
-    console.log("  \u2699\ufe0f  Kiro CLI        : capability:shell (python3 ~/.kiro/skills/*, ~/.claude/skills/*)");
+    console.log("  ⚙️  Kiro CLI        : capability:shell (python3 ~/.kiro/skills/*, ~/.claude*/skills/*)");
 
   console.log();
   console.log(cyanBold("Hooks deployed:"));
-  console.log("  \ud83d\udce2 aki-update-check (SessionStart, notify-only) \u2014 notifies when a new rule version is available");
+  console.log("  📢 aki-update-check (SessionStart, notify-only) — notifies when a new rule version is available");
 
   console.log(`\n${greenBold("==============================")}`);
 }
@@ -846,15 +1014,8 @@ function ask(question) {
 // Main install logic
 // ---------------------------------------------------------------------------
 
-async function runInstall() {
-  // Legacy migration: ~/.aki/claudedoc -> ~/.aki/akidevrule
-  if (isDir(LEGACY_INSTALL_ROOT) && !existsSync(INSTALL_ROOT)) {
-    mkdirSync(dirname(INSTALL_ROOT), { recursive: true });
-    renameSync(LEGACY_INSTALL_ROOT, INSTALL_ROOT);
-    console.log(`\ud83d\udce6 Migrated legacy install root: ${LEGACY_INSTALL_ROOT} \u2192 ${INSTALL_ROOT}`);
-  }
-
-  const sameCheckout = await inspectStatus();
+async function runInstall(claudeDirs) {
+  const sameCheckout = await inspectStatus(claudeDirs);
 
   // Skip the prompt only for a byte-identical overwrite (same commit, clean tree).
   if (process.stdin.isTTY && !sameCheckout) {
@@ -864,11 +1025,17 @@ async function runInstall() {
       process.exit(1);
     }
   }
+
+  // Legacy migration: ~/.aki/claudedoc -> ~/.aki/akidevrule
+  if (isDir(LEGACY_INSTALL_ROOT) && !existsSync(INSTALL_ROOT)) {
+    mkdirSync(dirname(INSTALL_ROOT), { recursive: true });
+    renameSync(LEGACY_INSTALL_ROOT, INSTALL_ROOT);
+    console.log(`📦 Migrated legacy install root: ${LEGACY_INSTALL_ROOT} → ${INSTALL_ROOT}`);
+  }
   console.log("Installing...");
 
   // --- 1. Payload -> INSTALL_ROOT ---
   mkdirSync(INSTALL_ROOT, { recursive: true });
-  mkdirSync(join(CLAUDE_DIR, "skills"), { recursive: true });
 
   const payloadSrc = join(REPO_ROOT, "payload");
   const EXCLUDED = new Set(["ref-ECC", ".DS_Store", "GEMINI.md"]);
@@ -909,65 +1076,19 @@ async function runInstall() {
     if (branch) versionLines.push(`branch=${branch}`);
   }
   writeTextLf(join(INSTALL_ROOT, ".version"), versionLines.join("\n") + "\n");
+  writeTextLf(join(INSTALL_ROOT, ".source-repo"), REPO_ROOT + "\n");
+
+  // --- 2. Claude targets (skills, agents, hooks, CLAUDE.md, settings.json) ---
+  for (const cDir of claudeDirs) {
+    installClaudeDir(cDir);
+  }
 
-  // --- 2. Skills ---
-  syncAkiSkills(join(CLAUDE_DIR, "skills"));
+  // --- 3. Other CLI skill roots ---
   syncAkiSkills(CODEX_SKILLS_DIR);
   syncAkiSkills(KIRO_SKILLS_DIR);
   syncAkiSkills(GROK_SKILLS_DIR);
 
-  // --- 3. Agents ---
-  syncAkiAgents();
-
-  // --- 4. Hooks + source-repo ---
-  const hooksDest = join(CLAUDE_DIR, "hooks");
-  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"));
-  // Remove orphaned Python hooks left by a pre-3.0 install.
-  for (const legacy of ["aki-update-check.py", "aki_version_check.py"]) {
-    const p = join(hooksDest, legacy);
-    if (existsSync(p)) rmrf(p);
-  }
-  // hooks/ is shared with the user's own hooks, so only our bytecode is removed, never the whole cache.
-  const pyCache = join(hooksDest, "__pycache__");
-  if (isDir(pyCache)) {
-    for (const n of readdirSync(pyCache)) if (n.startsWith("aki_version_check.")) rmrf(join(pyCache, n));
-    if (readdirSync(pyCache).length === 0) rmrf(pyCache);
-  }
-  writeTextLf(join(INSTALL_ROOT, ".source-repo"), REPO_ROOT + "\n");
-
-  // --- 5. CLAUDE.md ---
-  mkdirSync(CLAUDE_DIR, { recursive: true });
-  backup(join(CLAUDE_DIR, "CLAUDE.md"));
-  console.log("\ud83e\uddf9 Pruning CLAUDE.md backups (keeping the 2 most recent):");
-  pruneBackups(join(CLAUDE_DIR, "CLAUDE.md"));
-
-  const claudeMdSrc = readFileSync(join(REPO_ROOT, "claude", "CLAUDE.md"), "utf-8");
-  const propagateCmd = `node "${join(REPO_ROOT, "install.mjs")}"`;
-  const ruleSourceBlock =
-    "\n## akidevrule \u2014 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** \u2014 changes will be silently lost on the next install.\n\n` +
-    "@~/.claude/CLAUDE.local.md\n";
-  writeTextLf(join(CLAUDE_DIR, "CLAUDE.md"), claudeMdSrc + ruleSourceBlock);
-
-  // --- 6. CLAUDE.local.md (create-only) ---
-  const localMd = join(CLAUDE_DIR, "CLAUDE.local.md");
-  if (!isFile(localMd)) {
-    writeTextLf(
-      localMd,
-      "# Machine-local Claude instructions\n\n" +
-        "This file is machine-specific and never touched by akidevrule installs.\n" +
-        "Add any per-machine rules here (e.g. build constraints, IDE paths, remote flags).\n"
-    );
-    console.log(`\ud83d\udcdd Created ${localMd} (machine-local template)`);
-  }
-
-  // --- 7. GEMINI.md (only when ~/.gemini exists) ---
+  // --- 4. GEMINI.md (only when ~/.gemini exists) ---
   if (isDir(GEMINI_DIR)) {
     const geminiFile = join(GEMINI_DIR, "GEMINI.md");
     const geminiLocal = join(GEMINI_DIR, "GEMINI.local.md");
@@ -983,11 +1104,11 @@ async function runInstall() {
           "This file is machine-specific and never touched by akidevrule installs.\n" +
           "Add machine-specific paths, CLIs, and emulator commands here.\n"
       );
-      console.log(`\ud83d\udcdd Created ${geminiLocal} (machine-local template)`);
+      console.log(`📝 Created ${geminiLocal} (machine-local template)`);
     }
 
     backup(geminiFile);
-    console.log("\ud83e\uddf9 Pruning GEMINI.md backups (keeping the 2 most recent):");
+    console.log("🧹 Pruning GEMINI.md backups (keeping the 2 most recent):");
     pruneBackups(geminiFile);
 
     const d = new Date();
@@ -995,50 +1116,43 @@ async function runInstall() {
     const geminiTemplate = readFileSync(join(REPO_ROOT, "payload", "GEMINI.md"), "utf-8");
     const geminiContent = geminiTemplate.split("__VERSION__").join(geminiVersion);
 
+    const propagateCmd = `node "${join(REPO_ROOT, "install.mjs")}"`;
     const geminiSourceBlock =
-      "\n## 15. Shared rule source \u2014 edit source, not deployed copy (ABSOLUTE)\n\n" +
-      `The deployed rule corpus at \`${INSTALL_ROOT}\` is **overwritten on every install**.\n` +
+      "\n## 15. Shared rule source — edit source, not deployed copy (ABSOLUTE)\n\n" +
+      `The deployed rule corpus 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")}/\` (rules) or \`${join(REPO_ROOT, "claude")}/\` (runtime assets).\n` +
-      `2. Read \`${join(REPO_ROOT, "CLAUDE.md")}\` first \u2014 it lists which files must be updated together.\n` +
+      `2. Read \`${join(REPO_ROOT, "CLAUDE.md")}\` first — it lists which files must be updated together.\n` +
       `3. Run \`${propagateCmd}\` to propagate.\n\n` +
-      `**NEVER edit files under \`${INSTALL_ROOT}\` directly** \u2014 changes are silently lost on the next install.\n`;
+      `**NEVER edit files under \`${INSTALL_ROOT}\` directly** — changes will be silently lost on the next install.\n`;
 
     const localContent = readFileSync(geminiLocal, "utf-8");
     const fullGemini = geminiContent + geminiSourceBlock + "\n---\n\n" + localContent;
     writeTextLf(geminiFile, fullGemini);
 
-    console.log(`\ud83e\udd16 Installed ${geminiFile} (marker ${geminiMarker}${geminiVersion}])`);
+    console.log(`🤖 Installed ${geminiFile} (marker ${geminiMarker}${geminiVersion}])`);
     if (hadUnmanaged) {
-      console.log("  \u26a0\ufe0f  Your previous ~/.gemini/GEMINI.md was replaced (saved as *.akidevrule-backup-*).");
+      console.log("  ⚠️  Your previous ~/.gemini/GEMINI.md was replaced (saved as *.akidevrule-backup-*).");
       console.log(`      Move any machine-local lines from that backup into ${geminiLocal}.`);
     }
 
-    // --- 8. Antigravity rules ---
+    // --- Antigravity rules ---
     const agCount = installAgRules();
-    console.log(`\ud83e\udded Installed ${agCount} rule(s) to ${GEMINI_RULES_DIR} (read by AG, AG IDE and AGY)`);
+    console.log(`🧭 Installed ${agCount} rule(s) to ${GEMINI_RULES_DIR} (read by AG, AG IDE and AGY)`);
 
-    // --- 9. Antigravity skills ---
+    // --- Antigravity skills ---
     syncAkiSkills(GEMINI_SKILLS_DIR);
     syncAkiSkills(join(INSTALL_ROOT, "agskills"));
     updateSkillsJson();
-    console.log(`\ud83d\udca1 Deployed skills to ${GEMINI_SKILLS_DIR} & updated ~/.gemini/config/skills.json`);
-    console.log("  \u2139\ufe0f  Antigravity discovers rules and skills at startup \u2014 restart the app or start a new agy session.");
+    console.log(`💡 Deployed skills to ${GEMINI_SKILLS_DIR} & updated ~/.gemini/config/skills.json`);
+    console.log("  ℹ️  Antigravity discovers rules and skills at startup — restart the app or start a new agy session.");
   }
 
-  // --- 10. settings.json ---
-  const settingsPath = join(CLAUDE_DIR, "settings.json");
-  if (!isFile(settingsPath)) writeTextLf(settingsPath, "{}\n");
-  backup(settingsPath);
-  console.log("\ud83e\uddf9 Pruning settings.json backups (keeping the 2 most recent):");
-  pruneBackups(settingsPath);
-  mergeSettings(settingsPath, INSTALL_ROOT, CLAUDE_DIR);
-
-  // --- 11. Antigravity & Kiro permissions ---
-  mergeAntigravityPermissions();
-  mergeKiroPermissions();
+  // --- 5. Antigravity & Kiro permissions ---
+  mergeAntigravityPermissions(claudeDirs);
+  mergeKiroPermissions(claudeDirs);
 
-  printSummary();
+  printSummary(claudeDirs);
 }
 
 // ---------------------------------------------------------------------------
@@ -1048,17 +1162,20 @@ async function runInstall() {
 async function main() {
   const argv = process.argv.slice(2);
   if (argv.includes("-h") || argv.includes("--help")) {
-    console.log("akidevrule installer \u2014 deploys shared rule corpus and skills.");
+    console.log("akidevrule installer — deploys shared rule corpus and skills.");
     console.log("");
-    console.log("Usage: node install.mjs [--check]");
-    console.log("  --check   Print installed vs latest akidevrule version and exit. No install, no overwrite.");
+    console.log("Usage: node install.mjs [--check] [--claude-dir <path>]");
+    console.log("  --check              Print installed vs latest akidevrule version and exit. No install, no overwrite.");
+    console.log("  --claude-dir <path>  Explicit Claude config directory to include (also auto-detects ~/.claude* and $CLAUDE_CONFIG_DIR).");
     process.exit(0);
   }
   if (argv.includes("--check")) {
     await printVersionCheck();
     process.exit(0);
   }
-  await runInstall();
+  const claudeDirs = getClaudeDirs(argv);
+  preflightInstallSettings(claudeDirs);
+  await runInstall(claudeDirs);
 }
 
 main().catch((err) => {

package/package.json

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

package/payload/RULE-agent-behavior.md

@@ -29,7 +29,7 @@ Being called with a card means: re-read the root rule, fix **every** instance in
   - **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.
-- **Do the menial work through a worker, not personally** — bulk file reading, grep sweeps, inventory scans, log trawls. Main-thread context is the one resource a task cannot get back, and it is spent on the answer, not on the search. Read at orientation depth yourself: indexes, checklists, summaries, and the specific excerpt a decision turns on. "Doing it directly is faster" is true per-step and false per-task. How to brief and price that worker: A5
+- **Narrow and batch before crossing a process boundary.** Use the direct tools and in-shell aggregation rules above when they can return a bounded answer without flooding this context; `A5` alone decides when the remaining exploration belongs to a worker.
 
 ### A3. Communication vs task — a question is not a request
 Classify every turn before acting: is it **communication** (a question, discussion, or explanation — "why/how/can we/should we/what if", thinking aloud) or a **task** (an imperative aimed at the code/repo: add, fix, change, remove, commit)?
@@ -52,9 +52,13 @@ The reader often context-switches across many tasks and reads in a terminal; opt
 ### 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).
 
-**Default to delegating exploration.** The bar is not "is this too big for me" but "does this need *my* context to answer" — and searching, listing, and reading-to-find-out do not. Reach for a worker before reaching for a sweep of your own. Do it inline only when the answer is one file you already know, since a worker has a fixed overhead that only pays back on real work.
+**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.
 
-**Discovery goes to the current default wide-context tier available, one shot** — on Antigravity that is `agy --model gemini-3.7-flash-high --mode plan -p "<prompt>"` (prompt last; `-p` swallows the next token; owner-set default, 2026-08-15). It 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 that CLI degrades badly.
+**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 current default wide-context tier available, one shot** — on Antigravity that is `agy --model gemini-3.7-flash-high --mode plan -p "<prompt>"` (prompt last; `-p` swallows the next token; owner-set default, 2026-08-15). It 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 that CLI 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.

package/payload/RULE-release.md

@@ -1,6 +1,6 @@
 # Release & Versioning Rule
 
-<!-- Address map: release.A1-5 · release.B1-10 · release.C1-4 (⟨Aki⟩) -->
+<!-- Address map: release.A1-5 · release.B1-11 · release.C1-4 (⟨Aki⟩) -->
 
 ## A. Versioning core
 
@@ -116,7 +116,7 @@ After updating CHANGELOG and the version bump, produce the GitHub Release withou
 
 **`--generate-notes` alone is not a substitute for Title/Body above.** It derives content from merged PRs only; a repo that commits straight to trunk (no PR history) gets a near-empty body — footer line only. Pair it with `--notes-file` for real content, or, when release creation is CI-automated rather than run interactively, have the workflow itself extract the tagged version's CHANGELOG section into the notes file — the content requirement above still applies even though no one is typing the `gh release create` command by hand.
 
-### B5. Migration/infra completeness gate — a schema or infra change is not "released" until it ran
+### B5. Migration doctrine & completeness gate — a schema or infra change is not "released" until it ran
 
 A CHANGELOG or `releases.json` entry that describes a database schema change or any other infra-dependent change (migration, remote config, env var, cron/schedule registration — see [[RULE-coding]] B3) is a claim that the change is live. That claim is only true once two things both hold, not one:
 
@@ -125,6 +125,14 @@ A CHANGELOG or `releases.json` entry that describes a database schema change or
 
 Do not report a plan, task, or release/deploy as complete when a migration/infra step it depends on has not cleared **both** conditions. A written migration script plus a "Added" changelog line with the actual execution still outstanding is exactly the failure this gate exists to catch — the code shipped, the database did not, and nothing else in the release checklist would have noticed.
 
+#### Migration doctrine — MANDATORY. No project is exempt without a written declaration in its own `CLAUDE.md`.
+
+1. **DETECT by effect, never by location.** A migration is ANY change to the shape of persisted data: a `migrations/` script, an ORM auto-sync, a `CREATE`/`ALTER`/`DROP` of a table, column, index or constraint, a schema-version bump, a JSON state-file shape change, a re-keyed cache — **wherever it lives, including code that runs at application startup or inside a constructor.** Run the detector over the accumulation diff (boundary commit, B1.5) on EVERY release and paste its output or the word `empty` into the report: `git diff <boundary>..HEAD | grep -nEi 'ALTER +TABLE|CREATE +(UNIQUE +)?(TABLE|INDEX)|DROP +(TABLE|INDEX|COLUMN)|ADD +COLUMN|user_version|migrat|schema'`. A hit IS a migration until a written line proves otherwise. "It only auto-applies at startup" and "it is just an index" are NOT exemptions: the failure this doctrine exists for was an index on a new column created before that column existed, inside a constructor, invisible to a gate that only looked for migration scripts.
+2. **SEPARATE migration from application.** A migration is its own artifact — versioned, ordered, idempotent, recorded — executed as its own named deploy step. Application startup VERIFIES the schema version and reports `degraded` (B11); it NEVER mutates schema. A project that embeds migration in startup code (single-process embedded database) is a declared exception in its project `CLAUDE.md`, and this gate still treats that code as a migration in full: points 1 and 3–5 apply unchanged.
+3. **ORDER: expand → migrate → deploy code → contract.** Additive (expand) migrations run BEFORE the code that needs them restarts, so old code keeps running on the new schema; destructive (contract) steps ship in a LATER release, after nothing reads the old shape. Restarting new code onto an un-migrated schema is a VIOLATION.
+4. **REHEARSE from the PREVIOUS state, never from empty.** A test or dry-run that starts from a fresh database exercises `CREATE`, not the migration, and proves NOTHING about an upgrade. REQUIRED evidence: the migration executed against (a) a schema generated or snapshotted from the previous release, AND (b) for any data-dependent change (unique index, `NOT NULL` backfill, type change, dedupe) a COPY of real target data. State which was run and quote its output. "The tests pass" is not evidence.
+5. **POSTCONDITIONS asserted, ROLLBACK named.** After the real run, assert expected columns, indexes and row counts by query (condition 1 above), and record the backup or fix-forward path BEFORE any destructive step ([[RULE-agent-behavior]] B3). A migration with no stated rollback or fix-forward path does NOT ship.
+
 ### B6. Content discipline
 - Release note copy: no em/en dash (`—` `–`); short user-facing sentences, benefit first. See [[RULE-content-write]].
 - Keep terminology stable across versions (e.g. always "Release Notes", not mixed synonyms). See [[RULE-content-write]] semantic stability.
@@ -136,17 +144,23 @@ The last moment a mistake is still cheap: the work is done, the tree is clean, a
 
 Run in order; each step names the rule that owns it.
 
+**FAIL-CLOSED CONTRACT — this gate is NOT advisory, and a skipped step is a failed step.**
+- Every step 0–8 MUST leave a receipt line in the run's report: `S<n> PASS | FIXED | FAIL | N/A — <evidence>`. Evidence is quoted command output, a `file:line` actually read, or an observed fact — never an adjective. `N/A` REQUIRES the cited fact that makes the step inapplicable; an `N/A` with no cited fact is scored FAIL.
+- A step with NO receipt line was NOT RUN. NOT RUN means the gate FAILED. A failed gate FORBIDS commit, mint, tag, push and deploy — no exception for urgency, "hotfix", "tiny diff", or "same as the last release".
+- FORBIDDEN as evidence: "should", "presumably", "probably", "looks fine", "seems", "expected to". Each is an unverified claim and is scored `unverified` under step 7, never PASS.
+- **Self-interrogation is MANDATORY and REPORTED, not silent.** Before closing, answer in writing: (1) which step was cheapest to skip, and what did I actually do for it; (2) if this release broke production within the hour, which unchecked step caused it; (3) does the diff touch anything persisted, and did step 3 run against the PREVIOUS state; (4) what did verification exercise that exists only on production — a data path, not a version string. An unanswered question is a FAIL.
+
 0. **Leftover triage** — a tree that is not uniformly finished is classified first: finished / mid-edit / abandoned / accidental (the `/akigitcommit` step-0 taxonomy, under [[RULE-agent-behavior]] B5's read-only floor). Mid-edit vs abandoned is undecidable from the tree alone — that is an escalation (B8), never a guess.
 1. **Release state** — derive it cold from the repo per B1, never from session memory. `Drifted` blocks everything until A5's recovery has run.
 2. **Hygiene sweep — scoped to the accumulation, never the whole repo.** On the files touched since the boundary commit (B1.5): scythe `[WRAP]`/`[YAP]` lint ([[RULE-agent-behavior]] §0), dead code / redundant guards / duplication the accumulation itself introduced (`pattern.A8`; subtract-class detectors at diff scope), and doc references in touched comments still resolving ([[RULE-docs]] B3). A repo-wide subtraction or zero-trust sweep is a separately scheduled audit, never a per-release cost — diff scope is what keeps this gate affordable at many releases per day. Unlike an audit, findings here are fixed in place: this is a gate, not a report.
-3. **External-action completeness** — every change whose "done" depends on something outside the repo actually happened: migrations ran against the real target and their postconditions were checked, remote config/env vars/cron registrations are live, and each script sits in its completion location (B5, [[RULE-coding]] B3). A green build proves nothing about the database.
+3. **Migration & external-action completeness — the B5 detector runs FIRST, on EVERY release, without exception.** Paste its output (or `empty`) into the receipt. A hit obliges a written answer to each of B5 points 2–5: is it separate, is the order expand → migrate → deploy → contract, was it rehearsed from the PREVIOUS state (which one, quoted output), are postconditions and rollback stated. Startup-embedded migration code counts. Then every other change whose "done" lives outside the repo (remote config, env vars, cron registrations, cache purges) is confirmed live, and each script sits in its completion location ([[RULE-coding]] B3). A green build proves nothing about the database; a green test on an empty database proves nothing about an upgrade.
 4. **Record truthfulness** — every closed problem has its `CHANGELOG.md` entry, and no entry claims something step 3 has not cleared (B2). Web stacks additionally need `releases.json` parity (C3).
 5. **Doc sync — every record surface the accumulation touched, not only `docs/`.** Enumerate, then check each against the diff: plans whose work shipped moved to `docs/plan/done/`; `arch`/`feat` docs match what is about to ship ([[RULE-docs]] B1, B3); `README.md` wherever the accumulation changed setup, commands, layout, or a documented behavior; the project's task-note file when one exists (`.akidevsync/notes.json`, edited only through the `akidevsync-notes` skill — a note whose fix is in this accumulation is marked done with the matching CHANGELOG line, an unmatched or unverified one stays open and is named in the report); and any external standards doc the project `CLAUDE.md` binds the project to, updated in place when the accumulation changed a convention that doc owns. A surface skipped because it was not in `docs/` is the same drift finding as a stale doc.
 6. **Build & test — mirror CI.** Commands are derived, never invented: the jobs `.github/workflows/*` run on push/tag take priority; a repo with no such workflow falls back to the manifest's own scripts (`npm run typecheck`/`build`/`test`, `cargo build`/`cargo test`, equivalent). Run every one of them locally, self-authorized ([[RULE-coding]] B3 — ship/release is the moment full build+test is mandatory, not optional). A failure blocks the gate and is fixed in place, same as step 2. A CI step that cannot be reproduced locally (an other-OS matrix leg, a job needing secrets) is named explicitly and left to B10 to catch post-push. A repo with no build/test command at all says so plainly — that is a finding, not a silent pass. This step sits after 2–5 because those fix code and docs first, and the build must cover what is actually about to ship.
 7. **Verification honesty** — anything only checkable at runtime is reported as unverified rather than assumed ([[RULE-coding]] B3). "Untested but I expect it works" is a valid gate output; a silent "Done" is not.
 8. **Version decision** — mint or defer per A4/A5's materiality test. Do not mint a version to mark that a session ended.
 
-Post-push CI is B10; stack deploy verification (C5, `stack.C8`) follows a green CI.
+Post-push CI is B10; post-deploy functional verification is B11 (mandatory after every deploy or restart); stack deploy verification (C5, `stack.C8`) follows a green CI.
 
 ### B8. Autonomous full-release run — an explicit release order is the authorization
 
@@ -176,6 +190,15 @@ After any push or tag push, in any flow (not only `/akiship`): `gh run list --co
 
 **Evidence.** CI failures went unnoticed because the ritual only verified stack deploys (C5): a non-deploying repo (CLI, library, npm package) had no post-push check at all, so a red workflow could sit unnoticed indefinitely.
 
+### B11. Post-deploy verification — a version string proves the code, never the function
+
+After ANY deploy or restart, in any flow (not only `/akiship`), verify FUNCTION, not identity.
+- The check MUST exercise at least one real data path the release touched — an authenticated read that hits the changed table or route — and assert a success status AND a non-trivial payload. A `/version` or `/health` response, or a 200 from a static page, is an IDENTITY check: necessary, never sufficient.
+- A health endpoint returning a constant `ok` regardless of subsystem state is a FALSE INSTRUMENT. It MUST derive its status from the real state of every required subsystem (`degraded` plus the subsystem names when one failed to open), and until it does, a gate that trusts it scores the verification `unverified`, never PASS. Degraded runtime state MUST be visible — health, a log line carrying the underlying error text, or the UI — and never swallowed by a bare `catch`. A component whose failure must not take the service down degrades VISIBLY; it is never silent and never fatal to unrelated work.
+- Failure → execute the rollback or fix-forward path stated under B5 point 5, THEN report. "The process is up" is not Done.
+
+**Evidence.** A release passed every gate and its post-deploy check because the check read only the version endpoint and the health endpoint returned a hardcoded `ok`; the usage store had failed to open on the upgraded database and the dashboard was dead for the whole window until a person opened it.
+
 ## C. ⟨Aki⟩ Web release artifacts
 
 ### C1. Two separate channels — do not merge them

package/payload/index.md

@@ -18,7 +18,7 @@ Provides reusable rules for agent behavior, coding, content, docs, and stack-spe
 | `RULE-stack-tauri.md` | `tauri` | Contextual | public | Tauri v2 + Rust: absolute never-block-the-UI rule for any command running a subprocess/network call (`spawn_blocking`), titlebar boundary, version SSOT, IPC capability silent-fail, serde default for persisted JSON, cfg(target_os) scoping, subprocess PATH-resolution cold-start race, salient target context (ship platform) surfaced in the project CLAUDE.md, macOS TCC/Gatekeeper boundary for spawned sidecars (responsible-process attribution, FDA vs Files & Folders vs Developer Tools, sticky denials, ad-hoc signing losing grants on every rebuild, and the read-only scope limit of the whole chain) |
 | `RULE-ui-pattern.md` | `ui` | Contextual | public | Frontend enforcement of pattern-core: subtraction pass before any tier (delete/inherit/hoist — the ladder packages repetition, only this removes it), 4-tier class taxonomy with the second copy as the STOP (the ≥3 threshold is repo-wide and unobservable inside one file), inline `style=` as a runtime-only escape hatch, `<style>`-block budget measured in aggregate against the shared layer, design tokens in whichever mechanism the installed framework version uses with one theme source per project, arbitrary-value policy, atomic structure, variant API, two-way lookup-then-record pattern duty, UI audit/refactor playbook led by the inversion check |
 | `RULE-seo.md` | `seo` | Contextual | **mixed** — group C is ⟨Aki⟩ | Meta limits, schema.org matrix, robots, sitemap, OG, AI visibility, entity linking |
-| `RULE-release.md` | `release` | Contextual | **mixed** — group C is ⟨Aki⟩ | CHANGELOG.md mandatory in every project, release notes vs changelog split, GitHub Release compare-link footer, releases.json (web-only), release vs deploy boundary, cold-start version reconstruction, severity-driven bump, version minted only at the release event (`[Unreleased]` buffer, no local drift ahead of production), audit mode, pre-ship gate expanded into the full-release checklist (B7: leftover triage, diff-scoped hygiene, build & test mirroring CI as a mandatory step before verification honesty and the version decision), autonomous-run contract (B8: an explicit release order is the authorization — activation owned by akiship's own gate, this rule is never itself a trigger; asks front-loaded into one batch, three-case escalation floor and completion-intensity phrase list owned solely by B8, owner-worded criteria decided and reported rather than escalated by default; entry point `/akiship`), registry-published packages (B9: the registry version is the release, publish mechanism derived from existing convention and sibling packages, account/scope/2FA probed, OTP publish as the single hand-off, tarball verified before the irreversible publish), post-push CI watch (B10: a push or tag push is not Done until every triggered workflow is green, red fixed forward with a new commit never a history rewrite) |
+| `RULE-release.md` | `release` | Contextual | **mixed** — group C is ⟨Aki⟩ | CHANGELOG.md mandatory in every project, release notes vs changelog split, GitHub Release compare-link footer, releases.json (web-only), release vs deploy boundary, cold-start version reconstruction, severity-driven bump, version minted only at the release event (`[Unreleased]` buffer, no local drift ahead of production), audit mode, pre-ship gate expanded into the full-release checklist (B7: leftover triage, diff-scoped hygiene, build & test mirroring CI as a mandatory step before verification honesty and the version decision), autonomous-run contract (B8: an explicit release order is the authorization — activation owned by akiship's own gate, this rule is never itself a trigger; asks front-loaded into one batch, three-case escalation floor and completion-intensity phrase list owned solely by B8, owner-worded criteria decided and reported rather than escalated by default; entry point `/akiship`), registry-published packages (B9: the registry version is the release, publish mechanism derived from existing convention and sibling packages, account/scope/2FA probed, OTP publish as the single hand-off, tarball verified before the irreversible publish), post-push CI watch (B10: a push or tag push is not Done until every triggered workflow is green, red fixed forward with a new commit never a history rewrite), migration doctrine (B5: detect by effect including startup-embedded code, separate artifact, expand → migrate → deploy → contract, rehearse from the PREVIOUS state never from empty, postconditions + named rollback), fail-closed gate contract (B7: a receipt line per step or the step was NOT RUN, self-interrogation reported, forbidden evidence words), post-deploy functional verification (B11: a version string proves code not function, a constant-`ok` health endpoint is a false instrument) |
 | `RULE-db-design.md` | `db` | Contextual | public | Immutability & Event Sourcing, 1NF, Bounded Context (DDD), flat-query discipline — load when designing schema/migration/DB refactor |
 | `RULE-biz.md` | `biz` | Contextual | public | Positioning & audience (one primary audience, falsifiable USP, `docs/biz/` as SSoT, niche-first), offer & pricing (value-based, few tiers, validate before building), messaging & customer psychology (benefit-first, anxiety at decision points, no dark patterns) — load on any market-facing decision |
 | `METHOD-audit-flow.md` | `flow` | Analytical | public | Flow integrity audit method |
@@ -68,7 +68,7 @@ Some subjects legitimately live in several files: one **root rule** stating the
 | Subject | Root | Domain applications |
 |---|---|---|
 | **Naming** | `pattern.A7` — name by role, never by concrete value | `agent.C1` file names · `ui.A` design tokens · `stack.C1` ⟨Aki⟩ canonical component names · `release.A3` version/tag format · `content.A3` semantic stability (renaming an existing concept) |
-| **External-action completeness** ("done" needs the outside world to move, not just the file) | `coding.B3` — a change requiring a separate action against an external system isn't done when the file describing it is written | `release.B5` ⟨Aki⟩ CHANGELOG/release entry not truthful until a migration/infra step actually ran · `stack.C8` ⟨Aki⟩ D1 migration must run `--remote` and move to `scripts/done/`, a green build alone proves nothing about the database · `release.B10` a push or tag push is not Done until every triggered CI workflow is confirmed green |
+| **External-action completeness** ("done" needs the outside world to move, not just the file) | `coding.B3` — a change requiring a separate action against an external system isn't done when the file describing it is written | `release.B5` ⟨Aki⟩ CHANGELOG/release entry not truthful until a migration/infra step actually ran · `stack.C8` ⟨Aki⟩ D1 migration must run `--remote` and move to `scripts/done/`, a green build alone proves nothing about the database · `release.B10` a push or tag push is not Done until every triggered CI workflow is confirmed green · `release.B11` a deploy is not Done until a data path the release touched is exercised, not only the version |
 | **Audit reports, never fixes** (and the output depends on whether the baseline is stable) | `agent.B5` — an audit writes only its report; never mutates git state, never auto-classifies ambiguous work | `docs.C` docs-vs-reality, research+plan doc pair on a published baseline · `content.C2` canonical-term drift, density deletion test, i18n coverage sweeps · `release.B7` pre-ship pass/fail gate, no doc · `ui.C` class/token audit playbook · `flow` flow and state drift · `zero-trust` mechanical-first strict sweep, evidence weighted by the mechanism that produced it · `subtract` repo-wide does-this-need-to-exist sweep, terminating on two dry rounds |
 | **Sizing a control against its real threat** (severity is impact **and** who can actually reach it) | `proportion.A` — reach, capability, motive, blast radius, each labeled measured or estimated, before any guard is added, kept, or removed | `coding.C1` no defensive guards for impossible internal states · `coding.C4` the security floor this sizing never argues below · `pattern.A2` risk-weighted extraction at the 2nd occurrence for auth/money/permissions · `think.A1` one-way vs two-way door depth · `think.B5` when an edge-case is promoted above the MVP · `ux.C1` findings ranked by severity, never padded flat |
 | **Density — the deletion test** (a line exists only if deleting it loses information the reader needs) | `agent.A4` — report density: conclusion-first, no padding, no trimming of load-bearing detail | `coding.B4` code comments (naming first; comment only what code cannot say) · `docs.B3` doc prose · `content.B2` product copy · akiflow Step 4 output-hygiene floor (the enforcement tier for subagents, which inherit no router) · mechanical detection: `skills/akiflow/scripts/scythe.py` (`[WRAP]`/`[YAP]` only — `[FLUFF]` stays judgment, `agent` §0) |

package/skills/akirule/SKILL.md

@@ -71,6 +71,7 @@ Load if message or file path contains any of:
 - **Keywords (release-ritual context — these load this rule file, they never start a run; activation is owned entirely by akiship's own gate, an imperative release order):** `akiship`, `full release`, `release trọn gói`, `chạy full release`, `ship đợt này`, `ship trọn gói`
 - **Keywords (commit/push/deploy — load even without an explicit "release" word):** `commit`, `git commit`, `push`, `git push`, `deploy`, `deployment`, `git tag`, `ship it`, `commit và push`, `push lên`, `đẩy lên`, `triển khai`
 - **Keywords (registry publish — `release.B9`):** `npm publish`, `publish`, `npm`, `npx`, `registry`, `crates.io`, `cargo publish`, `PyPI`, `twine`, `2FA`, `OTP`, `lên npm`
+- **Keywords (migration & post-deploy — `release.B5`, `release.B11`):** `migration`, `migrate`, `schema change`, `ALTER TABLE`, `add column`, `db migration`, `health endpoint`, `/health`, `post-deploy`, `smoke test`, `chạy migration`, `đổi schema`
 - **Keywords (post-push CI — `release.B10`):** `CI`, `GitHub Actions`, `workflow run`, `gh run`, `CI fail`, `CI đỏ`, `build fail`, `test fail`
 - **Actions:** committing or pushing code, deploying, shipping a change that should be recorded for users or maintainers; bumping a version; checking whether finished-but-unpushed work is actually shippable (`release.B7`); running the full release ritual unattended (`release.B8`, `/akiship`); verifying CI after a push (`release.B10`)
 

package/skills/akiship/SKILL.md

@@ -7,7 +7,16 @@ description: Full release ritual end-to-end — front-loaded checks, then an una
 
 Invoke with `/akiship` or an explicit release order, only as described in § Activation gate below. Goal: replace the daily hand-typed ritual ("resolve leftovers, sync every doc, lint, fix drift, changelog, commit, release…") with one invocation that runs to completion or stops once, early, with every blocker in a single batch.
 
-**This skill sequences; it does not own content.** The checklist is `RULE-release.md` B7 and the autonomy/escalation contract is B8 — read that file first (installed at `~/.aki/akidevrule/RULE-release.md`), plus `RULE-docs.md` for the doc-sync step. If a step here ever disagrees with the rule file, the rule file wins — except the activation gate below, which this skill owns outright (`pattern.A1`) and which no rule file, keyword list, or routing table may widen.
+## CRITICAL — MANDATORY LOAD, BEFORE ANY OTHER TOOL CALL OF THE RUN (execute AND consult mode)
+
+**This skill sequences; it owns no content.** The checklist is `RULE-release.md` (B5 migration doctrine, B7 fail-closed gate, B8 autonomy contract, B10 CI, B11 post-deploy verification) and doc sync is `RULE-docs.md`. Both are installed at `~/.aki/akidevrule/`.
+
+1. `Read` `~/.aki/akidevrule/RULE-release.md` IN FULL and `~/.aki/akidevrule/RULE-docs.md` as the FIRST tool calls after this skill loads. Keyword routing, memory of an earlier session, this file's summary, and a rule that happens to be in context do NOT count as loading — only a `Read` performed in THIS run does.
+2. Emit as the first line of the run: `[RULES] agent,coding,pattern (core) + release,docs (akiship) | missing: none`. Any file that could not be read goes under `missing:` and the run STOPS there.
+3. A run that starts Phase 1 without those two `Read` calls is INVALID: every finding, commit, tag and deploy it produces is unauthorized and MUST be reported as such. Compliance is checked against the tool-call log, never against the receipt line (`agent.B2`).
+
+If a step in this file disagrees with the rule file, the rule file wins — except the activation gate below, which this skill owns outright (`pattern.A1`) and which no rule file, keyword list, or routing table may widen.
+
 
 ## Activation gate — two conditions, both required, checked before anything else
 
@@ -36,7 +45,7 @@ Consult is the default whenever both readings are available. A withheld executio
 Run B7 steps 2–7 in order, fixing findings as they surface (this is a gate, not an audit — no findings doc):
 
 - **Hygiene, diff scope only**: `python3 ~/.claude/skills/akiflow/scripts/scythe.py <files changed since boundary>` for `[WRAP]`/`[YAP]`; dead code / redundant guards / duplication the accumulation introduced (`pattern.A8`); doc refs in touched comments still resolve (`docs.B3`). Never widen to the whole repo.
-- External-action completeness — a pending migration qualifying under `stack.C8`'s execution-ownership clause (additive, idempotent, backup path available) is run here, not deferred; record truthfulness (CHANGELOG + `releases.json` parity where it exists), doc sync over every record surface B7 step 5 enumerates (plans → `done/`, `arch`/`feat` stamps per `docs.A4`, `README.md`, the task-note file via `akidevsync-notes`, any standards doc the project `CLAUDE.md` binds to).
+- **Migration & external-action completeness — FIRST gate step, every release.** Run the `release.B5` detector over the accumulation diff and paste its output. A hit (startup-embedded migration code included) obliges written answers to B5 points 2–5, including a rehearsal from the PREVIOUS state; a pending migration qualifying under `stack.C8`'s execution-ownership clause is run here, not deferred. Then record truthfulness (CHANGELOG + `releases.json` parity where it exists) and doc sync over every record surface B7 step 5 enumerates (plans → `done/`, `arch`/`feat` stamps per `docs.A4`, `README.md`, the task-note file via `akidevsync-notes`, any standards doc the project `CLAUDE.md` binds).
 - **Build & test — mirror CI (B7 step 6)**: derive commands from `.github/workflows/*` first, else the manifest's own scripts; run them all locally; a failure blocks and is fixed in place, same as the hygiene step above; a CI-only leg (other-OS matrix, secrets) is named and left to `release.B10`.
 - Verification honesty — anything else runtime-only, or a migration that does not qualify above, is carried to the final report as **unverified**, never silently assumed (`coding.B3`).
 
@@ -45,14 +54,17 @@ Run B7 steps 2–7 in order, fixing findings as they surface (this is a gate, no
 1. Commit in logical groups per `/akigitcommit` (domain-grouped mode; anti-stage-loss rules apply in full). B8 pre-answers its confirmation step — "commit luôn" semantics.
 2. Version decision per `release.A4`/`A5`: mint exactly once at the highest accumulated severity, or defer on the materiality test. Deferring is a normal outcome, not a failure.
 3. Artifacts per the repo's own convention: bare tag only if the repo already tags (`release.A3` B8 exception); GitHub Release per `release.B4`; `releases.json` sync check per `release.C4`; registry publish per `release.B9` — tarball verified first, and an OTP-gated publish is the report's single hand-off with its `npm view` check.
-4. **Push / deploy only if B8's push/deploy authorization holds for this invocation (named explicitly, or completion-intensity phrasing per `release.B8`).** Otherwise the run stays local-only. After any push, watch CI per `release.B10` — always, regardless of stack. If the stack additionally deploys on push, run live deploy verification per `release.C5` once CI is green.
+4. **Push / deploy only if B8's push/deploy authorization holds for this invocation (named explicitly, or completion-intensity phrasing per `release.B8`).** Otherwise the run stays local-only. After any push, watch CI per `release.B10` — always, regardless of stack. If the stack additionally deploys on push, run live deploy verification per `release.C5` once CI is green. After ANY deploy or restart, `release.B11` is mandatory: verify a data path the release touched, not only the version.
 
 ## Report
 
-One dense summary (`agent.A4`): state derived → findings fixed (counts per gate step) → commits made → version minted or deferred with the reason → artifacts created → CI results (`release.B10`) → any owner-worded criteria self-decided this run, as an `agent.A3` decision block (`Decided: X · because Y · rejected Z (why) · reopen if W`) → anything left **unverified**, each with the exact command that would settle it.
+**The FIRST block is the checklist receipt, and it is mandatory:** the `release.B7` lines `S0`–`S8` (`PASS | FIXED | FAIL | N/A — evidence`), the B5 detector output, and the four written self-interrogation answers. A report without them declares the run INCOMPLETE and says which steps were NOT RUN; an unreported step is a failed step (`release.B7` fail-closed contract), never an implicit pass.
+
+Then one dense summary (`agent.A4`): state derived → findings fixed (counts per gate step) → commits made → version minted or deferred with the reason → artifacts created → CI results (`release.B10`) → any owner-worded criteria self-decided this run, as an `agent.A3` decision block (`Decided: X · because Y · rejected Z (why) · reopen if W`) → anything left **unverified**, each with the exact command that would settle it.
 
 ## Boundaries
 
+- Never write `PASS` on a gate step without quoted evidence (`release.B7` fail-closed contract). "Should", "presumably", "looks fine" score `unverified`.
 - Never run a phase above on a turn that failed either activation condition — answer in consult mode instead, and never treat your own consult answer as the go-ahead for a later turn.
 - The B8 escalation floor is the only reason to stop mid-run; everything else is self-answered from repo, docs, and rules.
 - Never push, deploy, or push tags without B8's push/deploy authorization (`release.B8`).