ops-wiki-agent-kit 0.1.0 → 0.1.1

package/.github/agents/docs-target-catalog.agent.md

@@ -1,10 +1,11 @@
 ---
 name: docs-target-catalog
+tools: [execute, read, edit, search, todo]
 description: 建立以原始碼為依據的 documentation target catalog，提供目標來源交接資訊。
 handoffs:
   - label: Generate Documentation Target Queue
     agent: docs-target-queue-from-catalog
-    prompt: "使用 `docs/docs-target-catalog.md` 作為 catalog，執行 `docs-target-queue-from-catalog` 第二階段：依 `Authoritative Target Source Handoff` 取得或解析 authoritative sources，正規化為 current queue schema 的 generic target rows，必要時使用 `$docs-target-queue-from-catalog` 的 generic converter，並產生 `docs/docs-target-queue.md`。最終寫入時只加入精簡 `## Obsidian Links`，且僅可使用已確認存在或本次同時建立的 note links；沒有可靠 links 時可省略該區塊。輸出文件與回覆皆以中文為主，僅在固定欄位、識別字或必要原文引述時保留英文；回覆 source counts、acquisition status、count validation 與 coverage gaps。"
+    prompt: "使用 `docs/docs-target-catalog.md` 作為 catalog，執行 `docs-target-queue-from-catalog` 第二階段，依 `$docs-target-queue-from-catalog` 與 shared queue schema contract 產生 `docs/docs-target-queue.md`。"
 ---
 
 # Documentation Target Catalog Agent
@@ -24,28 +25,15 @@ handoffs:
 
 ## Quality Gates
 
-- Activation source 優先於 implementation files。不要只根據 extension、filename 或 folder placement 判定 top-level documentation target。
-- `keyword` 不是 target queue；`Function` 不泛指 method/helper；document section 不是 `source_type`；未限定的 `source` 必須改成 `source code`、`source evidence`、`authoritative source`、`source extract` 或 `source_type`。
-- 每個 target scope 都要說清楚最終 row authority；DB-backed、repo-owned hardcoded、client-side、external-file、route registry、scheduler registry 可以並存，但必須分 scope。
-- 對 external、environment-owned 或尚未取得 rows 的 authoritative source，不可自行補出 final-looking rows；只能放入 handoff acquisition action 或 `Coverage Review`。
-- repo-owned hardcoded menu、navigation、command 或 job list 若是 runtime 實際啟動來源，必須視為 authoritative source，不可降級成弱證據 candidate。
-- authority 判定與多來源分 scope 依 `$docs-target-catalog` 的 `Authority Disambiguation` 執行；agent 只負責確保不要把 control-plane source 誤寫成 final row authority。
-- `Authoritative Target Source Handoff` 必須能直接驅動第二階段，至少包含 `target_scope`、`source_kind`、`authoritative_source`、`owner`、`final_row_authority`、`required_fields_or_handles`、`evidence`、`target_queue_action`。
-- `target_queue_action` 只能使用可執行的 acquisition intent，例如 `query/export`、`parse_file`、`parse_catalog_table`、`direct_rows` 或 `coverage_gap`。
+以 `$docs-target-catalog` 的 discovery、classification、authority disambiguation、output contract 與 shared terminology contract 為準。Agent 只負責維持 high-level gate：不得把 implementation evidence、summary、candidate 或 control-plane source 誤寫成 final row authority。
 
-## Output Contract
-
-compact handoff catalog 預設只保留第二階段必要資訊：
+- Activation source 優先於 implementation files；不要只根據 extension、filename 或 folder placement 判定 top-level documentation target。
+- 沒有 final row authority 的 source 只能進 handoff acquisition action 或 coverage gap，不得寫成 final-looking target row。
+- `keyword` 不是 target queue；summary、candidate、document section 或 helper file 也不是 target row。
 
-- `Repo Fingerprint`
-- `Authoritative Target Source Handoff`
-- `Direct Target Rows` 或 `Hardcoded Target Rows`，僅限已具 source-backed row authority 的 targets
-- source-scoped summary，僅在有助於 acquisition 或 coverage 判斷時加入
-- 集中式 `Coverage Review`
+## Output Contract
 
-不要在每個 target 下重複 `Unresolved: None`，也不要把 call chain、DAO/resource details 或只有 summary/candidate 證據的項目放進 final-looking target rows。
-- 若寫入 `docs/docs-target-catalog.md` 且有可靠 direct context，只允許加入精簡 `## Obsidian Links`，例如 queue 或 direct related note；不要把 compact handoff catalog 擴寫成額外的索引或導覽內容。
-- 最終 catalog 的章節標題、表格說明、coverage review 與 handoff 敘述預設使用中文；只有 contract 明確要求的固定 token、欄位值、檔名或 source 原文才保留英文。
+正式 output contract 由 `$docs-target-catalog` 擁有；repo artifact 邊界由 `source-code-to-spec-tools/references/repository-artifact-contract.md` 擁有。
 
 ## Final Response
 

package/.github/agents/docs-target-queue-from-catalog.agent.md

@@ -1,5 +1,6 @@
 ---
 name: docs-target-queue-from-catalog
+tools: [execute, read, edit, search, todo]
 description: 依據 catalog 指引的來源取得、正規化與筆數驗證流程產生 docs/docs-target-queue.md。
 ---
 
