ops-wiki-agent-kit 0.1.0 → 0.1.2

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

@@ -1,125 +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 為 `all`，挑選第一筆 `document_completed_flag(Y/N)=N` 的 row。
-5. 若指定 scope 為 `foundation`，挑選第一筆 `foundation_doc_status=pending` 的 row。
-6. 若指定 scope 為 `architecture`，挑選第一筆 `architecture_doc_status=pending` 的 row。
-7. 若指定 scope 為 `ops`，挑選第一筆 `ops_doc_status=pending` 的 row。
-8. No-id auto selection 不自動挑選 `failed`、`partial`、`blocked`、`in_progress`、`generated`、`n/a` 或其他非 `pending` status；若要重跑這些 row，必須明確指定 `id`。
-9. `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 的 DAO/repository/service/helper/utility classes。
-- 只支援 parent target 的 SQL files、stored procedures、packages、triggers 與 views。
-- 若真正的 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 class、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 合併到該列。
-
-## Field Mapping
-
-`group` 優先使用 menu group、module、responsibility、ERP application 或 navigation section；其次才使用 route prefix、package/module、bounded context、primary data resource、scheduler/config/folder 類別。完全沒有 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 class、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`。
-
-## 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。
-- 若 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`、`foundation_doc_status`、`architecture_doc_status`、`ops_doc_status`、`review_status` 與 `document_completed_flag(Y/N)` 都符合允許值。
-- 沒有任何 main table row 只由 filename、class name、file extension、package path 或 catalog summary 推論而來。
-- final mode 的 writer output path 是 `docs/docs-target-queue.md`。若輸出到 `target/docs-target-queue-from-catalog/**`，必須是顯式 partial/staging output，且不可宣告正式 queue 完成。
-- 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 必須說明原因與剩餘風險。

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

@@ -1,149 +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、SQL/model files、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。
-
-## 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、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 判斷                         |
-| 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` 或 project-specific converter script。
-
-## 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。
-
-## 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，不可靜默略過。
-- 優先使用一個 target scope 一個 query/export。若同一 scope 需要多個 table，先取得 base table 的 row set，再逐一加入已證明必要的 relation。
-- 禁止 `SELECT *`、業務資料明細、交易 payload、大量 text/blob 欄位，以及與 `docs-target-queue.md` 無關的欄位。
-- status/filter 欄位必須來自 catalog、source code、schema evidence 或使用者提供的 metadata 說明；不要猜測 `ACTIVE_FLAG`、`ENABLE`、`STATUS` 等欄位是否存在。
-- Oracle treats empty string as `NULL`；判斷非空文字欄位時使用 `trim(column) is not null`，不要用 `trim(column) <> ''`，否則 eligible count 可能被錯算為 0。
-- 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 後要保留可重讀 result set 或明確 row export，不要只從 terminal scrollback 手工組 markdown。
-- 每個 query/export 都要記錄 raw row count、套用 filter 後的 eligible count、排除 count 與 gap count；count 無法對上時，該 source 不可進 final table。
-- SQL/export script 若保留，只能作為可重跑 acquisition recipe。最終轉換應使用 normalized rows 與 `scripts/write_documentation_target_queue.py`，不要把 SQL file 當成 `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/module/application/responsibility/domain/category。
-- `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。