ucl-commit

name

ucl-commit

description

使用者要求 commit / 提交 / 推改動時用本 skill。**預設只 commit 改動所在的那一層（單層），逐層 bump 父層要使用者明說 commit all / 全包 / 逐層 bump 才做。** 涵蓋 submodule 先切回追蹤分支（避免 detached HEAD 游離 commit）、ChatTavern 訊息獨立 [chat] commit、ephemeral 檔（log / 臨時渲染 / wait 檔）不入 commit 的規範，以及**提交一律走 `git_commit.py`**（自動組 Co-Authored-By trailer + 自動發酒館公告領薪）。 觸發詞包含：commit、提交、幫我 commit、分批 commit、推一下、存檔、落 commit、commit 一下、bump submodule、切分支、detached HEAD、commit 薪資、領 commit token、commit 公告。 涉及 UCL_Core 等 submodule 改動的 git 操作必用。

UCL Commit — 提交規範速查

一句話：你負責判斷「哪些檔走哪一筆」與 stage；提交走 git_commit.py，trailer 與領薪公告它自己來。

⚠ 兩條路，沒有第三條： 有作者的產出（code / 文件 / 她寫的信）走 git_commit.py —— 一律公告領薪，沒有關閉開關； 沒有作者的檔（帳本 / 訊息 / cursor / 狀態快照）走 Cmd AutoCommit —— 純 git commit，不掛 trailer、不公告、不領薪。「手動但不公告」不是一個選項 —— 不想公告就表示它不該走手動那條。

[!IMPORTANT]

預設是單層（Tim 2026-08-11 拍板）

收到「commit」→ 只提交改動所在的那一層，不 bump 父層。 逐層 bump 是選配，只在使用者明說時做：commit all / 全包 / 逐層 bump / bump 到主專案。

為什麼預設不 bump：bump 是一個對外的宣告（「這個版本可以拿去用了」）， 而剛寫完的東西通常還沒被實跑驗過。預設 bump 等於每次存檔都對同事廣播一次未驗收的版本。 單層則讓「寫完」跟「發佈」分開 —— 前者我自己決定，後者要人點頭。

代價要講清楚，因為它不會叫：單層之後父層指標仍指著舊 hash， 同事 pull 主專案拿到的還是舊版。所以單層 commit 完的回報必須明說這件事， 不能只報 SHA 就當交付完成 —— 那會讓人以為東西已經到得了別人手上。

⚠ 本 skill 是 UCL_Core 跨專案共用，路徑與分支名因專案而異，一律不寫死。 實際值用 git submodule status / git -C <sub> branch 現場判斷。

你做 vs 工具做

步驟	誰做
判斷哪些檔走哪一筆、具名 stage	你
submodule 切回追蹤分支	你
逐層 bump 的順序（只在使用者說 commit all 時）	你
commit 訊息內容	你
Co-Authored-By（身分／型號／信箱）	工具
酒館公告 + 領薪	工具
push	沒有人 —— Tim 手動

檔案分類（先看清再 stage）

類型	走哪筆 commit
代碼 / 文檔 / .meta	主 commit（具名 stage，走 git_commit.py）
機器生成的重複性檔（酒館訊息 / Treasury 帳本 / runtime state / persona 的 mailbox portraits profile bank _latest.md）	交給自動 commit（Cmd AutoCommit，見下節）—— 不必自己分類
ephemeral：*.log / _last_op.md / _last_view.md / _active_waits.json / _wait_*.md / DebugLogs / 臨時渲染檔	不 commit（自動 commit 也永遠不收）

[!IMPORTANT]

🤖 重複性檔案交給自動 commit（Tim 2026-08-20）

判準是「這個檔有沒有作者」，不是檔案類型：

	有作者的產出（code / 文件 / 她寫的信）	機器生成的狀態（帳本 / 訊息 / cursor / profile/ / bank/）
走哪支	git_commit.py	Cmd AutoCommit
trailer	✅ 掛作者	❌ 純 git commit
酒館公告＋領薪	✅	❌ 不領薪 —— 掛誰的名字領誰的薪都是假帳

# 先掃（預設 op=scan，純讀不動 index）—— 看清分群再決定
run_cmd.py --persona <me> run AutoCommit --arg op=scan
run_cmd.py --persona <me> run AutoCommit --arg op=scan --arg mode=letters

# 真的提交（逐群一筆 commit；不 push、不 bump 父層）
run_cmd.py --persona <me> run AutoCommit --arg op=commit
run_cmd.py --persona <me> run AutoCommit --arg op=commit --arg mode=letters

⚠ 四個硬擋（都是「不會當場叫」的錯，所以擋在必經路上）：

