ops-wiki-agent-kit 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/agents/docs-target-catalog.agent.md +8 -20
- package/.github/agents/docs-target-queue-from-catalog.agent.md +5 -4
- package/.github/agents/source-code-to-spec-documenter.agent.md +1 -0
- package/.github/agents/source-code-to-spec-reviewer.agent.md +7 -5
- package/.github/agents/source-code-to-system-ops-overview.agent.md +1 -0
- package/.github/prompts/00-discover-target-baseline.prompt.md +37 -0
- package/.github/prompts/00-generate-target-all-spec.prompt.md +10 -10
- package/.github/prompts/01-generate-target-foundation-spec.prompt.md +13 -9
- package/.github/prompts/02-generate-target-architecture-spec.prompt.md +11 -7
- package/.github/prompts/03-generate-target-ops-spec.prompt.md +11 -7
- package/.github/prompts/docs-target-catalog.prompt.md +1 -3
- package/.github/prompts/docs-target-queue-from-catalog.prompt.md +6 -6
- package/.github/prompts/generate-docs-index.prompt.md +77 -0
- package/.github/prompts/generate-system-ops-overview.prompt.md +3 -2
- package/.github/skills/database-query/SKILL.md +8 -6
- package/.github/skills/database-query/references/client-commands.md +9 -1
- package/.github/skills/database-query/scripts/find_db_config.py +1 -1
- package/.github/skills/docs-target-queue-from-catalog/SKILL.md +43 -213
- package/.github/skills/docs-target-queue-from-catalog/references/docs-target-queue-contract.md +60 -13
- package/.github/skills/docs-target-queue-from-catalog/references/metadata-acquisition-patterns.md +104 -9
- package/.github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py +20 -3
- package/.github/skills/source-code-to-ops-spec-guidelines/SKILL.md +3 -25
- package/.github/skills/source-code-to-ops-spec-guidelines/references/01-system-overview-and-business-scenarios-guideline.md +0 -8
- package/.github/skills/source-code-to-ops-spec-guidelines/references/02-core-architecture-flow-data-logic-guideline.md +230 -171
- package/.github/skills/source-code-to-ops-spec-guidelines/references/03-error-ops-scenario-coverage-guideline.md +20 -2
- package/.github/skills/source-code-to-ops-spec-guidelines/references/supporting-output-format-diagram-and-example-reference.md +145 -143
- package/.github/skills/source-code-to-spec-documenter/SKILL.md +35 -6
- package/.github/skills/source-code-to-spec-documenter/references/generation-handoff-contract.md +43 -132
- package/.github/skills/source-code-to-spec-documenter/references/generation-workflow.md +100 -48
- package/.github/skills/source-code-to-spec-documenter/references/handoff-initial-template.json +76 -0
- package/.github/skills/source-code-to-spec-documenter/references/source-tracing-rules.md +61 -15
- package/.github/skills/source-code-to-spec-documenter/references/target-queue-contract.md +24 -7
- package/.github/skills/source-code-to-spec-documenter/scripts/handoff_update.py +310 -0
- package/.github/skills/source-code-to-spec-documenter/scripts/spec_queue.py +31 -2
- package/.github/skills/source-code-to-spec-tools/SKILL.md +11 -0
- package/.github/skills/source-code-to-spec-tools/references/repository-artifact-contract.md +61 -51
- package/.github/skills/source-code-to-spec-tools/references/target-queue-schema-contract.md +13 -1
- package/.github/skills/source-code-to-spec-tools/references/terminology-contract.md +2 -2
- package/.github/skills/source-code-to-spec-tools/scripts/catalog_query.py +43 -2
- package/.github/skills/source-code-to-spec-tools/scripts/queue_contract.py +3 -0
- package/.github/skills/source-code-to-spec-tools/scripts/target_query.py +3 -0
- package/.github/skills/source-code-to-system-ops-overview/SKILL.md +2 -1
- package/.github/skills/source-code-to-system-ops-overview/references/system-operations-overview-guideline.md +36 -5
- package/package.json +1 -1
|
@@ -24,18 +24,19 @@ language_policy: "zh-TW narrative, English technical identifiers"
|
|
|
24
24
|
|
|
25
25
|
## Canonical Repository Layout
|
|
26
26
|
|
|
27
|
-
| Path
|
|
28
|
-
|
|
|
29
|
-
| `README.md`
|
|
30
|
-
| `.github/agents/*.agent.md`
|
|
31
|
-
| `.github/prompts/*.prompt.md`
|
|
32
|
-
| `.github/skills/<skill-name>/SKILL.md`
|
|
33
|
-
| `.github/skills/<skill-name>/references
|
|
34
|
-
| `.github/skills/<skill-name>/scripts/*.py`
|
|
35
|
-
|
|
|
36
|
-
| `docs/docs-target-
|
|
37
|
-
| `docs/
|
|
38
|
-
| `
|
|
27
|
+
| Path | Owner | Responsibility | Not Responsible For |
|
|
28
|
+
| --------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
+
| `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。 |
|
|
30
|
+
| `.github/agents/*.agent.md` | Agent layer | 定義角色、handoff、operating boundary、quality gates 與 final response contract。 | 不複製完整 workflow、template body、private script usage。 |
|
|
31
|
+
| `.github/prompts/*.prompt.md` | Prompt layer | 提供 thin orchestration：任務入口、scope、default inputs、handoff priority、final response。 | 不承載 durable workflow 細節，不硬編 private `scripts/` path。 |
|
|
32
|
+
| `.github/skills/<skill-name>/SKILL.md` | Skill layer | 定義 durable workflow、public contract、工具使用順序、fallback rules。 | 不放單一 target 的 generated SPEC 內容。 |
|
|
33
|
+
| `.github/skills/<skill-name>/references/*` | Reference layer | 保存 reusable contracts、templates、terminology、source tracing rules、quality gates。 | 不放一次性 terminal output 或不可重讀的 source extract。 |
|
|
34
|
+
| `.github/skills/<skill-name>/scripts/*.py` | Script layer | 提供 generic、source-agnostic、可重跑 CLI。 | 不寫入單一系統名稱、table name、business keyword 或 project-specific converter logic。 |
|
|
35
|
+
| `.github/artifacts/source-code-to-spec/**` | Durable workflow artifact | 保存可追蹤、可提交、可跨 agent/session 重讀的 source-code-to-spec handoff JSON。 | 不放 reader-facing SPEC 文件、不取代 `docs/**`、不放 transient terminal output。 |
|
|
36
|
+
| `docs/docs-target-catalog.md` | Generated / graph docs | 保存 source-backed acquisition map、authoritative source handoff、coverage review。 | 不是 final queue、不是 guideline source、不是 prompt contract。 |
|
|
37
|
+
| `docs/docs-target-queue.md` | Generated / graph docs | 保存 target row queue 與 generation / review 狀態。 | 不是 keyword list、不是 catalog、不是 source evidence 本身。 |
|
|
38
|
+
| `docs/source-code-to-spec-repo-review.md` | Repo review ledger | 保存 `REV-*` decision log、open gaps、implementation state。 | 不取代 skill/reference contracts。 |
|
|
39
|
+
| `target/**` | Runtime output / scratch | 可保存本機執行產物、partial output 或 temporary extract。 | 不作為 durable workflow source；不得保存 source-code-to-spec handoff runtime copy。 |
|
|
39
40
|
|
|
40
41
|
## Final Artifact Inventory
|
|
41
42
|
|
|
@@ -53,36 +54,45 @@ language_policy: "zh-TW narrative, English technical identifiers"
|
|
|
53
54
|
|
|
54
55
|
### Prompts
|
|
55
56
|
|
|
56
|
-
| File
|
|
57
|
-
|
|
|
58
|
-
| `.github/prompts/00-
|
|
59
|
-
| `.github/prompts/
|
|
57
|
+
| File | Responsibility |
|
|
58
|
+
| ---------------------------------------------------------------- | ------------------------------------------------- |
|
|
59
|
+
| `.github/prompts/00-discover-target-baseline.prompt.md` | baseline discovery handoff orchestration。 |
|
|
60
|
+
| `.github/prompts/00-generate-target-all-spec.prompt.md` | all target SPEC document orchestration。 |
|
|
61
|
+
| `.github/prompts/01-generate-target-foundation-spec.prompt.md` | foundation target SPEC document orchestration。 |
|
|
60
62
|
| `.github/prompts/02-generate-target-architecture-spec.prompt.md` | architecture target SPEC document orchestration。 |
|
|
61
|
-
| `.github/prompts/03-generate-target-ops-spec.prompt.md`
|
|
62
|
-
| `.github/prompts/04-review-target-spec.prompt.md`
|
|
63
|
-
| `.github/prompts/
|
|
63
|
+
| `.github/prompts/03-generate-target-ops-spec.prompt.md` | ops target SPEC document orchestration。 |
|
|
64
|
+
| `.github/prompts/04-review-target-spec.prompt.md` | review generated docs and update queue status。 |
|
|
65
|
+
| `.github/prompts/docs-target-catalog.prompt.md` | documentation target catalog orchestration。 |
|
|
66
|
+
| `.github/prompts/docs-target-queue-from-catalog.prompt.md` | catalog-to-queue orchestration。 |
|
|
67
|
+
| `.github/prompts/generate-system-ops-overview.prompt.md` | system-level operations overview orchestration。 |
|
|
64
68
|
|
|
65
|
-
Catalog / queue
|
|
69
|
+
Catalog / queue 建立由 dedicated prompts 啟動，並由 `.github/agents/docs-target-catalog.agent.md` 與 `.github/agents/docs-target-queue-from-catalog.agent.md` 承接執行。
|
|
66
70
|
|
|
67
71
|
### Skills
|
|
68
72
|
|
|
69
|
-
| Skill | Responsibility
|
|
70
|
-
| ---------------------------------------------------- |
|
|
71
|
-
| `.github/skills/
|
|
72
|
-
| `.github/skills/
|
|
73
|
-
| `.github/skills/
|
|
74
|
-
| `.github/skills/source-code-to-
|
|
73
|
+
| Skill | Responsibility |
|
|
74
|
+
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
75
|
+
| `.github/skills/database-query/` | 提供 DB config discovery 與 database query safety references，供需要 DB metadata 的 workflow 使用。 |
|
|
76
|
+
| `.github/skills/docs-target-catalog/` | 建立 source-backed documentation target catalog 與 authoritative source handoff。 |
|
|
77
|
+
| `.github/skills/docs-target-queue-from-catalog/` | 將 catalog / source extract 正規化為 `docs/docs-target-queue.md`。 |
|
|
78
|
+
| `.github/skills/source-code-to-spec-tools/` | 提供 shared lookup CLI、terminology contract、repository artifact contract。 |
|
|
79
|
+
| `.github/skills/source-code-to-spec-documenter/` | 選取 target row、追蹤 source evidence、建立 handoff、更新 generation status。 |
|
|
80
|
+
| `.github/skills/source-code-to-ops-spec-guidelines/` | 維護三份 ops SPEC 的維運導向 guideline contract、chapter rules 與 shared format routing。 |
|
|
81
|
+
| `.github/skills/source-code-to-system-ops-overview/` | 根據 source evidence 產生或更新跨系統型態、跨技術棧的 system-level operations overview。 |
|
|
75
82
|
|
|
76
|
-
Optional installed skills may still be useful during execution
|
|
83
|
+
Optional installed skills may still be useful during execution. They are not repo-local artifacts unless matching directories are tracked under `.github/skills/`.
|
|
77
84
|
|
|
78
85
|
### Public Scripts
|
|
79
86
|
|
|
80
|
-
| Script
|
|
81
|
-
|
|
|
82
|
-
| `.github/skills/source-code-to-spec-tools/scripts/target_query.py`
|
|
83
|
-
| `.github/skills/source-code-to-spec-tools/scripts/catalog_query.py`
|
|
84
|
-
| `.github/skills/source-code-to-spec-tools/scripts/source_lookup.py`
|
|
85
|
-
| `.github/skills/
|
|
87
|
+
| Script | Public Caller | Responsibility |
|
|
88
|
+
| ------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
|
|
89
|
+
| `.github/skills/source-code-to-spec-tools/scripts/target_query.py` | Any workflow needing queue lookup | 查詢 target row、related rows、queue preflight 與 coverage tables。 |
|
|
90
|
+
| `.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。 |
|
|
91
|
+
| `.github/skills/source-code-to-spec-tools/scripts/source_lookup.py` | Any workflow needing bounded source lookup | 以 handle / glob 搜尋 source evidence 並輸出 `EvidenceRef`。 |
|
|
92
|
+
| `.github/skills/database-query/scripts/find_db_config.py` | Workflows needing DB config discovery | 掃描 repo-local config，協助定位可用 database connection settings。 |
|
|
93
|
+
| `.github/skills/docs-target-queue-from-catalog/scripts/write_documentation_target_queue.py` | `docs-target-queue-from-catalog` workflow | 將 normalized target rows 寫入 `docs/docs-target-queue.md`。 |
|
|
94
|
+
| `.github/skills/source-code-to-spec-documenter/scripts/spec_queue.py` | `source-code-to-spec-documenter` workflow | 依 current queue schema 選取 / 更新 queue row 與 status transition。 |
|
|
95
|
+
| `.github/skills/source-code-to-spec-documenter/scripts/handoff_update.py` | `source-code-to-spec-documenter` workflow | 以 patch JSON compact-update durable `handoff.json`，避免手動重寫整份 history。 |
|
|
86
96
|
|
|
87
97
|
## Repository Cleanup Rules
|
|
88
98
|
|
|
@@ -91,7 +101,7 @@ Optional installed skills may still be useful during execution, including `docs-
|
|
|
91
101
|
3. Shared CLI 只放在 `source-code-to-spec-tools/scripts/`；domain workflow scripts 只能服務自己的 skill，不得被其他 skill 私下呼叫。
|
|
92
102
|
4. 若需要新的 converter，先判斷是否能擴充既有 generic script；禁止新增含單一系統名稱或 hardcoded business keyword 的一次性 converter。
|
|
93
103
|
5. `docs/` 可以保存目前 sample / generated graph docs，但 metadata、檔名與 review notes 必須維持 toolkit-neutral，不得把 repo 重新綁回單一專案。
|
|
94
|
-
6. `target/**`、terminal output、manual extract 只可作為 working evidence；若需要 reviewer 或 future agent 重讀，必須整理成 `docs/**`、`.github/skills/**/references/**` 或 handoff JSON。
|
|
104
|
+
6. `target/**`、terminal output、manual extract 只可作為 working evidence；若需要 reviewer 或 future agent 重讀，必須整理成 `docs/**`、`.github/skills/**/references/**` 或 `.github/artifacts/source-code-to-spec/**` handoff JSON。Source-code-to-spec handoff 只寫入 `.github/artifacts/source-code-to-spec/**/handoff.json`。
|
|
95
105
|
7. 新增或移動檔案時，必須同步更新引用該檔案的 agent / prompt / skill / reference；若影響 backbone scripts，使用實際 input 執行 bounded smoke command 或記錄未執行原因。
|
|
96
106
|
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 是否殘留。
|
|
97
107
|
|
|
@@ -99,24 +109,24 @@ Optional installed skills may still be useful during execution, including `docs-
|
|
|
99
109
|
|
|
100
110
|
在宣告 repo workflow stable、準備 commit 或關閉相關 `REV-*` item 前，至少檢查：
|
|
101
111
|
|
|
102
|
-
| Check
|
|
103
|
-
|
|
|
104
|
-
| Working tree scope
|
|
105
|
-
| Canonical tracked files
|
|
106
|
-
| Path drift
|
|
107
|
-
| Script smoke check
|
|
108
|
-
| Ignored runtime cache cleanup
|
|
109
|
-
| Whitespace / patch validity
|
|
112
|
+
| Check | Command / Evidence | Pass Criteria |
|
|
113
|
+
| ----------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
|
|
114
|
+
| Working tree scope | `git status --short` | 只包含本次 intended changes；沒有殘留過渡期檔案。 |
|
|
115
|
+
| Canonical tracked files | `git ls-files` | workflow artifacts 只出現在 `.github/agents`、`.github/prompts`、`.github/skills`、`docs`。 |
|
|
116
|
+
| Path drift | `rg -n "agents/ | prompts/ | skills/" .github docs` | 明確 path 使用 `.github/...`；只有 generic skill invocation 可使用 `$skill-name`。 |
|
|
117
|
+
| Script smoke check | bounded script command / representative query | Backbone scripts 使用實際 input 通過代表性 bounded command。若未跑，final answer 必須說明原因。 |
|
|
118
|
+
| Ignored runtime cache cleanup | `git status --short --ignored` or `Get-ChildItem -Force -Recurse -Directory -Filter __pycache__` | Python script 執行完成後沒有殘留 `__pycache__/` 或 `*.py[cod]`；若刻意保留，final answer 必須說明原因。 |
|
|
119
|
+
| Whitespace / patch validity | `git diff --check` | 無 trailing whitespace、conflict markers 或 patch whitespace error。 |
|
|
110
120
|
|
|
111
121
|
## Review Checklist
|
|
112
122
|
|
|
113
|
-
| Check ID | Rule
|
|
114
|
-
| -------------- |
|
|
115
|
-
| `CHK-REPO-001` | 新 workflow 檔案放在 canonical `.github/**` path，沒有新增 root `agents/`、`prompts/`、`skills/`。
|
|
116
|
-
| `CHK-REPO-002` | Prompt 保持 thin orchestration，沒有複製 skill/reference 的 durable workflow。
|
|
117
|
-
| `CHK-REPO-003` | Skill / reference 承載 durable contract；agent 只定 role、boundary、quality gates。
|
|
118
|
-
| `CHK-REPO-004` | Script 是 source-agnostic reusable CLI，沒有單一 target 或單一系統 hardcoding。
|
|
119
|
-
| `CHK-REPO-005` | Generated docs 與 guideline source 邊界清楚，`docs/**` 不被當作 workflow implementation source。
|
|
120
|
-
| `CHK-REPO-006` | Queue / catalog / terminology / repository artifact contracts 的引用保持一致。
|
|
123
|
+
| Check ID | Rule |
|
|
124
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
125
|
+
| `CHK-REPO-001` | 新 workflow 檔案放在 canonical `.github/**` path，沒有新增 root `agents/`、`prompts/`、`skills/`。 |
|
|
126
|
+
| `CHK-REPO-002` | Prompt 保持 thin orchestration，沒有複製 skill/reference 的 durable workflow。 |
|
|
127
|
+
| `CHK-REPO-003` | Skill / reference 承載 durable contract；agent 只定 role、boundary、quality gates。 |
|
|
128
|
+
| `CHK-REPO-004` | Script 是 source-agnostic reusable CLI，沒有單一 target 或單一系統 hardcoding。 |
|
|
129
|
+
| `CHK-REPO-005` | Generated docs 與 guideline source 邊界清楚，`docs/**` 不被當作 workflow implementation source。 |
|
|
130
|
+
| `CHK-REPO-006` | Queue / catalog / terminology / repository artifact contracts 的引用保持一致。 |
|
|
121
131
|
| `CHK-REPO-007` | 修改 `.github/skills/**/scripts/*.py` 時同步更新 CLI help、references 與 downstream contract；backbone scripts 必須使用實際 input 執行 bounded smoke command，其他 scripts 至少執行代表性 command 或記錄未執行原因。 |
|
|
122
|
-
| `CHK-REPO-008` | Python runtime cache 必須在 script run boundary 後清理；`__pycache__/` 與 `*.py[cod]` 不得作為 source-backed evidence 或 commit-ready artifact。
|
|
132
|
+
| `CHK-REPO-008` | Python runtime cache 必須在 script run boundary 後清理；`__pycache__/` 與 `*.py[cod]` 不得作為 source-backed evidence 或 commit-ready artifact。 |
|
|
@@ -17,12 +17,13 @@
|
|
|
17
17
|
| `document_path` | target SPEC output root，使用 repo-relative path。 |
|
|
18
18
|
| `keyword` | stable lookup handle，不可取代 source evidence。 |
|
|
19
19
|
| `doc_profile` | 三份 target SPEC 文件的深度與 completion standard：`lite`、`standard`、`full`。 |
|
|
20
|
+
| `baseline_status` | `00-discover-target-baseline.prompt.md` 的 shared handoff baseline status；不是 target-facing SPEC 文件狀態。 |
|
|
20
21
|
| `foundation_doc_status` | `01-document-foundation-and-business` 文件 generation status。 |
|
|
21
22
|
| `architecture_doc_status` | `02-core-architecture-flow-data-logic` 文件 generation status。 |
|
|
22
23
|
| `ops_doc_status` | `03-error-ops-scenario-coverage` 文件 generation status。 |
|
|
23
24
|
| `review_status` | Review status。 |
|
|
24
25
|
| `document_completed_flag(Y/N)` | 三份 target SPEC 文件是否已存在的 completion flag。 |
|
|
25
|
-
| `last_handoff` | 最新 generation / review handoff path
|
|
26
|
+
| `last_handoff` | 最新 generation / review handoff durable path，格式為 `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`。 |
|
|
26
27
|
| `notes` | 簡短、可重讀的狀態或 blocker 摘要。 |
|
|
27
28
|
|
|
28
29
|
## Supporting Tables
|
|
@@ -41,6 +42,15 @@
|
|
|
41
42
|
|
|
42
43
|
## Status Values
|
|
43
44
|
|
|
45
|
+
`baseline_status` 可用值：
|
|
46
|
+
|
|
47
|
+
- `pending`
|
|
48
|
+
- `in_progress`
|
|
49
|
+
- `baseline_ready`
|
|
50
|
+
- `partial`
|
|
51
|
+
- `blocked`
|
|
52
|
+
- `failed`
|
|
53
|
+
|
|
44
54
|
`foundation_doc_status`、`architecture_doc_status` 與 `ops_doc_status` 可用值：
|
|
45
55
|
|
|
46
56
|
- `pending`
|
|
@@ -104,6 +114,8 @@ Scripts must import `.github/skills/source-code-to-spec-tools/scripts/queue_cont
|
|
|
104
114
|
- `MAIN_COLUMNS`
|
|
105
115
|
- `SUMMARY_COLUMNS`
|
|
106
116
|
- `COVERAGE_COLUMNS`
|
|
117
|
+
- `BASELINE_STATUSES`
|
|
118
|
+
- `BASELINE_HANDOFF_STATUSES`
|
|
107
119
|
- `DOC_STATUSES`
|
|
108
120
|
- `FOUNDATION_DOC_STATUSES`
|
|
109
121
|
- `ARCHITECTURE_DOC_STATUSES`
|
|
@@ -31,7 +31,7 @@ docs-target-catalog -> docs-target-queue -> target-level SPEC generation -> revi
|
|
|
31
31
|
| `source extract` | 從 authoritative source 取得且可重讀的 result set、export、file excerpt 或 parsed data。 | 最終 queue 本身、不可重現的 terminal output。 | `normalized-targets.csv/jsonl`、query/export result、metadata file。 |
|
|
32
32
|
| `catalog` | 第一階段 source-backed acquisition map，說明有哪些 authoritative sources、如何取得 rows、哪些 scope 有 coverage gap。 | final target queue、完整 SPEC、keyword list。 | `docs/docs-target-catalog.md`。 |
|
|
33
33
|
| `queue` | 後段 generation / review 的 target row set。 | catalog、search index、coverage review、keyword list。 | `docs/docs-target-queue.md`。 |
|
|
34
|
-
| `handoff` | workflow stage 之間的 machine-readable 或 table-based交接契約。 | human-only notes、散落在敘述中的 hints。 | `Authoritative Target Source Handoff
|
|
34
|
+
| `handoff` | workflow stage 之間的 machine-readable 或 table-based交接契約。 | human-only notes、散落在敘述中的 hints。 | `Authoritative Target Source Handoff`、`.github/artifacts/source-code-to-spec/<target_id>/handoff.json` durable workflow artifact。 |
|
|
35
35
|
| `scope` | 本次執行要處理的文件範圍，例如 `foundation`、`architecture`、`ops` 或 `all`。 | 文件深度、target 類型。 | prompt generation scope、review scope。 |
|
|
36
36
|
| `doc_profile` | target 的 SPEC 文件深度與完成標準，例如 `lite`、`standard`、`full`。 | 本次執行 scope、source_type、document section name。 | queue `doc_profile`、handoff file plan。 |
|
|
37
37
|
| `coverage_gap` | 已知會影響 completeness、source acquisition 或 runtime truth 的缺口。 | 低優先級 TODO、普通 open question。 | queue/catalog `Coverage Review`、handoff `coverage_gaps`。 |
|
|
@@ -69,7 +69,7 @@ Use system keywords to generate all specs.
|
|
|
69
69
|
|
|
70
70
|
### Document Section Is Not `source_type`
|
|
71
71
|
|
|
72
|
-
`source_type` 描述 target 如何被啟動；`foundation_doc_status`、`architecture_doc_status` 與 `ops_doc_status` 描述三份 target SPEC 文件的生成狀態。coverage view 或文件章節不可因命名相似而變成新的 target row，除非它有獨立 activation evidence。
|
|
72
|
+
`source_type` 描述 target 如何被啟動；`baseline_status` 描述 shared handoff baseline 狀態；`foundation_doc_status`、`architecture_doc_status` 與 `ops_doc_status` 描述三份 target SPEC 文件的生成狀態。coverage view 或文件章節不可因命名相似而變成新的 target row，除非它有獨立 activation evidence。
|
|
73
73
|
|
|
74
74
|
### `source` Must Be Qualified
|
|
75
75
|
|
|
@@ -156,6 +156,28 @@ def parse_column_filters(values):
|
|
|
156
156
|
return filters
|
|
157
157
|
|
|
158
158
|
|
|
159
|
+
def tables_for_section(catalog, section):
|
|
160
|
+
return [table for table in catalog["tables"] if section_matches(table["section"], section)]
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def validate_column_filters(catalog, section, column_filters, command_name):
|
|
164
|
+
if not column_filters:
|
|
165
|
+
return
|
|
166
|
+
tables = tables_for_section(catalog, section)
|
|
167
|
+
columns = []
|
|
168
|
+
for table in tables:
|
|
169
|
+
for column in table["columns"]:
|
|
170
|
+
if column not in columns:
|
|
171
|
+
columns.append(column)
|
|
172
|
+
for column_name, _ in column_filters:
|
|
173
|
+
if not any(normalize_key(column) == normalize_key(column_name) for column in columns):
|
|
174
|
+
available = ", ".join(columns) if columns else "(none)"
|
|
175
|
+
raise SystemExit(
|
|
176
|
+
f"{command_name} has no column '{column_name}' in section '{section}'. "
|
|
177
|
+
f"Available columns: {available}."
|
|
178
|
+
)
|
|
179
|
+
|
|
180
|
+
|
|
159
181
|
def collect_rows(catalog, section=None, query=None, column_filters=None, limit=None):
|
|
160
182
|
results = []
|
|
161
183
|
for table in catalog["tables"]:
|
|
@@ -215,17 +237,31 @@ def command_tables(args):
|
|
|
215
237
|
|
|
216
238
|
def command_rows(args):
|
|
217
239
|
catalog = read_catalog(args.catalog)
|
|
240
|
+
filters = parse_column_filters(args.where)
|
|
241
|
+
validate_column_filters(catalog, args.section, filters, "catalog_query.py rows")
|
|
218
242
|
rows = collect_rows(
|
|
219
243
|
catalog,
|
|
220
244
|
section=args.section,
|
|
221
245
|
query=args.query,
|
|
222
|
-
column_filters=
|
|
246
|
+
column_filters=filters,
|
|
223
247
|
limit=args.limit,
|
|
224
248
|
)
|
|
225
249
|
print_output({"catalog": catalog["path"], "count": len(rows), "rows": rows}, args.output)
|
|
226
250
|
|
|
227
251
|
|
|
228
252
|
def command_handoff(args):
|
|
253
|
+
if args.queue_id:
|
|
254
|
+
raise SystemExit(
|
|
255
|
+
"catalog_query.py handoff queries docs-target-catalog rows, not docs-target-queue ids. "
|
|
256
|
+
"Use target_query.py preflight --id for queue rows, or catalog_query.py handoff "
|
|
257
|
+
"--query/--where for catalog columns."
|
|
258
|
+
)
|
|
259
|
+
if args.entrypoint:
|
|
260
|
+
raise SystemExit(
|
|
261
|
+
"catalog_query.py handoff has no entrypoint filter because Authoritative Target Source Handoff "
|
|
262
|
+
"does not contain entrypoint rows. Use target_query.py preflight --id for queue targets, or "
|
|
263
|
+
"catalog_query.py rows --section \"Direct Target Rows\" --where entrypoint=<value> for direct catalog rows."
|
|
264
|
+
)
|
|
229
265
|
catalog = read_catalog(args.catalog)
|
|
230
266
|
filters = parse_column_filters(args.where)
|
|
231
267
|
if args.action:
|
|
@@ -234,6 +270,7 @@ def command_handoff(args):
|
|
|
234
270
|
filters.append(("target_scope", args.target_scope))
|
|
235
271
|
if args.authority:
|
|
236
272
|
filters.append(("final_row_authority", args.authority))
|
|
273
|
+
validate_column_filters(catalog, PREFERRED_SECTIONS["handoff"], filters, "catalog_query.py handoff")
|
|
237
274
|
rows = collect_rows(
|
|
238
275
|
catalog,
|
|
239
276
|
section=PREFERRED_SECTIONS["handoff"],
|
|
@@ -246,11 +283,13 @@ def command_handoff(args):
|
|
|
246
283
|
|
|
247
284
|
def command_coverage(args):
|
|
248
285
|
catalog = read_catalog(args.catalog)
|
|
286
|
+
filters = parse_column_filters(args.where)
|
|
287
|
+
validate_column_filters(catalog, PREFERRED_SECTIONS["coverage"], filters, "catalog_query.py coverage")
|
|
249
288
|
rows = collect_rows(
|
|
250
289
|
catalog,
|
|
251
290
|
section=PREFERRED_SECTIONS["coverage"],
|
|
252
291
|
query=args.query,
|
|
253
|
-
column_filters=
|
|
292
|
+
column_filters=filters,
|
|
254
293
|
limit=args.limit,
|
|
255
294
|
)
|
|
256
295
|
print_output({"catalog": catalog["path"], "count": len(rows), "rows": rows}, args.output)
|
|
@@ -290,6 +329,8 @@ def build_parser():
|
|
|
290
329
|
handoff.add_argument("--target-scope")
|
|
291
330
|
handoff.add_argument("--authority", help="Filter final_row_authority.")
|
|
292
331
|
handoff.add_argument("--where", action="append", default=[], help="Column contains filter in column=value form.")
|
|
332
|
+
handoff.add_argument("--id", dest="queue_id", help=argparse.SUPPRESS)
|
|
333
|
+
handoff.add_argument("--entrypoint", help=argparse.SUPPRESS)
|
|
293
334
|
handoff.add_argument("--limit", type=int)
|
|
294
335
|
handoff.add_argument("--output", choices=("json", "markdown"), default="json")
|
|
295
336
|
handoff.set_defaults(func=command_handoff)
|
|
@@ -18,6 +18,7 @@ MAIN_COLUMNS = [
|
|
|
18
18
|
"document_path",
|
|
19
19
|
"keyword",
|
|
20
20
|
"doc_profile",
|
|
21
|
+
"baseline_status",
|
|
21
22
|
"foundation_doc_status",
|
|
22
23
|
"architecture_doc_status",
|
|
23
24
|
"ops_doc_status",
|
|
@@ -53,7 +54,9 @@ COVERAGE_COLUMNS = [
|
|
|
53
54
|
"recommended_next_step",
|
|
54
55
|
]
|
|
55
56
|
|
|
57
|
+
BASELINE_STATUSES = {"pending", "in_progress", "baseline_ready", "partial", "blocked", "failed"}
|
|
56
58
|
DOC_STATUSES = {"pending", "in_progress", "generated", "partial", "blocked", "failed", "n/a"}
|
|
59
|
+
BASELINE_HANDOFF_STATUSES = BASELINE_STATUSES
|
|
57
60
|
FOUNDATION_DOC_STATUSES = DOC_STATUSES
|
|
58
61
|
ARCHITECTURE_DOC_STATUSES = DOC_STATUSES
|
|
59
62
|
OPS_DOC_STATUSES = DOC_STATUSES
|
|
@@ -177,6 +177,8 @@ def matches_filters(row, args):
|
|
|
177
177
|
return False
|
|
178
178
|
if args.query and normalize_key(args.query) not in normalize_key(row_text(row)):
|
|
179
179
|
return False
|
|
180
|
+
if args.baseline and normalize_key(row.get("baseline_status")) != normalize_key(args.baseline):
|
|
181
|
+
return False
|
|
180
182
|
if args.foundation and normalize_key(row.get("foundation_doc_status")) != normalize_key(args.foundation):
|
|
181
183
|
return False
|
|
182
184
|
if args.architecture and normalize_key(row.get("architecture_doc_status")) != normalize_key(args.architecture):
|
|
@@ -362,6 +364,7 @@ def build_parser():
|
|
|
362
364
|
find.add_argument("--name")
|
|
363
365
|
find.add_argument("--entrypoint")
|
|
364
366
|
find.add_argument("--keyword")
|
|
367
|
+
find.add_argument("--baseline")
|
|
365
368
|
find.add_argument("--foundation")
|
|
366
369
|
find.add_argument("--architecture")
|
|
367
370
|
find.add_argument("--ops")
|
|
@@ -64,7 +64,7 @@ description: 當需要根據 source code、SQL、設定檔、部署線索、依
|
|
|
64
64
|
7. `維運初步分流判斷`
|
|
65
65
|
8. `Source Code 證據範圍與人工補充項目`
|
|
66
66
|
|
|
67
|
-
文件應是 narrative-first
|
|
67
|
+
文件應是 narrative-first 加上 guideline 指定的必要 inventory tables。表格用來支援查找與交接，不應變成無來源的大量猜測清單；不得將 reference guideline 明定需要 Markdown Table 的章節改成純敘述。
|
|
68
68
|
|
|
69
69
|
## Quality Gate
|
|
70
70
|
|
|
@@ -77,6 +77,7 @@ description: 當需要根據 source code、SQL、設定檔、部署線索、依
|
|
|
77
77
|
- Java、C#、JavaScript/TypeScript、SQL、PL/SQL、Python、ERP metadata 或其他 technical identifiers 保留原文。
|
|
78
78
|
- Secret value、password、token、private key、certificate content 沒有被輸出。
|
|
79
79
|
- 每個重要 module、config、integration、error/log、triage 結論都有來源位置；無法確認的項目列入 coverage gaps 或人工補充項目。
|
|
80
|
+
- 最終文件符合 reference guideline 的必填章節與表格欄位 contract；不適用欄位以 `N/A`、`Unknown` 或「無法由目前來源確認」標示。
|
|
80
81
|
- 沒有把猜測寫成已確認事實。
|
|
81
82
|
|
|
82
83
|
若 validator 可用，針對 skill 目錄執行 skill validation；若沒有 validator，至少用 `git diff --check` 檢查 Markdown 空白與格式問題。
|
|
@@ -110,6 +110,28 @@ Source evidence 的判讀必須保留原始技術語意。Java、C#、JavaScript
|
|
|
110
110
|
|
|
111
111
|
以下正式編號章節代表 `S01 系統維運總覽文件` 可採用的章節架構。章節下方的撰寫要求、欄位契約與限制規則只供 AI 參考，不應逐字輸出到最終文件。
|
|
112
112
|
|
|
113
|
+
## 章節與表格 Contract 規則
|
|
114
|
+
|
|
115
|
+
最終文件必須保留 8 個正式章節。除非該章確實不適用目前系統，否則不得省略章節或將要求使用 Markdown Table 的章節改成純敘述；不適用或無法確認時，應在表格欄位中填 `N/A`、`Unknown` 或「無法由目前來源確認」。
|
|
116
|
+
|
|
117
|
+
以下章節必須使用本 guideline 指定的 Markdown Table 欄位 contract：
|
|
118
|
+
|
|
119
|
+
| 章節 | 必須使用 Table | 備註 |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| `2.1 系統主要模組` | Yes | 建立 module / component navigation inventory。 |
|
|
122
|
+
| `2.2 系統功能清單摘要` | Yes | 作為 coverage map；若無法完整盤點，表內保留代表性項目並在 coverage gap 說明。 |
|
|
123
|
+
| `3. 技術與執行環境線索` | Yes | 列出可確認 runtime、framework、entrypoint、dependency 與 config 線索。 |
|
|
124
|
+
| `4. 系統設定與環境參數` | Yes | 只列 key / pattern 與用途，不列 secret value。 |
|
|
125
|
+
| `5. 外部介面與整合點摘要` | Yes | 保留 direction、trigger、destination key 與可觀測線索。 |
|
|
126
|
+
| `6.1 重要錯誤與 Exception 摘要` | Yes | 保留系統層分流線索，不補完整處理流程。 |
|
|
127
|
+
| `6.2 Log Keyword 摘要` | Yes | 不得創造無來源 log pattern。 |
|
|
128
|
+
| `6.3 SOP 人工補充提醒` | Yes | 只列已可確認與不可確認項目，不產出正式 SOP。 |
|
|
129
|
+
| `7. 維運初步分流判斷` | Yes | 只提供初步查找方向，不提供 production 操作指令。 |
|
|
130
|
+
| `8.2 Coverage Gaps` | Yes | 集中列出 source evidence 無法支撐的範圍。 |
|
|
131
|
+
| `8.3 Manual Required` | Yes | 集中列出需要人工補充或正式文件確認的項目。 |
|
|
132
|
+
|
|
133
|
+
若既有文件採用敘述型格式，更新時仍應保留正確內容，但需補齊上述 table contract，避免同一 prompt 在不同 repo 產生結構差異過大的文件。
|
|
134
|
+
|
|
113
135
|
## 1. 系統用途與邊界
|
|
114
136
|
|
|
115
137
|
**撰寫目標**:
|
|
@@ -154,7 +176,7 @@ Source evidence 的判讀必須保留原始技術語意。Java、C#、JavaScript
|
|
|
154
176
|
|
|
155
177
|
功能清單作為系統層索引與 coverage map，不取代功能層文件。若來源無法完整列出所有功能，應標示 coverage gap。
|
|
156
178
|
|
|
157
|
-
|
|
179
|
+
必須使用以下欄位：
|
|
158
180
|
|
|
159
181
|
| 功能名稱 | 功能用途摘要 | 所屬模組 | 主要入口線索 | 主要程式位置 | 是否需要功能層文件 |
|
|
160
182
|
|---|---|---|---|---|---|
|
|
@@ -167,7 +189,7 @@ Source evidence 的判讀必須保留原始技術語意。Java、C#、JavaScript
|
|
|
167
189
|
**撰寫目標**:
|
|
168
190
|
整理系統可由來源確認的技術組成與執行線索，協助維運或交接人員快速辨識 runtime、framework、啟動入口與設定來源。
|
|
169
191
|
|
|
170
|
-
使用 Markdown Table
|
|
192
|
+
使用 Markdown Table 呈現。最終文件表格必須至少包含 `類型`、`已確認內容`、`來源`、`備註` 欄位，並優先涵蓋以下類型：
|
|
171
193
|
|
|
172
194
|
| 類型 | 應列內容 | 可接受來源 | 不應加入 |
|
|
173
195
|
|---|---|---|---|
|
|
@@ -288,11 +310,20 @@ Source evidence 的判讀必須保留原始技術語意。Java、C#、JavaScript
|
|
|
288
310
|
**撰寫目標**:
|
|
289
311
|
明確分離可確認項目與需人工補充項目，避免系統層文件混入無來源的業務背景或正式維運規則。
|
|
290
312
|
|
|
291
|
-
### 8.1
|
|
313
|
+
### 8.1 主要 evidence sources
|
|
314
|
+
|
|
315
|
+
使用條列式或表格列出主要來源檔案與可直接確認的項目，例如 module inventory、entrypoint、config key、dependency、external endpoint key、Log keyword、error message、DB object。
|
|
316
|
+
|
|
317
|
+
### 8.2 Coverage Gaps
|
|
318
|
+
|
|
319
|
+
使用 Markdown Table 呈現 source evidence 無法完整支撐的範圍：
|
|
320
|
+
|
|
321
|
+
| 類型 | 缺口說明 | 影響 |
|
|
322
|
+
|---|---|---|
|
|
292
323
|
|
|
293
|
-
|
|
324
|
+
Coverage gap 應聚焦在維運查找、交接或後續文件產製會受影響的缺口；不得把所有尚未展開的功能細節都列成缺口。
|
|
294
325
|
|
|
295
|
-
### 8.
|
|
326
|
+
### 8.3 Manual Required
|
|
296
327
|
|
|
297
328
|
只列會影響維運交接、支援分流、正式處理、安全操作或 escalation 的缺口：
|
|
298
329
|
|