ops-wiki-agent-kit 0.1.0 → 0.1.1

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

@@ -1,155 +1,66 @@
 # Generation Handoff Contract
 
-每一次文件 generation run 在進入 review 前，都必須先寫出一份 handoff。預設路徑如下：
+每一次 baseline / generation run 都必須寫出 handoff。非 baseline generation run 在進入 review 前，必須先寫出或刷新 handoff；baseline run 只建立或刷新 discovery ledger，不觸發 review。Handoff 是 compact machine-readable ledger，不是 target SPEC 摘要、長篇追蹤報告或跨 scope history dump。Handoff 只寫入 durable workflow artifact path：
 
 ```text
-target/source-code-to-spec/<target_id>/handoff.json
+.github/artifacts/source-code-to-spec/<target_id>/handoff.json
 ```
 
-## JSON Shape
+## Initial Template
 
-```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"
-}
-```
+初始 handoff skeleton 由 `references/handoff-initial-template.json` 擁有。該檔只在建立新 baseline 或修復 missing / legacy baseline 時載入；一般 `01` / `02` / `03` scoped generation 若既有 durable handoff 有有效 `baseline`，不得為了更新 `current_run` 而讀取或重套初始 template。
+
+`generation-handoff-contract.md` 只維護欄位規則、compact update 與 write discipline；不要在本檔複製完整 JSON skeleton。
 
 ## 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`。兩者各自維持獨立欄位語意。
+- `target_id`、`entrypoint`、`document_root`、`generation_scope`、`doc_profile`、`queue_path`、`handoff_path`、`baseline`、`current_run`、`map_drift`、`artifact_drift` 與 `status` 為必填欄位。
+- `generation_scope` 必須是 `baseline`、`all`、`foundation`、`architecture` 或 `ops`；`doc_profile` 必須是 `lite`、`standard` 或 `full`。兩者各自維持獨立欄位語意。
+- Patch JSON 的 root `generation_scope` 與 `current_run.scope` 必須等於本次 invocation scope，也必須與 `handoff_update.py --scope` 完全一致。不得重用其他 scope 的 patch JSON，也不得用 baseline patch 更新非 baseline scope。
 - `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` 擁有。