• 未分類（__other）與 submodule pointer（__subptr）永遠不自動收 —— 前者可能是別人正在寫的產出，後者 bump 了別人會 pull 不到 hash。要收得顯式 --arg groups=__other。
• detached HEAD 的 repo 直接跳過（游離 commit 沒有分支指到它）。
• letters 模式預設跳過在線的 persona —— 她可能正在寫。要收得 --arg include_online=1， 而那應該只針對自己（--arg only_persona=<me>），不是順手掃全部。
• 呼叫前 index 已有 staged 檔的 repo，op=commit 直接跳過（BUG-30，沒有繞法）—— 分群只決定「工具 stage 哪些檔」，index 裡本來就有的會被併進第一個群、掛上那個群的訊息。 🩸 git mv 21 個檔後直接跑 op=commit ⇒ 那批改名落進 [chat] … [3 files]：訊息說 3 個、實際 24 個。 先自己 commit 或 unstage 再跑；op=scan 只警告不擋（那是被擋之後唯一的出路）。

⚠ 參數名是 only_persona 不是 persona —— --persona <me> 會把 persona 戳進 args （那是「這筆是誰派的」宣告），叫 persona 就會被它當成篩選條件。 🩸 實測踩過：letters 模式的掃描範圍從 9 個 repo 靜默縮成 1 個，而輸出是「repos=1」， 看起來像「找不到其他 repo」而不像參數撞名。

📌 分群規則的真相源分兩層（2026-08-21 起）：

• AgentCommands 本層與 persona 信件庫 → UCL_AutoCommitRules（寫死在程式碼，不開放編輯）。 [chat] 獨立 commit 是 CLAUDE.md 等級的硬規則，能被參數亂改的規則等於沒有規則。

• DebugLogs 保持 untracked 但不 ignore — Tim 要在 git status 看得到。
• 絕不 git add -A — 一律具名 stage。別人正在寫的檔會被你一起 commit 走，而那不會有錯誤訊息。 ⚠ git add <目錄> 跟 -A 是同一族 —— 目錄不是清單：它收的是「現在那底下有什麼」， 而那包含同事三分鐘前才落盤的檔。 🩸 2026-08-24 summit：git add Tasks 把 @basecamp 正在寫的兩張探針單收進自己的 commit， 而那筆的訊息只講了另外兩張單。--name-only 的清單印出來了，就在下一行輸出裡。
• 🛡 帶 --expect-files N —— 宣告這一筆該收幾個檔，不符就擋下（exit 2，commit 前返回）：

  python <UCL_Core>/Tools~/AgentCommands/git_commit.py --persona <你> --repo <repo> \
      --expect-files 3 --message-file <訊息檔>
  

  它把「我以為我在提交幾個檔」變成一個必須先算過的數字（同 sculpt.py --expect-pixels 的形狀）。 不帶＝不檢查（既有呼叫端行為不變）—— 但具名 stage ＋ 這個數字才是完整的那道手勢。
• 別漏 stage .meta，否則 Unity 跳 missing reference。

Submodule 先切追蹤分支（必做）

detached HEAD 直接 commit → 落在游離節點、追蹤分支永遠不前進（別人拉不到）。

git -C <submodule-path> status -b -s | head -1     # "## HEAD (no branch)" = detached
git -C <submodule-path> switch <tracked-branch>
git -C <submodule-path> pull --ff-only

訊息裡要有「順手修掉的（Q0）」那一段（Tim 2026-08-25 拍板）

做一件事的過程中順手修掉的實作細節，判準見 ucl-task skill §0.5 的四階梯 Q0 —— 它不上任務單，但它的痕跡落在這裡。

「不佔單子」不等於「不留痕跡」。 Q1／Q2／Q3 都有天然落點（單上留言／驗收細項／單子本身）， 只有 Q0 沒有，而 Q0 是每天觸發最多次的那一階 ⇒ 沒有落點它就是隱形工作的入口。 （@kiara 2026-08-25 指出這個洞）

怎麼寫

commit 訊息裡開一段，寫「為什麼」與「它會怎麼咬人」，不要只寫「改了什麼」：

## 順手修掉的（Q0）

<這個東西原本會怎麼咬人 —— 一句話>
<為什麼它不上單子：四個角色都不需要在單上討論它>
<如果有血證，寫現場讀數>

⚠ 不要寫成 changelog（「改了 A、改了 B」）—— 那種訊息三個月後 git log --grep 撈到了也看不出該不該回頭看它。 ✅ 要寫它為什麼存在：git log 是 Q0 唯一的檢索面。

📌 為什麼落點是 commit 而不是文件： 做的人本來就要 commit（成本零）／訊息跟那個 diff 綁死（不會自己漂走）／ 可以被 grep。文件會漂、記憶會歸檔，而 commit 訊息不會。

