references/behaviors.md

@@ -7,47 +7,47 @@
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 使用者給一條 Gitea wiki 頁連結或議題連結，要把那一頁變成一份離得開 Gitea 的 HTML 檔。請求裡沒有連結就直接停手。不猜存放庫、不猜頁名、不猜議題編號，也不回頭去讀工作目錄的 remote。要改某一類頁面用哪一組範本，走 jsc-gitea:html-style。 |
-| 關鍵步驟 | 用 tools/gitea-link.sh parse 解析連結、確認 GITEA_HOST 有值、同一批平行跑三條線、開 sub agent 整理 markdown、用 tools/html-render.sh 產出檔案。三條線分別是：A 取內容，wiki 頁走 jsc-gitea:wiki 的 wiki-get 與 wiki-url，議題走 tools/issue.sh show 一次取回標題、標籤、內文；B 取範本，tools/html-style.sh key 算出 kind key，再用 get 讀出版型、風格、來源三欄；C 問輸出路徑，預設提 ./.jsc/html/{名稱}.html。sub agent 只做兩件事：把舊頁殘留的 wiki 內部連結換成 [文字](絕對網址)、拿掉個資。 |
-| 外部呼叫 | tools/gitea-link.sh、tools/html-style.sh、tools/html-render.sh、tools/issue.sh、jsc-gitea:wiki、jsc-ask:ask、Gitea 的 wiki API、Gitea 的議題 API、Gitea 的 markdown 渲染 API。 |
-| 完成條件 | 檔案已經寫出來。回報裡有檔案路徑、版型名稱、風格名稱，以及這一組是從哪裡來的。來源是 default 或 builtin 時，回報要多一行告訴使用者可以用 jsc-gitea:html-style 設定。渲染失敗就不留半成品檔，直接停手回報。 |
-| 可驗證跡象 | 使用者確認過的輸出路徑多一個 HTML 檔，預設落在 ./.jsc/html/ 底下。這個檔把 CSS 與 JS 內嵌，不外連任何資源，開起來就是完整的一頁。不寫 wiki 頁、不建議題、不開 PR，來源頁面本身也不動。 |
+| 關鍵步驟 | 用 tools/gitea-link.sh parse 解析連結、確認 GITEA_HOST 有值、同一批平行跑三條線、開 sub agent 整理 markdown、用 tools/html-render.sh 產出檔案，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:html-export 寫下這一輪的結果。三條線分別是：A 取內容，wiki 頁走 jsc-gitea:wiki 的 wiki-get 與 wiki-url，議題走 tools/issue.sh show 一次取回標題、標籤、內文；B 取範本，tools/html-style.sh key 算出 kind key，再用 get 讀出版型、風格、來源三欄；C 問輸出路徑，預設提 ./.jsc/html/{名稱}.html。sub agent 只做兩件事：把舊頁殘留的 wiki 內部連結換成 [文字](絕對網址)、拿掉個資。收尾那一筆走每一條出口，連停在連結閘門那一條也要寫；status 五選一，檔案產出得完整是 ok，主機沒值就停是 blocked，讀頁或渲染中途壞掉是 failed，讀不到標籤而改用沒帶標籤的範本是 degraded，請求裡沒有連結或使用者中止是 aborted。腳本不在這台機器就安靜跳過，回報失敗不得改變這支技能的結果。 |
+| 外部呼叫 | tools/gitea-link.sh、tools/html-style.sh、tools/html-render.sh、tools/issue.sh、jsc-gitea:wiki、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end、Gitea 的 wiki API、Gitea 的議題 API、Gitea 的 markdown 渲染 API。 |
+| 完成條件 | 檔案已經寫出來。回報裡有檔案路徑、版型名稱、風格名稱，以及這一組是從哪裡來的。來源是 default 或 builtin 時，回報要多一行告訴使用者可以用 jsc-gitea:html-style 設定。渲染失敗就不留半成品檔，直接停手回報。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼。 |
+| 可驗證跡象 | 使用者確認過的輸出路徑多一個 HTML 檔，預設落在 ./.jsc/html/ 底下。這個檔把 CSS 與 JS 內嵌，不外連任何資源，開起來就是完整的一頁。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:html-export，status 與 exit 就是這一輪的結果。不寫 wiki 頁、不建議題、不開 PR，來源頁面本身也不動。 |
 
 ## html-style
 
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 某一類 wiki 頁或議題匯出時要換版型、換風格。或是 jsc-gitea:html-export 回報來源是 builtin 或 default，要補上這一類自己的設定。只是要出一份檔案，走 jsc-gitea:html-export。 |
-| 關鍵步驟 | 用 tools/html-style.sh list 列出目前設定、依決策樹敲定一個 kind key、用 layouts 列出全部六種版型讓使用者挑、用 styles 列出全部五種風格讓使用者挑、問這次寫專案還是寫全機、用 set 寫進設定檔、再用 get 讀回來核對來源欄。kind key 只有三種形狀：WIKI:{頁名前綴}、ISSUE:{標籤名}、DEFAULT。版型與風格一律整份列出，不先篩短清單。 |
-| 外部呼叫 | tools/html-style.sh 的 list、get、layouts、styles、set、unset 子命令、jsc-ask:ask。不打任何 Gitea API。 |
-| 完成條件 | set 回結束碼 0，並印出它寫的那個檔案。get 讀回來的來源欄與這次選的範圍一致：選 --project 就顯示 project，選 --global 就顯示 global。寫進去的版型名與風格名，都要是腳本列過的名字。 |
-| 可驗證跡象 | 設定檔多一列 {種類}={版型},{風格}，例如 WIKI:PLAN=report,corporate。選 --project 改的是工作目錄的 ./.jsc/html-styles，這個檔會跟著存放庫一起提交。選 --global 改的是 $JSC_HOME/html-styles.conf，JSC_HOME 預設 ~/.jsc。兩個檔都握有同一個 key 時，專案檔贏。不產 HTML 檔、不動 Gitea。 |
+| 關鍵步驟 | 用 tools/html-style.sh list 列出目前設定、依決策樹敲定一個 kind key、用 layouts 列出全部六種版型讓使用者挑、用 styles 列出全部五種風格讓使用者挑、問這次寫專案還是寫全機、用 set 寫進設定檔、再用 get 讀回來核對來源欄，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:html-style 寫下這一輪的結果。kind key 只有三種形狀：WIKI:{頁名前綴}、ISSUE:{標籤名}、DEFAULT。版型與風格一律整份列出，不先篩短清單。收尾那一筆走每一條出口，連停在範本目錄不見那一條也要寫；status 五選一，寫進去又讀回來對得上是 ok，範本目錄不見而列不出名字、整支停在問問題之前是 blocked，set 回 1、2 或 4 沒寫成是 failed，set 回 0 但讀回來的來源欄與這次選的範圍不同是 degraded，使用者在四個問題任何一關停手是 aborted。腳本不在這台機器就安靜跳過，回報失敗不得改變這支技能的結果。 |
+| 外部呼叫 | tools/html-style.sh 的 list、get、layouts、styles、set、unset 子命令、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end。不打任何 Gitea API。 |
+| 完成條件 | set 回結束碼 0，並印出它寫的那個檔案。get 讀回來的來源欄與這次選的範圍一致：選 --project 就顯示 project，選 --global 就顯示 global。寫進去的版型名與風格名，都要是腳本列過的名字。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼。 |
+| 可驗證跡象 | 設定檔多一列 {種類}={版型},{風格}，例如 WIKI:PLAN=report,corporate。選 --project 改的是工作目錄的 ./.jsc/html-styles，這個檔會跟著存放庫一起提交。選 --global 改的是 $JSC_HOME/html-styles.conf，JSC_HOME 預設 ~/.jsc。兩個檔都握有同一個 key 時，專案檔贏。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:html-style，status 與 exit 就是這一輪的結果。不產 HTML 檔、不動 Gitea。 |
 
 ## repo-sync
 
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 要把某一個 Gitea 擁有者底下讀得到的存放庫，一次全部拉到工作目錄。開新工作環境、或整批更新既有存放庫時用。只同步一個存放庫時不用這支。 |
-| 關鍵步驟 | 用 tools/gitea.sh owners 列出讀得到的擁有者、請使用者挑一個、用 tools/gitea.sh repos 列出該擁有者底下的存放庫、同一批平行開 sub agent 一個存放庫一個、每個 sub agent 跑 tools/repo-sync.sh 並依它那一行輸出分流、最後把每個存放庫的結果彙整回報。分流有四種：cloned 與 updated 就算完成，dirty {分支} 把那個分支當 base 交給 jsc-git:pr，failed {原因} 記下原因並停掉這個存放庫。複製或拉取的判斷、基準分支的優先序，都由腳本決定，不自己下 git clone、git checkout、git pull。 |
-| 外部呼叫 | tools/gitea.sh 的 owners、repos、clone-url、tools/repo-sync.sh、jsc-git:pr、jsc-ask:ask、Gitea 的擁有者與存放庫清單 API，以及腳本內部的 git clone、git fetch、git pull。 |
-| 完成條件 | 清單上的每一個存放庫都拿到一種結果：cloned、updated、一列 PR 表格，或失敗原因。一個存放庫失敗不取消其他存放庫。有多條 PR 時，全部併進同一張表。 |
-| 可驗證跡象 | 工作目錄底下多出或更新了各存放庫的目錄。新的是 git clone 的結果，既有的已經快轉到基準分支。原本有未提交變更的存放庫，會多一條推上去的分支，以及一條開在 Gitea 上的 PR，PR 網址寫在回報表格裡。不寫 wiki 頁、不建議題。 |
+| 關鍵步驟 | 用 tools/gitea.sh owners 列出讀得到的擁有者、請使用者挑一個、用 tools/gitea.sh repos 列出該擁有者底下的存放庫、同一批平行開 sub agent 一個存放庫一個、每個 sub agent 跑 tools/repo-sync.sh 並依它那一行輸出分流、把每個存放庫的結果彙整回報，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:repo-sync 寫下這一輪的結果。分流有四種：cloned 與 updated 就算完成，dirty {分支} 把那個分支當 base 交給 jsc-git:pr，failed {原因} 記下原因並停掉這個存放庫。複製或拉取的判斷、基準分支的優先序，都由腳本決定，不自己下 git clone、git checkout、git pull。收尾那一筆走每一條出口，連停在列不出擁有者那一條也要寫；status 五選一，每個存放庫都同步完是 ok，主機或金鑰沒值、或這把金鑰一個擁有者都讀不到而整輪沒動到任何存放庫是 blocked，列清單回 7 或 8、或每個存放庫都 failed 是 failed，有的成功有的 failed 是 degraded，使用者沒挑擁有者或中途停手是 aborted。detail 只放筆數，逐個存放庫的清單留在回報裡。腳本不在這台機器就安靜跳過，回報失敗不得改變這支技能的結果。 |
+| 外部呼叫 | tools/gitea.sh 的 owners、repos、clone-url、tools/repo-sync.sh、jsc-git:pr、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end、Gitea 的擁有者與存放庫清單 API，以及腳本內部的 git clone、git fetch、git pull。 |
+| 完成條件 | 清單上的每一個存放庫都拿到一種結果：cloned、updated、一列 PR 表格，或失敗原因。一個存放庫失敗不取消其他存放庫。有多條 PR 時，全部併進同一張表。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼。 |
+| 可驗證跡象 | 工作目錄底下多出或更新了各存放庫的目錄。新的是 git clone 的結果，既有的已經快轉到基準分支。原本有未提交變更的存放庫，會多一條推上去的分支，以及一條開在 Gitea 上的 PR，PR 網址寫在回報表格裡。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:repo-sync，status 與 exit 就是這一輪的結果。不寫 wiki 頁、不建議題。 |
 
 ## wiki
 
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 技能組裡任何一次 wiki 頁的讀、寫、刪或搬移，都經過這一支。呼叫端有 jsc-ask、jsc-sdlc、jsc-log、jsc-hooks 的 ERROR 頁、jsc-cli 的 CHECK 頁、jsc-meta 的 SKILLSET 與 TOOLING 頁、jsc-assist 的 MONITOR 頁。存放庫裡的程式碼檔案不歸這一支管。 |
-| 關鍵步驟 | 確認 GITEA_HOST 有值、用 tools/gitea.sh wiki-repo {TYPE} 解出 {owner}/{repo}、用 tools/hash-id 算頁名要用的 HASH、用 tools/page-name.sh check 驗過頁名、再依動作跑 wiki-list、wiki-get、wiki-put、wiki-delete 或 wiki-url，每一次呼叫都照結束碼表分流。所有 *_CONTENTS 頁一律走型別 CONTENTS，內容頁走自己的型別；存放庫的解法是先讀 JSC_WIKI_REPO_{TYPE}、再讀 JSC_WIKI_REPO、兩個都沒有才問使用者，而且不借用別的頁型的存放庫。頁面裡的連結一律寫成 [文字](絕對網址)，網址取自 wiki-url，不自行組路徑；wiki-put 之前先把這一頁要放的每一條連結交給 tools/link-check.sh，結束碼 0 才寫，1 就不寫並回報 DEAD 那幾筆，7 停下來回報金鑰問題。目錄頁的整列 upsert 交給 tools/wiki-contents.sh，寫入前一定先 wiki-get 讀回舊內容，只有結束碼 4 才准用範本建新頁；舊頁搬到新規則走 tools/migrate-wiki.sh，不帶 --apply 只印對照表，寫每一個目的地之前也一樣先 wiki-get 讀一次。 |
-| 外部呼叫 | tools/gitea.sh 的 wiki-repo、wiki-list、wiki-get、wiki-put、wiki-delete、wiki-url、tools/hash-id、tools/page-name.sh、tools/link-check.sh、tools/wiki-contents.sh、tools/migrate-wiki.sh、tools/write-confirm.sh、jsc-ask:ask、Gitea 的 wiki API 與議題 API。 |
-| 完成條件 | 讀取動作拿到頁面內容，或拿到一個講得清楚的結束碼。寫入動作先讓 tools/link-check.sh 回結束碼 0，再通過人工確認、wiki-put 回結束碼 0，而且送出去的是舊內容加上這次的異動，不是整頁覆蓋。連結檢查回 1 就不寫入，回 7 連同整個動作一起中止。wiki-put 的結束碼 7 與 8 一律中止整個動作，不建頁、不寫入、不用原參數重試。搬移動作要嘛全部搬完回 0，要嘛把失敗頁、孤兒頁、目的地已有內容的頁、指向被搬頁卻沒被搬的引用方逐條列出來，這四種一律交給人判斷。 |
-| 可驗證跡象 | 目標 wiki 存放庫多一頁或改一頁。內容頁的頁名是 {型別}_{40 碼大寫十六進位}，目錄頁是 {型別}_CONTENTS 且落在 JSC_WIKI_REPO_CONTENTS 指的那個存放庫。頁面內容是 UTF-8 繁體中文，以 mermaid 圖與 markdown 表格為主，散文每節最多三句；頁面裡每一條連結都是 [文字](絕對網址)，沒有 wiki 內部連結語法，而且每一條在寫入前都被 tools/link-check.sh 判成 OK。寫入與刪除前 tools/write-confirm.sh 會各留下一次人工確認。只做讀取的呼叫無寫入跡象，只有回報內容。 |
+| 關鍵步驟 | 確認 GITEA_HOST 有值、用 tools/gitea.sh wiki-repo {TYPE} 解出 {owner}/{repo}、用 tools/hash-id 算頁名要用的 HASH、用 tools/page-name.sh check 驗過頁名、再依動作跑 wiki-list、wiki-get、wiki-put、wiki-delete 或 wiki-url，每一次呼叫都照結束碼表分流。所有 *_CONTENTS 頁一律走型別 CONTENTS，內容頁走自己的型別；存放庫的解法是先讀 JSC_WIKI_REPO_{TYPE}、再讀 JSC_WIKI_REPO、兩個都沒有才問使用者，而且不借用別的頁型的存放庫。頁面裡的連結一律寫成 [文字](絕對網址)，網址取自 wiki-url，不自行組路徑；wiki-put 之前先把這一頁要放的每一條連結交給 tools/link-check.sh，結束碼 0 才寫，1 就不寫並回報 DEAD 那幾筆，7 停下來回報金鑰問題。目錄頁的整列 upsert 交給 tools/wiki-contents.sh，寫入前一定先 wiki-get 讀回舊內容，只有結束碼 4 才准用範本建新頁；舊頁搬到新規則走 tools/migrate-wiki.sh，不帶 --apply 只印對照表，寫每一個目的地之前也一樣先 wiki-get 讀一次。收尾一律呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki 寫下這一輪的結果，走每一條出口，連停在主機閘門那一條也要寫；這支被幾乎每支技能呼叫，只回報這一次 wiki 動作的成敗，不回報呼叫端自己的結果。status 五選一，讀到頁面或寫入落地是 ok，主機沒值、或 wiki-repo 回 3 而使用者沒給 {owner}/{repo}、整輪沒讀也沒寫是 blocked，金鑰失效那個結束碼 7 算 failed 不算頁面不存在、結束碼 8 與 link-check 回 1 擋下寫入也是 failed，內容頁寫成功但目錄頁沒更新（wiki-contents.sh 回 3 或 1）是 degraded、搬移只搬掉一部分也是 degraded，人工確認被否決或頁型不在允許清單而停在 wiki-repo 回 2 是 aborted。detail 只放頁名，不放頁面內容。腳本不在這台機器就安靜跳過，回報失敗不得改變回給呼叫端的結果。 |
+| 外部呼叫 | tools/gitea.sh 的 wiki-repo、wiki-list、wiki-get、wiki-put、wiki-delete、wiki-url、tools/hash-id、tools/page-name.sh、tools/link-check.sh、tools/wiki-contents.sh、tools/migrate-wiki.sh、tools/write-confirm.sh、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end、Gitea 的 wiki API 與議題 API。 |
+| 完成條件 | 讀取動作拿到頁面內容，或拿到一個講得清楚的結束碼。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響回給呼叫端的結束碼。寫入動作先讓 tools/link-check.sh 回結束碼 0，再通過人工確認、wiki-put 回結束碼 0，而且送出去的是舊內容加上這次的異動，不是整頁覆蓋。連結檢查回 1 就不寫入，回 7 連同整個動作一起中止。wiki-put 的結束碼 7 與 8 一律中止整個動作，不建頁、不寫入、不用原參數重試。搬移動作要嘛全部搬完回 0，要嘛把失敗頁、孤兒頁、目的地已有內容的頁、指向被搬頁卻沒被搬的引用方逐條列出來，這四種一律交給人判斷。 |
+| 可驗證跡象 | 目標 wiki 存放庫多一頁或改一頁。內容頁的頁名是 {型別}_{40 碼大寫十六進位}，目錄頁是 {型別}_CONTENTS 且落在 JSC_WIKI_REPO_CONTENTS 指的那個存放庫。頁面內容是 UTF-8 繁體中文，以 mermaid 圖與 markdown 表格為主，散文每節最多三句；頁面裡每一條連結都是 [文字](絕對網址)，沒有 wiki 內部連結語法，而且每一條在寫入前都被 tools/link-check.sh 判成 OK。寫入與刪除前 tools/write-confirm.sh 會各留下一次人工確認。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:wiki，status 與 exit 就是這一次 wiki 動作的結果。只做讀取的呼叫沒有 wiki 寫入跡象，只有回報內容與那一筆事件。 |
 
 ## wiki-to-issue
 
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 一頁 wiki 要變成一條追得動的議題，而且使用者已經給了那一頁的連結。請求裡沒有 wiki 連結就直接停手，不猜存放庫、不猜頁名。連結指向的是議題也停手。從零起草的議題不走這一支，已經存在的議題要同步也不走這一支。 |
-| 關鍵步驟 | 同一批檢查連結與主機、平行跑三條線、依決策樹挑標籤、處理看板、最後建議題。連結用 tools/gitea-link.sh parse 解析，要印出 kind=wiki 才算過；GITEA_HOST 要有值。三條線是：A 讀頁面並開 sub agent 起草標題與內文；B 用 tools/issue.sh labels 取這個存放庫既有的標籤清單；C 用 tools/issue.sh projects 取看板清單。內文開頭放一行「來源：{絕對網址}」，連結一律寫成 [文字](絕對網址)，舊頁殘留的 wiki 內部連結一併換掉，個資拿掉。標籤只能從既有清單裡挑，確認後用 label-ids 換成 id，缺的標籤不補建。看板 API 不存在時，把腳本印出的看板網址交給使用者自己拖。 |
-| 外部呼叫 | tools/gitea-link.sh、tools/issue.sh 的 labels、projects、label-ids、create、jsc-gitea:wiki、jsc-ask:ask、tools/write-confirm.sh、Gitea 的 wiki API 與議題 API。 |
-| 完成條件 | 議題已經建立，回報裡有議題網址、實際套上的標籤，以及看板狀態。建不成就明講沒有建成，並交出草稿檔的路徑，讓草稿不會白寫。標題、內文、標籤、看板都在呼叫 create 之前先跟使用者確認過。 |
-| 可驗證跡象 | 目標存放庫的議題追蹤器多一條議題，create 會印出 index= 與 url= 兩行。議題內文第一行是「來源：」加上 wiki 頁的絕對網址，內文裡每一條連結都是 [文字](絕對網址)，沒有殘留的 wiki 內部連結語法。標籤就是這次確認過的那一組。站台有看板 API 時，看板上多一張卡；沒有時，回報裡留一行待辦說明誰要去補。來源 wiki 頁本身不動。 |
+| 關鍵步驟 | 同一批檢查連結與主機、平行跑三條線、依決策樹挑標籤、處理看板、最後建議題。連結用 tools/gitea-link.sh parse 解析，要印出 kind=wiki 才算過；GITEA_HOST 要有值。三條線是：A 讀頁面並開 sub agent 起草標題與內文；B 用 tools/issue.sh labels 取這個存放庫既有的標籤清單；C 用 tools/issue.sh projects 取看板清單。內文開頭放一行「來源：{絕對網址}」，連結一律寫成 [文字](絕對網址)，舊頁殘留的 wiki 內部連結一併換掉，個資拿掉。標籤只能從既有清單裡挑，確認後用 label-ids 換成 id，缺的標籤不補建。看板 API 不存在時，把腳本印出的看板網址交給使用者自己拖。最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki-to-issue 寫下這一輪的結果，走每一條出口，連停在連結閘門那一條也要寫；status 五選一，議題建好且看板也掛上是 ok，主機沒值就停、整輪沒讀頁也沒起草是 blocked，讀頁回 4、7、8 或取標籤回 1 或 create 回 1 是 failed，議題建好但看板沒掛上（projects 回 3 或掛看板被拒）是 degraded，請求裡沒有 wiki 連結、parse 回 3、連結指向議題，或使用者否決 create 的人工確認是 aborted。detail 放議題編號，不放內文。腳本不在這台機器就安靜跳過，回報失敗不得改變這支技能的結果。 |
+| 外部呼叫 | tools/gitea-link.sh、tools/issue.sh 的 labels、projects、label-ids、create、jsc-gitea:wiki、jsc-ask:ask、tools/write-confirm.sh、jsc-hooks/tools/report-status.sh skill-end、Gitea 的 wiki API 與議題 API。 |
+| 完成條件 | 議題已經建立，回報裡有議題網址、實際套上的標籤，以及看板狀態。建不成就明講沒有建成，並交出草稿檔的路徑，讓草稿不會白寫。標題、內文、標籤、看板都在呼叫 create 之前先跟使用者確認過。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼。 |
+| 可驗證跡象 | 目標存放庫的議題追蹤器多一條議題，create 會印出 index= 與 url= 兩行。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:wiki-to-issue，status 與 exit 就是這一輪的結果。議題內文第一行是「來源：」加上 wiki 頁的絕對網址，內文裡每一條連結都是 [文字](絕對網址)，沒有殘留的 wiki 內部連結語法。標籤就是這次確認過的那一組。站台有看板 API 時，看板上多一張卡；沒有時，回報裡留一行待辦說明誰要去補。來源 wiki 頁本身不動。 |

