Files

T

jiantw83 77e7504982 docs(sdlc): 參考文件與 README 同步階梯、工作包隔離與日誌粒度

What：`references/branch.md` 新增「分支階梯與 base 推導」一節（只寫拿到 `jsc-git/tools/base-branch.sh --derive` 回應之後要做什麼）與「工作包隔離」一節（歸屬依據、狀態檔欄位、誰寫誰讀、查無歸屬放行、逃生門），閘門分工那一表補上 `claim`、`lock`、`owns`。`references/stage-report.md` 改寫暫存那一節，講明本節只適用於「還沒完成任何任務就停下」的階段。README 的工具表、`implement` 與 `maintain` 兩段說明、參考文件表與相依技能清單同步更新。

Why：階梯表與歸屬狀態檔的正本各有其處——階梯在 `jsc-meta` 的 `references/guidelines.md`，狀態檔格式在 `jsc-hooks`。抄第二份就會有兩份互相打架的規則，但完全不提又會讓實作階段不知道拿到 `7` 或「已建立功能主幹」時該做什麼。

How：兩節都只寫本階段要做的事，並把唯一來源用連結指出去。`branch.md` 的階梯那一節寫成一張「腳本回應 → 這個階段要做的事」對照表，`7` 明寫成「中止並問使用者，不退回 `develop`」。`stage-report.md` 補一句「暫存不等於已寫入」，因為日誌改成一個任務一筆之後，做完事情的階段本來就有日誌可連。

Who：讀 `jsc-sdlc` 參考文件與 README 的人，以及跑實作與維護兩階段的工作階段。

2026-08-27 11:20:30 +08:00

3.3 KiB

Raw Blame History

階段回報 — 四個階段收尾都要交的東西

規劃、分析、實作、維護跑完，最後一件事一定是階段回報。彙整由 tools/stage-report.sh 產出，技能只負責把事實餵進去：寫過哪些 wiki 頁、有沒有寫工作日誌、實作階段的工作目錄與三條分支。

什麼時候回報

階段結束就回報，提前停下來也算結束：模型閘門擋下、工作包閘門擋下、沒有可選的計畫或工作包、來源分支在遠端找不到——這些情況一樣要回報，而且更需要。停在半路卻沒有回報，看起來就跟沒跑過一樣。

每個階段都要回報的三項

項目	來源	沒有時怎麼辦
模型能力標籤	`jsc-hooks/hooks/sdlc-gate.sh report`，腳本自己讀	回報「查不到閘門狀態」，並要求重跑 `lock {stage}`
工作日誌連結	`--worklog` 給頁名、`--worklog-heading` 給條目標題，組成導向該條目的錨點連結	警告使用者檢查，並把內容暫存（見下節）
所有寫入的 wiki 連結	每寫一頁就記一筆，收尾時用 `--page TYPE:PAGE` 全部餵進去	沒寫任何頁就據實回報「本階段沒有寫入任何 wiki 頁」

--page 的 TYPE 是頁名前綴（PLAN、ANALYZE、DELIVER、REPO、MAINTAIN、LOG）。腳本用它解析該類型的 wiki 存取庫，再換成絕對網址，所以跨存取庫的頁面也連得到。目錄頁（*_CONTENTS）也算寫入，要列。

實作階段多回報四項

項目	選項	腳本自己查的部分
工作目錄	`--worktree PATH`	無，原樣列出
來源分支	`--source-branch NAME`	遠端有沒有這一條。遠端找不到就標「只有本機」
工作分支	`--work-branch NAME`	相對來源分支的 commit 數、推送狀態（未 push、或還有幾個 commit 沒 push）
目標分支	`--target-branch NAME`、`--pr URL`	省略目標分支時等同來源分支；沒有 PR 連結就列為警告

沒寫工作日誌就暫存

每完成一個任務就要寫一筆工作日誌（一個工作包、一輪 PR 留言修正、一個獨立的修正提交各算一個），所以做完事情的階段收尾時本來就有日誌可連。本節講的是還沒完成任何任務就停下的那種階段。

暫存不等於已寫入。內容只留在對話裡，換一個工作階段就沒了，所以：

把這個階段要記的日誌內容寫成一個檔案。
收尾時一起餵進去：--pending-file {檔案} --log-hash {LOG_{HASH} 的 HASH}。
腳本轉呼叫 jsc-log/tools/worklog-pending.sh add，把內容存進 $JSC_HOME/worklog-pending/{HASH}/，並在回報裡印出存放路徑。
下次 jsc-log:worklog 寫入時，會先把暫存區的內容一併寫進日誌頁，寫成功才清掉暫存。

{HASH} 用 jsc-gitea/tools/hash-id 對程式碼存取庫的 {owner}/{repo} 算出來，和 LOG_{HASH} 同一個值。

結束碼

碼	意思	呼叫端要做的事
0	回報完整	把輸出原樣貼給使用者
1	有警告（缺工作日誌、或實作階段沒有 PR）	一樣把輸出貼給使用者。這是警告不是阻擋，階段的工作已經做完了
2	用法錯誤	修正參數重跑
3	找不到 `gitea.sh` 或 `sdlc-gate.sh`	修好相依關係再重跑

3.3 KiB Raw Blame History Unescape Escape