ops-wiki-agent-kit 0.1.0 → 0.1.2

package/.github/skills/docs-target-catalog/references/entrypoint-source-patterns.md

@@ -1,83 +0,0 @@
-# Entrypoint Source Patterns
-
-在辨識 repo 特徵，或判斷真正的 documentation target entrypoint 可能定義在哪裡時，可參考這份文件。副檔名只能視為弱訊號，activation source 才是最強的邊界證據。
-
-## Authority Ranking
-
-1. Runtime registry 與 persisted metadata：例如 menu/navigation/permission tables、route registry、scheduler definition、ERP program/transaction metadata、deployment config、external menu/config files。
-2. Direct activation code：例如 controllers、annotated routes、client-side routers、command handlers、hardcoded menu/navigation declarations、job classes、queue/file consumers。
-3. Call-chain evidence：可追蹤從 handler 到 service，再到 data resource 的呼叫鏈。
-4. Naming convention 與 file type：可作為搜尋線索，但不足以單獨確認 target boundary。
-
-## Common Runtime Types
-
-| Runtime type   | Strong entry sources                                                                                                                     | Supporting evidence                                                             |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| Web UI         | Menu config/table、frontend router、server routes、controller/action mappings，以及 JSP/Struts/Spring/.NET route config                  | JSP/Razor/HTML views、JS handlers、form actions、breadcrumbs、permission checks |
-| Java/JSP       | `web.xml`、servlet mappings、Spring `@RequestMapping`、Struts action XML、Tiles/menu JSP，以及 Quartz/Spring Batch config                | JSP includes、action classes、service/DAO calls、SQL mapper files               |
-| .NET Web       | `Program.cs`、`Startup.cs`、route maps、MVC/API controllers、Razor Pages，以及 `Route`、`HttpGet`、`HttpPost` 這類 attributes            | View files、model binders、services、repositories                               |
-| JavaScript SPA | React Router、Vue Router、Angular routes、Next/Nuxt routes、navigation config、route guards                                              | Page components、API clients、state modules                                     |
-| Mobile         | Android manifest、navigation XML、Activity/Fragment/Compose navigation、iOS storyboard、SwiftUI navigation、deep links、tabs             | View models、services、local DB access、permission declarations                 |
-| Desktop        | Menu strip、toolbar/command definitions、XAML commands、form/window registries、event handlers                                           | Designer files、forms/windows、service calls、reports                           |
-| ERP            | menu/responsibility setup、program/transaction registry、concurrent programs、report definitions、form metadata、vendor extension config | PL/SQL packages、forms、reports、seeded setup SQL                               |
-| DB-heavy       | 對 app 對外暴露的 stored procedures/packages、report SQL、ETL definitions、DBMS scheduler、SQL Agent jobs                                | Tables/views、triggers、grants、synonyms                                        |
-| Batch/job      | Cron、Quartz、Spring Batch、Hangfire、Windows Task、DBMS_SCHEDULER、SQL Agent、batch launchers                                           | Job classes、step definitions、file/queue/table resources                       |
-| Integration    | REST/SOAP endpoints、queue topics、message consumers、file watchers、ETL jobs、webhooks                                                  | DTOs、serializers、mappings、retry/error handling                               |
-| Command        | CLI parser、command registry、script manifest、operator/admin command config                                                             | Command handlers、argument definitions、scripts、logs                           |
-| Workflow       | BPMN/process definition、workflow engine metadata、state-machine config、approval flow config                                            | Task handlers、transition guards、notifications、audit trails                   |
-| Library/API    | Package export map、public symbols、SDK manifest、typed public interface、documented extension points                                    | Implementation modules、types/interfaces、examples、tests                       |
-| Data pipeline  | DAG definition、ETL/ELT config、stream topology、pipeline catalog、data product refresh metadata                                         | Task modules、SQL/model files、source/sink tables、quality checks               |
-
-## Menu And Permission Sources
-
-請同時搜尋 code 與 data representation：
-
-- Tables 或 seed scripts：例如 `MENU`、`FUNCTION`、`PROGRAM`、`SCREEN`、`ROLE`、`PERMISSION`、`AUTH`、`RESPONSIBILITY`、`MODULE`、`FORM`。
-- Config keys：例如 `menuItems`、`routes`、`permissions`、`features`、`modules`、`programs`、`screens`。
-- Code constants：例如 metadata ids、permission ids、program codes、route names。
-- Join 或 mapping：例如 role-to-program、menu-to-program、permission-to-route、responsibility-to-program。
-
-如果 repo 有參照這些 tables，但未包含 seed data，請記錄可能由 DB 持有的 menu source，並將受影響的 targets 標記為 unresolved，直到取得足夠的佐證。
-
-如果 repo 的 runtime menu/navigation 是直接寫在程式或 config 中，該 code/config 就是該 scope 的 authoritative source。請逐列列出 hardcoded labels、target paths/handlers、access-control notes 與 source lines，並標記為可供 `docs-target-queue-from-catalog` 直接使用的 target rows。
-
-如果 menu/navigation 來自 client-side router、SPA route config、mobile navigation graph、desktop command map、external JSON/YAML/CSV/XML、CMS export、deployment-mounted config 或 vendor/platform metadata，請不要改用 page/component inventory 猜測。應先定位該 authority；若檔案可讀就解析 rows，若不可讀就列入 handoff 的 `parse_file` 或 `query/export` request。
-
-如果 DB-backed menu 與 hardcoded menu 同時存在，請分別呈現：
-
-- DB-backed scope：DB table/export 是該 scope 的最終 row authority；缺 rows 時列為 metadata acquisition。
-- Hardcoded/client/file scope：repo code/config、client router 或 external file 是該 scope 的最終 row authority；已列出的 entries 可直接進入 target list，缺檔時則提出最小取得需求。
-
-## Top-Level Documentation Target Signals
-
-當下列一項或多項條件具備 source-backed 證據時，可將該項目判定為 top-level documentation target：
-
-- 使用者可見的 menu/navigation item。
-- 獨立存在的 route、screen、form、command、job、API、queue consumer、file watcher 或 report definition。
-- 專屬的 permission code，或 runtime metadata 明確提供的 metadata code。
-- 專屬的 ERP program/transaction metadata，或平台明確定義的 target metadata。
-- 專屬的 scheduler registration。
-- 明確的 external contract 或 integration boundary。
-- 專屬的 workflow/process definition、CLI command manifest、mobile/desktop navigation node、public library export 或 data pipeline definition。
-- 獨立的 business outcome 與主要 data resource。
-
-## Sub-Action Signals
-
-若項目僅符合下列情況，則應保留在 parent target 之下：
-
-- 只能透過 parent target 進入的 CRUD view 或 handler。
-- 沒有獨立 menu/permission 的 detail/edit/create/delete JSP/Razor/component。
-- Popup、lookup、partial、include、modal、tab、wizard step 或 shared component。
-- 僅供特定 parent feature 使用的 SQL/helper/procedure。
-- 共用的 framework utility、validation helper、layout 或 generated artifact。
-
-## Special Cases
-
-- DB triggers 通常用來支援某個 target；只有在 system behavior 明確由 trigger 驅動，且對外具有實際意義時，才應視為 top-level target。
-- Stored procedures 若由 scheduler 執行、被 integration 呼叫、透過 service 對外暴露，或作為 ERP/program entrypoint 使用，就可以視為 top-level。否則應將其映射為 data/logic resource。
-- API endpoints 即使沒有 UI，也可以是 top-level target，特別是在 integration system 中。
-- Reports 若可獨立排程、可由 menu 存取，或具備 permission 控制，則可視為 top-level。
-- Public library exports 只有在 consumer 會直接呼叫且 repo 將其視為穩定 contract 時才是 top-level；internal helper、private module 與測試專用 facade 應排除。
-- Data pipelines 以 DAG、pipeline registry、job definition、stream topology 或 data product refresh metadata 為 row authority；不要只因 folder 叫 `pipelines` 就把每個 SQL/model file 提升為 target。
-- Workflow 與 state-machine 類 target 應以 process definition、transition metadata 或 workflow registry 為邊界；單一 task handler 預設只是 implementation detail。
-- 若可取得 generator 或 metadata source，generated code 應回溯對應到該來源。

