vlv-code/scan-meta-project

儲存庫後設知識完整性掃描器（Scan Meta-Project）

此為操作性技能，用於對現有後設專案設定進行快速表達式掃描或深度完整性審計，且無需重新初始化。

此技能提供兩種操作模式：

• --shallow（快速健全檢查）： 驗證根目錄 AGENTS.md 及 5 個知識片段的存續與非空狀態，執行邊界閘門（check_boundaries.py --audit-tree）以確認 100% 檔案覆蓋率，並檢查任務時效性。
• --deep（核心深度與偏移檢測）： 執行所有淺層檢查，並進一步調用核心檢查清單審視關鍵執行時模組、將元件/資料流同步委派給 sync-architecture、審計 weak_spots.md 中的技術債務，以及執行本地完整性測試。

---

何時調用此技能

• 使用者要求：「scan-meta-project」、「scan meta project」、「инспекция мета-знаний」、「чекни покрытие」、「audit meta-knowledge」、「check boundaries coverage」、「найди слепые зоны」、「verify slices」。
• 發佈前驗證、PR 審查，或長時間於智能代理會話外進行更改後恢復開發。
• 由 init-meta-project 在初始化完成時自動調用。
• 主要指定角色：agent-quality-guardian（在精簡三體拓撲中）或 agent-meta-guardian（在擴展角色拓撲中），或由使用者直接調用。

---

執行步驟

第一階段：模式判定與目標解析

1. 從使用者提示識別調用模式，若無則預設為 --shallow：
   • --shallow：例行完整性檢查、邊界覆蓋率驗證、任務時效性。
   • --deep：完整架構偏移檢測、核心檢查清單、測試執行。
2. 定位邊界閘門腳本：
   • 優先使用 .agents/scripts/check_boundaries.py（目標儲存庫佈局）。
   • 備用方案為 scripts/check_boundaries.py（後設專案佈局）。
   • 若兩者皆不存在，則手動根據 boundaries.md 中的 glob 模式驗證邊界。

---

第二階段：淺層檢查（--shallow）

1. 護照完整性：
   • 驗證根目錄 AGENTS.md 存在。
   • 確保第 1 節包含北極星與不變量（Circuit Breaker、Default Deny）。
   • 確保第 2、3、4、5 節已填充內容，且無佔位符標籤（{{...}}）。
2. 知識片段審計：
   • 驗證 .agents/project_knowledge/ 中的 5 個標準片段：
     • architecture.md（元件與資料流）。
     • boundaries.md（責任區域）。
     • weak_spots.md（脆弱的模組與風險）。
     • observations.md（5 欄觀察表格）。
     • tasks.md（當前目標與檢查清單）。
3. 邊界覆蓋率（零未映射目錄規則）：
   • 執行自動化邊界閘門審計：

     python .agents/scripts/check_boundaries.py --audit-tree
     # 備用方案：python scripts/check_boundaries.py --audit-tree
     

   • 若回報任何未映射的檔案或目錄，將其視為黑區違規。立即標記以便納入 boundaries.md。
4. 任務登錄檢查（tasks.md）：
   • 確認當前目標清晰，且已完成的項目標記為 - [x]。

---

第三階段：深度檢查（--deep）

執行 --deep 時，智能代理會執行所有第二階段的檢查，隨後進行：

1. 核心檢查清單（關鍵模組）：
   • 資料庫與儲存： 讀取主要模型/儲存庫檔案。檢查綱要耦合、遷移與單體增長。
   • 外部客戶端與 API： 讀取整合（AI SDK、HTTP 用戶端）。檢查超時設定、斷路器與錯誤傳播。
   • 容器化與 CI： 讀取 Dockerfile、docker-compose*.yml、.github/workflows/。驗證建置矩陣與安全性旗標。
   • 進入點與 UI： 讀取主要路由器、CLI 進入點與命令處理器。檢查平台負載限制與輸入驗證。
2. 架構偏移檢測（委派給 sync-architecture）：
   • 請勿複製自訂程式碼解析邏輯。改為調用程序性技能 sync-architecture：
     • sync-architecture 會對所有 local_repo_data 區塊進行飛行前保留。
     • 使用當前元件與端到端資料流更新 .agents/project_knowledge/architecture.md。
3. 風險與債務重新校準（weak_spots.md）：
   • 檢查 weak_spots.md 中現有項目：若先前記錄的技術債務已解決，則標記為已解決或予以移除。
   • 若在核心檢查期間發現新的脆弱耦合或架構瓶頸，則予以記錄。
4. 自動化測試執行：
   • 使用標準測試發現機制執行專案測試套件：

     python -m unittest discover -s tests -p "test_*.py" -v
     # 或使用特定技術棧的執行器（例如 pytest、npm test、cargo test）
     

---

第四階段：伺機重新整理與報告

1. 補遺已識別缺口（讀取 + 伺機重新整理）：
   • 將發現的未映射路徑原子化寫入 boundaries.md（在 <!-- local_repo_data:boundaries --> 區塊內）。
   • 使用新的子任務或已完成的里程碑更新 tasks.md。
   • 將新解決的環境異常記錄至 observations.md。
2. 提供掃描報告： 向使用者呈現簡潔摘要：

   ### 🔍 掃描報告（後設專案掃描器）
   - **模式：** `--shallow` | `--deep`
   - **護照與片段：** 5/5 片段存在，AGENTS.md 有效
   - **邊界覆蓋率：** 100% 已映射（或偵測到 N 個未映射路徑）
   - **架構偏移：** 已同步（或透過 sync-architecture 更新）
   - **已識別行動項目：** [若有的話，列出 1–3 項具體建議]