ops-wiki-agent-kit 0.1.0

package/.github/skills/database-query/scripts/find_db_config.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+import sys
+
+sys.dont_write_bytecode = True
+
+import argparse
+import json
+import os
+import re
+from pathlib import Path
+
+
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".idea",
+    ".vscode",
+    "__pycache__",
+    "node_modules",
+    "target",
+    "build",
+    "dist",
+    "out",
+    ".gradle",
+    ".mvn",
+    "vendor",
+}
+
+SCRIPT_SKILL_DIR = Path(__file__).resolve().parents[1]
+
+TEXT_EXTENSIONS = {
+    ".properties",
+    ".yml",
+    ".yaml",
+    ".xml",
+    ".json",
+    ".env",
+    ".ini",
+    ".conf",
+    ".cfg",
+    ".toml",
+    ".sql",
+    ".java",
+    ".kt",
+    ".groovy",
+    ".cs",
+    ".js",
+    ".ts",
+    ".py",
+    ".rb",
+    ".php",
+    ".sh",
+    ".ps1",
+    ".bat",
+    ".cmd",
+    ".txt",
+}
+
+CONFIG_EXTENSIONS = {
+    ".properties",
+    ".yml",
+    ".yaml",
+    ".xml",
+    ".json",
+    ".env",
+    ".ini",
+    ".conf",
+    ".cfg",
+    ".toml",
+}
+
+TEXT_NAMES = {
+    "Dockerfile",
+    "Jenkinsfile",
+    "docker-compose.yml",
+    "docker-compose.yaml",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "package.json",
+    "requirements.txt",
+    "persistence.xml",
+    "context.xml",
+    "tnsnames.ora",
+    "pg_service.conf",
+}
+
+CONFIG_NAMES = TEXT_NAMES | {
+    ".env",
+    ".env.local",
+    ".env.dev",
+    ".env.test",
+    ".env.prod",
+    "application.properties",
+    "application.yml",
+    "application.yaml",
+}
+
+DB_PATTERNS = [
+    ("oracle", re.compile(r"jdbc:oracle:thin|oracle\.jdbc|tnsnames\.ora|SERVICE_NAME|ORACLE_SID", re.I)),
+    ("postgresql", re.compile(r"jdbc:postgresql|org\.postgresql|PGHOST|PGDATABASE|postgres(?:ql)?://", re.I)),
+    ("sqlserver", re.compile(r"jdbc:sqlserver|com\.microsoft\.sqlserver|sqlcmd|Data Source=|Initial Catalog=", re.I)),
+    ("mysql", re.compile(r"jdbc:mysql|com\.mysql|mysql://|MYSQL_", re.I)),
+    ("mariadb", re.compile(r"jdbc:mariadb|org\.mariadb|mariadb://|MARIADB_", re.I)),
+    ("db2", re.compile(r"jdbc:db2|com\.ibm\.db2|DB2", re.I)),
+    ("sqlite", re.compile(r"jdbc:sqlite|sqlite3?|\.db\b|\.sqlite\b", re.I)),
+    ("h2", re.compile(r"jdbc:h2|org\.h2|H2_", re.I)),
+]
+
+CONFIG_KEY_PATTERN = re.compile(
+    r"(?i)("
+    r"spring\.datasource\.[\w.-]+|"
+    r"datasource\.[\w.-]+|"
+    r"r2dbc\.[\w.-]+|"
+    r"hibernate\.connection\.[\w.-]+|"
+    r"database[_\-.]?\w*|"
+    r"db[_\-.]?(host|port|name|user|username|password|passwd|pwd|url|schema)|"
+    r"jdbc[_\-.]?\w*|"
+    r"connection(string)?|"
+    r"url|username|user|password|passwd|pwd|host|port|schema|service_name|sid|"
+    r"PGHOST|PGPORT|PGDATABASE|PGUSER|PGPASSWORD|"
+    r"MYSQL_HOST|MYSQL_PORT|MYSQL_DATABASE|MYSQL_USER|MYSQL_PASSWORD|"
+    r"MARIADB_HOST|MARIADB_PORT|MARIADB_DATABASE|MARIADB_USER|MARIADB_PASSWORD|"
+    r"ORACLE_HOST|ORACLE_PORT|ORACLE_SERVICE|ORACLE_SID|"
+    r"SQLSERVER_HOST|SQLSERVER_PORT|SQLSERVER_DATABASE|SQLSERVER_USER|SQLSERVER_PASSWORD"
+    r")"
+)
+
+NON_CONFIG_HINT_PATTERN = re.compile(
+    r"(?i)("
+    r"jdbc:[\w:]+|"
+    r"postgres(?:ql)?://|mysql://|mariadb://|"
+    r"Data Source=|Initial Catalog=|"
+    r"PGHOST|PGDATABASE|MYSQL_|MARIADB_|ORACLE_|SQLSERVER_|"
+    r"tnsnames\.ora|sqlplus|sqlcmd|sqlite3|db2 connect"
+    r")"
+)
+
+SECRET_KEY_PATTERN = re.compile(r"(?i)(password|passwd|pwd|secret|token|credential|private[_-]?key|access[_-]?key)")
+USERNAME_KEY_PATTERN = re.compile(r"(?i)(^|[_.-])(user|username|uid)$|(^|[_.-])(user|username|uid)([_.-]|$)")
+ASSIGNMENT_PATTERN = re.compile(r"^\s*([^#;!\s][^:=\s]*?)\s*[:=]\s*(.+?)\s*$")
+MAX_FILE_BYTES = 2 * 1024 * 1024
+
+
+def is_text_candidate(path):
+    return path.name in TEXT_NAMES or path.suffix in TEXT_EXTENSIONS or path.name.startswith(".env")
+
+
+def is_config_file(path):
+    return path.name in CONFIG_NAMES or path.suffix in CONFIG_EXTENSIONS or path.name.startswith(".env")
+
+
+def detect_db_type(text):
+    matches = [name for name, pattern in DB_PATTERNS if pattern.search(text)]
+    return ",".join(matches) if matches else ""
+
+
+def redact_value(key, value):
+    value = value.strip().strip("\"'")
+    if SECRET_KEY_PATTERN.search(key):
+        return "<redacted>"
+    if USERNAME_KEY_PATTERN.search(key):
+        return "<redacted-user>"
+
+    redacted = value
+    redacted = re.sub(r"(?i)(password|passwd|pwd)=([^;&\s]+)", r"\1=<redacted>", redacted)
+    redacted = re.sub(r"(?i)(user(?:name)?\s*=\s*)([^;&\s]+)", r"\1<redacted-user>", redacted)
+    redacted = re.sub(r"(?i)(uid\s*=\s*)([^;&\s]+)", r"\1<redacted-user>", redacted)
+    redacted = re.sub(r"(?i)(User ID\s*=\s*)([^;&]+)", r"\1<redacted-user>", redacted)
+    redacted = re.sub(r"(?i)(Password\s*=\s*)([^;&]+)", r"\1<redacted>", redacted)
+    redacted = re.sub(r"://([^:/@\s]+):([^@\s]+)@", r"://<redacted-user>:<redacted>@", redacted)
+    return redacted
+
+
+def iter_files(root):
+    for current_root, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+        for name in files:
+            path = Path(current_root) / name
+            try:
+                path.resolve().relative_to(SCRIPT_SKILL_DIR)
+                continue
+            except ValueError:
+                pass
+            if is_text_candidate(path):
+                yield path
+
+
+def scan_file(path, root):
+    try:
+        if path.stat().st_size > MAX_FILE_BYTES:
+            return []
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+
+    results = []
+    rel_path = str(path.relative_to(root))
+    config_file = is_config_file(path)
+    for line_no, line in enumerate(content.splitlines(), start=1):
+        db_type = detect_db_type(line)
+        key = ""
+        value = line.strip()
+        match = ASSIGNMENT_PATTERN.match(line)
+
+        if match:
+            key = match.group(1).strip()
+            value = match.group(2).strip()
+            key_match = CONFIG_KEY_PATTERN.search(key)
+            if not db_type and not (config_file and key_match):
+                continue
+        else:
+            hint_match = NON_CONFIG_HINT_PATTERN.search(line)
+            if not db_type and not hint_match:
+                continue
+            if hint_match:
+                key = hint_match.group(1)
+
+        if not db_type:
+            db_type = detect_db_type(value)
+
+        results.append(
+            {
+                "file": rel_path,
+                "line": line_no,
+                "db_type": db_type or "unknown",
+                "key": key,
+                "value": redact_value(key, value),
+            }
+        )
+    return results
+
+
+def print_markdown(results):
+    if not results:
+        print("No DB config candidates found.")
+        return
+
+    print("| file | line | db_type | key | redacted_value |")
+    print("| --- | ---: | --- | --- | --- |")
+    for item in results:
+        value = item["value"].replace("|", "\\|")
+        key = item["key"].replace("|", "\\|")
+        print(f"| {item['file']} | {item['line']} | {item['db_type']} | `{key}` | `{value}` |")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Find DB connection config candidates with redacted output.")
+    parser.add_argument("repo", nargs="?", default=".", help="Repository path to scan.")
+    parser.add_argument("--json", action="store_true", help="Output JSON instead of markdown.")
+    args = parser.parse_args()
+
+    root = Path(args.repo).resolve()
+    if not root.exists():
+        print(f"Path does not exist: {root}", file=sys.stderr)
+        return 2
+
+    results = []
+    for path in iter_files(root):
+        results.extend(scan_file(path, root))
+
+    results.sort(key=lambda item: (item["file"], item["line"]))
+
+    if args.json:
+        print(json.dumps(results, indent=2, ensure_ascii=False))
+    else:
+        print_markdown(results)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,194 @@
+---
+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

@@ -0,0 +1,164 @@
+# 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 目錄不存在，先建立目錄後再寫入。