ops-wiki-agent-kit 0.1.0 → 0.1.2

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

@@ -1,51 +0,0 @@
----
-name: source-code-to-spec-reviewer
-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 建立。
-- 若三份 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 發現三份文件實際缺漏或路徑錯誤時同步修正。
-
-## 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 缺漏。
-- 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 建立 discovery baseline，並一次產生三份 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` 擁有。
-
-不要在 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；selected output files、coverage handling 與 output action 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 決定。
-
-## Generation Detail
-
-本次 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，不可用摘要取代缺漏章節。
-
-## Orchestration
-
-依 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 執行；prompt 不另行改寫 workflow contract。
-
-## Final Response
-
-依 `$source-code-to-spec-documenter` 的 Final Response contract 回報，並額外標示三份文件 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,32 +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。這份 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。
-
-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`。
-
-正式輸出的 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；不讀取、不保留舊欄位。
-
-預設輸入：
-
-- catalog: `docs/docs-target-catalog.md`
-- output: `docs/docs-target-queue.md`
-
-若使用者提供其他 catalog、template、query result、export、source list、config file 或 metadata file，改用使用者提供的來源。
-
-完成條件：
-
-- 正式輸出必須建立或更新 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` 已完成。
-
-依 `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 為準。
-
-Final response 保持精簡：提供 output path、source counts、每個 acquisition source 的 status、count validation 結果、cleanup result，以及 blockers 或 coverage gaps。

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

@@ -1,140 +0,0 @@
----
-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 時使用。"
----
-
-# 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=`
-   - `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, 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: `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: `SELECT 1`
-- MySQL/MariaDB: `SELECT 1`
-- SQLite: `SELECT 1`
-- IBM Db2: `SELECT 1 FROM sysibm.sysdummy1`
-- H2: `SELECT 1`
-
-如果 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。

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