skills/html-export/SKILL.md

@@ -19,6 +19,21 @@ The link is the only input. The output is one file that opens anywhere, with no
    Completion condition: the markdown and the document title are in hand, exactly one kind key is chosen with the reason that produced it, the layout, style and source are reported, and the user has confirmed one output path.
 4. **Prepare the markdown — this step MUST run as a sub agent.** Links are written as `[text](absolute URL)`, so pages that follow the current rule need no conversion. An older page can still carry a wiki-internal link: turn it into an absolute URL from `wiki-url`, because the renderer does not resolve it and it would ship as literal brackets. Strip personal data — an exported file travels further than the page it came from. Leave everything else exactly as written; this step never rewrites the content. Completion condition: every link in the file is `[text](absolute URL)`, and the diff against the source is limited to link conversion and personal-data removal.
 5. Render: `tools/html-render.sh --markdown {file} --title {title} --layout {layout} --style {style} --source-url {absolute URL} --out {path}`. Route every exit code: 0 → the path it printed is the finished file; 1 → Gitea's renderer or the write failed, so report it and stop, with no half-rendered file left behind; 2 → a usage error or a missing markdown file, so fix the arguments and call again; 4 → the layout or style template file is gone, so report which pair was asked for and send the user to `jsc-gitea:html-style` rather than editing the configuration by hand. Completion condition: the file exists, and the report names its path, the layout, the style and where that pair came from.