+- `baseline.doc_file_plan` 記錄 durable discovery baseline 與後續預期文件；`current_run.doc_file_plan` 才是本次 run 的 target-facing output allowlist。Allowlist 語意由 `generation-workflow.md` 的 `Strict Output Boundary` 擁有。
+- `current_run.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`。
+- `baseline` scope 的 `current_run.doc_file_plan.selected_output_files` 必須是空陣列；可用 `baseline.doc_file_plan.planned_output_files` 記錄後續 `foundation`、`architecture`、`ops` 預期輸出，但 planned files 不是本次 run 的寫入 allowlist。
 - `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 擁有。
+- `baseline` 必須記錄 generation 前已讀取的 queue/catalog 狀態、相關 rows、known gaps、coverage hints、trace hypotheses 與 search priority。它作為假設與搜尋索引；行為事實來源由 `direct_evidence_refs` 與各 scope delta 的 `source_evidence` 承接。
+- `baseline.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；`baseline.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 支撐。
+- `baseline.related_rows` 只保存依 `source-tracing-rules.md` 判定成立的 compact `handoff_edge`。共用資料表、報表查詢、audit/log、lookup、join 或只有 keyword/group/resource 相同的候選關係，依影響寫入 `baseline.relation_candidates`、`current_run.coverage_gaps` 或 `current_run.unresolved_items`。
+- `baseline.relation_candidates` 可短暫保留尚未確認的候選關係；形成 `handoff_edge` 後才升級成 related row。候選關係只應保留 id、name、candidate reason 與 unresolved reason。
+- `baseline` scope 必須保留 visible subfunctions、direct links、form actions、popup、AJAX、include、downstream candidate 與 unmapped behaviors 的索引；若尚未符合 `handoff_edge` 條件，不得丟棄，應放入 `baseline.relation_candidates`、`baseline.unmapped_behaviors_found`、`baseline.coverage_gaps`、`baseline.unresolved_items`、`current_run.coverage_gaps` 或 `current_run.unresolved_items`。
+- 每筆 `baseline.related_rows[]` 必須包含 `id`、`name`、`entrypoint`、`relation=handoff_edge`、`reason`、`correlation_key` 與可回查的 `source_evidence_refs` 或 source location。Handoff 中的 downstream target 關係維持 compact summary。
 - `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`。
+- 若 `docs/docs-target-catalog.md` 缺失或無法對應 selected row，`baseline.catalog_status` 必須標記為 `missing`、`not_applicable` 或 `unmatched`，並在 `current_run.unresolved_items` 說明影響。
+- `handoff_path` 必須是 `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`。不得指向 `target/**`、`docs/**` 或其他 scratch / reader-facing path。
+- `current_run.generated_files` 必須填入相對於 repository root 的路徑，且必須是 `current_run.doc_file_plan.selected_output_files` 的子集合；`baseline` scope 必須填空陣列。`handoff.json` 由 `handoff_path` 承接，不列入 `generated_files`。
+- `current_run.file_actions` 必須逐檔記錄 file action；action 判定規則由 `source-tracing-rules.md` 擁有。
+- `current_run.change_justification` 必須逐檔或逐章節記錄 action、reason 與 evidence；action 判定規則由 `source-tracing-rules.md` 擁有。
+- `current_run.evidence_checked` 必須列出本次實際檢查過的 source path、runtime metadata、DB object、SQL、config、existing doc 或 external contract。
+- `current_run.not_checked` 必須列出依 target 型態與 selected scope 應追蹤但尚未確認的 evidence，並說明原因；若無則填空陣列。
+- `current_run.source_evidence` 必須是本次 scope 新增或修正的 `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` 表示目前狀態。
+- `current_run.coverage_gaps` 應列出本次 scope 發現或仍影響完整性的缺失 evidence，例如 DB metadata、runtime config、generated registry、production seed data、credentials 或 external contract，並描述 impact 與最小下一步。
+- `current_run.unresolved_items` 應明確且可執行。
+- `scope_deltas` 保存必要的 prior scope deltas。每個 delta 只保留 scope、status、generated_files、file_actions、新增或修正的 `source_evidence`、仍需後續處理的 `not_checked`、`coverage_gaps`、`unresolved_items` 與更新時間；不得保存整段 prose summary、完整文件摘錄或重複 baseline 中已有的 map。
+- `status` 應為 `baseline_ready`、`generated`、`partial`、`blocked` 或 `failed`，並與 queue workflow 的 completion 判斷一致。`baseline_ready` 只可用於 `baseline` scope，表示 entrypoint、reader-facing name map、direct evidence 與 follow-up ledger 已建立；若主要 source path 尚未追完或 `not_checked` 仍包含 completion-critical evidence，使用 `partial`、`blocked` 或 `failed` 表示目前狀態。
 
 ## Write Discipline
 
-`handoff.json` 是 generation-to-review 的 machine-readable workflow artifact。Documenter 寫入 handoff 時必須遵守：
+`handoff.json` 是 baseline / generation / 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` 執行。
+- 每次 handoff 寫入都必須寫到 durable path：`.github/artifacts/source-code-to-spec/<target_id>/handoff.json`。
+- Handoff 寫入必須透過 `python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope <generation_scope> --patch <patch-json>`。Documenter 只準備本次 patch JSON，不手動讀寫或重組整份 `handoff.json`。
+- Patch JSON 必須包含 `current_run`；root `generation_scope`、`current_run.scope` 與 CLI `--scope` 必須表示同一個 invocation scope。若 handoff 檔案不存在或既有 handoff 缺少 `baseline`，才載入 `references/handoff-initial-template.json`，並在 patch 內包含 compact `baseline`。Patch 可包含要更新的 root metadata、`map_drift`、`artifact_drift` 與 `status`。
+- `foundation`、`architecture`、`ops` 與 `all` 都遵守同一個 helper merge 規則；不得直接編輯 durable `handoff.json`。
+- 若 workspace 中存在尚未合併的 patch JSON，必須以 patch 自身的 `generation_scope` / `current_run.scope` 呼叫 `handoff_update.py`；不得用目前 invocation scope 強制套用其他 scope 的 patch，也不得手動轉寫 patch 內容。
+- `handoff_update.py` 負責建立 parent directory、讀取既有 handoff、保留仍有效的 `baseline` 與 prior `scope_deltas`、覆寫 `current_run`、新增或取代同一 scope 的 compact delta，並以 UTF-8 no BOM atomic replace 寫回。不得為了格式、語氣、排序或重新生成偏好重寫整包 history。
+- Queue `last_handoff` 必須更新為 durable path：`.github/artifacts/source-code-to-spec/<target_id>/handoff.json`。若 `generation_scope=baseline`，也必須依 handoff `status` 更新 queue `baseline_status`：`baseline_ready`、`partial`、`blocked` 或 `failed`。
+- 若 selected row `last_handoff` 指向不存在的檔案，該狀況記錄於 `artifact_drift.items`；本次 run 依固定 durable path 重新建立 handoff。
+- `handoff.json` 由 `handoff_path` 欄位記錄；selected output file 的 `CREATED` / `UPDATED` / `UNCHANGED` 判定依 `current_run.doc_file_plan.selected_output_files` 執行。
+- Legacy handoff 若仍使用舊版 top-level `knowledge_map_preflight`、`code_verification`、`source_evidence`、`coverage_gaps` 或 `unresolved_items`，本次 run 只抽取可回查的 evidence、reader-facing map、gap 與 unresolved context 轉入 compact shape；不得把舊版長篇 prose 或重複 history 原樣搬入 `scope_deltas`。
 
 ## 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 擁有。
+Handoff 作為 baseline-to-generation 與 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

@@ -14,7 +14,7 @@ description: 定義 source-code-to-spec-documenter 依 docs-target-queue 產生
 
 - `docs/docs-target-queue.md`：target queue。
 - `id`：選配；若提供，只處理指定 target row。
-- `scope`：`all`、`foundation`、`architecture` 或 `ops`。
+- `scope`：`baseline`、`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。
@@ -23,28 +23,33 @@ description: 定義 source-code-to-spec-documenter 依 docs-target-queue 產生
 
 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` |
+| scope          | selected output file                                             |
+| -------------- | ---------------------------------------------------------------- |
+| `baseline`     | 不產生 target-facing SPEC 文件；只建立或刷新 durable handoff     |
+| `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` |
+| `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。
+`all` scope 必須規劃以上三份 target-facing 文件。`baseline` scope 的 `current_run.doc_file_plan.selected_output_files` 必須是空陣列，並可在 `baseline.doc_file_plan.planned_output_files` 記錄後續 `01` / `02` / `03` 預期輸出。若 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` 檔案。
+Generation run 只允許寫入 `current_run.doc_file_plan.selected_output_files` 列出的 target-facing SPEC 文件，以及 workflow-required durable handoff：
+
+- `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`
+
+`baseline` scope 不允許寫入任何 target-facing `docs/**/*.md` 檔案。不得因 `## 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 或任何未列入 `current_run.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 與實際檔案存在性分開處理：
+在建立 `current_run.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。
+- 檢查 selected row `last_handoff` 是否為可讀檔案；`last_handoff` 應指向 `.github/artifacts/source-code-to-spec/<target_id>/handoff.json` durable handoff。若 queue 指向的 `last_handoff` 不存在，不得把它當成可刪除或可復用的 baseline。
+- 若 queue 顯示某份 doc status 為 `generated`，但對應 selected output file 不存在，記錄為 `artifact_drift`，本次以實際檔案狀態建立 `current_run.doc_file_plan` 與 file action，不以 stale status 通過 completion gate。
+- 若 `last_handoff` 指向不存在的路徑，記錄為 `artifact_drift` 或 `unresolved_items`，並依 `generation-handoff-contract.md` 的 `Initial Template` / `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
@@ -55,7 +60,7 @@ Target row `id` 只可用於 queue selection、handoff path / JSON、review note
 
 ### 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。
