ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-spec-documenter/references/generation-handoff-contract.md

@@ -0,0 +1,155 @@
+# Generation Handoff Contract
+
+每一次文件 generation run 在進入 review 前，都必須先寫出一份 handoff。預設路徑如下：
+
+```text
+target/source-code-to-spec/<target_id>/handoff.json
+```
+
+## JSON Shape
+
+```json
+{
+  "handoff_type": "source-code-to-spec-document-generation",
+  "target_id": "F10",
+  "source_type": "Function",
+  "group": "{business_group}",
+  "name": "{target_name}",
+  "entrypoint": "{entrypoint}",
+  "document_root": "docs/feature/{business_group}/{target_name}",
+  "generation_scope": "all",
+  "doc_profile": "standard",
+  "selected_coverage_views": [],
+  "generation_entrypoint": "all-generation",
+  "review_entrypoint": "review-workflow",
+  "queue_path": "docs/docs-target-queue.md",
+  "doc_file_plan": {
+    "selected_output_files": [
+      "docs/feature/{business_group}/{target_name}/{target_name}-01-document-foundation-and-business.md",
+      "docs/feature/{business_group}/{target_name}/{target_name}-02-core-architecture-flow-data-logic.md",
+      "docs/feature/{business_group}/{target_name}/{target_name}-03-error-ops-scenario-coverage.md"
+    ],
+    "guideline_reference_set": [
+      ".github/skills/source-code-to-ops-spec-guidelines/references/supporting-output-format-diagram-and-example-reference.md",
+      ".github/skills/source-code-to-ops-spec-guidelines/references/01-system-overview-and-business-scenarios-guideline.md",
+      ".github/skills/source-code-to-ops-spec-guidelines/references/02-core-architecture-flow-data-logic-guideline.md",
+      ".github/skills/source-code-to-ops-spec-guidelines/references/03-error-ops-scenario-coverage-guideline.md"
+    ],
+    "omitted_docs": []
+  },
+  "knowledge_map_preflight": {
+    "queue_status": "loaded",
+    "catalog_status": "loaded",
+    "source_map": [],
+    "known_gaps": [],
+    "reader_facing_name_map": [
+      {
+        "id": "{target_id}",
+        "name": "{target_name}",
+        "entrypoint": "{entrypoint}",
+        "relation": "selected_target",
+        "display_label": "{target_name}"
+      },
+      {
+        "id": "{related_target_id}",
+        "name": "{related_target_name}",
+        "entrypoint": "{related_entrypoint}",
+        "relation": "handoff_edge",
+        "display_label": "{related_target_name}"
+      }
+    ],
+    "related_rows": [
+      {
+        "id": "{related_target_id}",
+        "name": "{related_target_name}",
+        "entrypoint": "{related_entrypoint}",
+        "relation": "handoff_edge",
+        "reason": "{short source-backed handoff reason}",
+        "correlation_key": "{correlation_key}",
+        "source_evidence_refs": []
+      }
+    ],
+    "relation_candidates": [],
+    "coverage_hints": [],
+    "trace_hypotheses": [],
+    "search_priority": []
+  },
+  "code_verification": {
+    "entrypoint_verified": false,
+    "verified_assumptions": [],
+    "source_backed_facts": [],
+    "expansion_search_performed": false,
+    "unmapped_behaviors_found": []
+  },
+  "map_drift": {
+    "status": "none",
+    "items": [],
+    "map_corrections": []
+  },
+  "artifact_drift": {
+    "status": "none",
+    "items": []
+  },
+  "generated_files": [],
+  "file_actions": [],
+  "change_justification": [],
+  "evidence_checked": [],
+  "not_checked": [],
+  "source_evidence": [
+    {
+      "path": "src/main/java/com/example/OrderController.java",
+      "line": 42,
+      "symbol": "OrderController.importOrders()",
+      "kind": "method"
+    }
+  ],
+  "coverage_gaps": [],
+  "unresolved_items": [],
+  "status": "generated"
+}
+```
+
+## Field Rules
+
+- `target_id`、`entrypoint`、`document_root`、`generation_scope`、`doc_profile`、`queue_path` 與 `generated_files` 為必填欄位。
+- `generation_scope` 必須是 `all`、`foundation`、`architecture` 或 `ops`；`doc_profile` 必須是 `lite`、`standard` 或 `full`。兩者各自維持獨立欄位語意。
+- `generation_entrypoint` 與 `review_entrypoint` 用來記錄本次 workflow 的 stable entrypoint；可以是 prompt path、slash command、agent handoff label 或其他 invoker-specific identifier。
+- `doc_file_plan` 必須列出 selected output files、guideline reference set、scope 外或整份不適用的 omitted docs 與 completion impact。Selected output filename 必須符合 `generation-workflow.md` 的 File Naming Contract：以 selected row `name` / 功能名稱為開頭，不使用 target row `id`。
+- `doc_file_plan.selected_output_files` 是本次 run 的 target-facing output allowlist；allowlist 語意由 `generation-workflow.md` 的 `Strict Output Boundary` 擁有。
+- `omitted_docs` 只用於記錄本次 `generation_scope` 未選取的整份文件，或整份 target doc 已確認不適用的情況。Selected output file 內沒有資料、不適用或來源不足的章節，必須保留章節標題並在文件中寫入簡短 `N/A` / `無法由目前來源確認` / `Unresolved` 原因。若省略整份文件或章節缺口會影響 completion，必須同步寫入 `coverage_gaps` 或 `unresolved_items`。
+- `knowledge_map_preflight` 必須記錄 generation 前已讀取的 queue/catalog 狀態、相關 rows、known gaps、coverage hints、trace hypotheses 與 search priority。它作為假設與搜尋索引；行為事實來源由 source evidence 承接。
+- `knowledge_map_preflight.reader_facing_name_map` 必須記錄 selected row 與本次可能寫入 final SPEC / handoff summary 的 related rows、confirmed `handoff_edge` rows、relation candidates 或 catalog handoff rows。每筆至少包含 `id`、`name`、`entrypoint`、`relation` 與 `display_label`。`id` 是 machine-readable lookup handle；`display_label` 是 final SPEC 可使用的 reader-facing label，必須優先使用 row `name` / 功能名稱，其次使用 source-backed job / API / handler / batch name。若只有 row `id` 而無法確認可讀 label，`display_label` 必須填 `Unresolved`，final SPEC 使用 `Unresolved` 作為可讀缺口標示。
+- `reader_facing_name_map` 用於 generation / review 檢查 selected output files 的 reader-facing label；`related_rows` 維持 relation classification，final SPEC metadata 由 guideline contract 擁有。
+- 任何 generation run、rerun 或 handoff reuse 若發現 handoff 缺少 `reader_facing_name_map`、map 中缺少 `display_label`，或 `display_label` 等於 raw row `id`，該 handoff 對 reader-facing naming 視為 legacy / incomplete。Documenter 必須用 current queue / catalog / source evidence 重建 map 後再產生 selected output file；無法解析者填 `display_label=Unresolved`，並在 `unresolved_items` 或 `map_drift.items` 記錄缺口。
+- `knowledge_map_preflight.related_rows` 只保存依 `source-tracing-rules.md` 判定成立的 compact `handoff_edge`。共用資料表、報表查詢、audit/log、lookup、join 或只有 keyword/group/resource 相同的候選關係，依影響寫入 `relation_candidates`、`coverage_gaps` 或 `unresolved_items`。
+- `knowledge_map_preflight.relation_candidates` 可短暫保留尚未確認的候選關係；形成 `handoff_edge` 後才升級成 related row。候選關係只應保留 id、name、candidate reason 與 unresolved reason。
+- 每筆 `related_rows[]` 必須包含 `id`、`name`、`entrypoint`、`relation=handoff_edge`、`reason`、`correlation_key` 與可回查的 `source_evidence_refs` 或 source location。Handoff 中的 downstream target 關係維持 compact summary。
+- `code_verification` 必須記錄 entrypoint 是否已由 source code 或可重讀 metadata 驗證，以及哪些 map assumptions 已被 source-backed evidence 支撐。
+- `map_drift` 必須記錄 queue/catalog 與 code evidence 的差異；沒有差異時使用 `status=none`，有差異時使用 `status=found` 並填入 `items` 與 `map_corrections`。
+- `artifact_drift` 必須記錄 queue status、`document_path`、三份 target SPEC 或 `last_handoff` 與實際檔案存在性的差異；沒有差異時使用 `status=none`，有差異時使用 `status=found` 並填入 `items`。每個 item 應至少包含 `path`、`expected_state`、`actual_state`、`impact` 與 `action_taken`。
+- 若 `docs/docs-target-catalog.md` 缺失或無法對應 selected row，`knowledge_map_preflight.catalog_status` 必須標記為 `missing`、`not_applicable` 或 `unmatched`，並在 `unresolved_items` 說明影響。
+- `generated_files` 必須填入相對於 repository root 的路徑，且必須是 `doc_file_plan.selected_output_files` 的子集合；`handoff.json` 由 handoff path 欄位承接。
+- `file_actions` 必須逐檔記錄 file action；action 判定規則由 `source-tracing-rules.md` 擁有。
+- `change_justification` 必須逐檔或逐章節記錄 action、reason 與 evidence；action 判定規則由 `source-tracing-rules.md` 擁有。
+- `evidence_checked` 必須列出本次實際檢查過的 source path、runtime metadata、DB object、SQL、config、existing doc 或 external contract。
+- `not_checked` 必須列出依 target 型態與 selected scope 應追蹤但尚未確認的 evidence，並說明原因；若無則填空陣列。
+- `source_evidence` 必須是 `EvidenceRef[]`，每個物件都包含 `path`、`line`、`symbol`、`kind`。Repo file evidence 必須使用 1-based `line`；只有 DB metadata、runtime export、external contract 或 generated doc 無可用行號時才可填 `null`。
+- `source_evidence[].kind` 必須使用穩定英文值，例如 `entrypoint`、`route`、`handler`、`class`、`method`、`SQL`、`table`、`config`、`job`、`procedure`、`routine`、`file`、`test`、`runtime_metadata`、`generated_doc`、`external_contract` 或 `other`。
+- `coverage_gaps` 應列出影響完整性的缺失 evidence，例如 DB metadata、runtime config、generated registry、production seed data、credentials 或 external contract，並描述 impact 與最小下一步。
+- `unresolved_items` 應明確且可執行。
+- `status` 應為 `generated`、`partial`、`blocked` 或 `failed`，並與 queue workflow 的 completion 判斷一致。若主要 source path 尚未追完或 `not_checked` 仍包含 completion-critical evidence，使用 `partial`、`blocked` 或 `failed` 表示目前狀態。
+
+## Write Discipline
+
+`handoff.json` 是 generation-to-review 的 machine-readable workflow artifact。Documenter 寫入 handoff 時必須遵守：
+
+- 目標路徑固定為 `target/source-code-to-spec/<target_id>/handoff.json`，除非 queue contract 未來另行變更。
+- 若 parent directory 不存在，先建立 parent directory，再寫入 handoff。
+- 若 handoff 檔案不存在，建立新檔；若已存在，更新或覆寫同一檔案。
+- 同一路徑的 `handoff.json` 更新以單一 overwrite/update 表示。需要重建 JSON 時，仍視為單一 overwrite/update。
+- 若 selected row `last_handoff` 指向不存在的檔案，該狀況記錄於 `artifact_drift.items`；本次 run 依固定 handoff path 建立新的 handoff。
+- `handoff.json` 由 handoff path 欄位記錄；selected output file 的 `CREATED` / `UPDATED` / `UNCHANGED` 判定依 `doc_file_plan.selected_output_files` 執行。
+
+## Review Use
+
+Handoff 作為 generation-to-review 的 evidence / status ledger。Review target resolution、selected row `document_path` 掃描、expected files subset、handoff drift 與 missing selected output 判定，統一由 `source-code-to-spec-reviewer.agent.md` 的 review contract 擁有。