@@ -14,21 +15,21 @@ description: 依據 catalog 指引的來源取得、正規化與筆數驗證流
 - 預設 input 是 `docs/docs-target-catalog.md`。
 - 預設 output 是 `docs/docs-target-queue.md`。
 - 主要執行規則來自 `$docs-target-queue-from-catalog` skill。
-- Queue vocabulary、schema、status enum、`source_type` registry 與 ID 規則以 repo shared contract 為準，不在 agent 內維護第二份定義。
-- Main target table 使用 current queue schema：`doc_profile` 搭配 `foundation_doc_status`、`architecture_doc_status`、`ops_doc_status`；不要讀取或輸出舊 profile/status 欄位。
+- Queue vocabulary、schema、status enum、`source_type` registry、ID 規則與 `doc_profile` 規則以 repo shared contracts 為準，不在 agent 內維護第二份定義。
 - 除非 catalog 缺失且允許建立第一階段 catalog，否則不要重跑 broad discovery，也不要根據 repo files 猜測 queue rows。
 
 ## Gates
 
 - 先確認可用 input：使用者提供的 catalog/handoff/source extract 優先，其次才讀 `docs/docs-target-catalog.md`。
 - 依 catalog 的 `Authoritative Target Source Handoff` 或等效欄位決定 acquisition path；不要把 summary、candidate、document section、helper file 或 file extension 當成 final row authority。
-- DB/environment metadata 才使用 `$database-query` 或 native DB client；repo/file/catalog/direct rows 使用對應 parse/read path。
+- DB/environment metadata 才使用 `$database-query` 或 native DB client；若 authoritative source 是 DB table、view 或 metadata store，必須先嘗試 repo-first DB discovery / read-only acquisition，或記錄具體 acquisition failure status，不可只因 repo 沒有現成 export 就跳到 coverage review。repo/file/catalog/direct rows 使用對應 parse/read path。
+- DB 連線測試只算 preflight；DB-owned final row authority 必須通過 `$docs-target-queue-from-catalog` 的 Source Acquisition Gate 後才能宣告正式 queue 完成。
 - 需要程式化轉換時，使用 `$docs-target-queue-from-catalog` 的 generic converter，不新增 project-specific converter。
 - 若 required、complete inventory 或 final row authority 尚未取得，只能輸出 partial/incomplete evidence，不可覆蓋或宣告正式 `docs/docs-target-queue.md` 完成。
 - Final success 必須確認 `docs/docs-target-queue.md` 已建立或更新，並通過 skill contract 的 validation 與 cleanup gate。
 
 ## Output
 
-正式輸出必須符合 `.github/skills/docs-target-queue-from-catalog/references/docs-target-queue-contract.md`。
+正式輸出必須符合 `.github/skills/docs-target-queue-from-catalog/references/docs-target-queue-contract.md` 與 `.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md`。
 
 Final response 以中文為主並保持精簡：只交代 output path、source counts、每個 acquisition source 的 status、count validation 結果、cleanup result，以及 blockers 或 coverage gaps。

package/.github/agents/source-code-to-spec-documenter.agent.md

@@ -1,5 +1,6 @@
 ---
 name: source-code-to-spec-documenter
+tools: [execute, read, edit, search, todo]
 description: 從 docs-target-queue target queue 選取一筆目標，依 entrypoint 追 source evidence，產生 source-code-backed SPEC docs；缺少 runtime metadata 時產出 partial SPEC 與可審查 coverage gaps，並交接 review handoff。
 handoffs:
   - label: Review Target SPEC

package/.github/agents/source-code-to-spec-reviewer.agent.md

@@ -1,5 +1,6 @@
 ---
 name: source-code-to-spec-reviewer
+tools: [execute, read, edit, search, todo]
 description: 依 selected row document_path review 當下存在的 target SPEC docs，使用 handoff 輔助檢查 source evidence、guideline contract、scenario / operations coverage applicability，並更新 docs-target-queue queue 狀態。
 ---
 
@@ -18,11 +19,11 @@ description: 依 selected row document_path review 當下存在的 target SPEC d
 - 對 `docs/**/*.md` 檔案只檢查 `## Obsidian Links` 是否僅引用已確認 notes。
 - Review target 必須先解析 selected row；明確指定 `id` 時用該 row，未指定 `id` 時沿用 `$source-code-to-spec-documenter` / `target-queue-contract.md` 的既有 selection rules。
 - Review file-set 以 selected row `document_path` 下當下實際存在的 expected target SPEC files 為準，且必須位於 `docs/**/*.md`。Expected filenames 由 selected row `name` 與 `$source-code-to-spec-documenter` File Naming Contract 建立。
