@akinet/akidevrule 3.0.0

package/claude/agents/aki-judge.md

@@ -0,0 +1,37 @@
+---
+name: aki-judge
+description: Judge an artifact against exactly one standard, named at spawn (pattern, proportion, ux, db, seo, release, …). Returns a verdict with evidence, never a fix. Spawn one per standard rather than asking one agent to hold several.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# Mandate
+
+Judge the artifact you are given against **exactly one standard**, named in your brief. Return a verdict with evidence.
+
+One standard per spawn is the whole design. An agent asked to hold three standards at once averages them into a single mild opinion, and the disagreement between them — which is the useful output — disappears silently. If your brief names more than one, judge the first and say the rest need their own seat.
+
+Your verdict must be able to go against whoever spawned you. If you find yourself confirming the caller's stated conclusion, check that you would have reached it from the artifact alone.
+
+# Rules you must read before working
+
+- `~/.aki/akidevrule/RULE-agent-behavior.md` — the behavior floor, `B5` above all: you report, you never fix. No edits, no git state, ever.
+- **The one standard named in your brief** — the rule or method file itself, read in full. Judging from a remembered summary of a rule is the failure this seat exists to prevent.
+
+# Receipt — first line of your output, always
+
+```
+[RULES] agent,pattern (brief) | missing: none
+```
+
+If the standard you were told to judge against could not be read, say so under `missing:` and **stop** — do not judge from memory of it. That is a LOAD-fail, and it is a bug in the brief, not in the artifact.
+
+# Output contract
+
+- The verdict first: does the artifact meet the standard, and if not, at which specific clause.
+- Per finding: the clause address (`pattern.A2`), the `path:line` it fails at, and the quoted fragment. A finding with no location is not actionable and does not ship.
+- Rank by severity. Never pad the list flat to look thorough — a report where everything is medium tells the caller nothing.
+- Say what you did **not** cover. A standard has clauses your scope could not reach; silence about them reads as a pass.
+- No fixes, no diffs, no rewritten code. Scheduling the fix is the caller's decision.
+- You never escalate to the owner. A conflict goes to the caller as `CONFLICT:`, subject to `agent.A3`'s kill-tests.
+- Never state compliance as a citation. `pattern.A2` in your output proves the address was available to you, nothing more (`agent.B2`).

package/claude/agents/aki-maker.md

@@ -0,0 +1,36 @@
+---
+name: aki-maker
+description: Turn an already-made decision into a diff. The only agent permitted to write. Requires the decision, the exact files, and the domain rules named in its brief — it implements, it does not decide.
+tools: Read, Edit, Write, Bash
+model: sonnet
+---
+
+# Mandate
+
+Turn a decision that has already been made into a diff. You are the only agent permitted to write, which is exactly why your scope is the narrowest: you implement what the brief specifies, at the sites the brief names.
+
+**You do not decide.** If the brief is ambiguous, under-specified, or turns out to be wrong once you read the code, stop and report the gap. Do not resolve it yourself and do not implement a nearby thing that seems better — an unrequested improvement inside a diff is indistinguishable from the requested change at review time, which is how scope creep becomes permanent.
+
+Change exactly what was asked. No adjacent refactors, no cleanup, no renames, no new files beyond those specified (`agent.B1`). Report anything worth doing; never do it silently.
+
+# Rules you must read before working
+
+- `~/.aki/akidevrule/RULE-agent-behavior.md` — the behavior floor: `B1` scope discipline, `B3` what to ask before, `B4` no model-credit trailers in any git artifact, `C3` never hard-wrap a logical line, `C5` temp files only in the scratchpad.
+- `~/.aki/akidevrule/RULE-coding.md` — `B2` (read the flow and its docs before changing code you did not write; confirm the intents you did *not* set out to touch still hold), `B3` (done means verified, by the narrowest tool that settles the doubt), `B4` (the comment budget — fix the name, then delete the comment).
+- `~/.aki/akidevrule/RULE-pattern-core.md` — `C1` is the definition of done at the pattern level.
+- **The domain rules named in your brief** — stack, ui, db, docs, content, whichever apply. You inherit no router; a domain rule not in your brief is a domain rule you do not have, and you must say so rather than improvise it.
+
+# Receipt — first line of your output, always
+
+```
+[RULES] agent,coding,pattern,ui (brief) | missing: none
+```
+
+A non-empty `missing:` on a domain rule means you should not have written that part. Report it instead of guessing what the rule probably said.
+
+# Output contract
+
+- What changed, per file, in one line each — the change, not a narration of the edit.
+- The verification you actually ran, with its output. Never a build or a dev server on your own initiative: those are the owner's call (cost and side effects), and a change whose risk lives only at runtime is reported as **"unverified — needs a runtime check"** with the exact command, never as "Done" (`coding.B3`).
+- Anything the brief specified that you did **not** do, and why. Silence about a skipped item reads as completion.
+- Attestation as checkable fact, not as citation: `files edited: 4 · git mutations: none · scope: only the paths named in the brief`.

