@godxjp/ui 23.2.0 → 23.3.0

package/docs/DESIGN-AUTHORITY.md

@@ -12,17 +12,17 @@ It changes no code by itself. It is the tie-breaker a reviewer points at.
 
 ## The layers, and who owns each
 
-| Layer                                                              | Authority                                     | Status in this repo                                                                                                               |
-| ------------------------------------------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Interaction semantics, keyboard, ARIA                              | **WAI-ARIA APG**                              | already followed — 33 references in `src/`                                                                                        |
-| Behaviour primitives                                               | **Radix**                                     | already the implementation — 193 references                                                                                       |
-| Component composition shape                                        | **shadcn**                                    | already the structural convention — 23 references                                                                                 |
-| Component taxonomy / grouping                                      | **Ant Design** groups                         | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed |
-| Colour foundation                                                  | **SmartHR**                                   | already the palette source — `--primary` = SmartHR MAIN `#0071bd`, `--foreground` = TEXT_BLACK, `--border` = BORDER               |
-| **Derived colour — the interaction states hanging off each seed**    | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold — see below |
-| **Japanese UI convention — density, JP typography, form patterns** | **SmartHR**                                   | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves |
-| **Japanese accessibility / public-sector convention**              | **デジタル庁 Design System** (Digital Agency) | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3)                       |
-| **Spacing, density, type scale, information architecture**         | **IBM Carbon**                                | **NEW — this decision**                                                                                                           |
+| Layer                                                              | Authority                                       | Status in this repo                                                                                                                                  |
+| ------------------------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Interaction semantics, keyboard, ARIA                              | **WAI-ARIA APG**                                | already followed — 33 references in `src/`                                                                                                           |
+| Behaviour primitives                                               | **Radix**                                       | already the implementation — 193 references                                                                                                          |
+| Component composition shape                                        | **shadcn**                                      | already the structural convention — 23 references                                                                                                    |
+| Component taxonomy / grouping                                      | **Ant Design** groups                           | already the catalog shape: `data-entry`, `data-display`, `layout`, `feedback`, `navigation`, `general` — a naming precedent, nothing is installed    |
+| Colour foundation                                                  | **SmartHR**                                     | already the palette source — `--primary` = SmartHR MAIN `#0071bd`, `--foreground` = TEXT_BLACK, `--border` = BORDER                                  |
+| **Derived colour — the interaction states hanging off each seed**  | **Measured contrast (WCAG 2.2 / JIS X 8341-3)** | Authored in `src/tokens/derived.css`; no algorithm derives them. Four contrast suites read that file and hold every value to a threshold — see below |
+| **Japanese UI convention — density, JP typography, form patterns** | **SmartHR**                                     | **NEW — this decision.** Extends SmartHR from "where the colours came from" to the authority for how a JP business screen behaves                    |
+| **Japanese accessibility / public-sector convention**              | **デジタル庁 Design System** (Digital Agency)   | **NEW — this decision.** The reference when a JP customer asks which standard a screen meets (JIS X 8341-3)                                          |
+| **Spacing, density, type scale, information architecture**         | **IBM Carbon**                                  | **NEW — this decision**                                                                                                                              |
 
 The first five were already true and merely unwritten. The last three are the choices being made
 here. Carbon fills the one layer that had no outside answer at all: page rhythm, table density, form layout,
