aibdd-dsl-refine

name	aibdd-dsl-refine
description	AIBDD DSL Refine SOP。
metadata	{"user-invocable":true,"source":"project-level"}

AIxBDD - DSL Refine

嚴格遵照底下 Principles 來執行 SOP。

PRINCIPLE: CWD 為產出錨點

• 本 skill 與其 sub-SOP 所有經授權產生或修改的 artifact，一律落在當次執行的工作目錄 CWD 所涵蓋之專案／規格樹內（相對路徑自 CWD 解析；本檔所列 ${...} 路徑皆以 CWD 為錨）。
• 【嚴禁】把應屬本流程的產物寫到 CWD 外的任意絕對路徑，或以「方便」為由落到未載明於當步 SOP 的其他根目錄。

PRINCIPLE: Artifact output contract（硬限制）

• 本 SOP 唯一允許產生或修改的 artifact，只能來自於下述 SOP 中透過 CREATE / WRITE / UPDATE 明確標注的產出物。
• 【嚴禁】除上述 target 外，其他任何 READ / SEARCH / THINK / DERIVE 所觀察到的路徑，都只可作為分析依據，不得被順手建立、寫入、更新或補骨架。
• 互動授權亦屬本契約：在 step 6/7 未取得使用者回覆前 BIND $FP_SLUG／$TARGET_FEATURES、在 step 10 未取得使用者逐項同意前標 # done 或寫 FP 層 isa.yml，一律屬未授權產出（等同越權寫檔）。即使開場指令看似已指定範圍（如「完成所有推導」），該指令只授權「開始跑本 SOP」，不取代任何停點的使用者回覆。

PRINCIPLE: STRICT SOP

1. 依序不漏步：自底下列 SOP 逐一執行；每做一步，在訊息中明示該步編號。

2. 限縮延長推理：僅當當步明文標示須 THINK / REASONING 時，才拉長內省與推演；否則以最直接可做之 READ／PARSE／DERIVE／WRITE／UPDATE／工具呼叫達成該步，省略冗長鋪墊。

PRINCIPLE: 長流程待辦（兩層）

長流程會跨多輪對話；在 conversation compact 之後，執行者仍要靠同一套待辦還原進度。外層只列 phase（本檔 # SOP 每一步），進入 LOOP 後每個 example 再把 sub-SOP 步驟拆成子項。必須以執行環境的待辦工具（TODOCREATE／TASKCREATE 或等效）實體化，禁止只靠聊天口頭列點。

PRINCIPLE: 提問／澄清只委派 clarify-loop

• 凡須向使用者提問或做結構化澄清，本 SOP 一律以一個 DELEGATE /clarify-loop 批次提問，由其決定提問工具與白話文轉譯。
• 各提問點用對應模版組裝 payload：選 FP → assets/fp-question.template.md；選 features → assets/features-question.template.md；example 變更 → 01-refine-example/assets/change-question.template.md；收尾 batch review 的 ISA 確認 → 01-refine-example/assets/isa-question.template.md。
• rich 內容（完整 Example、ISA 展開、DataTable）先 EMIT 到對話（markdown 正常渲染表格與 code block），讓使用者在完整脈絡下檢視；clarify-loop 的 context/question 保持精簡單句並引用上方預覽。切勿把展開／表格塞進 clarify-loop 的 question 欄位（會被攤平成一坨、無法閱讀）。
• 【嚴禁】在 SOP 內 inline 逐題提問、自行 classify／branch 使用者回覆，或在聊天中自組問句代替 clarify-loop。
• 互動斷點必須把問題交還使用者：凡 SOP 標示須經使用者選擇／同意的停點，一律等到真實使用者回覆才續行。【嚴禁】代使用者作答、自行視為同意，或以「整批授權」「本 session 無互動工具」「使用者要求完成全部」為由跳過停點；若當前環境無互動式提問工具，就以結束本回合的方式把問題完整輸出，等待下一輪使用者輸入再續。

PRINCIPLE: feature 非 SSOT，先驗 step 再推 isa

• .feature（SBE 產出）為待驗證候選、非 SSOT。每個未定義 step 先驗測試意圖與合理性（見 01-refine-example/rules/dsl-step-reasoning.md），確認正確才推 isa_step。
• 【嚴禁】在不正確的 step 上推理 isa_step；合理性未過即先經 /clarify-loop（帶完整 Example）確認後變更 .feature，再續。

PRINCIPLE: worklist 只由腳本產出

• 完成度暫存 DSL_REFINE_PLAN.yml（專案根）一律由 scripts/cli/build_worklist.py 產出／刷新，AI 不得手動修改；查看＝READ，刷新＝重跑腳本。
• 持久真相是 dsl.yml 的 # done 標記；worklist 為衍生 session 暫存，啟動即刪除重建。詳見 rules/refine-worklist-query.md。

SOP

請執行到哪讀到哪，千萬不要提早閱讀後續文件，SOP 寫啥就做啥，沒叫你 [THINK/REASONING] 就絕對不准啟用 EXTENDED THINKING。