+6. **Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill — including the ones that stop at step 1. Call
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-gitea:html-export {status} {exit code} [detail]`
+
+   `{exit code}` is the exit code of whatever decided the outcome, and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
+
+   | status | When this skill uses it |
+   | --- | --- |
+   | `ok` | The file was rendered and the report names its path, layout, style and source |
+   | `blocked` | The host gate of step 2 stopped the run: `GITEA_HOST` holds no value and the user gave none, so nothing was read and nothing was rendered |
+   | `failed` | The work started and broke: `wiki-get` returned 7 or 8, `issue.sh show` returned 1, or `html-render.sh` returned 1, 2 or 4. Nothing usable came out |
+   | `degraded` | The file was rendered, but part of the run did not hold — track B could not read the labels (exit 1) so the template was picked without them, and the export used a template the configuration did not choose |
+   | `aborted` | The premise did not hold, so the skill stopped on its own: the request carried no wiki or issue link, or `gitea-link.sh parse` returned 3. Also used when the user stops the run at step 3's destination question |
+
+   Completion condition: exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
 
 ## Rules
 

skills/html-style/SKILL.md

@@ -15,6 +15,21 @@ One kind of page, one layout, one style. `jsc-gitea:html-export` reads what this
 4. **Pick the scope.** Ask per `jsc-ask:ask` rules: `--project` writes `./.jsc/html-styles`, which only applies inside this working directory and is committed with the repository; `--global` writes `$JSC_HOME/html-styles.conf`, which follows the user across every project on this machine. State that the project file wins whenever both hold the same key. Completion condition: the user has picked one scope.
 5. Write it: `tools/html-style.sh set {key} {layout} {style} [--project|--global]`. Route every exit code: 0 → the file it printed now holds the pair; 1 → the settings file's directory could not be created, so report the path and stop, since nothing was written; 2 → a usage error, such as a missing name or a scope flag that is neither `--project` nor `--global`, so fix the arguments and call again; 4 → the layout or style name has no template file, so go back to step 2 or step 3 rather than editing the settings file by hand. Completion condition: the script exits 0 and prints the file it wrote.
 6. Read it back with `tools/html-style.sh get {key}` and report the resolved layout, style and source. Completion condition: the source column shows `project` or `global`, matching the scope chosen in step 4.
+7. **Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at step 2 included. Call
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-gitea:html-style {status} {exit code} [detail]`
+
+   `{exit code}` is the exit code of whatever decided the outcome, and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
+
+   | status | When this skill uses it |
+   | --- | --- |
+   | `ok` | `set` exited 0 and step 6 read the pair back with the source column matching the scope that was chosen |
+   | `blocked` | The template directory is missing, so `layouts` or `styles` listed nothing. There is no name to offer and no pair to write, so the run stops before any question and the settings file is untouched |
+   | `failed` | The write itself broke: `set` returned 1 because the settings directory could not be created, 2 on a malformed call, or 4 because the layout or style has no template file. Nothing was written |
+   | `degraded` | `set` exited 0, but step 6 read back a different source than the scope chosen in step 4 — usually a project file holding the same key and winning over a global write. The pair is on disk, yet the export will still resolve to another one |
+   | `aborted` | The user stopped at one of the four questions — the kind key, the layout, the style or the scope — so nothing was written |
+
+   Completion condition: exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
 
 ## Rules
 