package/claude/fragments/settings.akidoc.fragment.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//~/.aki/akidevrule/**)",
+      "Bash(python3 ~/.claude/skills/*)",
+      "Bash(python3 ~/.aki/akidevrule/agskills/*)"
+    ],
+    "additionalDirectories": [
+      "~/.aki/akidevrule"
+    ]
+  },
+  "skillOverrides": {
+    "akirule": "on"
+  }
+}

package/claude/hooks/aki-update-check.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// akidevrule update-check hook (Claude Code SessionStart). Notify-only, fail-silent, never auto-updates — see README.md § Update notifications for the five-state contract this classifies against.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import {
+  STATE_UNKNOWN,
+  STATE_CURRENT,
+  STATE_AHEAD,
+  classifyState,
+  cmpSemver,
+  fetchRemoteChangelog,
+  localInstallPresent,
+  parseChangelogVersion,
+} from "./aki_version_check.mjs";
+
+const CHANGELOG_URL_HUMAN = "https://github.com/lacvietanh/akidevrule/blob/master/CHANGELOG.md";
+const REPO_URL = "https://github.com/lacvietanh/akidevrule";
+const UPDATE_CMD = "npx @akinet/akidevrule@latest";
+const THROTTLE_OK_HOURS = 24; // after a definitive result, wait a full day
+const THROTTLE_FAIL_HOURS = 1; // after offline/timeout, retry sooner so a notice is not lost
+
+const HOME = homedir();
+const INSTALL_ROOT = join(HOME, ".aki", "akidevrule");
+const LOCAL_CHANGELOG = join(INSTALL_ROOT, "CHANGELOG.md");
+const THROTTLE_FILE = join(HOME, ".claude", "hooks", ".aki-update-check");
+
+function silentExit() {
+  process.exit(0);
+}
+
+/** True if it is time to check again (also when the marker is missing/unreadable). */
+function checkDue() {
+  try {
+    const due = parseFloat(readFileSync(THROTTLE_FILE, "utf8").trim());
+    if (Number.isNaN(due)) return true;
+    return Date.now() / 1000 >= due;
+  } catch {
+    return true;
+  }
+}
+
+/** Record the next-allowed check time. */
+function deferCheck(hours) {
+  try {
+    mkdirSync(dirname(THROTTLE_FILE), { recursive: true });
+    writeFileSync(THROTTLE_FILE, String(Math.floor(Date.now() / 1000 + hours * 3600)));
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Return [[header, [lines]]] for each '## ' section, in file order. */
+function splitEntries(text) {
+  const entries = [];
+  let cur = null;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("## ")) {
+      cur = [line.slice(3).trim(), [line]];
+      entries.push(cur);
+    } else if (cur) {
+      cur[1].push(line);
+    }
+  }
+  return entries;
+}
+
+function emit(banner, context) {
+  process.stdout.write(
+    JSON.stringify({
+      systemMessage: banner,
+      hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context },
+      suppressOutput: true,
+    }) + "\n"
+  );
+}
+
+function reportMissing() {
+  const banner =
+    "📦 akidevrule is not installed on this machine\n" +
+    `   Install: ${UPDATE_CMD}\n` +
+    `   Repo:    ${REPO_URL}`;
+  const context =
+    "The akidevrule shared-rule corpus is not installed on this machine.\n" +
+    `To install it, run: ${UPDATE_CMD}`;
+  emit(banner, context);
+}
+
+/** Released entries strictly newer than localVersion, newest-first, skipping [Unreleased]. */
+function buildDelta(remoteText, localVersion) {
+  const deltaLines = [];
+  for (const [header, lines] of splitEntries(remoteText)) {
+    const m = header.match(/^\[(\d+\.\d+\.\d+)\]/);
+    if (!m) continue; // [Unreleased] or any other non-version heading
+    if (cmpSemver(m[1], localVersion) <= 0) break; // reached local's own version or older
+    deltaLines.push(...lines);
+  }
+  return deltaLines.join("\n").trim();
+}
+
+function reportUpdate(localVersion, remoteVersion, remoteText) {
+  let delta = buildDelta(remoteText, localVersion);
+  const maxDelta = 1400;
+  if (delta.length > maxDelta) {
+    delta = delta.slice(0, maxDelta).replace(/\s+$/, "") + "\n… (see full changelog at the link below)";
+  }
+  const banner =
+    "📢 akidevrule has a new update available\n" +
+    `   ${localVersion} → ${remoteVersion}\n` +
+    `   Update:    ${UPDATE_CMD}\n` +
+    `   Changelog: ${CHANGELOG_URL_HUMAN}\n\n` +
+    delta;
+  const context =
+    "The akidevrule shared-rule corpus has a newer version available.\n" +
+    `Installed: ${localVersion}. Latest: ${remoteVersion}.\n` +
+    `To update, run: ${UPDATE_CMD}\n\n` +
+    "What's new (from CHANGELOG.md):\n" +
+    delta;
+  emit(banner, context);
+}
+
+async function main() {
+  // Local file-stat, always run and never throttled — a not-installed machine must hear about it every session, not once per THROTTLE_OK_HOURS.
+  if (!localInstallPresent(INSTALL_ROOT)) {
+    reportMissing();
+    silentExit();
+  }
+
+  if (!checkDue()) silentExit();
+
+  let localText;
+  try {
+    localText = readFileSync(LOCAL_CHANGELOG, "utf8");
+  } catch {
+    deferCheck(THROTTLE_OK_HOURS);
+    silentExit();
+  }
+  const localVersion = parseChangelogVersion(localText);
+
+  const remoteText = await fetchRemoteChangelog();
+  const remoteVersion = remoteText ? parseChangelogVersion(remoteText) : null;
+
+  const state = classifyState(true, localVersion, remoteVersion);
+
+  if (state === STATE_UNKNOWN) {
+    deferCheck(THROTTLE_FAIL_HOURS); // offline/timeout -> retry soon
+    silentExit();
+  }
+
+  deferCheck(THROTTLE_OK_HOURS); // definitive answer -> next check in a day
+
+  if (state === STATE_CURRENT || state === STATE_AHEAD) {
+    silentExit(); // up to date, or a dev machine ahead of remote — never nag
+  }
+
+  reportUpdate(localVersion, remoteVersion, remoteText);
+  silentExit();
+}
+
+main().catch(silentExit);

