ops-wiki-agent-kit 0.1.0 → 0.1.2

package/.github/skills/source-code-to-spec-documenter/references/source-tracing-rules.md

@@ -14,6 +14,41 @@
 
 只有在上述 CLI 查不到、解析失敗或檔案格式超出支援時，才補手動 `rg` 或 parser-specific inspection，並在 handoff 中記錄 CLI limitation。不要呼叫其他 skill 私有 `scripts/` 目錄。
 
+## Baseline And Rate-Limited Tracing
+
+`baseline` scope 的目標是建立可復用 discovery ledger，不是產生 target-facing SPEC，也不是證明所有 behavior 都已查完。它必須使用 CLI-first、bounded tracing，降低單次 agent run 的 `read/search` 密度，同時保留後續 scope 必須追蹤的線索。
+
+`baseline` scope 必須完成：
+
+1. 使用 `target_query.py preflight` 讀取 selected row、coverage review 與 related row candidates。
+2. 使用 `catalog_query.py handoff` / `catalog_query.py search` 讀取 catalog-level source acquisition 與 known gaps。
+3. 使用 canonical `source_lookup.py` 解析 selected `entrypoint` 的直接 evidence。
+4. 建立 `reader_facing_name_map`，包含 selected row、candidate related rows、visible subfunctions 與 catalog handoff rows。
+5. 登記 visible subfunctions、direct links、form actions、popup、AJAX、include、downstream candidate、shared data dependency 與 unmapped behavior。
+6. 將未完成的 deeper tracing 寫入 `not_checked`、`coverage_gaps` 或 `unresolved_items`。
+
+`baseline` scope 不得：
+
+- 建立或更新任何 target-facing `docs/**/*.md` 文件。
+- 因 bounded tracing 沒有展開 downstream job、DAO、SQL、error / ops behavior，就寫成 `N/A`、已確認不存在或已確認不適用。
+- 用連續未界定的 regex search 取代 canonical CLI lookup。
+- 丟棄 entrypoint 可見的子功能、連結、popup、AJAX、include 或 downstream candidate。
+
+### Baseline Tool Budget And Stop Conditions
+
+`baseline` scope 必須優先降低單次 agent run 的工具請求數。除非使用者明確要求 deep tracing，本 scope 的查詢與讀檔採下列節流規則：
+
+- 重用同一輪已取得的 CLI output，不得為了重新確認而重跑相同 `target_query.py preflight`、`catalog_query.py handoff/search`、`source_lookup.py` 或相同 `rg` 查詢。
+- 不在 generation run 期間執行 CLI `--help`、錯誤案例、smoke test、語法測試或維護用驗證；工具契約錯誤應在該工具修正回合處理，baseline run 只記錄 `cli_limitation` / `not_checked` 後停止對該方向的重試。
+- Source file read 以 selected `entrypoint` 與其直接可見 include / form action / AJAX / popup / handler 為上限；同一檔案同一輪只讀一次。若需要更多檔案才能追完 downstream、DAO、SQL、job 或 error / ops path，先把候選寫入 `relation_candidates`、`coverage_gaps` 或 `not_checked`，交給 `01` / `02` / `03`。
+- 達到 bounded scope、遇到 rate limit 風險、或 evidence 已足以建立 search priority 時，不繼續追求完整性；寫出 `partial` 或 `baseline_ready` handoff，並在 `not_checked` 明列後續應追的檔案、keyword 或 behavior。
+
+對 `generation_scope=foundation` 且 `doc_profile=standard`，若已存在 usable baseline，foundation tracing 可採 bounded update：只追 selected `entrypoint`、直接 include / handler、直接資料資源、直接子功能入口與明顯 handoff。更深的 downstream job lifecycle、DAO/SQL mapping、status transition、error handling、retry/rerun 與 ops behavior，應保留為 `not_checked` 或 follow-up gaps，交給 `architecture` / `ops` scope 繼續驗證。
+
+`foundation` bounded tracing 降低的是單次工具呼叫密度，不降低 evidence standard。文件中所有已確認敘述仍必須可回查 source evidence；未確認的項目必須明確標示「無法由目前來源確認」、`TBD` 或 `Unresolved`，並寫入 handoff。
+
+`architecture` 與 `ops` scope 必須把前序 handoff 的 `not_checked`、`coverage_gaps`、`relation_candidates` 與 `unmapped_behaviors_found` 視為 mandatory follow-up input。不得因 baseline 或 foundation 沒有展開某個 path，就推定該 behavior 不存在。
+
 ## Canonical Source Lookup Command
 
 `source_root` 是本次 selected row 要做 source tracing 的 source artifact 根目錄；若 queue、handoff、使用者指示或 workflow context 沒有提供更窄範圍，預設為 target source repo root。即使 `source_root` 等於 repo root，也必須在 `source_lookup.py` 命令中顯式傳入 `--root`，不要依賴目前 shell `cwd`。
