ops-wiki-agent-kit 0.1.0

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

@@ -0,0 +1,117 @@
+---
+name: source-code-to-spec-tools
+description: 提供 source-code-to-SPEC 工作流程共用的 CLI 工具。當工作流程在手動搜尋原始碼前，需要穩定查找 documentation target queue 資料列、catalog Markdown 表格、相關 targets 或 source evidence handles 時使用。
+---
+
+# Source Code To SPEC Tools
+
+## Purpose
+
+此 skill 是 `Source Code to Spec` toolkit 的共用工具層。它只提供可重跑的 CLI 查詢能力，不負責建立 catalog、產生 queue、撰寫 SPEC、審查文件或執行 DB acquisition。
+
+其他 domain skills 可以明確載入本 skill，使用這裡的 public scripts。不要讓某個 skill 呼叫另一個 skill 私有 `scripts/` 目錄中的檔案。
+
+## Shared Terminology
+
+所有使用本 toolkit 的 agent / prompt / skill 都應遵守 `references/terminology-contract.md`。該 contract 定義 `documentation target`、`target row`、`source_type`、`entrypoint`、`keyword`、`doc_profile`、`authoritative source` 與 `source evidence` 的 canonical meaning。
+
+重點規則：
+
+- `docs/docs-target-queue.md` 是 target row queue，不是 keyword list。
+- `keyword` 只是穩定 lookup handle，不是 queue、behavior evidence 或自由搜尋詞集合。
+- `Function` 只在 `source_type=Function` 或逐字引用 source evidence term 時使用，不泛指 method/helper。
+- `source` 應限定為 `source code`、`source evidence`、`authoritative source`、`source extract` 或 `source_type`。
+
+## Shared Queue Schema
+
+Queue 欄位順序、supporting table 欄位、status enum、`doc_profile` 規則、`source_type` registry、prefix 與 `document_path` 預設樣式由 `scripts/queue_contract.py` 提供，文件說明在 `references/target-queue-schema-contract.md`。修改這些 contract 時，不要在 domain scripts 或 downstream references 複製第二份定義。
+
+## Repository Artifact Contract
+
+所有 repo-level workflow 維護、cleanup 或新增 agent / prompt / skill / script 前，應先遵守 `references/repository-artifact-contract.md`。該 contract 固定 canonical repository layout、final artifact inventory、public script ownership、repository cleanup rules 與 commit readiness gate。
+
+重點規則：
+
+- Repository artifact contract 是 toolkit 維護規則，不是 target SPEC 內容來源；產生 target docs 時不要把 `README.md`、repo map、review ledger 或 cleanup gate 寫入 target behavior。
+- 明確 path 一律使用 `.github/agents/...`、`.github/prompts/...`、`.github/skills/...`。
+- Ops SPEC guideline library 的 canonical source 是 `.github/skills/source-code-to-ops-spec-guidelines/references/**`。
+- Shared lookup CLI 只放在 `source-code-to-spec-tools/scripts/`；domain scripts 不應被其他 skills 私下呼叫。
+- `docs/**` 是 generated / graph docs 與 review ledger，不是 workflow implementation source。
+- 修改 scripts 或 schema contract 後，至少同步更新 CLI help、references 與 downstream contract；若影響 backbone parser 或 queue schema，使用實際 queue / catalog input 執行 bounded smoke command。
+
+## CLI Contract
+
+從 repo root 執行以下 scripts，預設輸出 JSON，方便後續 handoff 或 agent parsing。執行本 skill 的 Python CLI 時使用 `python -B`，避免 smoke / generation run 產生 `__pycache__` 或 `*.pyc` runtime cache。
+
+### target_query.py
+
+用途：查詢 `docs/docs-target-queue.md` 的 target row、related rows、preflight context 與 supporting tables。
+
+```bash
+python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py find --queue docs/docs-target-queue.md --id F10
+python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py related --queue docs/docs-target-queue.md --id F10
+python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py preflight --queue docs/docs-target-queue.md --id F10
+python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py sections --queue docs/docs-target-queue.md
+```
+
+使用時機：
+
+- 需要 selected target row。
+- 需要用 `id`、`source_type`、`entrypoint`、`keyword`、`doc_profile`、status 或任意 query 查 row。
+- 需要 related rows、`Source Acquisition Summary` 或 `Coverage Review`。
+
+### catalog_query.py
+
+用途：解析 `docs/docs-target-catalog.md` 的 Markdown tables，尤其是 `Authoritative Target Source Handoff`、direct rows、hardcoded rows 與 coverage gaps。
+
+```bash
+python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py tables --catalog docs/docs-target-catalog.md
+python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py handoff --catalog docs/docs-target-catalog.md --action direct_rows
+python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py rows --catalog docs/docs-target-catalog.md --section "Direct Target Rows"
+python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py coverage --catalog docs/docs-target-catalog.md
+python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py search --catalog docs/docs-target-catalog.md --query "<handle>"
+```
+
+使用時機：
+
+- 需要判斷 `target_queue_action`。
+- 需要把 catalog table rows 轉給 queue normalization workflow。
+- 需要查 catalog-level coverage gap，不想手動掃 Markdown table。
+
+### source_lookup.py
+
+用途：對 source root 做 bounded handle lookup，回傳 `path`、`line`、`handles`、matched text、可選 context，以及可直接放入 handoff 的 `EvidenceRef`。
+
+```bash
+python -B .github/skills/source-code-to-spec-tools/scripts/source_lookup.py --root <source-root> --handle "<entrypoint>" --ignore-case --output json
+python -B .github/skills/source-code-to-spec-tools/scripts/source_lookup.py --root <source-root> --handle "<handler-or-route>" --include "**/*.java" --include "**/*.xml" --context 2
+python -B .github/skills/source-code-to-spec-tools/scripts/source_lookup.py --root <source-root> --handle "<handle-a>" --handle "<handle-b>" --mode all
+python -B .github/skills/source-code-to-spec-tools/scripts/source_lookup.py --root <source-root> --handle "<method>" --evidence-kind method --output json
+```
+
+使用時機：
+
+- 需要從 `entrypoint`、route、class、method、config key 或 stable handle 找 source evidence。
+- 需要在進入完整檔案閱讀前取得可重讀 evidence refs。
+- 需要限制搜尋範圍，例如 `--include "**/*.xml"` 或 `--include "**/*.java"`。
+
+JSON output 的 `matches[].evidence_ref` 與 top-level `evidence_refs[]` 必須保留 `path`、`line`、`symbol`、`kind`。缺口與限制寫入 `coverage_gaps` / `unresolved_items` 即可，不要新增額外判斷欄位。
+
+## Runtime Validation Contract
+
+`target_query.py`、`catalog_query.py` 與 `queue_contract.py` 是 workflow backbone。修改這些 scripts 或 shared schema 時，不要只跑 `--help`；使用實際 queue / catalog input 執行 bounded smoke command，例如：
+
+```bash
+python -B .github/skills/source-code-to-spec-tools/scripts/target_query.py sections --queue docs/docs-target-queue.md
+python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py tables --catalog docs/docs-target-catalog.md
+```
+
+本 user 版驗證時以 repository 內實際 `docs/**` 或使用者提供的 queue / catalog 檔案為準。
+
+## Boundary Rules
+
+- Scripts 必須保持 source-agnostic；不要加入單一系統名稱、table name、Java class、route 或 business keyword。
+- Scripts 可以解析 Markdown queue/catalog tables 與 source text lookup，但不應替代 structured parser、DB/API acquisition 或 SPEC generation。
+- 其他 skills 若需要這些 CLI，應明確引用 `source-code-to-spec-tools` 的路徑。
+- Repo-level workflow 檔案新增、改名或 cleanup 時，必須同步檢查 `references/repository-artifact-contract.md` 的 artifact owner 與 repository cleanup rules。
+- 若此 skill 不存在或 CLI 無法解析目前格式，workflow 可以 fallback 到手動 `rg`、structured parser 或檔案閱讀，但 handoff 應記錄 fallback reason。