@@ -197,10 +197,34 @@ rows or a totals row — which is how a consumer ends up hand-rolling a `<tfoot>
 in page CSS.
 
 **The rule: where antd names a capability, this library takes antd's name and antd's semantics.**
-The gap is read out of the INSTALLED types (`antd/es/table/interface.d.ts`,
-`antd/es/table/InternalTable.d.ts` and the `@rc-component/table` interface they extend) — never
-from memory, because antd's own names move between majors (`fixed: 'left'` is deprecated in favour
-of `start` inside rc-table itself).
+
+> **Restated and widened by the repo owner on 2026-09-12, because the rule above was being read as
+> advice rather than as the standard it is: Ant Design IS the standard. A missing capability is
+> ported from antd 100% FIRST — its names, its props, its semantics — and improved afterwards.
+> Not redesigned first, and not half-ported.**
+>
+> Two things forced the restatement, both measured rather than felt:
+>
+> - `Dialog` + `AlertDialog` ship **26** exports with **12 name-for-name pairs and 0 parts unique
+>   to `AlertDialog`**, whose entire difference is `role="alertdialog"` plus `isDismissable={false}`
+>   — two props the shell already takes. antd has exactly one `Modal`, where danger is `okType`
+>   and `Modal.confirm()`. The shape here came from Radix, silently, against this very rule
+>   (gh#567). A package-wide sweep over all 272 public exports found this is the ONLY such pair:
+>   `Skeleton.Avatar/Button/Input/Image/Node` looks identical in shape but is antd's own naming,
+>   so it is compliance, not drift.
+> - Whole families arrived half-ported: Ant Design X without `Conversations`, `Attachments`,
+>   `ThoughtChain`, `Welcome` or `Actions` (gh#559); `FloatButton` never at all (gh#558);
+>   `Typography` reduced to `Text` + `Heading`, with `Paragraph`, `Link`, `copyable`, `editable`,
+>   `mark`, `keyboard` and `italic` simply absent.
+>
+> A deviation from antd is still allowed — the three below are — but it must be WRITTEN DOWN at
+> the point of deviation. An undocumented deviation is a bug, and gh#567 is what that bug costs:
+> a consumer forced to pick between the right ARIA role and a form it needs, and an accessibility
+> decision pushed onto the party least able to make it.
+> The gap is read out of the INSTALLED types (`antd/es/table/interface.d.ts`,
+> `antd/es/table/InternalTable.d.ts` and the `@rc-component/table` interface they extend) — never
+> from memory, because antd's own names move between majors (`fixed: 'left'` is deprecated in favour
+> of `start` inside rc-table itself).
 
 > Đọc sau 20.0.0: bản major ấy đã **gỡ `antd` khỏi devDependencies** cùng máy sinh màu của nó, và
 > `check:no-antd-runtime` canh cho nó không quay lại. Câu trên mô tả cách bề mặt prop này ĐƯỢC ĐỌC
@@ -240,12 +264,12 @@ to trust them had to.
 **The authority is now the measurement, not the derivation.** Four suites read `derived.css`
 directly and hold every value in it to a threshold this repo has already committed to:
 
-| suite                                                   | what it holds                                                                                                                                                        |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| suite                                                    | what it holds                                                                                                                                                          |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `src/tokens/__tests__/focus-ring-contrast.test.ts`       | the focus mark in both switch positions — ≥3:1 (WCAG 2.2 SC 1.4.11) on every surface a control sits on, and the halo proven to be decoration rather than the indicator |
-| `src/tokens/__tests__/interactive-fill-contrast.test.ts` | an interactive fill must clear **4.5:1** against the label sitting on it                                                                                              |
-| `src/tokens/__tests__/destructive-contrast.test.ts`      | `--destructive-hover` / `--destructive-active` against the same bar                                                                                                  |
-| `src/lib/__tests__/theme-tokens-css.test.ts`             | the tier is actually loaded, and complete in both themes                                                                                                             |
+| `src/tokens/__tests__/interactive-fill-contrast.test.ts` | an interactive fill must clear **4.5:1** against the label sitting on it                                                                                               |
+| `src/tokens/__tests__/destructive-contrast.test.ts`      | `--destructive-hover` / `--destructive-active` against the same bar                                                                                                    |
+| `src/lib/__tests__/theme-tokens-css.test.ts`             | the tier is actually loaded, and complete in both themes                                                                                                               |
 
 The first three also pin each value as a literal, so an edit to `derived.css` alone turns CI red
 rather than quietly retinting the library. **That is a stronger claim than the generator made, not

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "23.2.0",
-  "godxUiMcp": "23.2.0",
+  "version": "23.3.0",
+  "godxUiMcp": "23.3.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     }
   },
   "sideEffects": false,
-  "description": "@godxjp/ui — shared React UI framework (shadcn + Radix + Tailwind v4).",
+  "description": "@godxjp/ui \u2014 shared React UI framework (shadcn + Radix + Tailwind v4).",
   "files": [
     "LICENSE",
     "dist",
@@ -397,7 +397,8 @@
     "check:number-input-step-target": "node scripts/check-number-input-step-target.mjs",
     "check:mcp-token-sync": "node scripts/gen-component-tokens.mjs --check",
     "check:email-token-sync": "node scripts/gen-email-tokens.mjs --check",
-    "check:focus-ring-paint": "node scripts/check-focus-ring-paint.mjs"
+    "check:focus-ring-paint": "node scripts/check-focus-ring-paint.mjs",
+    "typecheck:mcp": "node node_modules/typescript-7/bin/tsc --noEmit -p mcp/tsconfig.json"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^5.2.0",
@@ -412,11 +413,26 @@
     "zod": "^4.4.0"
   },
   "peerDependenciesMeta": {
-    "recharts": {
+    "@hookform/resolvers": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
       "optional": true
     },
     "playwright": {
       "optional": true
+    },
+    "react-hook-form": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "dependencies": {

package/scripts/_agent-setup.mjs

@@ -3,10 +3,25 @@
  * init-agent-kit.mjs (explicit, full kit). Every writer is IDEMPOTENT and
  * NON-DESTRUCTIVE: it only creates a missing file or ADDS a missing key, never
  * overwrites existing config.
+ *
+ * That sentence was a claim, not a guarantee, until gh#541: `readJson` returned `null` for BOTH
+ * "no file" and "file I cannot parse", so `readJson(path) ?? {}` read a consumer's malformed
+ * `.mcp.json` as an empty one and wrote over it — their other MCP servers went with it, silently.
+ * The guarantee is now structural: a file that exists but cannot be read, parsed, or recognised is
+ * NEVER written to. We leave a `.godxjp-ui-suggested` sidecar next to it and say so.
  */
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** The godxjp-ui MCP server — pulled on demand via npx (no extra dependency to ship). */
@@ -20,6 +35,14 @@ export const MCP_KEY = "godx-ui";
 export const AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.mjs";
 export const PRIMER_CMD = "cat .claude/godxjp-ui-workflow.md";
 
+/** What `.claude/settings.json` would get, used only for the `.godxjp-ui-suggested` sidecar. */
+const SUGGESTED_HOOKS = {
+  PostToolUse: [
+    { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: AUDIT_HOOK_CMD }] },
+  ],
+  SessionStart: [{ hooks: [{ type: "command", command: PRIMER_CMD }] }],
+};
+
 /** The per-session workflow mandate the SessionStart hook injects into the agent. */
 export const KIT_VERSION = readJson(join(SELF_ROOT, "package.json"))?.version ?? "0.0.0";
 
@@ -145,14 +168,89 @@ Full guide: \`.claude/godxjp-ui-workflow.md\`.
 <!-- godxjp-ui:end -->
 `;
 
