ops-wiki-agent-kit 0.1.0 → 0.1.1

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

@@ -43,7 +43,7 @@
 | 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              |
+| Data pipeline    | DAG definition、pipeline catalog、ETL/ELT config、stream processor topology                        | task modules、query/model definitions、source/sink resources      |
 
 ## Metadata Acquisition Decision
 
@@ -66,6 +66,53 @@
 
 每個 named source 的 acquisition status 必須寫入 acquisition ledger 或 final response。常用 status 包含 `collected_success`、`parsed_success`、`direct_rows_accepted`、`zero_rows_with_count`、`source_unavailable`、`parse_failed`、`connection_failed`、`missing_tool`、`missing_credentials`、`permission_denied`、`user_input_required`、`user_declined`。只有成功取得/解析 rows，或有 count evidence 的 zero-row result，可以宣告為 validated source。
 
+## Source Acquisition Gate
+
+對每個 handoff/source scope 先建立 acquisition attempt record，再進行 conversion。沒有 attempt record 時，不可把 source 移到普通 coverage gap。
+
+| status | Meaning |
+| ------ | ------- |
+| `collected_success` | 成功取得 rows，且有可重讀 export/result set/source file 與 count evidence。 |
+| `parsed_success` | 成功解析 repo/file/catalog/config/hardcoded source rows。 |
+| `direct_rows_accepted` | catalog/handoff 中已列出的 direct rows 被採用，且 count 可驗證。 |
+| `zero_rows_with_count` | 成功查詢或解析，但符合條件 rows 為 0；必須有 count evidence。 |
+| `source_unavailable` | source 已辨識，但目前不可讀、不可查或不在 workspace/environment。 |
+| `parse_failed` | source 可讀但解析失敗或欄位不足。 |
+| `connection_failed` | DB/API/platform connection profile 已嘗試但失敗。 |
+| `missing_tool` | 需要的 native client、parser、CLI、SDK 或 helper 不可用。 |
+| `missing_credentials` | repo discovery 後仍缺少必要 credentials、token 或 session secret。 |
+| `permission_denied` | source 可連線/可讀但無 table/schema/file/API 權限。 |
+| `user_input_required` | 需要使用者提供最小 export、file、config excerpt 或 connection detail。 |
+| `user_declined` | 使用者拒絕本次 source acquisition。 |
+
+只有 `collected_success`、`parsed_success`、`direct_rows_accepted` 與有 count evidence 的 `zero_rows_with_count` 可以進入 final count validation。其他 status 必須留在 blockers 或 coverage review。若該 source 是 required、complete inventory 或 final row authority，不可用弱推論替代它。
+
+Required source 是指 catalog/handoff 標示為 `acquisition_required`、`final_row_authority=yes`、完整 inventory source，或沒有它就無法正確枚舉該 target scope 的來源。它可能是 DB table、hardcoded registry、config file、route table、scheduler file、external export、ERP/platform metadata、catalog table 或使用者提供的清單。
+
+## Acquisition Reuse, Retry Budget, And Self-Healing
+
+同一輪 workflow 可以完成 acquisition、normalization、writer 與 validation，但每個 source scope 的 acquisition 結果必須先固化成 repo-local canonical extract，再進入後續步驟。後續 preparation script、manual parse、writer input 與 validation 只能讀 manifest 指定的 repo-local extract；不得讀取 chat tool、IDE、terminal session 或其他使用者環境中的暫存輸出。
+
+若 `target/docs-target-queue-from-catalog/source-manifest.json` 已有某 source scope 的 canonical extract，且該檔案存在、checksum 可驗證、row count 可重算，預設沿用該 extract，不重新連線或重新查詢。只有下列情況可以 refresh acquisition：
+
+- 使用者明確要求 refresh。
+- manifest 缺失、checksum 不符、extract 不可讀，或 row count 無法重算。
+- extract 缺少 `docs/docs-target-queue.md` 必要欄位，且無法從既有 source file / catalog table / bounded lookup 補齊。
+- 前次 acquisition status 是 `parse_failed`、`connection_failed`、`missing_tool`、`missing_credentials`、`permission_denied` 或其他會使 extract 不可信的 failure。
+
+DB source 的同輪 query budget：
+
+- 每個 DB profile 最多一次 harmless connection validation；已有本輪成功證據時不可重測。
+- 每個 source family 最多一次 schema/column discovery；只有欄位不確定時才執行。
+- 每個 source scope 最多一次正式 acquisition query/export；若第一次 query 因欄位缺失或 parse failure 需要修正，第二次 query 必須記錄原因，並淘汰舊 extract 或在 manifest 中標示 superseded。
+- 不可只因 native DB client 或 terminal 顯示格式不方便解析而重新查 DB；應將已取得的 raw output 轉成 delimiter-stable `csv`、`tsv` 或 `jsonl` extract。
+
+在 final response 或寫入 queue 前，先檢查 acquisition ledger 是否有未完成的 required DB source。若 source scope 是 `query/export`，指向 DB table、view、scheduler metadata、job metadata 或其他 metadata store，且本輪沒有 DB discovery、client check、harmless connection validation、bounded read-only query attempt 或具體 failure status，必須回到 `database-query` acquisition path 重試，不可直接 final。
+
+自我修復重試時，至少執行 repo-first DB config discovery，確認可用 client/helper，先跑 harmless validation query，再做 bounded read-only acquisition。若仍不能查，ledger 必須改成具體狀態：`missing_tool`、`missing_credentials`、`connection_failed`、`permission_denied` 或其他可診斷 failure；不要保留籠統的 `user_input_required` 取代實際 failure。
+
+若 ledger 已有本輪有效 canonical extract，self-healing 不可重新 DB acquisition；應先修正 parser、normalization mapping 或 writer input。只有 extract 本身缺失、不可驗證或缺少必要欄位時，才回到 DB acquisition path。
+
 ## Minimal Metadata Fields
 
 只取得最小且足夠使用的資料形狀即可。不同系統的 field names 會不同，因此應依語意對應，而不是硬套精確的欄位名稱。