-- 若三份 expected target SPEC 只有一份或兩份存在，仍必須審查已存在文件；缺少的 expected file 記錄為 missing selected output / artifact drift，並視實際缺漏修正 `document_completed_flag(Y/N)`。
-- Handoff 的 `generation_scope`、`doc_profile`、`doc_file_plan` 與 `source_evidence` 是 review 輔助 ledger；handoff 缺失、不可讀或與 current artifact state 差異，列為 handoff drift / artifact drift，review root 仍以 selected row `document_path` 為準。
-- Handoff 的 `source_evidence` 必須符合 `EvidenceRef[]`，每筆包含 `path`、`line`、`symbol`、`kind`；generated docs 的 evidence / traceability 欄位以可對應這些 refs 作為完成標準。
-- `document_completed_flag(Y/N)` 表示 selected row `document_path` 下三份 target SPEC 文件是否存在，由 generation file existence gate 維護；review passed / failed 由 `review_status` 表示。
-- Review workflow 更新 `review_status`、findings 與必要 notes；`document_completed_flag(Y/N)` 僅在 review 發現三份文件實際缺漏或路徑錯誤時同步修正。
+- Missing expected files、handoff drift、artifact drift、`EvidenceRef[]` shape、`document_completed_flag(Y/N)` 與 `review_status` transition 依 `$source-code-to-spec-documenter` 的 queue / handoff contract 執行；本 agent 不重複維護 schema。
+
+- Review root 是 selected row `document_path`，不是 handoff path、queue path 或任意 `docs/**` folder。
+- Missing expected target SPEC file、handoff drift、artifact drift 或 invalid `EvidenceRef[]` 必須列為 finding。
+- Queue status 與 completion flag 只依 `$source-code-to-spec-documenter` contract 更新，不得自行推導新狀態語意。
 
 ## Review Priority
 
@@ -35,6 +36,7 @@ Findings 先行，依嚴重程度排序：
 - 文件或 handoff 把 `keyword` 當成 queue/behavior evidence、把 implementation file 當 target、把 document section 當 source_type，或把未限定的 `source` 當 row authority。
 - 文件漏掉 entrypoint 可達但地圖未標記的 form action、AJAX、export/import、file/report、job、SQL/procedure 或 external integration 行為。
 - guideline-required sections 缺漏。
+- 若 source evidence 存在但文件漏掉實際入口型態、維護者定位表、interaction summary、validation / business rules summary、batch rules summary、transaction / resource boundary、source-backed risk / limitation 或 traceability locator，列為 guideline-required coverage finding。
 - selected row `document_path` 底下缺少 expected target SPEC file，或 handoff `doc_file_plan` / `generated_files` 與當下存在的 expected files 脫鉤。
 - `docs/**/*.md` 的 `[[internal links]]` 應指向已確認 notes；placeholder、sample hub 或 unresolved links 列為 link quality finding。
 - technical identifiers 被錯誤翻譯或改寫。

package/.github/agents/source-code-to-system-ops-overview.agent.md

@@ -1,5 +1,6 @@
 ---
 name: source-code-to-system-ops-overview
+tools: [execute, read, edit, search, todo]
 description: 根據 source code、SQL、設定檔、部署線索、依賴檔、Log keyword、錯誤訊息或既有文件，產生或更新跨系統型態、跨技術棧的系統層級維運總覽文件。
 ---
 

package/.github/prompts/00-discover-target-baseline.prompt.md

@@ -0,0 +1,37 @@
+---
+agent: source-code-to-spec-documenter
+tools: [execute, read, edit, search, todo]
+description: 為 docs-target-queue 的單一 target row 建立或刷新 shared discovery handoff baseline，不產生 target-facing SPEC 文件。
+---
+
+# Discover Target Baseline
+
+此 prompt 只設定 `baseline` scope invocation。Prompt role、execution order、handoff baseline、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
+
+不要在 task start 時一次完整載入所有 skills、全部 references 或 reviewer workflow；依 `generation-workflow.md` 的 progressive loading 順序執行。
+
+## Scope
+
+`generation_scope = baseline`
+
+`doc_profile = <selected row doc_profile | user specified | standard>`
+
+本 scope 只建立或刷新 shared `handoff.json` baseline；不得產生或更新 target-facing SPEC 文件，也不得將任何 doc status 設為 `generated`。
+
+## Critical Guardrails
+
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 baseline behavior。
+- Baseline 是 search priority / evidence ledger，不是 completion proof；不得把未追蹤的 behavior 寫成 `N/A` 或已確認不適用。
+- 必須保留 visible subfunctions、relation candidates、unmapped behaviors、coverage gaps 與 `not_checked`，避免後續 `01` / `02` / `03` 遺失追蹤線索。
+- 不得寫入任何 target-facing `docs/**/*.md` 檔案；只允許寫入 durable handoff `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`，並以同一路徑更新 queue `last_handoff`。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
+
+## Orchestration
+
+依 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 執行；prompt 不另行改寫 workflow contract。
+
+## Final Response
+
+依 `$source-code-to-spec-documenter` 的 baseline Final Response contract 回報，並額外標示 durable handoff path、confirmed evidence、not checked 與後續建議執行的 `01` / `02` / `03` prompt。

package/.github/prompts/00-generate-target-all-spec.prompt.md

@@ -1,12 +1,12 @@
 ---
 agent: source-code-to-spec-documenter
 tools: [execute, read, edit, search, todo]
-description: 針對 docs-target-queue 的單一 target row 建立 discovery baseline，並一次產生三份 source-code-backed ops SPEC 文件。
+description: 針對 docs-target-queue 的單一 target row 復用或刷新 shared handoff，並一次產生三份 source-code-backed ops SPEC 文件。
 ---
 
 # Generate Target All SPEC
 
