log/references/behaviors.md

jsc-log 技能行為清單

本頁記錄 jsc-log 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。

learn

項目	內容
觸發時機	一次技能執行留下可重用的教訓時，用 record 模式記錄。要跑某支技能之前，用 consult 模式查過去的教訓。工時與 Token 紀錄不走這支，走 worklog
關鍵步驟	record 模式收齊日期、技能、CLI、情境、教訓、下次做法這六欄、從 git remote get-url origin 解出 {owner}/{repo}、用 hash-id 算出完整 40 碼大寫的 {HASH}、用 wiki-repo LEARN 解出教訓頁存取庫、開 sub agent 讀 LEARN_{HASH}、依 wiki-get 的退出碼分支（0 在表尾追加一列、4 才用 templates/learn-page.md 建頁、7 與 8 停止並回報）、取 wiki-url 的絕對網址並寫成 [{頁名}]({絕對網址})、把該網址交給 link-check.sh 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 GITEA_HOST、7 金鑰被拒就停下）、同一輪跑 wiki-contents.sh upsert LEARN 1 {owner}/{repo} 更新落在 CONTENTS 存取庫的 LEARN_CONTENTS、依它的退出碼分流（0 已寫、1 寫入失敗、2 參數錯、3 未設 JSC_WIKI_REPO_CONTENTS、4 缺範本、7 金鑰失效、8 其他 API 失敗）、寫入失敗重試一次；consult 模式算出 {HASH}、從 CONTENTS 存取庫讀 LEARN_CONTENTS、從 LEARN 存取庫讀 LEARN_{HASH}、依列上的絕對網址讀頁、挑出「技能」欄相符的列、整理每一列的「下次做法」交給呼叫端
外部呼叫	jsc-gitea/tools/hash-id、jsc-gitea/tools/gitea.sh wiki-repo LEARN 與 wiki-repo CONTENTS 與 wiki-url、jsc-gitea/tools/link-check.sh（寫入前驗證連結）、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-gitea:wiki（其餘 wiki 讀寫）、git remote get-url origin、templates/learn-page.md、templates/learn-contents.md
完成條件	record 模式要 sub agent 回報兩頁都寫入成功，主代理確認新列在 LEARN_{HASH} 上，原有的列一列不少，寫入前 link-check.sh 回 0，wiki-contents.sh 回 0 並印出 updated 或 added。link-check.sh 回 1 就不寫目錄頁，改回報 DEAD 清單。consult 模式要兩頁都讀到，或以退出碼 4 回報頁面不存在，或在 5、7、8 停止並回報狀態
可驗證跡象	LEARN 存取庫的 LEARN_{HASH} 表尾多一列教訓；CONTENTS 存取庫的 LEARN_CONTENTS 上該 repo 那一列的「最後更新時間」換新，且「教訓紀錄」欄是 [{頁名}]({絕對網址})，頁面上沒有 [[...]] 這種同 wiki 寫法。頁面原本不存在時，會新建 LEARN_{HASH} 或 LEARN_CONTENTS。連結驗證不過就兩頁都沒有新內容，只有 DEAD 清單的回報。consult 模式無寫入跡象，只有回報內容

report