---

提交 — git_commit.py

git -C <repo> add <files>          # stage 自己來

python <UCL_Core>/Tools~/AgentCommands/git_commit.py \
    --persona <你> [--persona <協作者> ...] \
    --repo <該層 repo 路徑> \
    --message-file <訊息檔> \
    [--announce-body-file <開場白檔>]

[!CAUTION] body 一律走檔案，inline 只準用在「無標點的短句」。 --message-file / --announce-body-file，不要用 -m "…" / --announce-body "…" 塞長文。

🩸 2026-08-05 summit 一天被反引號咬四次（commit -m 兩次、work_memory --body 一次、 --announce-body 一次）。最後那次最難看：同一道指令裡 commit 訊息走了 --message-file （正確修法），公告內文卻用 inline —— 修法只套用在我記得的那半邊。 那次 `bookmark --reader` 被 shell 當命令替換執行掉了（log 留下 command not found）， 公告內文缺一整段，而已公告領薪的訊息無法 amend。

判準不是「含不含特殊字元」（那要人判斷，而人會錯）——是「長文一律走檔案」。 --message-file 有效不是因為你記得反引號會咬人，是因為它根本不經過 shell 解析那一層。

它會做而你不必記的事：

• 每位 --persona 各一行 trailer（身分／型號／信箱全部推導自檔案，重複自動去重）
• 提交後一律發酒館公告領薪，SHA 與 meta 由它填（沒有關閉開關）
• 解析訊息裡的 Fixes BUG-<n> 並自動關掉那幾張問題回報單（見下節）
• --announce-body / --announce-body-file 是可選開場白，插在標題與 commit 內文之間。 不帶就只發 commit 資訊。（commit 訊息寫給日後查 history 的人，開場白寫給現在在酒館的同事。）

它會擋下而不是默默做完的事：

• 信箱解析不到（--allow-unset 才放行）—— 假位址進了 history 改不掉
• persona 檔不存在 / agent 欄空白 —— 打錯名字會靜默生出 ?@nobody(?)，比失敗難查
• 沒有 staged 變更 —— 本工具只提交，不 stage
• 查不到 sender 的 bank —— sender 決定錢進誰的帳，猜錯是把薪水發給別人

exit 6 = commit 成功但公告失敗（錢沒領到，需手動補）。這兩件事刻意分開回報。

⚠ 也別走 stdin heredoc：內文若含 EOF 字樣，結束標記會把外層提前關掉 （2026-08-03 實測自摔，公告被截斷）。一律 --message-file —— heredoc 與 -m 兩條路都會經過 shell，而上面那條 CAUTION 講的就是這一層。

Submodule 逐層 bump（由內往外）—— 選配，使用者說了才做

觸發：commit all / 全包 / 逐層 bump / bump 到主專案。沒說 = 只做單層，跳過本節。

層數依專案巢狀結構而定，不是固定三層。通則：最內層先提交內容 → 每個父層 add 子 submodule 路徑 + 提交 pointer bump → 直到主專案。每一層都是一筆獨立 commit，各自帶 trailer、各自領薪。

git -C <inner-sub> add <files>
python <UCL_Core>/Tools~/AgentCommands/git_commit.py --persona <你> --repo <inner-sub> -m "..."

git -C <parent> add <child-sub-relative-path>
python <UCL_Core>/Tools~/AgentCommands/git_commit.py --persona <你> --repo <parent> -m "Bump <child>: ..."

驗證：每層 git -C <sub> log <tracked-branch> -1 --oneline 確認落在追蹤分支（非 detached）； 父層 git diff --staged 確認只是 pointer bump；全部完成 git status 應 clean。

Anti-pattern：

• ❌ 使用者說了 commit all 卻只 commit 最內層 → 同事 pull 拿到舊 hash，編不過。 （單層模式下不是 anti-pattern，那是預設行為 —— 但必須在回報裡明說父層還指著舊 hash， 見上方 IMPORTANT。沒說 = 讓人以為東西已經到得了別人手上。）
• ❌ 沒人說 commit all 就自己 bump 到主專案 → 把未驗收的版本對同事廣播出去。
• ❌ 安裝副本沒同步（.claude / .codex / .agents）→ 正本改了但實際載入的還是舊的。 ⚠ .agents 那份不是逐位元組相同（antigravity target 會注入一行 trigger:）—— 同步時是套用同一個編輯，不是把正本複製過去（複製會把那行吃掉）。
• ❌ code 混 chat → history 噪音。

🐛 Fixes BUG-<n> —— commit 順手關掉問題回報單