0. SEARCH **/arguments.yml（在 CWD 下）做 parameters binding；此檔一定存在，如不存在停止並回報：「我在 ${CWD} 底下找不到 **/arguments.yml，你是否已經執行過 /aibdd-kickoff 了？」

1. RESOLVE arguments——將下列 ${VAR} 透過 sibling resolver 綁定，stdout 原樣 EMIT；非 0 退出則 STOP 並透傳 stderr。

   python3 .claude/skills/aibdd-core/scripts/cli/resolve_args.py <<'EOF'
   AIBDD_ARGUMENTS_PATH=${AIBDD_ARGUMENTS_PATH}
   BOUNDARY_ISA=${BOUNDARY_ISA}
   CONTRACTS_DIR=${CONTRACTS_DIR}
   DATA_DIR=${DATA_DIR}
   TRUTH_BOUNDARY_PACKAGES_DIR=${TRUTH_BOUNDARY_PACKAGES_DIR}
   TRUTH_BOUNDARY_ROOT=${TRUTH_BOUNDARY_ROOT}
   EOF
   

2. ASSERT arguments 必備鍵齊全——對 ${AIBDD_ARGUMENTS_PATH} 檢查：TRUTH_BOUNDARY_ROOT、TRUTH_BOUNDARY_PACKAGES_DIR、BOUNDARY_ISA、CONTRACTS_DIR、DATA_DIR。缺鍵 → 列出、提示 /aibdd-kickoff、STOP。本步禁止順手補建 arguments.yml。