-此 prompt 只設定 `all` scope invocation。Prompt role、execution order、handoff baseline、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
+此 prompt 只設定 `all` scope invocation。Prompt role、execution order、handoff reuse / refresh、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
 
 不要在 task start 時一次完整載入所有 skills、全部 references 或 reviewer workflow；依 `generation-workflow.md` 的 progressive loading 順序執行。
 
@@ -16,15 +16,15 @@ description: 針對 docs-target-queue 的單一 target row 建立 discovery base
 
 `doc_profile = <selected row doc_profile | user specified | standard>`
 
-本 scope 產生或更新三份 target SPEC；selected output files、coverage handling 與 output action 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 決定。
+本 scope 產生或更新三份 target SPEC；若既有 shared baseline 可用，應先復用並增量更新。若 baseline 不存在，`all` scope 會建立完整 shared handoff。selected output files、coverage handling、durable handoff 寫入與 output action 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 決定。
 
-## Generation Detail
+## Critical Guardrails
 
-本次 invocation 必須要求 `$source-code-to-ops-spec-guidelines` 使用最詳細 source-backed SPEC style；不要把 source evidence 壓成摘要或只產生 overview。若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 逐檢三份 selected output file。
-
-三份 output files 都必須依各自 guideline 產出完整正式章節、完整 table contracts、source-backed SQL、Step / branch / mapping detail，以及每張 diagram 後的結構化圖表文字說明。
-
-`all` scope 是一次產出三份完整 sibling docs，不是把總篇幅平均分薄。若來源不足，以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 標示並寫入 handoff，不可用摘要取代缺漏章節。
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 generation behavior。
+- 不得用 summary、handoff summary、Final Response 或 reviewer note 取代 selected output file 內的正式章節內容。
+- 若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 檢查 selected output files。
+- 必須依 handoff contract 寫入 `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`，並以同一路徑更新 queue `last_handoff`。
+- 不得寫入 `doc_file_plan.selected_output_files` 以外的 target-facing `docs/**/*.md` 檔案。
 
 ## Orchestration
 
@@ -32,4 +32,4 @@ description: 針對 docs-target-queue 的單一 target row 建立 discovery base
 
 ## Final Response
 
-依 `$source-code-to-spec-documenter` 的 Final Response contract 回報，並額外標示三份文件 path 與是否需要執行 review。
+依 `$source-code-to-spec-documenter` 的 Final Response contract 回報，並額外標示三份文件 path、durable handoff path 與是否需要執行 review。

package/.github/prompts/01-generate-target-foundation-spec.prompt.md

@@ -1,12 +1,12 @@
 ---
 agent: source-code-to-spec-documenter
 tools: [execute, read, edit, search, todo]
-description: 為 docs-target-queue 的單一 target row 建立 discovery baseline，並產生第 1 份 foundation/business source-code-backed ops SPEC 文件。
+description: 為 docs-target-queue 的單一 target row 復用或更新 discovery baseline，並產生第 1 份 foundation/business source-code-backed ops SPEC 文件。
 ---
 
 # Generate Target Foundation SPEC
 
-此 prompt 只設定 `foundation` scope invocation。Prompt role、execution order、handoff baseline、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
+此 prompt 只設定 `foundation` scope invocation。Prompt role、execution order、handoff baseline reuse / update、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
 
 不要在 task start 時一次完整載入所有 skills、全部 references 或 reviewer workflow；依 `generation-workflow.md` 的 progressive loading 順序執行。
 
@@ -16,15 +16,19 @@ description: 為 docs-target-queue 的單一 target row 建立 discovery baselin
 
 `doc_profile = <selected row doc_profile | user specified | standard>`
 
-本 scope 產生或更新第 1 份 target SPEC；selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
+本 scope 產生或更新第 1 份 target SPEC；優先復用 `00-discover-target-baseline.prompt.md` 建立的 shared handoff。selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
 
-## Generation Detail
+## Critical Guardrails
 
-本次 invocation 必須要求 `$source-code-to-ops-spec-guidelines` 使用最詳細 source-backed SPEC style；single-scope 只限制 selected output file，不降低內容深度。
-
-本文件必須依 foundation/business guideline 產出完整正式章節、完整 table contracts、source-backed SQL（適用時）、Step / branch / mapping detail（適用時），以及每張 diagram 後的結構化圖表文字說明。
-
-不得只產出摘要、維運摘要卡或 cross-reference 代替正式章節。若來源不足，以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 標示並寫入 handoff，不可用摘要取代缺漏章節。
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 generation behavior。
+- 不得用 summary、handoff summary、Final Response 或 reviewer note 取代 selected output file 內的正式章節內容。
+- 若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 檢查 selected output file。
+- 若 baseline 不存在，只能建立最小 discovery baseline；不得把未追蹤的 downstream、DAO、SQL、error / ops evidence 寫成已確認不存在。
+- 不得寫入 `doc_file_plan.selected_output_files` 以外的 target-facing `docs/**/*.md` 檔案。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- 若發現同一 target 有尚未合併的 patch JSON，先依該 patch 自身 scope 完成 helper merge 與 queue sync，再繼續本 prompt。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
 
 ## Orchestration
 

package/.github/prompts/02-generate-target-architecture-spec.prompt.md

@@ -18,13 +18,17 @@ description: 為 docs-target-queue 的單一 target row 復用或更新 handoff
 
 本 scope 產生或更新第 2 份 target SPEC；selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
 