+在 `Knowledge Map Preflight` 完成後、建立或更新 selected output file 前，必須從 selected row、candidate related rows、confirmed `handoff_edge` rows、既有 handoff 的 compact baseline 與 catalog handoff 建立 `reader_facing_name_map`。此 map 只用來防止 final SPEC 誤用 queue lookup id；它不是新的 reader-facing metadata。
 
 `reader_facing_name_map` 至少包含：
 
@@ -63,54 +68,100 @@ Target row `id` 只可用於 queue selection、handoff path / JSON、review note
 - 每筆被寫入文件或 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。
+任何 generation run、rerun 或 handoff reuse 都必須先做 Reader-Facing Name Normalization，再開始撰寫 selected output file。既有 handoff 的 `baseline.related_rows`、`baseline.relation_candidates`、prior `scope_deltas`、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 當成可顯示名稱。
+寫作時應建立 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。禁止把 `baseline.related_rows[].id`、`baseline.relation_candidates[].id`、prior `scope_deltas[].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`。
+寫入 handoff 前必須重新掃描本次 `current_run.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 做增量追蹤與更新。 |
+| prompt                                           | role                                                                                                                                                                                                            |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `00-discover-target-baseline.prompt.md`          | `baseline discovery only`；建立或刷新 shared handoff，登記 entrypoint evidence、visible subfunctions、relation candidates、unmapped behaviors、coverage gaps 與 `not_checked`，不產生 target-facing SPEC 文件。 |
+| `00-generate-target-all-spec.prompt.md`          | `foundation + discovery baseline + architecture + ops`；一次產生或更新三份文件，並建立或刷新完整 shared durable handoff。                                                                                       |
+| `01-generate-target-foundation-spec.prompt.md`   | `foundation + consume/update discovery baseline`；優先復用 `00-discover-target-baseline` 的 shared handoff，產生第 1 份文件。若 baseline 不存在，只建立最小 baseline 並揭露 `not_checked` / unresolved items。  |
+| `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。
+`00-discover-target-baseline` 是 rate-limited 或大型 target 的建議前置，但不是每個 target 的必跑前置。成本敏感或 target 邊界已足夠明確時，可以直接從 `01` 開始，再執行 `02` / `03`。只有建立新 baseline 或修復 missing / legacy baseline 時，才載入 `references/handoff-initial-template.json`。若 `01`、`02` 或 `03` 發現缺少 handoff，必須用該 template 建立最小 discovery baseline 並記錄 limitation，不得只因 baseline 不存在就跳過 source tracing。
 
 ## Handoff Baseline Contract
 
