@akinet/akidevrule 3.4.0 → 3.6.0

package/skills/akirule/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: akirule
-description: Aki's contextual rule router — route EVERY task turn before acting, by what the task means (the domain it touches and the kind of act — write, decide, audit, ship), with listed signals as evidence, never as the test. Domains: docs and any .md, UI copy and i18n, frontend components and CSS, SEO, commit/push/deploy/release/CI, database schema and migrations, Nuxt/Cloudflare, Tauri/Rust, pricing and positioning, UX, guards and risk sizing, flow bugs, audits and minimization, conformance to a reference, and any decision or critique. Loads each contextual RULE/METHOD file whose domain the task touches; full corpus on an explicit load-everything request. Core rules are not routed here — the harness embeds them via CLAUDE.md.
+description: Aki's contextual rule router — route EVERY task turn before acting, by what the task means (the domain it touches and the kind of act — write, decide, audit, ship), with listed signals as evidence, never as the test. Domains: code quality and structure (any code file), docs and any .md, UI copy and i18n, frontend components and CSS, SEO, commit/push/deploy/release/CI, database schema and migrations, Nuxt/Cloudflare, Tauri/Rust, pricing and positioning, UX, guards and risk sizing, flow bugs, audits and minimization, conformance to a reference, and any decision or critique. Loads each contextual RULE/METHOD file whose domain the task touches; full corpus on an explicit load-everything request. Core rules are not routed here — the harness embeds them via CLAUDE.md.
 user-invocable: false
 ---
 
@@ -11,13 +11,13 @@ user-invocable: false
 - **Claude Code:** this file is `@`-imported by `~/.claude/CLAUDE.md`, so it is in context every session without a model decision. Do not invoke the skill as well — the routing below is already loaded.
 - **Antigravity (IDE and `agy`):** routing is native — every rule is installed as `akirule-<topic>.md` (`agent` `always_on`, the rest by descriptions the installer generates from the routes below), so do not invoke this skill there.
 - **Other harnesses (Codex, Kiro, Grok):** it is a skill; invoke it before acting on any task turn.
-- **Not routed here:** `index.md`, `RULE-agent-behavior.md`, `RULE-coding.md`, `RULE-pattern-core.md` — core, harness-embedded, never `Read` again and never listed as `(router)`.
-- What stays best-effort is the second hop: reading a routed file is still the model's `Read`. Nothing below is optional because of that — it is the reason the receipt exists.
+- **Not routed here:** `RULE-agent-behavior.md` (`agent`) — core, harness-embedded, never `Read` again and never listed as `(router)`.
+- **The second hop — reading a routed file — is the model's `Read`, and on Claude Code it is enforced for every route with an artifact signature:** the `aki-route-guard` PreToolUse hook denies the first Edit/Write of each artifact type in a session (code file → `coding`+`pattern`, `.md` → `docs`, `CHANGELOG.md` → `release`, `.vue`/`.css` → `ui`, Nuxt project → `stack`, `.rs` → `tauri`, `.sql` → `db`, `locales/` → `content`) until those files have been read in this transcript; the deny reason names them — read them in full, update the receipt, retry the edit. Routes with no artifact signature (`think`, `proportion`, `biz`, `ux`, the audits) rely on this table alone, so nothing below is optional — it is the reason the receipt exists.
 
 ## How to route — meaning first, signals as evidence
 
 1. **Every task turn, before acting**, name the task in two terms: the **domains** it touches (the artifact and its subject) and the **act** (create/change, evaluate/decide, audit/verify, ship). Route on that classification in whatever language or phrasing it arrived. A signal is evidence of a domain, never the test: a request that names no listed signal still routes, a synonym or paraphrase of one counts as the signal itself, and a word used in passing does not.
-2. **Load every file whose domain the task touches** — several at once is normal. **When in doubt, load:** a false positive costs a few tokens, a false negative ships wrong work.
+2. **Load every file whose domain the task touches** — several at once is normal. **When in doubt about the domain, load:** a false positive costs a few tokens, a false negative ships wrong work. **A lookup routes nothing:** a turn that only reads, counts, locates or explains what exists (how big is the source, where is X handled, what does this function do) produces no artifact and passes no judgment, so no rule's act is performed and no file is loaded — the tiering exists for exactly these turns. The rule loads the moment the turn edits, reviews or decides; on Claude Code an under-route is caught by the gate at the first edit. This precedes rules 3 and 5: an artifact type or a project binding is evidence for a task turn, and a lookup is not one.
 3. **The artifact type alone is sufficient evidence** — the route applies whether or not the project has the matching folder or maturity.
 4. **Skip a file already loaded this conversation.**
 5. **A project binding is a standing signal:** when the project's own `CLAUDE.md`/docs bind a stack, a reference implementation, or a domain, its route is ON for every task in that project without waiting for the message to mention it.