-## Generation Detail
-
-本次 invocation 必須要求 `$source-code-to-ops-spec-guidelines` 使用最詳細 source-backed SPEC style；single-scope 只限制 selected output file，不降低內容深度。
-
-本文件必須依 architecture/flow/data/logic guideline 產出完整正式章節、完整 table contracts、source-backed SQL、Step / branch / mapping detail，以及每張 diagram 後的結構化圖表文字說明。
-
-不得只產出摘要、維運摘要卡或 cross-reference 代替正式章節。若來源不足，以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 標示並寫入 handoff，不可用摘要取代缺漏章節。
+## Critical Guardrails
+
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 generation behavior。
+- 不得用 summary、handoff summary、Final Response 或 reviewer note 取代 selected output file 內的正式章節內容。
+- 必須把既有 baseline / foundation handoff 的 `not_checked`、`coverage_gaps`、`relation_candidates` 與 `unmapped_behaviors_found` 視為 architecture tracing 的 follow-up input；不得因 foundation 未展開就推定 behavior 不存在。
+- 若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 檢查 selected output file。
+- 不得寫入 `doc_file_plan.selected_output_files` 以外的 target-facing `docs/**/*.md` 檔案。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- 若發現同一 target 有尚未合併的 patch JSON，先依該 patch 自身 scope 完成 helper merge 與 queue sync，再繼續本 prompt。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
 
 ## Orchestration
 

package/.github/prompts/03-generate-target-ops-spec.prompt.md

@@ -18,13 +18,17 @@ description: 為 docs-target-queue 的單一 target row 復用或更新 handoff
 
 本 scope 產生或更新第 3 份 target SPEC；selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
 
-## Generation Detail
-
-本次 invocation 必須要求 `$source-code-to-ops-spec-guidelines` 使用最詳細 source-backed SPEC style；single-scope 只限制 selected output file，不降低內容深度。
-
-本文件必須依 error/ops/scenario coverage guideline 產出完整正式章節、完整 table contracts、source-backed SQL（適用時）、Step / branch / mapping detail（適用時），以及每張 diagram 後的結構化圖表文字說明。
-
-不得只產出摘要、維運摘要卡或 cross-reference 代替正式章節。若來源不足，以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 標示並寫入 handoff，不可用摘要取代缺漏章節。
+## Critical Guardrails
+
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 generation behavior。
+- 不得用 summary、handoff summary、Final Response 或 reviewer note 取代 selected output file 內的正式章節內容。
+- 必須把既有 baseline / foundation / architecture handoff 的 `not_checked`、`coverage_gaps`、`relation_candidates` 與 `unmapped_behaviors_found` 視為 ops tracing 的 follow-up input；不得因前序 scope 未展開就推定 behavior 不存在。
+- 若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 檢查 selected output file。
+- 不得寫入 `doc_file_plan.selected_output_files` 以外的 target-facing `docs/**/*.md` 檔案。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- 若發現同一 target 有尚未合併的 patch JSON，先依該 patch 自身 scope 完成 helper merge 與 queue sync，再繼續本 prompt。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
 
 ## Orchestration
 

package/.github/prompts/docs-target-catalog.prompt.md

@@ -11,9 +11,7 @@ description: '使用 docs-target-catalog skill，從 source-backed entrypoints
 
 ## Task
 
-分析目前 workspace，建立 source-backed compact handoff catalog。這份 catalog 的主要用途是交接給 `docs-target-queue-from-catalog`，讓第二階段知道哪些 authoritative sources 應 `query/export`、`parse_file`、`parse_catalog_table`、`direct_rows` 或列為 `coverage_gap`，並由第二階段正規化為 current queue schema 的 `doc_profile`、`foundation_doc_status`、`architecture_doc_status`、`ops_doc_status`。
-
-authority 判定依 `$docs-target-catalog` 的 `Authority Disambiguation` 執行；若 entry clue 只是 control-plane source，或同一 scope 有多個 candidate authorities，先分 scope 再交付 handoff。
+分析目前 workspace，建立 source-backed compact handoff catalog。Discovery、classification、handoff 欄位、template、authority 判定與 evidence rules 由 `$docs-target-catalog` 擁有；repo artifact 邊界由 `source-code-to-spec-tools/references/repository-artifact-contract.md` 擁有。
 
 Default output:
 

package/.github/prompts/docs-target-queue-from-catalog.prompt.md

@@ -8,7 +8,7 @@ description: '使用 docs-target-queue-from-catalog skill，依 catalog 指出
 
 使用 `$docs-target-queue-from-catalog` 將既有 catalog、handoff table、metadata extract、query/export result 或 source list 轉成 `docs/docs-target-queue.md`。
 
-正式輸出的 main target table 必須符合 shared queue schema：使用 `doc_profile`、`foundation_doc_status`、`architecture_doc_status`、`ops_doc_status`、`review_status` 與 `document_completed_flag(Y/N)`。輸入、既有 queue 與 normalized source extract 都應先整理成 current schema；不讀取、不保留舊欄位。
+Queue schema、status enum、`source_type` registry 與 `doc_profile` 規則由 `.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md` 與 `.github/skills/source-code-to-spec-tools/scripts/queue_contract.py` 擁有；conversion、source acquisition、normalization、ID preservation、generic writer 與 validation 由 `$docs-target-queue-from-catalog` 擁有。
 
 預設輸入：
 
