@zalkera/client 0.21.2 → 0.21.3

package/bin/validate-storefront.mjs

@@ -124,9 +124,9 @@
  * 이 파일은 **인자로 받은 소스 디렉터리 기준으로만** 동작한다(레포 고정 경로 0). 그래서 어느
  * 체크아웃에서든, 압축을 푼 zip 안에서든 똑같이 돈다.
  */
-import {existsSync, readdirSync, readFileSync, statSync} from "node:fs";
+import {existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync} from "node:fs";
 import {createRequire} from "node:module";
-import {basename, dirname, join, relative, resolve, sep} from "node:path";
+import {basename, dirname, isAbsolute, join, relative, resolve, sep} from "node:path";
 
 /**
  * 검사할 **소스 루트**(`src/`). 세 가지를 흡수한다 — 셋 다 실제로 사람이 치는 형태다.
@@ -151,6 +151,69 @@ function resolveSourceRoot() {
     return given; // 둘 다 아니면 준 대로 두고 아래 존재 검사가 말하게 한다
 }
 
+/**
+ * **못 잰 것**(unmeasured) — 통과도 위반도 아닌 셋째 칸.
+ *
+ * 종전엔 이 칸이 없어서 "읽지 못함"이 둘 중 하나로 접혔다:
+ *  - `walk` 의 `readdirSync`/`statSync` 는 **예외를 그대로 터뜨려** raw 스택트레이스 + rc=1 로 죽었다.
+ *    rc=1 은 "규약 위반 N개"와 같은 코드라, 수신자가 **도구가 죽은 것과 소스가 틀린 것을 못 가린다.**
+ *    실측: 심링크 루프·끊어진 심링크·권한 없는 디렉터리 셋 다 규칙이 **0개 돌기 전에** 죽었다.
+ *  - 형제 수집기들의 bare `catch {}` 는 **조용히 통과**시켰다. `.env` 를 못 읽으면 E3(시크릿 유출)가
+ *    아무 고지 없이 사라졌다(실측).
+ *
+ * `build.sh` 는 이 구분을 이미 한다 — `GATE-WARN … 통과가 아니라 미검사입니다` 를 두 번 외친다.
+ * 그 문장이 **파일 단위로도** 성립해야 한다. 그래서 셋째 칸을 1급으로 둔다.
+ *
+ * 처분은 모드로 갈린다(아래 종료 블록): 권고 모드는 경고·rc 0(고객 나무의 상태를 우리가 벌하지 않는다),
+ * 관문 모드는 fail-closed·**rc 7**. 관문 트리는 심링크 fail-closed·모드 0644 고정이라 이 칸이 뜨는 것이
+ * 구성상 불가능하고, 뜨면 그 자체가 변조·IO 이상 신호다 — 오탐 비용이 0이다.
+ */
+const unmeasured = [];
+
+/** 못 잰 것을 적는다. 사유(errno)와 무엇을 못 했는지를 함께 남긴다 — "안 잰 것을 잰 척" 하지 않기 위해. */
+function markUnmeasured(path, code, what) {
+    unmeasured.push({path: relative(process.cwd(), path), code: code ?? "UNKNOWN", what});
+}
+
+/**
+ * 못 읽으면 **적고 `null` 을 준다.** 조용한 `catch {}` 와 다르다 — 부재의 사유가 남는다.
+ *
+ * 이 검사기의 "못 읽음" 처분이 종전엔 네 가지로 갈려 있었다(심의 실측): 크래시(walk·AGENTS.md) ·
+ * 조용한 소멸(`.env`·`globals.css`) · 오분류 고지(N2 가 IO 오류를 "JSON 파싱 실패"로) · 통과.
+ * 한 자리로 모은다.
+ */
+function readSafe(file, what) {
+    try {
+        return readFileSync(file, "utf8");
+    } catch (e) {
+        if (e.code === "ENOENT") return null; // 없는 파일은 "못 잰 것"이 아니다 — 규칙이 판단할 사실이다
+        markUnmeasured(file, e.code, what);
+        return null;
+    }
+}
+
+/**
+ * **안전망** — 예기치 못한 예외가 raw 스택트레이스로 나가지 않게 한다.
+ *
+ * `build.sh` 가 스스로 적어 둔 「종료코드의 수신자는 비개발자다」가 근거다. 종전엔 파일시스템 예외
+ * 하나가 Node 스택 8줄 + `errno: -40` 으로 튀어나왔고, `verify-zip` 은 그것을 **납품 반려 사유로
+ * 그대로 인쇄**했다(실측). 납품사는 무엇을 고치라는 것인지 알 수 없었고, 실제로는 규약 검사가
+ * **0줄 돌았다.**
+ *
+ * rc=2(도구 오류)를 쓴다 — rc=1 은 "규약 위반"의 뜻이라 도구가 죽은 것과 섞이면 안 된다.
+ * 스택은 `ZALKERA_VALIDATE_DEBUG=1` 일 때만 보인다.
+ */
+process.on("uncaughtException", (err) => {
+    console.error(`\n❌ 검사기가 예기치 못한 오류로 멈췄습니다 — 규약 검사가 끝나지 않았습니다(통과가 아닙니다).`);
+    console.error(`   ${err?.code ? `[${err.code}] ` : ""}${err?.message ?? err}`);
+    if (err?.path) console.error(`   대상: ${err.path}`);
+    console.error(
+        `   개발자에게 이 줄을 전달하십시오. 자세한 스택은 ZALKERA_VALIDATE_DEBUG=1 로 다시 실행하면 나옵니다.`,
+    );
+    if (process.env.ZALKERA_VALIDATE_DEBUG === "1") console.error(err);
+    process.exit(2);
+});
+
 const root = resolveSourceRoot();
 
 /**
@@ -175,9 +238,18 @@ const repoRootDir = resolveRepoRoot(root);
  * 주의: 우리 `muted` 는 **글자색**이라 `bg-muted`(shadcn 은 배경)와 의미가 다르다.
  */
 const FOREIGN_TOKEN_CLASSES = [
-    "bg-card", "bg-popover", "bg-muted", "bg-accent", "bg-destructive",
-    "text-card-foreground", "text-popover-foreground", "text-muted-foreground", "text-accent-foreground",
-    "text-destructive", "ring-ring", "border-input",
+    "bg-card",
+    "bg-popover",
+    "bg-muted",
+    "bg-accent",
+    "bg-destructive",
+    "text-card-foreground",
+    "text-popover-foreground",
+    "text-muted-foreground",
+    "text-accent-foreground",
+    "text-destructive",
+    "ring-ring",
+    "border-input",
 ];
 
 /*
@@ -199,8 +271,21 @@ const FOREIGN_TOKEN_CLASSES = [
  *   검정이고 브랜드 색 표면이 아니다. 넣으면 정상 코드가 대량으로 빨개진다. 즉 이 축은 **안 잰다**.
  */
 const COLOR_UTILITY_ROOTS = new Set([
-    "bg", "text", "border", "ring", "outline", "decoration", "divide",
-    "placeholder", "caret", "accent", "fill", "stroke", "from", "via", "to",
+    "bg",
+    "text",
+    "border",
+    "ring",
+    "outline",
+    "decoration",
+    "divide",
+    "placeholder",
+    "caret",
+    "accent",
+    "fill",
+    "stroke",
+    "from",
+    "via",
+    "to",
 ]);
 /** 색 함수. `color-mix(` 까지 — Tailwind 임의값 안에서 전부 유효하다. */
 const COLOR_FUNCTION = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color-mix)\s*\(/;
@@ -213,13 +298,65 @@ const HEX_COLOR = /#[0-9a-fA-F]{3,8}(?![0-9a-zA-Z])/;
  * 아니라 위임이라 일부러 뺐다(Tailwind 에 `bg-transparent`·`text-current` 가 이미 있다).
  */
 const NAMED_COLORS = new Set([
-    "red", "blue", "green", "black", "white", "gray", "grey", "orange", "purple", "pink", "yellow",
-    "brown", "cyan", "magenta", "navy", "teal", "olive", "maroon", "lime", "aqua", "silver", "gold",
-    "indigo", "violet", "crimson", "coral", "salmon", "tomato", "khaki", "beige", "ivory", "azure",
-    "plum", "orchid", "turquoise", "lavender", "tan", "wheat", "snow", "skyblue", "hotpink",
-    "darkblue", "darkred", "darkgreen", "lightblue", "lightgray", "lightgrey", "midnightblue",
-    "steelblue", "slategray", "slategrey", "firebrick", "forestgreen", "seagreen", "royalblue",
-    "dodgerblue", "chocolate", "sienna", "peru",
+    "red",
+    "blue",
+    "green",
+    "black",
+    "white",
+    "gray",
+    "grey",
+    "orange",
+    "purple",
+    "pink",
+    "yellow",
+    "brown",
+    "cyan",
+    "magenta",
+    "navy",
+    "teal",
+    "olive",
+    "maroon",
+    "lime",
+    "aqua",
+    "silver",
+    "gold",
+    "indigo",
+    "violet",
+    "crimson",
+    "coral",
+    "salmon",
+    "tomato",
+    "khaki",
+    "beige",
+    "ivory",
+    "azure",
+    "plum",
+    "orchid",
+    "turquoise",
+    "lavender",
+    "tan",
+    "wheat",
+    "snow",
+    "skyblue",
+    "hotpink",
+    "darkblue",
+    "darkred",
+    "darkgreen",
+    "lightblue",
+    "lightgray",
+    "lightgrey",
+    "midnightblue",
+    "steelblue",
+    "slategray",
+    "slategrey",
+    "firebrick",
+    "forestgreen",
+    "seagreen",
+    "royalblue",
+    "dodgerblue",
+    "chocolate",
+    "sienna",
+    "peru",
 ]);
 
 /**
@@ -316,7 +453,11 @@ function detectStyleMode(srcDir) {
         const pkgPath = join(dir, "package.json");
         try {
             if (statSync(pkgPath).isFile()) {
-                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                // 못 읽으면 모드가 조용히 강등되어 **S 규칙군이 통째로 스킵**되고 ✅ rc 0 이 난다
+                // (심의 실측). 선언을 안 한 것과 못 읽은 것은 다른 사실이다.
+                const declText = readSafe(pkgPath, "스타일 규약 모드 판정(package.json)");
+                if (declText === null) return "none";
+                const pkg = JSON.parse(declText);
                 const styling = pkg?.zalkera?.styling ?? pkg?.oneque?.styling;
                 if (styling === "tailwind-tokens") return "declared";
                 if (styling !== undefined) return "none"; // 검사 규칙 없는 다른 선언값 = 잘커라 스타일 규약 없음
@@ -396,6 +537,25 @@ function servingSink() {
  * 반면 `E`(시크릿이 브라우저 번들에 실림)·`C`(SEO 라우트가 동적 SSR 강제)는 **사실을 잰다** — 오탐 여지가
  * 없고 상용 실측도 0건이라, 관문으로 켜도 아무도 안 막힌다. 그래서 그 둘만 `servingSink` 를 쓴다.
  */
+/**
+ * **X 축(X1·X1p·X3) 전용 목적지 — 승격은 영구 금지다**(memo140 §6.5).
+ *
+ * [clientIpSink] 와 지금은 같은 배열로 가지만 **함수가 다르다.** 이유는 [clientIpDeclarationSink] 와 같다:
+ * 남이 I1 을 `servingSink()` 로 승격시키는 날, 싱크를 공유하면 X 축이 **딸려 올라간다.**
+ *
+ * **왜 영구 금지인가.** "다른 수단으로 막고 있으니까"가 아니다 — 그렇게 적었다가 보안 심의 실측에
+ * 반증됐다(상용 사이트가 교차 오리진 요청을 200 으로 접수). 근거는 **이 검사가 안전을 재지 못한다**
+ * 는 것이다: X1 은 *"교차 오리진을 막았는가"* 가 아니라 *"우리 심볼 `assertSameOrigin` 을 썼는가"* 를
+ * 잰다. 동명 로컬 함수를 선언하면 통과하므로 **통과가 안전을 뜻하지 않는다.** 재지 못하는 것으로
+ * 남의 빌드를 막으면, 막는 대가는 치르고 얻는 안전은 없다.
+ *
+ * 그 결정의 **나머지 절반**은 "막지 않는 대신 반드시 보여야 한다"이다 — 이 경고가 업로드·검수 결과에
+ * 실제로 뜨지 않으면 그냥 방치다. ⚠ 오늘 이 경고는 `/api/system` 에만 보인다. 고칠 수 있는 당사자
+ * (파트너)가 못 보는 상태이고, 그 노출은 아직 안 만들었다.
+ *
+ * 그리고 X3 는 **경고다.** memo118 §2 가 "X3 가 strict 회귀를 error 로 막는다"고 적어 뒀던 것은
+ * 사실이 아니었다(2026-08-14 정정 · 그 문장이 근거로 인용되던 자리라 문서도 같이 고쳤다).
+ */
 function crossOriginSink() {
     return warnings;
 }
@@ -470,9 +630,9 @@ function servingOutputSink() {
 // ⚠ 아래 조각들은 **일반 문자열**로 쓴다. 정규식 리터럴·템플릿 리터럴 안에 백틱을 담을 수 없어서다
 //   (따옴표 세 종류를 다 흡수해야 하므로 백틱이 문자 클래스에 반드시 들어간다).
 /** 문자열 리터럴을 여는/닫는 따옴표 한 글자 — `"` · `'` · 백틱(```). */
-const QUOTE = '["\'\\u0060]';
+const QUOTE = "[\"'\\u0060]";
 /** 따옴표가 아닌 한 글자(리터럴 안쪽). */
-const NOT_QUOTE = '[^"\'\\u0060]';
+const NOT_QUOTE = "[^\"'\\u0060]";
 
 /** 헤더 이름 리터럴. Node(`req.headers["x-forwarded-for"]`)·web(`headers.get("x-forwarded-for")`) 양쪽을 흡수한다. */
 const XFF_NAME = new RegExp(`${QUOTE}x-forwarded-for${QUOTE}`, "i");
@@ -487,10 +647,7 @@ const SPLIT_ON_COMMA = `\\.\\s*split\\s*\\(\\s*${QUOTE}${NOT_QUOTE}*,${NOT_QUOTE
 const FIRST_ENTRY = "(?:\\s*\\[\\s*0\\s*\\]|\\s*\\.\\s*at\\s*\\(\\s*0\\s*\\)|\\s*\\.\\s*shift\\s*\\(\\s*\\))";
 
 /** 헤더 리터럴 → split → 첫 엔트리가 **한 표현식으로** 이어진 형태. 사이의 `?.`·`!`·`.trim()` 등은 흡수한다. */
-const I1_DIRECT = new RegExp(
-    `${QUOTE}x-forwarded-for${QUOTE}[\\s\\S]{0,120}?${SPLIT_ON_COMMA}${FIRST_ENTRY}`,
-    "i",
-);
+const I1_DIRECT = new RegExp(`${QUOTE}x-forwarded-for${QUOTE}[\\s\\S]{0,120}?${SPLIT_ON_COMMA}${FIRST_ENTRY}`, "i");
 
 /** `const xff = <…x-forwarded-for…>` — 같은 파일 안 단순 변수 경유를 좇기 위한 바인딩 수집. */
 const I1_BINDING = new RegExp(
@@ -655,7 +812,10 @@ function importsClientAtRuntime(text) {
         if (!braces) return true; // 기본·네임스페이스·부수효과 import — 값이다
         const outside = clause.replace(/\{[^}]*\}/, "").replace(/[\s,]/g, "");
         if (outside.length > 0) return true; // `import z, {type Order} from …`
-        const specifiers = braces[1].split(",").map((x) => x.trim()).filter(Boolean);
+        const specifiers = braces[1]
+            .split(",")
+            .map((x) => x.trim())
+            .filter(Boolean);
         if (specifiers.length === 0) return true; // `import {} from …` — 부수효과
         if (specifiers.some((x) => !/^type\s/.test(x))) return true;
     }
@@ -688,7 +848,8 @@ function prescription(called) {
     const parts = [];
     if (direct.length > 0) parts.push(`${direct.join("·")} 는 \`(첫 인자, {clientIp})\``);
     if (viaAccess.length > 0) parts.push(`${viaAccess.join("·")} 는 \`(no, {phone, context: {clientIp}})\``);
-    if (third.length > 0) parts.push(`${third.join("·")} 는 **세 번째** 인자라 \`(no, params, {phone, context: {clientIp}})\``);
+    if (third.length > 0)
+        parts.push(`${third.join("·")} 는 **세 번째** 인자라 \`(no, params, {phone, context: {clientIp}})\``);
     return parts.join(" · ");
 }
 
