ops-wiki-agent-kit 0.1.1 → 0.1.2

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

@@ -1,85 +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
-
-## Role
-
-這是 entry-catalog workflow 的第二階段 control plane。它負責 routing、owner selection、step order、retry budget 與完成判定；acquisition recipe、manifest contract、failure/status rules、queue schema 與 validation checklist 都由 references 維護。
-
-只有當使用者已經有 catalog、menu metadata、scheduler registry、route registry、client-side navigation config、external menu file、ERP metadata 或同等 authoritative source，且目標是產出 documentation target queue 時，才使用此 skill。若沒有 catalog，但允許建立第一階段 catalog，先建立 `docs/docs-target-catalog.md` 再繼續；不要直接從 repo files 猜測 queue rows。
-
-正式輸出是 `docs/docs-target-queue.md`。`target/docs-target-queue-from-catalog/**` 只作為 staging、canonical extracts、normalized inputs、partial candidate 或可重讀 evidence。
-
-## Required References
-
-開始執行前依需要讀取下列 owner；不要在 `SKILL.md` 重寫這些規則：
-
-- `references/metadata-acquisition-patterns.md`: authoritative source acquisition、DB/native-client guardrails、source scope independence、canonical source extract manifest、reuse/retry/self-healing、mapping rules。
-- `references/docs-target-queue-contract.md`: required sections、source acquisition summary、eligible rows、ID preservation、output state guard、final validation、failure rules、cleanup/final response。
-- `.github/skills/source-code-to-spec-tools/references/terminology-contract.md`: queue vocabulary；`keyword` 是 stable lookup handle，`source_type` 是 activation surface。
-- `.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md`: queue schema、status enum、`doc_profile` default、source type registry、prefix 與 `document_path` pattern。
-
-Shared CLI 只在需要 machine-readable catalog/queue parsing、ID lookup、schema validation 或 scoped source 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>"
-```
-
-執行 Python scripts 時使用 `python -B`，避免留下 `__pycache__` 或 `*.pyc`。若 shell、terminal 或 editor 顯示 Markdown 內容出現 mojibake，先用明確指定 UTF-8 的 reader 重新讀取；不要在重新讀取前判定檔案損毀或改寫內容。
-
-## Routing Workflow
-
-1. Preflight inputs and output state
-   - 優先使用使用者提供的 catalog、handoff table、metadata extract、query/export output、source file、normalized input 或 direct rows。
-   - 若 `docs/docs-target-catalog.md` 存在，先讀 catalog；若不存在且可建立第一階段 catalog，先執行 target catalog workflow；若不能建立，停止並提出最小輸入需求。
-   - 寫入前依 `docs-target-queue-contract.md` 的 `Output State And ID Preservation Guard` 檢查 working tree、index、`HEAD` 與既有 `docs/docs-target-queue.md`。
-
-2. Read catalog as acquisition map
-   - 讀取 `Authoritative Target Source Handoff`、direct rows、coverage gaps、source type candidates、group/display/handler evidence。
-   - 依 `target_queue_action` routing：`query/export`、`parse_file`、`parse_catalog_table`、`direct_rows` 或 `coverage_gap`。
-   - 不把 summary item、implementation file inventory 或檔名推論當成 final row set。
-
-3. Choose acquisition path per source scope
-   - 每個 handoff/source scope 獨立判斷 `authoritative_source`、`final_row_authority`、required/complete inventory 與 acquisition status。
-   - 依 `metadata-acquisition-patterns.md` 選 DB、repo file、catalog table、external export、ERP/platform metadata、generated source 或 direct rows acquisition path。
-   - DB table/view/metadata store 先走 repo-local `.github/skills/database-query/SKILL.md` workflow 做 DB config discovery、harmless connection validation 與 bounded read-only acquisition。
-
-4. Build ledger and pin canonical extracts
-   - normalization 前建立 `source-acquisition-summary.csv/jsonl` 或等效 ledger；欄位與 status enum 以 `docs-target-queue-contract.md` 為準。
-   - 每個成功 acquisition 的 source scope 都必須先寫入 `target/docs-target-queue-from-catalog/source-manifest.json`，pin 一個 repo-local canonical extract。
-   - 若 manifest/extract 有效，沿用它；若缺失、checksum 不符、count 不可重算、必要欄位不足或使用者要求 refresh，才重新 acquisition。
-
-5. Normalize rows
-   - 將 DB/file/config/catalog/direct rows 先整理成 `normalized-targets.csv/jsonl`，每列代表一個已確認 documentation target。
-   - 排除沒有獨立 activation evidence 的 CRUD child screens、popups、includes、helper modules、generated files、orphan implementation files。
-   - `source_type`、`group`、`name`、`entrypoint`、`keyword` 與 `document_path` mapping 依 references 與 shared schema contract；不要輸出可反查的 raw parent key fallback。
-
-6. Write with generic formatter
-   - 使用 `scripts/write_documentation_target_queue.py` 產生 Markdown；不要新增只服務單一 source、system 或 programming language 的 converter。
-   - final mode 只能輸出 `docs/docs-target-queue.md`。若 required source、count gate 或 output state 未完成，使用 `--partial-output` 寫到 `target/docs-target-queue-from-catalog/docs-target-queue.partial.md`。
-
-```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>"
-```
-
-7. Validate final or partial output
-   - 套用 `docs-target-queue-contract.md` 的 `Final Validation Gate`。
-   - 若任何 required、complete inventory 或 final row authority source 沒有 validated status，不得宣告完整，也不得覆蓋較完整或狀態不明的正式 queue。
-   - 若修改 `write_documentation_target_queue.py`，需用實際 normalized input 執行 bounded smoke command；不要只跑 `--help`。
-
-8. Respond and clean up
-   - Final response 只列 output path、main table source-type counts、每個 source scope 的 status/count/failure reason、ID preservation source、blockers/coverage gaps、cleanup result。
-   - final response 前依 `docs-target-queue-contract.md` 清理或列明保留 `target/docs-target-queue-from-catalog/**`、`__pycache__/` 與 `*.py[cod]` 的理由。

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

@@ -1,172 +0,0 @@
-# Documentation Target Queue Contract
-
-產生或維護 `docs/docs-target-queue.md` 時，請使用此 contract。此檔是 documentation target queue，不只是關鍵字清單；後續 SPEC generation 與 review 都會依這張表選取、鎖定與回寫 target row。
-
-正式產生或驗證 queue 時，共用詞彙以 repo shared queue vocabulary（`.github/skills/source-code-to-spec-tools/references/terminology-contract.md`）為準。特別注意：`keyword` 只是 stable lookup handle；`source_type` 描述 activation surface；document section 與 coverage view 不可當作 row authority；未限定的 `source` 不可當作 row authority。
-
-## Shared Schema Source
-
-正式寫入或驗證 queue schema 時，Queue 欄位順序、supporting table 欄位、status enum、`doc_profile` 規則、`source_type` registry、prefix 與 `document_path` default pattern 都以 repo shared schema contract（`.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md`）為準；正式處理 queue schema 的 reusable scripts 必須 import shared `queue_contract.py`，不要在本 workflow 重新定義。
-
-本文件只保留 catalog-to-queue conversion、row eligibility、ID preservation 與 final validation 的 workflow 規則。若要改 schema 或 profile default，先改 shared contract，再同步本文件的引用文字。
-
-## Required Sections
-
-若輸出路徑位於 `docs/**/*.md`，可在 Source note 後加入 `## Obsidian Links`；沒有可靠 link 時可省略整個區塊。
-
-`docs/docs-target-queue.md` 應包含以下 sections；supporting tables 不可取代 main target table：
-
-1. `# Documentation Target Queue`
-2. Source note，說明 catalog、query/export、file parse、config parse、catalog table parse 或 direct source。
-3. `## Source Acquisition Summary`
-4. `## Main Target Table`，下方 main target queue table 欄位必須符合 shared schema contract 的 `Main Target Table`。
-5. `## Source-Type Counts`
-6. `## Coverage Review`
-
-`## Source Acquisition Summary` 用來記錄 row authority 與 count reconciliation：
-
-| target_scope | source_kind | authoritative_source | acquisition_method | selected_fields | filter_or_scope | raw_count | eligible_count | excluded_count | gap_count | validation_status |
-| ------------ | ----------- | -------------------- | ------------------ | --------------- | --------------- | --------- | -------------- | -------------- | --------- | ----------------- |
-
-每一列需滿足 `raw_count = eligible_count + excluded_count + gap_count`。若 count 無法對上，該 source 不可進 final table，必須記入 `Coverage Review`。
-
-`validation_status` 可用值包含 `collected_success`、`parsed_success`、`direct_rows_accepted`、`zero_rows_with_count`、`source_unavailable`、`parse_failed`、`connection_failed`、`missing_tool`、`missing_credentials`、`permission_denied`、`user_input_required`、`user_declined`。只有成功取得/解析 rows，或有 count evidence 的 zero-row result，可以宣告為 validated source。
-
-## Queue Selection Rules
-
-當後段 SPEC workflow 要挑選 target row：
-
-1. 若使用者指定 `id`，只處理該列。
-2. 若使用者指定 `id`，不檢查 `document_completed_flag(Y/N)` 或任何 doc status；即使該列不是 `pending` 或不是 `N`，後段 workflow 仍處理該 selected row。
-3. 若未指定 `id`，依 main target table 順序由上到下挑選第一筆符合本次 scope 的 row。
-4. 若指定 scope 為 `baseline`，挑選第一筆 `baseline_status=pending` 的 row。
-5. 若指定 scope 為 `all`，挑選第一筆 `document_completed_flag(Y/N)=N` 的 row。
-6. 若指定 scope 為 `foundation`，挑選第一筆 `foundation_doc_status=pending` 的 row。
-7. 若指定 scope 為 `architecture`，挑選第一筆 `architecture_doc_status=pending` 的 row。
-8. 若指定 scope 為 `ops`，挑選第一筆 `ops_doc_status=pending` 的 row。
-9. No-id auto selection 不自動挑選 `failed`、`partial`、`blocked`、`in_progress`、`generated`、`n/a`、`baseline_ready` 或其他非 `pending` status；若要重跑這些 row，必須明確指定 `id`。
-10. `review_status` 不參與 generation no-id auto selection；review workflow 有自己的 selection / status 規則。
-
-## Eligible Rows
-
-當項目是具有獨立 activation evidence 的 documentation target 時，納入一列：
-
-- 使用者可見的 menu/navigation target 或 business capability。
-- 外部系統或 frontend 會直接使用的 API endpoint 或 service contract。
-- Scheduled job、DB job、worker、batch job 或 background processor。
-- 可由 menu 存取、可排程、可匯出，或具有獨立權限控管的 report。
-- File import/export process、file watcher、queue consumer、webhook 或 external integration。
-- ERP program/transaction、concurrent program、responsibility/menu item、form、report，或平台明確定義的 target metadata。
-- 可獨立執行的 CLI/operator command、script command 或 console command。
-- Workflow、BPMN/process definition、approval flow、state-machine transition set 或 orchestrated business process。
-- Mobile screen、tab、deep link、activity/fragment destination 或 mobile navigation node。
-- Desktop menu/toolbar action、shortcut command、form/window action 或 desktop command binding。
-- Public library/package API、SDK entrypoint 或 exported module contract。
-- Data pipeline、DAG、ETL/ELT flow、stream processor 或 materialized data product refresh。
-
-預設排除：
-
-- 只能透過 parent target 進入的 CRUD child screens，例如 create/edit/delete/detail。
-- Popup、lookup、modal、partial、include、tab、wizard step、layout 或 shared component。
-- 沒有獨立 activation 的 data-access components、repository modules、service internals、helper modules 或 utility resources。
-- 只支援 parent target 的 query/model definitions、stored routines、database objects、generated artifacts 或 implementation resources。
-- 若真正的 entry source 是 generator 或 metadata source，則排除 generated files。
-- 只有命名推測、source evidence 不足的 candidates。
-
-只有當 source evidence 顯示它具有自己的 menu、permission code、route、job registration、API contract、scheduler、command、workflow definition、mobile/desktop navigation entry、library export、pipeline definition、queue/file entry、ERP program/transaction metadata 或平台明確定義的 target metadata 時，才把原本排除的項目提升為獨立列。
-
-## Source Type And Prefix
-
-`source_type` 必須描述 activation surface，而不是 implementation language。若多個類型都看似適用，選最能代表「使用者、系統或下游 consumer 如何直接啟動它」的類型。
-
-若某列來自 scheduler、profile、registry 或其他 metadata-driven source，先判斷 authoritative row 描述的是 target artifact 還是實際執行器。若 row authority 指向的是 report、export、template、mail artifact、API contract、file definition 或其他可被直接消費的 target，本列仍應依 target 主體分類；不要只因它是由 scheduler、monitor、bootstrap 或 collector 載入，就改判為 `Job`。只有當 authoritative row 直接指向 worker、batch handler、queue consumer、scheduler bootstrap 或其他可執行單元時，才歸為 `Job`。
-
-允許的 `source_type`、prefix、default `doc_profile` 與 `document_path` pattern 由 shared schema contract 的 `Source Type Registry` 定義；本文件不維護第二份清單。未列入 registry 的 `source_type` 不會被 converter automatic 接受；請透過 registration extension 在 shared contract 註冊 prefix / default `doc_profile` / path pattern，或在一次性 converter run 使用 `--prefix source_type=PREFIX` 後同步回 contract。
-
-## ID Rules
-
-- `original_id` 是同一個 `source_type` 內的流水號。
-- `id` 格式為 `<prefix><original_id>`，例如 `F1`、`J1`、`A1`、`FI1`、`C1`、`W1`、`M1`、`D1`、`L1`、`DP1`。
-- 如果 `docs/docs-target-queue.md` 已存在，必須保留所有既有 IDs 與 `original_id`。
-- 新增列時，使用該 `source_type` 下一個可用編號。
-- 排序、重新分組、合併 evidence 或修改名稱時，都不要重新編號。
-- 若發現重複 target，保留較舊的 ID，並把較好的 evidence 合併到該列。
-
-## Output State And ID Preservation 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`。
-
-## Field Mapping
-
-`group` 優先使用 menu group label/name、module、responsibility、application 或 navigation section；其次才使用 route prefix、package/module、bounded context、primary data resource、scheduler/config/folder 類別。若 source 只提供 parent key，例如 `parent_key`、parent menu id 或 responsibility id，normalization 必須先用同一 canonical extract 或 authoritative source 反查 parent label/name；不可在 label/name 可反查時把 key 直接輸出成 `Menu:<id>`、`Parent:<id>` 或同類 debug fallback。完全沒有 source-backed grouping 時才使用 `Unclassified`。
-
-`name` 優先使用 user/operator 看得到的名稱，例如 menu label、ERP program/transaction name、平台 metadata name、report title、job display name、API operation name。不要用 helper class 或 child screen 檔名取代 parent target name。
-
-`entrypoint` 只儲存主要 activation handle，例如 menu target file、route、API method/path、job handler、scheduler key、command、ERP program/transaction/form id、file watcher/import/export handler。完整 call chain 應放在 feature SPEC，不放進此欄。
-
-`document_path` 使用 repo-relative path。預設 pattern 由 shared schema contract 的 `Source Type Registry` 定義。
-
-`keyword` 優先使用 permission/program/metadata code、source metadata stable key、route path、endpoint path、command、scheduler key 或 primary screen file。
-
-若 `notes` 只是轉寫 profile、scheduler 或 registry metadata，應維持 raw snapshot 語意。除非 authoritative source 明確提供 effective runtime state，否則不要把 enable、active、schedule 或同類欄位轉寫成「已啟用」、「目前正在執行」或其他 runtime 結論。
-
-`doc_profile` 若無 source-provided value，使用 shared schema contract 的 default profile rules。不要用 `full` 當作無條件預設。converter input 與正式輸出都必須使用 current schema 的 `doc_profile`。
-
-`baseline_status` 預設為 `pending`。此欄位只描述 shared handoff baseline stage，不代表任何 target-facing SPEC 文件已產生；handoff path 仍寫在 `last_handoff`。
-
-## Final Validation Gate
-
-完成前必須逐項確認：
-
-- Main target table 欄位與 shared schema contract 的 `Main Target Table` 完全一致。
-- 每一列都有唯一 `id`，且 `id = <source_type prefix><original_id>`。
-- `Source-Type Counts` 的總和等於 main target table rows。
-- `Source Acquisition Summary` 的 `eligible_count` 加總能對應到 main target table rows；若有跨 source 去重，需在 source note 說明去重規則。
-- 每個 catalog/handoff source scope 都有 acquisition status。
-- 每個進入 main target table 的 source scope 都有 `target/docs-target-queue-from-catalog/source-manifest.json` 記錄 canonical extract，且 manifest 至少包含 `canonical_extract_path`、`format`、`raw_count`、`eligible_count`、`excluded_count`、`gap_count`、`parser_or_command` 與 `checksum`。
-- Manifest 指向的 canonical extract 必須位於 repo-local workspace 或使用者明確提供的 source path；不得指向 chat/IDE session 暫存輸出、terminal scrollback、clipboard、外部 user profile 暫存目錄，或其他不可重讀來源。
-- Manifest path、count 與 checksum 可重讀驗證；若 manifest 已有效，normalization / writer / validation 必須沿用該 extract，不重新 DB acquisition。
-- 若同一 source scope 存在多個候選 export、spool 或 query result，已先停止選源並解決衝突；不得在未 pin canonical extract 的狀態下寫入 final output。
-- 每個 source scope 的 canonical extract count gate 已通過：可解析 raw rows 等於 manifest `raw_count`，`raw_count = eligible_count + excluded_count + gap_count`，且 normalized target rows 等於 `eligible_count` 或已在 source note 說明去重。
-- 若 required、complete inventory 或 final row authority 缺失，最終輸出不得宣稱完整，也不得覆蓋較完整或狀態不明的既有 `docs/docs-target-queue.md`。
-- 寫入前已使用 working tree、index、`HEAD` 或使用者提供的既有 `docs/docs-target-queue.md` 作為 ID preservation source。
-- `doc_profile`、`baseline_status`、`foundation_doc_status`、`architecture_doc_status`、`ops_doc_status`、`review_status` 與 `document_completed_flag(Y/N)` 都符合允許值。
-- 沒有任何 main table row 只由 filename、implementation symbol name、file extension、package/module path 或 catalog summary 推論而來。
-- final mode 的 writer output path 是 `docs/docs-target-queue.md`。若輸出到 `target/docs-target-queue-from-catalog/**`，必須是顯式 partial/staging output，且不可宣告正式 queue 完成。
-- 若所有 required / complete inventory / final row authority source 都有 validated canonical extract，應直接寫正式 `docs/docs-target-queue.md`；不要另外產生 partial queue smoke output。Partial output 只用於 incomplete source、count gate failure、使用者要求 staging review，或正式 output state guard 阻止覆蓋時。
-- final response 前已檢查 `target/docs-target-queue-from-catalog/**`、`__pycache__/` 與 `*.py[cod]`；不需保留的 staging/cache 已清理，保留的 evidence 有明確路徑與理由。
-- 若修改 `write_documentation_target_queue.py`，已使用實際 normalized input 執行 bounded smoke command；若未執行，final response 必須說明原因與剩餘風險。
-
-## Working Artifact And Cleanup 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。
-- Query/export scripts 僅作為可重跑 acquisition recipe；不要把它們當成 conversion source of truth。
-- Zero-row export 必須有 count evidence 或 ledger row。只有空檔案而沒有 count reconciliation 時，不可宣告為 validated-empty。
-- 所有 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。
-
-## 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；不要新增只服務單一 source、system 或 programming language 的 converter。
-
-## Final Response Contract
-
-Final response 不需要逐項重述已通過的 validation checklist；只列出：
-
-- 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]` 是否已清理；若有保留，列出保留理由。

package/.github/skills/docs-target-queue-from-catalog/references/metadata-acquisition-patterns.md

@@ -1,244 +0,0 @@
-# Metadata Acquisition Patterns
-
-當 `docs-target-catalog.md` 或等效的 entry-catalog 報告指向真實的 entry source，而這些來源可能是 repo-owned、client-owned、file-owned、DB-owned、environment-owned、platform-owned 或 generated 時，使用這份指引。
-
-目標是取得真正定義「哪些內容可以被啟用」的 metadata。不要把語言、framework、副檔名、資料夾名稱或檔名視為主要的功能邊界。
-
-第一階段 catalog 若將某個 DB table、ERP metadata、scheduler registry、route registry、config file、catalog table 或 external metadata 標為 `unresolved`，在本階段不是停止條件，而是 source acquisition trigger。只有在無法 read-only query/export、無法解析 source file/config/catalog rows，且使用者也未提供 extract 時，才停止並提出最小 request。
-
-如果 catalog/handoff 已指名某個 source，agent 必須先依 source kind 嘗試 acquisition 或記錄明確不可執行原因。不能把「repo 內沒有現成 export」或「source 不是 DB」視為足夠理由而直接跳到 coverage review。
-
-## Catalog Signals
-
-在 catalog 中尋找以下 signals：
-
-- authoritative target registry source
-- authoritative job 或 scheduler source
-- route、navigation、command 或 API registry
-- menu、permission、role、responsibility 或 feature metadata
-- report、export、import 或 file-process catalog
-- database-owned 或 platform-owned metadata
-- ERP、workflow、integration 或 external-system metadata
-- generated-code source metadata
-- 缺失的 metadata、尚未解析的 entry source，或建議的下一步搜尋方向
-
-這些 signals 的判定力應高於 implementation file inventory。
-
-## Technology-Neutral Acquisition Matrix
-
-| Runtime type     | First acquisition target                                                                           | Secondary validation                                              |
-| ---------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Web UI           | menu/navigation metadata、route registry、permission mapping、page registry                        | page/view/component、request handler、controller/action           |
-| API/service      | endpoint registry、service contract、route table、gateway config                                   | handler method、service module、request/response schema           |
-| Mobile           | navigation graph、screen registry、deep-link registry、tab/menu definition                         | screen component、view model、service call                        |
-| Desktop          | menu/toolbar metadata、command registry、window/form registry、shortcut/action binding             | form/window、event handler、service call                          |
-| Client-side web  | SPA router、navigation config、route guard/permission config、client menu JSON                     | page component、API client、state module                          |
-| External file    | JSON/YAML/CSV/XML menu export、deployment-mounted config、CMS/navigation export                    | loader/parser、target handler、permission mapping                 |
-| Database-centric | exposed stored routine catalog、database scheduler metadata、ETL/job metadata                      | tables/views、procedure body、grants、dependent resources         |
-| ERP/platform     | metadata catalog、responsibility/menu setup、program/report/process metadata、transaction metadata | extension code、form/report artifacts、backend package/module     |
-| Batch/job        | scheduler registry、job table/config、batch launcher、worker registry                              | job handler、script/module、step definitions、log/resource tables |
-| Reporting        | report catalog、export registry、scheduled-report metadata、dashboard/page registry                | report template/query、download handler、delivery config          |
-| File process     | import/export catalog、file watcher config、integration schedule、transfer definition              | parser/writer、staging resource、validation logic                 |
-| Integration      | contract registry、webhook registry、queue/topic subscription、partner interface config            | adapter/consumer/producer、message schema、retry/error logic      |
-| Command          | command registry、CLI parser metadata、script manifest、operator command config                    | command handler、script/module、argument parser                   |
-| Workflow         | workflow/process definition、BPMN/state-machine metadata、approval flow config                     | task handlers、transition guards、notification/action modules     |
-| Library/API      | package export map、public symbols、SDK manifest、OpenAPI/typed public contract                    | implementation module、types/interfaces、tests/examples           |
-| Data pipeline    | DAG definition、pipeline catalog、ETL/ELT config、stream processor topology                        | task modules、query/model definitions、source/sink resources      |
-
-## Metadata Acquisition Decision
-
-1. 如果 catalog 已指出 repo-owned 的 config 或 seed file，直接解析該檔案。
-2. 如果 catalog 已命名 DB table、view 或 metadata store，使用這些名稱做 read-only acquisition target，只查 `docs-target-queue.md` 所需的欄位。
-3. 如果 catalog 指向 environment-owned metadata，只請求或查詢 `docs-target-queue.md` 所需的欄位。
-4. 如果 catalog 指向 client-side navigation 或 external file，且檔案可讀，解析該檔案；若不可讀，要求提供最小 export/file。
-5. 如果 catalog 指向 platform-owned metadata，使用該平台的 export 或 read-only metadata API。
-6. 如果 catalog 指向 generated artifacts，向上追溯到 generator metadata，並以它作為來源。
-7. 如果 catalog 或 handoff 已包含足夠的 Markdown table/direct rows，直接解析那些 rows 並建立 source summary；不要為了產生 converter input 而改查 DB。
-8. 如果 catalog 無法辨識 authoritative source，就不要把候選項放進主表，而是把缺少的證據列在 coverage review 中。
-
-## Multi-Scope Authority Preservation
-
-多個 source scope 先視為彼此獨立的 acquisition units，再依 `SKILL.md` 的 `Source Scope Independence` 規則決定 partial/complete；本 reference 只補 acquisition-side 記錄原則。
-
-- required 或 `final_row_authority=yes` 的 scope 必須各自建立 acquisition attempt、ledger row 與 count evidence。
-- control-plane、overlay 或其他 scope-limited source 若缺失，應記入 coverage review 或 partial reason，但不要因此折疊、覆蓋或跳過另一個已確認的 row-authority scope。
-- 只有在 catalog 已明確指出多個 scope 共用同一個不可拆分的 final row authority 時，才可把它們合併成單一 acquisition summary row。
-
-每個 named source 的 acquisition status 必須寫入 acquisition ledger 或 final response。常用 status 包含 `collected_success`、`parsed_success`、`direct_rows_accepted`、`zero_rows_with_count`、`source_unavailable`、`parse_failed`、`connection_failed`、`missing_tool`、`missing_credentials`、`permission_denied`、`user_input_required`、`user_declined`。只有成功取得/解析 rows，或有 count evidence 的 zero-row result，可以宣告為 validated source。
-
-## Source Acquisition Gate
-
-對每個 handoff/source scope 先建立 acquisition attempt record，再進行 conversion。沒有 attempt record 時，不可把 source 移到普通 coverage gap。
-
-| 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 或使用者提供的清單。
-
-## Acquisition Reuse, Retry Budget, And Self-Healing
-
-同一輪 workflow 可以完成 acquisition、normalization、writer 與 validation，但每個 source scope 的 acquisition 結果必須先固化成 repo-local canonical extract，再進入後續步驟。後續 preparation script、manual parse、writer input 與 validation 只能讀 manifest 指定的 repo-local extract；不得讀取 chat tool、IDE、terminal session 或其他使用者環境中的暫存輸出。
-
-若 `target/docs-target-queue-from-catalog/source-manifest.json` 已有某 source scope 的 canonical extract，且該檔案存在、checksum 可驗證、row count 可重算，預設沿用該 extract，不重新連線或重新查詢。只有下列情況可以 refresh acquisition：
-
-- 使用者明確要求 refresh。
-- manifest 缺失、checksum 不符、extract 不可讀，或 row count 無法重算。
-- extract 缺少 `docs/docs-target-queue.md` 必要欄位，且無法從既有 source file / catalog table / bounded lookup 補齊。
-- 前次 acquisition status 是 `parse_failed`、`connection_failed`、`missing_tool`、`missing_credentials`、`permission_denied` 或其他會使 extract 不可信的 failure。
-
-DB source 的同輪 query budget：
-
-- 每個 DB profile 最多一次 harmless connection validation；已有本輪成功證據時不可重測。
-- 每個 source family 最多一次 schema/column discovery；只有欄位不確定時才執行。
-- 每個 source scope 最多一次正式 acquisition query/export；若第一次 query 因欄位缺失或 parse failure 需要修正，第二次 query 必須記錄原因，並淘汰舊 extract 或在 manifest 中標示 superseded。
-- 不可只因 native DB client 或 terminal 顯示格式不方便解析而重新查 DB；應將已取得的 raw output 轉成 delimiter-stable `csv`、`tsv` 或 `jsonl` extract。
-
-在 final response 或寫入 queue 前，先檢查 acquisition ledger 是否有未完成的 required DB source。若 source scope 是 `query/export`，指向 DB table、view、scheduler metadata、job metadata 或其他 metadata store，且本輪沒有 DB discovery、client check、harmless connection validation、bounded read-only query attempt 或具體 failure status，必須回到 `database-query` acquisition path 重試，不可直接 final。
-
-自我修復重試時，至少執行 repo-first DB config discovery，確認可用 client/helper，先跑 harmless validation query，再做 bounded read-only acquisition。若仍不能查，ledger 必須改成具體狀態：`missing_tool`、`missing_credentials`、`connection_failed`、`permission_denied` 或其他可診斷 failure；不要保留籠統的 `user_input_required` 取代實際 failure。
-
-若 ledger 已有本輪有效 canonical extract，self-healing 不可重新 DB acquisition；應先修正 parser、normalization mapping 或 writer input。只有 extract 本身缺失、不可驗證或缺少必要欄位時，才回到 DB acquisition path。
-
-## Minimal Metadata Fields
-
-只取得最小且足夠使用的資料形狀即可。不同系統的 field names 會不同，因此應依語意對應，而不是硬套精確的欄位名稱。
-
-| Meaning             | Examples of source meaning                                                                                                                                        | Used for                                 |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| stable key          | target id、menu id、route id、job id、program id、command id、report id                                                                                           | `keyword`、重複偵測、可選的 `entrypoint` |
-| display name        | menu label、operation name、job name、report title、command label                                                                                                 | `name`                                   |
-| grouping            | parent menu label/name、module、application、domain、responsibility、system、category                                                                             | `group`                                  |
-| activation target   | path、route、handler、command、job key、program name、process name                                                                                                | `entrypoint`                             |
-| source type         | menu、API、job、report、file process、ERP/platform program/transaction、integration、command、workflow、mobile screen、desktop action、library API、data pipeline | `source_type`                            |
-| status              | active/enabled/deprecated/hidden/environment-specific                                                                                                             | coverage review 或 filtering             |
-| parent relationship | parent menu id、route group、workflow parent、report group                                                                                                        | merge/split 判斷；不可直接取代 `group`   |
-| permission boundary | role、permission code、responsibility、access profile                                                                                                             | top-level target 證據                    |
-| source file/path    | file path、export path、route config path、source location                                                                                                        | evidence、parse request                  |
-
-## Generic Read-Only Requests
-
-當來源是 database、platform、ERP、external metadata store 或 external file 時，不要憑空假設 table/file names。若 catalog 已命名 table、metadata store 或 file path，使用該名稱；若未命名，才要求提供符合下列邏輯結構的 read-only export：
-
-```text
-source_type, stable_key, display_name, group_name, activation_target,
-parent_key, permission_key, status, source_location
-```
-
-如果需要 query，應依該系統中實際發現的 schema 撰寫。查詢必須保持 read-only，且只選取 keyword table 需要的 metadata 欄位。不要查業務資料內容、交易明細或大量 payload。
-
-DB/native-client output 的職責只到 acquisition：輸出 rows、counts、執行過的 query 摘要與不確定性。不要在 DB query 步驟產生 `docs/docs-target-queue.md` 或只服務單一 source/system/language 的 converter script。
-
-DB/native-client output 必須落地成 repo-local evidence，路徑位於 `target/docs-target-queue-from-catalog/**`。不要讓後續 parser、preparation script 或 writer 讀取 chat/IDE session 暫存輸出、terminal scrollback、clipboard、外部 user profile 暫存目錄，或其他不可由 repo 重讀的來源。若工具只能先產生 console output，先將原始輸出保存為 raw evidence，再轉成 delimiter-stable canonical extract。
-
-## Native Client Script Safety
-
-- 寫入 native-client script 前，先建立 repo-local staging folder；不要假設 shell redirection、file write helper 或 client wrapper 會自動建立 parent directory。
-- DB client script 應先寫入具名 script file，再以變數保存的 path 呼叫 native client；不要把 script body、file write 與 native client invocation 串成難以除錯的長單行。
-- Shell command 應設定 fail-fast 行為；寫檔失敗、script 產生失敗或 client preflight 失敗時，不得繼續執行 DB client。
-- 呼叫 native client script 時，將 script path 作為單一 argument 或明確 quoted argument 傳入；避免在長單行中直接嵌入未 quote 的相對路徑，以免 path quoting、argument parsing 或 line wrapping 造成 shell 層解析錯誤。
-
-## Non-DB Source Collection
-
-非 DB source 與 DB export 是同等有效的 row authority，只要它能提供可重讀的清單與 count evidence。常見來源包含：
-
-- route registry、router config、URL mapping、API gateway config。
-- menu/navigation JSON、YAML、XML、CSV、properties、desktop/mobile command registry。
-- scheduler config、batch registry、workflow definition、cron manifest。
-- CLI command manifest、package export metadata、public API list、BPMN/state-machine definition、pipeline DAG/config。
-- report catalog、export registry、file import/export catalog。
-- catalog/handoff 內已列出的 Markdown table rows 或 direct rows。
-- 使用者提供的 spreadsheet/CSV/JSON extract。
-
-處理規則：
-
-- 先依格式語意解析 source rows，再映射成 `normalized-targets.csv/jsonl`；不要把原始檔名或 implementation file inventory 直接當 target row。
-- 每個 source scope 都要建立 `source-acquisition-summary.csv/jsonl` row，記錄 raw/eligible/excluded/gap counts。
-- 如果 source 是 catalog Markdown table，`authoritative_source` 應指出 section/table 名稱，`acquisition_method` 可使用 `parse_catalog_table` 或 `direct_rows`。
-- 如果 source 可讀但 rows 缺少 `name`、`entrypoint` 或 `keyword` 所需欄位，先回 source/context 做 scoped lookup；仍無法補齊時放入 coverage review。
-
-## Canonical Source Extract Manifest
-
-每個 source scope 只能有一個 canonical extract 進入 normalization。Acquisition 完成後，先寫入或更新 `target/docs-target-queue-from-catalog/source-manifest.json`，以 array/object 形式記錄每個 scope：
-
-```json
-{
-  "target_scope": "User-facing navigation registry",
-  "source_kind": "metadata store",
-  "authoritative_source": "<metadata_store_or_registry_name>",
-  "acquisition_method": "query/export",
-  "canonical_extract_path": "target/docs-target-queue-from-catalog/navigation_rows.tsv",
-  "format": "tsv",
-  "selected_fields": ["stable_key", "parent_key", "sort_key", "display_name", "activation_target"],
-  "filter_or_scope": "all in-scope rows from <metadata_store_or_registry_name>",
-  "raw_count": 135,
-  "eligible_count": 116,
-  "excluded_count": 19,
-  "gap_count": 0,
-  "parser_or_command": "native DB client export -> tsv parser",
-  "generated_at": "2026-06-15T14:38:24+08:00",
-  "checksum": "sha256:<hex>"
-}
-```
-
-`canonical_extract_path` 必須是可重讀檔案，且 row count 可由 parser 重算。若同 scope 有多個候選檔，先列出候選檔的 path、mtime、size、checksum 與可解析 row count，停止 normalization；不要自動選最新檔或檔名看似正確的檔案。
-
-Preferred extract format 是 `jsonl`、`csv` 或 `tsv`。避免把 native-client / console 視覺表格當 canonical extract；若工具只能輸出文字表格，必須先轉成 delimiter-stable extract，並把原始輸出當 evidence，不可直接作為 writer input。
-
-Manifest reuse rules：
-
-- 如果 manifest 指向的 `canonical_extract_path` 存在、checksum 符合、row count 可重算，後續 normalization / validation 必須沿用該 extract，不重新連 DB 或重新 parse terminal output。
-- 如果需要重跑 acquisition，必須在 manifest 或 acquisition summary 說明 refresh reason，例如 missing required field、parse failure、checksum mismatch、user requested refresh。
-- 若新 extract 取代舊 extract，manifest 必須只 pin 新 canonical extract；舊 spool/export 若保留，必須標示為 superseded evidence，不可再被 writer input 使用。
-- `source-manifest.json` 不能只記 summary status；進入 main table 的 source scope 必須至少記錄 `canonical_extract_path`、`format`、`raw_count`、`eligible_count`、`excluded_count`、`gap_count`、`parser_or_command` 與 `checksum`。
-
-## DB Query Guardrails
-
-- 將 catalog/handoff 的 `authoritative_source` 視為白名單；schema lookup 只可針對被點名的 table、view、metadata store 或其必要 key relation。
-- 對白名單中的 DB source，先做 repo-first DB discovery 與 harmless connection validation；失敗時記錄 failure status，不可靜默略過。
-- 同一輪 workflow 中，每個 DB profile 最多做一次 harmless connection validation；已有成功 validation evidence 時，不可為每個 source scope 重複測試連線。
-- 每個 source family 最多做一次 schema/column discovery；只有欄位不確定、catalog 欄位與實際 schema 不一致，或 query parse 失敗時才做 discovery。
-- 優先使用一個 target scope 一個 query/export。若同一 scope 需要多個 table，先取得 base table 的 row set，再逐一加入已證明必要的 relation。
-- 每個 source scope 原則上只做一次正式 acquisition query/export。第二次 acquisition 只允許用於修正欄位缺失、parse failure、schema mismatch 或使用者要求 refresh，且必須記錄原因與淘汰舊 extract；不可因 native-client 顯示排版不便、欄寬不滿意或 terminal output 不好讀而重新查 DB。
-- 在寫 query 前先決定 output shape：固定欄位、固定排序、delimiter-stable `csv`/`tsv` 或可轉換 raw output、count query 與 data query 的對應關係。不要先查 sample 再靠模型反覆猜欄位。
-- 禁止 `SELECT *`、業務資料明細、交易 payload、大量 text/blob 欄位，以及與 `docs-target-queue.md` 無關的欄位。
-- status/filter 欄位必須來自 catalog、source code、schema evidence 或使用者提供的 metadata 說明；不要猜測 `ACTIVE_FLAG`、`ENABLE`、`STATUS` 等欄位是否存在。
-- 文字空值判斷必須符合實際 DB engine 的 `NULL` / empty-string semantics；不要把某一種 query dialect 的空字串判斷硬套到所有資料庫，否則 eligible count 可能被錯算。
-- join 只能用於 visibility、permission、parent/grouping、activation target 或 enabled status 判斷；必須能說明 join key 與 row eligibility 的關係。
-- 不要把 menu/navigation、batch scheduler、report profile、permission、business transaction table 等不同 source family 用一個 broad query 混在一起。
-- query/export 後要保留 manifest 指定的可重讀 result set 或明確 row export，不要只從 terminal scrollback 手工組 markdown。
-- 每個 query/export 都要記錄 raw row count、套用 filter 後的 eligible count、排除 count 與 gap count；count 無法對上或無法由 canonical extract 重算時，該 source 不可進 final table。
-- Query/export script 若保留，只能作為可重跑 acquisition recipe。最終轉換應使用 normalized rows 與 `scripts/write_documentation_target_queue.py`，不要把 query script 當成 `docs-target-queue.md` 的 conversion source of truth。
-- 若 source 是 required、complete inventory 或 final row authority，例如 menu/navigation inventory、route registry、scheduler registry、report profile registry、hardcoded command registry、external navigation export、ERP/platform metadata catalog，acquisition 未成功時只能產出 partial candidate、incomplete note 或 acquisition request，不可覆蓋較完整或狀態不明的正式 `docs/docs-target-queue.md`。
-
-## Mapping Rules
-
-- `source_type`: 應選擇 activation surface，而不是 implementation language。
-- `group`: 使用 metadata 中的 parent menu label/name、module/application/responsibility/domain/category；若 raw source 只有 parent id，必須先以同一 canonical extract 或同一 authoritative source 反查 parent label/name，再寫入 `group`。不得在 parent label/name 可反查時把 raw key 直接格式化為 `Menu:<id>`、`Parent:<id>` 或同類 debug fallback。若 parent id 無法反查，將該 row 放入 coverage/blocker 或使用 source-backed 上層 category；只有完全沒有 source-backed grouping 時才使用 `Unclassified`。
-- `name`: 優先使用 user/operator 可見的 label，而不是 handler 或 file name。
-- `entrypoint`: 使用精簡的 activation target，例如 route、command、job key、program id、report id 或 main handler。
-- `keyword`: 使用 metadata 中最穩定、最適合搜尋的識別值。
-- `document_path`: 依 source type、group 與 name，配合 contract reference 推導。
-
-## Missing Data
-
-如果 catalog 表示 authoritative source 位於 repo 之外，且目前拿不到 metadata 結果，應產出 coverage item，而不是自行猜測：
-
-| item                | reason_not_in_table                              | evidence             | recommended_next_step                                |
-| ------------------- | ------------------------------------------------ | -------------------- | ---------------------------------------------------- |
-| `<metadata source>` | 已辨識 authoritative source，但 records 尚不可得 | `<catalog evidence>` | request/read export with the minimal metadata fields |
-
-coverage item 應同時保留 acquisition failure status。例如 DB client/parser/CLI 不存在寫 `missing_tool`，credentials 不足寫 `missing_credentials`，可連線或可讀但無權限寫 `permission_denied`，檔案可讀但解析失敗寫 `parse_failed`。不要使用籠統的 `not exported in repo` 取代 acquisition status。