package/.github/skills/docs-target-catalog/references/output-templates.md

@@ -1,168 +0,0 @@
-# Output Templates
-
-當使用者要求可重複使用的 artifacts、markdown files，或需要以 source 為依據的 documentation target 盤點時，請使用這些 templates。
-
-## Repo Fingerprint
-
-| Area                          | Finding | Evidence | Impact On Entrypoint Search |
-| ----------------------------- | ------- | -------- | --------------------------- |
-| Languages/frameworks          |         |          |                             |
-| Runtime types                 |         |          |                             |
-| Likely target registry source |         |          |                             |
-| Scheduler/job source          |         |          |                             |
-| API/integration source        |         |          |                             |
-| DB/resource source            |         |          |                             |
-| Missing external metadata     |         |          |                             |
-
-## Authoritative Target Source Handoff
-
-這個 section 是給 `docs-target-queue-from-catalog` 的交接資訊。每個 target scope 都應有自己的 row；同一系統可同時存在 DB-backed 與 hardcoded-backed scopes。
-
-| target_scope | source_kind                                                                                                                                                    | authoritative_source | owner                                             | final_row_authority             | required_fields_or_handles | evidence | target_queue_action                                    |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------- | ------------------------------- | -------------------------- | -------- | ------------------------------------------------------ |
-|              | DB metadata / repo-owned config / repo-owned hardcoded code / client-side navigation / external file / route registry / scheduler registry / external metadata |                      | repo / client / environment / platform / external | yes / acquisition_required / no |                            |          | query/export / parse_file / direct_rows / coverage_gap |
-
-`final_row_authority` 的語意：
-
-- `yes`: source rows 已在 repo 中可讀，或 hardcoded rows 已逐列列出，可直接作為 target list。
-- `acquisition_required`: 已確認 source 是最終依據，但缺少 runtime rows；第二階段必須取得最小 metadata。
-- `no`: 只可作為 supporting evidence，不可產生 target rows。
-
-`target_queue_action` 的語意：
-
-- `query/export`: 使用 read-only query、metadata API 或使用者提供的 export 取得 rows。
-- `parse_file`: 解析已知的 JSON/YAML/CSV/XML/config/router/navigation file。
-- `direct_rows`: catalog 已逐列列出 rows，可直接轉成 `docs-target-queue.md`。
-- `coverage_gap`: 來源仍不明或不可取得，只能保留缺口。
-
-## Compact Handoff Catalog
-
-當 catalog 的主要用途是交接給 `docs-target-queue-from-catalog`，預設使用以下精簡輸出結構。這個格式目標是降低第一階段撰寫成本，並避免第二階段把 summary、candidate 或 unresolved implementation trace 誤當 final target rows。
-
-```markdown
-# <System Name> Documentation Target Catalog
-
-Generated: <YYYY-MM-DD>
-Scope: <scope>
-Method: authoritative entry sources first; implementation files are supporting evidence unless an activation source confirms them.
-
-## Repo Fingerprint
-
-| Area | Finding | Evidence | Impact On Entrypoint Search |
-| ---- | ------- | -------- | --------------------------- |
-
-## Authoritative Target Source Handoff
-
-| target_scope | source_kind | authoritative_source | owner | final_row_authority | required_fields_or_handles | evidence | target_queue_action |
-| ------------ | ----------- | -------------------- | ----- | ------------------- | -------------------------- | -------- | ------------------- |
-
-## Direct Target Rows
-
-| id  | source_kind | label_or_name | target_handler | entrypoint | source | access_control | target_scope | notes |
-| --- | ----------- | ------------- | -------------- | ---------- | ------ | -------------- | ------------ | ----- |
-
-## Coverage Review
-
-| gap | evidence | affected_scope | risk | recommended_next_search |
-| --- | -------- | -------------- | ---- | ----------------------- |
-```
-
-Compact handoff catalog 的排除規則：
-
-- 不輸出完整 deep-dive target catalog、完整 `Entrypoint Map`、完整 `Data Resource Map`，除非使用者明確要求 deep mode。
-- 不在每個 target 下重複 `Unresolved: None`。
-- 不把只有 DB/source family 證據、但尚未取得實際 rows 的項目展開成 final-looking target rows。
-- 不把 call chain、DAO/resource details 放進第二階段必讀 sections；只在需要說明 acquisition 或 coverage gap 時保留精簡 evidence。
-
-## Hardcoded Target Rows
-
-如果 menu、navigation、command 或 job list 寫死在 code/config 中，請逐列列出，並在 handoff table 將 `target_queue_action` 設為 `direct_rows`。
-
-| id  | source_kind               | label_or_name | target_handler | entrypoint | source | access_control | mapped_target | notes |
-| --- | ------------------------- | ------------- | -------------- | ---------- | ------ | -------------- | ------------- | ----- |
-|     | repo-owned hardcoded code |               |                |            |        |                |               |       |
-
-## Entrypoint Map
-
-| id   | entry_type | label_or_name | source | target_handler | access_control | mapped_target | unresolved |
-| ---- | ---------- | ------------- | ------ | -------------- | -------------- | ------------- | ---------- |
-| E001 | menu       |               |        |                |                | F001          |            |
-
-建議使用的 `entry_type` 值：`menu`、`web-route`、`api`、`mobile-screen`、`desktop-command`、`job`、`db-job`、`erp-program`、`erp-transaction`、`report`、`queue-consumer`、`file-import`、`file-export`、`cli-command`、`workflow`、`library-api`、`data-pipeline`、`unknown`。
-
-## Documentation Target Catalog Entry
-
-```markdown
-## F001 <Target Name>
-
-Type: <menu/API/job/report/mobile-screen/desktop-action/ERP/command/workflow/library-api/data-pipeline/DB/integration>
-Status: Confirmed | Candidate | Unresolved
-Primary Entry:
-- <entry type>: <label/path/name>
-- Source: <file/table/config with exact handle>
-- Handler: <handler/class/method/procedure>
-
-Purpose:
-- <一到兩句有 source 依據的描述>
-
-Actions:
-- <query/create/update/delete/export/import/approve/run/etc.>
-
-Implementation Scope:
-- UI/View: <files or N/A>
-- Handler: <controller/action/job/procedure>
-- Service/Domain: <files/classes/modules>
-- Data Access: <DAO/repository/mapper/package/procedure>
-- Reports/Files/Queues: <resources or N/A>
-
-Data Resources:
-- <tables/views/files/queues/external systems>
-
-Access Control:
-- <permission/role/metadata code, or N/A>
-
-Evidence:
-- <有 source 依據的條列>
-- <有 source 依據的條列>
-
-Unresolved:
-- <missing DB seed/live config/generated metadata/untraced branch, or N/A>
-```
-
-## Data Resource Map
-
-| resource | resource_type                            | operations              | source | mapped_targets | notes |
-| -------- | ---------------------------------------- | ----------------------- | ------ | -------------- | ----- |
-|          | table/view/procedure/file/queue/external | C/R/U/D/read/write/call |        | F001           |       |
-
-## Target Handle Index
-
-| id   | type     | canonical_name | exact_handles | aliases | entry_source | parent_target | top_level | unresolved |
-| ---- | -------- | -------------- | ------------- | ------- | ------------ | ------------- | --------- | ---------- |
-| F001 | Function |                |               |         |              |               | Y         |            |
-
-此處 `Function` 僅作為 `source_type` 範例值；若 target 不是 user-facing menu/navigation/business capability，請使用更精確的 activation-surface type。
-
-在 `exact_handles` 中請使用可直接從 source 搜尋到的精確值：menu labels、route paths、permission codes、class names、method names、JSP names、stored procedure names、job ids、report names。
-
-## Scheduler Target Handle Index
-
-| id   | job_type            | canonical_name | exact_handles | schedule_source | target_handler | data_resources | unresolved |
-| ---- | ------------------- | -------------- | ------------- | --------------- | -------------- | -------------- | ---------- |
-| J001 | batch/db-job/worker |                |               |                 |                |                |            |
-
-## Coverage Review
-
-| gap                                               | evidence | affected_scope           | risk                         | recommended_next_search                                                |
-| ------------------------------------------------- | -------- | ------------------------ | ---------------------------- | ---------------------------------------------------------------------- |
-| Menu data appears DB-owned but no seed data found |          | Target list completeness | 缺少僅存在於 menu 的 targets | 搜尋 migrations/DB exports，或要求提供 menu/navigation metadata export |
-
-## Final Summary Shape
-
-在 chat 回覆時，請讓答案以便於查找為導向：
-
-- 已確認的 documentation target 數量與 source type 分布。
-- 找到的最具權威性的 entry sources。
-- 重要但尚未解決的 sources。
-- 產出 artifacts 的路徑。
-- 若相關，列出已執行的 test/search commands。