@@ -720,7 +881,24 @@ function prescription(called) {
  * 아래 문자 뒤라면 값이 올 자리이므로 정규식이고, 그 밖(식별자·`)`·숫자 뒤)이면 나눗셈이다.
  */
 const BEFORE_REGEX_LITERAL = new Set([
-    "(", ",", "=", ":", "[", "!", "&", "|", "?", "{", "}", ";", "+", "-", "*", "%", "~", "^",
+    "(",
+    ",",
+    "=",
+    ":",
+    "[",
+    "!",
+    "&",
+    "|",
+    "?",
+    "{",
+    "}",
+    ";",
+    "+",
+    "-",
+    "*",
+    "%",
+    "~",
+    "^",
 ]);
 
 /**
@@ -747,7 +925,20 @@ const BEFORE_REGEX_WORD = new Set([
     // 지금은 낱말이 아니라 **형태**로 가른다(아래 [isRegexStart]): `/` 다음이 공백·`{` 이거나 본문에
     // 리터럴 공백이 있으면 산문이다. 그래서 뺐던 낱말을 도로 넣어 잃었던 탐지를 회수했고,
     // 산문 6형상은 그대로 안 걸린다(심의 실측). 낱말 목록은 값-자리 판별용이지 산문 방어가 아니다.
-    "return", "throw", "typeof", "void", "await", "yield", "instanceof", "case", "else", "in", "of", "new", "delete", "do",
+    "return",
+    "throw",
+    "typeof",
+    "void",
+    "await",
+    "yield",
+    "instanceof",
+    "case",
+    "else",
+    "in",
+    "of",
+    "new",
+    "delete",
+    "do",
 ]);
 
 /**
@@ -954,7 +1145,10 @@ function maskCode(text, jsx = false) {
  */
 function callArguments(source, code, fn) {
     const found = [];
-    const opener = new RegExp(`(?:\\.|\\?\\.)\\s*${fn}\\s*(?:\\?\\.)?\\s*\\(|\\[\\s*["'\`]${fn}["'\`]\\s*\\]\\s*\\(`, "g");
+    const opener = new RegExp(
+        `(?:\\.|\\?\\.)\\s*${fn}\\s*(?:\\?\\.)?\\s*\\(|\\[\\s*["'\`]${fn}["'\`]\\s*\\]\\s*\\(`,
+        "g",
+    );
     // ⚠ 호출 **위치**는 원본에서 찾는다 — 브래킷 접근(`zalkera["getOrder"](…)`)은 이름 자체가 문자열
     // 안이라 덮은 사본에서는 사라진다. 깊이만 덮은 사본에서 세면 된다(길이가 같아 오프셋이 맞는다).
     for (const m of source.matchAll(opener)) {
@@ -1123,7 +1317,10 @@ function detectContentMode(srcDir) {
         const pkgPath = join(dir, "package.json");
         try {
             if (statSync(pkgPath).isFile()) {
-                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                // 위와 같은 자리 — 못 읽으면 N 규칙군이 통째로 스킵된다.
+                const declText = readSafe(pkgPath, "콘텐츠 규약 모드 판정(package.json)");
+                if (declText === null) break;
+                const pkg = JSON.parse(declText);
                 declared = pkg?.zalkera?.content ?? pkg?.oneque?.content;
                 break;
             }
@@ -1137,9 +1334,9 @@ function detectContentMode(srcDir) {
     if (declared === "source") return "declared";
     if (declared === "sections-db") {
         warnings.push(
-            "[N0] package.json 의 `zalkera.content` 가 은퇴한 값 `\"sections-db\"` 입니다 — " +
+            '[N0] package.json 의 `zalkera.content` 가 은퇴한 값 `"sections-db"` 입니다 — ' +
                 "섹션이 백엔드 DB 에 살던 시절의 표기이고 그 거처는 퇴역했습니다(어휘 rev 7). " +
-                "사이트의 얼굴을 `content/pages/*.json`·`content/nav.json` 으로 옮기고 선언을 `\"source\"` 로 바꾸세요 " +
+                '사이트의 얼굴을 `content/pages/*.json`·`content/nav.json` 으로 옮기고 선언을 `"source"` 로 바꾸세요 ' +
                 "(llms.txt §9.1).",
         );
         return "none";
@@ -1172,7 +1369,10 @@ function contentPageFiles(repoRoot) {
             .filter((n) => n.endsWith(".json"))
             .sort()
             .map((n) => join(dir, n));
-    } catch {
+    } catch (e) {
+        // 콘텐츠 디렉터리는 **선택**이다 — 없는 것은 정상이고 "못 잰 것"이 아니다.
+        // 그러나 있는데 못 읽는 것(권한·I/O)은 N 검사가 0줄 돈다는 뜻이라 적는다.
+        if (e.code !== "ENOENT" && e.code !== "ENOTDIR") markUnmeasured(dir, e.code, "N 콘텐츠 페이지 수집");
         return [];
     }
 }
@@ -1200,11 +1400,28 @@ const DOC_PATH_TOKEN = /^[A-Za-z0-9_.\-/[\]]+\.(?:tsx?|jsx?|mjs|cjs|json|css|md)
 const DOC_PATH_SKIP_PREFIX = ["doc/", "node_modules/", ".zalkera/", "@", "/", "http"];
 
 /** 문서 본문에서 이 레포의 파일을 가리키는 것으로 판정되는 백틱 토큰. */
+/**
+ * 문서에서 **좌표로 볼 백틱 토큰**을 고른다.
+ *
+ * ⚠ **`/` 요구는 실수가 아니라 정밀도의 근거다 — 넓히지 마라.** `.prettierrc.json` 처럼 슬래시 없는
+ * 루트 파일이 안 재진다는 것은 사실이고, 그래서 두 가지 확장을 실측으로 재 봤다(2026-08-14):
+ *
+ *  ⒜ **이름 좌표를 루트에서 찾기** — 우리 `AGENTS.md` 한 벌에서만 오탐 11건. `Button.tsx`·`page.tsx`·
+ *     `globals.css` 는 루트 파일이 아니라 **종류를 가리키는 이름**으로 쓰인다.
+ *  ⒝ **이름 좌표를 트리 전체에서 찾기** — 오탐이 문서당 2건으로 줄지만, 남은 6건이 **전부 정당한
+ *     참조**였다: 설치본(`llms.txt`·`sections.ts` → `node_modules/@zalkera/client/`), 소비처가 가질
+ *     파일(`robots.ts`·`sitemap.ts` — llms.txt 는 고객 앱을 설명한다), 남의 레포(`aeo-surface-guarantees.json`
+ *     → backend), 런타임 생성물(`robots.txt`). 즉 오탐률 100%다.
+ *
+ * D 규칙은 선언 레포에서 **error** 라 오탐 하나가 남의 빌드를 막는다. 못 잡는 좌표(루트 닷파일)의
+ * 대가는 "죽은 링크 하나"이고, 잘못 잡는 대가는 "멀쩡한 납품물 반려"다. 대칭이 아니다 — 그래서
+ * 슬래시가 있는 것만 좌표로 본다. **이 판단은 값이 아니라 비대칭에서 나온다.**
+ */
 function docPathTokens(text, only) {
     const seen = new Set();
     for (const m of text.matchAll(/`([^`\n]+)`/g)) {
         const tok = m[1];
-        if (!tok.includes("/")) continue;
+        if (!tok.includes("/")) continue; // 위 KDoc 의 실측 — 이름만 있는 토큰은 좌표가 아니다
         if (!DOC_PATH_TOKEN.test(tok)) continue;
         if (DOC_PATH_SKIP_PREFIX.some((p) => tok.startsWith(p))) continue;
         if (only && !only.test(tok)) continue;
@@ -1242,7 +1459,8 @@ function checkDocCoordinates() {
 
     const agents = join(repoRoot, "AGENTS.md");
     if (fileExists(agents)) {
-        for (const tok of docPathTokens(readFileSync(agents, "utf8"))) {
+        const agentsText = readSafe(agents, "D1 문서 좌표 검사(AGENTS.md)");
+        for (const tok of docPathTokens(agentsText ?? "")) {
             if (!fileExists(join(repoRoot, tok))) {
                 sink.push(
                     `[D1] AGENTS.md 가 없는 파일을 가리킵니다: \`${tok}\` — codegen 이 이 문서를 가장 먼저 ` +
@@ -1255,7 +1473,9 @@ function checkDocCoordinates() {
     // D2 — 본보기 레포 전용.
     let isExemplar = false;
     try {
-        isExemplar = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).name === "@zalkera/storefront-examples";
+        isExemplar =
+            JSON.parse(readSafe(join(repoRoot, "package.json"), "본보기 레포 판정") ?? "{}").name ===
+            "@zalkera/storefront-examples";
     } catch {
         isExemplar = false;
     }
@@ -1263,7 +1483,8 @@ function checkDocCoordinates() {
 
     const llms = join(repoRoot, "node_modules", "@zalkera", "client", "llms.txt");
     if (!fileExists(llms)) return; // 미설치 — 없는 것을 센 척하지 않는다.
-    for (const tok of docPathTokens(readFileSync(llms, "utf8"), /^src\/(app|components|lib)\//)) {
+    const llmsText = readSafe(llms, "D2 문서 좌표 검사(llms.txt)");
+    for (const tok of docPathTokens(llmsText ?? "", /^src\/(app|components|lib)\//)) {
         if (!fileExists(join(repoRoot, tok))) {
             sink.push(
                 `[D2] llms.txt 가 본보기로 지목한 \`${tok}\` 이 이 레포에 없습니다 — 레시피가 실물을 ` +
@@ -1318,7 +1539,10 @@ function isSeoPageFile(file) {
 
 // SEO page 에서 금지되는 per-page SSR 유발 패턴들.
 const SSR_FORBIDDEN = [
-    {re: /export\s+const\s+dynamic\s*=\s*["']force-dynamic["']/, why: `export const dynamic = "force-dynamic" (전 요청 SSR 강제)`},
+    {
+        re: /export\s+const\s+dynamic\s*=\s*["']force-dynamic["']/,
+        why: `export const dynamic = "force-dynamic" (전 요청 SSR 강제)`,
+    },
     {re: /export\s+const\s+revalidate\s*=\s*0\b/, why: `export const revalidate = 0 (ISR 무력화·매 요청 재생성)`},
     {re: /\bcookies\s*\(/, why: `page 레벨 cookies() 호출 (동적 렌더 opt-in — 세션값은 클라이언트 컴포넌트로)`},
     {re: /\bheaders\s*\(/, why: `page 레벨 headers() 호출 (동적 렌더 opt-in)`},
@@ -1326,12 +1550,155 @@ const SSR_FORBIDDEN = [
     {re: /next\s*:\s*\{[^}]*\brevalidate\s*:\s*0\b/, why: `fetch(..., { next: { revalidate: 0 } }) (ISR 무력화)`},
 ];
 
+const WALK_MAX_DEPTH = 64;
+
+/**
+ * 서빙 빌드가 **소스 복사에서 버리는** 이름들 — `build.sh` 의 `tar --exclude` 거울이다.
+ * 저쪽이 늘거나 줄면 여기도 같이 고쳐야 한다. 갈리면 "빌드엔 실리는데 검사는 안 되는" 자리가 생긴다.
+ */
+const BUILD_DROPS = new Set(["node_modules", ".next", ".git"]);
+
+/**
+ * **나무를 훑는 자리는 여기 하나다.** 파일마다 `onFile(전체경로, 이름)` 을 부른다.
+ *
+ * 종전엔 훑기가 **네 벌**이었다(`walk`·X1 의 `collect`·X3 의 `collectSources`·`collectSourceFiles`).
+ * 그래서 `walk` 하나만 고쳤을 때 나머지 셋은 옛 결함을 그대로 들고 있었다 — 같은 패치를 네 번
+ * 덧대는 대신 훑기를 하나로 모은다. 규칙마다 다른 것은 **무엇을 줍느냐**이지 **어떻게 걷느냐**가 아니다.
+ *
+ * ## 디렉터리 심링크를 만나면 — **realpath 가 어느 구역인가**로 정한다
+ *
+ * | realpath 위치 | 처분 | 왜 |
+ * | --- | --- | --- |
+ * | **소스 루트 안** | 따라가지 않음 | 그 실디렉터리는 **어차피 제 자리에서 훑는다**. 별칭으로 또 들어가면 같은 파일을 두 번 세거나, 더 나쁘게 **별칭 경로로 보고**한다 |
+ * | 레포 루트 안 · 소스 루트 밖 | **따라간다** | `src/app/shared -> ../../shared` 같은 정당한 공유 코드. 안 따라가면 그 안의 E1(시크릿)이 통째로 사라진다 |
+ * | 레포 루트 **밖** | 따라가지 않고 **적는다** | 우리 도구가 남의 파일을 대신 읽어 주지 않는다. 납품 zip 은 신뢰 밖 코드이고 `unzip` 은 심링크를 복원한다 |
+ *
+ * ⚠ **첫 칸이 이 구조의 존재 이유다.** 초판은 전역 `visited` 집합 하나로 순환만 끊었는데, 그것이
+ * **형제 별칭까지 잘라 냈다**(심의 실측): `src/aaa -> app` 이 있으면 `aaa` 를 먼저 만난 순간 실제
+ * `src/app` 의 realpath 가 이미 visited 라 **원본 가지가 통째로 스킵**되고, 파일은 `src/aaa/...` 로만
+ * 보고된다. 첫 세그먼트로 `app` 을 판정하는 규칙(C1·C1b·[isLayoutFile]·S3 배선)이 전부 침묵하고
+ * `❌ rc=1` 이 `✅ rc=0` 으로 뒤집힌다. 더 나쁜 것은 **판정이 `readdirSync` 순서에 달렸다**는 점이다 —
+ * `aaa` 는 깨지고 `zzz` 는 멀쩡했다. 관문이 비결정적이면 그것은 관문이 아니다.
+ *
+ * ⚠ 심의 초안이 제안한 "`withFileTypes` + `isDirectory()` 로 심링크를 **전부** 건너뛰기"도 채택하지
+ * 않았다 — 그러면 둘째 칸이 죽어 `src/app/shared -> ../../shared` 안의 E1 2건이 `rc=1` → `rc=0` 으로
+ * 뒤집힌다(실측). 크래시를 **빈 선반**으로 바꾸는 처방이다. 구역을 나누면 셋 다 산다.
+ *
+ * 순환은 **조상 사슬**로 끊는다(전역 집합이 아니라) — 둘째 칸을 따라간 뒤 그 안에서 되돌아오는 경우가
+ * 남기 때문이다. 깊이 상한은 최후의 안전망이지 순환 차단 수단이 아니다(상한으로 버티면 같은 위반이
+ * 64줄 찍힌다 — 실측). 그리고 **못 읽은 자리는 적는다** — 조용한 `catch {}` 는 관문에서 통과로 읽힌다.
+ *
+ * @param dir 시작 디렉터리. 없으면(ENOENT/ENOTDIR) 조용히 끝난다 — 선택적 디렉터리가 많다.
+ * @param onFile 파일마다 불린다. 디렉터리 판단·순환 차단은 여기서 신경 쓸 필요가 없다.
+ * @param what 못 읽었을 때 사람에게 보일 말("X1 라우트 수집" 처럼 **어느 검사가** 못 돌았는지).
+ */
+function walkTree(dir, onFile, what) {
+    const step = (d, depth, ancestors) => {
+        if (depth > WALK_MAX_DEPTH) {
+            markUnmeasured(d, "EDEPTH", `디렉터리 깊이 ${WALK_MAX_DEPTH} 초과 — ${what}`);
+            return;
+        }
+        let names;
+        try {
+            names = readdirSync(d);
+        } catch (e) {
+            // 없는 디렉터리는 "못 잰 것"이 아니다 — 선택적 좌표가 대부분이다.
+            if (e.code !== "ENOENT" && e.code !== "ENOTDIR") markUnmeasured(d, e.code, what);
+            return;
+        }
+        for (const name of names) {
+            const full = join(d, name);
+            // **빌드가 버리는 것만 건너뛴다 — 그 밖은 전부 훑는다.**
+            //
+            // ⚠ 종전엔 이 셋을 **깊이 무관하게 이름으로** 건너뛰었다. 그런데 서빙 복사는 최상위만
+            // 버린다(`build.sh`: `tar --exclude='./node_modules' --exclude='./.next' --exclude='./.git'`
+            // — `./` 접두가 최상위에 못박는다). 즉 `src/app/node_modules/widget.tsx` 는 **빌드에 실제로
+            // 실리는데 검사기만 안 봤다.** 심의 실측: 같은 E1 위반이 정상 위치에서는 관문 exit 1,
+            // `node_modules` 라는 이름의 평범한 디렉터리 안에서는 exit 5(next build 까지 진행).
+            // 디렉터리 이름 한 칸만 바꾸면 세 관문(서빙·납품검수·CI)이 동시에 열렸다.
+            //
+            // 그래서 판정을 이름이 아니라 **자리**로 한다: 레포 루트 바로 아래의 그 셋만 건너뛴다.
+            // 그 아래 것은 빌드에 실리므로 검사 대상이다 — 잣대가 "번들에 들어가는가"이지
+            // "이름이 무엇인가"가 아니다. (`.git` 은 비용 때문에도 뺀다 — 심의 실측 +59%.)
+            if (BUILD_DROPS.has(name) && dirname(full) === repoRootDir) continue;
+            let stat;
+            try {
+                stat = statSync(full);
+            } catch (e) {
+                // 끊어진 심링크·권한 없는 자리. 종전엔 여기서 **스택트레이스로 죽었다.**
+                markUnmeasured(full, e.code, `파일 정보 — ${what}`);
+                continue;
+            }
+            if (!stat.isDirectory()) {
+                onFile(full, name);
+                continue;
+            }
+            // 심링크가 아니면 realpath 를 물을 이유가 없다 — `realpathSync` 는 `statSync` 의 **11.5배**
+            // 이고 **경로 깊이에 선형**이라(심의 실측: depth2 17us → depth64 281us) 디렉터리가 많은
+            // 트리에서 총비용이 제곱으로 번진다. 실디렉터리는 부모의 실경로에 이름만 붙이면 된다.
+            let real = join(currentReal(ancestors), name);
+            if (isSymlink(full)) {
+                try {
+                    real = realpathSync(full);
+                } catch (e) {
+                    // ⚠ **이 줄에는 회귀 시험이 없다 — 도달 형상을 못 만들었다.** 바로 위 `statSync` 가
+                    // 이미 전체 경로를 해석하므로, 여기까지 왔으면 realpath 도 대개 성공한다(끊어진
+                    // 심링크·ELOOP·권한 부족은 전부 statSync 에서 먼저 잡힌다 — 실측). 남는 것은 훑는
+                    // 도중 트리가 바뀌는 경합뿐이라 시험으로 고정할 수 없다.
+                    // 그래서 이 줄은 **심층방어**다. 없는 커버리지를 있다고 적지 않기 위해 여기 적는다.
+                    markUnmeasured(full, e.code, `실경로 해석 — ${what}`);
+                    continue;
+                }
+                // ⓐ 소스 루트 안 — 따라가지 않는다. 그 실디렉터리는 제 자리에서 훑는다.
+                if (within(real, root)) continue;
+                // ⓑ 레포 밖 — 따라가지 않고 적는다. 못 잰 것이지 통과가 아니다.
+                if (!within(real, repoRootDir)) {
+                    markUnmeasured(full, "EXDEV", `레포 밖을 가리키는 심링크라 따라가지 않았습니다 — ${what}`);
+                    continue;
+                }
+            }
+            if (ancestors.has(real)) continue; // 조상으로 되돌아가는 순환
+            step(full, depth + 1, new Set(ancestors).add(real));
+        }
+    };
+    let rootReal;
+    try {
+        rootReal = realpathSync(dir);
+    } catch (e) {
+        // 시작 좌표의 부재는 정상(선택적 디렉터리가 많다). 그 밖의 사유는 적는다.
+        if (e.code !== "ENOENT" && e.code !== "ENOTDIR") markUnmeasured(dir, e.code, what);
+        return;
+    }
+    step(dir, 0, new Set([rootReal]));
+}
+
+/** `p` 가 `base` 와 같거나 그 아래인가. 경로 문자열이 아니라 **경계**를 묻는다. */
+function within(p, base) {
+    if (p === base) return true;
+    const rel = relative(base, p);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/** 심링크인가. `lstatSync` 는 따라가지 않는다. 못 물으면 아니라고 답한다(뒤의 `statSync` 가 잡는다). */
+function isSymlink(p) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    } catch {
+        return false;
+    }
+}
+
+/** 현재 하강 사슬의 끝 = 지금 디렉터리의 실경로. Set 은 삽입 순서를 지킨다. */
+function currentReal(ancestors) {
+    let last;
+    for (const a of ancestors) last = a;
+    return last;
+}
+
 function walk(dir) {
-    for (const name of readdirSync(dir)) {
-        if (name === "node_modules" || name === ".next") continue;
-        const full = join(dir, name);
-        if (statSync(full).isDirectory()) {
-            walk(full);
+    walkTree(
+        dir,
+        (full, name) => {
             // ⚠ **관문 대가가 있다**(심의 실측): `.mjs` 를 훑으면서 `preview-runner --gate` 의 종료코드가
             // **0 → 1** 로 바뀐다(`[E3]` 예시 키 `oqsk_test_…` 를 오류층으로 잡는다). 실제 서빙 코퍼스는
             // rc=0 을 유지해 오늘의 폭발반경은 0 이지만, **발행이 남의 관문 계약을 바꾼다**는 사실은
@@ -1343,13 +1710,15 @@ function walk(dir) {
             // ⚠ `.mjs`·`.cjs` 도 훑는다. 종전엔 빠져 있어 **그 파일에서는 규칙이 아예 안 돌았다**
             // (심의 관찰 — 검사기가 조용한 것이지 안전한 것이 아니다). Next 설정·서버 유틸이 그 확장자로
             // 오는 레포가 있다.
-        } else if (/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(name)) {
-            check(full);
-            if (isLayoutFile(full)) layoutFiles.push(full);
-        } else if (name.endsWith(".css")) {
-            cssFiles.push(full);
-        }
-    }
+            if (/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(name)) {
+                check(full);
+                if (isLayoutFile(full)) layoutFiles.push(full);
+            } else if (name.endsWith(".css")) {
+                cssFiles.push(full);
+            }
+        },
+        "소스 파일 수집(규약 검사 본체)",
+    );
 }
 
 // ── C1b: layout 폭발반경 게이트 ──────────────────────────────────
@@ -1372,7 +1741,10 @@ function isLayoutFile(file) {
     if (!/^(layout|template)\.(ts|tsx|js|jsx)$/.test(basename(file))) return false;
     const segments = relative(root, file).split(sep);
     if (segments[0] !== "app") return false;
-    return !segments.slice(1, -1).map(normalizeSegment).some((s) => SEO_EXCLUDE_SEGMENTS.has(s));
+    return !segments
+        .slice(1, -1)
+        .map(normalizeSegment)
+        .some((s) => SEO_EXCLUDE_SEGMENTS.has(s));
 }
 
 /**
@@ -1409,7 +1781,32 @@ const DYNAMIC_API = [
  * (SiteHeader 주석이 정확히 그렇다). `//` 는 URL(`http://`)과 구분하려고 앞 문자가 `:` 이 아닐 때만.
  */
 function stripComments(src) {
-    return src.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/(^|[^:])\/\/[^\n]*/g, "$1 ");
+    // ⚠ 종전엔 `src.replace(/\/\*[\s\S]*?\*\//g, " ")` 였다. **닫히지 않은 `/*` 가 많은 파일에서
+    // 2차로 폭발한다** — 오프너마다 파일 끝까지 훑고 실패한 뒤 한 칸 전진해 다시 훑는다.
+    // 실측(심의 성능축 F5): 배증할 때마다 4배 — 15KB 17.6ms · 30KB 103ms · 60KB 275ms ·
+    // 120KB 1320ms, 검사기 전체로는 240KB 17.6초 · 600KB 110초. 이 레포는 이미 두 번 ReDoS 를
+    // 냈고 `REGEX_SCAN_CAP` 으로 옆 자리를 막아 뒀는데, **상한 없는 형제가 그대로 남아 있었다.**
+    //
+    // 선형 스캐너로 바꾸되 **의미는 종전과 같다**: 닫는 `*/` 가 없으면 그 `/*` 는 주석으로 치지
+    // 않고 원문을 남긴다(정규식이 닫힘을 요구했으므로 같은 결과다). 뒤에 `*/` 가 하나도 없으면
+    // 그 뒤의 어떤 `/*` 도 닫힐 수 없으므로 거기서 멈추는 것이 안전하다.
+    let out = "";
+    let i = 0;
+    for (;;) {
+        const open = src.indexOf("/*", i);
+        if (open === -1) {
+            out += src.slice(i);
+            break;
+        }
+        const close = src.indexOf("*/", open + 2);
+        if (close === -1) {
+            out += src.slice(i); // 미종료 — 원문 유지(종전 정규식과 동일)
+            break;
+        }
+        out += src.slice(i, open) + " ";
+        i = close + 2;
+    }
+    return out.replace(/(^|[^:])\/\/[^\n]*/g, "$1 ");
 }
 
 /**
@@ -1548,7 +1945,9 @@ function checkLayoutBlastRadius() {
 
             // 면제는 **범인 파일**에 붙인다 — layout 에 붙이면 그 아래 전부가 한 번에 뚫린다.
             // 신 마커 zalkera- + 구 마커(oneq-/oneque-)를 양형 수용한다(리네임 이행기).
-            const allow = readFileSync(file, "utf8").match(/\/\/\s*(?:zalkera|oneque?)-allow-dynamic:\s*(.+)/);
+            const allow = (readSafe(file, "C1b 면제 마커 판독") ?? "").match(
+                /\/\/\s*(?:zalkera|oneque?)-allow-dynamic:\s*(.+)/,
+            );
             const path = chain.map((f) => relative(process.cwd(), f)).join(" → ");
             const detail =
                 `${relative(process.cwd(), layout)} 이 ${why} 에 도달한다 → ${path}. ` +
@@ -1590,12 +1989,10 @@ function checkThemeWiring() {
     if (STYLE_MODE !== "declared") return; // 선언 없는 레포의 주입 부재는 결함이 아니라 정상이다.
 
     const globalsCss = join(root, "app", "globals.css");
-    let css = null;
-    try {
-        css = readFileSync(globalsCss, "utf8");
-    } catch {
-        return; // 파일 부재는 S3 가 이미 error 로 잡는다 — 같은 사실을 두 번 외치지 않는다.
-    }
+    // 부재는 S3 가 이미 error 로 잡는다(같은 사실을 두 번 외치지 않는다). 그러나 **있는데 못 읽는 것**은
+    // 다른 사실이고, 조용히 return 하면 S8 이 통째로 사라진 채 ✅ 가 난다(심의 실측).
+    const css = readSafe(globalsCss, "S8 테마 토큰 검사(globals.css)");
+    if (css === null) return;
 
     // S8-a — 토큰 정의.
     if (!/@theme\b/.test(css) || !/--color-primary\s*:/.test(css)) {
@@ -1617,7 +2014,8 @@ function checkThemeWiring() {
         });
     if (!rootLayout) return; // root layout 부재는 C1 계열의 몫.
 
-    const raw = readFileSync(rootLayout, "utf8");
+    const raw = readSafe(rootLayout, "테마 주입 배선 검사(root layout)");
+    if (raw === null) return;
     const src = stripComments(raw); // 주석은 거짓말을 한다 — 앵커를 코드에서만 찾는다.
     const injects = /parseThemeColors\s*\(/.test(src) && /<html[^>]*\sstyle=/.test(src);
     if (injects) return;
@@ -1644,12 +2042,9 @@ function checkSectionCoverage() {
     if (!Array.isArray(contract) || contract.length === 0) return;
 
     const rendererPath = join(root, "components/sections/SectionRenderer.tsx");
-    let src;
-    try {
-        src = readFileSync(rendererPath, "utf8");
-    } catch {
-        return; // 렌더러가 없는 구조(BYO) — 검사 대상 아님.
-    }
+    // 렌더러가 없는 구조(BYO)는 검사 대상이 아니다. 못 읽는 것은 그것과 다른 사실이다.
+    const src = readSafe(rendererPath, "섹션 렌더러 계약 검사");
+    if (src === null) return;
     const cases = new Set([...src.matchAll(/case\s+"([A-Z_]+)"/g)].map((m) => m[1]));
     const missing = contract.map((c) => c.type).filter((t) => !cases.has(t));
     if (missing.length > 0) {
@@ -1746,10 +2141,10 @@ function checkContentContract() {
 
     // N1 — 매니페스트. 정적 import 가 없으면 HMR 도 standalone 트레이싱도 없다(계약 rev 4 `contentFile.manifest`).
     const manifestPath = join(repoRoot, "content", "index.ts");
-    let manifest = null;
-    try {
-        manifest = readFileSync(manifestPath, "utf8");
-    } catch {
+    // ⚠ 종전엔 EACCES 도 "없습니다"로 보고했다 — 있는데 못 읽는 것을 부재로 말하면 고칠 자리가 어긋난다.
+    const manifest = readSafe(manifestPath, "N1 콘텐츠 매니페스트");
+    if (manifest === null && existsSync(manifestPath)) return; // 못 읽음은 markUnmeasured 가 적었다
+    if (manifest === null) {
         sink.push(
             `[N1] ${rel(manifestPath)} 가 없습니다 — 콘텐츠 매니페스트(정적 import)가 없으면 ` +
                 `dev 에서 json 을 고쳐도 화면이 안 바뀌고(HMR 미발화), 빌드 산출물에 콘텐츠가 안 실립니다.`,
@@ -1761,9 +2156,7 @@ function checkContentContract() {
     // import 로 읽으면 없는 파일을 찾는 오탐이 난다(실제로 이 검사를 넣자마자 그렇게 죽었다).
     // 이 레포가 C1b·S8 에서 이미 밟은 함정과 같은 것이라 같은 처방을 쓴다.
     const declaredSlugs = manifest
-        ? new Set(
-              [...stripComments(manifest).matchAll(/from\s+["']\.\/pages\/([\w-]+)\.json["']/g)].map((m) => m[1]),
-          )
+        ? new Set([...stripComments(manifest).matchAll(/from\s+["']\.\/pages\/([\w-]+)\.json["']/g)].map((m) => m[1]))
         : null;
     if (declaredSlugs) {
         for (const file of files) {
@@ -1777,7 +2170,9 @@ function checkContentContract() {
         }
         for (const slug of declaredSlugs) {
             if (!files.some((f) => basename(f, ".json") === slug)) {
-                sink.push(`[N3] ${rel(manifestPath)} 가 import 하는 content/pages/${slug}.json 이 없습니다 — 빌드가 깨집니다.`);
+                sink.push(
+                    `[N3] ${rel(manifestPath)} 가 import 하는 content/pages/${slug}.json 이 없습니다 — 빌드가 깨집니다.`,
+                );
             }
         }
     }
@@ -1786,15 +2181,19 @@ function checkContentContract() {
     warnIfContractMissing(contract);
 
     for (const file of files) {
+        const pageText = readSafe(file, "N2 콘텐츠 페이지 판독");
+        if (pageText === null) continue; // 못 읽음은 파싱 실패가 아니다
         let page;
         try {
-            page = JSON.parse(readFileSync(file, "utf8"));
+            page = JSON.parse(pageText);
         } catch (e) {
             sink.push(`[N2] ${rel(file)}: JSON 파싱 실패 — ${e.message}`);
             continue;
         }
         if (page == null || typeof page !== "object" || Array.isArray(page)) {
-            sink.push(`[N2] ${rel(file)}: 최상위가 객체여야 합니다(현재 ${Array.isArray(page) ? "배열" : typeof page}).`);
+            sink.push(
+                `[N2] ${rel(file)}: 최상위가 객체여야 합니다(현재 ${Array.isArray(page) ? "배열" : typeof page}).`,
+            );
             continue;
         }
 
@@ -1811,7 +2210,9 @@ function checkContentContract() {
                 continue;
             }
             if (typeof section.type !== "string" || section.type.trim() === "") {
-                sink.push(`[N4] ${at}: type 은 비어 있지 않은 문자열이어야 합니다 — 렌더러가 이 섹션을 통째로 건너뜁니다.`);
+                sink.push(
+                    `[N4] ${at}: type 은 비어 있지 않은 문자열이어야 합니다 — 렌더러가 이 섹션을 통째로 건너뜁니다.`,
+                );
                 continue;
             }
             if ("sortOrder" in section) {
@@ -1847,7 +2248,12 @@ function checkContentContract() {
                     sink.push(`[N5] ${at}: "${path}" 는 public 루트 절대 경로 문자열이어야 합니다.`);
                     continue;
                 }
-                if (!value.startsWith("/") || value.startsWith("//") || value.includes("\\") || value.split("/").includes("..")) {
+                if (
+                    !value.startsWith("/") ||
+                    value.startsWith("//") ||
+                    value.includes("\\") ||
+                    value.split("/").includes("..")
+                ) {
                     sink.push(
                         `[N5] ${at}: "${path}" = ${JSON.stringify(value)} — 레포 public/ 루트 절대 경로만 그려집니다` +
                             `(원격 URL·상대 경로·경로 탈출은 렌더에서 통째로 떨어집니다).`,
@@ -1857,7 +2263,9 @@ function checkContentContract() {
                 try {
                     statSync(join(repoRoot, "public", value));
                 } catch {
-                    sink.push(`[N5] ${at}: "${path}" 가 가리키는 public${value} 파일이 없습니다 — 개시하면 깨진 이미지입니다.`);
+                    sink.push(
+                        `[N5] ${at}: "${path}" 가 가리키는 public${value} 파일이 없습니다 — 개시하면 깨진 이미지입니다.`,
+                    );
                 }
             }
             // N5 — 계약 필수 참조.
@@ -1894,7 +2302,15 @@ function checkContentContract() {
 }
 
 function check(file) {
-    const src = readFileSync(file, "utf8");
+    let src;
+    try {
+        src = readFileSync(file, "utf8");
+    } catch (e) {
+        // 권한 없는 파일. 종전엔 여기서 스택트레이스로 죽었다(심의 처방이 못 닫은 자리 — 그 처방은
+        // `readdirSync` 축만 봤다).
+        markUnmeasured(file, e.code, "파일 읽기");
+        return;
+    }
     const rel = relative(process.cwd(), file);
     // ⚠ **파일 머리만 본다(심의 차단 4).** 종전은 `/m` 플래그로 **원문 전체의 행머리**를 봤고,
     //    행머리에 `"use client"` 를 담은 **템플릿 리터럴 한 줄**이 있으면 SEO 페이지가 클라이언트로
@@ -1907,14 +2323,17 @@ function check(file) {
     // 서버 클라이언트 싱글턴 존재 확인 — create{Zalkera,Oneque}Client 호출(구 심볼 수용).
     if (/create(?:Zalkera|Oneque)Client\s*\(/.test(src)) {
         singletonFound = true;
-        if (isClient) servingSink().push(`[E1] ${rel}: "use client" 파일에서 createZalkeraClient 를 만든다 — baseUrl 노출.`);
+        if (isClient)
+            servingSink().push(`[E1] ${rel}: "use client" 파일에서 createZalkeraClient 를 만든다 — baseUrl 노출.`);
     }
 
     if (isClient) {
         // E1: 값 import(= import type 아님)로 @zalkera/client 를 들여옴(구 @oneque/client 도 잡는다).
         const valueImport = /^import\s+(?!type\s)[^;]*from\s+["']@(?:zalkera|oneque)\/client["']/m.test(src);
         if (valueImport) {
-            servingSink().push(`[E1] ${rel}: "use client" 파일에서 @zalkera/client 를 값으로 import 한다 (타입은 \`import type\` 으로).`);
+            servingSink().push(
+                `[E1] ${rel}: "use client" 파일에서 @zalkera/client 를 값으로 import 한다 (타입은 \`import type\` 으로).`,
+            );
         }
         // E2: 서버 싱글턴(lib/zalkera) import(구 lib/oneque 도 잡는다).
         if (/from\s+["'][^"']*lib\/(?:zalkera|oneque)["']/.test(src)) {
@@ -2065,8 +2484,9 @@ function checkStyleWiring() {
                     }
                 });
             if (rootLayout) {
-                const src = stripComments(readFileSync(rootLayout, "utf8"));
-                if (!/import\s+["'][^"']*globals\.css["']/.test(src)) {
+                const layoutText = readSafe(rootLayout, "S3 globals.css import 검사");
+                const src = stripComments(layoutText ?? "");
+                if (layoutText !== null && !/import\s+["'][^"']*globals\.css["']/.test(src)) {
                     s3.push(
                         `[S3] ${relative(process.cwd(), rootLayout)} 이 globals.css 를 import 하지 않습니다 ` +
                             `(\`import "./globals.css"\`). 배선이 없으면 Tailwind CSS·테마 토큰이 로드되지 않습니다.`,
@@ -2285,7 +2705,11 @@ function findMutationHandlers(code) {
     // ⒞ `export {POST}` · `export {handler as POST}` — 본문을 못 따라간다.
     for (const m of code.matchAll(/export\s*\{([^}]*)\}/g)) {
         for (const part of m[1].split(",")) {
-            const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+            const name = part
+                .trim()
+                .split(/\s+as\s+/)
+                .pop()
+                ?.trim();
             if (name && new RegExp(`^(${METHODS})$`).test(name)) push(name, null);
         }
     }
@@ -2374,22 +2798,17 @@ function judgeGuardPlacement(rawBody) {
 // 로 쓰면 플랫폼 존에서 형제 테넌트가 통과한다.
 function checkCrossOriginGuards() {
     const routes = [];
-    const collect = (dir) => {
-        let entries;
-        try {
-            entries = readdirSync(dir, {withFileTypes: true});
-        } catch {
-            return;
-        }
-        for (const e of entries) {
-            const full = join(dir, e.name);
-            if (e.isDirectory()) collect(full);
-            // ⚠ `route.js`·`.jsx`·`.mjs` 도 라우트다. 종전엔 `.ts`·`.tsx` 만 봐서 **가드 규칙(X1)이
-            // 그 파일들에서 통째로 침묵**했다(I2 는 도는데 X1 만 안 도는 비대칭 · 심의 실측).
-            // 구식인 Pages Router 쪽(X1p)이 오히려 `.js` 를 보고 있었다.
-            else if (/^route\.(ts|tsx|js|jsx|mjs|cjs)$/.test(e.name)) routes.push(full);
-        }
-    };
+    const collect = (dir) =>
+        walkTree(
+            dir,
+            (full, name) => {
+                // ⚠ `route.js`·`.jsx`·`.mjs` 도 라우트다. 종전엔 `.ts`·`.tsx` 만 봐서 **가드 규칙(X1)이
+                // 그 파일들에서 통째로 침묵**했다(I2 는 도는데 X1 만 안 도는 비대칭 · 심의 실측).
+                // 구식인 Pages Router 쪽(X1p)이 오히려 `.js` 를 보고 있었다.
+                if (/^route\.(ts|tsx|js|jsx|mjs|cjs)$/.test(name)) routes.push(full);
+            },
+            "X1 라우트 수집(교차출처 가드)",
+        );
     // ⚠ `root` 는 **레포 루트가 아니라 소스 루트**(`./src`)다(82행). 초판은 `src/app/api` 도
     // 함께 걸었는데 그건 `./src/src/app/api` 라 존재하지 않는 죽은 경로였다.
     //
@@ -2401,12 +2820,13 @@ function checkCrossOriginGuards() {
 
     const exempted = [];
     for (const file of routes) {
-        const code = readFileSync(file, "utf8");
+        const code = readSafe(file, "X1 교차출처 가드 검사");
+        if (code === null) continue;
         const rel = relative(root, file);
         // ⚠ **가드 축(X1·X1p)만 JSX 강등을 끈다.** JSX 파일에서 낱말 뒤 정규식을 나눗셈으로 두면
-            // 그 안의 백틱이 살아나 파일을 삼켜 **가드가 안 보인다**(미탐). 산문 삼킴은 I2·X3 축에만
-            // 해로우므로, 두 축을 갈라 각각에 맞는 사본을 준다(심의 처방 · 미탐 4·오탐 2 동시 해소).
-            const handlers = findMutationHandlers(stripLiterals(code, false));
+        // 그 안의 백틱이 살아나 파일을 삼켜 **가드가 안 보인다**(미탐). 산문 삼킴은 I2·X3 축에만
+        // 해로우므로, 두 축을 갈라 각각에 맞는 사본을 준다(심의 처방 · 미탐 4·오탐 2 동시 해소).
+        const handlers = findMutationHandlers(stripLiterals(code, false));
         if (!handlers.length) continue;
 
         // 면제 마커는 **파일 상단**에만 둔다 — 아무 데나 허용하면 주석·문자열 안의 한 줄로
@@ -2441,7 +2861,8 @@ function checkCrossOriginGuards() {
 
     // X2 — 읽기 GET 면제는 "CORS 헤더가 없다"에 의존한다. 그 전제가 깨지면 면제도 깨진다.
     for (const file of routes) {
-        const code = readFileSync(file, "utf8");
+        const code = readSafe(file, "X2 CORS 헤더 검사");
+        if (code === null) continue;
         if (/Access-Control-Allow-Origin/i.test(code)) {
             crossOriginSink().push(
                 `[X2] ${relative(root, file)} 가 CORS 헤더를 답니다 — 읽기 GET 을 가드에서 빼는 근거가` +
@@ -2460,25 +2881,19 @@ function checkCrossOriginGuards() {
     //    **fail-open** 했다(심의 실측: 소각 삭제 + 리네임 = 통과). `./src/src/app/api` 이후
     //    좌표가 죽어 검사가 사라진 **세 번째 사례**라 정의를 찾아가는 쪽으로 바꾼다.
     const sources = [];
-    const collectSources = (dir) => {
-        let entries;
-        try {
-            entries = readdirSync(dir, {withFileTypes: true});
-        } catch {
-            return;
-        }
-        for (const e of entries) {
-            const full = join(dir, e.name);
-            if (e.isDirectory()) collectSources(full);
-            else if (/\.tsx?$/.test(e.name)) sources.push(full);
-        }
-    };
-    collectSources(root);
+    walkTree(
+        root,
+        (full, name) => {
+            if (/\.tsx?$/.test(name)) sources.push(full);
+        },
+        "X3 소스 수집(OAuth state 소각)",
+    );
 
     let consumeDef = null;
     let usesStateCookie = false;
     for (const file of sources) {
-        const raw = readFileSync(file, "utf8");
+        const raw = readSafe(file, "파일 읽기");
+        if (raw === null) continue;
         const src = stripLiterals(raw, holdsJsx(file, raw)); // X3 — 산문 삼킴을 막아야 하는 축
         if (/\bconsumeOAuthState\s*\(/.test(src)) usesStateCookie = true;
         // 정의 형태를 묻지 않는다 — function 선언·화살표 상수 둘 다.
@@ -2567,20 +2982,15 @@ function pagesRoot() {
     return null;
 }
 
-/** 디렉터리 아래 소스 파일 전량(재귀). `node_modules`·`.next` 는 건너뛴다. */
+/** 디렉터리 아래 소스 파일 전량(재귀). 걷는 규율은 [walkTree] 하나에 모여 있다. */
 function collectSourceFiles(dir, into = []) {
-    let entries;
-    try {
-        entries = readdirSync(dir, {withFileTypes: true});
-    } catch {
-        return into;
-    }
-    for (const e of entries) {
-        if (e.name === "node_modules" || e.name === ".next") continue;
-        const full = join(dir, e.name);
-        if (e.isDirectory()) collectSourceFiles(full, into);
-        else if (/\.(ts|tsx|js|jsx|mjs)$/.test(e.name)) into.push(full);
-    }
+    walkTree(
+        dir,
+        (full, name) => {
+            if (/\.(ts|tsx|js|jsx|mjs)$/.test(name)) into.push(full);
+        },
+        "C1p·X1p 소스 수집(Pages Router 축)",
+    );
     return into;
 }
 
@@ -2602,7 +3012,8 @@ function checkPagesRouter() {
 
     for (const file of collectSourceFiles(pagesDir)) {
         const rel = relative(process.cwd(), file);
-        const raw = readFileSync(file, "utf8");
+        const raw = readSafe(file, "파일 읽기");
+        if (raw === null) continue;
         const text = stripComments(raw);
         const stem = basename(file).replace(/\.[^.]+$/, "");
 
@@ -2680,16 +3091,18 @@ function checkEnvFiles() {
     let names;
     try {
         names = readdirSync(repoRoot).filter((n) => n === ".env" || n.startsWith(".env."));
-    } catch {
+    } catch (e) {
+        // 레포 루트를 못 읽으면 E3 가 **한 줄도 안 돈다.** 조용히 return 하면 ✅ 가 난다.
+        if (e.code !== "ENOENT" && e.code !== "ENOTDIR") markUnmeasured(repoRoot, e.code, "E3 환경파일 스캔");
         return;
     }
     for (const name of names.sort()) {
-        let lines;
-        try {
-            lines = readFileSync(join(repoRoot, name), "utf8").split("\n");
-        } catch {
-            continue;
-        }
+        // ⚠ 여기가 E3 의 **다른 절반**이다. 디렉터리는 읽히는데 파일이 안 읽히는 경우가 있고, 종전엔
+        // 그때 조용히 `continue` 해서 **시크릿을 한 줄도 안 보고 `✅ 통과`** 가 났다(심의 셋이 모두 지목).
+        // 디렉터리 읽기만 고치고 파일 읽기를 남겨 두면 같은 구멍이 그대로다 — 실제로 한 번 그랬다.
+        const text = readSafe(join(repoRoot, name), `E3 환경파일 판독(${name})`);
+        if (text === null) continue;
+        const lines = text.split("\n");
         for (const line of lines) {
             if (/^\s*#/.test(line)) continue; // 주석 — `.env.example` 이 금지 규약을 문장으로 적어 뒀다.
             const m = line.match(PUBLIC_SECRET_ENV);
@@ -2744,12 +3157,9 @@ function checkServingOutputContract() {
     // 설정 파일이 여럿이면 어느 것이 유효한지 Next 의 해석 순서에 달렸다 — 못 가르는 자리라 스킵한다.
     if (found.length !== 1) return;
 
-    let text;
-    try {
-        text = stripComments(readFileSync(found[0], "utf8"));
-    } catch {
-        return;
-    }
+    const configText = readSafe(found[0], "O1 서빙 산출물 계약 검사(next.config)");
+    if (configText === null) return;
+    const text = stripComments(configText);
     if (!isStaticallyReadableConfig(text)) return; // 동적 조립 — 잠자코 스킵.
 
     const name = basename(found[0]);
@@ -2773,8 +3183,16 @@ function checkServingOutputContract() {
     servingOutputSink().push(`[O1] ${name}: output 설정이 없습니다 — ${advice}`);
 }
 
+// ⚠ `statSync` 만으로는 **파일을 소스 루트로 준 경우**를 못 가른다. `walkTree` 는 시작 좌표의
+// ENOTDIR 를 "선택적 하위 디렉터리 부재"로 관용하므로, 그대로 두면 훑을 것이 0개인 채 `✅ rc=0` 으로
+// 끝난다(심의 실측 — 구판은 크래시로나마 관문을 닫았다). 선택은 하위 좌표의 성질이지 시작 좌표의
+// 성질이 아니다. 여기서 틀리면 **검사를 한 줄도 안 돌고 통과**가 난다.
 try {
-    statSync(root);
+    if (!statSync(root).isDirectory()) {
+        console.error(`디렉터리가 아닙니다(소스 디렉터리를 주십시오 · 보통 ./src): ${root}`);
+        console.error(`검사를 시작하지 못했습니다 — 통과가 아닙니다.`);
+        process.exit(2);
+    }
 } catch {
     console.error(`디렉터리를 찾을 수 없습니다: ${root}`);
     process.exit(2);
@@ -2827,7 +3245,8 @@ function checkManualCarrier() {
 
 checkManualCarrier(); // W-LLMS — zip 이 나르는 명세가 설치본과 같은가(fail-soft).
 
-if (!singletonFound) warnings.push(`[W1] createZalkeraClient 싱글턴을 찾지 못했습니다 — 서버 사이드 호출 패턴이 있는지 확인하세요.`);
+if (!singletonFound)
+    warnings.push(`[W1] createZalkeraClient 싱글턴을 찾지 못했습니다 — 서버 사이드 호출 패턴이 있는지 확인하세요.`);
 
 console.log(
     `스타일 규약 모드: ${STYLE_MODE}` +
@@ -2848,8 +3267,50 @@ console.log(
 for (const w of warnings) console.warn("⚠️  " + w);
 for (const e of errors) console.error("❌ " + e);
 
+// ── 못 잰 것 — 통과도 위반도 아닌 셋째 칸 ───────────────────────────────
+//
+// 문면은 `build.sh` §exit4 의 2층 관례를 그대로 쓴다: 첫 줄은 **업로더가 할 수 있는 일**,
+// 다음 줄은 개발자·LLM 에 그대로 붙여넣을 지시. 종전엔 이 자리가 스택트레이스이거나 침묵이었다.
+// 같은 파일이 여러 검사에서 걸리면 줄이 그만큼 늘어난다 — 사람에게는 **자리 수**가 정보다.
+// 자리별로 접고, 어느 검사가 사라졌는지는 그 아래에 모은다.
+const unmeasuredByPath = new Map();
+for (const u of unmeasured) {
+    const key = `${u.path}|${u.code}`;
+    if (!unmeasuredByPath.has(key)) unmeasuredByPath.set(key, {...u, whats: new Set()});
+    unmeasuredByPath.get(key).whats.add(u.what);
+}
+
+if (unmeasuredByPath.size > 0) {
+    const say = GATE_MODE ? console.error : console.warn;
+    const mark = GATE_MODE ? "❌" : "⚠️ ";
+    say(`\n${mark} 읽지 못한 자리 ${unmeasuredByPath.size}곳 — 이 자리들은 **검사하지 않았습니다(통과가 아닙니다).**`);
+    say(`   이 소스를 만든 개발자에게 아래 줄을 그대로 전달하십시오.`);
+    for (const u of unmeasuredByPath.values()) {
+        say(`   · ${u.path} [${u.code}] — 못 돈 검사: ${[...u.whats].join(" · ")}`);
+    }
+    if (GATE_MODE) {
+        // 관문 fail-closed. 오탐 비용을 0 이라고 적었던 종전 주석은 **거짓이었다**(심의 실측): 서빙
+        // 복사는 `tar --no-same-owner` 라 소유권만 정규화하고 **모드는 보존**하며, 빌더는 `--cap-drop ALL`
+        // 이라 root 라도 DAC_OVERRIDE 가 없어 EACCES 가 실제로 난다. 그래도 닫는 것이 맞다 — 이유가
+        // "안 뜬다"가 아니라 **"못 잰 것을 통과로 세지 않는다"** 이기 때문이다.
+        console.error(`\n검사를 끝내지 못했습니다. rc=7(검사 불능) — 규약 위반(rc=1)과 다른 뜻입니다.`);
+        process.exit(7);
+    }
+}
+
 if (errors.length > 0) {
     console.error(`\n${errors.length}개 오류. 스토어프론트 규약 위반을 고치세요 (llms.txt §5 참고).`);
     process.exit(1);
 }
-console.log(`✅ 통과 — 검사한 규약 위반 없음${warnings.length ? ` (경고 ${warnings.length})` : ""}.`);
+// ⚠ **못 잰 것을 요약 줄에 합친다.** 권고 모드에서는 위의 고지 **뒤에** 이 줄이 찍히므로, 여기서
+// 침묵하면 사람이 마지막에 본 `✅ 통과` 만 기억한다(심의 지적 — verify-zip 커밋이 스스로 적은
+// "사람은 ✅ 를 기억한다"의 더 나쁜 판이다. 거기서는 ✅ 가 위에 있었고 여기서는 아래에 있다).
+const tally = [
+    warnings.length ? `경고 ${warnings.length}` : "",
+    unmeasuredByPath.size ? `못 잰 자리 ${unmeasuredByPath.size}` : "",
+]
+    .filter(Boolean)
+    .join(" · ");
+console.log(
+    `✅ ${unmeasuredByPath.size ? "잰 범위에서는 통과" : "통과"} — 검사한 규약 위반 없음${tally ? ` (${tally})` : ""}.`,
+);