handoff

handoff

Invoked with: $ARGUMENTS

解析 $ARGUMENTS

tokens = split $ARGUMENTS by whitespace
mode = first non-flag token（或 default "task" 若空）
flags = tokens starting with "--"

if mode == "task" or empty → Mode A
if mode == "log" → Mode B
if mode == "view" → Mode C
otherwise → 回應「unknown mode: {mode}」並停止

flags 處理：
  --verify （僅 Mode C 有意義；其他 mode 忽略並 warn）

何時使用

Mode	場景	輸出檔
task 或空	一個 task 結束、準備進下一個	.harness/handoff/task-handoff.md（整份取代）
log	一個 session 結束（task 是否完成皆可）	.harness/handoff/progress-log.md（更新 living + append entry）
view	想看當前狀態	無寫檔，summary 到 chat
view --verify	想看當前狀態並驗證 living 命令是否仍跑通	無寫檔，跑命令 + 報告 drift 到 chat

不觸發於：sprint contract 起草 / rubric.md 撰寫 / 對 source code 的 commit-time 操作。

Mode A · task

流程

1. Read .harness/handoff/task-handoff.md（若存在）以了解上輪狀態——僅供 context、非 truth。
2. 蒐集本輪狀態：跑過的測試、git status + git diff --stat、已 commit 的 hash。
3. 用 templates/task-handoff.md 範本填 5 段（含 Shell: 宣告、component_type 標籤、evidence path）。
4. 跑 validator（warn-only）。
5. 寫入 .harness/handoff/task-handoff.md（整份取代）。
6. 回報一行摘要：哪些段標「無」、warn 總數。

First-run

若 .harness/handoff/task-handoff.md 不存在：

• 建立 .harness/handoff/ 目錄
• 無上輪 context 可參考——本輪從零填
• frontmatter task_id 由 user / agent 宣告（對應 .harness/contract/<task_id>/）
• 若 .harness/contract/<task_id>/ 不存在 → warn「task_id 對應的 contract 目錄不存在」

Mode B · log

流程

1. Read .harness/handoff/progress-log.md（若存在）。
2. 更新 living section（檔案頂部 5 欄）。與舊值差異時：在新 log entry 的「Living section 變動」段內明文記錄變動內容與理由。
3. Append 一條 log entry 到檔案底部（8 個欄位，含「Living section 變動」段）。
4. 跑 validator（warn-only）。
5. 寫入 .harness/handoff/progress-log.md。
6. 回報一行摘要：append 第 N 條 entry、living section 哪幾欄變動。

First-run

若 .harness/handoff/progress-log.md 不存在：

• 建立 .harness/handoff/ 目錄
• 自動偵測 living section 初值：
  • repo_root: git rev-parse --show-toplevel；失敗則用 pwd
  • default_shell: 偵測 OS / shell（Windows + git-bash in PATH → "bash"；純 PowerShell → "powershell"；macOS/Linux → "bash"；偵測失敗 → 留空 + warn）
  • 其他四欄留空 + warn「請於本輪填入」
• Append 第一條 entry，「Living section 變動」段填「初始化 living section」
• 報告：「First-run：建立 .harness/handoff/progress-log.md，living section 已偵測 repo_root 與 default_shell；請於本輪填入啟動 / 驗證指令」

Mode C · view

流程

1. Read .harness/handoff/task-handoff.md + .harness/handoff/progress-log.md。
2. Summary 到 chat：task-handoff 全部段 + progress-log living section 全部 + progress-log 最近 N=3 條 entry。
3. 不寫檔。

--verify flag

額外執行：

1. 從 progress-log living section 抽 default_shell（frontmatter）+「標準啟動路徑」+「標準驗證路徑」
2. 用對應 shell 跑這兩條命令
3. 比對 output 與 living section claim
4. 報告 drift：命令 fail（exit 非 0）→「verify failed: exit ; output: ...」；output 與描述顯著不一致 →「possible drift: living says X, actual shows Y」
5. 不採取任何修補動作；agent / user 看到後自行決定下一步。

驗證原則（warn-only · 不阻塞寫入）

規則	warn 觸發條件
段非空	段標題下無內容 → 「段空白：填內容或明寫『無』」
無 padding	偵測 "TBD" / "暫無，待補充" / "依需要" / "待確認" / "繼續推進" → warn
Shell 宣告	命令段缺 **Shell**: 行或 code fence 缺 language → warn
Shell-syntax 一致	宣告 bash 但命令出現 $env: / Get-ChildItem style → warn；宣告 powershell 但出現 export VAR= / /dev/null → warn
命令可貼	命令段是純散文無 code block → warn
component_type	「仍損壞」/「已知風險」段內每條缺 component_type 標籤 → warn（enum 見 references/component-enum.md）
Evidence path 格式	含 : 在第二位或開頭 / → warn「path 應相對 repo root」
Evidence file 存在	path 寫了但檔案不存在 → warn
Don't touch path 存在	path 不是現存 file / dir → warn
Don't touch reason	: 後為空白或單字、或含 padding → warn
Living section 變動 audit	living 改了但「Living section 變動」段空白或未提及變動欄位 → warn
last_updated 新鮮度	living section last_updated 超過 7 天 → warn
schema_version	缺 schema_version → warn
last_writer 必填	last_writer 欄位空白 → warn
task_id 對應 contract	task-handoff 的 task_id 對應 .harness/contract/<task_id>/ 目錄不存在 → warn

驗證後續處置由 agent 決定——本 skill 不強制阻塞、不自動修補。

寫入限制（hard constraints）

只寫：

• .harness/handoff/task-handoff.md
• .harness/handoff/progress-log.md

絕不寫：sprint contract / rubric.md / scripts/ / agents/ / source code / .harness/contract/* / .harness/evidence/*。

絕不刪 progress-log.md 的歷史 entry（append-only）。

若 .harness/handoff/ 目錄不存在，建立它。

Memory-as-hint 提醒

本 skill 產出的 artifact 是 hint，不是 truth。下輪 agent 讀完後：

• 描述性事實（架構、慣例）→ 作 prior 信念使用
• 可驗證事實（命令、檔案位置、API 行為）→ 採取破壞性動作前 verify。Verify 方式：(a) 跑 /handoff view --verify、(b) 手動跑 living section 的命令、(c) grep / read 對應檔案。

Anti-patterns

• ✗ 「本輪改動：暫無重大改動，待後續補充」（padding）
• ✗ 「命令：依照專案文件執行相應的測試」（不可貼）
• ✗ 「下一步最佳動作：繼續推進開發」（無資訊量）
• ✗ Don't touch: src/login.svelte: 不要動（reason 過短、無因果）
• ✗ Shell 宣告 bash 但命令出現 $env:VAR=...
• ✓ 「本輪改動：無」
• ✓ 「命令」段含 **Shell**: bash + bash code fence + pytest tests/test_login.py -v
• ✓ 「下一步最佳動作：修 D-001 的 CJK 垂直渲染（src/login.svelte:42）；不要動 src/router.svelte 直到 D-003 確認」

引用檔案

• Template：templates/task-handoff.md、templates/progress-log.md
• Reference：references/component-enum.md（不確定 component_type 該選哪個時必讀）