skills/repo-sync/SKILL.md

@@ -16,3 +16,18 @@ description: Batch-sync all readable repos of a chosen Gitea owner into the work
 
    Done when every repo's sub agent has returned one of those outcomes; one repo failing never cancels the others.
 5. Report the sync result for every repo: cloned, updated, PR table row, or the failure reason. Done when every `{repo}` from step 3 carries one of those four results, and all PR rows share one table when more than one PR exists.
+6. **Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at step 1 included. Call
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-gitea:repo-sync {status} {exit code} [detail]`
+
+   `{exit code}` is the exit code of whatever decided the outcome, and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters — the repo counts fit there, the per-repo list does not. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
+
+   | status | When this skill uses it |
+   | --- | --- |
+   | `ok` | Every repo from step 3 came back `cloned`, `updated`, or dirty with its PR opened |
+   | `blocked` | Nothing could be listed, so no repo was touched: `GITEA_HOST` or `GITEA_TOKEN` was required and the user gave none, or `owners` exited 0 with no owner this key can read |
+   | `failed` | The listing broke mid-run — `owners` or `repos` returned 7 or 8 — or every repo in step 4 came back `failed`. No repo reached the working directory |
+   | `degraded` | Some repos synced and some did not: at least one `failed {reason}` next to at least one `cloned`, `updated` or PR row. One repo failing never cancels the others, so the run finishes with part of the workspace missing |
+   | `aborted` | The user named no owner at step 2, or stopped the run before step 4 started |
+
+   Completion condition: exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.

skills/wiki-to-issue/SKILL.md

@@ -24,6 +24,22 @@ The wiki link is the only input. Everything else — repository, page name, host
 4. **Project board.** Track C returned a board list: let the user pick one per `jsc-ask:ask` rules, attach it, and report the failure verbatim if the attach call is refused. Track C exited 3: say plainly that this Gitea has no board API, and hand the user the board URL the script printed so they can drag the issue in themselves. Completion condition: the issue is either attached to a board, or the report states in one line that the board link is still outstanding and who has to do it.
 5. Create the issue: `tools/issue.sh create {repo} {title} {body-file} [--labels {ids}]`. The script asks for confirmation before it writes, so expect that prompt and hand the user the title, the labels and the board it is about to apply. Exit 0: report the `index=` and `url=` it prints. Exit 1 means no issue was created — report that plainly, and hand back the path of the drafted body file so the draft is not lost. Exit 2 is a usage error, usually a body file that is not there — fix the arguments and call again. Completion condition: the issue URL is reported to the user together with the labels applied and the board status from step 4, or the report states that no issue was created and where the draft is.
 
+6. **Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at step 1 included. Call
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki-to-issue {status} {exit code} [detail]`
+
+   `{exit code}` is the exit code of whatever decided the outcome, and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters — the issue index fits there, the issue body does not. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
+
+   | status | When this skill uses it |
+   | --- | --- |
+   | `ok` | `issue.sh create` exited 0, and the report carries the issue URL, the labels applied and a board that is attached |
+   | `blocked` | The host gate stopped the run: `GITEA_HOST` holds no value and the user gave none, so the page was never read and no issue was drafted |
+   | `failed` | The work started and broke: `wiki-get` returned 4, 7 or 8, `issue.sh labels` returned 1 so no label could be picked without inventing one, or `issue.sh create` returned 1 and no issue exists. Report the draft path in `{detail}` when the create failed |
+   | `degraded` | The issue was created, but part of it stays outstanding — track C exited 3 because this Gitea has no board API, or the attach call was refused, so the report hands the board link back to the user to drag in by hand. The issue is real, its place on the board is not |
+   | `aborted` | The premise did not hold, so the skill stopped on its own: the request carried no wiki link, `gitea-link.sh parse` returned 3, or the link parsed as `kind=issue`. Also used when the user refuses the confirmation `issue.sh create` asks for, so nothing was written |
+
+   Completion condition: exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
+
 ## Rules
 
 - One wiki page, one issue. Splitting a page into several issues is analysis work, not conversion — hand that to `jsc-sdlc:analyze`.

