data-sanity

name	data-sanity
description	Layer C of spectra pre-handoff quality gates. Static audit for the data-shape failure class where a client query param literal violates the server zod schema bound (e.g. perPage: 200 vs max(100)) → silent 4xx → lookup map empties → admin list column collapses to a uniform fallback. Use when running /spectra-apply Design Review, before /spectra-archive, or ad-hoc on any change that touches paginated queries + lookup-resolved columns.
effort	medium
metadata	{"author":"clade","version":"1.0"}

/data-sanity — Layer C static data-shape audit.

Born from perno app-status-badge-extraction（2026-05-24）: attendance/amendments.vue 用 useEmployeeListQuery({ perPage: 200 })，但 server schema 是 perPage: z....max(100) → API 400 → employeeNameMap empty → 員工 column 整列「-」。typecheck / lint / design review / verify:ui 全沒抓到，因為它是資料形狀問題，不是型別或視覺問題。

這是 clade 自有 skill（不是 /impeccable 的 sub-command — impeccable 是第三方 npx-managed skill，clade 不擁有）。

何時跑

• /spectra-apply Section 7 Design Review 期間：對本 change 觸及的 paginated query + lookup-resolved column 跑一次。
• /spectra-archive Step 0 之前：archive gate 的 data-shape 防線。
• Ad-hoc：任何改到 useXxxQuery({ <param>: <literal> }) 或 lookup map 的工作。

怎麼跑

從 clade central 呼叫（<clade-vendor> = ~/offline/clade/vendor，與其他 vendor script 同慣例）：

node <clade-vendor>/scripts/audit-data-sanity.mjs \
  --consumer-path . \
  [--files <comma-separated-touched-files>] \
  --json

• 不給 --files → walk 整個 consumer（skip node_modules/.nuxt/dist）。
• 給 --files → 只掃指定檔（spectra-apply 時傳本 phase touched files 較快）。

偵測項

1. PARAM_BOUNDARY（Critical — blocks archive）：client 端 pagination-ish param literal（perPage / per_page / pageSize / limit / take / first / count / top / size）超過（max）或低於（min）同名 server zod bound（.max(N) / .min(N) / .length(N)）。對應 UI-INV-2（lookup-resolved column 解析率 100%）。
2. LOOKUP_MAP_RISK（advisory / warn）：偵測 xxxMap / xxxLookup / xxxById 從 query data（.reduce( / Object.fromEntries( / new Map(）建的 lookup map。提醒：來源 query 若失敗，此 map empty → 對應 column uniform fallback。確認來源 query param 在 schema bound 內。

限制（heuristic，非真 AST）：clade home 無 oxc-parser / @vue/compiler-sfc，本 audit 是 dependency-free regex 掃描（與 d-pattern-audit.mjs / manual-review-audit.mjs 同慣例），靠 param 名跨檔對應 連結 client literal ↔ server bound。同名 param 出現在不相關 schema 時可能 false-link；PARAM_BOUNDARY 命中後請人工確認該 client query 真打到該 server endpoint。

結果處置

• exit 0 status: "pass" → 通過。advisory lookupRisks 印到 stderr 供參考，不 block。
• exit 1 status: "fail"（含 PARAM_BOUNDARY）→ Critical，MUST block：root-cause 修 client literal 到 bound 內（典型：perPage: 200 → 100），或若新 bound 是有意則調 server schema。NEVER 標 phase / archive done、NEVER 留給 user 在 manual review 抓。
• JSON schema：{ status: "pass"|"fail", violations: [{param, clientValue, kind, bound, clientFile, clientLine, serverFile, serverLine}], lookupRisks: [{name, file, line}], scanned: N }。

與其他 Layer 的關係

• Layer B（refactor-invariant-check.mjs）：runtime 偵測「column 整欄 fallback」（症狀）。Layer C 是 static 偵測「param 超界」（root cause）。兩者互補。
• Layer D（UI-INVARIANTS.md）：UI-INV-2 是本 skill 的契約來源。
• Layer E.1（pre-handoff self-analysis）：D4 維度（API contract boundary）可直接引用本 audit 結果。