ops-wiki-agent-kit 0.1.0 → 0.1.1

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

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

@@ -39,12 +39,13 @@
 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 規則。
+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
 
@@ -67,8 +68,8 @@
 
 - 只能透過 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。
+- 沒有獨立 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。
 
@@ -78,7 +79,7 @@
 
 `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`。
+若某列來自 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。
 
@@ -91,13 +92,22 @@
 - 排序、重新分組、合併 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、module、responsibility、ERP application 或 navigation section；其次才使用 route prefix、package/module、bounded context、primary data resource、scheduler/config/folder 類別。完全沒有 source-backed grouping 時才使用 `Unclassified`。
+`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 class、scheduler key、command、ERP program/transaction/form id、file watcher/import/export handler。完整 call chain 應放在 feature SPEC，不放進此欄。
+`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` 定義。
 
@@ -107,6 +117,8 @@
 
 `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
 
 完成前必須逐項確認：
@@ -116,10 +128,45 @@
 - `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`、`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 推論而來。
+- `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]` 是否已清理；若有保留，列出保留理由。