@@ -37,26 +72,37 @@ python -B .github/skills/source-code-to-spec-tools/scripts/source_lookup.py --ro
 }
 ```
 
-| Field        | Required | Rule                                                                                                                                                                                                              |
-| ------------ | -------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path`       |        Y | Repo-relative file path、可重讀 metadata path，或穩定 source identifier。對 repo file 必須使用實際相對路徑，不要只寫 filename。                                                                                   |
-| `line`       |        Y | Repo file evidence 必須填 1-based line number。只有 DB metadata、runtime export、external contract 或 generated doc 無可用行號時才可填 `null`。                                                              |
-| `symbol`     |        Y | 最小可搜尋 technical handle，例如 `ClassName.methodName()`、`GET /api/orders`、`TABLE_NAME`、`config.key`、`JobName`、`ProcedureName`。                                                                           |
-| `kind`       |        Y | 使用穩定英文值：`entrypoint`、`route`、`handler`、`class`、`method`、`SQL`、`table`、`config`、`job`、`procedure`、`routine`、`file`、`test`、`runtime_metadata`、`generated_doc`、`external_contract`、`other`。 |
+| Field    | Required | Rule                                                                                                                                                                                                              |
+| -------- | -------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path`   |        Y | Repo-relative file path、可重讀 metadata path，或穩定 source identifier。對 repo file 必須使用實際相對路徑，不要只寫 filename。                                                                                   |
+| `line`   |        Y | Repo file evidence 必須填 1-based line number。只有 DB metadata、runtime export、external contract 或 generated doc 無可用行號時才可填 `null`。                                                                   |
+| `symbol` |        Y | 最小可搜尋 technical handle，例如 `ClassName.methodName()`、`GET /api/orders`、`TABLE_NAME`、`config.key`、`JobName`、`ProcedureName`。                                                                           |
+| `kind`   |        Y | 使用穩定英文值：`entrypoint`、`route`、`handler`、`class`、`method`、`SQL`、`table`、`config`、`job`、`procedure`、`routine`、`file`、`test`、`runtime_metadata`、`generated_doc`、`external_contract`、`other`。 |
 
 `source_lookup.py` 的 `matches[].evidence_ref` 是可複用的初始 EvidenceRef；後續人工 tracing 可調整 `kind` 與 `symbol`，但不可移除必要欄位。若同一結論需要多個 evidence，請用多個 `EvidenceRef`，不要把多個 path/line 塞進同一欄字串。
 
 ## Knowledge Map Preflight
 
-1. 使用 `target_query.py preflight` 讀取 `docs/docs-target-queue.md` 的 selected row，確認 `id`、`source_type`、`group`、`name`、`entrypoint`、`document_path`、`keyword`、status、`last_handoff` 與 `notes`。
+1. 使用 `target_query.py preflight` 讀取 `docs/docs-target-queue.md` 的 selected row，確認 `id`、`source_type`、`group`、`name`、`entrypoint`、`document_path`、`keyword`、`baseline_status`、doc status、`last_handoff` 與 `notes`。
 2. 讀取 queue 的 `Source Acquisition Summary`，確認 selected row 來自 DB export、catalog direct rows、repo-owned route/config、hardcoded source、external metadata 或 unresolved source。
 3. 讀取 queue 的 `Coverage Review`，先排除 known helper、folder-only row、unmapped servlet、missing metadata 或 excluded target，避免把 gap 當成新 target。
 4. 使用 `catalog_query.py` 讀取 `docs/docs-target-catalog.md` 的 `Authoritative Target Source Handoff`、direct target rows、hardcoded target rows 與 catalog-level `Coverage Review`，確認 final row authority 與 acquisition action。
-5. 使用 `target_query.py related` 查找 candidate related rows：同 `group`、同 `entrypoint`、同 handler/class、同 route/path、同 scheduler/job、同 table/resource、同 `keyword` 或 catalog evidence 指向同一 implementation artifact 的 rows。這些只是候選關係，不是 target boundary 結論；必須依 `Functional Boundary And Handoff Edges` 分類後，才可寫入 handoff `related_rows`。
-6. 若 selected row 有 `last_handoff`、既有 docs、partial output 或 review failure，先讀取並復用已確認的 evidence、unresolved items 與仍有效的說明；但舊 handoff 的 `id`、path segment 或 related row key 不得作為 reader-facing label 復用。
+5. 優先使用 `target_query.py preflight` 回傳的 `related_rows` 作為 candidate related rows；只有 preflight 缺少 related candidates、需要不同 `--limit` / `--include-self`，或需要重新查證 related rows 時，才另外呼叫 `target_query.py related`。這些只是候選關係，不是 target boundary 結論；必須依 `Functional Boundary And Handoff Edges` 分類後，才可寫入 handoff `related_rows`。
+6. 若 selected row 有 `last_handoff`、既有 docs、partial output 或 review failure，先讀取並復用已確認的 evidence、unresolved items 與仍有效的說明；`last_handoff` 必須指向 `.github/artifacts/source-code-to-spec/<target_id>/handoff.json` durable handoff。舊 handoff 的 `id`、path segment 或 related row key 也不得作為 reader-facing label 復用。
 7. 建立 `reader_facing_name_map`，至少包含 selected row，以及本次可能寫入 final SPEC 或 handoff summary 的 candidate related rows、confirmed `handoff_edge` rows、既有 handoff related rows 與 catalog handoff rows。每筆必須保留 machine-readable `id`，但 final SPEC 顯示用 `display_label` 必須優先取 row `name` / 功能名稱，其次取 source-backed job / API / handler / batch name；若無法確認可讀 label，`display_label=Unresolved`。若既有 handoff 沒有 `reader_facing_name_map` 或某筆 map 只剩 raw `id`，必須用 current queue / catalog / source evidence 重建 map，並把無法解析的 label 寫成 `Unresolved`。
 8. 將 preflight 結果整理為 `source map`、`known gaps`、`related rows`、`reader_facing_name_map`、`coverage hints`、`trace hypotheses`、`search_priority`，再開始 source tracing。
 
+### Visible Subfunction Preservation
+
+Entry point 可見的 link、form action、button handler、AJAX/fetch/XHR、popup、tab、wizard step、include、iframe、menu node、report/export/import、upload/download 或 downstream activation candidate 都不得因目前 scope 不展開而消失。
+
+分類規則：
+
+- 若子功能沒有獨立 activation evidence，且是 selected target 的 private helper 或同一 handler 內 sub-action，應在目前 target 的 source tracing 中保留為 current target behavior。
+- 若子功能已有 queue row、獨立 menu/API/job/scheduler/command/route 或其他 activation evidence，不能寫進目前 target 的完整內部規格；必須登記為 `relation_candidates`、confirmed `related_rows`，或最小 cross-reference / boundary note。
+- 若 source evidence 可見，但 queue / catalog 沒有對應 row，必須寫入 `code_verification.unmapped_behaviors_found`，並視 impact 寫入 `coverage_gaps` 或 `unresolved_items`。
+- 若只是 shared table/resource、lookup、report query、audit/log 或 incidental reference，不建立 `handoff_edge`；必要時寫入 `relation_candidates` 並說明 unresolved reason。
+
 ## Existing Output Reconciliation
 
 既有 target 文件、handoff 與 reviewer note 是前次 generation context，不是目前 SPEC truth。當使用者指定 `id`，或 queue row 的 `document_path` / `last_handoff` 指向既有輸出時，必須在寫新內容前做 reconciliation：
@@ -116,7 +162,7 @@ Code verification 的目標是產生 full detail source-backed SPEC，而不是
 - 驗證 preflight 中的 handler、target name、entrypoint、data resource、coverage hints 與 known gaps 是否仍符合 source。
 - 如果 queue/catalog 與 code 不一致，以 code evidence 為準，但必須記錄差異。
 - 不可因 preflight 沒提到某個行為，就跳過 entrypoint 可達的 code path。
-- `generation_scope` 只限制本次 selected output file 與本次 run 擁有的正式章節，不限制 source tracing 範圍，也不降低本 scope 內 source-backed detail 的深度。若同一 business lifecycle 可能需要 downstream job、callback、staging table、status transition 或 external integration 才能解釋目前 scope 的交付點，必須檢查足夠 evidence 並依 `Functional Boundary And Handoff Edges` 分類；不可因本次只產生 foundation / architecture / ops 單檔就省略，也不可把獨立 downstream target 的內部流程展開到目前文件。
+- `generation_scope` 只限制本次 selected output file 與本次 run 擁有的正式章節，不降低本 scope 內已確認結論的 evidence standard。`baseline` 與 bounded `foundation` 可將深層 source tracing 轉成 `not_checked` / follow-up ledger，但不得把未查項目寫成不存在或不適用。若同一 business lifecycle 可能需要 downstream job、callback、staging table、status transition 或 external integration 才能解釋目前 scope 的交付點，必須檢查足夠 evidence 或明確登記為 follow-up，並依 `Functional Boundary And Handoff Edges` 分類；不可因本次只產生 foundation / architecture / ops 單檔就省略，也不可把獨立 downstream target 的內部流程展開到目前文件。
 - `doc_profile=full` 時，必須保留可讀取的完整 SQL excerpt；動態 SQL 必須轉為 source-backed pseudo SQL，並列出條件來源、參數、join、排序、狀態過濾與限制。DAO / Repository / Mapper method 必須 mapping 到 SQL、table、status column、DB object、stored routine、file resource 或 external resource。
 
 每次 generation / update 都必須整理 `Evidence Checked` / `Not Checked`：
@@ -160,11 +206,11 @@ A 文件不應展開 B-owned 內部規格：
 
 將 candidate relation 分為以下三類：
 
-| relation | Definition | Current target doc behavior | Handoff behavior |
-| --- | --- | --- | --- |
-| `handoff_edge` | A 建立 work item，B 以明確 source evidence 接手並推進同一 work item。 | 完整寫 A 的交付資料、狀態、correlation key、SQL / DAO mapping 與 source evidence；B 只寫 activation pointer、交接摘要與 cross-reference。 | 可寫入 `related_rows`。 |
-| `shared_data_dependency` | A / B 使用同一 table/resource，但沒有明確接手或狀態推進關係。 | 通常不寫；必要時只列資料影響。 | 不寫入 `related_rows`；必要時寫入 `coverage_gaps` / `unresolved_items`。 |
-| `incidental_reference` | lookup、report、audit/log、history、join、permission check 或其他偶然引用。 | 不寫。 | 不寫入 `related_rows`。 |
+| relation                 | Definition                                                                  | Current target doc behavior                                                                                                               | Handoff behavior                                                         |
+| ------------------------ | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `handoff_edge`           | A 建立 work item，B 以明確 source evidence 接手並推進同一 work item。       | 完整寫 A 的交付資料、狀態、correlation key、SQL / DAO mapping 與 source evidence；B 只寫 activation pointer、交接摘要與 cross-reference。 | 可寫入 `related_rows`。                                                  |
+| `shared_data_dependency` | A / B 使用同一 table/resource，但沒有明確接手或狀態推進關係。               | 通常不寫；必要時只列資料影響。                                                                                                            | 不寫入 `related_rows`；必要時寫入 `coverage_gaps` / `unresolved_items`。 |
+| `incidental_reference`   | lookup、report、audit/log、history、join、permission check 或其他偶然引用。 | 不寫。                                                                                                                                    | 不寫入 `related_rows`。                                                  |
 
 只有同時符合下列條件，才可判定為 `handoff_edge`：
 

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

@@ -9,12 +9,13 @@
 1. 明確指定 `id` 時，一律以該 `id` 為準。
 2. 明確指定 `id` 時，不檢查 `document_completed_flag(Y/N)` 或任何 doc status；即使該列不是 `pending` 或不是 `N`，也必須處理該 selected row。
 3. 未提供 `id` 時，依 `docs/docs-target-queue.md` main target table 順序由上到下挑選第一筆符合本次 scope 的 row。
-4. 若 `scope=all`，挑選第一筆 `document_completed_flag(Y/N)=N` 的 row。
-5. 若 `scope=foundation`，挑選第一筆 `foundation_doc_status=pending` 的 row。
-6. 若 `scope=architecture`，挑選第一筆 `architecture_doc_status=pending` 的 row。
-7. 若 `scope=ops`，挑選第一筆 `ops_doc_status=pending` 的 row。
-8. No-id auto selection 不自動挑選 `failed`、`partial`、`blocked`、`in_progress`、`generated`、`n/a` 或其他非 `pending` status；若要重跑這些 row，必須明確指定 `id`。
-9. `review_status` 不參與 generation no-id auto selection；review workflow 有自己的 selection / status 規則。
+4. 若 `scope=baseline`，挑選第一筆 `baseline_status=pending` 的 row；`last_handoff` 只用於 artifact drift / durable handoff consistency 檢查，不作 no-id auto selection 主條件。
+5. 若 `scope=all`，挑選第一筆 `document_completed_flag(Y/N)=N` 的 row。
+6. 若 `scope=foundation`，挑選第一筆 `foundation_doc_status=pending` 的 row。
+7. 若 `scope=architecture`，挑選第一筆 `architecture_doc_status=pending` 的 row。
+8. 若 `scope=ops`，挑選第一筆 `ops_doc_status=pending` 的 row。
+9. No-id auto selection 不自動挑選 `failed`、`partial`、`blocked`、`in_progress`、`generated`、`n/a`、`baseline_ready` 或其他非 `pending` status；若要重跑這些 row，必須明確指定 `id`。
+10. `review_status` 不參與 generation no-id auto selection；review workflow 有自己的 selection / status 規則。
 
 明確指定 `id` 只鎖定 selected row，不代表直接覆蓋文件，也不得只因 target docs 或 `last_handoff` 已存在就跳過。Selected output file 的 create-or-update action 由 `generation-workflow.md` 的 Output Action Contract 擁有；既有內容比對與 material difference 判斷由 `source-tracing-rules.md` 擁有。
 
@@ -26,6 +27,7 @@
 
 | scope | target document | status field |
 | --- | --- | --- |
+| `baseline` | 不產生 target-facing SPEC；只建立 shared handoff | `baseline_status` |
 | `all` | 三份文件全部處理 | `foundation_doc_status`、`architecture_doc_status`、`ops_doc_status` |
 | `foundation` | `{name}-01-document-foundation-and-business.md` | `foundation_doc_status` |
 | `architecture` | `{name}-02-core-architecture-flow-data-logic.md` | `architecture_doc_status` |
@@ -39,6 +41,7 @@ Generation:
 
 | generation entrypoint / scope | status fields owned by this run |
 | --- | --- |
+| `00-discover-target-baseline.prompt.md` / `baseline` | `baseline_status`；完成時同步更新 `last_handoff` |
 | `00-generate-target-all-spec.prompt.md` / `all` | `foundation_doc_status`、`architecture_doc_status`、`ops_doc_status` |
 | `01-generate-target-foundation-spec.prompt.md` / `foundation` | `foundation_doc_status` |
 | `02-generate-target-architecture-spec.prompt.md` / `architecture` | `architecture_doc_status` |
@@ -48,6 +51,7 @@ Status update rules:
 
 | event | status update |
 | --- | --- |
+| `baseline` scope 建立或刷新 handoff | 將 `baseline_status` 設為 `baseline_ready`、`partial`、`blocked` 或 `failed`，並在建立 handoff 時將 `last_handoff` 更新為 durable path `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`；不得更新 target-facing doc status、`review_status` 或 `document_completed_flag(Y/N)` |
 | 選入本次 scope 產生流程 | 本次 scope owned status field 設為 `in_progress`；`all` scope 同時設定三個 doc status |
 | 本次 selected output file 已產生、更新或經 reconciliation 判定 existing file 可作為目前 scope 的有效輸出 | 對應 doc status 設為 `generated` |
 | 本次 scope 不適用 | 對應 doc status 設為 `n/a` |
@@ -58,7 +62,7 @@ Status update rules:
 
 Completion flag update:
 
-- 每次 generation run 結束後，都必須檢查 selected row 的 `document_path` 下三份 target SPEC 文件是否存在。
+- 每次非 baseline generation run 結束後，都必須檢查 selected row 的 `document_path` 下三份 target SPEC 文件是否存在。
 - 若 `{name}-01-document-foundation-and-business.md`、`{name}-02-core-architecture-flow-data-logic.md`、`{name}-03-error-ops-scenario-coverage.md` 三份文件都存在，設定 `document_completed_flag(Y/N)=Y`。
 - 若三份文件尚未齊全，設定或保持 `document_completed_flag(Y/N)=N`。
 - `document_completed_flag(Y/N)` 不等待 `review_status=passed`，也不代表 review 已通過。
@@ -76,3 +80,16 @@ Review:
 | 明確豁免審查 | `review_status=waived` |
 
 `document_completed_flag(Y/N)` 表示三份 target SPEC 文件是否已存在，不再由 `review_status` gate。Review workflow 只更新 `review_status` 與 review findings；除非 review 發現三份文件實際缺漏或路徑錯誤，否則不應只因 review 未通過而把 completion flag 改回 `N`。
+
+## Queue Sync Gate
+
+Generation workflow 在 handoff update 成功後，必須透過 `$source-code-to-spec-documenter` Queue Helper 的 `spec_queue.py update` 同步 selected row，並立刻用 `spec_queue.py select` 重新讀取同一列驗證結果。這個 gate 是 workflow completion 的一部分；若 update 或 reselect 失敗，不得宣告 `docs/docs-target-queue.md` 已更新。
+
+Queue sync 必須遵守：
+
+- `last_handoff` 一律更新為 `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`。
+- `baseline` scope 只更新 `baseline_status` 與 `last_handoff`。
+- `foundation`、`architecture`、`ops` scope 只更新本次 scope 擁有的 doc status，並依實際三份文件存在性更新 `document_completed_flag(Y/N)`。
+- `all` scope 同步更新三個 doc status，並依實際三份文件存在性更新 `document_completed_flag(Y/N)`。
+- 非 baseline generation 若本次文件可審查，`review_status` 設為 `pending`；若 target boundary 或必要 source 受阻，設為 `blocked`。
+- Final response 使用 reselect 後的 queue row，不使用記憶中的預期狀態。

package/.github/skills/source-code-to-spec-documenter/scripts/handoff_update.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+import sys
+
+sys.dont_write_bytecode = True
+
+import argparse
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+SUPPORTED_SCOPES = {"baseline", "all", "foundation", "architecture", "ops"}
+SUPPORTED_STATUSES = {"baseline_ready", "generated", "partial", "blocked", "failed"}
+
+ROOT_FIELDS = [
+    "handoff_type",
+    "target_id",
+    "source_type",
+    "group",
+    "name",
+    "entrypoint",
+    "document_root",
+    "generation_scope",
+    "doc_profile",
+    "selected_coverage_views",
+    "generation_entrypoint",
+    "review_entrypoint",
+    "queue_path",
+    "handoff_path",
+    "baseline",
+    "scope_deltas",
+    "current_run",
+    "map_drift",
+    "artifact_drift",
+    "status",
+]
+
+DELTA_FIELDS = [
+    "scope",
+    "status",
+    "generated_files",
+    "file_actions",
+    "change_justification",
+    "source_evidence",
+    "not_checked",
+    "coverage_gaps",
+    "unresolved_items",
+]
+
+REQUIRED_ROOT_FIELDS = [
+    "target_id",
+    "entrypoint",
+    "document_root",
+    "generation_scope",
+    "doc_profile",
+    "queue_path",
+    "handoff_path",
+    "baseline",
+    "current_run",
+    "map_drift",
+    "artifact_drift",
+    "status",
+]
+
+
+def canonical_handoff_path(target_id):
+    return f".github/artifacts/source-code-to-spec/{target_id}/handoff.json"
+
+
+def normalize_path_text(value):
+    return str(value or "").strip().replace("\\", "/")
+
+
+def read_json(path):
+    return json.loads(Path(path).read_text(encoding="utf-8-sig"))
+
+
+def write_json_atomic(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp_name = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            newline="\n",
+            dir=str(path.parent),
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temp_name = handle.name
+            json.dump(data, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temp_name, path)
+    except Exception:
+        if temp_name:
+            try:
+                os.unlink(temp_name)
+            except OSError:
+                pass
+        raise
+
+
+def require_object(value, label):
+    if not isinstance(value, dict):
+        raise SystemExit(f"{label} must be a JSON object")
+    return value
+
+
+def require_scope(scope):
+    normalized = str(scope or "").strip().lower()
+    if normalized not in SUPPORTED_SCOPES:
+        raise SystemExit(
+            f"Unsupported scope: {scope}. Supported scopes: {', '.join(sorted(SUPPORTED_SCOPES))}"
+        )
+    return normalized
+
+
+def validate_handoff_path(path_text, target_id):
+    expected = canonical_handoff_path(target_id)
+    actual = normalize_path_text(path_text)
+    if actual != expected:
+        raise SystemExit(
+            f"Invalid handoff path. Expected {expected}; got {path_text}"
+        )
+    return expected
+
+
+def validate_patch(patch, target_id, scope):
+    patch_target = patch.get("target_id")
+    if patch_target and str(patch_target) != target_id:
+        raise SystemExit(f"Patch target_id {patch_target} does not match --target-id {target_id}")
+
+    current_run = require_object(patch.get("current_run"), "patch.current_run")
+    patch_scope = patch.get("generation_scope") or current_run.get("scope")
+    if patch_scope and require_scope(patch_scope) != scope:
+        raise SystemExit(
+            f"Patch scope {patch_scope} does not match --scope {scope}. "
+            "Use a patch JSON generated for the same invocation scope; do not reuse another scope's patch."
+        )
+
+    status = patch.get("status") or current_run.get("status")
+    if status and str(status).strip() not in SUPPORTED_STATUSES:
+        raise SystemExit(
+            f"Unsupported status: {status}. Supported statuses: {', '.join(sorted(SUPPORTED_STATUSES))}"
+        )
+
+    current_run_scope = current_run.get("scope")
+    if current_run_scope and require_scope(current_run_scope) != scope:
+        raise SystemExit(
+            f"current_run.scope {current_run_scope} does not match --scope {scope}. "
+            "Use a patch JSON generated for the same invocation scope; do not reuse another scope's patch."
+        )
+
+
+def compact_delta(current_run, scope, timestamp):
+    delta = {}
+    for field in DELTA_FIELDS:
+        if field == "scope":
+            delta[field] = scope
+        elif field == "status":
+            delta[field] = current_run.get("status", "partial")
+        else:
+            delta[field] = current_run.get(field, [])
+    delta["updated_at"] = timestamp
+    return delta
+
+
+def replace_scope_delta(scope_deltas, delta):
+    updated = []
+    replaced = False
+    for existing in scope_deltas:
+        if not isinstance(existing, dict):
+            continue
+        if str(existing.get("scope", "")).strip().lower() == delta["scope"]:
+            updated.append(delta)
+            replaced = True
+        else:
+            updated.append(existing)
+    if not replaced:
+        updated.append(delta)
+    return updated
+
+
+def validate_merged_handoff(handoff):
+    missing = [
+        field
+        for field in REQUIRED_ROOT_FIELDS
+        if field not in handoff or handoff[field] in (None, "")
+    ]
+    if missing:
+        raise SystemExit(f"Merged handoff is missing required fields: {', '.join(missing)}")
+    require_object(handoff["baseline"], "handoff.baseline")
+    require_object(handoff["current_run"], "handoff.current_run")
+    require_object(handoff["map_drift"], "handoff.map_drift")
+    require_object(handoff["artifact_drift"], "handoff.artifact_drift")
+
+
+def merge_handoff(existing, patch, target_id, scope, handoff_path):
+    current_run = dict(require_object(patch["current_run"], "patch.current_run"))
+    current_run["scope"] = scope
+    status = patch.get("status") or current_run.get("status") or "partial"
+
+    if status not in SUPPORTED_STATUSES:
+        raise SystemExit(f"Unsupported status: {status}")
+
+    if existing:
+        handoff = {field: existing.get(field) for field in ROOT_FIELDS if field in existing}
+    else:
+        handoff = {}
+
+    for key, value in patch.items():
+        if key in {"scope_deltas", "current_run"}:
+            continue
+        if key in ROOT_FIELDS:
+            handoff[key] = value
+
+    handoff["handoff_type"] = handoff.get(
+        "handoff_type", "source-code-to-spec-document-generation"
+    )
+    handoff["target_id"] = target_id
+    handoff["generation_scope"] = scope
+    handoff["handoff_path"] = handoff_path
+    handoff["current_run"] = current_run
+    handoff["status"] = status
+    handoff.setdefault("queue_path", "docs/docs-target-queue.md")
+    handoff.setdefault("map_drift", {"status": "none", "items": [], "map_corrections": []})
+    handoff.setdefault("artifact_drift", {"status": "none", "items": []})
+
+    if "baseline" in patch:
+        handoff["baseline"] = patch["baseline"]
+    elif "baseline" not in handoff or handoff["baseline"] is None:
+        raise SystemExit("Existing handoff has no baseline; patch.baseline is required")
+
+    scope_deltas = handoff.get("scope_deltas")
+    if not isinstance(scope_deltas, list):
+        scope_deltas = []
+
+    if scope != "baseline":
+        timestamp = patch.get("updated_at") or datetime.now(timezone.utc).isoformat()
+        scope_deltas = replace_scope_delta(scope_deltas, compact_delta(current_run, scope, timestamp))
+
+    handoff["scope_deltas"] = scope_deltas
+    validate_merged_handoff(handoff)
+    return {field: handoff[field] for field in ROOT_FIELDS if field in handoff}
+
+
+def command_update(args):
+    scope = require_scope(args.scope)
+    handoff_path = validate_handoff_path(args.handoff, args.target_id)
+    patch = require_object(read_json(args.patch), "patch")
+    validate_patch(patch, args.target_id, scope)
+
+    path = Path(handoff_path)
+    existing = read_json(path) if path.exists() else None
+    if existing:
+        existing_target = existing.get("target_id")
+        if existing_target and str(existing_target) != args.target_id:
+            raise SystemExit(
+                f"Existing handoff target_id {existing_target} does not match --target-id {args.target_id}"
+            )
+
+    updated = merge_handoff(existing, patch, args.target_id, scope, handoff_path)
+    write_json_atomic(path, updated)
+    print(
+        json.dumps(
+            {
+                "handoff_path": handoff_path,
+                "target_id": args.target_id,
+                "scope": scope,
+                "status": updated.get("status"),
+                "scope_deltas": len(updated.get("scope_deltas", [])),
+                "queue_update_required": True,
+                "last_handoff": handoff_path,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="Compactly merge source-code-to-spec handoff patch JSON into durable handoff.json."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    update = subparsers.add_parser("update", help="Create or compact-update one durable handoff.")
+    update.add_argument("--handoff", required=True)
+    update.add_argument("--target-id", required=True)
+    update.add_argument("--scope", required=True)
+    update.add_argument("--patch", required=True)
+    update.set_defaults(func=command_update)
+
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except BrokenPipeError:
+        sys.exit(1)

package/.github/skills/source-code-to-spec-documenter/scripts/spec_queue.py

@@ -16,6 +16,7 @@ else:
     raise SystemExit("Cannot locate source-code-to-spec-tools/scripts/queue_contract.py")
 
 from queue_contract import (
+    BASELINE_STATUSES,
     DOC_STATUSES,
     MAIN_COLUMNS,
     REVIEW_STATUSES,
@@ -25,7 +26,7 @@ from queue_contract import (
 )
 
 
-SUPPORTED_SCOPE_TEXT = "all, foundation, architecture, ops"
+SUPPORTED_SCOPE_TEXT = "baseline, all, foundation, architecture, ops"
 
 
 def split_markdown_row(line):
@@ -59,6 +60,9 @@ def normalize_row(row):
     normalized["doc_profile"] = normalize_doc_profile(
         normalized.get("doc_profile", ""), normalized.get("source_type", "")
     )
+    normalized["baseline_status"] = normalize_status(
+        normalized["baseline_status"], BASELINE_STATUSES, "pending"
+    )
     for field in ("foundation_doc_status", "architecture_doc_status", "ops_doc_status"):
         normalized[field] = normalize_status(normalized[field], DOC_STATUSES, "pending")
     normalized["review_status"] = normalize_status(
@@ -115,6 +119,8 @@ def row_for_id(rows, target_id):
 
 def scope_fields(scope):
     scope = str(scope or "").strip().lower()
+    if scope == "baseline":
+        return ["baseline_status"]
     if scope == "foundation":
         return ["foundation_doc_status"]
     if scope == "architecture":
@@ -126,9 +132,22 @@ def scope_fields(scope):
     raise SystemExit(f"Unsupported scope: {scope}. Supported scopes: {SUPPORTED_SCOPE_TEXT}")
 
 
+def normalize_last_handoff_path(value, target_id):
+    text = str(value or "").strip()
+    expected = f".github/artifacts/source-code-to-spec/{target_id}/handoff.json"
+    if text != expected:
+        raise SystemExit(
+            "Invalid last_handoff path. Expected "
+            f"{expected}; source-code-to-spec handoff is durable-only."
+        )
+    return text
+
+
 def is_selectable(row, scope):
     normalized_scope = str(scope or "").strip().lower()
     scope_fields(normalized_scope)
+    if normalized_scope == "baseline":
+        return row.get("baseline_status") == "pending"
     if normalized_scope == "all":
         return normalize_flag(row.get("document_completed_flag(Y/N)")) == "N"
     for field in scope_fields(normalized_scope):
@@ -142,6 +161,11 @@ def select_row(rows, args):
     target_id = getattr(args, "id", None)
     if target_id:
         return row_for_id(rows, target_id)
+    if str(args.scope or "").strip().lower() == "baseline":
+        for row in rows:
+            if is_selectable(row, args.scope):
+                return row
+        raise SystemExit(f"No selectable target row found for scope={args.scope}")
     for row in rows:
         if is_selectable(row, args.scope):
             return row
@@ -157,6 +181,10 @@ def command_select(args):
 def command_update(args):
     path, lines, start, end, rows = read_queue(args.queue)
     row = row_for_id(rows, args.id)
+    if args.baseline is not None:
+        row["baseline_status"] = normalize_status(
+            args.baseline, BASELINE_STATUSES, row["baseline_status"]
+        )
     for argument_name, field_name in (
         ("foundation", "foundation_doc_status"),
         ("architecture", "architecture_doc_status"),
@@ -172,7 +200,7 @@ def command_update(args):
     if args.completed is not None:
         row["document_completed_flag(Y/N)"] = normalize_flag(args.completed)
     if args.last_handoff is not None:
-        row["last_handoff"] = args.last_handoff
+        row["last_handoff"] = normalize_last_handoff_path(args.last_handoff, args.id)
     if args.notes is not None:
         row["notes"] = args.notes
     write_queue(path, lines, start, end, rows)
@@ -197,6 +225,7 @@ def build_parser():
     update = subparsers.add_parser("update", help="Update queue status fields for one row.")
     update.add_argument("--queue", required=True)
     update.add_argument("--id", required=True)
+    update.add_argument("--baseline")
     update.add_argument("--foundation")
     update.add_argument("--architecture")
     update.add_argument("--ops")

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

@@ -43,6 +43,15 @@ Queue 欄位順序、supporting table 欄位、status enum、`doc_profile` 規
 
 從 repo root 執行以下 scripts，預設輸出 JSON，方便後續 handoff 或 agent parsing。執行本 skill 的 Python CLI 時使用 `python -B`，避免 smoke / generation run 產生 `__pycache__` 或 `*.pyc` runtime cache。
 
+本 skill 只提供 lookup / schema backbone CLI：`target_query.py`、`catalog_query.py`、`source_lookup.py` 與 `queue_contract.py`。`spec_queue.py` 與 `handoff_update.py` 不在本 skill；queue row selection / status update 與 durable handoff merge 必須使用 `.github/skills/source-code-to-spec-documenter/scripts/` 下的 workflow helper：
+
+```bash
+python -B .github/skills/source-code-to-spec-documenter/scripts/spec_queue.py ...
+python -B .github/skills/source-code-to-spec-documenter/scripts/handoff_update.py ...
+```
+
+不要嘗試執行 `.github/skills/source-code-to-spec-tools/scripts/spec_queue.py` 或 `.github/skills/source-code-to-spec-tools/scripts/handoff_update.py`；這些路徑不是 canonical script location。
+
 ### target_query.py
 
 用途：查詢 `docs/docs-target-queue.md` 的 target row、related rows、preflight context 與 supporting tables。
@@ -78,6 +87,8 @@ python -B .github/skills/source-code-to-spec-tools/scripts/catalog_query.py sear
 - 需要把 catalog table rows 轉給 queue normalization workflow。
 - 需要查 catalog-level coverage gap，不想手動掃 Markdown table。
 
+`catalog_query.py handoff` 查的是 `docs/docs-target-catalog.md` 中的 handoff rows，不查 `docs/docs-target-queue.md` 的 target row id。若要查 `F1`、`J2` 這類 queue row id，使用 `target_query.py preflight --queue docs/docs-target-queue.md --id <target_id>`。
+
 ### source_lookup.py
 
 用途：對 source root 做 bounded handle lookup，回傳 `path`、`line`、`handles`、matched text、可選 context，以及可直接放入 handoff 的 `EvidenceRef`。