項目	內容
觸發時機	有人要一段期間的工作總結時用，期間分年、月、週、日四種。單一工作包的紀錄不走這支，走 worklog
關鍵步驟	呼叫端沒指定期間就依 jsc-ask:ask 問、跑 tools/report-range.sh 取得起訖日與標籤、平行做四件事（tools/report-template.sh resolve 解出範本、從 CONTENTS 存取庫讀 LOG_CONTENTS 並照列上的絕對網址逐頁讀回工作日誌、年報另外讀 LEARN_CONTENTS 並用 wiki-repo LEARN 解出教訓內容頁的存取庫、解出 REPORT 的 wiki repo）、把頁面內容存成檔案後跑 tools/log-aggregate.sh 算出條目數、涵蓋 repo、花費時間、Token 用量、任務狀態、從存活條目挑出阻塞與未完成工作包、照範本的標題與表格填出報告、用 hash-id "{REPORT wiki 存取庫}/{period}" 算出完整 40 碼頁名、讀 REPORT_{HASH} 後把本期當成新章節追加在最前、取 wiki-url 的絕對網址並依它的退出碼分流（4 是頁還沒寫、5 是頁上沒有 html_url、7 與 8 一律停下並回報金鑰或 API 狀態，不得當成 4）、章節內與目錄列的連結一律寫成 [{文字}]({絕對網址}) 並在寫入前全數交給 link-check.sh 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 GITEA_HOST、7 金鑰被拒就停下）、最後跑 wiki-contents.sh upsert REPORT 2 {HASH} 更新落在 CONTENTS 存取庫的 REPORT_CONTENTS（鍵取第 2 欄的裸 HASH，不取第 1 欄那個帶主機名的連結）
外部呼叫	tools/report-range.sh、tools/report-template.sh、tools/log-aggregate.sh、jsc-gitea/tools/gitea.sh wiki-repo（CONTENTS、LOG、LEARN、REPORT）與 hash-id 與 wiki-url、jsc-gitea/tools/link-check.sh（寫入前驗證連結）、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-gitea:wiki、jsc-ask:ask、templates/report-{period}.md、templates/report-contents.md
完成條件	回報頁面 URL，或回報跳過寫入與它的原因，或在讀取回 7、8 時停下並回報狀態。每次寫入前 link-check.sh 要回 0，回 1 就不寫該頁並回報 DEAD 清單。wiki-contents.sh upsert 要回 0，回 1、2、3、4、7、8 就照該碼回報且不得謊報已寫入。收尾要講出期間標籤、條目數、涵蓋的 repo、範本來源、頁面 URL、帶到下一期的未完成工作包清單，以及 ELAPSED_MISSING 與 TOKEN_MISSING
可驗證跡象	REPORT 存取庫的 REPORT_{HASH}（雜湊取自 REPORT wiki 存取庫的 {owner}/{repo} 加期間，不是程式碼存取庫）多一個本期章節；CONTENTS 存取庫的 REPORT_CONTENTS 該列的「最新一期」、「期數」、「最後更新」換新，且「報表頁」欄是 [{頁名}]({絕對網址})、「HASH」欄是不帶連結的裸 HASH，兩頁都找不到 [[...]] 這種同 wiki 寫法。連結驗證不過就沒有新章節，也沒有新的目錄列，只有 DEAD 清單的回報。重跑同一期間只換掉那一列，不會多出第二列。本機留下工作日誌頁面內容的暫存檔，供 log-aggregate.sh 讀取。沒設定 REPORT wiki repo 時不寫 wiki，只印出報告本文；沒設定 JSC_WIKI_REPO_CONTENTS 時內容頁照寫，只有目錄頁那一列沒動

stats

