@akinet/akidevrule 3.3.1 → 3.5.0

package/lib/permissions.mjs

@@ -0,0 +1,244 @@
+// Script pre-allow for every agent harness akidevrule deploys skills to.
+// Matcher facts per harness: docs/ref/cli-permission-allowlist-standard.md.
+import { existsSync, readdirSync, readFileSync, mkdirSync } from "node:fs";
+import { join, dirname, relative, isAbsolute, sep } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Inventory — the scripts and the command lines that invoke them
+// ---------------------------------------------------------------------------
+
+export function listSkillScripts(skillsSrc) {
+  const scripts = [];
+  for (const skill of readdirSync(skillsSrc).sort()) {
+    const dir = join(skillsSrc, skill, "scripts");
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir).sort()) {
+      if (name.endsWith(".py")) scripts.push([skill, "scripts", name]);
+    }
+  }
+  return scripts;
+}
+
+function launchers(isWin) {
+  return isWin ? ["py -3", "python", "python3"] : ["python3"];
+}
+
+// Every rendering a model may type: absolute and `~/`-literal, since no surveyed matcher expands `~` on both sides.
+export function scriptInvocations({ roots, scripts, home, isWin }) {
+  const out = new Set();
+  for (const root of new Set(roots)) {
+    for (const parts of scripts) {
+      const abs = join(root, ...parts);
+      const renderings = [abs];
+      const rel = relative(home, abs);
+      if (rel && !rel.startsWith("..") && !isAbsolute(rel)) renderings.push("~/" + rel.split(sep).join("/"));
+      for (const launcher of launchers(isWin)) {
+        for (const path of renderings) out.add(`${launcher} ${path}`);
+      }
+    }
+  }
+  return [...out];
+}
+
+// ---------------------------------------------------------------------------
+// Ownership — which existing entries this installer wrote and may replace
+// ---------------------------------------------------------------------------
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Owned = any Python launcher pointing into `<akiSkill>/scripts/`, plus the directory-glob rules of earlier releases.
+export function ownershipTest(skillNames) {
+  const names = skillNames.map(escapeRe).join("|");
+  const current = new RegExp(`(?:py -3|python3?)[\\s:]+\\S*[\\\\/](?:${names})[\\\\/]scripts[\\\\/]`);
+  const legacy = /^(?:(?:Bash|command)\()?python3 \S*(?:skills|agskills)[\\/]\*{1,2}\)?$/;
+  return (entry) => typeof entry === "string" && (current.test(entry) || legacy.test(entry));
+}
+
+export function replaceOwned(list, isOwned, desired) {
+  return [...list.filter((e) => !isOwned(e)), ...desired];
+}
+
+// Recovers a --claude-dir root already recorded in a shared target's allowlist, so a run that omits the flag does not prune it as stale.
+export function recoverSkillRoots(allow, isOwned, home) {
+  const roots = new Set();
+  for (const entry of allow) {
+    if (!isOwned(entry)) continue;
+    const m = /^command\((?:py -3|python3?)[ :]+(.+)\)$/.exec(entry);
+    if (!m) continue;
+    let p = m[1];
+    if (p.startsWith("~/")) p = join(home, ...p.slice(2).split("/"));
+    if (!isAbsolute(p)) continue;
+    const root = dirname(dirname(dirname(p)));
+    if (isAbsolute(root)) roots.add(root);
+  }
+  return [...roots];
+}
+
+// ---------------------------------------------------------------------------
+// File writers
+// ---------------------------------------------------------------------------
+
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+function writeIfChanged(path, before, after, io) {
+  if (before === after) return false;
+  mkdirSync(dirname(path), { recursive: true });
+  if (existsSync(path)) io.backup(path);
+  io.writeText(path, after);
+  return true;
+}
+
+function updateJson(path, mutate, io) {
+  const before = existsSync(path) ? readFileSync(path, "utf-8") : null;
+  const data = before === null ? {} : JSON.parse(before);
+  if (!isObject(data)) throw new Error(`must be a JSON object: ${path}`);
+  mutate(data);
+  return writeIfChanged(path, before, JSON.stringify(data, null, 2) + "\n", io);
+}
+
+function allowList(data, key = "allow") {
+  if (!isObject(data.permissions)) data.permissions = {};
+  if (!Array.isArray(data.permissions[key])) data.permissions[key] = [];
+  return data.permissions;
+}
+
+const BLOCK_START = "# >>> akidevrule managed — regenerated on every install";
+const BLOCK_END = "# <<< akidevrule managed";
+
+// Kiro 3.x: one `rules:` list per file; the managed items live between two marker comments at its end.
+function writeKiroYaml(path, matches, isOwned, io) {
+  const before = existsSync(path) ? readFileSync(path, "utf-8") : null;
+  let body = (before ?? "").replace(new RegExp(`\\n?${escapeRe(BLOCK_START)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n?`), "\n");
+  // Pre-marker releases appended bare allow items; drop those whose every match line is owned.
+  body = body.replace(/\n  - capability: shell\n    match:\n((?:      - ".*"\n)+)    effect: allow\n?/g, (item, lines) =>
+    lines.trimEnd().split("\n").every((l) => isOwned(JSON.parse(l.trim().slice(2)))) ? "\n" : item
+  );
+  body = body.replace(/\s+$/, "");
+  if (!/^rules:/m.test(body)) body = (body ? body + "\n" : "") + "rules:";
+  const block = [BLOCK_START, "  - capability: shell", "    match:", ...matches.map((m) => `      - ${JSON.stringify(m)}`), "    effect: allow", BLOCK_END];
+  return writeIfChanged(path, before, body + "\n" + block.join("\n") + "\n", io);
+}
+
+function splitLauncher(invocation) {
+  const i = invocation.startsWith("py -3 ") ? 5 : invocation.indexOf(" ");
+  return [invocation.slice(0, i), invocation.slice(i + 1)];
+}
+
+// ---------------------------------------------------------------------------
+// Harness adapters — one per rule dialect
+// ---------------------------------------------------------------------------
+
+// Claude Code: `*` spans `/` and spaces; used inside the settings.json merge the installer already owns.
+export function claudeAllowRules(invocations) {
+  return invocations.map((inv) => `Bash(${inv}*)`);
+}
+
+// Each adapter: which config it owns, which skill roots its sessions see, and how to write the rules.
+export function harnessAdapters(ctx) {
+  const { home, claudeSkillRoots, dirs } = ctx;
+  const primaryClaude = claudeSkillRoots[0];
+  return [
+    {
+      id: "antigravity",
+      present: existsSync(dirs.gemini),
+      roots: [dirs.geminiSkills, ...claudeSkillRoots],
+      files: [join(dirs.gemini, "antigravity-cli", "settings.json"), join(dirs.gemini, "settings.json")],
+      // Literal string-prefix matcher, no glob: one rule per exact invocation.
+      write(path, invs, isOwned, io) {
+        return updateJson(path, (data) => {
+          const perms = allowList(data);
+          const lanes = [
+            `write_file(${join(home, ".aki", "agent-council")}/)`,
+            `read_file(${join(home, ".aki", "akidevrule")}/)`,
+            "write_file(~/.aki/agent-council/)",
+            "read_file(~/.aki/akidevrule/)",
+          ];
+          perms.allow = replaceOwned(perms.allow.filter((e) => !lanes.includes(e)), isOwned, [
+            ...invs.map((inv) => `command(${inv})`),
+            ...lanes,
+          ]);
+          perms.allowNonWorkspaceAccess = true;
+          perms.agentMode = true;
+          if (!Array.isArray(perms.trustedWorkspaces)) perms.trustedWorkspaces = [];
+          if (!perms.trustedWorkspaces.includes(home)) perms.trustedWorkspaces.push(home);
+        }, io);
+      },
+    },
+    {
+      id: "kiro",
+      present: existsSync(dirs.kiro),
+      roots: [dirs.kiroSkills, primaryClaude],
+      files: [join(dirs.kiro, "settings", "permissions.yaml")],
+      write: (path, invs, isOwned, io) => writeKiroYaml(path, invs.map((inv) => `${inv}*`), isOwned, io),
+    },
+    {
+      id: "codex",
+      present: existsSync(dirs.codex),
+      roots: [dirs.agentsSkills, primaryClaude],
+      // A whole file akidevrule owns — regenerated, never merged.
+      files: [join(dirs.codex, "rules", "akidevrule.rules")],
+      write(path, invs, _isOwned, io) {
+        const before = existsSync(path) ? readFileSync(path, "utf-8") : null;
+        const rules = invs.map((inv) => {
+          const [launcher, script] = splitLauncher(inv);
+          const pattern = [...launcher.split(" "), script].map((t) => JSON.stringify(t)).join(", ");
+          return `prefix_rule(pattern = [${pattern}], decision = "allow")`;
+        });
+        return writeIfChanged(path, before, ["# Generated by akidevrule installer — do not edit.", ...rules, ""].join("\n"), io);
+      },
+    },
+    {
+      id: "cursor",
+      present: existsSync(dirs.cursor),
+      roots: [dirs.agentsSkills, primaryClaude],
+      files: [join(dirs.cursor, "cli-config.json")],
+      // `Shell(<first token>:<args glob>)`; a bare `Shell(python3)` would allow every Python command.
+      write(path, invs, isOwned, io) {
+        return updateJson(path, (data) => {
+          const perms = allowList(data);
+          perms.allow = replaceOwned(perms.allow, isOwned, invs.map((inv) => {
+            const [launcher, args] = splitLauncher(inv);
+            const [base, ...flags] = launcher.split(" ");
+            return `Shell(${base}:${[...flags, args].join(" ")}*)`;
+          }));
+        }, io);
+      },
+    },
+    {
+      id: "opencode",
+      present: existsSync(dirs.opencode),
+      roots: [primaryClaude, dirs.agentsSkills],
+      files: [join(dirs.opencode, "opencode.json")],
+      // `permission.bash` maps glob → action, last match wins, so owned keys go last.
+      write(path, invs, isOwned, io) {
+        return updateJson(path, (data) => {
+          if (!isObject(data.permission)) data.permission = {};
+          const bash = data.permission.bash;
+          const kept = isObject(bash) ? bash : typeof bash === "string" ? { "*": bash } : {};
+          const next = Object.fromEntries(Object.entries(kept).filter(([k]) => !isOwned(k)));
+          for (const inv of invs) next[`${inv}*`] = "allow";
+          data.permission.bash = next;
+        }, io);
+      },
+    },
+  ];
+}
+
+// Returns one report row per file touched or skipped, for the install summary.
+export function applyHarnessPreAllow(ctx, io) {
+  const isOwned = ownershipTest(ctx.akiSkillNames);
+  const report = [];
+  for (const adapter of harnessAdapters(ctx)) {
+    if (!adapter.present) continue;
+    const invs = scriptInvocations({ roots: adapter.roots, scripts: ctx.scripts, home: ctx.home, isWin: ctx.isWin });
+    for (const file of adapter.files) {
+      try {
+        const changed = adapter.write(file, invs, isOwned, io);
+        report.push({ id: adapter.id, file, rules: invs.length, changed });
+      } catch (err) {
+        report.push({ id: adapter.id, file, error: err.message });
+      }
+    }
+  }
+  return report;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@akinet/akidevrule",
-  "version": "3.3.1",
-  "description": "Aki's shared rule corpus + Agent Skills for Claude Code, Gemini/Antigravity, Codex, Kiro and Grok — install and update with one command.",
+  "version": "3.5.0",
+  "description": "Aki's shared rule corpus + Agent Skills for Claude Code, Gemini/Antigravity, Codex, Kiro, Grok, Cursor and OpenCode — install and update with one command.",
   "keywords": [
     "claude-code",
     "agent-skills",
@@ -10,6 +10,8 @@
     "codex",
     "kiro",
     "grok",
+    "cursor",
+    "opencode",
     "ai-rules",
     "coding-standards",
     "installer",
@@ -40,6 +42,7 @@
     "install.mjs",
     "install.sh",
     "install.ps1",
+    "lib/",
     "payload/",
     "skills/",
     "claude/",

package/payload/GEMINI.md

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

package/payload/METHOD-audit-frozen-reference.md

@@ -0,0 +1,33 @@
+# Frozen-Reference Compliance Audit
+
+<!-- Address map: frozen-ref.A1-3 · frozen-ref.B1-5 · frozen-ref.C1-5 -->
+
+**Activation**: a rule or project doc names one or more concrete implementations as the canonical/frozen shape another project must match structurally (a pinned dependency version, a byte-identical component, a literal config key, a frozen page layout) — and the user asks whether the target actually conforms, at any strictness down to a single character.
+
+## Why this method exists
+
+Ordinary rule-following audits judge against *principles* (DRY, SRP, naming) — a project can satisfy those by reading well. A frozen-reference clause instead claims literal parity with a specific artifact that exists somewhere else. Reading the rule's prose and judging "this looks compliant" against memory or impression is the single highest-frequency failure mode for this class of clause: the rule text describes the shape, but only the reference file *is* the shape. A rule audited this way will keep re-surfacing the same violations across sessions, because "looks compliant" is not falsifiable and each session re-derives its own impression instead of re-running the same diff.
+
+This method forces the audit to be a diff against the actual reference bytes, never a recollection of them. It inherits `zero-trust`'s CERTAIN/SUGGESTED evidence split and read-only discipline (`agent.B5`) — this file adds what is specific to *comparing against a named external artifact* rather than auditing a codebase against itself.
+
+## A. Locate every reference before judging anything
+
+1. **Resolve the exact file(s)** the clause points to — not "the project that implements X" but the literal path(s):line(s). A frozen-reference clause with no resolvable path is not yet auditable; resolve it first or say plainly it cannot be resolved.
+2. **A single reference can itself have drifted from the written rule.** When more than one implementation of the standard exists, read at least two independently before ruling — where they disagree with each other, that is a defect in the *rule corpus*, not in the target project being audited. Report it as a **standard-vs-practice gap**, separate from target defects, and never charge it against the target.
+3. **Note what changed since the clause was written.** A frozen reference frozen a year ago against a codebase that has since evolved elsewhere is now two artifacts pulling apart; say so rather than silently picking a side.
+
+## B. Build the comparison mechanically, never from memory
+
+1. **One row per literal unit**, not per file: a specific exported function name, a specific class/prop, a specific config key, a specific sequence of steps in a flow. "The auth composable looks similar" is not a row; "`loginWithGoogle` returns `Result<T>`, the reference throws" is.
+2. **Verdict per row is one of exactly:** `MATCH` / `RENAMED` / `MISSING` / `EXTRA` / `STRUCTURAL-DIFF`. No row gets softened into "acceptable variance," "close enough," or "minor style difference" inside the audit — that judgment belongs to whoever reads the report, not to the auditor produced it. State the literal fact; let severity be decided downstream.
+3. **Distinguish clauses that explicitly allow local naming** (a rule that says "class names follow each project's own tokens") from clauses that claim structural/sequence/value identity. The former makes a naming difference not-a-violation by the rule's own text; the latter makes even a one-character difference a row. Cite which kind of clause governs each row — do not apply free-naming leniency to a clause that never granted it, and do not manufacture a violation out of a clause that did.
+4. **Every row carries `path:line` on both sides** — the target and whichever reference the row was checked against. A row without both sides is not yet evidence.
+5. **When the target diverges from the frozen shape, check whether a separate, higher-precedence rule justifies the divergence** (a project-level constraint that pre-dates and conflicts with the frozen clause). Report the conflict explicitly rather than either silently fixing it or silently ignoring it — that decision is the project owner's, not the auditor's.
+
+## C. Report
+
+1. **Verdict first**: does the target meet the standard, plainly stated, before any table.
+2. **Findings ranked by severity** (hard-rule / functional break → structural drift → cosmetic), each with the comparison row(s) that produced it.
+3. **A separate, clearly labeled section for standard-vs-practice gaps** (A2) — these are follow-ups for the rule corpus, not the audited project.
+4. **A coverage line**: which references were read, which clauses could not be resolved to a path, what was explicitly out of scope for this run.
+5. **Read-only** (`agent.B5`): this produces a report, never a fix. Fixing what the report finds is a separate, explicitly authorized run.

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

@@ -1,6 +1,6 @@
 # Zero-Trust Audit Method
 
-**Activation**: the user asks for a strict, uncompromising sweep ("audit khắt khe", "ép rule", "force audit", "quét tuyệt đối", "zero-trust audit", "rà soát toàn bộ").
+**Activation**: the user asks for a strict, uncompromising sweep that must be proven by detectors rather than impression — of the whole project, or of a change plus everything that reads it.
 
 Zero trust means nothing counts as clean because it looks clean: a finding exists only when a mechanism produced it, and it weighs exactly what that mechanism weighs — an exact match is a verdict, a pattern match is a candidate. This is **read-only** like every audit (`agent.B5`): it reports, it does not fix, it never mutates git state. Fixing is a separate run, sized after the report is read.
 

package/payload/METHOD-deep-think.md

@@ -22,7 +22,7 @@ Not every decision deserves the same depth. Before applying any module, size the
 
 This METHOD is consumed three ways:
 
-- **Passive (this file, via akirule):** akirule auto-loads it when a normal task hits a matching signal. Apply the lenses inline, briefly, inside the current answer. Ask at most ONE clarifying question. Never turn a routine task into an interrogation session.
+- **Passive (this file, via akirule):** the router loads it whenever a task evaluates, decides or critiques rather than only executes. Apply the lenses inline, briefly, inside the current answer. Ask at most ONE clarifying question. Never turn a routine task into an interrogation session.
 - **Triggered self-run:** fired by `agent.A3`'s deep-think triggers, or by owner-authorized self-run (`skills/akithink/SKILL.md` § Self-run mode). Non-interactive — run Modules 1–3 and 5 (add 4 when there is business context), depth scaled to difficulty. Ends in decide-and-report or escalate per `agent.A3`'s outcomes, never in a question left hanging.
 - **Active (`/akithink` skill):** the user explicitly opens a full structured thinking session. That skill runs a 5-phase interactive protocol and uses this METHOD as its toolbox at maximum depth.
 

package/payload/RULE-agent-behavior.md

@@ -58,11 +58,11 @@ A worker is a subagent, or the same or another CLI called headlessly (`claude -p
 
 **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.
+**When delegation is warranted, use the cheap wide-context tier the host resolves, one shot** — the literal command, model id and read-only mechanism per host live in one table (`skills/akiflow/references/harness-facts.md` § Model tiers › Host resolution), never in this rule. That tier holds a very large context; its failure mode is skimming, so the counter is prompt precision rather than a bigger model: name the exact paths, the exact question, and the exact output shape, and leave it nothing to improvise. Keep it to a single call — multi-turn on those CLIs degrades badly.
 
 **Know which kind of cheap you are buying.** A stateless cheap call is cheap *per call* and must re-receive its context every time. A persistent worker (`claude -p --session-id <uuid>`, later `--resume <uuid>`) is cheap *per turn after the first*, because its prefix is cached — roughly an eighth of the opening turn, then flat — and it keeps everything **it** was told, though nothing the caller knows. Use the first for one wide question, the second for a worker you will come back to. The session id is scoped to the directory it was created in.
 - **A worker inherits nothing** — not your context, not your rules, not your router. Name the exact rule files it must read and the exact paths or targets it must look at. "Follow the project rules" loads nothing and reads as compliance.
-- **Require the return leg — the worker reports what it actually received.** Naming the files is only half the loop: a brief that was ignored, a path that no longer resolves, and a rule read in full all produce output that looks the same. The worker's first line is a receipt — `[RULES] agent,coding (brief) | missing: none` — naming the topic address of every rule file it read and listing anything it was told to read and could not. A worker gets one round, so this is not conditional: with no receipt, a later violation cannot be traced to either the brief or the behavior, and those two have opposite fixes. Format and the session-side duty: `skills/akirule/SKILL.md` § Load confirmation.
+- **Require the return leg — the worker reports what it actually received.** Naming the files is only half the loop: a brief that was ignored, a path that no longer resolves, and a rule read in full all produce output that looks the same. The worker's first line is a receipt — `[RULES] agent,coding (brief)` — naming the topic address of every rule file it read; a file the brief named that is absent from the line was not read. A worker gets one round, so this is not conditional: with no receipt, a later violation cannot be traced to either the brief or the behavior, and those two have opposite fixes. Format and the session-side duty: `skills/akirule/SKILL.md` § Load confirmation.
 - **Set both dials, every time: model tier and thinking effort.** An omitted parameter does not fall back to something cheap; it silently inherits the caller's own expensive settings. Silence is an expensive choice made by accident.
 - **Enforce read-only by mechanism, not by wording**, wherever "fixing while I'm here" would be unrecoverable — restrict the worker's tool set, or use the CLI's read-only/plan mode. A prompt-worded ban is one the model can talk itself out of.
 - **If a program will parse the output, use the structured-output flag** rather than asking for JSON in prose.
@@ -89,7 +89,9 @@ A worker is a subagent, or the same or another CLI called headlessly (`claude -p
 ### B3. Decision boundaries
 Ask before:
 - destructive or hard-to-reverse actions — hard-to-reverse means no backup/restore or fix-forward path exists; an action that has one (e.g. an additive migration with a backup, `stack.C8`) climbs `coding.B5`'s ladder instead of asking
+- discarding or hiding tracked/uncommitted work: `git stash`, `checkout -- <path>`/`checkout .`, `restore .`, `reset --hard`, `clean -f[d]`, `push --force`, `branch -D` — run only on the user's explicit ask, never as a shortcut past a failing check or an obstacle (`coding.B3`'s stash-for-attribution ban is the narrow instance of this)
 - changing deployment, infrastructure, auth, billing, or shared config assumptions
+- any test, benchmark, or trial run that spends paid API credits or session quota
 - modifying shared rule files, templates, or project-wide conventions
 - large rewrites or broad renames
 - actions visible to other people or external services

package/payload/RULE-coding.md

@@ -49,7 +49,7 @@ A principle with the procedure that guarantees it — apply to any edit of code
 ### B4. Self-documenting code — comments are a last resort
 Domain application of the density root (`agent.A4` — every line must carry information the reader does not already have); the naming root is `pattern.A7`. Penalty card: `[YAP]` (`agent` §0).
 - Naming and shape come first: a comment that explains *what* a block does is a failed name or a failed extraction — fix the name/structure (`pattern.A7`, `pattern.A3`), then delete the comment. Clean flow plus role-named functions and variables need no narration.
-- A comment may state only what the code cannot say: a non-obvious constraint, an external contract, a genuine why. Never narrate the next line, restate the signature, or record change history.
+- A comment may state only what the code cannot say: a non-obvious constraint, an external contract, a genuine why. Never narrate the next line, restate the signature, or record change history. What a pinned project doc already states, the code need not say either (`C1`).
 - Deletion test, per comment: if removing it loses nothing a reader needs beyond what the code already says, remove it. Default is silence — comment density is a smell, not a virtue.
 - Comments rot: no compiler checks a comment, so it drifts silently as the code under it changes, and a stale comment misleads worse than none — one more reason deletion is the default, and why a rationale that must stay current lives in a doc the code references ([[RULE-docs]] B3), never duplicated inline.
 - One line when a comment is genuinely needed; a rationale bigger than that lives in docs, with the comment holding only the reference (see [[RULE-docs]] B3).
@@ -79,6 +79,7 @@ None of this weakens `B3`'s honesty floor: what genuinely stays unverified is st
 ### C1. Error handling
 - Validate at system boundaries: user input, external APIs, filesystem, network, persistence
 - Do not add defensive guards for impossible internal states — and size the ones that do guard a reachable state against who can actually reach it (`METHOD-proportionality.md`), instead of adding protection by reflex
+- **Impossible and obvious are judged against the project's pinned facts** — `CLAUDE.md`, `docs/biz`, `docs/feat|arch`, recorded research decisions — never against imagination: a state those documents rule out gets no guard, a dependency they declare present gets no fallback, a fact they state gets no comment (`B4`), and a path they define gets one natural flow, not a patch beside it (`pattern.A8`)
 - Fail loudly in development when it helps reveal broken assumptions
 - Keep production failures safe and user-appropriate
 - **Never fabricate mock/fixture data as a runtime fallback for a missing dependency** (DB, API, service binding). Throw/return a real error instead. If a local dev environment genuinely lacks that dependency, fix the environment itself (real local instance, proper binding/proxy) — don't paper over it with fake data. Verify the dependency is actually unavailable by reading how the runtime/framework wires it in dev before assuming a fallback is needed at all.

package/payload/RULE-content-write.md

@@ -28,7 +28,7 @@ These rules apply to all product content: interface text, meta titles/descriptio
 ### B2. Writing style — density is enforced, not preferred
 - Prefer clear, concrete wording
 - Deletion test per sentence (domain application of `agent.A4`): a sentence ships only if cutting it loses information the reader needs. Cut preamble, filler connectives, restatement, and reassurance — length follows content, never the reverse.
-- First sentence carries the point (the benefit, the instruction, or the answer); detail follows. This generalizes B3's FAQ rule to all content.
+- First sentence carries the point (the benefit, the instruction, or the answer); detail follows. An FAQ answer is the sharpest case: answer in the first sentence, never a "Đây là...", "According to..." preamble.
 - Avoid filler and vague marketing language unless the project explicitly wants it
 - Keep headings short and literal
 - Punctuation: Strictly limit the use of em dash (—) and en dash (–)
@@ -38,7 +38,6 @@ These rules apply to all product content: interface text, meta titles/descriptio
 - Use stable labels for repeated concepts
 - Avoid unnecessary abbreviations in user-facing text
 - Make important entity definitions obvious near the start of a page or section
-- FAQ answers: answer directly in the first sentence — no "Đây là...", "According to..." preamble
 
 ## C. Separation
 
@@ -47,8 +46,9 @@ These rules apply to all product content: interface text, meta titles/descriptio
 - Do not let temporary task context leak into permanent copy
 
 ### C2. Content audit
-Read-only (`agent.B5`). Three sweeps, each anchored to the rule it checks:
+Read-only (`agent.B5`). Four sweeps, each anchored to the rule it checks:
 1. **Canonical-term drift** (A3) — grep UI strings and i18n keys for synonyms of one concept; one concept with two live labels is a finding.
 2. **Density** (B2) — deletion test per shipped sentence; preamble, restatement, and reassurance in product copy are findings.
 3. **i18n coverage** (A2) — hardcoded user-facing strings that should be keys (excluding the EN=VI exception).
+4. **Fact-check** (`agent.B2`) — every claim about a product, feature, version or number must trace to the project's `ref/fact-*` (`docs.A6`) first, then to that product's own repo or live page; a claim that cannot be traced is a finding, not a style note.
 Classify severity per `docs.C4` (wrong / stale / incomplete / cosmetic); findings spanning domains route into the `docs.C2` research+plan pair.

package/payload/RULE-docs.md

@@ -1,6 +1,6 @@
 # Core Docs Rules
 
-<!-- Address map: docs.A1-4 · docs.B1-3 · docs.C1-4 -->
+<!-- Address map: docs.A1-6 · docs.B1-3 · docs.C1-4 -->
 
 ## Goals
 Docs should be readable for both humans and LLMs.
@@ -19,7 +19,7 @@ Use these short, stable topic folders:
 - `docs/feat/` — features, systems, behaviors
 - `docs/arch/` — architecture, structure, technical design
 - `docs/plan/` — plans and execution notes
-- `docs/ref/` — stable references, setup notes, lookup docs
+- `docs/ref/` — stable lookups: commands, paths and setup steps, verified by running them; `ref/fact-*.md` holds claims about the outside world, verified by evidence (A6)
 - `docs/research/` — exploratory, comparative, or time-bound findings
 
 Do not create new top-level doc topics unless the existing set clearly fails.
@@ -32,10 +32,11 @@ Filenames across all `docs/*` never lead with a date — the content-identifying
 - For any project with a business dimension, `docs/biz/` is REQUIRED and is the spine.
 - All `arch/`, `feat/`, and `plan/` docs that touch product direction or money must reference it.
 - When code intent and a `biz/` doc disagree, the `biz/` doc wins — reconcile or escalate.
+- `biz/` holds decisions, not facts: it wins because the owner chose it, never because a source proved it. A market fact the decision rests on (a competitor's price, a platform limit) belongs in `ref/fact-*` with its evidence (A6), and the `biz/` doc cites it.
 
-### A4. Anchor stamp — `updated <time> <version>` on every `arch|biz|feat` doc
+### A4. Anchor stamp — `updated <time> <version>` on every `arch|biz|feat` doc and every `ref/fact-*`
 
-`arch/`, `biz/` and `feat/` hold current state and are the SSoT other docs and code are written against, so a reader cannot tell a still-true doc from a silently rotted one without knowing when it was last confirmed. These three folders carry a stamp; `plan/`, `research/` and `ref/` do not — the first two are event records whose own schema already dates them (B1, B2), and `ref/` is verified by running its commands, not by a date.
+`arch/`, `biz/` and `feat/` hold current state and are the SSoT other docs and code are written against, so a reader cannot tell a still-true doc from a silently rotted one without knowing when it was last confirmed. These three folders carry a stamp, and so does every `ref/fact-*` doc (A6): a fact is confirmed by reading a source on a date, and the outside world moves without touching this repo. `plan/`, `research/` and the rest of `ref/` do not — the first two are event records whose own schema already dates them (B1, B2), and a command lookup is verified by running it, not by a date.
 
 **Placement** — first line of the file's own header block: immediately under the H1 for a plain Markdown doc, or as a `updated:` key in the frontmatter/description field where the file already has one. One stamp per file, never per section.
 
@@ -51,6 +52,26 @@ Filenames across all `docs/*` never lead with a date — the content-identifying
 
 The stamp is what makes drift mechanically visible: a `docs/arch/` file stamped three releases back is a drift-audit lead (C3) before anyone reads a line of it.
 
+### A5. The auto-loaded instruction file — `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`
+
+The harness prepends this file to every request, so every line in it is paid on every turn and read under every task, related or not. It is the most expensive doc in the project and carries the highest bar: `agent.A4`'s deletion test with a reach condition on top. A line stays only if it passes all five, and the whole file is re-run through them on every edit:
+1. **Harm** — absent from every request, name the concrete mistake the agent makes. No nameable mistake, no line.
+2. **Reach** — it governs the majority of requests in this project. A line that matters to one domain belongs in the doc that domain's route loads (`feat/`, `arch/`, `biz/`, a project rule file), not here.
+3. **Not derivable** — it cannot be read from the code, the manifest (`package.json`, `Cargo.toml`), or a doc the router already loads for that task.
+4. **Not a restatement** — a shared-corpus rule is pointed at by address (`coding.B3`), never copied; a copy drifts and doubles the cost.
+5. **Facts and limits, not behavior** — the file binds the project's facts (stack, reference implementation, test and compile command, ship platform, hard limits) and stricter constraints; behavior rules live in the corpus (`index.md` § Precedence). Those bindings are the router's standing signal for every task in the project.
+
+One file is the source: a per-project `GEMINI.md` or `AGENTS.md` is a bootstrap that points at `CLAUDE.md`, never a second copy.
+
+### A6. Fact docs — `docs/ref/fact-*.md`
+
+Three claim classes, three authorities, never interchangeable: a **biz** claim is decided by the owner and wins by decision (A3); a **decision** is reached by research and holds by its recorded reasoning (B2); a **fact** is a claim about the outside world — a vendor's behavior, a limit, a price, what a standard specifies, what an artifact of a given version contains — and holds only by evidence. A fact nobody can trace is an unverified claim: it lives in `research/` marked as such, never in `ref/fact-*`.
+
+- **Every fact carries its own trail, on the claim, not only on the file**: the source — an official page with the date it was read, or a named artifact pinned by version with the path inside it — and the research doc and section that verified it (`research/<doc>.md § R3`). A fact with a source but no research origin was asserted, not verified.
+- **Current state only; history lives in research.** The fact doc is the distilled answer (B2 Action). Every change lands through a research event — an `## Amendments` entry when the finding stands, a successor doc when it changes — and the fact doc is updated in the same edit with its stamp rewritten (A4). A fact doc edited with no research event behind it is a **Wrong** finding (C3).
+- **A fact earns its row when a second consumer needs to cite it** — a rule, another doc, an audit (`content.C2`'s fact-check reads here before the product's repo or live page). A one-off finding stays in the research doc that produced it.
+- **The filename declares the class**: `fact-<subject>.md`. The rest of `ref/` stays commands and setup, verified by running.
+
 ## B. Lifecycle & Sync
 
 ### B1. Plan lifecycle & Filename Rules
@@ -79,7 +100,7 @@ Required fields, in order:
    - **Verification** — the evidence/method that hardens the result (data, test, cross-check against another case). If not verified, say so explicitly — silence reads as certainty when it isn't.
    - **Corroborating links** — links to the evidence/cases the result rests on or conflicts with (not just a verified/unverified flag)
 6. **Decision** — the resolution reached, one of:
-   - **Action** — link to the artifact(s) where it materialized (`arch/`, `plan/`, `feat/`, `biz/`, `ref/`, or code/commit); 0 or many. Landing in `ref/` always means a **new** clean lookup doc, never the research doc itself relocated or rewritten into ref format — `ref/` is a distilled answer, research is the narrative trail behind it.
+   - **Action** — link to the artifact(s) where it materialized (`arch/`, `plan/`, `feat/`, `biz/`, `ref/`, or code/commit); 0 or many. Landing in `ref/` always means a **new** clean lookup doc, never the research doc itself relocated or rewritten into ref format — `ref/` is a distilled answer, research is the narrative trail behind it. A fact lands in `ref/fact-*` (A6) with this doc's section named on the claim, so the trail runs both ways.
    - **No action** — state why explicitly, so it reads as a deliberate stop, not an abandoned doc
    - **Follow-up research** — link to the new research doc opened by this result
    - **Rejected/closed** — an option eliminated with no replacement; no link needed
@@ -128,7 +149,7 @@ Walk the topology, checking each doc against what is actually true now:
 - `docs/feat/` — the described behavior still matches what the code does
 - `docs/biz/` — where code intent contradicts it, A3 decides: the `biz/` doc wins until it is explicitly changed
 - `docs/research/` — a conclusion whose recorded context no longer holds needs a successor doc plus a `Status: superseded by` line; a claim corrected while the Decision stands needs an `## Amendments` entry plus a `Status: amended` notice; a body rewritten in place with neither is a **Wrong** finding (B2)
-- `docs/ref/` — commands, paths, and setup steps still run
+- `docs/ref/` — commands, paths, and setup steps still run; in `ref/fact-*`, every source still resolves and still says what the claim says, every pinned artifact version is still the one in use, and every claim's research origin exists — a claim changed with no research event behind it is **Wrong** (A6)
 - Doc references inside code comments (B3) still point at a heading that exists
 - **The inverse walk — code → docs:** a complex feature or subsystem shipped with no corresponding `feat/`/`arch/` doc is an **Incomplete** finding (C4). The audit checks both directions, never only whether existing docs still hold
 

package/payload/RULE-pattern-core.md

@@ -37,7 +37,7 @@ These are constraints on **structure and reuse**, not style. Reach for this file
 **A7 — Name by role, never by concrete value.** Name things for what they *mean*, not what they *currently are*: `retryLimit` not `three`, `PrimaryAction` not `BlueButton`, `AuthBoundary` not `FirebaseWrapper`. Value-names rot the instant the value changes and force codebase-wide find-and-replace.
 - *Root rule for naming.* Every other naming item in this corpus (`agent.C1` file names, `ui.A` tokens, `stack.C1` component names, `release.A3` version/tag format, `content` semantic stability) is a **domain application** of A7, not a competing rule — do not restate A7 in them, and do not move them out of their domain. Address map: `index.md` § Cross-cutting lens.
 
-**A8 — One flow, made natural — not guarded.** When the same guard / check / fallback keeps reappearing around a path, the path's shape is wrong. Reshape the flow so the correct behavior is automatic; do not stack more enforcement on a weak path. Full method: `METHOD-audit-flow.md`.
+**A8 — One flow, made natural — not guarded.** When the same guard / check / fallback keeps reappearing around a path, the path's shape is wrong. Reshape the flow so the correct behavior is automatic; do not stack more enforcement on a weak path. "Correct" is measured against the project's pinned facts (`coding.C1`), so a guard for a state those facts rule out is a patch, not a flow. Full method: `METHOD-audit-flow.md`.
 
 ---