@@ -74,11 +121,11 @@
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
 | 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`                                  |
+| grouping            | parent menu label/name、module、application、domain、responsibility、system、category                                                                             | `group`                                  |
 | activation target   | path、route、handler、command、job key、program name、process name                                                                                                | `entrypoint`                             |
 | source type         | menu、API、job、report、file process、ERP/platform program/transaction、integration、command、workflow、mobile screen、desktop action、library API、data pipeline | `source_type`                            |
 | status              | active/enabled/deprecated/hidden/environment-specific                                                                                                             | coverage review 或 filtering             |
-| parent relationship | parent menu id、route group、workflow parent、report group                                                                                                        | merge/split 判斷                         |
+| parent relationship | parent menu id、route group、workflow parent、report group                                                                                                        | merge/split 判斷；不可直接取代 `group`   |
 | permission boundary | role、permission code、responsibility、access profile                                                                                                             | top-level target 證據                    |
 | source file/path    | file path、export path、route config path、source location                                                                                                        | evidence、parse request                  |
 
@@ -93,7 +140,16 @@ 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。
+DB/native-client output 的職責只到 acquisition：輸出 rows、counts、執行過的 query 摘要與不確定性。不要在 DB query 步驟產生 `docs/docs-target-queue.md` 或只服務單一 source/system/language 的 converter script。
+
+DB/native-client output 必須落地成 repo-local evidence，路徑位於 `target/docs-target-queue-from-catalog/**`。不要讓後續 parser、preparation script 或 writer 讀取 chat/IDE session 暫存輸出、terminal scrollback、clipboard、外部 user profile 暫存目錄，或其他不可由 repo 重讀的來源。若工具只能先產生 console output，先將原始輸出保存為 raw evidence，再轉成 delimiter-stable canonical extract。
+
+## Native Client Script Safety
+
+- 寫入 native-client script 前，先建立 repo-local staging folder；不要假設 shell redirection、file write helper 或 client wrapper 會自動建立 parent directory。
+- DB client script 應先寫入具名 script file，再以變數保存的 path 呼叫 native client；不要把 script body、file write 與 native client invocation 串成難以除錯的長單行。
+- Shell command 應設定 fail-fast 行為；寫檔失敗、script 產生失敗或 client preflight 失敗時，不得繼續執行 DB client。
+- 呼叫 native client script 時，將 script path 作為單一 argument 或明確 quoted argument 傳入；避免在長單行中直接嵌入未 quote 的相對路徑，以免 path quoting、argument parsing 或 line wrapping 造成 shell 層解析錯誤。
 
 ## Non-DB Source Collection
 
@@ -114,25 +170,64 @@ DB/native-client output 的職責只到 acquisition：輸出 rows、counts、執
 - 如果 source 是 catalog Markdown table，`authoritative_source` 應指出 section/table 名稱，`acquisition_method` 可使用 `parse_catalog_table` 或 `direct_rows`。
 - 如果 source 可讀但 rows 缺少 `name`、`entrypoint` 或 `keyword` 所需欄位，先回 source/context 做 scoped lookup；仍無法補齊時放入 coverage review。
 
+## Canonical Source Extract Manifest
+
+每個 source scope 只能有一個 canonical extract 進入 normalization。Acquisition 完成後，先寫入或更新 `target/docs-target-queue-from-catalog/source-manifest.json`，以 array/object 形式記錄每個 scope：
+
+```json
+{
+  "target_scope": "User-facing navigation registry",
+  "source_kind": "metadata store",
+  "authoritative_source": "<metadata_store_or_registry_name>",
+  "acquisition_method": "query/export",
+  "canonical_extract_path": "target/docs-target-queue-from-catalog/navigation_rows.tsv",
+  "format": "tsv",
+  "selected_fields": ["stable_key", "parent_key", "sort_key", "display_name", "activation_target"],
+  "filter_or_scope": "all in-scope rows from <metadata_store_or_registry_name>",
+  "raw_count": 135,
+  "eligible_count": 116,
+  "excluded_count": 19,
+  "gap_count": 0,
+  "parser_or_command": "native DB client export -> tsv parser",
+  "generated_at": "2026-06-15T14:38:24+08:00",
+  "checksum": "sha256:<hex>"
+}
+```
+
+`canonical_extract_path` 必須是可重讀檔案，且 row count 可由 parser 重算。若同 scope 有多個候選檔，先列出候選檔的 path、mtime、size、checksum 與可解析 row count，停止 normalization；不要自動選最新檔或檔名看似正確的檔案。
+
+Preferred extract format 是 `jsonl`、`csv` 或 `tsv`。避免把 native-client / console 視覺表格當 canonical extract；若工具只能輸出文字表格，必須先轉成 delimiter-stable extract，並把原始輸出當 evidence，不可直接作為 writer input。
+
+Manifest reuse rules：
+
+- 如果 manifest 指向的 `canonical_extract_path` 存在、checksum 符合、row count 可重算，後續 normalization / validation 必須沿用該 extract，不重新連 DB 或重新 parse terminal output。
+- 如果需要重跑 acquisition，必須在 manifest 或 acquisition summary 說明 refresh reason，例如 missing required field、parse failure、checksum mismatch、user requested refresh。
+- 若新 extract 取代舊 extract，manifest 必須只 pin 新 canonical extract；舊 spool/export 若保留，必須標示為 superseded evidence，不可再被 writer input 使用。
+- `source-manifest.json` 不能只記 summary status；進入 main table 的 source scope 必須至少記錄 `canonical_extract_path`、`format`、`raw_count`、`eligible_count`、`excluded_count`、`gap_count`、`parser_or_command` 與 `checksum`。
+
 ## DB Query Guardrails
 
 - 將 catalog/handoff 的 `authoritative_source` 視為白名單；schema lookup 只可針對被點名的 table、view、metadata store 或其必要 key relation。
 - 對白名單中的 DB source，先做 repo-first DB discovery 與 harmless connection validation；失敗時記錄 failure status，不可靜默略過。
+- 同一輪 workflow 中，每個 DB profile 最多做一次 harmless connection validation；已有成功 validation evidence 時，不可為每個 source scope 重複測試連線。
+- 每個 source family 最多做一次 schema/column discovery；只有欄位不確定、catalog 欄位與實際 schema 不一致，或 query parse 失敗時才做 discovery。
 - 優先使用一個 target scope 一個 query/export。若同一 scope 需要多個 table，先取得 base table 的 row set，再逐一加入已證明必要的 relation。
+- 每個 source scope 原則上只做一次正式 acquisition query/export。第二次 acquisition 只允許用於修正欄位缺失、parse failure、schema mismatch 或使用者要求 refresh，且必須記錄原因與淘汰舊 extract；不可因 native-client 顯示排版不便、欄寬不滿意或 terminal output 不好讀而重新查 DB。
+- 在寫 query 前先決定 output shape：固定欄位、固定排序、delimiter-stable `csv`/`tsv` 或可轉換 raw output、count query 與 data query 的對應關係。不要先查 sample 再靠模型反覆猜欄位。
 - 禁止 `SELECT *`、業務資料明細、交易 payload、大量 text/blob 欄位，以及與 `docs-target-queue.md` 無關的欄位。
 - status/filter 欄位必須來自 catalog、source code、schema evidence 或使用者提供的 metadata 說明；不要猜測 `ACTIVE_FLAG`、`ENABLE`、`STATUS` 等欄位是否存在。
-- Oracle treats empty string as `NULL`；判斷非空文字欄位時使用 `trim(column) is not null`，不要用 `trim(column) <> ''`，否則 eligible count 可能被錯算為 0。
+- 文字空值判斷必須符合實際 DB engine 的 `NULL` / empty-string semantics；不要把某一種 query dialect 的空字串判斷硬套到所有資料庫，否則 eligible count 可能被錯算。
 - join 只能用於 visibility、permission、parent/grouping、activation target 或 enabled status 判斷；必須能說明 join key 與 row eligibility 的關係。
 - 不要把 menu/navigation、batch scheduler、report profile、permission、business transaction table 等不同 source family 用一個 broad query 混在一起。
-- query/export 後要保留可重讀 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。
+- query/export 後要保留 manifest 指定的可重讀 result set 或明確 row export，不要只從 terminal scrollback 手工組 markdown。
+- 每個 query/export 都要記錄 raw row count、套用 filter 後的 eligible count、排除 count 與 gap count；count 無法對上或無法由 canonical extract 重算時，該 source 不可進 final table。
+- Query/export script 若保留，只能作為可重跑 acquisition recipe。最終轉換應使用 normalized rows 與 `scripts/write_documentation_target_queue.py`，不要把 query script 當成 `docs-target-queue.md` 的 conversion source of truth。
 - 若 source 是 required、complete inventory 或 final row authority，例如 menu/navigation inventory、route registry、scheduler registry、report profile registry、hardcoded command registry、external navigation export、ERP/platform metadata catalog，acquisition 未成功時只能產出 partial candidate、incomplete note 或 acquisition request，不可覆蓋較完整或狀態不明的正式 `docs/docs-target-queue.md`。
 
 ## Mapping Rules
 
 - `source_type`: 應選擇 activation surface，而不是 implementation language。
-- `group`: 使用 metadata 中的 parent menu/module/application/responsibility/domain/category。
+- `group`: 使用 metadata 中的 parent menu label/name、module/application/responsibility/domain/category；若 raw source 只有 parent id，必須先以同一 canonical extract 或同一 authoritative source 反查 parent label/name，再寫入 `group`。不得在 parent label/name 可反查時把 raw key 直接格式化為 `Menu:<id>`、`Parent:<id>` 或同類 debug fallback。若 parent id 無法反查，將該 row 放入 coverage/blocker 或使用 source-backed 上層 category；只有完全沒有 source-backed grouping 時才使用 `Unclassified`。
 - `name`: 優先使用 user/operator 可見的 label，而不是 handler 或 file name。
 - `entrypoint`: 使用精簡的 activation target，例如 route、command、job key、program id、report id 或 main handler。
 - `keyword`: 使用 metadata 中最穩定、最適合搜尋的識別值。

package/.github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py

@@ -19,6 +19,7 @@ else:
     raise SystemExit("Cannot locate source-code-to-spec-tools/scripts/queue_contract.py")
 
 from queue_contract import (
+    BASELINE_STATUSES as VALID_BASELINE_STATUSES,
     DOC_STATUSES as VALID_DOC_STATUSES,
     COVERAGE_COLUMNS,
     DEFAULT_PATH_PATTERNS,
@@ -133,6 +134,11 @@ def normalize_targets(rows, prefixes):
         entrypoint = normalize_text(row_get(row, "entrypoint", "activation_target", "route", "path", "command"))
         keyword = normalize_text(row_get(row, "keyword", "stable_key", "key", "code", "id"))
         document_path = normalize_text(row_get(row, "document_path", "doc_path"))
+        baseline_status = normalize_status(
+            row_get(row, "baseline_status"),
+            VALID_BASELINE_STATUSES,
+            "pending",
+        )
         foundation_doc_status = normalize_status(
             row_get(row, "foundation_doc_status"),
             VALID_DOC_STATUSES,
@@ -187,6 +193,7 @@ def normalize_targets(rows, prefixes):
                 "document_path": document_path,
                 "keyword": keyword,
                 "doc_profile": doc_profile,
+                "baseline_status": baseline_status,
                 "foundation_doc_status": foundation_doc_status,
                 "architecture_doc_status": architecture_doc_status,
                 "ops_doc_status": ops_doc_status,
@@ -217,8 +224,18 @@ def dedupe_targets(rows):
     return list(deduped.values())
 
 
-def sort_targets_by_source_type(rows):
-    return sorted(rows, key=lambda row: normalize_text(row.get("source_type", "")).casefold())
+def target_sort_key(row):
+    return (
+        normalize_text(row.get("source_type", "")).casefold(),
+        normalize_text(row.get("group", "")).casefold(),
+        normalize_text(row.get("name", "")).casefold(),
+        normalize_text(row.get("entrypoint", "")).casefold(),
+        normalize_text(row.get("keyword", "")).casefold(),
+    )
+
+
+def sort_targets_for_id_assignment(rows):
+    return sorted(rows, key=target_sort_key)
 
 
 def parse_existing_ids(path):
@@ -509,8 +526,8 @@ def main():
     summary = normalize_summary(read_rows(args.summary))
     coverage = normalize_coverage(read_rows(args.coverage) if args.coverage else [])
     existing_mapping, used_original_ids = parse_existing_ids(args.existing)
+    targets = sort_targets_for_id_assignment(targets)
     targets = assign_ids(targets, prefixes, existing_mapping, used_original_ids)
-    targets = sort_targets_by_source_type(targets)
     validate_main_counts(targets, summary)
 
     output.parent.mkdir(parents=True, exist_ok=True)

package/.github/skills/source-code-to-ops-spec-guidelines/SKILL.md

@@ -52,25 +52,10 @@ description: 在產生、維護、重構或審查 source-code-backed ops SPEC gu
 
 若任務只維護某一份主要 guideline 且不涉及共用文件基礎，可先載入該 owner guideline；涉及 target-facing SPEC generation、Metadata、Obsidian Links、章節適用或圖表格式時，必須載入 `references/supporting-output-format-diagram-and-example-reference.md`。
 
-`doc_file_plan` 用來記錄 generation scope、selected output files、章節 `N/A` / `Unresolved` 原因、coverage gaps 與 handoff impact；reference 檔案選擇以本 skill 的 Reference Routing 為準。
-
-Target-facing SPEC 的內容優先順序是完整、準確、source-backed，其次才是篇幅壓縮或版面簡潔。摘要、維運摘要卡、圖表文字說明、handoff summary 或 cross-reference 只能協助導覽，不可取代正式詳細章節；若來源可確認 handler、service、DAO / Repository / Mapper、SQL、table、status transition、config、job、file I/O 或 external integration 行為，應在對應 scope 的章節保留可審查細節。
-
-Target-facing SPEC 以業務行為、處理流程、資料規則、錯誤處理與維運判斷方式為主。Source path、line、symbol 與 `EvidenceRef[]` 由 `source-code-to-spec-documenter` 的 `handoff.json` 保存；文件本身只在內容需要時保留必要識別資料，例如 API path、SQL ID、table、status column、job name、config key、file name、log keyword 或 trace id，且應整合到對應章節的操作、資料、狀態或錯誤欄位中。
-
-`doc_profile=full` 代表 selected scope 內採完整深度，不是把 source-backed detail 壓成摘要。Full profile 至少應保留：
-
-- 可從 source 讀取的完整 SQL excerpt；若 SQL 是動態組合，保留 source-backed pseudo SQL、組合條件、參數來源與限制。
-- DAO / Repository / Mapper method 與 SQL、table、status column、DB object、stored routine 或 external resource 的 mapping。
-- Handler / controller / job / service 到 DAO method 的可追蹤流程，以及與維運判斷有關的 branch、transaction、rollback、retry、rerun、log、error message 與 status transition。
-- 欄位 mapping、狀態 mapping、request / response mapping、file column mapping 或 external payload mapping 的來源欄位、目標欄位、轉換規則與限制。
-
-不要因為流程、SQL、圖表或資料 mapping 較大就刪減 source-backed detail；必要時拆成多個表格、子章節或多張圖表，並讓每一段都可追溯到 source evidence。
+`doc_file_plan`、full-depth completion gate、source tracing、status transition、handoff 欄位與 write / update behavior 由 `source-code-to-spec-documenter/references/generation-workflow.md`、`source-code-to-spec-documenter/references/source-tracing-rules.md`、`source-code-to-spec-documenter/references/generation-handoff-contract.md` 與 `source-code-to-spec-documenter/references/target-queue-contract.md` 擁有；本 skill 只維護 reference routing 與 target-facing chapter guideline ownership。
 
 Target-facing SPEC 的每一個正式章節都應保留章節標題。若該章節沒有來源資料、已確認不適用，或目前來源不足以填寫，不要硬湊表格、圖表或推測內容；在章節下方輸出一行 `N/A: <簡短原因>`、`無法由目前來源確認: <缺少的 evidence>` 或 `Unresolved: <阻塞原因>` 即可，並將 completion-impacting gap 寫入 handoff。
 
-Target-facing SPEC 的 generation / update 執行流程、source tracing、idempotent update、handoff 欄位與 queue 狀態不由本 skill 維護；請使用 `source-code-to-spec-documenter/references/generation-workflow.md`、`source-code-to-spec-documenter/references/source-tracing-rules.md`、`source-code-to-spec-documenter/references/generation-handoff-contract.md` 與 `source-code-to-spec-documenter/references/target-queue-contract.md`。
-
 ## Ownership Boundary
 
 維護 guideline contract 時，先找 owner，再改 owner。避免同一條規則散落在多份文件中。
@@ -98,16 +83,9 @@ Target-facing SPEC 的 generation / update 執行流程、source tracing、idemp
 7. 若來源不足，guideline 應要求標示 `N/A`、`無法由目前來源確認`、`unknown` 或 `Unresolved`，不得鼓勵 AI 補完不存在的行為。
 8. 不要把歷史範例中的示意 table、狀態值、API、Job 或 DB object 當成真實 source evidence；只能作為格式與顆粒度範例。
 
-## Diagram and Metadata Rules
-
-圖表與 Metadata 的補充規則放在 `references/supporting-output-format-diagram-and-example-reference.md`。維護任一 guideline 時，至少要遵守以下共通規則：
+## Shared Format Rules
 
-- 每張 Mermaid、ASCII Art、ERD、UML、flowchart、sequenceDiagram、classDiagram 或其他圖表後面，必須立即附上 `> 📝 **圖表文字說明**` blockquote。
-- 圖表文字說明必須可獨立閱讀；即使 diagram 無法 render，讀者仍能理解架構、流程、資料關聯、分支結果與維運線索。
-- 圖表負責視覺化，圖表文字說明負責補足完整脈絡；兩者共同構成必填內容。
-- Mermaid `sequenceDiagram` 失敗或例外訊息優先使用 `-x`，避免使用不穩定的 `A--xB` 寫法。
-- Mermaid `erDiagram` 的 PK/FK 標示必須使用雙引號，例如 `string PRODUCT_ID "PK"`。
-- Metadata 與 `## Obsidian Links` 規則以 `references/supporting-output-format-diagram-and-example-reference.md` 為主；若任務明確要求「系統功能規格書」格式，使用同一 supporting reference 的 Metadata variant。
+圖表、Metadata、`## Obsidian Links`、Mermaid / ASCII Art 語法、圖表文字說明與 Metadata variant 的完整規則，統一由 `references/supporting-output-format-diagram-and-example-reference.md` 維護；本 `SKILL.md` 只保留 routing、owner boundary 與 quality gate。
 
 ## Quality Gate
 

package/.github/skills/source-code-to-ops-spec-guidelines/references/01-system-overview-and-business-scenarios-guideline.md

@@ -16,8 +16,6 @@
 
 本文件本身不是交付給維運人員閱讀的最終文件，而是提供 AI 產生最終維運文件時使用的參考規則與章節範本。
 
-跨 `01`、`02`、`03` 都適用的文件定位、系統單元型態、章節適用判斷、Metadata、`## Obsidian Links` 與章節編號原則，統一由 `supporting-output-format-diagram-and-example-reference.md` 維護，本文件不重複定義。
-
 本文件負責讓第一份維運文件優先回答以下問題：
 
 - 使用者從哪裡進入或觸發這個功能？
@@ -42,12 +40,6 @@
 
 即使在正式編號章節底下，`撰寫目標`、`撰寫要求`、`內容規範`、欄位契約與填寫規則等文字也屬於 guideline 說明；AI 產出最終文件時，應使用這些規則生成實際內容，不應原樣複製規則文字。
 
-## 共用文件基礎規則
-
-跨三份 target SPEC 的文件定位、系統單元型態、章節適用判斷、Metadata、`## Obsidian Links`、reader-facing `Name` / lookup `ID` 規則與產出文件章節編號原則，請依 `supporting-output-format-diagram-and-example-reference.md` 的「跨三份 SPEC 的文件基礎規則」撰寫。
-
-本文件只保留第一份輸出文件的正式章節契約。若需要調整共用文件基礎規則，請修改 supporting reference，不要在本文件新增重複規則。
-
 ---
 
 # 產出文件章節範本