ops-wiki-agent-kit 0.1.1 → 0.1.3

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

@@ -1,194 +0,0 @@
----
-name: docs-target-catalog
-description: 依 source code 盤點 repo 的 documentation targets，例如 menu/navigation target、API、job、command、screen、report、integration 與其他可直接觸發的 entrypoint。當使用者要建立 source-backed target catalog，或區分 top-level target 與 CRUD、view、helper、dialog 等附屬檔案時使用。
----
-
-# Documentation Target Catalog
-
-## Overview
-
-先從 activation surface 建立 documentation target catalog，再用檔案作為佐證。除非 source evidence 明確顯示該檔案可被獨立觸發，否則不要把 file type、filename 或單一畫面檔直接視為 target boundary。
-
-本 workflow 的術語必須與 repo shared terminology contract 對齊；若 repo 提供 `.github/skills/source-code-to-spec-tools/references/terminology-contract.md`，以該檔為準。`documentation target` 是可被獨立啟動或使用者指定的文件目標；`keyword` 不是 target queue；`Function` 不泛指 method/helper；document section 不是 `source_type`；未限定的 `source` 應改寫成 `source code`、`source evidence`、`authoritative source`、`source extract` 或 `source_type`。
-
-## Core Rule
-
-優先採用以下 evidence 順序：
-
-1. Authoritative registries：menu tables、navigation registries、permission mappings、route registries、scheduler registries、ERP metadata、DB job definitions、repo-owned hardcoded menu/navigation/command definitions、client-side navigation config、external menu/config files。
-2. Runtime entrypoints：controllers、API routes、service endpoints、message consumers、CLI commands、workflow definitions、mobile/desktop navigation nodes、public library exports、data pipeline definitions。
-3. Handler call chains：controller/action -> service -> DAO/repository -> SQL/table/file/queue。
-4. Implementation files：JSP/JS/TS/Java/C#/SQL/report/form files 僅作為 supporting evidence，預設不視為 standalone documentation targets。
-
-如果某個看似獨立的 screen 或 file 沒有對應的獨立 menu、route、permission、job、API、command 或 navigation entry，應將它分類為 sub-action、helper、partial、include、dialog、report asset，或 unresolved candidate。
-
-## Authority Disambiguation
-
-- 將 bootstrap、control-plane 與 row authority 分開處理。若 startup、monitor、launcher、dispatcher、wrapper、deployment switch 或 polling loop 只是啟用、重啟、輪詢、委派或包裝另一個 runtime unit，它最多只能作為 activation clue 或 control evidence；必須再追一跳到真正列舉、註冊、排程、載入或組裝 target rows 的 registry / metadata source。
-- 若同一 activation surface 同時出現 deployment config、persisted metadata、repo-owned hardcoded registry、generated export、external metadata 或其他 candidate authorities，請分 scope 記錄。只有直接產生或載入 target rows 的來源可標為最終 row authority；其餘來源應保留為 enablement/control evidence、獨立 acquisition scope，或 coverage gap。
-- 在 handoff 定稿前，對每個 registry-driven scope 至少做一個便宜的反證檢查：確認 candidate source 是否真的被 runtime 直接讀取、實例化、註冊或 build；若發現還有更直接的 registry read / metadata load path，應改由後者擔任 authoritative source。
-
-## Workflow
-
-### 1. Fingerprint The Repo
-
-在列舉 documentation targets 前，先辨識 runtime types：
-
-- Languages and frameworks。
-- Runtime types：web、mobile、desktop、batch/job、DB-heavy、ERP、integration、reporting、command、workflow、library/API、data pipeline。
-- 可能的 entrypoint mechanisms：menu source、router、controller、scheduler、DB job、target registry、API、queue、file watcher、command line、workflow engine、package export、DAG/pipeline registry。
-- 能揭露 runtime shape 的 build/deploy/config files。
-
-當 repo 屬於 mixed-stack，或需要判斷該從哪裡搜尋 authoritative entry sources 時，閱讀 `references/entrypoint-source-patterns.md`。
-
-### 2. Discover Authoritative Entry Sources
-
-在大範圍列舉檔案之前，先搜尋有 source backing 的 activation surfaces：
-
-- 來自 config、SQL seed、migration、XML/YAML/JSON、code constants、hardcoded menu/navigation/command code、client-side router/navigation config、external menu/config file、ERP metadata 或 DB access code 的 menu/navigation/permission metadata。
-- Web routes、frontend routers、server controllers、JSP/Struts/Spring/.NET route mappings。
-- Mobile navigation graphs、activities/screens、deep links、tab definitions。
-- Desktop menus、command bindings、toolbar actions、form/window registries。
-- Scheduler/job definitions、batch launchers、DBMS scheduler、SQL Agent、Quartz、Hangfire、cron、Windows services。
-- API/service/message/file/CLI/workflow/library/data-pipeline entrypoints。
-
-如果 target、menu 或 navigation list 看起來只存在於 production DB data，請記錄推定來源，並把缺少的 DB seed/data 標記為 unresolved coverage item。
-
-如果 menu、navigation、command 或 job list 是寫死在 repo code/config 中，且該 code/config 是 runtime 實際使用的 activation source，請把它視為 repo-owned authoritative source，逐列列出 hardcoded targets、labels、handlers 與 source lines。不要只把 hardcoded targets 當作 supporting evidence。
-
-如果 menu 由 client-side router、SPA navigation config、mobile navigation graph、desktop command config、external JSON/YAML/CSV/XML、CMS export、deployment-mounted file 或 vendor/platform metadata 產生，請把該來源視為該 scope 的 candidate authority。若檔案或 export 在 repo 中可讀，逐列解析；若只知道來源名稱但拿不到 rows，列入 handoff 的 acquisition/parse request，不要退回用 page files 猜測。
-
-### 2.1 Produce Authoritative Target Source Handoff
-
-在 output 中加入 `Authoritative Target Source Handoff` section，明確交接給後續 `docs-target-queue-from-catalog`：
-
-- `target_scope`: 這個來源負責哪些 documentation targets。
-- `source_kind`: `DB metadata`、`repo-owned config`、`repo-owned hardcoded code`、`client-side navigation`、`external file`、`route registry`、`scheduler registry`、`external metadata` 等。
-- `authoritative_source`: table、file、config、registry、API、export 名稱。
-- `final_row_authority`: 是否可作為該 scope 的最終 target rows；若仍缺 rows，說明需要 acquisition。
-- `required_fields_or_handles`: 第二階段要取得或使用的最小欄位/handle。
-- `target_queue_action`: 第二階段應 `query/export`、`parse_file`、`direct_rows` 或 `coverage_gap`。
-
-DB-backed source、client-side source、external file source 與 hardcoded source 可以同時存在，但必須分 scope。不要把 DB table 說成整個系統唯一來源，如果 repo、client 或 external file 另有 menu/navigation entries；也不要因 DB menu 缺失而忽略已確認的 non-DB entries。
-
-authority 判定若有疑義，回到上面的 `Authority Disambiguation` 規則處理；不要在 handoff table 內同時把 control-plane source 與 final row authority 寫成同一列。
-
-### 3. Build An Entrypoint Inventory
-
-每個可由 source 驗證的 entrypoint 建立一列，內容包含：
-
-- Stable id。
-- Entry type：menu、route、API、job、DB job、report、screen、command、workflow、queue consumer、file import/export、ERP program/transaction、mobile screen、desktop action、library API、data pipeline。
-- Display label 或 technical name。
-- Source file/table/config 與可精準搜尋的 handle。
-- Target handler。
-- 若存在則記錄 access control、permission code 或 runtime metadata 明確提供的 metadata code。
-- Unresolved notes。
-
-### 4. Trace Implementation Scope
-
-對每個 entrypoint，只 trace 到足以辨識 feature boundary 的深度：
-
-- UI/screen/view files。
-- Controller/action/handler。
-- Service/domain logic。
-- DAO/repository/stored procedure/package。
-- Tables/views/files/queues/external systems。
-- Reports/templates/download/upload resources。
-
-保留可直接回查 source 的精確 handle。如果 call chain 分叉進入 shared framework code，請在 shared boundary 停止並加註說明。
-
-### 5. Cluster Into Documentation Targets
-
-當多個 files/actions 共享明確證據時，將它們歸納到同一個 documentation target：
-
-- 相同的 menu/navigation/permission code，或 runtime metadata 明確提供的 metadata code。
-- 相同的 route prefix 或 navigation path。
-- 相同的 controller/handler family。
-- 相同的主要 business noun 與 data resource。
-- 只能透過同一個 parent entry 進入的 CRUD/detail/popup/export/import actions。
-
-若存在獨立的 activation evidence，則應拆分為不同 documentation targets：
-
-- 獨立的 menu item 或 ERP program/transaction metadata。
-- 獨立的 permission code，或 runtime metadata 明確提供的 metadata code。
-- 獨立的 scheduler/job/API/command/workflow/queue entry。
-- 獨立的 mobile/desktop navigation node、public library export 或 data pipeline definition。
-- 獨立的 business outcome 或主要 data resource。
-- 不需經過 parent、可由 user/system 直接進入。
-
-### 6. Classify Target Vs Sub-Action
-
-如果某項能力擁有自己的 entry source、可被直接觸達，或具有獨立 authorization boundary，就歸類為 top-level documentation target。
-
-如果它只是 parent target 底下的子動作，且缺乏獨立 entry evidence，例如 `create`、`edit`、`delete`、`detail`、`lookup`、`popup`、`partial`、`include`、`print`、`export` 或 `upload` screens，則歸類為 sub-action。
-
-避免把每個 JSP、Razor page、SQL file、stored procedure 或 CRUD method 都提升成 top-level target。
-
-### 7. Produce Navigation-First Outputs
-
-優先輸出以下結果，並依使用者需求調整粒度。下列 filename 只是常見 convention，不是硬性規定；如果 repo 已有自己的 docs 命名或 folder 慣例，請沿用既有慣例。當目標是交接給 `docs-target-queue-from-catalog` 或產生 `docs-target-queue.md` 時，不要強制先產生 feature catalog。
-
-- `Compact handoff catalog`: 當目標是交接給 `docs-target-queue-from-catalog` 或產生 `docs/docs-target-queue.md`，預設只輸出精簡 source handoff、direct rows 與 coverage review；不要輸出完整 per-target deep dive，除非使用者明確要求 deep mode。
-- `<feature-catalog-file>`：grouped business capabilities with entrypoints, actions, source evidence, unresolved items；如果 repo 採用 numbered feature-catalog convention，請使用 repo 現有或使用者指定的 catalog filename。
-- `<entrypoint-map-file>`：raw menu/route/API/job/screen/command entries mapped to handlers and documentation targets；如果 repo 採用 numbered source-map convention，請使用 repo 現有或使用者指定的 entrypoint-map filename。
-- `<data-resource-map-file>`：table/procedure/file/queue/resource backtracking to documentation targets；如果 repo 採用 numbered source-map convention，請使用 repo 現有或使用者指定的 data-resource-map filename。
-- `Authoritative Target Source Handoff`: source-of-truth map for `docs-target-queue-from-catalog`.
-- `<target-handle-index-file>`：exact searchable menu/API/job/report/command handles。
-- `<scheduler-target-index-file>`：exact searchable batch/job/scheduler handles。
-- Coverage review：缺漏或 source evidence 不足的 entry sources、疑似僅存在於 DB 的 menu data、尚未 trace 的 handlers、orphan files。
-
-當要產出可重用的 files 或 tables 時，閱讀 `references/output-templates.md`。
-
-Compact handoff catalog 的預設 sections：
-
-- `Repo Fingerprint`: 只保留影響 authoritative source 搜尋的最小 facts。
-- `Authoritative Target Source Handoff`: 每個 target scope 一列，直接指定第二階段 `query/export`、`parse_file`、`direct_rows` 或 `coverage_gap`。
-- `Direct Target Rows` 或 `Hardcoded Target Rows`: 只列可直接轉成 `docs-target-queue.md` 的 repo-owned rows。
-- `Coverage Review`: 集中列出缺少 metadata、弱證據 candidates、orphan handlers，以及不能進入主表的 source gaps。
-
-Compact handoff catalog 不應輸出完整 call chain、完整 data-resource map、逐 target `Unresolved: None`，或只根據 summary/candidate 展開的 target rows。
-
-當要在 `docs/**/*.md` 下寫入 compact handoff catalog 時，加入精簡 `## Obsidian Links`；links 只可使用已確認存在、或本次同時建立的 notes。沒有可靠 links 時可省略整個區塊；不要加入 placeholder、sample hub、YAML frontmatter、tags 或其他非 contract metadata。
-
-## Source Gap Handling Rules
-
-不要輸出額外判斷分類。可由 entry source、handler 或 runtime metadata 回查的 target 才放入 documentation targets；其他命名推測、間接引用、不完整 trace 或 repo 外來源缺口，集中放在 `Coverage Review`，並只保留 gap、affected scope 與 recommended next search。
-
-## Search Guidance
-
-可使用 repo shared source lookup CLI 作為 source evidence lookup 輔助，再依結果補充人工閱讀。不要只靠散落的手動 `rg` scrollback 形成 catalog evidence，也不要呼叫其他 skill 私有 `scripts/` 目錄。
-
-當需要重複查找 source evidence，且 repo 提供 `.github/skills/source-code-to-spec-tools/scripts/source_lookup.py` 時，可使用以下命令：
-
-```bash
-python .github/skills/source-code-to-spec-tools/scripts/source_lookup.py --root <source-root> --handle "<entrypoint-pattern>" --ignore-case --output json
-python .github/skills/source-code-to-spec-tools/scripts/source_lookup.py --root <source-root> --handle "<registry-keyword>" --include "**/*.xml" --include "**/*.json" --include "**/*.yaml" --context 2
-```
-
-若使用 `source_lookup.py`，其輸出必須保留到工作摘要或 evidence note 中，至少包含 `path`、`line`、`handles` 與 matched text。若需要 structured config parser 或 DB/API acquisition，CLI lookup 只作為定位輔助，不可取代真正的 row authority。
-
-先廣泛盤點 repo 檔案，再搜尋 entrypoint patterns。把 registries 中的名稱往回搜尋到 code，也把 handler 名稱往前追到 views、services、data access。若可行，優先使用 structured config 或 parser-aware 的讀法；但在 discovery 階段，簡單搜尋也可接受。
-
-可使用的通用搜尋詞包含：
-
-- `menu`, `function`, `permission`, `role`, `auth`, `module`, `program`, `screen`, `form`
-- `route`, `controller`, `request`, `action`, `endpoint`, `api`
-- `job`, `schedule`, `cron`, `batch`, `worker`, `queue`, `consumer`
-- `report`, `export`, `import`, `upload`, `download`
-- `procedure`, `package`, `dbms_scheduler`, `sqlagent`, `trigger`
-
-## Output Standard
-
-每個 confirmed documentation target 都必須附上 source evidence。每一列或每個區段都應回答：
-
-- 由什麼機制啟動？
-- 啟動點定義在哪裡？
-- 會執行哪個 handler？
-- 它代表哪一種 user/system action？
-- 哪個 authoritative source 應作為後續 `docs-target-queue.md` 的 row source？
-- 哪些 files/resources 只是 implementation details？
-- 觸及哪些 data resources？
-- 目前還有哪些 source evidence gap 或 unresolved items？
-
-當使用者要的是 target catalog，不要只產出 docs-first 或 architecture-only 的摘要。結果應以便於 lookup 與 source navigation 為優先。

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