package/.github/skills/docs-target-queue-from-catalog/SKILL.md

@@ -1,255 +0,0 @@
----
-name: docs-target-queue-from-catalog
-description: 將 docs/docs-target-catalog.md 或其他已完成的入口盤點報告，依其中指出的 menu、DB、route、scheduler、ERP、platform 等 authoritative source 取得最小 metadata，並正規化成 docs/docs-target-queue.md。只在使用者要把 catalog 或 metadata 轉成 documentation target queue 時使用，不用於第一階段 target catalog 盤點。
----
-
-# Documentation Target Queue From Catalog
-
-## Overview
-
-這是 entry-catalog workflow 的第二階段，不是重新做一次 repo 盤點。先把 catalog 當成 source acquisition map，找出 authoritative source，再取得對應的 metadata、config 或清單資料，最後只把已確認的 documentation targets 正規化到 `docs/docs-target-queue.md`。
-
-只有當使用者已經有 catalog、menu metadata、scheduler registry、route registry、client-side navigation config、external menu file、ERP metadata 或同等 authoritative source，並且目標是產出 documentation target queue 時，才使用這個 skill。若沒有 catalog，但允許建立第一階段 catalog，先建立 catalog 再繼續；不要直接從 repo files 猜測 rows。
-
-正式產生或驗證 `docs/docs-target-queue.md` 時，使用 repo shared queue vocabulary（`source-code-to-spec-tools/references/terminology-contract.md`）。`docs/docs-target-queue.md` 是 target row queue，不是 keyword list；`keyword` 只可作為 stable lookup handle；`source_type` 描述 activation surface，不可與 document section、implementation language 或 file type 混用。
-
-當 source 來自 scheduler、profile、registry 或其他 metadata-driven source 時，仍應依 authoritative row 所描述的 target 主體決定 `source_type`；不要只因該列是被 monitor、bootstrap 或 collector 載入，就把 artifact 類 target 誤歸為 `Job`。
-
-正式寫入或驗證 queue schema 時，Queue schema、status enum、`doc_profile` default、`source_type` registry、prefix 與 `document_path` default pattern 以 shared schema contract（`source-code-to-spec-tools/references/target-queue-schema-contract.md`）為準；本 workflow 與 converter script 不維護第二份定義。
-
-## Inputs
-
-預設輸入：
-
-- `docs/docs-target-catalog.md`: 第一階段 catalog workflow 產出的 source-backed report。
-- User-provided queue markdown/table or normalized source extract：如果使用者有提供 queue 欄位、範例表格或 extract，將其作為輸入；final output 仍須遵循 `references/docs-target-queue-contract.md` 與 shared schema contract。
-- 現有的 `docs/docs-target-queue.md`：如果已存在，需用來保留 IDs。
-- Optional source extracts：包含 read-only query results、CSV/Excel exports、seed files、route/menu/navigation config、client-side router config、external JSON/YAML/CSV/XML menu files、ERP metadata、scheduler exports、command registries、integration catalogs、catalog Markdown tables 或使用者整理好的清單。
-- Optional normalized inputs：`normalized-targets.csv/jsonl`、`source-acquisition-summary.csv/jsonl`、`coverage-review.csv/jsonl`，欄位依 `references/docs-target-queue-contract.md`。
-
-如果 report 指出真正的 source 在 repo 之外，例如 environment-owned 的 menu/navigation、permission、scheduler、DB job、report metadata、external file 或 platform metadata，不要根據檔名自行補出資料列。應使用可用的 read-only metadata tools、使用者提供的 export，或可讀的 external/config file 取得最小欄位；若沒有工具或連線能力，才請對方提供 metadata extract/query output。
-
-## Preflight
-
-1. 如果使用者提供 catalog、handoff table、metadata extract、query/export output 或 source file，直接使用該來源。
-2. 如果 `docs/docs-target-catalog.md` 存在，先讀 catalog。
-3. 如果 catalog 不存在，但 workspace 可讀且可建立檔案，先使用 `docs-target-catalog` minimal workflow 產生 `docs/docs-target-catalog.md`，再繼續本 workflow。
-4. 如果 catalog 不存在，且不能產生第一階段 catalog，停止並提出最小輸入需求；不要直接掃 repo 猜測 `docs-target-queue.md` rows。
-
-Windows/PowerShell 讀取本 workflow 的 prompt、skill、catalog 或 queue Markdown 時，若畫面出現 mojibake，先用 `Get-Content -Encoding UTF8 -LiteralPath <path>` 重新讀取；不要在 UTF-8 reread 前判定檔案損毀或改寫內容。
-
-### Shared Lookup Tooling
-
-只有在需要 machine-readable catalog/queue parsing、ID preservation、schema validation、scoped source lookup 或 generic writer 時，才使用 `source-code-to-spec-tools` public CLI / shared contract 取得可重讀結果；direct rows、使用者提供的 normalized extract、單純 source acquisition request 或 partial/manual evidence 不需要在 workflow 一開始載入 shared CLI。不要呼叫其他 skill 私有 `scripts/` 目錄。執行本 workflow 對應 Python script 時使用 `python -B`，避免留下 `__pycache__` 或 `*.pyc` runtime cache。
-
-| workflow need | shared CLI | purpose |
-| --- | --- | --- |
-| catalog table inventory / handoff rows / direct rows / coverage gaps | `python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py ...` | 以 section、column filter 與 query 解析 `docs/docs-target-catalog.md`，避免把 summary row 誤當 final target row。 |
-| queue section / supporting table inventory | `python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py sections ...` | 解析 `docs/docs-target-queue.md` 的 sections、main table 與 supporting tables；`target_query.py` 沒有 `tables` command。 |
-| existing queue ID lookup / duplicate target lookup | `python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py ...` | 查詢既有 `docs/docs-target-queue.md` row、IDs、source type、entrypoint 與 keyword，保留穩定 ID。 |
-| scoped source handle verification | `python -B .github/skills/source-code-to-spec-tools/scripts/source_lookup.py ...` | 僅在 normalization 必須補 label、handler、route 或 config handle 時，對 source root 做 bounded lookup。 |
-
-建議命令：
-
-```bash
-python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py tables --catalog docs/docs-target-catalog.md
-python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py handoff --catalog docs/docs-target-catalog.md --action direct_rows
-python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py rows --catalog docs/docs-target-catalog.md --section "Direct Target Rows"
-python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py sections --queue docs/docs-target-queue.md
-python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py find --queue docs/docs-target-queue.md --query "<entrypoint-or-keyword>"
-```
-
-### Output State Guard
-
-在任何寫入前先確認輸出狀態：
-
-- 檢查 working tree、Git index、`HEAD` 是否存在 `docs/docs-target-queue.md`。若任一位置存在，該檔都是 ID preservation source。
-- 如果輸出路徑有 staged deletion、untracked replacement、merge conflict 或其他 unclear dirty state，先停止並回報狀態；不要直接覆蓋正式檔案。
-- 如果既有 `docs/docs-target-queue.md` 含有 `Function`、`Job` 或其他 source type IDs，必須作為 `--existing` 來源保留 IDs。若 working tree 檔案不可用但 `HEAD` 有檔案，可先將 `git show HEAD:docs/docs-target-queue.md` 匯出到 `target/docs-target-queue-from-catalog/existing-docs-target-queue-from-head.md` 作為 converter input。
-- 若 catalog 標示為 required、complete inventory 或 final row authority 的 source 尚未取得，只能輸出 partial candidate 到 `target/docs-target-queue-from-catalog/docs-target-queue.partial.md`，除非使用者明確要求覆蓋正式 `docs/docs-target-queue.md`。
-
-### Finalization And Cleanup Gate
-
-本 workflow 的完成狀態以 `docs/docs-target-queue.md` 為準；`target/`、temp folders、terminal output 或 raw acquisition extracts 不能單獨代表完成。
-
-- Final success 必須確認 `docs/docs-target-queue.md` 已寫入或更新，且通過 count validation、ID preservation 與 required sections 檢查。
-- `write_documentation_target_queue.py` 在 final mode 只能輸出 `docs/docs-target-queue.md`；若 required source 尚未取得，只能顯式使用 `--partial-output` 寫入 `target/docs-target-queue-from-catalog/docs-target-queue.partial.md`，並在 final response 標示為 `partial`。
-- 如果本次只產生 `target/docs-target-queue-from-catalog/**`，不可宣告正式 queue 已完成；必須說明缺少哪些 authoritative source、normalized rows 或 count evidence。
-- 所有 Python acquisition / conversion / validation stage 結束後，final response 前檢查 `target/docs-target-queue-from-catalog/`、`__pycache__/` 與 `*.py[cod]`。不再需要的 staging/cache 應清理；若保留 raw export、partial candidate 或 `HEAD` export 作為可重讀 evidence，必須列出路徑與保留理由。
-- `target/` 已被 `.gitignore` 忽略，不能只靠 `git status --short` 判斷乾淨；必要時使用 `git status --short --ignored` 或 `Get-ChildItem -Force target -Recurse` 檢查 staging residue。
-
-## Workflow
-
-### 1. Read The Catalog As Acquisition Map
-
-從 `docs/docs-target-catalog.md` 擷取以下項目：
-
-- 優先讀取 `Authoritative Target Source Handoff` section；需要 machine-readable extraction 時使用 `catalog_query.py handoff`。
-- 已確認的 authoritative sources，例如 menu/navigation metadata、scheduler registries、route registries、navigation registries、ERP metadata、database-owned job metadata、report catalogs、command registries 或 config files。
-- 會阻礙完整 target inventory 的 unresolved coverage gaps。
-- source type candidates：`Function`、`Job`、`API`、`Report`、`File`、`External`、`ERP`、`DatabaseProgram`、`Command`、`Workflow`、`MobileScreen`、`DesktopAction`、`LibraryAPI`、`DataPipeline`，或專案自定義 type。
-- 任何與 grouping、display labels、target handlers、activation paths 相關的既有證據。
-
-不要把 catalog 中的 summary item 直接視為最終 row set。當 catalog 說明「完整 inventory 在 DB、ERP、platform 或 external metadata」時，這代表下一步要 acquisition；不是代表這些 rows 不存在。
-
-如果 handoff table 已提供 `target_queue_action`，依下列規則處理：
-
-- `query/export`: 使用 `authoritative_source` 與 `required_fields_or_handles` 進行 read-only acquisition。source 可能是 DB、platform metadata、external export、service API 或其他 metadata store；先嘗試合適的 read-only acquisition，不能只因為 repo 中沒有現成 export 就直接放入 coverage review。
-- `parse_file`: 解析 `authoritative_source` 指出的 JSON/YAML/CSV/XML/config/router/navigation file。
-- `parse_catalog_table`: 使用 `catalog_query.py rows` 解析 catalog 或 handoff 中已列出的 Markdown table rows。
-- `direct_rows`: 使用 `catalog_query.py rows` 直接讀取 catalog 中已列出的 hardcoded/config rows 作為該 scope 的 target list。
-- `coverage_gap`: 不產生主表 rows，將該 scope 留在 coverage review。
-
-### 1.0 Source Scope Independence
-
-當 catalog 或 handoff table 同時列出多個 source scope 時，必須逐 scope 獨立判斷 `authoritative_source`、`final_row_authority` 與 acquisition status；不要把同一功能區域內的不同 source 混成單一 pass/fail decision。
-
-- `final_row_authority=yes`、required source 或 complete inventory source，都必須先各自執行 acquisition attempt；不能因為另一個 scope 只是 control-plane、overlay 或 scope-limited metadata 而跳過。
-- control-plane、overlay 或其他 scope-limited source 的缺失，只能影響 coverage review 與 partial/incomplete 判定；不能取消另一個獨立 row-authority scope 的 acquisition。
-- 每個 scope 都要保留自己的 ledger row、status 與 count evidence。若獨立的 final-row-authority scope 已成功取得 rows，這些 rows 仍應進入後續 normalization；缺失的 overlay 只留在 coverage review。
-
-只有在需要驗證 mappings、column meanings 或 normalization 所需的 handler names 時，才回頭查看 source files。
-
-### 1.1 Source Acquisition Gate
-
-對每個 handoff/source scope 建立 acquisition attempt record，再進行 conversion：
-
-| status | Meaning |
-| ------ | ------- |
-| `collected_success` | 成功取得 rows，且有可重讀 export/result set/source file 與 count evidence。 |
-| `parsed_success` | 成功解析 repo/file/catalog/config/hardcoded source rows。 |
-| `direct_rows_accepted` | catalog/handoff 中已列出的 direct rows 被採用，且 count 可驗證。 |
-| `zero_rows_with_count` | 成功查詢或解析，但符合條件 rows 為 0；必須有 count evidence。 |
-| `source_unavailable` | source 已辨識，但目前不可讀、不可查或不在 workspace/environment。 |
-| `parse_failed` | source 可讀但解析失敗或欄位不足。 |
-| `connection_failed` | DB/API/platform connection profile 已嘗試但失敗。 |
-| `missing_tool` | 需要的 native client、parser、CLI、SDK 或 helper 不可用。 |
-| `missing_credentials` | repo discovery 後仍缺少必要 credentials、token 或 session secret。 |
-| `permission_denied` | source 可連線/可讀但無 table/schema/file/API 權限。 |
-| `user_input_required` | 需要使用者提供最小 export、file、config excerpt 或 connection detail。 |
-| `user_declined` | 使用者拒絕本次 source acquisition。 |
-
-只有 `collected_success`、`parsed_success`、`direct_rows_accepted` 與有 count evidence 的 `zero_rows_with_count` 可以進入 final count validation。其他 status 必須留在 blockers 或 coverage review，且若該 source 是 required、complete inventory 或 final row authority，不能用弱推論替代它。
-
-Required source 是指 catalog/handoff 標示為 `acquisition_required`、`final_row_authority=yes`、完整 inventory source，或沒有它就無法正確枚舉該 target scope 的來源。它可能是 DB table、hardcoded registry、config file、route table、scheduler file、external export、ERP/platform metadata、catalog table 或使用者提供的清單。
-
-### 2. Choose The Acquisition Path
-
-決定如何取得資料列時，使用 `references/metadata-acquisition-patterns.md`；本 `SKILL.md` 只維護階段順序與完成條件，不重寫各 source kind 的 acquisition recipe。
-
-- catalog 已明確列出的 DB table、view、metadata store、file、registry、Markdown table 或 external source，就是本階段允許的 acquisition target。
-- DB、repo file、catalog table、external export、ERP/platform metadata、generated source 等細部處理方式，依 `metadata-acquisition-patterns.md` 的 decision matrix、DB guardrails 與 non-DB collection 規則執行。
-- 如果沒有可用的 authoritative rows，產出 acquisition plan 與 coverage review，不要捏造 `docs-target-queue.md`。
-
-### 2.1 Keep Source Collection Separate From Conversion
-
-source collection 可以來自 DB query/export、file parse、config parse、catalog Markdown table、direct rows、scheduler registry、route registry、ERP/platform export 或使用者提供的清單。DB/native client path 只用來取得 read-only metadata rows、row counts 與 acquisition notes。不要讓 DB acquisition step 產生 `docs/docs-target-queue.md`、Markdown target table，或 project-specific converter script。
-
-禁止為單一系統臨時產生 `generate-docs-target-queue.py`、`generate-docs-target-queue.ps1` 或類似的一次性 converter。若需要程式化轉換，先把取得的 rows 整理成 generic input files，再使用本 skill 內建腳本：
-
-```bash
-python -B .github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py \
-  --targets <normalized-targets.csv|jsonl> \
-  --summary <source-acquisition-summary.csv|jsonl> \
-  --coverage <coverage-review.csv|jsonl> \
-  --existing docs/docs-target-queue.md \
-  --output docs/docs-target-queue.md \
-  --source-note "<catalog/export/source summary>"
-```
-
-此腳本是 source-agnostic final formatter + validator。它只接受已正規化的 row data，負責保留既有 IDs、依 source type prefix 指派新 IDs、驗證 counts，並輸出符合 contract 的 Markdown。不要把特定系統名稱、table name、SQL、Java class、route 或 business keyword 寫進此腳本。
-
-修改 `write_documentation_target_queue.py` 時，使用實際 normalized input 執行 bounded smoke command，不要只跑 `--help`：
-
-```bash
-python -B .github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py \
-  --targets <normalized-targets.csv|jsonl> \
-  --summary <source-acquisition-summary.csv|jsonl> \
-  --coverage <coverage-review.csv|jsonl> \
-  --existing docs/docs-target-queue.md \
-  --output target/docs-target-queue-from-catalog/docs-target-queue.partial.md \
-  --partial-output \
-  --source-note "<catalog/export/source summary>"
-```
-
-本 user 版驗證時以實際 acquisition / normalization 產物為準，且 partial smoke output 必須放在 `target/docs-target-queue-from-catalog/**`。
-
-### 2.2 Normalize Source Lists
-
-不論來源是 DB、file、config、catalog table 或 direct rows，都先整理成 `normalized-targets.csv/jsonl`。每一列代表一個已確認 documentation target，欄位語意如下：
-
-當需要合併 catalog table rows、DB/file extracts、source summary 與 coverage rows 給 writer 使用時，先產生具名 UTF-8 writer input files（例如 `normalized-targets.csv/jsonl`、`source-acquisition-summary.csv/jsonl`、`coverage-review.csv/jsonl`），不要用 PowerShell 長單行 `python -c` 組裝複雜資料。若合併邏輯需要程式，使用 `target/docs-target-queue-from-catalog/` 下的小型 preparation script 作為暫存執行載體；final cleanup 時移除該 script，保留可重讀的 normalized input/output evidence。重複出現的通用合併邏輯才提升為 reusable script，不新增 project-specific converter。
-
-```text
-source_type, group, name, entrypoint, keyword, document_path, doc_profile,
-foundation_doc_status, architecture_doc_status, ops_doc_status, review_status, document_completed_flag(Y/N)
-```
-
-`document_path`、`doc_profile` 與 queue 狀態欄可省略；converter 會依 shared schema contract 補預設值。輸入必須使用 current schema 欄位；不要提供或依賴舊 profile/status 欄位。`id` 與 `original_id` 也可省略，converter 會讀取既有 `docs/docs-target-queue.md` 並保留可匹配的 IDs。
-
-同時整理 `source-acquisition-summary.csv/jsonl`，每個 source scope 一列，記錄 raw/eligible/excluded/gap counts。若某個 source 只有 catalog direct rows，也要有對應 summary row；不要只把 rows 寫進 final table 而缺少 count reconciliation。
-
-若 source 不可取得、count 不可驗證，或 catalog 只指出 source family 但沒有實際 rows，將該項寫入 `coverage-review.csv/jsonl`，不要混入 `normalized-targets`。
-
-如果缺少 required、complete inventory 或 final row authority，`normalized-targets` 可以保留已取得的 rows 作為 partial evidence，但 final output 應顯式使用 `--partial-output` 寫到 `target/docs-target-queue-from-catalog/docs-target-queue.partial.md`，不可替換較完整或狀態不明的 `docs/docs-target-queue.md`。
-
-### 3. Build The Acquisition Ledger
-
-在 normalization 前，先為每個 source scope 建立 ledger。這是 row authority 的追蹤表，不是最後的 target table。Ledger 欄位、count reconciliation 與 failure handling 以 `references/docs-target-queue-contract.md` 的 `Source Acquisition Summary` 為準。
-
-核心規則：
-
-- `target_scope` 必須來自 handoff table 或 catalog 中可追溯的 source scope。
-- `authoritative_source` 必須是 catalog 指名或 source evidence 可證明的 table/view/file/config/export/registry/catalog table。
-- DB source 的欄位選擇、join 邊界與禁止事項以 `references/metadata-acquisition-patterns.md` 的 `DB Query Guardrails` 為準；非 DB source 以格式語意與 catalog handoff 欄位為準。
-- 每個 source scope 都必須有 acquisition attempt record 與 status；沒有 attempt record 時不可把 source 移到普通 coverage gap。
-- 非 DB source parsing 必須保留可重讀的 source file、catalog table 範圍或 normalized source list。
-- Ledger count 對不上、source collection 不可重現，或 row authority 只存在於 terminal scrollback 時，不可寫成 final table；改列 blocker 或要求最小 metadata/source export。
-
-### 4. Normalize Rows
-
-請嚴格遵循 `references/docs-target-queue-contract.md`：
-
-- 每個已確認的 documentation target 對應一列。
-- 排除 CRUD child screens、popups、includes、helper modules、shared data-access resources、generated files，以及沒有獨立 activation evidence 的 orphan implementation files。
-- 保留現有 `docs/docs-target-queue.md` 中的 IDs。
-- 依 shared schema contract 的 `source_type` prefix 指派新的 IDs；若專案需要自訂 type，先透過 registration extension 在 contract 中明確定義，或於一次性 converter run 使用 `--prefix source_type=PREFIX`。
-- Queue 建立階段不以 review 狀態推定 completion；新列的 `document_completed_flag(Y/N)` 預設保持 `N`。後續由 `source-code-to-spec-documenter` 依三份 target SPEC 文件是否存在更新 completion flag；review workflow 只更新 `review_status` 與 findings。
-- 建議將正規化後的 rows 保留成 `normalized-targets.csv/jsonl`，再用 `scripts/write_documentation_target_queue.py` 寫出最終 Markdown；不要把正規化規則藏在一次性腳本中。
-
-### 5. Validate Before Writing
-
-在更新 `docs/docs-target-queue.md` 之前，執行 `references/docs-target-queue-contract.md` 的 `Final Validation Gate`。任何 validation failure 都要先修正；如果需要 external metadata 才能修正，將該 source 移到 coverage review/blocker，不要混入主表。
-
-如果有任何 required、complete inventory 或 final row authority 的 status 不是 `collected_success`、`parsed_success`、`direct_rows_accepted` 或 validated `zero_rows_with_count`，final validation 不得宣告完整；應產出 partial candidate、incomplete note 或 acquisition request。
-
-### 6. Output
-
-除非使用者要求輸出到其他路徑，否則請寫入 `docs/docs-target-queue.md`，並使用 `references/docs-target-queue-contract.md` 的 `Required Sections` 與 table contract。
-
-輸出內容要聚焦在 navigation。除非使用者要求 deep mode，否則不要加入完整 call chains、architecture sections 或冗長的 repo analysis。
-
-Final response 必須列出：
-
-- output path，如果是 partial candidate 必須明確標 `partial`。
-- main table source-type counts。
-- 每個 source scope 的 acquisition status 與 row count/failure reason。
-- 是否保留既有 IDs，以及使用的 existing source 是 working tree、index、`HEAD` export 或使用者提供檔案。
-- blockers / coverage gaps，特別是會影響 target inventory 完整性的 required source。
-- cleanup result：`target/docs-target-queue-from-catalog/**`、`__pycache__/` 與 `*.py[cod]` 是否已清理；若有保留，列出保留理由。
-
-## Working Artifact Policy
-
-- `target/`、temp folders 或 tool-generated acquisition folders 只能作為暫存 evidence；最終可維護輸出是 `docs/docs-target-queue.md` 與必要的 reusable skill resources。
-- 若 required source acquisition 尚未完成，`target/docs-target-queue-from-catalog/` 是 partial evidence 的安全輸出位置；不要覆蓋較完整或狀態不明的正式文件。
-- Raw source files、query/export files、catalog table extracts 可以保留作為 evidence，但不可取代 `Source Acquisition Summary`、normalized target rows 或 final validation。
-- SQL/export scripts 僅作為可重跑 acquisition recipe；不要把它們當成 conversion source of truth。
-- Zero-row export 必須有 count evidence 或 ledger row。只有空檔案而沒有 count reconciliation 時，不可宣告為 validated-empty。
-
-## Failure Rules
-
-- 如果需要 external metadata/file access 但目前無法取得，請在產出精確的 acquisition request 後停止，並說明 final table 仍需要那些 result sets/files。
-- 如果 catalog 指名的 source 可辨識但未嘗試 acquisition，不可宣告完整輸出；先執行 source acquisition gate 或產出最小 acquisition request。
-- 如果缺少 catalog，請先執行第一階段的 target catalog workflow；若無法執行，要求 catalog 或等效 handoff/source extract，不要根據 repo files 猜測。
-- 如果取得的 metadata 與 catalog 衝突，納入項目時優先以 runtime metadata 為準，source code 只用來驗證 handler paths 或 unresolved items。
-- 如果轉換需要程式輔助，必須使用或修正本 skill 的 generic converter；不要新增 project-specific converter。