-function readJson(path) {
+/**
+ * Read a JSON file and say WHICH failure happened. Collapsing "absent" and "corrupt" into one
+ * `null` is the whole of gh#541 — see the module header.
+ *
+ * @returns {{state:"ok",json:object}|{state:"missing"}|{state:"unreadable"}|{state:"invalid-json"}|{state:"wrong-shape"}}
+ */
+function readJsonFile(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    return error.code === "ENOENT" ? { state: "missing" } : { state: "unreadable" };
+  }
+  let json;
   try {
-    return JSON.parse(readFileSync(path, "utf8"));
+    json = JSON.parse(raw);
   } catch {
-    return null;
+    return { state: "invalid-json" };
+  }
+  // `JSON.parse` happily returns `null`, `[]` or `"text"`. Merging keys into any of those and
+  // writing the result back is the same data loss by a different door, so it is a refusal too.
+  if (json === null || typeof json !== "object" || Array.isArray(json))
+    return { state: "wrong-shape" };
+  return { state: "ok", json };
+}
+
+/** The sentence that goes in the refusal, so a consumer knows which of the three it hit. */
+const READ_FAILURE = {
+  "invalid-json": "not valid JSON",
+  "wrong-shape": "JSON, but not an object",
+  unreadable: "unreadable",
+};
+
+/** Unusable-as-absent — only for the read-only callers, which never write anything back. */
+function readJson(path) {
+  const read = readJsonFile(path);
+  return read.state === "ok" ? read.json : null;
+}
+
+/**
+ * Write through a temp file + rename. `writeFileSync` is NOT atomic: an interrupt mid-write (^C
+ * during `npm install`, a full disk, the OOM killer) leaves a truncated file behind, which the
+ * next run reads as malformed. That is how the two halves of gh#541 fed each other — one bad
+ * write manufactured the precondition for the overwrite.
+ */
+function writeFileAtomic(path, data) {
+  // UNIQUE temp name. A fixed `${path}.godxjp-ui-tmp` is a shared mutable file: two installs
+  // running at once — a workspace installing packages in parallel is enough — write over each
+  // other's temp and `rename` whichever finished last.
+  const tmp = `${path}.godxjp-ui-tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    writeFileSync(tmp, data);
+    // `rename` does NOT carry the target's permissions: the new file is born under the process
+    // umask. A `.mcp.json` the consumer had chmod 600 would come back 644 after the first sync,
+    // silently, because the CONTENT would be right. This happens on every write, not only under
+    // contention, which makes it the worse half of the two.
+    try {
+      chmodSync(tmp, statSync(path).mode & 0o7777);
+    } catch {
+      // No existing file (a create), or a filesystem that will not report/set the mode. Either
+      // way the default is correct and this must not abort the write.
+    }
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // Nothing to clean up.
+    }
+    throw error;
   }
 }
 
+/**
+ * Refuse to touch `path`, leave what we WOULD have written beside it, and return the sentence the
+ * caller prints. A diff the consumer can read beats a config we guessed at.
+ */
+function refuseAndSuggest(path, data, reason) {
+  const suggested = `${path}.godxjp-ui-suggested`;
+  writeFileAtomic(suggested, data);
+  return `left untouched (${reason}) — see ${basename(suggested)}`;
+}
+
 /** Ensure `.mcp.json` registers the godx-ui MCP server. Returns 'created' | 'added' | 'present'. */
 /**
  * The version that wrote each managed artefact, stamped so `postinstall` can tell "already there"
@@ -164,22 +262,61 @@ function readJson(path) {
  * agent reading whatever guidance shipped the day the package was FIRST installed. The library
  * moved; the instructions for using it did not.
  */
+/**
+ * Replace the delimited managed region, or REFUSE.
+ *
+ * The old shape set `tail = ""` when the closing marker was missing and returned
+ * `current.slice(0, i) + next` — so a file whose end marker had been deleted (or truncated away by
+ * a half-finished write) lost everything after the opening marker. Whatever the consumer wrote
+ * below our block was simply gone (gh#541).
+ *
+ * There is no safe way to guess where a region ends, so we do not guess. Two refusals, both
+ * returning `null` for the caller to report:
+ *   • the opening marker appears more than once — which region is ours is ambiguous;
+ *   • the closing marker is missing — the region has no end.
+ * A closing marker that appears more than once is NOT a refusal: the first one after the opening
+ * marker is the region's end, and everything past it is preserved either way.
+ *
+ * @returns {string|null} the rewritten file, or `null` to say "do not write".
+ */
 export function refreshBlock(current, next, startMarker, endMarker) {
-  const i = current.indexOf(startMarker);
-  if (i < 0) return current.replace(/\s*$/, "") + "\n\n" + next;
-  const j = endMarker ? current.indexOf(endMarker, i) : -1;
-  const tail = j < 0 ? "" : current.slice(j + endMarker.length);
-  return current.slice(0, i) + next + tail;
+  const first = current.indexOf(startMarker);
+  if (first < 0) return current.replace(/\s*$/, "") + "\n\n" + next;
+  if (current.indexOf(startMarker, first + startMarker.length) >= 0) return null;
+  if (!endMarker) return null;
+  const j = current.indexOf(endMarker, first);
+  if (j < 0) return null;
+  return current.slice(0, first) + next + current.slice(j + endMarker.length);
 }
 
 export function ensureMcpJson(root) {
   const path = join(root, ".mcp.json");
-  const json = readJson(path) ?? {};
+  const read = readJsonFile(path);
+  if (read.state !== "ok" && read.state !== "missing") {
+    return refuseAndSuggest(
+      path,
+      JSON.stringify({ mcpServers: { [MCP_KEY]: MCP_SERVER } }, null, 2) + "\n",
+      READ_FAILURE[read.state],
+    );
+  }
+  const json = read.state === "ok" ? read.json : {};
+  if (
+    json.mcpServers !== undefined &&
+    (json.mcpServers === null ||
+      typeof json.mcpServers !== "object" ||
+      Array.isArray(json.mcpServers))
+  ) {
+    return refuseAndSuggest(
+      path,
+      JSON.stringify({ mcpServers: { [MCP_KEY]: MCP_SERVER } }, null, 2) + "\n",
+      "`mcpServers` is not an object",
+    );
+  }
   json.mcpServers = json.mcpServers ?? {};
   if (json.mcpServers[MCP_KEY]) return "present";
-  const created = !existsSync(path);
+  const created = read.state === "missing";
   json.mcpServers[MCP_KEY] = MCP_SERVER;
-  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
   return created ? "created" : "added";
 }
 
@@ -187,7 +324,31 @@ export function ensureMcpJson(root) {
 export function ensureClaudeHooks(root) {
   const path = join(root, ".claude", "settings.json");
   mkdirSync(dirname(path), { recursive: true });
-  const json = readJson(path) ?? {};
+  const read = readJsonFile(path);
+  if (read.state !== "ok" && read.state !== "missing") {
+    // Same guard as ensureMcpJson, and the reason it is here rather than only there: this file
+    // holds the consumer's OWN hooks. Rewriting it from `{}` silently unhooks their tooling.
+    return [
+      refuseAndSuggest(
+        path,
+        JSON.stringify({ hooks: SUGGESTED_HOOKS }, null, 2) + "\n",
+        READ_FAILURE[read.state],
+      ),
+    ];
+  }
+  const json = read.state === "ok" ? read.json : {};
+  if (
+    json.hooks !== undefined &&
+    (json.hooks === null || typeof json.hooks !== "object" || Array.isArray(json.hooks))
+  ) {
+    return [
+      refuseAndSuggest(
+        path,
+        JSON.stringify({ hooks: SUGGESTED_HOOKS }, null, 2) + "\n",
+        "`hooks` is not an object",
+      ),
+    ];
+  }
   json.hooks = json.hooks ?? {};
   const added = [];
 
@@ -209,7 +370,7 @@ export function ensureClaudeHooks(root) {
     added.push("SessionStart:workflow-primer");
   }
 
-  writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
+  writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
   return added;
 }
 
@@ -225,10 +386,10 @@ export function writeWorkflowMd(root) {
   if (existsSync(path)) {
     const cur = readFileSync(path, "utf8");
     if (cur.trim() === WORKFLOW_MD.trim()) return false;
-    writeFileSync(path, WORKFLOW_MD);
+    writeFileAtomic(path, WORKFLOW_MD);
     return "refreshed";
   }
-  writeFileSync(path, WORKFLOW_MD);
+  writeFileAtomic(path, WORKFLOW_MD);
   return true;
 }
 
@@ -248,7 +409,8 @@ function blockIsCurrent(existing, block) {
   const wanted = stampedDigest(block);
   const have = stampedDigest(existing);
   if (wanted && have) return wanted === have;
-  const region = (text) => text.slice(text.indexOf("<!-- godxjp-ui:start"), text.indexOf("<!-- godxjp-ui:end -->"));
+  const region = (text) =>
+    text.slice(text.indexOf("<!-- godxjp-ui:start"), text.indexOf("<!-- godxjp-ui:end -->"));
   return region(existing).trim() === region(block).trim();
 }
 
@@ -264,17 +426,22 @@ export function ensureClaudeMd(root) {
     // reached nobody, and the block still read as current. A file written before digest stamping
     // has no digest at all, so fall back to comparing the rendered body.
     if (blockIsCurrent(existing, CLAUDE_MD_BLOCK)) return "present";
-    writeFileSync(
-      path,
-      refreshBlock(existing, CLAUDE_MD_BLOCK, "<!-- godxjp-ui:start", "<!-- godxjp-ui:end -->"),
+    const next = refreshBlock(
+      existing,
+      CLAUDE_MD_BLOCK,
+      "<!-- godxjp-ui:start",
+      "<!-- godxjp-ui:end -->",
     );
+    if (next === null)
+      return refuseAndSuggest(path, CLAUDE_MD_BLOCK, "godxjp-ui markers are broken");
+    writeFileAtomic(path, next);
     return "refreshed";
   }
   if (existing == null) {
-    writeFileSync(path, CLAUDE_MD_BLOCK);
+    writeFileAtomic(path, CLAUDE_MD_BLOCK);
     return "created";
   }
-  writeFileSync(path, existing.replace(/\s*$/, "") + "\n\n" + CLAUDE_MD_BLOCK);
+  writeFileAtomic(path, existing.replace(/\s*$/, "") + "\n\n" + CLAUDE_MD_BLOCK);
   return "appended";
 }
 
@@ -323,8 +490,8 @@ export function refreshGuineaPigSkill(root) {
   const current = readFileSync(target, "utf8");
   const marker = "\n---\n\n# 8. ";
   const i = current.indexOf(marker);
-  writeFileSync(target, base.replace(/\s*$/, "") + "\n" + (i < 0 ? "" : current.slice(i)));
-  writeFileSync(optin, `${stamp}\n`);
+  writeFileAtomic(target, base.replace(/\s*$/, "") + "\n" + (i < 0 ? "" : current.slice(i)));
+  writeFileAtomic(optin, `${stamp}\n`);
   return true;
 }
 
@@ -370,7 +537,7 @@ export function ensureConsumerRules(root) {
     return false;
   }
   mkdirSync(dir, { recursive: true });
-  writeFileSync(target, next);
+  writeFileAtomic(target, next);
 
   // Prettier and this writer were fighting over the same file: the body holds aligned markdown
   // tables, Prettier reformats them, the digest changes, the next install writes it back, and
@@ -383,7 +550,7 @@ export function ensureConsumerRules(root) {
       (line) => !cur.includes(line),
     );
     if (owned.length) {
-      writeFileSync(
+      writeFileAtomic(
         ignoreFile,
         `${cur.replace(/\s*$/, "")}\n\n# Owned by @godxjp/ui — rewritten on every install, never hand-formatted.\n${owned.join("\n")}\n`,
       );