@@ -1,164 +0,0 @@
-# Documentation Target Queue Conversion
-
-當使用者明確要求同一輪將 source-code documentation target catalog 轉成 repo root `docs/docs-target-queue.md`，或下游 `docs-target-queue-from-catalog` 需要讀取 catalog handoff 時，才使用這份參考。一般 catalog discovery 不需要載入本文件。
-
-## Shared Queue Contract
-
-Queue 欄位順序、supporting table 欄位、status enum、`doc_profile` 規則、`source_type` registry、prefix 與 `document_path` default pattern 以 `.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md` 為準；converter scripts 必須 import `.github/skills/source-code-to-spec-tools/scripts/queue_contract.py`。
-
-本文件只說明 catalog-to-queue conversion 的判斷流程，不維護第二份欄位、profile 或 `source_type` 清單。
-
-## Conversion Pipeline
-
-1. 建立或讀取 entrypoint inventory。
-2. 將 entrypoints 與 implementation files 歸併成真正的 documentation targets。
-3. 過濾只屬於 implementation 的 artifacts。
-4. 指派 `source_type` 與穩定的 IDs。
-5. 決定 `group`、`name`、`entrypoint`、`keyword`、`document_path` 與 `doc_profile`。
-6. 初始化 queue 狀態欄。
-7. 輸出精簡表格。
-8. 將排除的 candidates 與尚未解決的 source gaps 放到 coverage review，不要放進主表。
-
-## Row Eligibility
-
-當項目是具有獨立 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 Rules
-
-請使用最符合 activation surface 的具體 source type。一旦檔案已存在，prefix 就要保持穩定。
-
-允許的 `source_type`、prefix、default `doc_profile` 與 `document_path` pattern 由 shared schema contract 的 `Source Type Registry` 定義。如果系統需要其他 source type，代表要透過 registration extension 支援新的 activation surface；先在 shared contract 中定義唯一的大寫 prefix、default `doc_profile` 與 path pattern，再新增資料列。converter 對未知 `source_type` 不會 automatic 接受，除非本次 run 明確傳入 `--prefix source_type=PREFIX`。不要因程式語言不同而新增 type；`source_type` 描述 activation surface，不描述 Java/C#/Python/JavaScript 等 implementation language。
-
-## ID And Original ID Rules
-
-- `original_id` 是同一個 `source_type` 內的流水號。
-- `id` 格式為 `<prefix><original_id>`，例如 `F1`、`J1`、`A1`、`FI1`、`C1`、`W1`、`M1`、`D1`、`L1`、`DP1`。
-- 如果 repo root 的 docs/docs-target-queue.md 已存在，必須保留所有既有的 IDs 與 original IDs。
-- 新增列時，使用該 `source_type` 下一個可用編號。
-- 排序、重新分組、合併 evidence 或修改名稱時，都不要重新編號。
-- 若發現重複 target，保留較舊的 ID，並把較好的 evidence 合併到該列。
-
-## Field Mapping Rules
-
-### `group`
-
-優先順序如下：
-
-1. Menu group、module、responsibility、ERP application 或 navigation section。
-2. 從 route prefix、package/module name、bounded context 或 primary data resource 推得的 business domain。
-3. 由 scheduler/config/folder 推得的 job/report/integration category。
-4. 只有在完全沒有 source-backed grouping 時才使用 `Unclassified`。
-
-### `name`
-
-優先使用 user 或 operator 看得到的名稱：
-
-1. Menu label、ERP program/transaction name、平台 metadata name、report title、job display name、API operation name。
-2. 將 permission/program/metadata code 轉成可讀文字。
-3. 將 route/handler/class/procedure name 轉成可讀文字。
-
-如果已有 parent target name，不要用 helper class 或 child screen 的檔名當作 `name`。
-
-### `entrypoint`
-
-只儲存主要 activation handle。請擇一使用精簡值：
-
-- Menu target file 或 route。
-- API method 與 path，例如 `POST /orders`。
-- Job class、scheduler key、command 或 DB job name。
-- ERP program/transaction/form id。
-- File watcher/import/export handler。
-- Workflow/process definition id、mobile/desktop navigation id、public library export name 或 data pipeline DAG id。
-
-不要把完整 call chain 放進 `entrypoint`。call-chain evidence 應保留在 coverage review 或詳細的 feature catalog。
-
-### `document_path`
-
-請使用 repository-relative paths。Default pattern 由 shared schema contract 的 `Source Type Registry` 定義；path segments 要符合 repo 既有風格，避免使用機器專屬的 absolute paths。
-
-### `keyword`
-
-選擇最容易從 source 搜到、也最能定位 target 的 keyword：
-
-1. 唯一且在 source 中可見的 permission/program/metadata code。
-2. 出現在 source 或 seed data 中的 menu/report/job/API label。
-3. Route path、endpoint path、command name、job id、scheduler key、workflow id、mobile/desktop navigation id、exported API name、pipeline id。
-4. Main handler class/method/procedure 或 primary screen file。
-
-每列只用一個精簡 keyword。若有多個重要 handles，`keyword` 請挑選最可靠的搜尋入口，其餘資訊放到 detailed catalog 或 evidence notes。
-
-### `doc_profile`
-
-`doc_profile` 決定後段 target SPEC 的文件深度；允許值與 default profile rules 由 shared schema contract 定義。若來源沒有提供 profile，依 shared default 補值；不要把所有 row 都預設成 `full`。
-
-## Duplicate And Split Rules
-
-當多筆 entries 其實代表同一個 documentation target 時，應合併為同一列：
-
-- 相同的 menu/navigation/permission code，或 runtime metadata 明確提供的 metadata code。
-- 相同的 parent menu 與相同的 primary business object。
-- 同一個 parent 底下的 CRUD/list/detail/edit/export actions。
-- 同一 target 的多個 aliases 或 localized labels。
-
-當 entries 具有獨立的 documentation scope 時，應拆成多列：
-
-- 不同的 menu 或 permission code。
-- 不同的 scheduler/API/command/ERP metadata。
-- 不同的 report identity。
-- 不同的 external contract。
-- 不同的 business owner 或 lifecycle。
-
-如果無法確定，先保留一列已確認的 parent row，並把不確定的 child 列為 excluded 或 unresolved candidate。
-
-## Coverage Review
-
-在表格後方，必要時補上一段簡短的 coverage review：
-
-| item | reason_not_in_table | evidence | recommended_next_step |
-| ---- | ------------------- | -------- | --------------------- |
-
-適用情況：
-
-- repo 中不存在的 DB-owned menu/navigation metadata。
-- 只靠檔名推測、source evidence 不足的 candidates。
-- 沒有 activation evidence 的 orphan handlers。
-- 可能可獨立存在，但缺少 scheduler/API/menu evidence 的 shared SQL/procedures。
-- 需要業務確認的重複或模糊名稱。
-
-coverage review 是診斷資訊，不屬於 `docs/docs-target-queue.md` 的 main target queue table；必要時放在後段 `## Coverage Review`。
-
-## Minimal Output Contract
-
-當使用者只要求 docs/docs-target-queue.md 時，輸出內容應為：
-
-1. 完全符合 shared schema contract 的 main target queue table。
-2. 依 `source_type` 統計的簡短說明。
-3. 針對 excluded 或 unresolved candidates 的簡短 coverage review。
-
-除非使用者另外要求，否則不要加入 repo fingerprint、完整 call chains、data-resource maps 或詳細 feature sections。
-
-預設輸出檔案固定為 repo root 的 docs/docs-target-queue.md；若 docs 目錄不存在，先建立目錄後再寫入。

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。