skills/wiki/SKILL.md

@@ -74,6 +74,26 @@ Every code below gets its own branch. Nothing here is retried unchanged.
 | | 2 | usage error, including an unconfigured CONTENTS repo | fix the arguments or set `JSC_WIKI_REPO_CONTENTS`, then call again |
 | | 3 | something needs manual handling: an orphan page, a page that links to a moved page without being moved itself, or a destination page that already holds content | report those lists and hand them to the user; guess no key, and rewrite no link the script left alone |
 
+## Close the run
+
+**Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at the host gate included. Call
+
+`jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki {status} {exit code} [detail]`
+
+`{exit code}` is the exit code of whatever decided the outcome — the `gitea.sh`, `link-check.sh` or `wiki-contents.sh` call that ruled the run — and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters; put the page name there, never the page content. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns to its caller.
+
+This skill is called by almost every other one, so its status is what the caller reads back. Report the status of this wiki operation only, never the caller's own outcome.
+
+| status | When this skill uses it |
+| --- | --- |
+| `ok` | The read returned the page, or the write landed: `link-check.sh` exited 0, the confirmation was given, and `wiki-put` exited 0 |
+| `blocked` | The location could not be resolved, so nothing was read and nothing was written: `GITEA_HOST` holds no value and the user gave none, or `wiki-repo` exited 3 and the user supplied no `{owner}/{repo}` for that page type |
+| `failed` | The operation ran and broke. **Exit 7 belongs here**: the key is invalid or lacks permission, so the whole operation stopped, and that is a failure, never an absent page. Exit 8, a `wiki-put` that did not land, a `link-check.sh` exit 1 that refused the write, and a `hash-id` or `page-name.sh` rejection all sit here too |
+| `degraded` | The content page landed and the contents page did not — `wiki-put` on `{TYPE}_{HASH}` exited 0, then `wiki-contents.sh upsert` exited 3 with no CONTENTS repo configured, or exited 1 on a page holding no markdown table. The record exists but nothing indexes it, so the next reader will not find it. A migration that moved some pages and left orphans or occupied destinations behind sits here as well |
+| `aborted` | The premise did not hold or the user stopped it: `write-confirm.sh` was refused before a write or a delete, or the caller asked for a page type outside the allowed list and the run stopped at `wiki-repo` exit 2 |
+
+Completion condition: exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
+
 ## Rules
 
 1. Page names must follow the wiki naming table in the skill guidelines (see `jsc-meta/references/guidelines.md`). Check any page name you build with `tools/page-name.sh check {page}` before it reaches an API call.