@@ -26,24 +26,28 @@ user-invocable: false
 
 All files live in `~/.aki/akidevrule/`.
 
-| File | Load when the task … | Signals — each stands for a concept; any synonym, in any language, counts the same (EN · VI) |
+| File · topic | Load when the task … | Signals — each stands for a concept; any synonym, in any language, counts the same (EN · VI) |
 |---|---|---|
-| `RULE-docs.md` | creates, edits, moves or completes any Markdown, doc, plan, instruction file (`CLAUDE.md`, `SKILL.md`, `README`, `CHANGELOG`), or checks docs against the code | any `.md`, `docs/**`, `SKILL.md`; docs, plan, README, diagram, mermaid, architecture, drift, stale/outdated docs · tài liệu, sơ đồ, kiến trúc, lệch, lỗi thời, rà soát tài liệu |
-| `RULE-content-write.md` | writes, renames or audits text an end user reads — UI copy, messages, labels, i18n strings, page metadata copy | button/label/heading, error message, tooltip, empty state, tone, i18n, locale, translation, `locales/**`, renaming a user-facing term · nội dung giao diện, nhãn, thông báo lỗi, bản dịch |
-| `RULE-stack-akiNuxtCf.md` | works in a Nuxt / Vue / Cloudflare Pages-Workers project — ON for the whole project when its binding names that stack | `.vue`, `nuxt.config`, `wrangler.toml`, Nuxt, Vue, Cloudflare Workers/Pages, D1, KV, Nitro, composable, middleware, `useFetch`, breadcrumb, layout width |
-| `RULE-stack-tauri.md` | works in a Tauri / Rust desktop project — ON for the whole project | `.rs`, `src-tauri/`, `tauri.conf.json`, `Cargo.toml`, `#[tauri::command]`, IPC, `spawn_blocking`, freeze, hang, blocking UI, settings breaking after an upgrade · treo app, đứng app, đơ, khựng |
-| `RULE-ui-pattern.md` | builds, styles, minimizes or audits frontend components, classes, tokens or style blocks | `.vue`/`.css`/`.scss`/`.tsx`, Tailwind, class, style block, inline style, design token, variant, `@apply`, `@theme`, arbitrary value, duplicate/bloated CSS, looks inconsistent · dọn CSS, class trùng, tối giản CSS, nhiều CSS quá |
-| `RULE-seo.md` | shapes how pages are found or represented — metadata, structured data, sitemap/robots, canonical/hreflang, search or AI visibility, entity identity | SEO, meta title/description, OG image, JSON-LD, schema.org, sitemap, robots, canonical, hreflang, trailing slash, AI visibility, not indexed · không lên Google |
-| `RULE-release.md` | records, versions, commits, pushes, tags, publishes, deploys or migrates; watches CI or verifies a deploy; or asks whether finished work is shippable | commit, push, deploy, tag, release, release notes, `CHANGELOG`, version, semver, bump, publish, npm/registry, 2FA/OTP, CI, GitHub Actions, migration, post-deploy, health check, "is it done / ready to ship?" · phát hành, phiên bản, nâng version, đẩy lên, triển khai, xong chưa, CI đỏ |
-| `RULE-db-design.md` | designs or changes the shape of stored data — schema, migration, query structure, data refactor | `.sql`, `migrations/`, schema, table, column, index, D1, SQL, ERD, event sourcing, normalization, keeping history of a value, choosing a database · thiết kế DB, đổi schema, thêm cột |
-| `RULE-biz.md` | makes a market-facing decision — audience, positioning, pricing, offer, sales/landing copy, `docs/biz/` | pricing, plan/tier, subscription, monetization, revenue, positioning, USP, target audience, customer, market, conversion, landing page, `docs/biz/` · định giá, gói, khách hàng, thị trường, định vị, doanh thu |
-| `METHOD-audit-flow.md` | refactors or debugs across a chain of steps or files, or meets guards/fallbacks accumulating around one path, async/state/timing trouble | refactor, restructure, simplify, fragile, flaky, race condition, timing, state machine, async chain, nested conditionals, repeated guards, patchwork, a guard or fallback for a state the docs rule out, a fix that keeps not holding · luồng xử lý, điều kiện lồng nhau, tái cấu trúc, chắp vá, hiển nhiên, native flow, lúc được lúc không |
-| `METHOD-deep-think.md` | evaluates, decides, critiques or discusses rather than only executes — approach choice, tradeoff, scope, value, strategy, a review of an idea/plan/rule | should we, is it worth it, which option, tradeoff, scope, first principles, critique, pre-mortem, edge case, side effect, one-way door, stuck after repeated failures, the owner hands over the decision, conflicting instructions, ambiguous wording · có nên, có đáng, đánh giá, phản biện, bế tắc, thử lại vẫn lỗi, tự chốt, mâu thuẫn |
-| `METHOD-ux-psych.md` | judges an interface or flow by how users will behave | UX, usability, onboarding, user flow, friction, cognitive load, drop-off, conversion, no feedback after an action, dead end, dark pattern · khó dùng, rối, trải nghiệm người dùng, bỏ ngang |
-| `METHOD-proportionality.md` | adds, keeps, sizes or removes a guard, limit, validation or permission, or accepts a risk deliberately | rate limit, quota, throttle, abuse, spam, bot, bypass, tamper, client-side check, hardening, threat model, over-engineering, overkill · chặn, giới hạn, lạm dụng, phòng thủ, vẽ vời, rủi ro, mấy ai làm được |
-| `METHOD-audit-zero-trust.md` | demands an uncompromising, proof-driven sweep of a project or of a change plus everything that reads it | zero-trust audit, strict audit, sweep the whole project, miss nothing, prove it with tool output · audit khắt khe, rà soát toàn bộ, quét tuyệt đối, chứng minh sạch |
-| `METHOD-audit-subtraction.md` | asks to minimize, strip or clean out what no longer needs to exist | dead code, unused, unreferenced, bloat, redundant guard or fallback, comment restating a known fact, strip down, lean as possible, heavy cleanup · code chết, code thừa, hiển nhiên, tối giản tối đa, dọn sạch repo, tinh gọn |
-| `METHOD-audit-frozen-reference.md` | judges conformance to a concrete reference implementation (another repo, a pinned version, a specific file) at any strictness | frozen/pinned reference, canonical implementation, reference project, template repo, byte-identical, structurally identical, drifted from the original · đối chiếu, giống hệt, y hệt, lệch chuẩn, khớp chuẩn, so với dự án gốc |
+| `RULE-coding.md` · `coding` | creates or changes code, config, a script, a query, or judges how code is written or verified — a review, a bug diagnosis, "is it done?"; ON for every code edit, OFF for a lookup that only reads, counts or explains code | any code file (`.ts` `.js` `.vue` `.rs` `.py` `.go` `.sh` `.sql` `.css` …), function, module, bug fix, comment, error handling, verification, test, build, "is it done / verified?" · viết code, sửa code, sửa lỗi, kiểm tra, xong chưa |
+| `RULE-pattern-core.md` · `pattern` | designs, extracts, splits, abstracts, guards, names or reviews structure — every turn `coding` is ON for, plus a design discussion before an edit exists; never a lookup | duplicate, abstraction, helper, shared/base module, extract, split, responsibility, boundary, repeated guard or fallback, naming, a value written twice, draft vs commit, live preview writing through · trùng lặp, tách hàm, gom chung, đặt tên, cấu trúc, chắp vá, xem trước mà đã ghi |
+| `RULE-docs.md` · `docs` | creates, edits, moves or completes any Markdown, doc, plan, instruction file (`CLAUDE.md`, `SKILL.md`, `README`, `CHANGELOG`), or checks docs against the code | any `.md`, `docs/**`, `SKILL.md`; docs, plan, README, diagram, mermaid, architecture, drift, stale/outdated docs · tài liệu, sơ đồ, kiến trúc, lệch, lỗi thời, rà soát tài liệu |
+| `RULE-content-write.md` · `content` | writes, renames, translates or audits text an end user reads — UI copy, messages, labels, i18n strings, page metadata copy, articles and posts | button/label/heading, error message, tooltip, empty state, tone, i18n, locale, translation, `locales/**`, renaming a user-facing term, article, blog/news post, announcement, content data file (`posts.ts`, `content/**`) · nội dung giao diện, nhãn, thông báo lỗi, bản dịch, bài viết, tin tức, bài đăng |
+| `RULE-stack-akiNuxtCf.md` · `stack` | works in a Nuxt / Vue / Cloudflare Pages-Workers project — ON for the whole project when its binding names that stack | `.vue`, `nuxt.config`, `wrangler.toml`, Nuxt, Vue, Cloudflare Workers/Pages, D1, KV, Nitro, composable, middleware, `useFetch`, breadcrumb, layout width |
+| `RULE-stack-tauri.md` · `tauri` | works in a Tauri / Rust desktop project — ON for the whole project | `.rs`, `src-tauri/`, `tauri.conf.json`, `Cargo.toml`, `#[tauri::command]`, IPC, `spawn_blocking`, freeze, hang, blocking UI, settings breaking after an upgrade · treo app, đứng app, đơ, khựng |
+| `RULE-ui-pattern.md` · `ui` | builds, styles, minimizes or audits frontend components, classes, tokens or style blocks, or implements a pointer/keyboard gesture | `.vue`/`.css`/`.scss`/`.tsx`, Tailwind, class, style block, inline style, design token, variant, `@apply`, `@theme`, arbitrary value, duplicate/bloated CSS, looks inconsistent, drag and drop, reorder, resize, slider, live preview then commit · dọn CSS, class trùng, tối giản CSS, nhiều CSS quá, kéo thả, sắp xếp lại, xem trước |
+| `RULE-seo.md` · `seo` | shapes how pages are found or represented — metadata, structured data, sitemap/robots, canonical/hreflang, search or AI visibility, entity identity | SEO, meta title/description, OG image, JSON-LD, schema.org, sitemap, robots, canonical, hreflang, trailing slash, absolute vs relative URL, image path, AI visibility, not indexed · không lên Google, link ảnh |
+| `RULE-release.md` · `release` | records, versions, commits, pushes, tags, publishes, deploys or migrates; watches CI or verifies a deploy; or asks whether finished work is shippable | commit, push, deploy, tag, release, release notes, `CHANGELOG`, version, semver, bump, publish, npm/registry, 2FA/OTP, CI, GitHub Actions, migration, post-deploy, health check, "is it done / ready to ship?" · phát hành, phiên bản, nâng version, đẩy lên, triển khai, xong chưa, CI đỏ |
+| `RULE-db-design.md` · `db` | designs or changes the shape of stored data — schema, migration, query structure, data refactor | `.sql`, `migrations/`, schema, table, column, index, D1, SQL, ERD, event sourcing, normalization, keeping history of a value, choosing a database · thiết kế DB, đổi schema, thêm cột |
+| `RULE-biz.md` · `biz` | makes a market-facing decision — audience, positioning, pricing, offer, sales/landing copy, `docs/biz/` | pricing, plan/tier, subscription, monetization, revenue, positioning, USP, target audience, customer, market, conversion, landing page, `docs/biz/` · định giá, gói, khách hàng, thị trường, định vị, doanh thu |
+| `METHOD-audit-flow.md` · `flow` | refactors or debugs across a chain of steps or files, or meets guards/fallbacks accumulating around one path, async/state/timing trouble | refactor, restructure, simplify, fragile, flaky, race condition, timing, state machine, async chain, nested conditionals, repeated guards, patchwork, a guard or fallback for a state the docs rule out, a fix that keeps not holding · luồng xử lý, điều kiện lồng nhau, tái cấu trúc, chắp vá, hiển nhiên, native flow, lúc được lúc không |
+| `METHOD-deep-think.md` · `think` | evaluates, decides, critiques or discusses rather than only executes — approach choice, tradeoff, scope, value, strategy, a review of an idea/plan/rule | should we, is it worth it, which option, tradeoff, scope, first principles, critique, pre-mortem, edge case, side effect, one-way door, stuck after repeated failures, the owner hands over the decision, conflicting instructions, ambiguous wording · có nên, có đáng, đánh giá, phản biện, bế tắc, thử lại vẫn lỗi, tự chốt, mâu thuẫn |
+| `METHOD-ux-psych.md` · `ux` | judges an interface or flow by how users will behave | UX, usability, onboarding, user flow, friction, cognitive load, drop-off, conversion, no feedback after an action, dead end, dark pattern · khó dùng, rối, trải nghiệm người dùng, bỏ ngang |
+| `METHOD-proportionality.md` · `proportion` | adds, keeps, sizes or removes a guard, limit, validation or permission, or accepts a risk deliberately | rate limit, quota, throttle, abuse, spam, bot, bypass, tamper, client-side check, hardening, threat model, over-engineering, overkill · chặn, giới hạn, lạm dụng, phòng thủ, vẽ vời, rủi ro, mấy ai làm được |
+| `METHOD-audit-zero-trust.md` · `zero-trust` | demands an uncompromising, proof-driven sweep of a project or of a change plus everything that reads it | zero-trust audit, strict audit, sweep the whole project, miss nothing, prove it with tool output · audit khắt khe, rà soát toàn bộ, quét tuyệt đối, chứng minh sạch |
+| `METHOD-audit-subtraction.md` · `subtract` | asks to minimize, strip or clean out what no longer needs to exist | dead code, unused, unreferenced, bloat, redundant guard or fallback, comment restating a known fact, strip down, lean as possible, heavy cleanup · code chết, code thừa, hiển nhiên, tối giản tối đa, dọn sạch repo, tinh gọn |
+| `METHOD-audit-frozen-reference.md` · `frozen-ref` | judges conformance to a concrete reference implementation (another repo, a pinned version, a specific file) at any strictness | frozen/pinned reference, canonical implementation, reference project, template repo, byte-identical, structurally identical, drifted from the original · đối chiếu, giống hệt, y hệt, lệch chuẩn, khớp chuẩn, so với dự án gốc |
+
+**Publishable writing** — a task that writes, rewrites or translates an article, news or blog post, announcement or knowledge entry, in any wording, including "turn this release/finding into a post": invoke the `aki-article-writer` skill (the procedure) and load `content` and `seo` (the rules).
 
 **Sequential full audit** — the task asks to check a codebase thoroughly across every standard, one after another: load `zero-trust`, `flow`, `subtract`, `docs`, `content`, plus `ui` for a frontend, and run the passes in this order, each read-only: detectors (`zero-trust.B`) → structure (`pattern` laws, `flow`) → subtraction (`subtract`) → docs drift both directions (`docs.C`) → content (`content.C2`). One report, severity-ranked; fixes are a separate run (`agent.B5`).
 