@@ -1,189 +0,0 @@
-# DB Client Commands
-
-這份 reference 提供使用 native CLI 進行查詢的方式。實際使用時需依 repo 的 DB type、environment、schema、VPN/bastion/container 條件調整。
-
-## General Handling
-
-- 優先使用 password prompts、wallets、DSN 或 session environment variables，避免把 password 直接放在 command-line arguments。
-- 查詢完成後，清除暫時性的 environment variables。
-- 可以的話，優先使用 read-only users。
-- query files 應維持為暫時用途，不要 commit。
-- logs 與 final answers 中的 credentials 要遮蔽。
-
-## Oracle
-
-建議使用的 clients: `sqlplus`、Oracle SQLcl `sql`。
-
-```powershell
-sqlplus -L /nolog
-```
-
-接著在 client session 內連線：
-
-```sql
-connect <username>/<password>@//<host>:<port>/<service_name>
-SELECT 1 FROM dual;
-exit
-```
-
-實用的 inspection queries：
-
-```sql
-SELECT owner, table_name
-FROM all_tables
-WHERE owner = UPPER('<schema>')
-FETCH FIRST 50 ROWS ONLY;
-
-SELECT owner, table_name, column_name, data_type, nullable
-FROM all_tab_columns
-WHERE owner = UPPER('<schema>')
-  AND table_name = UPPER('<table_name>')
-ORDER BY column_id;
-```
-
-較舊的 Oracle versions 可能需要使用 `WHERE ROWNUM <= 50`，而不是 `FETCH FIRST`。
-
-## PostgreSQL
-
-建議使用的 client: `psql`。
-
-```powershell
-$env:PGPASSWORD = "<password>"
-psql -h <host> -p <port> -U <username> -d <database> -c "SELECT 1;"
-Remove-Item Env:\PGPASSWORD
-```
-
-實用的 inspection queries：
-
-```sql
-SELECT table_schema, table_name
-FROM information_schema.tables
-WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
-ORDER BY table_schema, table_name
-LIMIT 50;
-
-SELECT column_name, data_type, is_nullable
-FROM information_schema.columns
-WHERE table_schema = '<schema>'
-  AND table_name = '<table_name>'
-ORDER BY ordinal_position;
-```
-
-## SQL Server
-
-建議使用的 client: `sqlcmd`。
-
-```powershell
-$env:SQLCMDPASSWORD = "<password>"
-sqlcmd -S <host>,<port> -d <database> -U <username> -Q "SELECT 1;"
-Remove-Item Env:\SQLCMDPASSWORD
-```
-
-若使用 Windows authentication：
-
-```powershell
-sqlcmd -S <host>,<port> -d <database> -E -Q "SELECT 1;"
-```
-
-實用的 inspection queries：
-
-```sql
-SELECT TOP (50) TABLE_SCHEMA, TABLE_NAME
-FROM INFORMATION_SCHEMA.TABLES
-WHERE TABLE_TYPE = 'BASE TABLE'
-ORDER BY TABLE_SCHEMA, TABLE_NAME;
-
-SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE
-FROM INFORMATION_SCHEMA.COLUMNS
-WHERE TABLE_SCHEMA = '<schema>'
-  AND TABLE_NAME = '<table_name>'
-ORDER BY ORDINAL_POSITION;
-```
-
-## MySQL And MariaDB
-
-建議使用的 clients: `mysql`、`mariadb`。
-
-```powershell
-$env:MYSQL_PWD = "<password>"
-mysql --host=<host> --port=<port> --user=<username> --database=<database> --execute="SELECT 1;"
-Remove-Item Env:\MYSQL_PWD
-```
-
-實用的 inspection queries：
-
-```sql
-SELECT TABLE_SCHEMA, TABLE_NAME
-FROM information_schema.TABLES
-WHERE TABLE_SCHEMA = '<database>'
-ORDER BY TABLE_NAME
-LIMIT 50;
-
-SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE
-FROM information_schema.COLUMNS
-WHERE TABLE_SCHEMA = '<database>'
-  AND TABLE_NAME = '<table_name>'
-ORDER BY ORDINAL_POSITION;
-```
-
-## SQLite
-
-建議使用的 client: `sqlite3`。
-
-```powershell
-sqlite3 <database_file> "SELECT 1;"
-```
-
-實用的 inspection commands：
-
-```sql
-.tables
-PRAGMA table_info('<table_name>');
-SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') ORDER BY name LIMIT 50;
-```
-
-## IBM Db2
-
-建議使用的 client: `db2`。
-
-```powershell
-db2 connect to <database> user <username> using <password>
-db2 -x "SELECT 1 FROM sysibm.sysdummy1"
-db2 connect reset
-```
-
-實用的 inspection queries：
-
-```sql
-SELECT tabschema, tabname
-FROM syscat.tables
-WHERE type = 'T'
-ORDER BY tabschema, tabname
-FETCH FIRST 50 ROWS ONLY;
-
-SELECT colname, typename, nulls
-FROM syscat.columns
-WHERE tabschema = UPPER('<schema>')
-  AND tabname = UPPER('<table_name>')
-ORDER BY colno;
-```
-
-## H2
-
-H2 常見於 tests 或 local development 中以 embedded 方式使用。優先使用 repo 的 test profile 或 app 提供的 console/tooling。
-
-常見的 JDBC URL patterns：
-
-```text
-jdbc:h2:mem:<database>
-jdbc:h2:file:<path>
-```
-
-實用的 inspection query：
-
-```sql
-SELECT TABLE_SCHEMA, TABLE_NAME
-FROM INFORMATION_SCHEMA.TABLES
-ORDER BY TABLE_SCHEMA, TABLE_NAME
-LIMIT 50;
-```

package/.github/skills/database-query/references/query-safety.md

