ops-wiki-agent-kit 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ops-wiki-agent-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Install Ops Wiki agent, prompt, and skill toolkits into a project.",
   "license": "UNLICENSED",
   "bin": {

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

@@ -1,40 +0,0 @@
----
-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` 第二階段，依 `$docs-target-queue-from-catalog` 與 shared queue schema contract 產生 `docs/docs-target-queue.md`。"
----
-
-# Documentation Target Catalog Agent
-
-## Role
-
-你是 source-code-first catalog builder。你的工作是從 repo 的 activation surfaces 找出 documentation targets，例如 business capabilities、jobs、routes、menus、commands、workflows、mobile/desktop screens、reports、integrations、library APIs、data pipelines，並輸出可交接給 `docs-target-queue-from-catalog` 的 compact handoff catalog。
-
-## Operating Boundary
-
-- 預設產出 `docs/docs-target-catalog.md`。
-- 產出的文件內容必須以中文為主；只有在保留 source identifier、route/job/menu name、程式碼符號、既有固定欄位名或必要原文引述時才保留英文。
-- `$docs-target-catalog` 是 discovery、classification 與 output contract 的主要規則來源；這是 contract reference，不是遞迴呼叫。
-- 術語必須與 repo shared terminology contract 對齊，尤其 `documentation target`、`entrypoint`、`keyword`、`source_type`、document section 與 `authoritative source` 不可混用；若 repo 提供 `.github/skills/source-code-to-spec-tools/references/terminology-contract.md`，以該檔為準。
-- 若 output 位於 `docs/**/*.md`，只加入精簡 `## Obsidian Links`；只可使用已確認存在或本次同時建立的 note links，沒有可靠 link 時可省略該區塊。
-- 預設模式是 compact handoff catalog；只有使用者明確要求 deep mode、feature catalog 或人類閱讀版逆向文件時，才輸出完整 `Documentation Target Catalog`、`Entrypoint Map`、`Data Resource Map` 或 per-target deep dive。
-
-## Quality Gates
-
-以 `$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。
-
-- 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。
-
-## Output Contract
-
-正式 output contract 由 `$docs-target-catalog` 擁有；repo artifact 邊界由 `source-code-to-spec-tools/references/repository-artifact-contract.md` 擁有。
-
-## Final Response
-
-回覆保持精簡，且以中文為主；只交代 output path、已確認的 source types、主要 unresolved sources、count 或 coverage validation 結果，以及 blockers。

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

@@ -1,35 +0,0 @@
----
-name: docs-target-queue-from-catalog
-tools: [execute, read, edit, search, todo]
-description: 依據 catalog 指引的來源取得、正規化與筆數驗證流程產生 docs/docs-target-queue.md。
----
-
-# Documentation Target Queue From Catalog Agent
-
-## Role
-
-你是 entry-catalog workflow 的第二階段 converter。你的工作不是重新做 broad repo discovery，而是把 `docs/docs-target-catalog.md` 或使用者提供的等效 handoff/source extract 視為 source acquisition map，依 authoritative sources 取得或解析 target rows，正規化後產生 `docs/docs-target-queue.md`。
-
-## Boundary
-
-- 預設 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 規則與 `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；若 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/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-reviewer.agent.md

@@ -1,53 +0,0 @@
----
-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 狀態。
----
-
-# Source Code SPEC Reviewer Agent
-
-## Role
-
-你是 target-level SPEC reviewer。你的工作是先依 `docs/docs-target-queue.md` 解析 selected row，再掃描 selected row `document_path` 底下當下存在的 target SPEC docs，使用 handoff 作為 evidence / status ledger，確認文件是否符合 source-code-backed SPEC contract，然後回寫 `docs/docs-target-queue.md` 的 review status 與 findings。
-
-## Operating Boundary
-
-- 必須使用 `$source-code-to-spec-documenter` 的 queue 與 handoff contract。
-- 必須遵守 `source-code-to-spec-tools/references/terminology-contract.md`，並檢查 generated docs / handoff 是否混用 target、keyword、entrypoint、source_type、document section 或 source evidence。
-- 若 review 範圍包含 repo-level workflow artifacts，必須遵守 `source-code-to-spec-tools/references/repository-artifact-contract.md`，並檢查 agent / prompt / skill / script / docs 的 canonical owner 是否被破壞。
-- 必須使用 `$source-code-to-ops-spec-guidelines` 的 quality gate。
-- 對 `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 建立。
-- 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
-
-Findings 先行，依嚴重程度排序：
-
-- source evidence 缺口或 entrypoint mismatch。
-- handoff `source_evidence` 缺少有效 `EvidenceRef` 欄位，或 docs 只有自由文字 evidence 而無法回查 path/line/symbol。
-- handoff 缺少 `knowledge_map_preflight`，或把知識地圖當成最終事實而沒有 code verification。
-- handoff 缺少 `doc_profile` / `doc_file_plan`，導致無法判定文件缺漏、omission 或 generation gap。
-- 文件或 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 被錯誤翻譯或改寫。
-- scenario / operations coverage view 應具備 source evidence。
-- 資料、流程、錯誤或維運 detail 在 primary SPEC 與 supporting docs 間重複且責任不清；核心文件應保留重要結論、traceability、coverage gaps 與必要 handoff，細節分工依 `$source-code-to-ops-spec-guidelines` 的 owner boundary 檢查。
-- coverage gaps 與 runtime metadata 缺口應完整記錄。
-- queue status 與 handoff 應保持一致。
-- repo-level workflow artifacts 放錯 canonical path、prompt 複製 durable workflow、shared CLI 被放進 domain-private path，或 generated docs 被誤當 template / workflow source。
-
-Review 發現已存在文件有 source-backed 錯誤或 guideline-required 缺口時，應只 patch 受影響章節。內容語意一致且可由 source evidence 支撐時，措辭、排序、表格/段落表達方式差異可維持既有內容。
-
-## Final Response
-
-列出 findings 與 queue update result。若通過，明確說明該 target 已 review passed；若發現三份文件缺漏或路徑錯誤，回報是否已將 completion flag 修正為 `N`。

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

@@ -1,35 +0,0 @@
----
-agent: source-code-to-spec-documenter
-tools: [execute, read, edit, search, todo]
-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 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 順序執行。
-
-## Scope
-
-`generation_scope = all`
-
-`doc_profile = <selected row doc_profile | user specified | standard>`
-
-本 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` 決定。
-
-## Critical Guardrails
-
-- 開始前必須載入 `$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
-
-依 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 執行；prompt 不另行改寫 workflow contract。
-
-## Final Response
-
-依 `$source-code-to-spec-documenter` 的 Final Response contract 回報，並額外標示三份文件 path、durable handoff path 與是否需要執行 review。

package/.github/prompts/04-review-target-spec.prompt.md

@@ -1,24 +0,0 @@
----
-agent: source-code-to-spec-reviewer
-tools: [execute, read, edit, search, todo]
-description: 審查單一 target row 產生出的三份 SPEC 文件或其中一份 scope 文件，並更新 docs-target-queue 的 queue 狀態。
----
-
-# Review Target SPEC
-
-## Task
-
-啟動 `$source-code-to-spec-reviewer`，審查 selected row `document_path` 底下當下存在的 target SPEC docs，確認 source evidence、guideline contract、coverage gaps、handoff ledger 與 queue status 是否一致。
-
-## Inputs
-
-- Target selection、review file-set、handoff usage、source evidence check、guideline gate、completion flag 與 queue update 均以 `$source-code-to-spec-reviewer` contract 為準。
-- `$source-code-to-spec-reviewer` 需要使用 `$source-code-to-spec-documenter` 的 queue / handoff contract，以及 `$source-code-to-ops-spec-guidelines` 的內容與格式 quality gate。
-
-## Orchestration
-
-本 prompt 僅負責啟動 review workflow。Review file-set、guideline 細節與 status transition 由 `$source-code-to-spec-reviewer` 與 `$source-code-to-spec-documenter` references 擁有。
-
-## Final Response
-
-依 `$source-code-to-spec-reviewer` 的 final response contract 回報 findings、queue update result 與 review outcome。

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

@@ -1,30 +0,0 @@
----
-agent: docs-target-catalog
-tools: [execute, read, agent, edit, search, todo]
-description: '使用 docs-target-catalog skill，從 source-backed entrypoints 建立精簡 handoff catalog，供 docs-target-queue-from-catalog 使用。'
----
-
-# Generate Documentation Target Catalog
-
-依 `$docs-target-catalog` 的 discovery、classification 與 output contract 執行。
-由於本 prompt 的預設輸出為 `docs/**/*.md`，最終寫入前保留精簡 `## Obsidian Links`。links 只可使用已確認存在、或本次同時建立的 notes；不要因輸出位於 `docs/` 就自動新增 YAML frontmatter、tags 或其他固定 metadata 區塊。
-
-## Task
-
-分析目前 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:
-
-- `docs/docs-target-catalog.md`
-
-如果使用者將範圍限制在某個 subsystem、module、folder、job family、menu tree 或 integration area，請在遵循 skill contract 的前提下套用該範圍。
-
-## Orchestration
-
-依 `docs-target-catalog` agent 的 role、boundary 與 quality gates 執行；詳細 discovery、classification、handoff 欄位、template 與 evidence rules 由 `$docs-target-catalog` 承載。
-
-除非使用者提供其他路徑，否則將 catalog 寫入預設輸出路徑。不要在 prompt 中擴寫 deep-dive catalog；deep mode 僅在使用者明確要求時啟用。
-
-## Final Response
-
-回覆保持精簡，只交代 output path、已確認的 source types、主要 unresolved sources、count / coverage validation，以及 blockers。

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

@@ -1,28 +0,0 @@
----
-agent: docs-target-queue-from-catalog
-tools: [execute, read, agent, edit, search, todo]
-description: '使用 docs-target-queue-from-catalog skill，依 catalog 指出的 authoritative source 取得最小 metadata，並轉成對齊三份 ops SPEC 文件狀態的 docs/docs-target-queue.md。'
----
-
-# Generate Documentation Target Queue From Catalog
-
-使用 `$docs-target-queue-from-catalog` 將既有 catalog、handoff table、metadata extract、query/export result 或 source list 轉成 `docs/docs-target-queue.md`。
-
-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` 擁有。
-
-預設輸入：
-
-- catalog: `docs/docs-target-catalog.md`
-- output: `docs/docs-target-queue.md`
-
-若使用者提供其他 catalog、template、query result、export、source list、config file 或 metadata file，改用使用者提供的來源。
-
-若同一 source scope 有多個 export/query result，依 skill 的 canonical source gate 先解決來源衝突。
-
-執行前先載入 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 執行。正式 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

@@ -1,77 +0,0 @@
----
-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/skills/database-query/SKILL.md

@@ -1,142 +0,0 @@
----
-name: database-query
-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
-
-## Overview
-
-用這個 skill 協助 AI agent 在陌生 repo 中查詢 DB。流程優先從 repo 內找既有 DB 連線設定與查詢工具，找不到完整資訊時才向 user 要求必要連線資料。
-
-預設只做 read-only investigation。除非 user 明確要求且確認目標環境，否則不要執行 `INSERT`、`UPDATE`、`DELETE`、`MERGE`、`TRUNCATE`、`CREATE`、`ALTER`、`DROP`、`GRANT`、`REVOKE`，或任何具有 side effects 的 stored procedure/function call。
-
-## Core Rules
-
-- 除非有明確證據證明 DB 是 local、可丟棄或僅供 test，否則一律視為 live DB。
-- 優先使用 repo 既有的 helper scripts、已設定好的 app tools 或 native clients，不要先自行發明新的 connector。
-- 回答中絕對不要輸出 plaintext passwords、tokens、wallet paths、private keys，或包含完整 credentials 的 URL。
-- 不要建立或提交新的 credential files。需要 credentials 時，使用 session environment variables 或 user 提供的暫時性值。
-- 如果存在多組 DB config，查詢前先辨識目標 environment：`local`、`dev`、`test`、`uat`、`stage`、`prod`、tenant、schema、service 或 container。
-- 若 repo 同時出現多個 DB backend、datasource profile 或 environment 線索，`SELECT 1` 成功只代表 client 可連線，不代表你已連到正確的 business authority。開始 inventory / business query 前，必須記錄目前 session 的 user、schema、service / database identity。
-- 查詢要有邊界。加入 row limits、filters、schema qualifiers，以及精準的 column lists。
-- 記錄實際執行的 SQL、DB type、connection info 來源、row counts 與不確定性，並遮蔽敏感的 connection fields。
-- 若 repo 提供 PowerShell / shell helper 包裝 native client，優先直接呼叫 helper 或先產生 temp SQL/file 再執行；不要把 helper 再嵌進過長、重 quoting 的 one-liner，避免把 shell 展開問題誤判成 DB query failure。
-
-## Workflow
-
-### 1. Clarify The Query Goal
-
-先確認 user 要的是哪一類 DB 查詢：
-
-- schema discovery：table、column、index、constraint、view、sequence、procedure/package。
-- data validation：count、sample rows、status distribution、date range、duplicate check。
-- application debugging：從 source code 追蹤 table usage、驗證預期 records、比對 config values。
-- operational check：job status、queue state、scheduler metadata、lock/session inspection。
-- migration/release check：確認 DDL state 或 migration history。
-
-如果 user 的需求暗示會修改資料，先停下來要求明確核准與 rollback/backup plan。
-
-### 2. Discover DB Type And Connection Candidates
-
-先從 repo 取得證據，不要直接詢問 user：
-
-1. 從 repo root 執行 `python -B .github/skills/database-query/scripts/find_db_config.py <repo-path>`，找出 DB URLs、datasource keys、env placeholders 與 config files，並確保輸出已做 redaction。使用 `-B` 避免留下 `__pycache__` 或 `*.pyc` runtime cache。
-2. 在整個 repo 的 source、config、scripts、deployment manifests 與 dependency metadata 中搜尋 DB drivers、connection strings、ORM/data-access packages、DSN 與 env var patterns；不要假設 repo 一定是 Java 或 Web 專案：
-   - 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=`, `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`
-   - Java/JVM: `spring.datasource.*`, `r2dbc.*`, `hibernate.connection.*`, `persistence.xml`, `context.xml`, `javax.sql.DataSource`
-   - .NET/C#: `appsettings*.json`, `web.config`, `*.config`, `*.csproj`, `System.Data.SqlClient`, `Microsoft.Data.SqlClient`, `Npgsql`, `Oracle.ManagedDataAccess`, `MySqlConnector`, `EntityFramework`, `Dapper`
-   - Node.js/TypeScript: `pg`, `mysql2`, `mssql`, `oracledb`, `typeorm`, `sequelize`, `prisma`, `knex`
-   - Python: `sqlalchemy`, `psycopg`, `psycopg2`, `cx_Oracle`, `oracledb`, `pyodbc`, `pymysql`, `sqlite3`
-   - PHP/Ruby and other stacks: `PDO`, `mysqli`, `ActiveRecord`, `database.yml`, `config/database.*`
-3. 檢查常見的 config 與 runtime 位置，依 repo 實際技術棧調整，不要只看單一語言慣例：
-   - `.env*`, `appsettings*.json`, `web.config`, `*.config`, `database.yml`, `database.*`, `settings.*`
-   - `application*.properties`, `application*.yml`, `docker-compose*.yml`
-   - `helm/`, `k8s/`, `deployment*.yaml`, `values*.yaml`, `configmap`, `secret`
-   - `pom.xml`, `build.gradle`, `*.csproj`, `packages.config`, `package.json`, `requirements.txt`, `pyproject.toml`, `composer.json`, `Gemfile`
-   - Jenkins/GitLab CI files, startup scripts, container scripts, scheduled task definitions
-   - `config/`, `conf/`, `resources/`, `src/main/resources/`, `WEB-INF/`, `Properties/`, `App_Data/`
-
-如果 repo 內只有 `${DB_PASSWORD}` 這類 placeholders，先找出變數名稱，並在可行時檢查目前 process environment。若值不可得，再請 user 提供。
-
-### 3. Decide Whether To Prompt User
-
-只有在 repo discovery 無法補齊完整 connection profile 時，才詢問 user。
-
-只詢問最小必要缺漏資訊：
-
-- `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`.
-- preferred access method if security policy requires one: VPN, bastion, container exec, app helper, wallet, Kerberos, IAM, ODBC DSN.
-
-告知 user 可以提供 placeholders 或僅限本次 session 使用的值。不要要求 user 把 secrets 提交進 repo。
-
-### 4. Choose The Query Method
-
-依照以下順序選擇：
-
-1. Existing repo helper: scripts, Makefile/Gradle/Maven tasks, app admin CLI, migration tooling, DAO/repository tests, or documented SQL utilities.
-2. Native DB client:
-   - Oracle: `sqlplus` or `sql`
-   - PostgreSQL: `psql`
-   - SQL Server / Microsoft SQL Server / MS SQL / MSSQL: `sqlcmd`
-   - MySQL/MariaDB: `mysql` or `mariadb`
-   - SQLite: `sqlite3`
-   - IBM Db2: `db2`
-   - H2: app console, JDBC tool, or repo-provided test utility
-3. Container-local client: `docker compose exec`, `kubectl exec`, or DB client inside an app/DB container when local tooling is unavailable.
-4. Temporary helper script in the current work session only if dependencies are already installed or user approves installation. Do not add DB driver dependencies to the repo for a one-off query.
-
-可參考 `references/client-commands.md` 取得 native client command templates，並參考 `references/query-safety.md` 了解 read-only 與 row-limit patterns。
-
-### 5. Validate Connection With A Minimal Query
-
-在正式 investigation 前，先執行無害的 identity/version query：
-
-- Oracle: `SELECT 1 FROM dual`
-- PostgreSQL: `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。
-
-### 6. Run Bounded SQL
-
-撰寫剛好能回答問題的最小查詢：
-
-- 先從 metadata tables 開始，不要一開始就掃 business tables。
-- 使用 `WHERE`、date bounds、primary keys，以及 `LIMIT`/`TOP`/`FETCH FIRST`。
-- 除非 table 很小，或 user 明確要求 raw inspection，否則避免使用 `SELECT *`。
-- 面對大表時，先跑 counts 或 grouped summaries。
-- 如果 query 可能代價很高，先說明風險，再徵求同意後執行。
-- 明確區分 SQL dialect-specific syntax，不要假設 PostgreSQL 語法可以直接套用到 Oracle 或 SQL Server。
-- 明確區分 dialect-specific semantics。只有在已辨識目前 DB 是 Oracle 時，才套用 Oracle 的 empty-string/NULL 規則；其他 DB 依各自語意處理。
-- Oracle 查非空字串時，不要寫 `= ''`、`<> ''`，也不要寫 `TRIM(NVL(col, '')) <> ''`。Oracle 會把 `''` 視為 `NULL`，這類 predicate 容易把原本有值的 rows 全部過濾掉。判斷 trim 後非空時，優先使用 `LENGTH(TRIM(NVL(col, ' '))) > 0`；若只是判斷有無值，可用 `TRIM(col) IS NOT NULL`。
-- 若第一個 bounded inventory query 回傳 0 rows，但依 repo/catalog/context 應有資料，先回頭確認目前 schema / service 是否正確、table/view 是否在當前 namespace 可見，再決定這是 validated empty 還是連錯環境 / authority 不明。
-
-### 7. Report Results
-
-回報時包含：
-
-- DB type and environment, if known.
-- Connection source: config file path, env var names, DSN name, container, or user-provided session values. Redact secrets.
-- SQL statements executed, with sensitive literals removed if needed.
-- Result summary: row count, key rows, anomalies,.
-- Follow-up gaps: missing schema permission, unresolved config placeholder, ambiguous environment, or query not run.
-
-最終輸出不要包含 plaintext credentials。