package/.github/skills/source-code-to-spec-documenter/references/generation-workflow.md

@@ -0,0 +1,184 @@
+---
+description: 定義 source-code-to-spec-documenter 依 docs-target-queue 產生或更新 source-code-backed ops SPEC 的執行流程與回報格式。
+---
+
+# Source Code To SPEC Generation Workflow
+
+## 職責
+
+本檔是 `source-code-to-spec-documenter` 的 workflow owner，負責控制 target-level SPEC generation / update 的執行順序與回報格式。
+
+章節內容契約由 `$source-code-to-ops-spec-guidelines` 的 `01`、`02`、`03` reference guideline 定義；queue selection、status transition 與 completion gate 由 `target-queue-contract.md` 定義；source tracing、existing output reconciliation、idempotent update 與 coverage checklist 細節由 `source-tracing-rules.md` 定義；handoff JSON shape 由 `generation-handoff-contract.md` 定義。本檔不重複維護章節欄位、status enum、tracing 規則或 JSON schema。
+
+## Input
+
+- `docs/docs-target-queue.md`：target queue。
+- `id`：選配；若提供，只處理指定 target row。
+- `scope`：`all`、`foundation`、`architecture` 或 `ops`。
+- `doc_profile`：取自 selected row；可用值與語意由 `source-code-to-spec-tools/references/target-queue-schema-contract.md` 擁有。
+- `source-code-to-spec-tools` public CLI：用於 target lookup、catalog lookup 與 source evidence lookup。
+- `$source-code-to-ops-spec-guidelines`：三份 ops SPEC 文件的 content contract 與 quality gate。
+
+## File Naming Contract
+
+Target SPEC 文件一律寫入 selected row 的 `document_path`。檔名必須以 selected row `name` / 功能名稱作為開頭，不使用 target row `id`，格式如下：
+
+| scope | selected output file |
+| --- | --- |
+| `foundation` | `{document_path}/{name}-01-document-foundation-and-business.md` |
+| `architecture` | `{document_path}/{name}-02-core-architecture-flow-data-logic.md` |
+| `ops` | `{document_path}/{name}-03-error-ops-scenario-coverage.md` |
+
+`all` scope 必須規劃以上三份文件。若 queue row 的 `name` 與 `id` 或 source index id 不一致，target-facing filename 仍以 `name` / 功能名稱為準，差異只記錄在 handoff、review note 或 unresolved items。
+
+## Strict Output Boundary
+
+Generation run 只允許寫入 `doc_file_plan.selected_output_files` 列出的 target-facing SPEC 文件，以及 workflow-required `target/source-code-to-spec/<target_id>/handoff.json`。不得因 `## Obsidian Links`、sibling links、catalog links、system overview links、group name、target name、queue row name 或 final response 需要，而額外建立 index note、landing note、folder note、link placeholder、catalog summary 或任何未列入 `doc_file_plan.selected_output_files` 的 `docs/**/*.md` 檔案。
+
+若發現需要補充導覽文件、system overview、catalog、queue 或相關 note，僅在 generated SPEC 的 `## Obsidian Links`、handoff `unresolved_items` 或 final response 中記錄建議；該 generation run 不得順手建立。Reference guideline 只作為規則套用，不輸出成 target-facing doc。
+
+## Artifact Consistency Preflight
+
+在建立 `doc_file_plan` 前，必須檢查 selected row 的 artifact state，並把 queue status 與實際檔案存在性分開處理：
+
+- 檢查 selected row `document_path` 是否存在，以及三份 target SPEC 檔案是否存在。
+- 檢查 selected row `last_handoff` 是否為可讀檔案；若 queue 指向的 `last_handoff` 不存在，不得把它當成可刪除或可復用的 baseline。
+- 若 queue 顯示某份 doc status 為 `generated`，但對應 selected output file 不存在，記錄為 `artifact_drift`，本次以實際檔案狀態建立 `doc_file_plan` 與 file action，不以 stale status 通過 completion gate。
+- 若 `last_handoff` 指向不存在的路徑，記錄為 `artifact_drift` 或 `unresolved_items`，並依 `generation-handoff-contract.md` 的 `Write Discipline` 建立新的最小 handoff baseline。
+- 若現有 artifact state 與 queue status 不一致，但 selected output file 可由目前 source evidence 重新建立或更新，繼續 generation；若不一致阻擋 target boundary 或 source tracing，將 handoff `status` 設為 `blocked` 或 `partial`，並同步更新 queue status。
+
+## Reader-Facing Naming Gate
+
+寫入或更新任何 selected output file 前，必須套用 `$source-code-to-ops-spec-guidelines` 的 Metadata / naming contract：human-readable doc 的標題、Metadata、摘要、表格描述、圖表文字說明、快速入口卡與 troubleshooting 敘述都使用 selected row `name` / 功能名稱稱呼本系統單元，不使用 target row `id` 作為 reader-facing label。
+
+Target row `id` 只可用於 queue selection、handoff path / JSON、review note、final response 或 machine-readable reconciliation。若狀態表、監控指標、排查表或描述欄需要解釋 technical value，應描述該 value 對 selected row `name` / 功能名稱或實際資料狀態的意義，不得以 target row `id` 代稱功能。若 source evidence 本身包含 business id、request id、batch id、trace id、API id、SQL ID 或其他必要識別資料，可保留該 identifier，但必須清楚標示其維運用途，且不得把它當成 target 名稱。
+
+### Reader-Facing Name Resolution
+
+在 `Knowledge Map Preflight` 完成後、建立或更新 selected output file 前，必須從 selected row、candidate related rows、confirmed `handoff_edge` rows、既有 handoff 與 catalog handoff 建立 `reader_facing_name_map`。此 map 只用來防止 final SPEC 誤用 queue lookup id；它不是新的 reader-facing metadata。
+
+`reader_facing_name_map` 至少包含：
+
+- selected row 的 `id`、`name`、`entrypoint` 與 `display_label`，其中 `display_label` 必須等於 selected row `name` / 功能名稱。
+- 每筆被寫入文件或 handoff summary 的 related row / downstream target 的 `id`、`name`、`entrypoint`、`relation` 與 `display_label`。
+- 若只知道 row `id` 而無法確認 `name`、source-backed job/API/handler/batch name 或其他可讀 label，`display_label` 必須是 `Unresolved`，final SPEC 不得輸出該 row `id` 代稱功能。
+
+任何 generation run、rerun 或 handoff reuse 都必須先做 Reader-Facing Name Normalization，再開始撰寫 selected output file。既有 handoff、`related_rows`、`relation_candidates`、review note 或舊版 handoff summary 中的 `id` 只能作為 lookup key；documenter 必須用 current queue / catalog / source evidence 重新對齊 `reader_facing_name_map.display_label`。若既有 handoff 缺少 `reader_facing_name_map`、某筆 related row 沒有 `name` / `display_label`，或舊資料只剩 raw row `id`，該 baseline 對 reader-facing wording 視為不完整：先補 map、標示 `Unresolved`，或把缺口寫入 handoff，不得直接把 raw `id` 寫入 selected output file。
+
+寫作時應建立 render-only context：每個 selected row、related row、downstream target、Mermaid participant、sibling reference 與 cross-reference 都先用 `id` 查 `reader_facing_name_map`，再輸出 `display_label` 或 source-backed technical identifier。禁止把 `related_rows[].id`、`relation_candidates[].id`、`last_handoff` path segment 或 target folder name 當成可顯示名稱。
+
+寫入 selected output file 時，所有自然語言主語、cross-reference、sibling 文件關係、Mermaid participant alias、ERD 補充表、圖表文字說明、狀態 mapping、維護注意事項、監控指標與 troubleshooting 敘述，必須使用 `reader_facing_name_map.display_label` 或 source-backed technical identifier。不得把 `F1`、`F2`、`J2` 這類 queue row `id` 當成 display label；`MENU_ID:555`、`REQUEST_HEADER_ID`、`DPK_ID`、SQL ID、API path、table / column name、job class name 等 technical identifiers 只有在對應章節具維運用途時才可保留。
+
+寫入 handoff 前必須重新掃描本次 `doc_file_plan.selected_output_files` 的 reader-facing content。若發現 known queue row `id` 仍以功能、job、target、participant、狀態主語或 cross-reference label 出現，必須先修正 selected output file；不得把對應 file action 回報為 `UNCHANGED`，也不得將對應 doc status 設為 `generated`。
+
+## Scope Roles
+
+各 generation prompt 的角色如下：
+
+| prompt | role |
+| --- | --- |
+| `00-generate-target-all-spec.prompt.md` | `foundation + discovery baseline + architecture + ops`；一次產生或更新三份文件，並建立完整 shared handoff。 |
+| `01-generate-target-foundation-spec.prompt.md` | `foundation + discovery baseline`；作為不先跑 `00` 時的低成本起點，建立可供 `02` / `03` 復用的 shared handoff。 |
+| `02-generate-target-architecture-spec.prompt.md` | `architecture + reuse/update handoff`；復用既有 baseline，再針對 architecture evidence 做增量追蹤與更新。 |
+| `03-generate-target-ops-spec.prompt.md` | `ops + reuse/update handoff`；復用既有 baseline，再針對 error / ops / scenario coverage 做增量追蹤與更新。 |
+
+`00` 不是每個 target 的必跑前置；成本敏感或 target 邊界已足夠明確時，可以直接從 `01` 開始，再執行 `02` / `03`。若 `02` 或 `03` 發現缺少 handoff，必須建立最小 discovery baseline 並記錄 limitation，不得只因 baseline 不存在就跳過 source tracing。
+
+## Handoff Baseline Contract
+
+Shared handoff 是 scoped generation 之間的可重用 evidence ledger，不是最終文件內容。`00` 與 `01` 必須建立或刷新 baseline；`02` 與 `03` 必須復用並增量更新 baseline。
+
+Baseline 至少包含：
+
+- selected target row、`entrypoint`、`generation_scope`、`doc_profile` 與 `doc_file_plan`。
+- `knowledge_map_preflight`、`reader_facing_name_map`、依 `source-tracing-rules.md` 判定成立的 compact `handoff_edge` related rows、coverage hints、target boundary decision 與 search priority。
+- 可重讀的 `source_evidence: EvidenceRef[]`。
+- downstream relation classification、`map_drift`、`unmapped_behaviors_found`、`coverage_gaps` 與 `unresolved_items`。
+- 逐檔 `file_actions` 與 `change_justification`。
+
+若復用的 baseline 來自舊版 workflow 或缺少 `reader_facing_name_map`，只能復用 evidence 與 unresolved/gap context；不得復用其中的 reader-facing label。任何 selected output file 寫入前，都必須用 current queue row、catalog handoff 與 `target_query.py related` 重新建立 map。
+
+Scoped prompt 更新 handoff 時，應保留其他 scope 已確認且仍符合 source evidence 的 baseline，只追加或修正本次 scope 的 evidence、file action、gap 與 unresolved item；不得為了風格或重新生成偏好覆蓋整份 handoff。
+
+Handoff 寫入語意由 `generation-handoff-contract.md` 的 `Write Discipline` 擁有；本 workflow 只負責在正確流程點觸發 handoff create-or-update，並將 artifact drift、file actions、evidence 與 unresolved items 交給 handoff contract 序列化。
+
+## Output Action Contract
+
+`doc_file_plan` 內的 selected output file 使用 create-or-update 語意：
+
+- 若 selected output file 尚未存在，先完成 source tracing 與 guideline gate，再新增該文件。
+- 若 selected output file 已存在，必須先依 `source-tracing-rules.md` 執行 Existing Output Reconciliation、Idempotent Update Gate 與 Code Verification Pass，比對目前 source code、queue / catalog handoff、related rows、既有 handoff 與本次 scope。
+- 只有當既有文件與目前 source evidence 不符、缺少本次 `doc_profile` / `generation_scope` 必要內容，或結構錯誤影響可審查性時，才補充修正。若沒有 material difference，保留既有內容並回報 `UNCHANGED`。
+- 修改既有文件時，只 patch 受影響章節；不要為了風格、語氣或同義改寫重建整份文件。
+- 任何不在 `doc_file_plan.selected_output_files` 的 `docs/**/*.md` 檔案都不是本次 generation 的合法 create-or-update target；若已被錯誤建立，必須回報為 contract violation，不得寫入 `generated_files` 或用它通過 completion gate。
+
+## Detail And Summary Contract
+
+Target SPEC generation 的內容優先順序是完整、準確、source-backed，其次才是摘要與版面壓縮。摘要、overview、圖表文字說明、handoff summary、Final Response 或 reviewer note 只能協助導覽與交接，不可取代 selected output file 內的正式詳細章節。
+
+`generation_scope` 控制本次寫哪一份 selected output file 與哪些正式章節由本次 run 擁有；它不允許把本 scope 可由 source evidence 確認的 handler、service、DAO / Repository / Mapper、SQL、table、status、config、job、file I/O、external integration、error handling 或 operations detail 壓成概要。
+
+## Full-Depth Gate
+
+`doc_profile=full` 啟用 full-depth gate。此 gate 是 generation workflow 的 completion gate；章節欄位與內容細節仍由 `$source-code-to-ops-spec-guidelines` 的 reference guideline 擁有，source evidence 與 reconciliation 細節仍由 `source-tracing-rules.md` 擁有。
+
+`00-generate-target-all-spec.prompt.md` / `generation_scope=all` 必須對三份 selected output file 分別通過 full-depth gate。`foundation`、`architecture` 與 `ops` 是 sibling docs，不可用其中一份的詳細章節、handoff summary、Final Response 或 reviewer note 代替另一份文件在本 scope 內應保留的 source-backed detail。
+
+對 `doc_file_plan` 內每一份 selected output file，將對應 doc status 設為 `generated`，或將 file action 回報為 `UPDATED` / `UNCHANGED` 前必須確認：
+
+- 本次 `Knowledge Map Preflight`、`Code Verification Pass` 與 `Expansion Search` 已發現、且屬於該文件正式 scope 的 source-backed behavior、SQL、DAO / Repository / Mapper mapping、table / status / field mapping、request / response / file / external payload mapping、branch、transaction、rollback、retry/rerun、log、error 與 operations detail，已寫入該 selected output file 的正式章節。
+- 若 `Code Verification Pass` 或 `Expansion Search` 發現 File I/O / Report evidence，且 architecture selected output file 在本次 `doc_file_plan` 內，full-depth gate 必須確認 `02` 的 `6.5 檔案 I/O 規格` 已依 `$source-code-to-ops-spec-guidelines` 產出欄位規格、驗證規則與錯誤輸出；有匯出 / 報表 evidence 時也必須保留資料來源與欄位對應。只在 `6.3`、`03`、summary 或 final response 提及 File I/O 不算通過。
+- 若 detail 屬於另一份 sibling doc 的正式 scope，該 detail 寫入正確 sibling doc；目前文件只保留必要 cross-reference 或 handoff cue，不複製 sibling doc 的正式章節。
+- 若 detail 屬於具獨立 activation evidence 的 downstream target 內部規格，目前文件完整寫清本 target 的交付資料、狀態與 correlation key；downstream 內部規格只寫 handoff summary 與 cross-reference，完整 `EvidenceRef[]` 保留在 handoff。
+- 若 source evidence 不存在、目前來源不足或已確認不適用，該章節保留標題並以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 說明原因；completion-impacting 缺口同步寫入 handoff `coverage_gaps` 或 `unresolved_items`。
+- 若既有文件未達 full-depth gate，但缺漏可由目前 source evidence 補足，必須依 Output Action Contract 與 `source-tracing-rules.md` patch 受影響章節，不得回報 `UNCHANGED`。
+
+若任一 selected output file 未通過 full-depth gate，不得把對應 doc status 設為 `generated`。可保留 partial output，但對應 status 必須依 `target-queue-contract.md` 設為 `partial`、`blocked` 或 `failed`，並在 handoff `file_actions`、`change_justification`、`Evidence Checked` / `Not Checked`、`coverage_gaps` 或 `unresolved_items` 中說明未通過原因。
+
+`doc_profile=full` 的 completion standard 包含下列要求：
+
+- 保留可從 source 讀取的完整 SQL excerpt；若 SQL 由條件式或字串組合產生，改以 source-backed pseudo SQL 呈現完整查詢意圖、條件、join、排序、狀態過濾與參數來源。
+- 明確列出 DAO / Repository / Mapper method 到 SQL、table、status column、DB object、stored routine、file resource 或 external resource 的 mapping。
+- 保留 handler / controller / job / service 到 DAO method 的 source-backed flow，包含與維運判斷相關的 branch、transaction、rollback、retry/rerun、log、error message 與 status transition。
+- 若存在 request / response、file column、DB column、status 或 external payload mapping，必須以表格或結構化段落保留欄位對應與轉換規則。
+- 若存在 File I/O / Report 行為，architecture selected output file 的 `6.5` 擁有欄位主規格；ops selected output file 只補維運覆蓋、troubleshooting 與 coverage gaps，不得取代 `02` 的欄位表。
+
+若流程、SQL、mapping 或圖表過大，不得因此刪除 source-backed detail；應拆成多個子章節、表格、圖表或 code fence excerpt。只有沒有 source evidence、確定不適用，或屬於另一個具獨立 activation evidence 的 downstream target 內部規格時，才以 `N/A`、`無法由目前來源確認`、`Unresolved` 或 handoff summary 處理。
+
+## 執行流程
+
+1. 檢查 repo 狀態並定位 `docs/docs-target-queue.md`。
+2. 使用 `spec_queue.py` 選取 target row；使用 `target_query.py preflight` 與 `target_query.py related` 取得 queue summary、coverage 與 related rows。
+3. 執行 `Artifact Consistency Preflight`：檢查 selected row `document_path`、三份 target SPEC、`last_handoff` 與實際檔案存在性；若 queue status 與 artifact state 不一致，記錄 `artifact_drift`，並以實際檔案狀態決定 create-or-update，不把 stale `last_handoff` 當成可刪除 baseline。
+4. 執行 `Knowledge Map Preflight`：讀取 selected row、queue supporting tables、catalog handoff、related rows、既有 handoff / docs / review note，整理 source map、known gaps、related rows、coverage hints、trace hypotheses、search priority 與 `reader_facing_name_map`；若既有 handoff 缺少或污染 reader-facing label，依 Reader-Facing Name Normalization 先重建 map。
+5. 解析 `generation_scope` 與 `doc_profile`，建立 `doc_file_plan`：
+   - `all`：規劃三份文件。
+   - `foundation`：只規劃 File Naming Contract 中的 foundation 文件。
+   - `architecture`：只規劃 File Naming Contract 中的 architecture 文件。
+   - `ops`：只規劃 File Naming Contract 中的 ops 文件。
+   - `generation_scope` 只限制 selected output file 與本次 run 擁有的正式章節，不限制 source tracing 範圍，也不降低本 scope 內 source-backed detail 的深度；若 downstream job、status transition、staging table 或 external integration 可能接手目前 target 建立的 work item，必須依 `source-tracing-rules.md` 的 `Functional Boundary And Handoff Edges` 分類。若 downstream 有獨立 activation evidence，目前文件完整寫清本 target 的交付資料、狀態與 correlation key，downstream 內部規格只寫 handoff summary 與 cross-reference；完整 `EvidenceRef[]` 保留在 handoff。
+   - 本次 scope 內的正式章節應保留章節標題；若章節沒有來源資料、已確認不適用，或目前來源不足以填寫，不產生空表格、空圖表或推測內容，只輸出簡短 `N/A` / `無法由目前來源確認` / `Unresolved` 原因。若該缺口影響 completion，必須寫入 `coverage_gaps` 或 `unresolved_items`。
+6. 讀取 `doc_file_plan` 指定的 existing output、既有 handoff 與 reviewer note，依 `source-tracing-rules.md` 建立 reconciliation context；缺少的 selected output file 標記為待新增，不以空白文件代替 evidence。
+7. 在產生文件前，將本次 scope 對應 status 設為 `in_progress`。
+8. 執行 `Code Verification Pass` 與 `Expansion Search`：從 selected row 的 `entrypoint` 實際追蹤 handler、flow、data resource、error / security / observability、operation behavior 與 coverage evidence；不得停在高階摘要，必須依 `doc_profile` 保留可審查的 source-backed detail。
+9. 執行 `Map Drift Handling`：若 queue / catalog 與 code evidence 不一致，文件以 source evidence 為準，並在 handoff 記錄 drift、corrections 或需要後續 catalog / queue 修正的 items。
+10. 依 `doc_file_plan`、Output Action Contract、Strict Output Boundary、Reader-Facing Name Normalization 與 `$source-code-to-ops-spec-guidelines` 的必要 reference guideline，新增缺少的 selected output file，或只補充修正與目前 source evidence 不符的既有文件。Reference guideline 只作為規則套用，不輸出成 target-facing doc；writing context 只能使用 `reader_facing_name_map.display_label` 或 source-backed technical identifier，不直接渲染 handoff raw `id`。
+11. 若 `doc_profile=full`，依 Full-Depth Gate 逐檔檢查 selected output file；未通過 gate 的文件不得將對應 doc status 設為 `generated`，也不得回報無缺口的 `UPDATED` / `UNCHANGED`。
+12. 依 `$source-code-to-ops-spec-guidelines` 的 Metadata / naming contract 與本 workflow 的 `Reader-Facing Name Resolution` 檢查 selected output files；未通過時必須修正後才可進入 handoff / queue status 更新。
+13. 依 `source-tracing-rules.md` 整理逐檔 `file_actions`、`change_justification`、`Evidence Checked` / `Not Checked` 與 completion-impacting gaps。
+14. 依 `generation-handoff-contract.md` 的 `Write Discipline` 將 generation handoff 寫入 `target/source-code-to-spec/<target_id>/handoff.json`，並包含 `doc_profile`、`doc_file_plan`、`knowledge_map_preflight.reader_facing_name_map`、`code_verification`、`map_drift`、`artifact_drift`、`file_actions`、`change_justification`、`evidence_checked`、`not_checked`、`source_evidence: EvidenceRef[]`、`coverage_gaps` 與 `unresolved_items`。
+15. 依 `target-queue-contract.md` 的 generation entrypoint / scope status mapping 更新本次 scope owned doc status。每次 generation run 結束後都必須檢查 selected row `document_path` 下三份 target SPEC 文件是否存在；三份都存在時設定 `document_completed_flag(Y/N)=Y`，否則保持或設定為 `N`。Generation 只可將 `review_status` 設為 `pending` 或 `blocked`；`passed`、`failed`、`waived` 由 review workflow 更新。
+16. 將結果交給 review workflow；review workflow 只負責後續 `review_status`、findings 與必要 notes。
+
+## Final Response
+
+回報 target id、entrypoint、document root、`doc_profile`、generated files、handoff path、queue status 與下一步 review prompt。若本次 run 建立或修改任何不在 `doc_file_plan.selected_output_files` 的 `docs/**/*.md` 檔案，必須明確列為 contract violation，並要求清理後重跑或 review。
+
+若發現 queue status、`last_handoff` 或 `document_path` 與實際 artifact state 不一致，Final Response 必須回報 `Artifact Drift`，包含受影響 path、實際存在狀態、採取的 create-or-update action，以及是否影響 completion flag。
+
+若本次是 update 既有文件，必須同時回報：
+
+- `File Actions`: 逐檔列出 `CREATED`、`UPDATED` 或 `UNCHANGED`。
+- `Change Justification`: 對 `UPDATED` 與 `UNCHANGED` 說明 reason 與 evidence。
+- `Evidence Checked` / `Not Checked`。
+- `Open Items`: 需要人工補充或無法由目前來源確認的事項。