@@ -1,109 +0,0 @@
-# Query Safety
-
-## Read-Only Default
-
-除非 user 明確要求資料修改，否則預設只允許 metadata 與 read-only `SELECT`。如果查詢內容涉及下列操作，必須先停下來確認：
-
-- `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `TRUNCATE`
-- `CREATE`, `ALTER`, `DROP`
-- `GRANT`, `REVOKE`
-- 可能修改資料的 stored procedure/function/package calls
-- scheduler/job control、queue dequeue、lock/session kill
-
-## Row Limits By Dialect
-
-請使用有筆數上限的查詢：
-
-```sql
--- PostgreSQL, MySQL, MariaDB, SQLite, H2
-SELECT <columns>
-FROM <table>
-WHERE <condition>
-LIMIT 50;
-```
-
-```sql
--- SQL Server
-SELECT TOP (50) <columns>
-FROM <schema>.<table>
-WHERE <condition>;
-```
-
-```sql
--- Oracle 12c+, IBM Db2
-SELECT <columns>
-FROM <schema>.<table>
-WHERE <condition>
-FETCH FIRST 50 ROWS ONLY;
-```
-
-```sql
--- Older Oracle
-SELECT <columns>
-FROM <schema>.<table>
-WHERE <condition>
-  AND ROWNUM <= 50;
-```
-
-## Oracle Empty String Semantics
-
-這一節只在已確認 `db_type`、driver 或 client session 是 Oracle 時適用。不要把這組規則套用到 PostgreSQL、SQL Server、MySQL、MariaDB、SQLite、Db2 或其他 DB。
-
-Oracle 會把 `''` 視為 `NULL`。因此 Oracle predicate 對空字串的處理要直接用 `NULL` 語意，不要把 `''` 當成一般字串比較。
-
-- 不要用 `= ''`、`<> ''`，也不要用 `TRIM(NVL(<column>, '')) <> ''` 判斷空值或非空值。
-- 判斷 `NULL` / 非 `NULL` 時，使用 `IS NULL` 或 `IS NOT NULL`。
-- 判斷 trim 後是否有內容時，優先使用 `LENGTH(TRIM(NVL(<column>, ' '))) = 0` 或 `> 0`；若只需要確認 trim 後有值，可用 `TRIM(<column>) IS NOT NULL`。
-- 若 query 結果意外為 0 rows，先檢查是否誤用了 Oracle empty-string 語意，再解讀資料是否真的為空。
-
-範例：
-
-```sql
--- Avoid in Oracle
-WHERE path_program <> ''
-```
-
-```sql
--- Avoid in Oracle even after wrapping with TRIM/NVL
-WHERE TRIM(NVL(path_program, '')) <> ''
-```
-
-```sql
--- Prefer when checking for the presence of a trimmed value
-WHERE TRIM(path_program) IS NOT NULL
-```
-
-```sql
--- Prefer when checking for a non-empty value after trimming
-WHERE LENGTH(TRIM(NVL(path_program, ' '))) > 0
-```
-
-## Safer Investigation Pattern
-
-1. 先透過 metadata 確認 schema/table 存在。
-2. 只有在安全的前提下，才檢查大致筆數或精確 count。
-3. 先查 grouped summary，再看 row sample。
-4. 以關鍵欄位查詢範圍較小的 sample。
-5. 依照 user request 加上業務過濾條件。
-
-範例：
-
-```sql
-SELECT status, COUNT(*) AS row_count
-FROM <schema>.<table>
-WHERE created_at >= <start_date>
-GROUP BY status
-ORDER BY row_count DESC;
-```
-
-## Reporting
-
-最終回覆應提供足夠證據，讓結果可被重現，同時避免洩露敏感資訊：
-
-- connection source：`src/main/resources/application-dev.yml`、`.env`、`docker-compose.yml`、user-provided session value
-- DB type 與 target environment
-- SQL statements；如果使用了敏感 literal，則改提供摘要化 SQL
-- result rows 或 aggregate summary
-- 不確定之處與 permission gaps
-
-不可包含 plaintext password values、token values、帶有憑證資訊的 URL，或任何 private network secrets。