-Shared handoff 是 scoped generation 之間的可重用 evidence ledger，不是最終文件內容。`00` 與 `01` 必須建立或刷新 baseline；`02` 與 `03` 必須復用並增量更新 baseline。
+Shared handoff 是 scoped generation 之間的 compact evidence ledger，不是最終文件內容，也不是 source tracing completion proof。`00-discover-target-baseline` 只建立或刷新 baseline；`00-generate-target-all-spec` 建立 baseline 並把三份文件的成果寫入 scope deltas；`01` 優先復用 baseline 並產 foundation，必要時建立最小 baseline；`02` 與 `03` 必須復用 baseline，並只針對本次 scope 新增或修正 delta。
 
 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`。
+- selected target row、`entrypoint`、`generation_scope`、`doc_profile` 與 `baseline.doc_file_plan`。
+- `reader_facing_name_map`、依 `source-tracing-rules.md` 判定成立的 compact `handoff_edge` related rows、coverage hints、target boundary decision 與 search priority。
+- 可重讀的 direct `EvidenceRef[]`，只保留定位 entrypoint、source map 與 relation classification 所需的最小 evidence。
+- downstream relation classification、unmapped behavior index、baseline-level `coverage_gaps` 與 `unresolved_items`。
+
+Scope delta 至少包含：
+
+- 本次 `generation_scope`、`status`、`current_run.doc_file_plan.selected_output_files`、`generated_files`、`file_actions` 與 `change_justification`。
+- 本次實際檢查的 `evidence_checked`、新增或修正的 `source_evidence: EvidenceRef[]`、仍需後續追蹤的 `not_checked`、`coverage_gaps` 與 `unresolved_items`。
+- 必要時保存本次發現的 `map_drift` / `artifact_drift` reference，但不要複製整份 baseline map。
+
+`baseline` scope 的 handoff 必須額外遵守：
 
-若復用的 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。
+- `current_run.doc_file_plan.selected_output_files=[]`，不得建立或更新 target-facing SPEC 文件。
+- `generated_files=[]`、`file_actions=[]`，除非未來 contract 另行定義 baseline-specific action。
+- `status` 使用 `baseline_ready`、`partial`、`blocked` 或 `failed`；若主要 entrypoint 尚未驗證或仍有 completion-critical `not_checked`，不得使用 `baseline_ready`。
+- queue 只可更新 `baseline_status` 與 `last_handoff`；`last_handoff` 必須是 durable path `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`。不得更新 `foundation_doc_status`、`architecture_doc_status`、`ops_doc_status`、`review_status` 或 `document_completed_flag(Y/N)`。
+- visible subfunctions、direct links、form actions、popup、AJAX、include、downstream candidate 或 unmapped behavior 不得因 bounded tracing 被丟棄；必須寫入 `relation_candidates`、`unmapped_behaviors_found`、`coverage_gaps` 或 `unresolved_items`。
 
-Scoped prompt 更新 handoff 時，應保留其他 scope 已確認且仍符合 source evidence 的 baseline，只追加或修正本次 scope 的 evidence、file action、gap 與 unresolved item；不得為了風格或重新生成偏好覆蓋整份 handoff。
+`01` 產出的 foundation delta 若因 rate limit 或 bounded tracing 未追完，不得把缺少的 downstream、DAO、SQL、error / ops evidence 寫成已確認不存在。這些項目必須保留在 `current_run.not_checked`、`current_run.coverage_gaps` 或 `current_run.unresolved_items`，供 `02` / `03` 強制 follow-up。
+
+若復用的 baseline 來自舊版 workflow 或缺少 `reader_facing_name_map`，只能抽取可回查的 evidence 與 unresolved/gap context；不得復用其中的 reader-facing label，也不得把舊版 prose/history 原樣搬入新版 `scope_deltas`。任何 selected output file 寫入前，都必須用 current queue row、catalog handoff 與必要的 `target_query.py related` 重新建立 map。
+
+Scoped prompt 更新 handoff 時，應保留 baseline 中仍符合 source evidence 的 compact index，只追加或修正本次 scope delta 的 evidence、file action、gap 與 unresolved item；不得為了風格、排序、摘要或重新生成偏好覆蓋整份 handoff。後續 scope 只需要讀取 baseline、current scope 所需的 prior deltas、以及仍 open 的 `not_checked` / `coverage_gaps` / `unresolved_items`，不得把所有歷史 delta 當作寫作材料。
 
 Handoff 寫入語意由 `generation-handoff-contract.md` 的 `Write Discipline` 擁有；本 workflow 只負責在正確流程點觸發 handoff create-or-update，並將 artifact drift、file actions、evidence 與 unresolved items 交給 handoff contract 序列化。
 
+## Handoff Patch And Queue Sync Gate
+
+每次 baseline / generation run 都只更新同一份 durable handoff：`.github/artifacts/source-code-to-spec/<target_id>/handoff.json`。本次 run 準備的是 patch JSON，不是另一份正式 handoff。Patch JSON 的 root `generation_scope` 與 `current_run.scope` 必須等於本次 invocation scope，並與 `handoff_update.py --scope` 完全一致；不得重用其他 scope 的 patch JSON。
+
+Handoff update 成功後，必須立即同步 selected row 的 queue status。Queue sync 是 handoff 寫入後的 required gate，不是 final response 的建議事項；若 queue update 或 reselect 驗證失敗，本次 run 不得宣告 `docs/docs-target-queue.md` 已更新。
+
+進入目前 scope 前，若發現同一 target 已有前序或本次 pending patch JSON，但 durable `handoff.json` 尚未包含該 patch 對應的 scope delta / `current_run` 狀態，必須先依 patch 內的 root `generation_scope` 或 `current_run.scope` 執行 `handoff_update.py`。不得把該 patch 內容手動複製進 `handoff.json`，也不得在未 merge 的狀態下讓後續 scope 依 stale handoff 繼續。前序 patch merge 成功後，也必須依該 patch scope 執行 queue sync / reselect；再回到目前 invocation scope。
+
+Baseline scope 使用：
+
+```bash
+python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope baseline --patch <patch-json>
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --baseline <baseline_ready|partial|blocked|failed> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id <target_id> --scope baseline
+```
+
+Non-baseline scope 使用同一個 durable handoff path，並只更新本次 scope 擁有的 doc status。`<doc_status>` 依 `target-queue-contract.md` 使用 `generated`、`n/a`、`partial`、`blocked` 或 `failed`；`<completed_flag>` 必須由 selected row `document_path` 下三份 target SPEC 文件的實際存在性決定。下列 `--foundation`、`--architecture`、`--ops` queue update commands 是依本次 scope 擇一執行，不是同一 scoped run 全部執行。
+
+```bash
+python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py update --handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json --target-id <target_id> --scope <foundation|architecture|ops> --patch <patch-json>
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --foundation <doc_status> --review <pending|blocked> --completed <Y|N> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --architecture <doc_status> --review <pending|blocked> --completed <Y|N> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py update --queue docs/docs-target-queue.md --id <target_id> --ops <doc_status> --review <pending|blocked> --completed <Y|N> --last-handoff .github/artifacts/source-code-to-spec/<target_id>/handoff.json
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py select --queue docs/docs-target-queue.md --id <target_id> --scope <foundation|architecture|ops>
+```
+
+`all` scope 仍只寫同一份 durable handoff，但 queue sync 必須同時更新 `--foundation`、`--architecture` 與 `--ops` 的狀態，並用同一個 reselect 驗證 selected row。Final response 必須回報 reselect 後的 queue status；不得只回報 handoff update 結果。
+
+Documenter 不得直接編輯 durable `handoff.json` 來替代 `handoff_update.py` merge。若 patch JSON 已準備完成但 helper 尚未成功執行，本次 scope 的 handoff update 視為未完成；不得只靠手動修改、final response 或 queue status 宣告已同步。
+
 ## Output Action Contract
 
-`doc_file_plan` 內的 selected output file 使用 create-or-update 語意：
+`current_run.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。
+- 任何不在 `current_run.doc_file_plan.selected_output_files` 的 `docs/**/*.md` 檔案都不是本次 generation 的合法 create-or-update target；若已被錯誤建立，必須回報為 contract violation，不得寫入 `generated_files` 或用它通過 completion gate。
 
 ## Detail And Summary Contract
 
