feat(狀態回報): 收尾寫一筆 skill-end 事件
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就 中止的技能，在紀錄裡長得一模一樣。 start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾 步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在 原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。 status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜 跳過，回報失敗一律不改變技能自己的結論。
This commit is contained in:
+16
-16
@@ -7,37 +7,37 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 計畫已經寫進 `PLAN_CONTENTS`（CONTENTS 存取庫）、狀態是「未分析」，要把它拆成工作包時用。也用於延伸既有的 `ANALYZE_{HASH}` 分析頁。要寫程式碼時不用，那是 `implement`。`PLAN_CONTENTS` 還沒有計畫時不用，先跑 `plan`。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock analyze` 過模型閘門，本階段要 `reasoning-max` 標籤、用 `gitea.sh wiki-repo CONTENTS` 解出目錄頁存取庫，並行讀 `PLAN_CONTENTS` 與 `ANALYZE_CONTENTS`、讓使用者選延伸既有分析或分析新計畫、跑 `git fetch --prune origin` 後確認來源分支，並核對 HEAD 與 `origin/{source-branch}` 指到同一個 commit，有落差就停下回報、逐則使用者故事問到共識、先查 `REPO_{HASH}` 盤點頁（雜湊取自該存取庫自己的 `{owner}/{repo}`）決定複用，資料過期就開 sub agent 重新盤點，把 `REPO_{HASH}` 寫回 REPO 存取庫、`REPO_CONTENTS` 用 `wiki-contents.sh upsert REPO 1 {owner}/{repo}` 寫回、做 WBS 拆工作包並標相依，交付工作包固定編為 `WP-01` 且獨立不併入實作包、用 CPM 估工時與天數，標出要徑並依 `references/cpm-chart.md` 畫 mermaid 甘特圖、寫使用者故事驗收計畫，再逐包寫 TDD 待辦、一次寫入 `ANALYZE_{HASH}`（ANALYZE 存取庫），再用 `wiki-contents.sh upsert ANALYZE 3 {HASH}` 與 `wiki-contents.sh upsert PLAN 4 {HASH}` 各自單列 upsert、目錄列的分析頁與盤點頁連結一律取自 `gitea.sh wiki-url` 的絕對網址，並依退出碼分流（`0` 用它印出的網址，`4` 回頭補寫那頁再回來，`5`、`7`、`8` 停下回報，一律不自行組網址、也不留空白連結）、每個要放進頁面或目錄列的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整筆不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、目錄列檔與待寫日誌檔一律用 Bash 的 heredoc 或 `mktemp` 產在暫存目錄，不走 Write 或 Edit 工具，因為 `write-guard.sh` 的 stage 模式只看階段鎖不看路徑，走工具會被自己的閘門擋下、跑 `tools/stage-report.sh analyze` 收尾回報，目錄頁一律用 `--page CONTENTS:{頁名}`。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`jsc-hooks/hooks/write-guard.sh`（claude 的 `PreToolUse` 擋寫入）、`jsc-gitea:wiki`、`jsc-gitea/tools/hash-id`、`jsc-gitea/tools/gitea.sh` 的 `wiki-repo` 與 `wiki-url`、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-ask:ask`、`tools/stage-report.sh`、`git fetch --prune origin`、`git branch -r`、`git rev-list --left-right --count`。 |
|
||||
| 完成條件 | 模型閘門退出 0 並回報實際模型 id、來源分支經使用者確認且與遠端一致、每則使用者故事達成共識、每個複用決策連理由記進「複用決策」欄、每則故事對應至少一個編號工作包、每包有工時與天數、要徑與甘特圖齊備、每個實作包至少一則測試先行的 `[ ]` 待辦、`ANALYZE_{HASH}` 存進 wiki 且未決項欄有值（沒有就寫「無」）、每個目錄列的頁面連結都來自退出 0 的 `wiki-url`，非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼、每一頁與每一列寫出去之前都經 `link-check.sh` 退出 0 驗過，連結格式一律是 `[{文字}]({連結})`、每次目錄頁寫入都講出 `wiki-contents.sh` 的退出碼並依碼分流（`0` 續行，`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、`stage-report.sh` 的輸出原樣貼給使用者。提前停下也要跑收尾回報。 |
|
||||
| 可驗證跡象 | ANALYZE 存取庫多一頁或更新一頁 `ANALYZE_{HASH}`；CONTENTS 存取庫的 `ANALYZE_CONTENTS` 多一列該分析，連結是絕對網址；`PLAN_CONTENTS` 該計畫那列狀態變成「已分析」；重新盤點時 REPO 存取庫多一頁 `REPO_{HASH}`，`REPO_CONTENTS` 多一列；`$JSC_HOME/sessions/{工作階段 id}.stage` 是 `sdlc-gate.sh lock` 寫的階段鎖狀態檔；還沒有工作日誌時，`$JSC_HOME/worklog-pending/{HASH}/` 下有暫存的日誌內容檔；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，頁面上找不到 `[[...]]` 寫法的連結。工作目錄的檔案一律不動，程式碼沒有任何改動。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock analyze` 過模型閘門，本階段要 `reasoning-max` 標籤、用 `gitea.sh wiki-repo CONTENTS` 解出目錄頁存取庫，並行讀 `PLAN_CONTENTS` 與 `ANALYZE_CONTENTS`、讓使用者選延伸既有分析或分析新計畫、跑 `git fetch --prune origin` 後確認來源分支，並核對 HEAD 與 `origin/{source-branch}` 指到同一個 commit，有落差就停下回報、逐則使用者故事問到共識、先查 `REPO_{HASH}` 盤點頁（雜湊取自該存取庫自己的 `{owner}/{repo}`）決定複用，資料過期就開 sub agent 重新盤點，把 `REPO_{HASH}` 寫回 REPO 存取庫、`REPO_CONTENTS` 用 `wiki-contents.sh upsert REPO 1 {owner}/{repo}` 寫回、做 WBS 拆工作包並標相依，交付工作包固定編為 `WP-01` 且獨立不併入實作包、用 CPM 估工時與天數，標出要徑並依 `references/cpm-chart.md` 畫 mermaid 甘特圖、寫使用者故事驗收計畫，再逐包寫 TDD 待辦、一次寫入 `ANALYZE_{HASH}`（ANALYZE 存取庫），再用 `wiki-contents.sh upsert ANALYZE 3 {HASH}` 與 `wiki-contents.sh upsert PLAN 4 {HASH}` 各自單列 upsert、目錄列的分析頁與盤點頁連結一律取自 `gitea.sh wiki-url` 的絕對網址，並依退出碼分流（`0` 用它印出的網址，`4` 回頭補寫那頁再回來，`5`、`7`、`8` 停下回報，一律不自行組網址、也不留空白連結）、每個要放進頁面或目錄列的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整筆不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、目錄列檔與待寫日誌檔一律用 Bash 的 heredoc 或 `mktemp` 產在暫存目錄，不走 Write 或 Edit 工具，因為 `write-guard.sh` 的 stage 模式只看階段鎖不看路徑，走工具會被自己的閘門擋下、跑 `tools/stage-report.sh analyze` 收尾回報，目錄頁一律用 `--page CONTENTS:{頁名}`、階段回報之後緊接著跑 `jsc-hooks/tools/report-status.sh skill-end jsc-sdlc:analyze {status} {結束碼} [detail]` 寫一筆結束事件，模型閘門擋下或 HEAD 與 `origin/{source-branch}` 有落差填 `blocked`，分析頁寫成功但目錄列沒跟上填 `degraded`，找不到腳本就安靜跳過，這一步失敗不改變本次階段的結論。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`jsc-hooks/hooks/write-guard.sh`（claude 的 `PreToolUse` 擋寫入）、`jsc-gitea:wiki`、`jsc-gitea/tools/hash-id`、`jsc-gitea/tools/gitea.sh` 的 `wiki-repo` 與 `wiki-url`、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-ask:ask`、`tools/stage-report.sh`、`jsc-hooks/tools/report-status.sh skill-end`、`git fetch --prune origin`、`git branch -r`、`git rev-list --left-right --count`。 |
|
||||
| 完成條件 | 模型閘門退出 0 並回報實際模型 id、來源分支經使用者確認且與遠端一致、每則使用者故事達成共識、每個複用決策連理由記進「複用決策」欄、每則故事對應至少一個編號工作包、每包有工時與天數、要徑與甘特圖齊備、每個實作包至少一則測試先行的 `[ ]` 待辦、`ANALYZE_{HASH}` 存進 wiki 且未決項欄有值（沒有就寫「無」）、每個目錄列的頁面連結都來自退出 0 的 `wiki-url`，非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼、每一頁與每一列寫出去之前都經 `link-check.sh` 退出 0 驗過，連結格式一律是 `[{文字}]({連結})`、每次目錄頁寫入都講出 `wiki-contents.sh` 的退出碼並依碼分流（`0` 續行，`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、`stage-report.sh` 的輸出原樣貼給使用者、已寫一筆 `skill-end` 事件，狀態照 SKILL.md 收尾步驟那張對應表選定。提前停下也要跑收尾回報，結束事件一樣要寫；只有找不到 `report-status.sh` 才准沒有這一筆。 |
|
||||
| 可驗證跡象 | ANALYZE 存取庫多一頁或更新一頁 `ANALYZE_{HASH}`；CONTENTS 存取庫的 `ANALYZE_CONTENTS` 多一列該分析，連結是絕對網址；`PLAN_CONTENTS` 該計畫那列狀態變成「已分析」；重新盤點時 REPO 存取庫多一頁 `REPO_{HASH}`，`REPO_CONTENTS` 多一列；`$JSC_HOME/sessions/{工作階段 id}.stage` 是 `sdlc-gate.sh lock` 寫的階段鎖狀態檔；還沒有工作日誌時，`$JSC_HOME/worklog-pending/{HASH}/` 下有暫存的日誌內容檔；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，頁面上找不到 `[[...]]` 寫法的連結；`$JSC_HOME/usage/events.jsonl` 多一筆 `{kind:skill,phase:end}` 的事件，`name` 是 `jsc-sdlc:analyze`，`status` 是五個值之一。工作目錄的檔案一律不動，程式碼沒有任何改動。 |
|
||||
|
||||
## implement
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 分析頁已經有工作包與 TDD 待辦，要動手寫程式碼時用。也用於回頭處理既有工作包 PR 的留言。規劃或分析階段不用。`ANALYZE_CONTENTS` 沒有未完成分析頁時不用。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock implement` 過模型閘門，本階段要 `coding` 標籤、從 CONTENTS 存取庫讀 `ANALYZE_CONTENTS`、從 ANALYZE 存取庫讀每一頁未完成分析頁，這份資料後續步驟重用不再讀第二次、對每支未合併 PR 並行跑 `wp-gate.sh check` 取狀態與留言、動任何 PR 之前先跑 `wp-gate.sh owns` 確認歸屬，`foreign` 就放手、每則留言先經 `jsc-ask:ask` 取得共識，再由 sub agent 在同一個 worktree 內修、推同一條工作分支、逐則留言用 `gitea.sh comment-reply` 回覆處置結果，把 `latest=` 時間寫回分析頁 PR 欄、一輪留言修正算一個任務，當下寫一筆 `jsc-log:worklog`、列出可挑的工作包，每個候選並行跑 `wp-gate.sh check-deps` 過相依閘門，只有 `ready` 進選項、使用者挑定後跑 `wp-gate.sh claim` 登錄歸屬、確認來源分支，它同時是 worktree 基準與 PR 目標，遠端找不到就停下回報、產生 `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}` 工作證並寫回分析頁「工作證」欄，同時改工作階段名稱、交付包先問交付內容型別並寫回「交付型別」欄、`git fetch --prune origin` 後從 `origin/{source-branch}` 建 worktree，多存取庫並行建、逐項待辦各開一個 sub agent 跑 TDD，主代理每完成一項就把 `[ ]` 翻成 `[x]` 並存回 wiki、收尾並行跑 `jsc-review:code-review` 與 `jsc-review:api-doc`，後者先用 `swagger-detect.sh` 判定，退出碼 1 就明確略過並回報、跑 `jsc-git:pr` 開 PR 回來源分支，把 PR 連結寫回分析頁，再跑 `wp-gate.sh lock` 上鎖、寫一筆工作日誌，接著用 `pr-watch.sh` 輪詢等合併，退出碼 10 就回頭跑同一套留言處理、合併後移除 worktree 並把工作包標為完成、問交付格式並產出 `DELIVER_{HASH}` wiki 頁（寫進 DELIVER 存取庫，雜湊取自 `{owner}/{repo}` 加工作包編號，一包一頁不互相覆蓋）或 Gitea issue 留言，交付頁再用 `wiki-contents.sh upsert DELIVER 6 {HASH}` 把 `DELIVER_CONTENTS` 那一列寫回，連結取自 `gitea.sh wiki-url` 的絕對網址並依退出碼分流（`0` 用它印出的網址，`4` 回頭補寫交付頁再回來，`5`、`7`、`8` 停下回報，一律不自行組網址、也不留空白連結）、每個要放進頁面、目錄列、PR 欄或 issue 留言的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整筆不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、問要不要登錄維護並用 `wiki-contents.sh upsert MAINTAIN 1 {owner}/{repo}` 寫回 `MAINTAIN_CONTENTS`、跑 `tools/stage-report.sh implement` 收尾回報，目錄頁一律用 `--page CONTENTS:{頁名}`。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`tools/wp-gate.sh` 的 `check`、`check-deps`、`claim`、`lock`、`owns`、`tools/stage-report.sh`、`jsc-gitea:wiki`、`jsc-gitea/tools/hash-id`、`jsc-gitea/tools/gitea.sh`（`wiki-repo`、`wiki-url`、`comment-reply` 與 issue 留言 API）、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-gitea/tools/pr-watch.sh`、`jsc-ask:ask`、`jsc-review:code-review`、`jsc-review:api-doc`、`jsc-review/tools/swagger-detect.sh`、`jsc-hooks/hooks/comment-scope.sh`、`jsc-git:commit`、`jsc-git:pr`、`jsc-log:worklog`、`git fetch`、`git worktree`。 |
|
||||
| 完成條件 | 模型閘門退出 0、每支未合併 PR 的留言都有處置與回覆、挑中的工作包經 `check-deps` 判為 `ready` 並 `claim` 成功、來源分支經確認並記進分析頁、工作證寫上 wiki、該包每一項待辦在 wiki 上都是 `[x]`、兩個收尾稽核都放行（`api-doc` 回報略過也算放行）、PR 開好且 `wp-gate.sh lock` 回 `status=locked`、工作日誌已寫、`pr-watch.sh` 退出 0 且 `wp-gate.sh check` 回 `status=merged`、交付文件已產出、交付頁那列的連結來自退出 0 的 `wiki-url`，非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼、每一頁、每一列與每一則 issue 留言寫出去之前都經 `link-check.sh` 退出 0 驗過，連結格式一律是 `[{文字}]({連結})`、維護登錄問題已回答、每次目錄頁寫入都講出 `wiki-contents.sh` 的退出碼並依碼分流（`0` 續行，`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、`stage-report.sh` 的輸出原樣貼出並列出 worktree 與三條分支。提前停下也要跑收尾回報。 |
|
||||
| 可驗證跡象 | 開出一條工作分支，並有一支回到來源分支的 PR；ANALYZE 存取庫的分析頁 `ANALYZE_{HASH}` 的「工作證」欄（值是 `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}`，帶著 `hash-id` 原樣印出的雜湊）、「交付型別」欄、PR 欄、待辦勾選狀態都更新過；DELIVER 存取庫多一頁 `DELIVER_{HASH}`，或該 issue 下多一則留言；CONTENTS 存取庫的 `DELIVER_CONTENTS` 多一列，連結是絕對網址；使用者同意登錄時 `MAINTAIN_CONTENTS` 多一列；`LOG_{HASH}` 每完成一個任務多一筆條目；`$JSC_HOME/wp/{owner}-{repo}.claim` 與 `$JSC_HOME/wp/{owner}-{repo}-{index}.pr` 兩個狀態檔；`{cwd}/.worktree/{分析-HASH}/{工作包編號}/{repo}` 目錄，PR 合併後被移除；該存取庫 `.git/info/exclude` 多一筆 `.worktree/`；PR 每則留言底下有回覆；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，寫出去的頁面與留言都找不到 `[[...]]` 寫法的連結。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock implement` 過模型閘門，本階段要 `coding` 標籤、從 CONTENTS 存取庫讀 `ANALYZE_CONTENTS`、從 ANALYZE 存取庫讀每一頁未完成分析頁，這份資料後續步驟重用不再讀第二次、對每支未合併 PR 並行跑 `wp-gate.sh check` 取狀態與留言、動任何 PR 之前先跑 `wp-gate.sh owns` 確認歸屬，`foreign` 就放手、每則留言先經 `jsc-ask:ask` 取得共識，再由 sub agent 在同一個 worktree 內修、推同一條工作分支、逐則留言用 `gitea.sh comment-reply` 回覆處置結果，把 `latest=` 時間寫回分析頁 PR 欄、一輪留言修正算一個任務，當下寫一筆 `jsc-log:worklog`、列出可挑的工作包，每個候選並行跑 `wp-gate.sh check-deps` 過相依閘門，只有 `ready` 進選項、使用者挑定後跑 `wp-gate.sh claim` 登錄歸屬、確認來源分支，它同時是 worktree 基準與 PR 目標，遠端找不到就停下回報、產生 `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}` 工作證並寫回分析頁「工作證」欄，同時改工作階段名稱、交付包先問交付內容型別並寫回「交付型別」欄、`git fetch --prune origin` 後從 `origin/{source-branch}` 建 worktree，多存取庫並行建、逐項待辦各開一個 sub agent 跑 TDD，主代理每完成一項就把 `[ ]` 翻成 `[x]` 並存回 wiki、收尾並行跑 `jsc-review:code-review` 與 `jsc-review:api-doc`，後者先用 `swagger-detect.sh` 判定，退出碼 1 就明確略過並回報、跑 `jsc-git:pr` 開 PR 回來源分支，把 PR 連結寫回分析頁，再跑 `wp-gate.sh lock` 上鎖、寫一筆工作日誌，接著用 `pr-watch.sh` 輪詢等合併，退出碼 10 就回頭跑同一套留言處理、合併後移除 worktree 並把工作包標為完成、問交付格式並產出 `DELIVER_{HASH}` wiki 頁（寫進 DELIVER 存取庫，雜湊取自 `{owner}/{repo}` 加工作包編號，一包一頁不互相覆蓋）或 Gitea issue 留言，交付頁再用 `wiki-contents.sh upsert DELIVER 6 {HASH}` 把 `DELIVER_CONTENTS` 那一列寫回，連結取自 `gitea.sh wiki-url` 的絕對網址並依退出碼分流（`0` 用它印出的網址，`4` 回頭補寫交付頁再回來，`5`、`7`、`8` 停下回報，一律不自行組網址、也不留空白連結）、每個要放進頁面、目錄列、PR 欄或 issue 留言的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整筆不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、問要不要登錄維護並用 `wiki-contents.sh upsert MAINTAIN 1 {owner}/{repo}` 寫回 `MAINTAIN_CONTENTS`、跑 `tools/stage-report.sh implement` 收尾回報，目錄頁一律用 `--page CONTENTS:{頁名}`、階段回報之後緊接著跑 `jsc-hooks/tools/report-status.sh skill-end jsc-sdlc:implement {status} {結束碼} [detail]` 寫一筆結束事件，模型閘門擋下、候選全被 `check-deps` 判 `blocked`、`owns` 判 `foreign` 或來源分支在遠端找不到都填 `blocked`，工作包已合併但交付目錄列或維護登錄沒寫成填 `degraded`，找不到腳本就安靜跳過，這一步失敗不改變本次階段的結論。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`tools/wp-gate.sh` 的 `check`、`check-deps`、`claim`、`lock`、`owns`、`tools/stage-report.sh`、`jsc-gitea:wiki`、`jsc-gitea/tools/hash-id`、`jsc-gitea/tools/gitea.sh`（`wiki-repo`、`wiki-url`、`comment-reply` 與 issue 留言 API）、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-gitea/tools/pr-watch.sh`、`jsc-ask:ask`、`jsc-review:code-review`、`jsc-review:api-doc`、`jsc-review/tools/swagger-detect.sh`、`jsc-hooks/hooks/comment-scope.sh`、`jsc-git:commit`、`jsc-git:pr`、`jsc-log:worklog`、`jsc-hooks/tools/report-status.sh skill-end`、`git fetch`、`git worktree`。 |
|
||||
| 完成條件 | 模型閘門退出 0、每支未合併 PR 的留言都有處置與回覆、挑中的工作包經 `check-deps` 判為 `ready` 並 `claim` 成功、來源分支經確認並記進分析頁、工作證寫上 wiki、該包每一項待辦在 wiki 上都是 `[x]`、兩個收尾稽核都放行（`api-doc` 回報略過也算放行）、PR 開好且 `wp-gate.sh lock` 回 `status=locked`、工作日誌已寫、`pr-watch.sh` 退出 0 且 `wp-gate.sh check` 回 `status=merged`、交付文件已產出、交付頁那列的連結來自退出 0 的 `wiki-url`，非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼、每一頁、每一列與每一則 issue 留言寫出去之前都經 `link-check.sh` 退出 0 驗過，連結格式一律是 `[{文字}]({連結})`、維護登錄問題已回答、每次目錄頁寫入都講出 `wiki-contents.sh` 的退出碼並依碼分流（`0` 續行，`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、`stage-report.sh` 的輸出原樣貼出並列出 worktree 與三條分支、已寫一筆 `skill-end` 事件，狀態照 SKILL.md 收尾步驟那張對應表選定。提前停下也要跑收尾回報，結束事件一樣要寫；只有找不到 `report-status.sh` 才准沒有這一筆。 |
|
||||
| 可驗證跡象 | 開出一條工作分支，並有一支回到來源分支的 PR；ANALYZE 存取庫的分析頁 `ANALYZE_{HASH}` 的「工作證」欄（值是 `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}`，帶著 `hash-id` 原樣印出的雜湊）、「交付型別」欄、PR 欄、待辦勾選狀態都更新過；DELIVER 存取庫多一頁 `DELIVER_{HASH}`，或該 issue 下多一則留言；CONTENTS 存取庫的 `DELIVER_CONTENTS` 多一列，連結是絕對網址；使用者同意登錄時 `MAINTAIN_CONTENTS` 多一列；`LOG_{HASH}` 每完成一個任務多一筆條目；`$JSC_HOME/wp/{owner}-{repo}.claim` 與 `$JSC_HOME/wp/{owner}-{repo}-{index}.pr` 兩個狀態檔；`{cwd}/.worktree/{分析-HASH}/{工作包編號}/{repo}` 目錄，PR 合併後被移除；該存取庫 `.git/info/exclude` 多一筆 `.worktree/`；PR 每則留言底下有回覆；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，寫出去的頁面與留言都找不到 `[[...]]` 寫法的連結；`$JSC_HOME/usage/events.jsonl` 多一筆 `{kind:skill,phase:end}` 的事件，`name` 是 `jsc-sdlc:implement`，`status` 是五個值之一。 |
|
||||
|
||||
## maintain
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 已交付、且已登錄在 `MAINTAIN_CONTENTS`（CONTENTS 存取庫）的專案要做定期保養時用。還在實作中的專案不用。沒有登錄進 `MAINTAIN_CONTENTS` 的專案不用。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock maintain` 過模型閘門，本階段不要求特定標籤，只要判定得出實際模型 id、用 `gitea.sh wiki-repo CONTENTS` 解出存取庫後讀 `MAINTAIN_CONTENTS`（`MAINTAIN` 只有目錄頁、沒有內容頁），篩出還在維護期內的專案（起始日不晚於今天，結束日為空或不早於今天）、主代理先並行對每個專案跑 `git fetch --prune origin`，切到維護分支並與 `origin/{branch}` 對齊，有落差就回報並略過該專案、之後一個專案一個專案跑，每個專案的維護都開一個 sub agent、每個專案提出至少五項維護做法給使用者挑、把改動用 `jsc-git:commit` 提交到新分支，推送後用 `jsc-git:pr` 開 PR 回步驟 3.1 那條分支、PR 開好當下寫一筆 `jsc-log:worklog`、用 `wiki-contents.sh upsert MAINTAIN 1 {owner}/{repo}` 把該專案在 `MAINTAIN_CONTENTS` 的「前次維護時間」更新成今天，其餘欄位原樣保留、該頁指向別型別頁的連結一律取自 `gitea.sh wiki-url` 的絕對網址並依退出碼分流（`0` 用它印出的網址，`4` 填「無」或回頭補寫那頁，`5`、`7`、`8` 停下回報，`7` 絕不當成 `4` 填「無」，一律不自行組網址、也不留空白連結）、每個要放進該列的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整列不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、主代理彙整每個專案的做法、PR 表格列與失敗原因、跑 `tools/stage-report.sh maintain` 收尾回報，目錄頁用 `--page CONTENTS:MAINTAIN_CONTENTS`。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`jsc-gitea:wiki`、`jsc-gitea/tools/gitea.sh` 的 `wiki-repo` 與 `wiki-url`、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-ask:ask`、`jsc-git:commit`、`jsc-git:pr`、`jsc-log:worklog`、`jsc-pkg:pkg-update`（選了套件更新才用）、`jsc-hooks/hooks/comment-scope.sh`、`tools/stage-report.sh`、`git fetch --prune origin`。 |
|
||||
| 完成條件 | 模型閘門退出 0、步驟 2 列出的每個在期專案都跑完自己的 sub agent，各自收在一條 PR 連結或一個記錄下來的略過原因、每個完成的專案都有一筆工作日誌，而且下一個專案開始前就存好、`wiki-contents.sh` 退出 0 且退出碼有講出來（`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、每個跨型別連結都來自退出 0 的 `wiki-url`，非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼、每一列寫回去之前都經 `link-check.sh` 退出 0 驗過，連結格式一律是 `[{文字}]({連結})`、`MAINTAIN_CONTENTS` 該專案的「前次維護時間」是今天，其他專案那幾列一個位元組都沒變、彙整報告涵蓋每個專案、`stage-report.sh` 的輸出原樣貼給使用者。沒有專案在期時，一樣要跑收尾回報。 |
|
||||
| 可驗證跡象 | 每個維護過的專案多一條新分支與一支回到 `develop` 或 `master` 的 PR；CONTENTS 存取庫的 `MAINTAIN_CONTENTS` 對應那列的「前次維護時間」變成今天；`LOG_{HASH}` 每個完成的專案多一筆條目；`$JSC_HOME/sessions/{工作階段 id}.stage` 是 `sdlc-gate.sh lock` 寫的階段鎖狀態檔；一個專案都沒完成時，`$JSC_HOME/worklog-pending/{HASH}/` 下有暫存的日誌內容檔；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，該頁找不到 `[[...]]` 寫法的連結。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock maintain` 過模型閘門，本階段不要求特定標籤，只要判定得出實際模型 id、用 `gitea.sh wiki-repo CONTENTS` 解出存取庫後讀 `MAINTAIN_CONTENTS`（`MAINTAIN` 只有目錄頁、沒有內容頁），篩出還在維護期內的專案（起始日不晚於今天，結束日為空或不早於今天）、主代理先並行對每個專案跑 `git fetch --prune origin`，切到維護分支並與 `origin/{branch}` 對齊，有落差就回報並略過該專案、之後一個專案一個專案跑，每個專案的維護都開一個 sub agent、每個專案提出至少五項維護做法給使用者挑、把改動用 `jsc-git:commit` 提交到新分支，推送後用 `jsc-git:pr` 開 PR 回步驟 3.1 那條分支、PR 開好當下寫一筆 `jsc-log:worklog`、用 `wiki-contents.sh upsert MAINTAIN 1 {owner}/{repo}` 把該專案在 `MAINTAIN_CONTENTS` 的「前次維護時間」更新成今天，其餘欄位原樣保留、該頁指向別型別頁的連結一律取自 `gitea.sh wiki-url` 的絕對網址並依退出碼分流（`0` 用它印出的網址，`4` 填「無」或回頭補寫那頁，`5`、`7`、`8` 停下回報，`7` 絕不當成 `4` 填「無」，一律不自行組網址、也不留空白連結）、每個要放進該列的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整列不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、主代理彙整每個專案的做法、PR 表格列與失敗原因、跑 `tools/stage-report.sh maintain` 收尾回報，目錄頁用 `--page CONTENTS:MAINTAIN_CONTENTS`、階段回報之後緊接著跑 `jsc-hooks/tools/report-status.sh skill-end jsc-sdlc:maintain {status} {結束碼} [detail]` 寫一筆結束事件，模型閘門擋下或在期專案全部與遠端有落差而整批略過填 `blocked`，一部分專案交出 PR、另一部分略過或「前次維護時間」沒更新成填 `degraded`，找不到腳本就安靜跳過，這一步失敗不改變本次階段的結論。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`jsc-gitea:wiki`、`jsc-gitea/tools/gitea.sh` 的 `wiki-repo` 與 `wiki-url`、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-ask:ask`、`jsc-git:commit`、`jsc-git:pr`、`jsc-log:worklog`、`jsc-pkg:pkg-update`（選了套件更新才用）、`jsc-hooks/hooks/comment-scope.sh`、`tools/stage-report.sh`、`jsc-hooks/tools/report-status.sh skill-end`、`git fetch --prune origin`。 |
|
||||
| 完成條件 | 模型閘門退出 0、步驟 2 列出的每個在期專案都跑完自己的 sub agent，各自收在一條 PR 連結或一個記錄下來的略過原因、每個完成的專案都有一筆工作日誌，而且下一個專案開始前就存好、`wiki-contents.sh` 退出 0 且退出碼有講出來（`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、每個跨型別連結都來自退出 0 的 `wiki-url`，非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼、每一列寫回去之前都經 `link-check.sh` 退出 0 驗過，連結格式一律是 `[{文字}]({連結})`、`MAINTAIN_CONTENTS` 該專案的「前次維護時間」是今天，其他專案那幾列一個位元組都沒變、彙整報告涵蓋每個專案、`stage-report.sh` 的輸出原樣貼給使用者、已寫一筆 `skill-end` 事件，狀態照 SKILL.md 收尾步驟那張對應表選定。沒有專案在期時，一樣要跑收尾回報並寫結束事件，狀態填 `aborted`；只有找不到 `report-status.sh` 才准沒有這一筆。 |
|
||||
| 可驗證跡象 | 每個維護過的專案多一條新分支與一支回到 `develop` 或 `master` 的 PR；CONTENTS 存取庫的 `MAINTAIN_CONTENTS` 對應那列的「前次維護時間」變成今天；`LOG_{HASH}` 每個完成的專案多一筆條目；`$JSC_HOME/sessions/{工作階段 id}.stage` 是 `sdlc-gate.sh lock` 寫的階段鎖狀態檔；一個專案都沒完成時，`$JSC_HOME/worklog-pending/{HASH}/` 下有暫存的日誌內容檔；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，該頁找不到 `[[...]]` 寫法的連結；`$JSC_HOME/usage/events.jsonl` 多一筆 `{kind:skill,phase:end}` 的事件，`name` 是 `jsc-sdlc:maintain`，`status` 是五個值之一。 |
|
||||
|
||||
## plan
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 使用者要開新計畫、或要補強既有計畫時用。做分析或寫程式碼時不用。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock plan` 過模型閘門，本階段要 `reasoning-max` 標籤、用 `gitea.sh wiki-repo CONTENTS` 解出存取庫後讀 `PLAN_CONTENTS`，列出狀態為「未分析」的計畫與各自的 HASH、讓使用者選延伸既有計畫或建立新計畫、依 `references/consensus.md` 跑決策樹，把目標、範圍、可行性三項問到共識，每個答案都要導出下一個問題、把共識寫成「身為⋯⋯我想要⋯⋯以便⋯⋯」格式的使用者故事、套 `templates/plan-page.md` 寫入 `PLAN_{HASH}`（PLAN 存取庫）、用 `wiki-contents.sh upsert PLAN 4 {HASH}` 把這份計畫在 `PLAN_CONTENTS` 的那一列 upsert，狀態填「未分析」、計畫頁連結取自 `gitea.sh wiki-url` 的絕對網址並依退出碼分流（`0` 用它印出的網址，`4` 回頭補寫計畫頁再回來，`5`、`7`、`8` 停下回報，一律不自行組網址、也不留空白連結）、每個要放進頁面或目錄列的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整筆不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、目錄列檔與待寫日誌檔一律用 Bash 的 heredoc 或 `mktemp` 產在暫存目錄，不走 Write 或 Edit 工具，因為 `write-guard.sh` 的 stage 模式只看階段鎖不看路徑，走工具會被自己的閘門擋下、跑 `tools/stage-report.sh plan` 收尾回報，目錄頁用 `--page CONTENTS:PLAN_CONTENTS`。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`jsc-hooks/hooks/write-guard.sh`（claude 的 `PreToolUse` 擋寫入）、`jsc-gitea:wiki`、`jsc-gitea/tools/hash-id`、`jsc-gitea/tools/gitea.sh` 的 `wiki-repo` 與 `wiki-url`、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-ask:ask`、`tools/stage-report.sh`。 |
|
||||
| 完成條件 | 模型閘門退出 0 並回報實際模型 id、目標、範圍、可行性三項都達成共識，而且使用者明確確認過覆述的摘要、每個共識項目至少對應一則使用者故事、`PLAN_{HASH}` 存進 wiki 且範本要求的每個區段都有值、沒有留下未填的佔位字、`PLAN_CONTENTS` 該列狀態是「未分析」，計畫頁那格的連結來自退出 0 的 `wiki-url`（非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼），並經 `link-check.sh` 退出 0 驗過，格式是 `[{文字}]({連結})`，其他列一個位元組都沒變，而且 `wiki-contents.sh` 的退出碼有講出來並依碼分流（`0` 續行，`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、`stage-report.sh` 的輸出原樣貼給使用者。提前停下也要跑收尾回報。 |
|
||||
| 可驗證跡象 | PLAN 存取庫多一頁或更新一頁 `PLAN_{HASH}`；CONTENTS 存取庫的 `PLAN_CONTENTS` 多一列或更新一列，狀態是「未分析」、計畫頁欄位是 `[{文字}]({連結})` 格式的絕對網址；`$JSC_HOME/sessions/{工作階段 id}.stage` 是 `sdlc-gate.sh lock` 寫的階段鎖狀態檔；還沒有工作日誌時，`$JSC_HOME/worklog-pending/{HASH}/` 下有暫存的日誌內容檔；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，頁面上找不到 `[[...]]` 寫法的連結。工作目錄的檔案一律不動。 |
|
||||
| 關鍵步驟 | 跑 `model-tags.sh sync` 與 `sdlc-gate.sh lock plan` 過模型閘門，本階段要 `reasoning-max` 標籤、用 `gitea.sh wiki-repo CONTENTS` 解出存取庫後讀 `PLAN_CONTENTS`，列出狀態為「未分析」的計畫與各自的 HASH、讓使用者選延伸既有計畫或建立新計畫、依 `references/consensus.md` 跑決策樹，把目標、範圍、可行性三項問到共識，每個答案都要導出下一個問題、把共識寫成「身為⋯⋯我想要⋯⋯以便⋯⋯」格式的使用者故事、套 `templates/plan-page.md` 寫入 `PLAN_{HASH}`（PLAN 存取庫）、用 `wiki-contents.sh upsert PLAN 4 {HASH}` 把這份計畫在 `PLAN_CONTENTS` 的那一列 upsert，狀態填「未分析」、計畫頁連結取自 `gitea.sh wiki-url` 的絕對網址並依退出碼分流（`0` 用它印出的網址，`4` 回頭補寫計畫頁再回來，`5`、`7`、`8` 停下回報，一律不自行組網址、也不留空白連結）、每個要放進頁面或目錄列的連結一律寫成 `[{文字}]({連結})`，不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`，而且寫入前先整批交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫，有 DEAD 就整筆不寫並回報連不到的清單（`2` 補參數重跑、`3` 先設好 `GITEA_HOST`、`7` 金鑰失效停下回報，不得當成連不到）、目錄列檔與待寫日誌檔一律用 Bash 的 heredoc 或 `mktemp` 產在暫存目錄，不走 Write 或 Edit 工具，因為 `write-guard.sh` 的 stage 模式只看階段鎖不看路徑，走工具會被自己的閘門擋下、跑 `tools/stage-report.sh plan` 收尾回報，目錄頁用 `--page CONTENTS:PLAN_CONTENTS`、階段回報之後緊接著跑 `jsc-hooks/tools/report-status.sh skill-end jsc-sdlc:plan {status} {結束碼} [detail]` 寫一筆結束事件，模型閘門擋下填 `blocked`，計畫頁寫成功但 `PLAN_CONTENTS` 那列沒跟上填 `degraded`，找不到腳本就安靜跳過，這一步失敗不改變本次階段的結論。 |
|
||||
| 外部呼叫 | `jsc-cli/tools/model-tags.sh sync`、`jsc-hooks/hooks/sdlc-gate.sh lock`、`jsc-hooks/hooks/write-guard.sh`（claude 的 `PreToolUse` 擋寫入）、`jsc-gitea:wiki`、`jsc-gitea/tools/hash-id`、`jsc-gitea/tools/gitea.sh` 的 `wiki-repo` 與 `wiki-url`、`jsc-gitea/tools/wiki-contents.sh upsert`、`jsc-gitea/tools/link-check.sh`、`jsc-ask:ask`、`tools/stage-report.sh`、`jsc-hooks/tools/report-status.sh skill-end`。 |
|
||||
| 完成條件 | 模型閘門退出 0 並回報實際模型 id、目標、範圍、可行性三項都達成共識，而且使用者明確確認過覆述的摘要、每個共識項目至少對應一則使用者故事、`PLAN_{HASH}` 存進 wiki 且範本要求的每個區段都有值、沒有留下未填的佔位字、`PLAN_CONTENTS` 該列狀態是「未分析」，計畫頁那格的連結來自退出 0 的 `wiki-url`（非 0 依 `4`、`5`、`7`、`8` 分流並講出退出碼），並經 `link-check.sh` 退出 0 驗過，格式是 `[{文字}]({連結})`，其他列一個位元組都沒變，而且 `wiki-contents.sh` 的退出碼有講出來並依碼分流（`0` 續行，`1`、`3`、`7`、`8` 停下回報，`2` 修參數重跑，`4` 在本技能一律帶範本的呼叫方式下不會出現，真的出現就確認 plugin 安裝完整後重跑）、`stage-report.sh` 的輸出原樣貼給使用者、已寫一筆 `skill-end` 事件，狀態照 SKILL.md 收尾步驟那張對應表選定。提前停下也要跑收尾回報，結束事件一樣要寫；只有找不到 `report-status.sh` 才准沒有這一筆。 |
|
||||
| 可驗證跡象 | PLAN 存取庫多一頁或更新一頁 `PLAN_{HASH}`；CONTENTS 存取庫的 `PLAN_CONTENTS` 多一列或更新一列，狀態是「未分析」、計畫頁欄位是 `[{文字}]({連結})` 格式的絕對網址；`$JSC_HOME/sessions/{工作階段 id}.stage` 是 `sdlc-gate.sh lock` 寫的階段鎖狀態檔；還沒有工作日誌時，`$JSC_HOME/worklog-pending/{HASH}/` 下有暫存的日誌內容檔；`stage-report.sh` 的「寫入的 wiki 頁」表格多一欄連結驗證，逐列標「通過、無可查端點、連不到、未驗證」，頁面上找不到 `[[...]]` 寫法的連結；`$JSC_HOME/usage/events.jsonl` 多一筆 `{kind:skill,phase:end}` 的事件，`name` 是 `jsc-sdlc:plan`，`status` 是五個值之一。工作目錄的檔案一律不動。 |
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
# 階段回報 — 四個階段收尾都要交的東西
|
||||
|
||||
規劃、分析、實作、維護跑完，最後一件事一定是階段回報。彙整由 `tools/stage-report.sh` 產出，
|
||||
技能只負責把事實餵進去：寫過哪些 wiki 頁、有沒有寫工作日誌、實作階段的工作目錄與三條分支。
|
||||
規劃、分析、實作、維護跑完，最後兩件事固定是這兩筆：先給使用者看的階段回報，再給機器看的
|
||||
結束事件。階段回報由 `tools/stage-report.sh` 彙整產出，技能只負責把事實餵進去：寫過哪些
|
||||
wiki 頁、有沒有寫工作日誌、實作階段的工作目錄與三條分支。結束事件見本頁最後一節。
|
||||
|
||||
## 什麼時候回報
|
||||
|
||||
@@ -61,3 +62,22 @@
|
||||
| 1 | 有警告（缺工作日誌、實作階段沒有 PR、或清單裡有連不到的連結） | 一樣把輸出貼給使用者，連不到的連結照著修。**這是警告不是阻擋**，階段的工作已經做完了 |
|
||||
| 2 | 用法錯誤 | 修正參數重跑 |
|
||||
| 3 | 找不到 `gitea.sh` 或 `sdlc-gate.sh` | 修好相依關係再重跑 |
|
||||
|
||||
## 結束事件 — 階段回報之後那一筆
|
||||
|
||||
階段回報是給人看的，結束事件是給機器看的。跑完階段回報，緊接著跑
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-sdlc:{技能名} {status} {結束碼} [detail]`，
|
||||
一筆寫進 `$JSC_HOME/usage/events.jsonl`。腳本名怎麼寫，比照各技能既有寫
|
||||
`jsc-hooks/hooks/sdlc-gate.sh` 的方式，不另立一套。
|
||||
|
||||
為什麼非得由技能自己寫：配對的 `skill-start` 由 jsc-hooks 自己記，但那個 hook 接在技能工具
|
||||
呼叫之後就觸發，實際工作還在後面的模型輪次，所以**沒有任何 hook 看得到階段怎麼結束**。
|
||||
有 `start` 沒有配對的 `end`，在紀錄裡就是中止；收尾少寫這一筆，跑完的階段每一次都會被算成中止。
|
||||
|
||||
| 項目 | 規則 |
|
||||
| --- | --- |
|
||||
| `status` | `ok`、`blocked`、`failed`、`degraded`、`aborted` 五選一。哪一種情況選哪一個，各技能 SKILL.md 的收尾步驟有自己的對應表，那張表是唯一判準 |
|
||||
| 模型閘門擋下 | 一律 `blocked`，不是 `failed`。閘門擋下不合格的模型是閘門在做事，記成失敗會讓下一手去找一個不存在的缺陷 |
|
||||
| `{結束碼}` | 判定該狀態的那支腳本的結束碼；沒有任何腳本回非 0 就填 `0`，`ok` 與 `aborted` 都是這種 |
|
||||
| `[detail]` | 選填，繁體中文單行，講清楚是什麼決定了這個狀態。腳本截到 200 字元，長內容不要塞 |
|
||||
| 失敗怎麼辦 | **這一步失敗不改變本次階段的結論。** 找不到腳本就安靜跳過，不回報也不重跑任何步驟。三個記錄子命令本來就設計成寫檔失敗也回 0，所以回非 0 只代表呼叫本身寫錯了（`2` 是用法錯誤），修一次參數就好 |
|
||||
|
||||
Reference in New Issue
Block a user