@@ -17,12 +17,12 @@ description: '使用 docs-target-queue-from-catalog skill，依 catalog 指出
 
 若使用者提供其他 catalog、template、query result、export、source list、config file 或 metadata file，改用使用者提供的來源。
 
-完成條件：
+若同一 source scope 有多個 export/query result，依 skill 的 canonical source gate 先解決來源衝突。
 
-- 正式輸出必須建立或更新 repo root 的 `docs/docs-target-queue.md`。
-- `target/docs-target-queue-from-catalog/**`、temp folder、terminal output 或 raw acquisition extract 只能作為 staging / evidence，不能視為正式輸出。
-- 若 required、complete inventory 或 final row authority 尚未取得，只能依 skill contract 產生 `partial` / `incomplete` output，不可宣告 `docs/docs-target-queue.md` 已完成。
+執行前先載入 repo-local `.github/skills/docs-target-queue-from-catalog/SKILL.md`。若 catalog、handoff、query result 或 source request 指向 DB table、view 或 metadata store，必須同輪載入 `.github/skills/database-query/SKILL.md`，先做 repo-first DB config discovery / read-only acquisition，或記錄具體 acquisition status；不可只因 repo 沒有現成 export 就轉為 coverage gap。
 
-依 `docs-target-queue-from-catalog` agent 的 role / boundary 執行，詳細 conversion、source acquisition、normalization、ID preservation、generic writer、validation 與 cleanup gate 都以 `$docs-target-queue-from-catalog` skill 為準。
+依 `docs-target-queue-from-catalog` agent 的 role / boundary 執行。正式 output 與 staging artifact 邊界由 `$docs-target-queue-from-catalog` 與 `.github/skills/source-code-to-spec-tools/references/repository-artifact-contract.md` 擁有。
+
+Final output 必須寫入 `docs/docs-target-queue.md`。`target/docs-target-queue-from-catalog/**` 只能作為 partial / staging artifact；若本次只產生該路徑，Final response 必須標示為 partial，不可宣告正式 queue 已完成。
 
 Final response 保持精簡：提供 output path、source counts、每個 acquisition source 的 status、count validation 結果、cleanup result，以及 blockers 或 coverage gaps。

package/.github/prompts/generate-docs-index.prompt.md

@@ -0,0 +1,77 @@
+---
+tools: [execute, read, edit, search, todo]
+description: 掃描 docs 路徑下的所有文件，依統一分類整理並產生 docs/index.md 文件索引。
+---
+
+# Generate Docs Index
+
+## Goal
+
+掃描目前 repo 的 `docs/**` 文件，產生或更新 `docs/index.md`。本 prompt 已包含完整規則，不需要額外 skill。
+
+## Scope
+
+- 納入 `docs/**` 下可讀的 reader-facing 文件，例如 Markdown、HTML、text 文件。
+- 排除 `docs/index.md` 本身、binary、runtime cache、temporary output。
+- 不掃描或整理 `target/**`、`.github/**`、`.git/**`。
+
+## Output Format
+
+`docs/index.md` 使用以下結構：
+
+```markdown
+# Docs Index
+
+## 文件總覽
+
+- `檔案總數`: {count}
+- `更新日期`: {YYYY-MM-DD}
+
+#### {分類名稱} 相關文件
+
+| 文件名稱 | 說明 | 文件路徑 |
+| -------- | ---- | -------- |
+| ... | ... | ... |
+```
+
+## Classification
+
+分類標題固定為 `#### {分類名稱} 相關文件`，並依下列順序分類：
+
+1. `docs/feature/<domain>/<target>/...`：使用 `<domain>`，例如 `FeatureGroup 相關文件`。
+2. catalog / queue 文件：`Documentation Target 管理`。
+3. system operations overview 文件：`系統維運總覽`。
+4. repo、toolkit、workflow、guide、HTML guide：`Toolkit 使用指南`。
+5. 其他：`其他文件`。
+
+同一分類內依 `文件名稱` 升冪排序。
+
+## Table Rules
+
+- 每個分類輸出一張表格，欄位固定為 `文件名稱`、`說明`、`文件路徑`。
+- `文件名稱` 優先取第一個 `# H1`；沒有 H1 時取檔名去副檔名。
+- `說明` 優先取 H1 後第一段摘要；沒有摘要時依檔名、路徑與標題做保守描述，不要發明業務內容。
+- `文件路徑` 使用 Markdown link；顯示文字用 repo-relative path，link target 用從 `docs/index.md` 出發的相對路徑，空白與特殊字元需 URL encode。
+
+Example:
+
+```markdown
+#### FeatureGroup 相關文件
+
+| 文件名稱 | 說明 | 文件路徑 |
+| -------- | ---- | -------- |
+| Sample Feature-01-document-foundation-and-business | Sample Feature 的基礎與業務說明文件 | [docs/feature/FeatureGroup/Sample-Feature/Sample%20Feature-01-document-foundation-and-business.md](feature/FeatureGroup/Sample-Feature/Sample%20Feature-01-document-foundation-and-business.md) |
+```
+
+## Checks
+
+- 每個納入範圍的文件只出現一次。
+- 不列出 `docs/index.md` 自己。
+- Markdown table 欄位數一致。
+- 所有 link target 對應到實際存在的檔案。
+- narrative 使用繁體中文；technical identifiers、file paths、Markdown syntax、HTML filename、CLI / config terms 保留英文或原始語法。
+- 若可行，執行 `git diff --check`。
+
+## Final Response
+
+回覆保持精簡，只說明 output path、文件總數、分類名稱，以及是否有無法判讀的檔案。