@@ -124,10 +175,10 @@ Target SPEC generation 的內容優先順序是完整、準確、source-backed
 
 `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` 前必須確認：
+對 `current_run.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 不算通過。
+- 若 `Code Verification Pass` 或 `Expansion Search` 發現 File I/O / Report evidence，且 architecture selected output file 在本次 `current_run.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`。
@@ -139,7 +190,7 @@ Target SPEC generation 的內容優先順序是完整、準確、source-backed
 
 - 保留可從 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。
+- 保留 handler / controller / job / service / template / custom tag / script / procedure / trigger / workflow task / message consumer 到資料存取、外部資源或狀態異動節點的 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` 的欄位表。
 
@@ -148,31 +199,32 @@ Target SPEC generation 的內容優先順序是完整、準確、source-backed
 ## 執行流程
 
 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。
+2. 使用 `$source-code-to-spec-documenter` Queue Helper 選取 target row；使用 `target_query.py preflight` 取得 selected row、queue summary、coverage 與 related rows。只有 preflight 缺少 related candidates、需要不同 `--limit` / `--include-self`，或需要重新查證 related rows 時，才另外呼叫 `target_query.py related`，並在 handoff 記錄補查目的。
 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`：
+4. 執行 `Knowledge Map Preflight`：讀取 selected row、queue supporting tables、catalog handoff、related rows、既有 handoff 的 `baseline` / open deltas、既有 docs / review note，整理 source map、known gaps、related rows、coverage hints、trace hypotheses、search priority 與 `reader_facing_name_map`；若 handoff 不存在、缺少 `baseline` 或屬於 legacy shape，才載入 `references/handoff-initial-template.json` 建立最小 baseline patch。若既有 handoff 可用，只讀取 baseline、current scope 所需的 prior deltas 與仍 open 的 gap，不讀 template、不重套 skeleton。若既有 handoff 缺少或污染 reader-facing label，依 Reader-Facing Name Normalization 先重建 map。不要把 prior `scope_deltas` 全量展開成寫作材料，只取本次 scope 需要的 open gaps、related rows 與 evidence refs。
+5. 解析 `generation_scope` 與 `doc_profile`，建立 `current_run.doc_file_plan`：
+   - `baseline`：不規劃 target-facing selected output file；`current_run.doc_file_plan.selected_output_files=[]`，只規劃 handoff。
    - `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。
