Skip to content

skill-system-gate-plan.md

Latest commit

 

History

History
58 lines (45 loc) · 3.36 KB

skill-system-gate-plan.md

File metadata and controls

58 lines (45 loc) · 3.36 KB

Behavior Spec: skill-system-gate

This document serves as the BDD specification, acceptance criteria, and implementation plan for skill-system-gate (Issue #6).

1. Behavior Spec (WHAT)

skill_name: skill-system-gate
description: 負責驗證 GNN/FraudDetect 實驗管線與登錄檔安全性的守門員，整合了原先的 gate-ready-workflow 與 registry-safety 功能。

operations:
  - name: validate_experiment
    intent: 檢查特定實驗設定（包括原始碼與 log）是否符合 `gate_bank.json` 中的防呆規範，確保實驗隨時可安全執行或重跑。
    inputs:
      - exp_name: string (實驗名稱)
      - phase_root: string (Phase 目錄，預設為 Phase3)
    constraints:
      - "絕對不可直接修改實驗的原始碼或設定檔"
      - "遇到 error 級別的違規必須中斷並明確回報錯誤，不可放行該實驗"
    expected_effects:
      - returns: "結構化的驗證報告 (Markdown)，包含 [ERROR] 或 [WARN] 項目清單"

  - name: verify_registry_safety
    intent: 驗證 DB Registry 中的實驗狀態是否安全合法，避免 Dirty / Zombie 狀態的實驗被強制重跑。
    inputs:
      - exp_name: string (實驗名稱)
    constraints:
      - "不可強行覆蓋 RUNNING 狀態的實驗"
      - "只進行安全檢查或標記 NEEDS_RERUN，不負責實際排程執行"
    expected_effects:
      - returns: "Registry 安全性檢查結果與狀態建議 (Markdown)"

2. Acceptance Tests (VERIFY)

2.1 Structural Tests (自動化驗收)

  • Manifest Validation: manifest.yaml 必須正確曝露 validate_experiment 與 verify_registry_safety 兩個 operation，Schema 需符合系統定義。
  • Script Existence: 宣告的執行檔（如 scripts/validate.py 或 .sh）必須真實存在於 skill 目錄內。
  • Router Integration: 能夠透過 skill-system-router 成功路由並載入此 skill。

2.2 Behavioral Tests (功能驗收)

  • Safe Block: 提供一個必定觸發 error 規則（例如缺少 train.py 或內含禁用語法）的測試實驗，斷言 Agent 會拒絕放行並輸出具體的錯誤報告。
  • Warning Pass: 提供一個僅觸發 warning 規則的實驗，斷言 Agent 會印出警告但最終給出 "Pass/Safe" 的建議。
  • Registry Safety: 提供一個正處於 RUNNING 的實驗名稱，要求 Agent 進行檢查，斷言 Agent 會察覺其為執行中，且拒絕將其判定為 "可安全重置" 的狀態。

3. Implementation Steps (HOW)

給接下來開發此技能的 Agent (Coding Agent) 參考的實作步驟：

  1. 建立結構: 在 skills/ 底下建立 skill-system-gate 資料夾。
  2. 建立 Manifest: 依照上述 YAML 撰寫正規的 manifest.yaml。
  3. 封裝腳本 (Scripts):
    • 撰寫 scripts/validate_exp.sh (或 Python 封裝腳本)，透過參數呼叫 GNN/FraudDetect 內部的 gate_engine.py 取得判斷結果，並轉化為 Markdown 輸出給 Agent。
    • 撰寫 scripts/check_registry.py，串接 db_registry.DBExperimentsDB，實作狀態檢查與安全守門邏輯。
  4. TDD 迴圈: 分別實作上述兩個功能，並確保符合 Constraints 與 Expected Effects。
  5. 文件生成: 等一切測試通過後，再透過指令把 Behavior Spec 轉發為 Mermaid DAG 當作 SKILL.behavior.yaml（或直接附帶在 README 中）供人類檢閱。