@@ -58,13 +62,13 @@ The owner asks, in any wording, to load the whole corpus: `ls ~/.aki/akidevrule/
 One line at the start of the response, reporting the **whole rule context**:
 
 ```
-[RULES] agent,coding,pattern (core) + docs,ui (router)
+[RULES] agent (core) + coding,pattern,docs (router)
 ```
 
 | Element | Rule |
 |---|---|
-| Names | topic addresses from the `index.md` manifest Topic column — no new vocabulary |
-| `(core)` | the three core rule files, always listed: their presence is otherwise unobservable |
+| Names | the topic beside each file in the Routes table, `agent` for the core file — no new vocabulary. An item inside a file is addressed `topic.A1`: group letter, item number (`coding.B2`) |
+| `(core)` | the `@`-imported rule file, always listed (`agent`): its presence is otherwise unobservable |
 | `(router)` | files this router loaded; full load writes `(router:full)` |
 | `(brief)` | a worker/subagent's files named by its spawning prompt and actually read — it inherits no router, and emits the line first in its single round (`agent.A5`) |
 

package/skills/akiship/SKILL.md

@@ -12,7 +12,7 @@ Invoke with `/akiship` or an explicit release order, only as described in § Act
 **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)`. If either file could not be read, say so and the run STOPS there.