package/.github/prompts/generate-system-ops-overview.prompt.md

@@ -15,8 +15,9 @@ description: 從 source code、SQL、設定檔、部署線索、依賴檔、Log
 3. System classification gate：依 evidence 判定一種或多種系統型態，例如 web/API、mobile app、desktop application、DB SQL/database program、ERP、batch、CLI、integration service。不得把 web、Java、Spring、REST 或 server deployment 當作預設前提。
 4. Evidence boundary gate：整理 module、function group、runtime/config、external integration、error/log clue、triage direction 與 coverage gap。每個重要結論都標示 source location；不要輸出額外判斷欄位。
 5. Reconciliation gate：若 output file 已存在，先比對既有內容與現行 source evidence，保留仍正確的段落，修正過期、無 evidence、過度功能層化或敏感資訊風險的內容。
-6. Write gate：產生或更新 `S01 系統維運總覽文件`。文件使用繁體中文 narrative；technical identifiers、source paths、config keys、API paths、SQL/database object、class/method names、CLI commands 與 protocol names 保留英文或原始語法。不要輸出 secret value、production 操作指令、完整功能流程或正式 SOP。
-7. Quality gate：依 `$source-code-to-system-ops-overview` 的 quality gate 檢查章節邊界、來源標示、跨技術棧適用性、敏感資訊與功能層內容外溢。若可用，執行 `git diff --check` 或等效 Markdown whitespace 檢查。
+6. Contract gate：寫入前依 `references/system-operations-overview-guideline.md` 檢查必填章節與表格欄位。不得把 guideline 要求使用 Markdown Table 的章節降級成純 narrative；若某欄不適用，填 `N/A`、`Unknown` 或「無法由目前來源確認」。
+7. Write gate：產生或更新 `S01 系統維運總覽文件`。文件使用繁體中文 narrative；technical identifiers、source paths、config keys、API paths、SQL/database object、class/method names、CLI commands 與 protocol names 保留英文或原始語法。不要輸出 secret value、production 操作指令、完整功能流程或正式 SOP。
+8. Quality gate：依 `$source-code-to-system-ops-overview` 的 quality gate 檢查章節邊界、表格 contract、來源標示、跨技術棧適用性、敏感資訊與功能層內容外溢。若可用，執行 `git diff --check` 或等效 Markdown whitespace 檢查。
 
 ## Task
 

package/.github/skills/database-query/SKILL.md

@@ -1,6 +1,6 @@
----
+---
 name: database-query
-description: "通用 DB 查詢 workflow。當 agent 需要從 repo 找出 DB 連線資訊、選擇安全的查詢方式，並透過 helper scripts、native CLI clients 或 repo 既有工具，對 Oracle、PostgreSQL、SQL Server、MySQL、MariaDB、SQLite、IBM Db2、H2 或其他 SQL databases 執行 read-only SQL investigation 時使用。"
+description: "通用 DB 查詢 workflow。當 agent 需要從 repo 找出 DB 連線資訊、選擇安全的查詢方式，並透過 helper scripts、native CLI clients 或 repo 既有工具，對 Oracle、PostgreSQL、SQL Server / Microsoft SQL Server / MS SQL / MSSQL、MySQL、MariaDB、SQLite、IBM Db2、H2 或其他 SQL databases 執行 read-only SQL investigation 時使用。"
 ---
 
 # Database Query
@@ -46,7 +46,7 @@ description: "通用 DB 查詢 workflow。當 agent 需要從 repo 找出 DB 連
    - generic: `DATABASE_URL`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `ConnectionStrings`, `ODBC DSN`, `DSN=`, `Data Source=`, `Server=`, `Host=`, `User ID=`
    - `jdbc:oracle:thin`, `oracle.jdbc`, `tnsnames.ora`, `sqlplus`, `sqlcl`
    - `jdbc:postgresql`, `org.postgresql`, `PGHOST`, `DATABASE_URL`
-   - `jdbc:sqlserver`, `com.microsoft.sqlserver`, `sqlcmd`, `Data Source=`
+   - `jdbc:sqlserver`, `com.microsoft.sqlserver`, `sqlcmd`, `Data Source=`, `Microsoft SQL Server`, `MS SQL`, `MSSQL`
    - `jdbc:mysql`, `jdbc:mariadb`, `com.mysql`, `org.mariadb`
    - `jdbc:db2`, `com.ibm.db2`, `db2 connect`
    - `jdbc:h2`, `jdbc:sqlite`, `sqlite3`
@@ -71,7 +71,7 @@ description: "通用 DB 查詢 workflow。當 agent 需要從 repo 找出 DB 連
 
 只詢問最小必要缺漏資訊：
 