+   - `generation_scope` 只限制 selected output file 與本次 run 擁有的正式章節，不降低本 scope 內已確認結論的 evidence standard。`baseline` 與 bounded `foundation` 可將深層 source tracing 轉成 `not_checked` / follow-up ledger，但不得把未查項目寫成不存在或不適用；若 downstream job、status transition、staging table 或 external integration 可能接手目前 target 建立的 work item，必須檢查足夠 evidence 或明確登記為 follow-up，並依 `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。
+6. 讀取 `current_run.doc_file_plan` 指定的 existing output、既有 handoff baseline / relevant scope deltas 與 reviewer note，依 `source-tracing-rules.md` 建立 reconciliation context；缺少的 selected output file 標記為待新增，不以空白文件代替 evidence。
+7. 在產生文件前，將本次 scope 對應 status 設為 `in_progress`；`baseline` scope 只更新 `baseline_status`，不得更新任何 target-facing doc status。
+8. 執行 `Code Verification Pass` 與 `Expansion Search`：`baseline` scope 只執行 bounded verification，確認 selected row `entrypoint`、direct evidence、visible subfunctions 與 follow-up ledger，不展開完整 target SPEC detail；非 baseline scope 從 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`。
+10. 依 `current_run.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 不符的既有文件。`baseline` scope 跳過 target-facing writing，只寫 handoff evidence ledger。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。
+13. 依 `source-tracing-rules.md` 整理本次 scope 的逐檔 `file_actions`、`change_justification`、`Evidence Checked` / `Not Checked` 與 completion-impacting gaps；這些內容只整理成本次 `current_run` 與必要 root metadata，不得把 prior `scope_deltas` 全量展開成新的寫作材料。
+14. 依 `generation-handoff-contract.md` 的 `Write Discipline` 準備本次 handoff patch JSON，並執行 `Handoff Patch And Queue Sync Gate`。Patch JSON 必須包含 `current_run`，且 root `generation_scope`、`current_run.scope` 與 CLI `--scope` 必須等於本次 invocation scope；若 handoff 不存在或缺少 `baseline`，patch 也必須依 `references/handoff-initial-template.json` 補入 compact `baseline`。`handoff_update.py` 負責保留既有 `baseline`、replace 同一 scope 的 compact delta、覆寫 `current_run`、維持 `handoff_path` / `doc_profile` / `map_drift` / `artifact_drift` / `status`，並以 atomic replace 寫回 durable handoff。Documenter 不得手動重寫整份 `handoff.json`，也不得把 prior deltas 重新摘要成長篇 history。
+15. 依 `target-queue-contract.md` 的 generation entrypoint / scope status mapping 更新本次 scope owned status，並用 `spec_queue.py select` 重新讀取 selected row 驗證更新結果。`baseline` scope 只更新 `baseline_status` 與 durable `last_handoff` path，不更新 target-facing doc status、review status 或 completion flag。每次非 baseline 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. 非 baseline generation 將結果交給 review workflow；review workflow 只負責後續 `review_status`、findings 與必要 notes。`baseline` scope 不觸發 review，只在 Final Response 建議下一步執行 `01` / `02` / `03`。
 
 ## 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。
+回報 target id、entrypoint、document root、`doc_profile`、generated files、durable handoff path、reselect 後的 queue status 與下一步 review prompt。`baseline` scope 回報 confirmed evidence、relation candidates、unmapped behaviors、coverage gaps、`not_checked`、durable handoff path 與下一步建議 prompt，不回報 generated files 或 review handoff。若本次 run 建立或修改任何不在 `current_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。
 