項目	內容
觸發時機	使用者問某支技能用了幾次，或問技能之間的呼叫鏈用了幾次。Token 與工時統計不走這支，走 worklog
關鍵步驟	直接跑 tools/usage-stats.sh skills 或 tools/usage-stats.sh chains、需要時加 --cli 篩選單一 CLI、先讀退出碼再看輸出、退出碼 0 就把每一行印成表格一列、一行都沒印也是退出碼 0，代表次數為零，要說明 jsc-hooks 還沒經 jsc-hooks:hooks-install 安裝接線且不出表、退出碼 2 代表子指令或 --cli 參數被拒，改正參數後重跑
外部呼叫	tools/usage-stats.sh；資料由 jsc-hooks/hooks/skill-usage.sh 持續寫進 $JSC_HOME/usage/*.jsonl，這支技能只讀不寫
完成條件	讀到退出碼，並走完該退出碼指定的分支
可驗證跡象	無寫入跡象，只有回報內容

worklog

項目	內容
觸發時機	implement 或 maintain 階段每結束一項任務就寫一筆。一項任務是一個工作包、一輪 PR 意見修正，或一次獨立的修正提交。下一項任務開始前就要寫完。規劃階段的筆記不走這支
關鍵步驟	全程由 sub agent 收集與寫入、平行取得十項事實（git remote get-url origin 的 repo、git branch --show-current 的分支、PLAN 頁絕對連結、ANALYZE 頁工作包絕對連結、session-timer.sh report 的花費時間、token-usage.sh 的各 CLI Token、任務狀態、細節與產出、困難與解法、PR 目標分支）、平行解出 LOG wiki repo（只供內容頁）與完整 40 碼大寫的 {HASH}、跑 tools/worklog-target.sh 取得頁名與本週五日期、用 templates/log-entry.md 填出單筆條目檔、跑 tools/worklog-pending.sh merge 併入待寫內容（同時收編同一個 {HASH} 的「H 加前 7 碼」舊目錄）、跑 tools/worklog-pending.sh orphans 掃出現行規則定址不到的暫存目錄（0 就安靜帶過，4 就把每一列回報給使用者並繼續本輪）、讀 PAGE 後依退出碼分支（0 追加在頁尾、4 才建頁、7 與 8 停止且不建頁）、寫入前把 MERGED 裡的每個連結交給 link-check.sh 驗證（0 才寫入、1 有 DEAD 就不寫並回報那幾筆、2 沒給網址、3 未設 GITEA_HOST、7 金鑰被拒就停下）、同一輪用 wiki-repo CONTENTS 解出目錄頁存取庫、取 wiki-url 的絕對網址並寫成 [{頁名}]({絕對網址})、同樣先過 link-check.sh 才跑 wiki-contents.sh upsert LOG 2 {HASH} 更新 LOG_CONTENTS（鍵取第 2 欄的裸 HASH，不取第 1 欄那個帶主機名的連結）並依 0、1、2、3、4、7、8 各自分流、最後依成敗跑 worklog-pending.sh commit 或 abort
外部呼叫	jsc-hooks/hooks/session-timer.sh report、tools/token-usage.sh、tools/worklog-target.sh、tools/worklog-pending.sh、jsc-gitea/tools/gitea.sh wiki-repo（LOG 與 CONTENTS）與 wiki-url、jsc-gitea/tools/link-check.sh（寫入前驗證連結）、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-gitea/tools/hash-id、jsc-gitea:wiki、jsc-ask:ask、git remote get-url origin、git branch --show-current、templates/log-entry.md、templates/log-contents.md
完成條件	兩次寫入前 link-check.sh 都回 0，MERGED 的每一筆條目都在 PAGE 上，原有條目逐字不動，wiki-contents.sh upsert 回 0 且 CONTENTS 該列帶著本週五日期、其他列不動，worklog-pending.sh 的 commit 或 abort 其中一個跑過並回報退出碼，orphans 也跑過且回 0 或已把孤兒清單回報出去。link-check.sh 回 1 或 upsert 回非 0 就照該碼回報，並把步驟七當成失敗處理，讓待寫內容留著
可驗證跡象	LOG 存取庫的 LOG_{HASH} 頁尾多一筆條目，條目裡的計畫名稱、工作包編號、PR 目標分支三欄都是 [{文字}]({絕對網址})；CONTENTS 存取庫的 LOG_CONTENTS 該列的「條目數」與「最後更新」換新，且「日誌頁」欄是 [{頁名}]({絕對網址})，頁面上沒有 [[...]] 這種同 wiki 寫法，「HASH」欄是不帶連結的裸 HASH。連結驗證不過就兩頁都沒有新內容，待寫檔原樣保留。重跑同一頁只換掉那一列，不會多出第二列。$JSC_HOME/worklog-pending/{HASH} 底下的待寫檔在 commit 後清空，abort 後原樣保留；該目錄名是 40 碼大寫十六進位，或尚未遷移的舊暫存那種 8 碼大寫十六進位、H 加 7 碼大寫十六進位；推得出對映的舊目錄會連同新目錄一起被清掉。暫存區留下非 40 碼的目錄時，該輪的回報上看得到 orphans 印出的那幾列。本機留下填好的條目檔