@@ -396,7 +563,7 @@ export function ensureConsumerRules(root) {
   if (existsSync(index)) {
     const cur = readFileSync(index, "utf8");
     if (!cur.includes(".ai/rules/godxjp-ui.md")) {
-      writeFileSync(
+      writeFileAtomic(
         index,
         cur.replace(/\s*$/, "") + `\n| ${uiDir}/** | .ai/rules/godxjp-ui.md |\n`,
       );

package/scripts/guinea-pig-skill.md

@@ -131,6 +131,20 @@ những thứ ấy trên PR. **Tới được bước này KHÔNG phải là đ
 một câu hỏi, không phải một chướng ngại. Nếu bạn tin cổng ấy sai thì nói ra và
 đưa số đo, đừng lặng lẽ sửa nó.
 
+**VÀ ĐỪNG NGỒI CHỜ CI.** Đẩy nhánh, mở PR, rồi đi làm việc khác. Không có vòng lặp
+`until … gh pr checks … sleep` nào cả. CI chạy là việc của CI; nếu cần theo dõi thì
+mở một agent nền, đừng chặn người đang điều phối. Đo được ngày 12/09/2026: một lượt
+ngồi poll bốn shard đã ăn hơn một tiếng đồng hồ của chủ dự án để nhìn một thanh tiến
+trình, trong khi có việc khác đang xếp hàng.
+
+**Và full suite thì chạy theo LỊCH, không nằm trong vòng lặp sửa code của ai.** Cùng
+ngày, tôi thêm bốn shard vitest vào làn PR của kho DS và đặt chúng thành required
+check, để bịt một khoảng trống có thật (hai commit vào `main` đỏ qua một làn nhanh
+xanh). Khoảng trống là thật và phép đo trung thực — nhưng nó chỉ định giá **máy**.
+Máy chưa bao giờ là phần đắt. Từ lúc ấy mọi PR phải chờ bốn shard mới merge được.
+Đã hoàn nguyên. Một hàng rào làm người điều phối phải chờ không rẻ hơn một `main`
+đỏ; nó chỉ dời chi phí sang con đường duy nhất không song song hoá được.
+
 ### Bước 6 — Khép vòng
 
 Phát hành → nâng gói ở consumer → **gỡ vá tạm** → **gỡ mọi chú thích "chờ

package/scripts/postinstall.mjs

@@ -20,13 +20,22 @@ if (skip) process.exit(0); // silent: CI / opt-out / self-install / no consumer
 
 try {
   const r = ensureMcpJson(root);
+  // A refusal is a full sentence, not one of the three status words — say it on its own line
+  // rather than folding it into "MCP in .mcp.json (…)", where it would read as a success.
+  if (r.startsWith("left untouched")) {
+    console.log(`\n  @godxjp/ui → .mcp.json ${r}\n`);
+  }
   // The mandate is plain text the agent reads every turn (CLAUDE.md block + workflow file). It
   // changes nothing in the dev loop, so it is installed by default: an agent that never saw the
   // but no mandate). Only the hooks — which DO change the loop — stay behind `init-agent`.
   const md = ensureClaudeMd(root);
+  if (md.startsWith("left untouched")) {
+    console.log(`  @godxjp/ui → CLAUDE.md ${md}\n`);
+  }
   const wf = writeWorkflowMd(root);
   const skill = refreshGuineaPigSkill(root);
   const rules = ensureConsumerRules(root);
+  if (r.startsWith("left untouched") || md.startsWith("left untouched")) process.exit(0); // already reported
   if (r === "present" && md === "present" && !wf && !skill && !rules) process.exit(0); // current — stay quiet
   console.log(
     `\n  @godxjp/ui → MCP in .mcp.json (${r}); workflow mandate in CLAUDE.md (${md}).\n` +