package/.github/skills/source-code-to-spec-documenter/references/handoff-initial-template.json

@@ -0,0 +1,76 @@
+{
+  "handoff_type": "source-code-to-spec-document-generation",
+  "target_id": "{target_id}",
+  "source_type": "{source_type}",
+  "group": "{business_group}",
+  "name": "{target_name}",
+  "entrypoint": "{entrypoint}",
+  "document_root": "docs/feature/{business_group}/{target_name}",
+  "generation_scope": "baseline",
+  "doc_profile": "standard",
+  "selected_coverage_views": [],
+  "generation_entrypoint": "baseline-discovery",
+  "review_entrypoint": "review-workflow",
+  "queue_path": "docs/docs-target-queue.md",
+  "handoff_path": ".github/artifacts/source-code-to-spec/{target_id}/handoff.json",
+  "baseline": {
+    "doc_file_plan": {
+      "selected_output_files": [],
+      "planned_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": [],
+      "omitted_docs": []
+    },
+    "queue_status": "loaded",
+    "catalog_status": "loaded",
+    "reader_facing_name_map": [
+      {
+        "id": "{target_id}",
+        "name": "{target_name}",
+        "entrypoint": "{entrypoint}",
+        "relation": "selected_target",
+        "display_label": "{target_name}"
+      }
+    ],
+    "related_rows": [],
+    "relation_candidates": [],
+    "coverage_hints": [],
+    "trace_hypotheses": [],
+    "search_priority": [],
+    "direct_evidence_refs": [],
+    "unmapped_behaviors_found": [],
+    "coverage_gaps": [],
+    "unresolved_items": []
+  },
+  "scope_deltas": [],
+  "current_run": {
+    "scope": "baseline",
+    "doc_file_plan": {
+      "selected_output_files": [],
+      "guideline_reference_set": [],
+      "omitted_docs": []
+    },
+    "generated_files": [],
+    "file_actions": [],
+    "change_justification": [],
+    "evidence_checked": [],
+    "not_checked": [],
+    "source_evidence": [],
+    "coverage_gaps": [],
+    "unresolved_items": [],
+    "status": "baseline_ready"
+  },
+  "map_drift": {
+    "status": "none",
+    "items": [],
+    "map_corrections": []
+  },
+  "artifact_drift": {
+    "status": "none",
+    "items": []
+  },
+  "status": "baseline_ready"
+}