Qjudge Quality Gates Owner

QJudge Quality Gates Owner

Quick start

• 先跑 naming：
  • node .codex/skills/qjudge-quality-gates-owner/scripts/lint-naming.js --root frontend/src
• 再跑 architecture：
  • node .codex/skills/qjudge-quality-gates-owner/scripts/lint-architecture.js --root frontend/src
• 檢查 repository public surface：
  • node .codex/skills/qjudge-quality-gates-owner/scripts/lint-repository-exports.js
• 跑 Carbon 全量 audit（不因 review findings 失敗）：
  • node .codex/skills/qjudge-quality-gates-owner/scripts/audit-carbon-practices.js --root frontend/src
• 本機快速檢查 staged hard blockers：
  • bash .codex/skills/qjudge-quality-gates-owner/scripts/check-carbon-style.sh --staged
• 執行與 CI 相同的 Carbon strict hard gate：
  • bash .codex/skills/qjudge-quality-gates-owner/scripts/check-carbon-style.sh --all
• 修復無效的 var(--cds-spacing-*) 與可精確映射的 spacing（先 dry-run）：
  • node .codex/skills/qjudge-quality-gates-owner/scripts/fix-carbon-spacing-tokens.js --root frontend/src
  • node .codex/skills/qjudge-quality-gates-owner/scripts/fix-carbon-spacing-tokens.js --root frontend/src --write

責任邊界（Owner Scope）

• ✅ lint 規則、Carbon audit/staged/strict profile、CI gate 定義。
• ✅ 架構/命名/Carbon public API/樣式禁則的可執行檢查腳本。
• ✅ 違規分類與遷移節奏（先報告再阻擋）。
• ❌ 不做 feature 架構決策（交給 qjudge-architecture-owner）。
• ❌ 不做 PR 流程決策（交給 qjudge-github-workflow-owner）。

Policy

• audit：全量掃描，將每個檔案標成 clean、findings、policy-reviewed、exception-review 或 not-applicable；review 類不阻擋。
• staged：以 --staged 快速檢查已暫存檔案，供本機迭代使用；它不是 CI 的完整替代。
• strict：以 --all 掃整個 root；只要仍有 blocker 就失敗。這是目前 .github/workflows/ci.yml 的 CI hard gate。

Carbon audit contract

• blocker：.cds--* / .bx--* internal selector、!important、Carbon React 不會輸出的 var(--cds-spacing-*) runtime variable。
• review：hard-coded theme/spacing/type、raw controls、accessible labels、notification variant、scroll owner 等需結合 UI context 判斷的候選。
• policy-reviewed：已由 references/carbon-audit-decisions.json 以精確檔案、元件類型、理由、owner 與移除條件完成審查；新路徑或新控制類型不會自動繼承決策。
• exception-review：測試 fixture、shared/copilot boundary、editor/media 等合理但仍需人工驗證的例外。
• 需要人工視覺／runtime 判斷的 review debt 由 references/carbon-manual-review-budget.json 鎖定上限，只能下降；可精確映射的 spacing 使用 scripts/fix-carbon-spacing-tokens.js --write 處理。
• Audit script 會使用專案 TypeScript parser 做 JSX semantic checks；缺少 frontend dependencies 時退回保守 regex 掃描。
• 不建立不存在的 generic Carbon override allowlist。若真的需要 compatibility boundary，必須是命名明確、範圍最小且有移除條件的 app-owned wrapper。

參考文件

• references/quality-profiles.md
• references/carbon-audit-decisions.json
• references/carbon-manual-review-budget.json
• scripts/lint-naming.js
• scripts/lint-architecture.js
• scripts/lint-repository-exports.js
• scripts/audit-carbon-practices.js
• scripts/check-carbon-style.sh

Portable notes

• 可移植核心：可執行規則 > 文字規範。
• 新專案只需替換 root path 與 package-specific exception policy，即可重用。