+2. Emit as the first line of the run: `[RULES] agent (core) + release,docs (akiship)`. If either file could not be read, say so 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.
@@ -45,6 +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.
+- **Record shape (B7 step 4)**: `python3 ~/.claude/skills/akiflow/scripts/release_lint.py --latest .` — verdict tags fixed in place; each `[HILITE]` line gets a written answer in the receipt (`release.C2`).
 - **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`).
@@ -62,6 +63,8 @@ Run B7 steps 2–7 in order, fixing findings as they surface (this is a gate, no
 
 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.
 
+**The LAST block is the release copy, every run, in `release.B6`'s shape** — Headline, Short, Full, and the announce verdict — quoting the `releases.json` entry and GitHub Release body the run already wrote rather than composing a third text; a deferred version prints `deferred — no copy`. It is the owner's paste-ready text for whatever channel they announce on (a post, a notification, a store listing); the block never names a channel the project's own records do not.
+
 ## Boundaries
 
 - Never write `PASS` on a gate step without quoted evidence (`release.B7` fail-closed contract). "Should", "presumably", "looks fine" score `unverified`.

package/payload/index.md

@@ -1,95 +0,0 @@
-# Aki-RULE
-
-Shared source-of-truth rules for Aki projects.
-
-## Purpose
-Provides reusable rules for agent behavior, coding, content, docs, and stack-specific work. Project `CLAUDE.md` files bind these shared rules to a specific project.
-
-## File manifest
-
-| File | Topic | Tier | Type | Purpose |
-|------|-------|------|------|---------|
-| `RULE-agent-behavior.md` | `agent` | Core — `@` import in `~/.claude/CLAUDE.md` | public | Core: full text already in context every turn — read it directly, not this summary |
-| `RULE-coding.md` | `coding` | Core — `@` import in `~/.claude/CLAUDE.md` | public | Core: full text already in context every turn — read it directly, not this summary |
-| `RULE-pattern-core.md` | `pattern` | Core — `@` import in `~/.claude/CLAUDE.md` | public | Core: full text already in context every turn — read it directly, not this summary |
-| `RULE-docs.md` | `docs` | Contextual | public | Docs structure (incl. mandatory `docs/biz/` backbone), `updated <date> <version>` anchor stamp on every `arch|biz|feat` doc, the auto-loaded instruction file's five-test admission bar (`A5`: nameable harm, majority-of-requests reach, not derivable, not a restatement, facts not behavior), plan lifecycle, research doc schema (event record: start time/purpose/strategy/checklist/result+verification/decision+cross-refs; frozen body, dated `## Amendments` for errata, successor doc only when the Decision changes), doc-sync behavior, drift audit (when it runs vs the two situations it does not, research+plan doc pair, comparison checklist, wrong/stale/incomplete/cosmetic severity) |
-| `RULE-content-write.md` | `content` | Contextual | public | UI copy, semantic stability, writing style (density enforced by deletion test), i18n, content audit (`content.C2` — canonical-term drift, density deletion test, i18n coverage, severity-classified per `docs.C4`) |
-| `RULE-stack-akiNuxtCf.md` | `stack` | Contextual | **mixed** — group C is ⟨Aki⟩ | Nuxt/Vue/Cloudflare Pages/Workers, Tailwind, i18n, canonical component names, state (useState-first), build & TypeScript, admin layout isolation, dev workflow scripts (killport/D1), layout chrome (breadcrumb/scroll-to-top), layout width (single source of truth in the layout, pages/apps never redeclare max-w), deploy verification after push |
-| `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 definition 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 |
-| `METHOD-deep-think.md` | `think` | Analytical | public | Deep-think brain: goal excavation, first principles, critique, conditional techbiz lens; passive via akirule, active via /akithink, triggered self-run via `agent.A3` |
-| `METHOD-ux-psych.md` | `ux` | Analytical | public | UX psychology audit: cognitive-load/recognition/feedback/defaults/motor-cost/mental-model lenses, persona walkthrough protocol (first-run, friction ledger, failure paths, state completeness), severity-weighted output routed through the design system |
-| `METHOD-audit-zero-trust.md` | `zero-trust` | Analytical | public | Strict mechanical-first audit: scope locked by command (project-wide or change-plus-callers), detectors run before any opinion, findings split into CERTAIN (exact machine match — a verdict) vs SUGGESTED (pattern/naming — a candidate judgment must settle), signature propagation across the locked scope, short findings-only report. Read-only like every audit |
-| `METHOD-proportionality.md` | `proportion` | Analytical | public | Sizing a defense against its real threat: four measures before any verdict (reach against the `docs/biz/` audience, capability ladder, motive, blast radius by recoverability), every number labeled measured or estimated; asymmetry law (irreversibility outranks frequency), the `coding.C4`/`biz.C3` floor that is never sizeable, the cheapest-sufficient-control ladder (impossible by shape → one trust boundary → detect → accept-and-record) with client-side limits classified as UX and never enforcement; verdict record carries a reopen trigger. Seated in akiflow as `risk-sizing` |
-| `METHOD-audit-subtraction.md` | `subtract` | Analytical | public | Repo-wide "does this need to exist" sweep: inherits zero-trust's scope-lock, detector-first order, CERTAIN/SUGGESTED classes and signature propagation, changes only the question. Loop-until-dry termination (two empty rounds) because no detector returns "minimal", nine domain passes each delegating detectors to the rule that owns them, subtraction severity classes including the mandatory *load-bearing but ugly* class, Chesterton's Fence as the brake before any CERTAIN removal. Read-only; bulk sweeps route to workers, judgment does not |
-| `METHOD-audit-frozen-reference.md` | `frozen-ref` | Analytical | public | Compliance audit for a clause that names a concrete external artifact as the canonical shape to match (a pinned version, a byte-identical component, a frozen page layout) — never judged from memory of the rule's prose. Resolve the reference to an exact path before judging (§A); when more than one reference implementation exists, read at least two, since a single reference can itself have drifted from the written rule; a comparison table is built one literal unit per row (a function name, a config key, a flow step) with `path:line` on both sides and a verdict of MATCH/RENAMED/MISSING/EXTRA/STRUCTURAL-DIFF — never softened to "acceptable variance" inside the audit (§B); standard-vs-practice gaps (the rule and its own reference disagree) are reported separately from target defects (§C). Inherits zero-trust's evidence discipline and read-only floor |
-
-Five files load mechanically, not by routing: this `index.md`, `RULE-agent-behavior.md`, `RULE-coding.md`, `RULE-pattern-core.md` and the router `~/.claude/skills/akirule/SKILL.md` are `@`-imported by `~/.claude/CLAUDE.md`, which the harness reads at session start. Every other file is routed by meaning — the domain a task touches, with concept signals as evidence, never as the test — and enters context when the model `Read`s it on a route match.
-
-The two rule files were promoted out of the router because "default ON" was a description of intent, not a mechanism: a router that runs only when the model chooses to invoke it cannot guarantee anything, and the rules the owner had to re-state most often (`coding.B4` comment budget, `pattern.A2` Rule of Three, `pattern.A8` fix-at-the-root) turned out to be missing from the context rather than present and ignored. A rule that must hold unconditionally belongs in an `@` import. The router followed for the same reason: as a skill it went uninvoked until the owner asked by name, so the routing itself is now imported and only the second hop — the `Read` of a routed file — stays model-dependent. The cost — both files in every session, including sessions that touch no code — is the price of that guarantee and was accepted knowingly.
-
-## Addressing scheme — `topic.A1`
-
-Every file is internally organized into groups **A/B/C** (a topic's broad themes) and numbered items **1/2/3…** within each group — e.g. `coding.B2` (Changing existing code), `stack.C1` (Canonical component names). `topic` is the manifest's Topic column above — usually the filename with its `RULE-`/`METHOD-` prefix dropped; the audit methods keep their short topics (`flow`, `zero-trust`, `subtract`, `frozen-ref`). This is purely a recall/reference convention — it does not change routing (still governed by `akirule/SKILL.md`) and does not rename any file.
-
-**`⟨Aki⟩`** marks a group (always the last group in its file) that is specific to Aki's own AkiNuxtCf ecosystem rather than universal — currently `seo.C`, `release.C`, `stack.C`. These groups stay in this public repo (auto-load is more useful to Aki, the heaviest user, than a clean public/ private split), but are logically separable if a stripped public export is ever needed. Everything outside a `⟨Aki⟩` group is universal and applies to any project on the matching stack.
-
-| Topic | Groups |
-|---|---|
-| `agent` | §0 Penalty cards · A Communication · B Scope & decision discipline · C Files & memory |
-| `coding` | A Philosophy & source of truth · B Quality, changing code & who verifies · C Runtime safety |
-| `pattern` | A The 8 laws · B Decomposition & the forest pass · C Closure |
-| `db` | A Data principles · B Unicode |
-| `docs` | A Index & Structure · B Lifecycle & Sync · C Drift audit |
-| `content` | A Content principles · B Style & patterns · C Separation |
-| `seo` | A Meta & structure · B AI visibility & entity · **C ⟨Aki⟩ API & tooling stack** |
-| `release` | A Versioning core · B Identify & audit · **C ⟨Aki⟩ Web release artifacts** |
-| `stack` | A Cloudflare & TypeScript foundation · B Render · i18n · Vue patterns · **C ⟨Aki⟩ Ecosystem conventions** |
-| `tauri` | A Never block the UI · B Boundary & config |
-| `ui` | A Taxonomy & tokens · B Component structure · C Audit playbook |
-| `think` | A Decision framework · B 5 Modules · C Radar |
-| `flow` | A Flow thinking · B 8 first-principles questions · C Closure & output |
-| `biz` | A Positioning & audience · B Offer & pricing · C Messaging & customer psychology |
-| `ux` | A Lenses · B Walkthrough protocol · C Output & decision |
-| `zero-trust` | A Scope-lock · B Mechanical pass first · C Evidence classes · D Signature propagation · E Adversarial self-challenge · F Report |
-| `proportion` | A Dimensioning · B Verdict · C Output & reuse |
-| `subtract` | A Scope & terminating condition · B The passes · C Output · D Runner |
-| `frozen-ref` | A Locate every reference · B Build the comparison mechanically · C Report |
-
-Full item-level breakdown: `docs/research/public-private-abc-restructure.md`.
-
-## Cross-cutting lens
-
-Some subjects legitimately live in several files: one **root rule** stating the principle, plus **domain applications** that must stay inside their domain (moving them would strip the context where they are actually read). This section is an **address map only — never rule text** — so it stays a pointer, not a duplicate.
-
-| 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 · `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 · `docs.A5` the auto-loaded instruction file (deletion test plus a majority-of-requests reach bar, since every line is paid on every request) · `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) |
-| **Subtraction before abstraction** (packaging repetition is second-best; not needing it is first) | `think.B4` — what can be deleted, skipped, merged, delayed, or made manual | `pattern.B3` first bullet of the critique gate · `ui.A1` delete/inherit/hoist pass ahead of the tier ladder · `subtract` the repo-wide audit form of the same question, read-only and detector-driven · akiflow's `aki-challenger`, which closes every solution-shaped item on "what can be cut?" |
-| **Interrupting the owner** (a question must survive the kill-tests before it costs a read and an answer) | `agent.A3` — impact, already-authorized, silence≠contradiction, reversibility as the fourth, plus escalation outcomes and a `Decided: X · because Y · rejected Z (why) · reopen if W` decision block for what does get self-answered | `coding.B3` one human hand-off ledger per run, deduped by flow · `coding.B5` the six-rung ladder a check must fail before it may be handed to the owner at all, and the one-line reason each survivor carries · `release.B8` a question the repo already answers is a violation; owner-worded criteria decided and reported, escalated only when readings diverge on an irreversible artifact · akiflow Step 4 seat-raised `CONFLICT` filtered through the lead's kill-test pass |
-
-| **Literal parity with a frozen external artifact** (a clause claiming byte/structural identity with a named reference is not satisfied by "looks compliant") | `frozen-ref.A` — resolve the reference to an exact path before judging; read ≥2 implementations when more than one exists, since one reference can itself have drifted | `stack.C1` ⟨Aki⟩ canonical component names — the naming half of this problem · `pattern.A7` root naming rule that frozen-reference structural clauses do not override · `zero-trust.C` evidence-class discipline this method inherits |
-
-Add a lens row only when a subject has actually caused a miss — `pattern.A2` (Rule of Three) applies to this rule corpus too, and so did a real production incident where a migration script shipped in CHANGELOG but was never executed against remote D1 (2026-07-23). The `frozen-ref` row above was added after a private project spent over ten audit sessions re-discovering the same structural drift against its own frozen reference each time, because compliance was judged from the rule's prose instead of a literal diff against the reference file.
-
-## Precedence
-When rules conflict, use this order:
-1. Current local source code, runtime output, and build output
-2. User's explicit instruction in the current conversation
-3. User's standing instructions — `~/.claude/CLAUDE.md` and the machine-local `~/.claude/CLAUDE.local.md`. An item marked ABSOLUTE there is never weakened by anything below it, including a shared rule that grants an autonomy other projects rely on; ordinary guidance there yields to a more specific project rule.
-4. Project `CLAUDE.md`
-5. Aki-RULE shared files
-6. Older docs, memory, or prior conversation context
-
-Project `CLAUDE.md` may add project facts and stricter constraints. It must not silently weaken core safety, verification, or source-of-truth rules.
-
-Corpus-maintenance material (project binding, change policy) lives in the source repo's `README.md` — repo path recorded in `~/.aki/akidevrule/.source-repo`.