package/.github/skills/source-code-to-spec-tools/references/repository-artifact-contract.md

@@ -0,0 +1,122 @@
+---
+type: contract
+title: Source Code to SPEC Repository Artifact Contract
+aliases:
+  - repository-artifact-contract
+  - source-code-to-spec-repo-contract
+tags:
+  - doc/contract
+  - repo/ownership
+  - source/source-code
+created: 2026-05-20
+language_policy: "zh-TW narrative, English technical identifiers"
+---
+
+# Source Code to SPEC Repository Artifact Contract
+
+本 contract 固定 `Source Code to Spec` repo 的最終檔名、目錄責任與 cleanup gate。它用來避免 agent / prompt / skill / script 重複放置、互相呼叫私有路徑，或把 generated docs 誤當 workflow source。
+
+## Toolkit Docs vs Target Generated Docs
+
+本檔描述的是 toolkit repo 的維護邊界，不是 target SPEC 的內容模板。`README.md`、repository map、review ledger、skill contracts、script inventory 與 cleanup gate 只服務 toolkit 維護與 agent handoff。
+
+當 workflow 產生 target-level SPEC 時，文件主體必須以 target system 的 source evidence、entrypoint、processing flow、data contract、error/security/operation behavior 與 coverage gaps 為中心；不得把 `Source Code to Spec` repo identity、first read order、artifact inventory 或 maintainer cleanup rules 寫成 target behavior。若需要保留來源資訊，只放在 metadata / generation handoff，例如 `generated_by` 或 `toolkit_contract_version`，不得取代 target source evidence。
+
+## Canonical Repository Layout
+
+| Path                                              | Owner                      | Responsibility                                                                                                                             | Not Responsible For                                                                                                                                  |
+| ------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `README.md`                                       | Toolkit entrypoint         | 說明 repo 是 reusable `Source Code to Spec` toolkit、first read order、artifact boundary 與 generated sample boundary。                    | 不放單一 target 的 generated SPEC 內容、不放 project-specific acquisition result、不取代 skill/reference contract；target SPEC 不應複製此 repo map。 |
+| `.github/agents/*.agent.md`                       | Agent layer                | 定義角色、handoff、operating boundary、quality gates 與 final response contract。                                                          | 不複製完整 workflow、template body、private script usage。                                                                                           |
+| `.github/prompts/*.prompt.md`                     | Prompt layer               | 提供 thin orchestration：任務入口、scope、default inputs、handoff priority、final response。                                               | 不承載 durable workflow 細節，不硬編 private `scripts/` path。                                                                                       |
+| `.github/skills/<skill-name>/SKILL.md`            | Skill layer                | 定義 durable workflow、public contract、工具使用順序、fallback rules。                                                                     | 不放單一 target 的 generated SPEC 內容。                                                                                                             |
+| `.github/skills/<skill-name>/references/*.md`     | Reference layer            | 保存 reusable contracts、templates、terminology、source tracing rules、quality gates。                                                     | 不放一次性 terminal output 或不可重讀的 source extract。                                                                                             |
+| `.github/skills/<skill-name>/scripts/*.py`        | Script layer               | 提供 generic、source-agnostic、可重跑 CLI。                                                                                                | 不寫入單一系統名稱、table name、business keyword 或 project-specific converter logic。                                                               |
+| `docs/docs-target-catalog.md`                     | Generated / graph docs     | 保存 source-backed acquisition map、authoritative source handoff、coverage review。                                                        | 不是 final queue、不是 guideline source、不是 prompt contract。                                                                                      |
+| `docs/docs-target-queue.md`                       | Generated / graph docs     | 保存 target row queue 與 generation / review 狀態。                                                                                        | 不是 keyword list、不是 catalog、不是 source evidence 本身。                                                                                         |
+| `docs/source-code-to-spec-repo-review.md`         | Repo review ledger         | 保存 `REV-*` decision log、open gaps、implementation state。                                                                               | 不取代 skill/reference contracts。                                                                                                                   |
+| `target/**`                                       | Runtime output / scratch   | 可保存本機執行產物、partial output、handoff draft 或 temporary extract。                                                                   | 不作為 canonical workflow contract；若需要長期維護，應提升到 `.github/**`、`docs/**` 或 handoff JSON。                                               |
+
+## Final Artifact Inventory
+
+本節只列目前 repo-local tracked artifacts。若 agent / prompt 提到 `$skill-name`，但本 repo 沒有對應 `.github/skills/<skill-name>/` 目錄，該名稱只能視為 optional installed skill 或外部 workflow trigger；不得在 contract 中把它寫成已存在的 local path。
+
+### Agents
+
+| File                                                         | Responsibility                                      |
+| ------------------------------------------------------------ | --------------------------------------------------- |
+| `.github/agents/docs-target-catalog.agent.md`                | 第一階段 catalog builder agent。                    |
+| `.github/agents/docs-target-queue-from-catalog.agent.md`     | catalog-to-queue normalization agent。              |
+| `.github/agents/source-code-to-spec-documenter.agent.md`     | target-level SPEC generation agent。                |
+| `.github/agents/source-code-to-spec-reviewer.agent.md`       | target-level SPEC review agent。                    |
+| `.github/agents/source-code-to-system-ops-overview.agent.md` | system-level operations overview documenter agent。 |
+
+### Prompts
+
+| File                                                      | Responsibility                                   |
+| --------------------------------------------------------- | ------------------------------------------------ |
+| `.github/prompts/00-generate-target-all-spec.prompt.md` | all target SPEC document orchestration。         |
+| `.github/prompts/01-generate-target-foundation-spec.prompt.md` | foundation target SPEC document orchestration。 |
+| `.github/prompts/02-generate-target-architecture-spec.prompt.md` | architecture target SPEC document orchestration。 |
+| `.github/prompts/03-generate-target-ops-spec.prompt.md` | ops target SPEC document orchestration。         |
+| `.github/prompts/04-review-target-spec.prompt.md`       | review generated docs and update queue status。  |
+| `.github/prompts/generate-system-ops-overview.prompt.md`  | system-level operations overview orchestration。 |
+
+Catalog / queue 建立目前由 `.github/agents/docs-target-catalog.agent.md` 與 `.github/agents/docs-target-queue-from-catalog.agent.md` 承接；若未來新增 dedicated `.prompt.md`，必須同步更新本 inventory 與引用該 prompt 的 handoff。
+
+### Skills
+
+| Skill                                                | Responsibility                                                                                                                |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `.github/skills/source-code-to-spec-tools/`          | 提供 shared lookup CLI、terminology contract、repository artifact contract。                                                  |
+| `.github/skills/source-code-to-spec-documenter/`     | 選取 target row、追蹤 source evidence、建立 handoff、更新 generation status。                                                 |
+| `.github/skills/source-code-to-ops-spec-guidelines/` | 維護三份 ops SPEC 的維運導向 guideline contract、chapter rules 與 `doc_file_plan` contract。 |
+| `.github/skills/source-code-to-system-ops-overview/` | 根據 source evidence 產生或更新跨系統型態、跨技術棧的 system-level operations overview。                                      |
+
+Optional installed skills may still be useful during execution, including `docs-target-catalog`, `docs-target-queue-from-catalog`, and `database-query`. They are not repo-local artifacts unless matching directories are tracked under `.github/skills/`.
+
+### Public Scripts
+
+| Script                                                                | Public Caller                              | Responsibility                                                      |
+| --------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------- |
+| `.github/skills/source-code-to-spec-tools/scripts/target_query.py`    | Any workflow needing queue lookup          | 查詢 target row、related rows、queue preflight 與 coverage tables。 |
+| `.github/skills/source-code-to-spec-tools/scripts/catalog_query.py`   | Any workflow needing catalog table lookup  | 解析 catalog tables、handoff rows、direct rows 與 coverage gaps。   |
+| `.github/skills/source-code-to-spec-tools/scripts/source_lookup.py`   | Any workflow needing bounded source lookup | 以 handle / glob 搜尋 source evidence 並輸出 `EvidenceRef`。        |
+| `.github/skills/source-code-to-spec-documenter/scripts/spec_queue.py` | `source-code-to-spec-documenter` workflow  | 依 current queue schema 選取 / 更新 queue row 與 status transition。 |
+
+## Repository Cleanup Rules
+
+1. 不新增 root-level `agents/`、`prompts/`、`skills/` 作為 canonical workflow path；明確引用必須使用 `.github/agents/...`、`.github/prompts/...`、`.github/skills/...`。
+2. Ops SPEC guideline library 的 canonical source 是 `.github/skills/source-code-to-ops-spec-guidelines/references/**`；target generation 預設在 `document_path` 下產生一份 primary readable SPEC，supporting docs 才依 evidence / handoff 需求拆成相對檔名。Generated target docs 不可反向作為 guideline source。
+3. Shared CLI 只放在 `source-code-to-spec-tools/scripts/`；domain workflow scripts 只能服務自己的 skill，不得被其他 skill 私下呼叫。
+4. 若需要新的 converter，先判斷是否能擴充既有 generic script；禁止新增含單一系統名稱或 hardcoded business keyword 的一次性 converter。
+5. `docs/` 可以保存目前 sample / generated graph docs，但 metadata、檔名與 review notes 必須維持 toolkit-neutral，不得把 repo 重新綁回單一專案。
+6. `target/**`、terminal output、manual extract 只可作為 working evidence；若需要 reviewer 或 future agent 重讀，必須整理成 `docs/**`、`.github/skills/**/references/**` 或 handoff JSON。
+7. 新增或移動檔案時，必須同步更新引用該檔案的 agent / prompt / skill / reference；若影響 backbone scripts，使用實際 input 執行 bounded smoke command 或記錄未執行原因。
+8. `__pycache__/`、`*.pyc`、`*.pyo`、`*.pyd` 是 Python runtime cache，不是 workflow evidence 或 handoff artifact。不要在仍有 downstream Python stage 需要執行時反覆清除；應在 Python-based smoke / generation scripts 全部完成後、final workspace / commit readiness check 前清掉。若 automation 希望避免再產生 cache，可使用 `PYTHONDONTWRITEBYTECODE=1` 或 `python -B ...`，但 final cleanup 仍需檢查既有 cache 是否殘留。
+
+## Commit Readiness Gate
+
+在宣告 repo workflow stable、準備 commit 或關閉相關 `REV-*` item 前，至少檢查：
+
+| Check                           | Command / Evidence                                                                               | Pass Criteria                                                                                                                                      |
+| ------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Working tree scope              | `git status --short`                                                                             | 只包含本次 intended changes；沒有殘留過渡期檔案。                                                                                                  |
+| Canonical tracked files         | `git ls-files`                                                                                   | workflow artifacts 只出現在 `.github/agents`、`.github/prompts`、`.github/skills`、`docs`。                                                        |
+| Path drift                      | `rg -n "agents/                                                                                  | prompts/                                                                                                                                           | skills/" .github docs` | 明確 path 使用 `.github/...`；只有 generic skill invocation 可使用 `$skill-name`。 |
+| Script smoke check              | bounded script command / representative query                                                    | Backbone scripts 使用實際 input 通過代表性 bounded command。若未跑，final answer 必須說明原因。                                                   |
+| Ignored runtime cache cleanup   | `git status --short --ignored` or `Get-ChildItem -Force -Recurse -Directory -Filter __pycache__` | Python script 執行完成後沒有殘留 `__pycache__/` 或 `*.py[cod]`；若刻意保留，final answer 必須說明原因。                                            |
+| Whitespace / patch validity     | `git diff --check`                                                                               | 無 trailing whitespace、conflict markers 或 patch whitespace error。                                                                               |
+
+## Review Checklist
+
+| Check ID       | Rule                                                                                                                                                                                                                             |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CHK-REPO-001` | 新 workflow 檔案放在 canonical `.github/**` path，沒有新增 root `agents/`、`prompts/`、`skills/`。                                                                                                                               |
+| `CHK-REPO-002` | Prompt 保持 thin orchestration，沒有複製 skill/reference 的 durable workflow。                                                                                                                                                   |
+| `CHK-REPO-003` | Skill / reference 承載 durable contract；agent 只定 role、boundary、quality gates。                                                                                                                                              |
+| `CHK-REPO-004` | Script 是 source-agnostic reusable CLI，沒有單一 target 或單一系統 hardcoding。                                                                                                                                                  |
+| `CHK-REPO-005` | Generated docs 與 guideline source 邊界清楚，`docs/**` 不被當作 workflow implementation source。                                                                                                                                 |
+| `CHK-REPO-006` | Queue / catalog / terminology / repository artifact contracts 的引用保持一致。                                                                                                                                                   |
+| `CHK-REPO-007` | 修改 `.github/skills/**/scripts/*.py` 時同步更新 CLI help、references 與 downstream contract；backbone scripts 必須使用實際 input 執行 bounded smoke command，其他 scripts 至少執行代表性 command 或記錄未執行原因。 |
+| `CHK-REPO-008` | Python runtime cache 必須在 script run boundary 後清理；`__pycache__/` 與 `*.py[cod]` 不得作為 source-backed evidence 或 commit-ready artifact。                                                                        |

package/.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md

@@ -0,0 +1,116 @@
+# Target Queue Schema Contract
+
+此檔是 documentation target queue 的 shared schema contract。可執行定義以 `.github/skills/source-code-to-spec-tools/scripts/queue_contract.py` 為準；若要新增欄位、`source_type`、status enum 或 `doc_profile` 規則，必須先更新該 module，再同步本文件與測試。
+
+## Main Target Table
+
+主表欄位與順序固定如下：
+
+| column | meaning |
+| --- | --- |
+| `id` | 穩定 target row id，格式為 `<source_type prefix><original_id>`。 |
+| `source_type` | activation surface 類型，不是 implementation language 或 document section。 |
+| `original_id` | 同一個 `source_type` 內的流水號。 |
+| `group` | 業務、模組、導覽、responsibility 或其他 source-backed grouping。 |
+| `name` | 面向使用者、operator 或 downstream consumer 的 target 名稱。 |
+| `entrypoint` | source tracing 起點，例如 route、job class、command、menu target、program id。 |
+| `document_path` | target SPEC output root，使用 repo-relative path。 |
+| `keyword` | stable lookup handle，不可取代 source evidence。 |
+| `doc_profile` | 三份 target SPEC 文件的深度與 completion standard：`lite`、`standard`、`full`。 |
+| `foundation_doc_status` | `01-document-foundation-and-business` 文件 generation status。 |
+| `architecture_doc_status` | `02-core-architecture-flow-data-logic` 文件 generation status。 |
+| `ops_doc_status` | `03-error-ops-scenario-coverage` 文件 generation status。 |
+| `review_status` | Review status。 |
+| `document_completed_flag(Y/N)` | 三份 target SPEC 文件是否已存在的 completion flag。 |
+| `last_handoff` | 最新 generation / review handoff path。 |
+| `notes` | 簡短、可重讀的狀態或 blocker 摘要。 |
+
+## Supporting Tables
+
+`Source Acquisition Summary` 欄位：
+
+| target_scope | source_kind | authoritative_source | acquisition_method | selected_fields | filter_or_scope | raw_count | eligible_count | excluded_count | gap_count | validation_status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+每列必須滿足 `raw_count = eligible_count + excluded_count + gap_count`。`validation_status` 可用值包含 `collected_success`、`parsed_success`、`direct_rows_accepted`、`zero_rows_with_count`、`source_unavailable`、`parse_failed`、`connection_failed`、`missing_tool`、`missing_credentials`、`permission_denied`、`user_input_required`、`user_declined`。
+
+`Coverage Review` 欄位：
+
+| item | reason_not_in_table | evidence | recommended_next_step |
+| --- | --- | --- | --- |
+
+## Status Values
+
+`foundation_doc_status`、`architecture_doc_status` 與 `ops_doc_status` 可用值：
+
+- `pending`
+- `in_progress`
+- `generated`
+- `partial`
+- `blocked`
+- `failed`
+- `n/a`
+
+`review_status` 可用值：
+
+- `not_started`
+- `pending`
+- `passed`
+- `failed`
+- `blocked`
+- `waived`
+
+`document_completed_flag(Y/N)` 不是 review 狀態。當 selected row 的 `document_path` 下三份 target SPEC 文件都存在時，可設為 `Y`；不需要等待 `review_status=passed` 或 `waived`。Review workflow 只更新 `review_status` 與 findings，除非發現文件實際缺漏或路徑錯誤，否則不應只因 review 未通過而把 completion flag 改回 `N`。
+
+## Document Profile Rules
+
+`doc_profile` 表示 target SPEC 文件深度，不是本次處理範圍。`generation_scope` 與三份文件 completion 的 workflow 規則由後段 documenter workflow 擁有；本檔只定義 queue schema 可用值、預設值與 source_type mapping。
+
+| doc_profile | Use when | Completion standard |
+| --- | --- | --- |
+| `lite` | 小型 script、single API、library API、report、單一 SQL/command 或單一 activation surface。 | 單一 activation surface 的 source-backed completion；可省略不適用章節，但不可省略可確認的 trigger、SQL / command、input / output、error 與維運線索。 |
+| `standard` | 一般 enterprise business capability、job、workflow、file process、external integration 或 data pipeline。 | 一般 enterprise source-backed completion，涵蓋入口、流程、資料、狀態、錯誤與維運線索。 |
+| `full` | 使用者明確要求完整文件集、高風險流程、跨多 runtime surfaces 或完整維運交接。 | 完整 source-backed completion，保留跨 runtime、handoff、SQL、mapping、狀態、交易、錯誤與操作線索。 |
+
+預設規則：`API`、`Command`、`LibraryAPI`、`Report` 預設 `lite`；其他 `source_type` 預設 `standard`。`full` 只能由使用者、queue row 或明確 handoff requirement 指定，不可當作無條件預設。
+
+## Source Type Registry
+
+`source_type` 描述 target 如何被使用者、系統或 downstream consumer 直接啟動。它不是 source code language、document section、file extension 或 implementation layer。
+
+此 registry 是預設 registration set，不代表 converter 會 automatic 接受任何未知 `source_type`。目前預設涵蓋 Web/API、job、command、mobile、desktop、library API、data pipeline、database program 等常見 activation surfaces；若出現未列入 registry 的 activation surface，必須透過 registration extension 明確定義 `source_type`、唯一 prefix、default `doc_profile` 與 `document_path` pattern，或在一次性 converter run 使用 `--prefix source_type=PREFIX` 後同步回 shared contract。
+
+| source_type | prefix | default `doc_profile` | document_path pattern | Use for |
+| --- | --- | --- | --- | --- |
+| `Function` | `F` | `standard` | `docs/feature/{group}/{name}` | user-facing menu/navigation/business capabilities that are not better represented by a specific channel |
+| `Job` | `J` | `standard` | `docs/job/{name}` | scheduled jobs, workers, batch jobs, DB jobs, background processors |
+| `API` | `A` | `lite` | `docs/api/{name}` | independently activated REST/SOAP/RPC/service endpoints or service operations |
+| `Report` | `R` | `lite` | `docs/report/{group}/{name}` | independent reports, exports, dashboards, report scheduler identities |
+| `File` | `FI` | `standard` | `docs/file-process/{name}` | file import, export, watcher, transfer, archive processes |
+| `External` | `X` | `standard` | `docs/external/{name}` | external integrations, webhooks, partner/system interfaces, message contracts |
+| `ERP` | `E` | `standard` | `docs/erp/{group}/{name}` | ERP or platform metadata, forms, responsibilities, programs, transactions |
+| `DatabaseProgram` | `DBP` | `standard` | `docs/database-program/{group}/{name}` | database-side packages, stored procedures/functions, triggers, routine tasks, and DB-owned program units |
+| `Command` | `C` | `lite` | `docs/command/{name}` | CLI/operator commands, console tasks, scripted commands, admin commands |
+| `Workflow` | `W` | `standard` | `docs/workflow/{name}` | BPMN/process definitions, approval flows, state-machine workflows, orchestrated business processes |
+| `MobileScreen` | `M` | `standard` | `docs/mobile/{group}/{name}` | mobile screens, tabs, activities/fragments, deep links, mobile navigation destinations |
+| `DesktopAction` | `D` | `standard` | `docs/desktop/{group}/{name}` | desktop menu/toolbar actions, shortcut commands, form/window actions, command bindings |
+| `LibraryAPI` | `L` | `lite` | `docs/library-api/{name}` | public library/package APIs, SDK entrypoints, exported module contracts |
+| `DataPipeline` | `DP` | `standard` | `docs/data-pipeline/{name}` | DAGs, ETL/ELT pipelines, stream processors, data product refreshes |
+
+## Script Usage
+
+Scripts must import `.github/skills/source-code-to-spec-tools/scripts/queue_contract.py` instead of redefining these constants locally:
+
+- `MAIN_COLUMNS`
+- `SUMMARY_COLUMNS`
+- `COVERAGE_COLUMNS`
+- `DOC_STATUSES`
+- `FOUNDATION_DOC_STATUSES`
+- `ARCHITECTURE_DOC_STATUSES`
+- `OPS_DOC_STATUSES`
+- `REVIEW_STATUSES`
+- `DOC_PROFILES`
+- `SOURCE_TYPE_REGISTRY`
+- `DEFAULT_PREFIXES`
+- `DEFAULT_PATH_PATTERNS`
+- `DEFAULT_DOC_PROFILE_BY_SOURCE_TYPE`

package/.github/skills/source-code-to-spec-tools/references/terminology-contract.md

@@ -0,0 +1,121 @@
+# Source Code To SPEC Terminology Contract
+
+此 contract 定義 `Source Code to Spec` toolkit 的共用詞彙。Agent、prompt、skill、queue、handoff 與 review 文件若使用下列詞彙，必須遵守本檔語意；若需要更細的 domain 名稱，請先保留這裡的 canonical term，再在欄位或說明中補充 domain context。
+
+## Purpose
+
+本 toolkit 的核心流程是：
+
+```text
+docs-target-catalog -> docs-target-queue -> target-level SPEC generation -> review
+```
+
+因此 `target`、`queue`、`entrypoint`、`keyword`、`source`、`doc_profile` 等詞不可混用。尤其 `docs/docs-target-queue.md` 是 SPEC generation queue，不是搜尋 keyword list。
+
+## Canonical Terms
+
+| Term                   | Canonical Meaning                                                                                                     | Do Not Use As                                                               | Typical Fields / Files                                                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `documentation target` | 一個需要產出或維護 SPEC 的可啟動業務/系統目標。它必須有獨立 activation evidence 或被使用者明確指定。                  | 任意 source file、class、method、CRUD child screen、helper、搜尋詞。        | `docs/docs-target-queue.md` main table row、`document_path`。                                                                       |
+| `target row`           | `docs/docs-target-queue.md` 主表中的一列，是後段 generation / review 的鎖定單位。                                     | catalog summary row、coverage gap row、source acquisition summary row。     | `id`、`source_type`、`name`、`entrypoint`、`keyword`、`doc_profile`。                                                              |
+| `target id`            | target row 的穩定識別碼，例如 `F10`、`J3`、`A1`、`DP1`、`DBP1`。                                                      | original runtime id、DB primary key、menu id 的同義詞。                     | `id`、handoff `target_id`。                                                                                                         |
+| `source_type`          | target 的 activation surface 類型，描述 user/system/downstream consumer 如何直接啟動它。                              | implementation language、document section、file type。                      | `Function`、`Job`、`API`、`Command`、`Workflow`、`MobileScreen`、`DesktopAction`、`LibraryAPI`、`DataPipeline`、`DatabaseProgram`。 |
+| `function`             | 只有在 `source_type=Function`，或逐字引用 source evidence 中既有名稱時使用。                                          | JavaScript function、Java method、stored function、任意 feature 的泛稱。    | `source_type=Function`、quoted source name such as `FUNCTION` table。                                                               |
+| `job`                  | 可排程、背景執行、worker、batch 或 DB job 類 target。                                                                 | 任意 long-running method、普通 service task。                               | `source_type=Job`、scheduler registry、job class。                                                                                  |
+| `entrypoint`           | 從 target row 開始做 source tracing 的主要 activation handle。                                                        | 完整 call chain、feature summary、document path、keyword list。             | route path、menu target file、job class、command、workflow id、library export。                                                     |
+| `keyword`              | 來自 authoritative source 的穩定搜尋識別或 metadata handle，用來輔助 lookup 與去重。                                  | 自由搜尋詞清單、文件標籤、完整 target queue、業務同義詞集合。               | permission code、route path、scheduler key、program code、source metadata key。                                                     |
+| `source`               | 不應單獨作為精確工作流語意；請改用下列更明確詞彙。                                                                    | 混指 source code、row authority、source_type、evidence、external metadata。 | 使用 `source code`、`source evidence`、`authoritative source`、`source extract`、`source_type`。                                    |
+| `source code`          | repo 中可閱讀的程式碼、config、SQL、template、script 或同等 source artifact。                                         | runtime metadata、production DB rows、外部契約。                            | code verification、source tracing。                                                                                                 |
+| `source evidence`      | 支撐 SPEC 結論的可回查證據，必須能整理為 `EvidenceRef`。                                                              | 未定位的自由文字、terminal scrollback、沒有 path/line/symbol 的摘要。       | handoff `source_evidence: EvidenceRef[]`。                                                                                          |
+| `authoritative source` | 對某個 target scope 具有 final row authority 或 metadata authority 的來源。                                           | supporting evidence、implementation detail。                                | DB table、route registry、scheduler registry、navigation config、ERP metadata、catalog direct rows。                                |
+| `source extract`       | 從 authoritative source 取得且可重讀的 result set、export、file excerpt 或 parsed data。                              | 最終 queue 本身、不可重現的 terminal output。                               | `normalized-targets.csv/jsonl`、query/export result、metadata file。                                                                |
+| `catalog`              | 第一階段 source-backed acquisition map，說明有哪些 authoritative sources、如何取得 rows、哪些 scope 有 coverage gap。 | final target queue、完整 SPEC、keyword list。                               | `docs/docs-target-catalog.md`。                                                                                                     |
+| `queue`                | 後段 generation / review 的 target row set。                                                                          | catalog、search index、coverage review、keyword list。                      | `docs/docs-target-queue.md`。                                                                                                       |
+| `handoff`              | workflow stage 之間的 machine-readable 或 table-based交接契約。                                                       | human-only notes、散落在敘述中的 hints。                                    | `Authoritative Target Source Handoff`、`target/source-code-to-spec/<target_id>/handoff.json`。                                      |
+| `scope`                | 本次執行要處理的文件範圍，例如 `foundation`、`architecture`、`ops` 或 `all`。                                         | 文件深度、target 類型。                                                     | prompt generation scope、review scope。                                                                                              |
+| `doc_profile`          | target 的 SPEC 文件深度與完成標準，例如 `lite`、`standard`、`full`。                                                 | 本次執行 scope、source_type、document section name。                        | queue `doc_profile`、handoff file plan。                                                                                             |
+| `coverage_gap`         | 已知會影響 completeness、source acquisition 或 runtime truth 的缺口。                                                 | 低優先級 TODO、普通 open question。                                         | queue/catalog `Coverage Review`、handoff `coverage_gaps`。                                                                          |
+| `unresolved_item`      | 需要後續確認的具體問題或行動，不一定影響 completion。                                                                 | coverage gap 的替代詞；若影響完成度，仍要列入 `coverage_gaps`。             | generated docs `Unresolved Items`、handoff `unresolved_items`。                                                                     |
+
+## Required Distinctions
+
+### `keyword` Is Not The Queue
+
+`keyword` 只是 target row 的一個 stable handle。它可用於搜尋、去重或 related row lookup，但不可代表整份 queue。
+
+Good:
+
+```text
+Use `docs/docs-target-queue.md` to select the next target row. Use `keyword` only as one lookup handle.
+```
+
+Bad:
+
+```text
+Use system keywords to generate all specs.
+```
+
+### `function` Is Not A Generic Method
+
+`Function` 是 `source_type` 的一個值，通常代表 user-facing menu/navigation/business capability。Java method、JavaScript function 或 helper routine 應使用 `method`、`routine` 等更精確詞，不要寫成 target `Function`。Oracle stored function、stored procedure、package 或 trigger 若本身是文件目標，應優先使用 `source_type=DatabaseProgram`。
+
+### `target` Is Not A File
+
+一個 `.jsp`、`.java`、`.sql`、`.py` 或 `.tsx` file 預設只是 implementation evidence。只有當它被 route、menu、command、scheduler、workflow、library export、navigation config 或使用者明確指定為獨立 activation unit 時，才可成為 `documentation target`。
+
+### `entrypoint` Is Not The Whole Flow
+
+`entrypoint` 是 tracing 起點。完整 call chain、data resource、coverage applicability、error/security/observability 與 operation behavior 必須寫入 SPEC 或 handoff，不應塞進 `entrypoint` 欄位。
+
+### Document Section Is Not `source_type`
+
+`source_type` 描述 target 如何被啟動；`foundation_doc_status`、`architecture_doc_status` 與 `ops_doc_status` 描述三份 target SPEC 文件的生成狀態。coverage view 或文件章節不可因命名相似而變成新的 target row，除非它有獨立 activation evidence。
+
+### `source` Must Be Qualified
+
+新文件避免單獨使用 `source` 作為關鍵欄位或規則名。請依情境選用：
+
+- `source code`: repo 內可讀程式/設定/SQL/template/script。
+- `source evidence`: 支撐結論的 `EvidenceRef`。
+- `authoritative source`: 能決定 row authority 或 metadata truth 的來源。
+- `source extract`: 從 authoritative source 取得的可重讀資料。
+- `source_type`: target row 的 activation surface 類型。
+
+既有 frontmatter 或表格若已有 `source` 欄位可以保留，但新增契約應補描述其實際意義，避免混用。
+
+## Naming Rules
+
+- 使用 `docs-target-catalog` 表示第一階段 acquisition map。
+- 使用 `docs-target-queue` 表示後段 target row queue。
+- 避免新增 `system-keywords`、`function-job-catalog`、`keyword queue` 這類非 canonical 命名。
+- Machine-readable field 應優先使用既有 canonical keys，例如 `target_id`、`source_type`、`entrypoint`、`keyword`、`doc_profile`、`source_evidence`、`coverage_gaps`。
+
+## Workflow Usage
+
+### Catalog Builder
+
+Catalog builder 應輸出 authoritative source map，不輸出 final queue。它可以列出 candidate target rows 或 direct rows，但必須標明 row authority 與 `target_queue_action`。
+
+### Queue Converter
+
+Queue converter 只把已確認 row authority 的資料正規化為 target rows。它不得把 catalog summary、coverage gap、helper file 或自由 keyword 提升為 target row。
+
+### SPEC Documenter
+
+Documenter 從一筆 target row 出發，使用 `entrypoint` 與 `keyword` 做 lookup，但 SPEC 內容必須由 `source_evidence` 支撐。`keyword` 不足以作為 behavior evidence。
+
+### Reviewer
+
+Reviewer 應檢查文件是否混用上述詞彙。若 generation 把 `keyword` 當 queue、把 implementation file 當 target、把 document section 當 `source_type`、或把未限定的 `source` 當 row authority，應列為 review finding。
+
+## Minimum Review Checklist
+
+| Check                | Rule                                                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Queue meaning        | `docs/docs-target-queue.md` 被描述為 target row queue，不是 keyword list。                                                      |
+| Target boundary      | Main table row 只包含有 independent activation evidence 或使用者指定的 documentation target。                                   |
+| Keyword usage        | `keyword` 只作為 stable lookup handle，不作為 behavior evidence 或 queue synonym。                                              |
+| Function usage       | `Function` 只作為 `source_type` 或逐字引用 source evidence term，不泛指 method/helper。                                         |
+| Source qualification | 新增規則使用 `source code`、`source evidence`、`authoritative source`、`source extract` 或 `source_type`，避免未限定 `source`。 |
+| Document boundary    | 三份 target SPEC 文件與 coverage views 不替代 `source_type` 或 target row。                                                     |
+| Scope/profile split  | execution scope 與 `doc_profile` 分開使用，不能互相替代。                                                                       |