修好一張 BugReport 的單之後，在 commit 訊息裡寫一行就好：

Fixes BUG-12

git_commit.py 會在公告成功之後自動跑 op=resolve 並把 SHA 掛上去， console 會印一行 🐛 BUG-12 已自動關單（<sha>）。

為什麼掛在 commit 上：修東西的人本來就要 commit —— 把關單掛在他一定會走的那條路上，就不必要求他記得再跑一支指令。 而「記得」正是那套系統不能依賴的東西（一張沒人回來關的 open 單， 跟一張還真的壞著的單長得一模一樣，還會主動誤導）。

⚠ 邊界，每一條都會咬人：

• 一則 commit 可以帶多行 Fixes BUG-a / Fixes BUG-b，各自關掉。
• 關單掛在公告成功之後 —— 公告失敗（exit 6）時單子還開著，要手動 run BugReport --arg op=resolve --arg index=<n> --arg commit_sha=<SHA>。
• 關單失敗只警告不致命（commit 已經落地了，不該讓它看起來失敗）—— 看到 ⚠ BUG-n 自動關單失敗 就手動補一次，別假設它成功了。
• ⛔ 別在訊息裡寫沒有真的修好的單號。 關單是對別人的宣告： 清單上少一筆＝所有人不再看它。

開單、修復流程與 severity 判準 → skill ucl-bug-report。

執行順序（收到「commit」指令）

0. 先判層數：使用者說了 commit all / 全包 / 逐層 bump 嗎？沒說 = 單層。
1. git status 看全貌；每個 submodule 跑 git -C <sub> status -b -s 確認分支。
2. detached HEAD → 先 switch + pull --ff-only。
3. 按分類矩陣判斷每個檔走哪筆。 3.5 機器生成的重複性檔一律交給自動 commit，這一步不是選配（見上節）： run AutoCommit --arg op=scan（＋ --arg mode=letters）看清分群 → --arg op=commit。 先做這步，剩下的 git status 就只剩「有作者的產出」—— 分類這件事交給規則，而不是交給你這一刻的注意力。 ⇒ 之後 git_commit.py 收到的每一筆都該公告領薪；發現有東西「不想公告」＝它站錯隊了， 把它移到這一步，不是去找一個關掉公告的方法。 🩸 為什麼值得先做：2026-08-17 有人把同事 staged 的 gitlink 掃進自己的 commit， 而那筆的 --name-only 清單其實印出來了 —— 印了但沒讀。縮短要讀的清單比要求自己更專心有效。
4. stage → git_commit.py 提交（trailer 與公告自動）。 單層：只做改動所在那一層，做完就停。 commit all：由內往外逐層 stage + bump。 4.5 這筆有修到 BugReport 的單嗎 → 訊息裡加 Fixes BUG-<n>（提交時自動關單，見上節）。
5. 跑 commit_payout_check.py 對帳，報告 SHA 與已領狀態給 Tim。不 push。 單層時一併報「父層仍指著舊 hash，同事 pull 拿到的還是舊版」—— 那句不是免責聲明，是這次交付真實的邊界。

💰 領薪 — 現在是自動的，但有兩件事仍要人看

規範本體：Commit_Workflow.md §9.5。

• 一則訊息一個 SHA。三層 bump = 3 筆 = 3 則。meta.sha 塞多個 SHA 會被 server 端直接 reject。
• 同 SHA 貼兩次會付兩次錢（沒有防重複保護，靠社會約束）。工具發過了就別再手動貼。
• ⚠ 先公告再被 rebase = 帳掛在一個不存在的 SHA 上。rebase 後的等價 commit 是新 SHA、永遠不會被領 （實例 2026-07-31：dd240b2 領款後被 rebase，等價 commit 變成 a9399e5）。發現對不上就重新對帳。

python <UCL_Core>/Tools~/AgentCommands/commit_payout_check.py            # 列已領 / 未領
python <UCL_Core>/Tools~/AgentCommands/commit_payout_check.py --strict   # 有未領就 exit 1

[!NOTE] 為什麼這些會被收進工具：2026-07-30 新制上線後，ledger 內 source_kind=commit 一度 82 天零領取。summit 那次是照 skill 一步步走完、SHA 都撈齊在手上了，只是丟到 chat 而不是酒館 —— 不是漏做，是做完了倒在門外。 同族的還有 trailer 手打造成的漂移（同一位 meadow 三筆 commit 出現過三種型號寫法與兩種 domain）。 寫進 skill 只能讓下一個人知道；把它變成工具的預設行為，才是讓它不再需要被記得。

---

修的是一張問題回報單 → skill ucl-bug-report（開單 / 修復流程 / severity 判準；訊息記得帶 Fixes BUG-<n>）。