-- `db_type`: Oracle, PostgreSQL, SQL Server, MySQL, MariaDB, SQLite, IBM Db2, H2, etc.
+- `db_type`: Oracle, PostgreSQL, SQL Server / Microsoft SQL Server / MS SQL / MSSQL, MySQL, MariaDB, SQLite, IBM Db2, H2, etc.
 - `host`, `port`, `database` or `service_name`/`SID`, and optional `schema`.
 - `username` and password/token, preferably read-only and temporary.
 - environment name: `local`, `dev`, `test`, `uat`, `prod`.
@@ -87,7 +87,7 @@ description: "通用 DB 查詢 workflow。當 agent 需要從 repo 找出 DB 連
 2. Native DB client:
    - Oracle: `sqlplus` or `sql`
    - PostgreSQL: `psql`
-   - SQL Server: `sqlcmd`
+   - SQL Server / Microsoft SQL Server / MS SQL / MSSQL: `sqlcmd`
    - MySQL/MariaDB: `mysql` or `mariadb`
    - SQLite: `sqlite3`
    - IBM Db2: `db2`
@@ -103,12 +103,14 @@ description: "通用 DB 查詢 workflow。當 agent 需要從 repo 找出 DB 連
 
 - Oracle: `SELECT 1 FROM dual`
 - PostgreSQL: `SELECT 1`
-- SQL Server: `SELECT 1`
+- SQL Server / Microsoft SQL Server / MS SQL / MSSQL: `SELECT 1`
 - MySQL/MariaDB: `SELECT 1`
 - SQLite: `SELECT 1`
 - IBM Db2: `SELECT 1 FROM sysibm.sysdummy1`
 - H2: `SELECT 1`
 
+Native client self-healing：正式查詢前先確認選定的 native client 或 repo helper 能啟動。若 client initialization 失敗且錯誤明確指向 process environment、proxy、encoding、PATH 或 client runtime 設定，允許在不修改 repo、不寫入 credential file 的前提下，以乾淨 child process 或 current process env 做一次最小重試；vendor-specific retry pattern 放在 `references/client-commands.md`。若重試成功，記錄 self-healing action；若仍失敗，才回報 `connection_failed`、`missing_tool` 或其他具體 status，並保留不含 secrets 的錯誤摘要。
+
 如果 connection 失敗，回報精確但不含 secrets 的錯誤類型：network、auth、service/database name、missing client、missing driver、SSL/TLS、VPN/bastion、permission denied 或 syntax mismatch。
 
 若 repo 有多組連線線索、同時存在多個 datasource，或 user 問題依賴特定 schema / service，`SELECT 1` 後再執行 identity query，記錄目前 session 的 user、schema、service / database。例如 Oracle 可用 `SELECT USER, SYS_CONTEXT('USERENV','CURRENT_SCHEMA'), SYS_CONTEXT('USERENV','SERVICE_NAME') FROM dual`；其他 DB 使用對應 identity function。

package/.github/skills/database-query/references/client-commands.md

@@ -18,6 +18,14 @@
 sqlplus -L /nolog
 ```
 
+如果 `sqlplus -V` 或 `sqlplus -L /nolog` 出現 `Error 46 initializing SQL*Plus`、`HTTP proxy setting has incorrect value` 或 `SP2-1502`，先用乾淨的 child process 移除 proxy env 後重試：
+
+```powershell
+cmd /c "set HTTP_PROXY=& set HTTPS_PROXY=& set ALL_PROXY=& set GIT_HTTP_PROXY=& set GIT_HTTPS_PROXY=& set NO_PROXY=& sqlplus -V"
+```
+
+若版本檢查成功，後續 Oracle read-only query 也應在同樣清掉 proxy env 的 child process 或 helper wrapper 內執行，並在 acquisition ledger 記錄 `sqlplus proxy env cleared before retry`。若清掉 proxy 後仍失敗，才將狀態記為 `connection_failed` 或 `missing_tool`。
+
 接著在 client session 內連線：
 
 ```sql
@@ -69,7 +77,7 @@ WHERE table_schema = '<schema>'
 ORDER BY ordinal_position;
 ```
 
-## SQL Server
+## SQL Server / Microsoft SQL Server / MS SQL / MSSQL
 
 建議使用的 client: `sqlcmd`。
 

package/.github/skills/database-query/scripts/find_db_config.py

@@ -100,7 +100,7 @@ CONFIG_NAMES = TEXT_NAMES | {
 DB_PATTERNS = [
     ("oracle", re.compile(r"jdbc:oracle:thin|oracle\.jdbc|tnsnames\.ora|SERVICE_NAME|ORACLE_SID", re.I)),
     ("postgresql", re.compile(r"jdbc:postgresql|org\.postgresql|PGHOST|PGDATABASE|postgres(?:ql)?://", re.I)),
-    ("sqlserver", re.compile(r"jdbc:sqlserver|com\.microsoft\.sqlserver|sqlcmd|Data Source=|Initial Catalog=", re.I)),
+    ("sqlserver", re.compile(r"jdbc:sqlserver|com\.microsoft\.sqlserver|sqlcmd|Data Source=|Initial Catalog=|Microsoft SQL Server|MS SQL|MSSQL", re.I)),
     ("mysql", re.compile(r"jdbc:mysql|com\.mysql|mysql://|MYSQL_", re.I)),
     ("mariadb", re.compile(r"jdbc:mariadb|org\.mariadb|mariadb://|MARIADB_", re.I)),
     ("db2", re.compile(r"jdbc:db2|com\.ibm\.db2|DB2", re.I)),