package/claude/hooks/aki_version_check.mjs

@@ -0,0 +1,83 @@
+// Shared version-status parser for akidevrule (pattern.A1 SSOT).
+//
+// Imported by both install.mjs (--check / inspect) and aki-update-check.mjs
+// (SessionStart notify hook), so the two never classify the same CHANGELOG
+// differently. A keep-a-changelog file's *latest released* version is its first
+// `## [x.y.z]` heading — the `[Unreleased]` buffer at the top (release.A5's
+// normal working state) is never a version and must be skipped.
+import { statSync } from "node:fs";
+import { join } from "node:path";
+
+export const REMOTE_CHANGELOG_URL =
+  "https://raw.githubusercontent.com/lacvietanh/akidevrule/master/CHANGELOG.md";
+export const NETWORK_TIMEOUT_MS = 3000;
+
+export const STATE_MISSING = "missing";
+export const STATE_CURRENT = "current";
+export const STATE_UPDATE = "update";
+export const STATE_AHEAD = "ahead";
+export const STATE_UNKNOWN = "unknown";
+
+const VERSION_HEADING_RE = /^##\s*\[(\d+\.\d+\.\d+)\]/m;
+
+/** First released `## [x.y.z]` heading, skipping `[Unreleased]`. null if absent/unparseable. */
+export function parseChangelogVersion(text) {
+  if (!text) return null;
+  const m = text.match(VERSION_HEADING_RE);
+  return m ? m[1] : null;
+}
+
+/** -1/0/1 for a<b / a==b / a>b on 3-part numeric semver. Either side missing -> 0 (no claim). */
+export function cmpSemver(a, b) {
+  if (!a || !b) return 0;
+  const pa = a.split(".");
+  const pb = b.split(".");
+  for (let i = 0; i < 3; i++) {
+    const x = i < pa.length ? parseInt(pa[i], 10) : 0;
+    const y = i < pb.length ? parseInt(pb[i], 10) : 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Raw text of the public CHANGELOG.md. null on any network/HTTP failure — never throws. */
+export async function fetchRemoteChangelog(timeoutMs = NETWORK_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(REMOTE_CHANGELOG_URL, {
+      headers: { "User-Agent": "aki-update-check" },
+      signal: controller.signal,
+    });
+    if (!resp.ok) return null;
+    return await resp.text();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** True when installRoot looks intact enough to compare (CHANGELOG.md and index.md both present). */
+export function localInstallPresent(installRoot) {
+  return isFile(join(installRoot, "CHANGELOG.md")) && isFile(join(installRoot, "index.md"));
+}
+
+/** One of the STATE_* constants — see README.md "Update notifications" for the full 5-state table. */
+export function classifyState(localPresent, localVersion, remoteVersion) {
+  if (!localPresent) return STATE_MISSING;
+  if (remoteVersion == null) return STATE_UNKNOWN;
+  if (localVersion == null) return STATE_AHEAD;
+  const cmp = cmpSemver(localVersion, remoteVersion);
+  if (cmp === 0) return STATE_CURRENT;
+  if (cmp < 0) return STATE_UPDATE;
+  return STATE_AHEAD;
+}

package/docs/ref/macos-codesign-tcc.md

@@ -0,0 +1,59 @@
+# Local macOS codesign and TCC
+
+The one AkiDevRule lookup for this chain. `tauri.B7` is the concise rule (do not delete it); the installer (`install.mjs`) deploys this file to `~/.aki/akidevrule/docs/ref/macos-codesign-tcc.md`. Evidence trail: `docs/research/macos-tcc-tauri-boundary-aug21.md`.
+
+**Stable self-signed identity keeps TCC grants across rebuilds. Apple ad-hoc (`codesign --sign -`) does not.** Artifact names, install paths, and identity names live in that project’s own docs — not here.
+
+## Responsible process
+
+TCC judges a child (`git`/`rsync`/`ssh`/a CLI spawned by `std::process::Command`, `tauri-plugin-shell`, a PTY) by the **responsible process** at the head of the chain, inherited across `fork`/`posix_spawn`. Inside a shipped `.app` that is the bundle, never the user’s Terminal. Symptom: the same sidecar works in Terminal and is denied (`EPERM`, or a consent dialog naming the app) only in the bundle.
+
+## Three switches (not peers)
+
+- **Full Disk Access** (`kTCCServiceSystemPolicyAllFiles`) — top of the chain, a superset. If the responsible app holds it, protected locations are readable with no per-folder prompt. Request only when reach is genuinely unbounded.
+- **Files & Folders** (`kTCCServiceSystemPolicyDocumentsFolder`, `…DesktopFolder`, `…DownloadsFolder`, plus removable/network volumes) — least privilege; consulted only when there is no FDA. A refusal is **sticky**: one “Don’t Allow” = denial with no re-prompt. Recovery is `tccutil reset` or **removing** the app’s entry — flipping the toggle back on restores access but not prompting.
+- **Developer Tools** (`kTCCServiceDeveloperTool`) — **not file access.** Gatekeeper exemption for software the app *runs* (unsigned/ad-hoc sidecars, local toolchains). It silences no Files & Folders dialog.
+
+Scope every spawn (`cwd`, workspace, app data dir). An unbounded walk from `$HOME` is a prompt/`EPERM` storm charged to the bundle.
+
+This chain governs consent-based **reads**. User-picked Open/Save or drag-and-drop paths, and file *writes*, are a different diagnosis.
+
+When the switch is unknown: `log show --predicate 'subsystem == "com.apple.TCC"' --last 5m` prints `AttributionChain` and the result.
+
+## What TCC stores
+
+TCC does not store “this app path is allowed”. It stores a **code signing requirement** (`csreq`). At check time it evaluates the running binary against that requirement.
+
+| How the binary is signed | Designated requirement (typical) | Rebuild |
+|---|---|---|
+| Ad-hoc (`-`) | pinned to that build’s **CDHash** | CDHash changes → stored `csreq` fails → grant gone (Settings toggle can still look ON) |
+| Named cert (self-signed or Developer ID) | `identifier "bundle.id" and certificate leaf = H"…"` | CDHash still changes; **leaf hash does not** → grant holds |
+
+Measured 2026-08-28 on a Tauri `.app` re-signed with a login-keychain identity: DR was `identifier "<bundle-id>" and certificate leaf = H"…"`. CDHash is expected to change next compile.
+
+Do **not** regenerate the cert. A new leaf hash is a new DR; every existing grant dies. Create once; reuse.
+
+`security find-identity -p codesigning -v` lists only **trusted** identities. A self-signed cert often shows `CSSMERR_TP_NOT_TRUSTED` and vanishes from `-v`. `codesign --sign "Name"` still works. Probe without `-v`.
+
+`sudo codesign` is wrong: root’s keychain is not the login keychain. If the installed `.app` is root-owned from an old `sudo cp`, `chown` once, then sign as the user.
+
+## Gatekeeper is not TCC
+
+| | Trigger | Survives rebuild? |
+|---|---|---|
+| **Gatekeeper** | `com.apple.quarantine` (downloads). Local compile typically has none | N/A if never quarantined |
+| **TCC** | first access to a protected resource | yes iff DR stays the same cert+identifier |
+
+`xattr -cr` on the installed `.app` strips quarantine if something set it. It does not reset TCC. A “right-click Open once” warning is a Gatekeeper first-launch, not a TCC grant.
+
+## Rebuild and designated requirement
+
+A Tauri bundle step ad-hoc-signs. Overwriting that signature with the **same** named identity is required every build; that is the mechanism, not wasted work. `codesign --force --sign "…"` must preserve entitlements. Skip `codesign` after a bundle and you ship ad-hoc again.
+
+TCC evaluates the **running** binary against the stored `csreq`. The signed artifact and the `.app` the user launches must be the same path with the same DR. Signing a build output then opening a leftover copy does not keep the grant.
+
+`tccutil reset` only clears stale state; it does not prevent the next loss. Install location and identity display name live in that project’s docs.
+
+## Sources
+
+[Apple TN3127 — Inside Code Signing: Requirements](https://developer.apple.com/documentation/technotes/tn3127-inside-code-signing-requirements) · [Nick Liu — TCC pins Accessibility to a cdhash](https://www.nick-liu.com/posts/tcc-cdhash-trap/) · [Eclectic Light — app first run / quarantine](https://eclecticlight.co/2020/01/27/what-could-possibly-go-wrong-on-an-app-first-run/) · `tauri.B7` · `docs/research/macos-tcc-tauri-boundary-aug21.md` §5 + §5b