3. ASSERT 上游真相已就緒（READ-ONLY；任一失敗即列缺項、STOP、提示對應 skill）：

   • ${BOUNDARY_ISA} 存在（kickoff isa 種子）；缺 → /aibdd-kickoff。
   • ${TRUTH_BOUNDARY_PACKAGES_DIR}/*/features/*.feature 至少一份且已列 atomic rules；缺 → /aibdd-flows-specify、/aibdd-rules-specify。
   • api-plan 已完成：${CONTRACTS_DIR} 下有實際 operation contract 檔（排除 .gitkeep）；缺 → /aibdd-api-plan。
   • data-plan 已完成：${DATA_DIR} 下有 schema（DDL .sql／.dbml）與 entity_to_table_mapping.yml；缺 → /aibdd-data-plan。

4. LOAD 參照真相（一次性，READ-ONLY；供整個 LOOP 共用，不在 loop 內逐 example 重讀）：

   • isa instruction 目錄：READ ${BOUNDARY_ISA} 與 ${TRUTH_BOUNDARY_PACKAGES_DIR}/*/*.isa.yml（每條 name／format／instruction_type／data_format／custom 契約）。
   • operation contracts：READ ${CONTRACTS_DIR}/**（summary／path／query／header／required）。
   • data schema：READ ${DATA_DIR}/**（DDL／.dbml 與 entity_to_table_mapping.yml；表／欄位／NOT NULL／PK）。
   • 本步只 READ。

5. BUILD worklist——RUN 下列腳本掃出「含未完成定義 dsl step」的 FP/feature/example，產出 DSL_REFINE_PLAN.yml（專案根；先刪舊檔再產，read-only 對 specs）。語意見 rules/refine-worklist-query.md。

   python3 .claude/skills/aibdd-dsl-refine/scripts/cli/build_worklist.py --packages-dir ${TRUTH_BOUNDARY_PACKAGES_DIR} --out DSL_REFINE_PLAN.yml
   

   產出為空（全部完成）→ STOP 並回報完成；腳本回報找不到 package → STOP 並提示先完成 /aibdd-flows-specify。

6. SELECT FP（單選硬閘門）——READ DSL_REFINE_PLAN.yml 的 fps[]，以 assets/fp-question.template.md 組裝、DELEGATE /clarify-loop 讓使用者選一個 FP。

   • 取得真實使用者回覆 → BIND $FP_SLUG、$FP_DIR=${TRUTH_BOUNDARY_PACKAGES_DIR}/$FP_SLUG、$FP_FEATURES=$FP_DIR/features、$FP_PACKAGE_DSL=$FP_DIR/dsl.yml，進入 step 7。
   • 互動工具不可用或 clarify-loop 未能取得真實使用者回覆 → EMIT FP 選項清單並結束本回合：此時本回合的正式交付物就是這份問題清單，交出它即視為本回合任務圓滿完成（不是失敗、不是中止），最後一則訊息就是待答問題，等待下一輪使用者輸入再續。
   • 【嚴禁】代選：「候選唯一」「背景／subagent 執行」「開場指令已指定範圍或整批授權（如：完成所有推導）」皆不構成代答理由——開場指令只授權開始跑本 SOP，不取代本停點的回覆。

7. SELECT Features（多選硬閘門）——READ worklist 選定 FP 的 features[]，以 assets/features-question.template.md 組裝、DELEGATE /clarify-loop 讓使用者複選。

   • 取得真實使用者回覆 → BIND $TARGET_FEATURES[]；空集合 → STOP。
   • 互動工具不可用或 clarify-loop 未能取得真實使用者回覆 → EMIT features 選項清單並結束本回合（同 step 6：問題清單即本回合正式交付物，交出即圓滿完成）。
   • 【嚴禁】代選；不構成理由同 step 6。

8. ENSURE {feature}.dsl.yml 就緒——對每個 $TARGET_FEATURES，$FP_FEATURES/{feature}.dsl.yml 不存在 → 以 assets/dsl.template.yml 為模版 CREATE 空骨架。（跨 feature 共用的 $FP_PACKAGE_DSL 待 sub-SOP 重構步按需才建。）本步只 CREATE 空骨架，不填內容。

9. LOOP examples（推導期，不中途確認）——對 worklist 中「屬 $TARGET_FEATURES、status: pending」的每個 example，逐一 EXECUTE the sub-sop：

   01-refine-example/SOP.md（輸入：該 example 的 feature 路徑 ${FEATURE}、example 標題、worklist 列的未完成 step）

   每個 example 的 sub-SOP 返回後（帶回該 example 的待 review 展開），接續下一個 pending example；直到 $TARGET_FEATURES 內無 pending。 【嚴禁】推導期間逐 example 或逐 dsl_step 向使用者確認 ISA；所有 ISA 確認集中在 step 10 的收尾 batch review 一次進行（sub-SOP 內 a/b 的 example 合理性變更授權不在此限）。

10. BATCH REVIEW（收尾一次 review，強制硬閘門）——所有選定 examples 推導完成後才執行；使用者同意前不得定案：

    a. 對每個受影響 example RUN 01-refine-example 的 expand_isa.py 取得展開，一次 EMIT 全部受影響 features/examples 的完整展開預覽到對話（每個 example：完整 Example ＋ 逐 dsl_step 展開）。 b. 依 01-refine-example/assets/isa-question.template.md 組裝、DELEGATE /clarify-loop 讓使用者對預覽逐項同意／不同意（引用上方預覽，question 保持精簡單句）。

    • 互動工具不可用或 clarify-loop 未能取得真實使用者回覆 → 確保 a 的完整預覽已 EMIT，補上逐項待答問題後結束本回合：此時本回合的正式交付物就是這份待 review 展開與問題清單，交出它即視為本回合任務圓滿完成，等待下一輪使用者輸入再續。
    • 【嚴禁】代答同意：「候選唯一」「背景／subagent 執行」「開場指令已指定範圍或整批授權」皆不構成代行 review 的理由；「採同意為工作假設」即未授權標 # done（見 Artifact output contract）。 c. 任一項不同意 → 依回饋回 sub-SOP c 調整該 dsl_step（含把誤開的 custom 改為 builtin 組合），重跑該 example 展開，回 a 只重審被拒項，直到全數同意。 d. 全數同意 → 才在各 dsl_step name 上方標 # done；custom 有新增 → 此時才寫 FP 層 isa.yml 契約；再重跑 step 5 的 build_worklist.py 刷新 worklist，確認 $TARGET_FEATURES 內無 pending。 【嚴禁】在使用者同意前標 # done、寫 FP 層 isa.yml，或以任何理由（含環境無互動工具）跳過本 review 自行定案。

11. FP 級去重 + name 唯一性 gate（收尾，強制硬閘門）——所有選定 feature 的 example 全部 # done 後才執行；這是宣告完成前的決定性 gate，不可略過、不可只憑自我回報「已收斂」（曾發生 agent 謊報無重複、實際 16 條未上移、展開階段被阻斷）。

    a. RUN 偵測器（其 exit code 為 gate）：

    python3 .claude/skills/aibdd-dsl-refine/scripts/cli/detect_shared_dsl.py --packages-dir ${TRUTH_BOUNDARY_PACKAGES_DIR} --fp $FP_SLUG
    

    b. exit 3（有跨 feature 重複）：對回報的每一條都要處理，依 01-refine-example/rules/example-refactor.md §2 hoist 到 $FP_PACKAGE_DSL、刪各 {feature}.dsl.yml 的重複（保留 # done）。

    • name 重複為阻斷級（dsl.yml 規則：dsl_step name 在其 FP 解析範圍／祖先鏈內必須唯一；重複會在展開時造成名稱衝突 DSL_DEFINITION_DUPLICATE_NAME、阻斷整個 FP、連 dry-run 都掃不到）→ 務必全部上移；標「同名不同 format」者先對齊 format 再上移。
    • format 重複（收斂級）一併上移。 c. 重跑 a，直到 exit 0。唯有 detect exit 0 才得宣告完成；仍 exit 3 代表還有重複，未清不得結束。 d. 清乾淨後重跑 step 5 build_worklist.py 確認 worklist 仍空。本步只重構結構、不改驗收意圖。