Merge pull request '釋出：收尾寫執行狀態事件，並修好自家腳本路徑' (#37) from develop into master

Reviewed-on: #37
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

.agents/plugins/marketplace.json

@@ -13,6 +13,14 @@
       },
       "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）"
     },
+    {
+      "name": "jsc-assist",
+      "source": {
+        "source": "url",
+        "url": "https://gitea.jsc.idv.tw/plugins/assist.git"
+      },
+      "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_* wiki 頁）"
+    },
     {
       "name": "jsc-cli",
       "source": {
@@ -43,7 +51,7 @@
         "source": "url",
         "url": "https://gitea.jsc.idv.tw/plugins/hooks.git"
       },
-      "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄"
+      "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查"
     },
     {
       "name": "jsc-log",
@@ -75,7 +83,7 @@
         "source": "url",
         "url": "https://gitea.jsc.idv.tw/plugins/review.git"
       },
-      "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組"
+      "description": "程式碼審查：Refactoring 壞味道六組、註解規範、淺模組"
     },
     {
       "name": "jsc-sdlc",
@@ -83,7 +91,7 @@
         "source": "url",
         "url": "https://gitea.jsc.idv.tw/plugins/sdlc.git"
       },
-      "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）"
+      "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）"
     }
   ]
 }

.claude-plugin/marketplace.json

@@ -13,6 +13,14 @@
       },
       "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）"
     },
+    {
+      "name": "jsc-assist",
+      "source": {
+        "source": "url",
+        "url": "https://gitea.jsc.idv.tw/plugins/assist.git"
+      },
+      "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_* wiki 頁）"
+    },
     {
       "name": "jsc-cli",
       "source": {
@@ -43,7 +51,7 @@
         "source": "url",
         "url": "https://gitea.jsc.idv.tw/plugins/hooks.git"
       },
-      "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄"
+      "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查"
     },
     {
       "name": "jsc-log",
@@ -75,7 +83,7 @@
         "source": "url",
         "url": "https://gitea.jsc.idv.tw/plugins/review.git"
       },
-      "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組"
+      "description": "程式碼審查：Refactoring 壞味道六組、註解規範、淺模組"
     },
     {
       "name": "jsc-sdlc",
@@ -83,7 +91,7 @@
         "source": "url",
         "url": "https://gitea.jsc.idv.tw/plugins/sdlc.git"
       },
-      "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）"
+      "description": "開發生命週期：規劃、分析、實作、維護（wiki 追蹤）"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-git",
-  "version": "0.0.4",
+  "version": "0.1.8",
   "description": "Commit 分組認可與 Push Request 建立",
   "skills": "./skills",
   "author": {
@@ -13,5 +13,12 @@
     "git",
     "skills",
     "cross-tool"
-  ]
+  ],
+  "jsc": {
+    "requires": {
+      "jsc-gitea": ">=0.1.8",
+      "jsc-hooks": ">=0.2.8",
+      "jsc-meta": ">=0.2.2"
+    }
+  }
 }

.codex-plugin/plugin.json

@@ -1,6 +1,13 @@
 {
   "name": "jsc-git",
-  "version": "0.0.4",
+  "version": "0.1.8",
   "description": "Commit 分組認可與 Push Request 建立",
-  "skills": "./skills"
+  "skills": "./skills",
+  "jsc": {
+    "requires": {
+      "jsc-gitea": ">=0.1.8",
+      "jsc-hooks": ">=0.2.8",
+      "jsc-meta": ">=0.2.2"
+    }
+  }
 }

README.md

@@ -18,6 +18,20 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 > 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。
 
+## 工具
+
+| 檔案 | 用途 |
+| --- | --- |
+| `tools/base-branch.sh` | 決定 PR 基底分支。兩種模式：不帶旗標時，呼叫方傳入的分支最優先，沒傳才依序試 develop、main、master；`--derive [分支]` 從分支名推出階梯的上一階。一律確認分支存在於遠端，找不到就回傳非零。「沒傳」看參數個數，傳入空字串算錯誤，不會退回 develop |
+| `tools/slugify.sh` | 把類型與英文短語組成 ASCII 分支名 `{type}/{slug}`；輸入含非 ASCII 或 slug 化後為空，就回傳非零並要求先翻譯成英文短語。第一個參數可以帶斜線，所以連叫兩次就組得出 `feat/{功能}/{子功能}` |
+| `tools/pick-type.sh` | 從一組 commit 型別中選出優先度最高的一個，是型別優先序的唯一真實來源。參數或標準輸入都收，commit 標題整行餵進來也認得出型別；沒有輸入回傳 2，輸入裡沒有階梯表型別回傳 3 |
+
+## PR 階梯
+
+階梯規則的唯一真實來源是 `jsc-meta` 的 `references/guidelines.md` 「PR 分支階梯」一節，本檔不再抄一份。基底一律由 `tools/base-branch.sh --derive` 推導，不手挑。
+
+腳本這一側的行為：推不出唯一合法基底就回傳 7 並中止，由呼叫端問使用者，不猜也不退回 develop。功能主幹不在遠端時，自動以 develop 為起點建立並推上去，再把建立了哪一條分支印到 stderr。分支名只允許 ASCII（小寫、數字、連字號、斜線），中文簡述先過 `tools/slugify.sh`，`--derive` 不收非 ASCII 分支名。
+
 ## Skills 目錄
 
 呼叫方式：Claude / Antigravity `/jsc-git:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
@@ -26,11 +40,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 ### `commit`
 
-追蹤所有檔案變更，依 Commit 格式 `{類型}({需求 or 功能}): {訊息}` 將同類型與同需求的變更認可在一起。訊息格式三選一：完整版（What/Why/How/Who）、簡易版（依 git diff 總結一句）、自訂。
+追蹤所有檔案變更，依 Commit 格式 `{類型}({需求 or 功能}): {訊息}` 將同類型與同需求的變更認可在一起。盤點與註解掃描兩件事同時跑，分組草擬要吃盤點的檔案清單，排在盤點之後，可以與掃描並行；掃描要求的修正仍在第一個 commit 之前完成；註解掃描跑 `jsc-hooks` 的 `comment-scope.sh sweep`，攔下夾帶文件相關資訊的註解，腳本不在本機就跳過並在回報中說明，不中止認可。`git add -A` 後單次提交與非繁中訊息由 `jsc-hooks` 的 PreToolUse `Bash` 閘門在程式層擋下，只有 claude 有這道閘門，其餘四支 CLI 仍靠技能內文的規則。訊息格式三選一：完整版（What/Why/How/Who）、簡易版（依 git diff 總結一句）、自訂。由 `pr` 呼叫進來時不查 PR，結果由 `pr` 傳入；單獨呼叫時查一次 `gitea.sh pr-of-branch`，查到就交給 `pr` 校準標題、描述與前置 PR 依賴。
 
 ### `pr`
 
-先認可所有變更，再從 develop / main 建立目標分支（分支名只允許 ASCII：類型取 commit 優先度最高者，標題翻譯成英文短語後 slug 化）、push、以範本描述建立 Gitea PR。
+呼叫方傳入的基底先驗合法性，再認可所有變更，然後依階梯命名目標分支、push、以範本描述建立 Gitea PR。基底分支由 `base-branch.sh --derive` 從分支名推出上一階；呼叫方傳入的基底與推導結果不同，就當成越級擋下並說明正確階梯，不會悄悄改目標。分支名只允許 ASCII：類型交給 `pick-type.sh` 選，功能與標題先翻譯成英文短語再 slug 化。PR 標題另寫一句繁體中文摘要，說明這條 PR 做了什麼，不套用分支名：分支名給機器判階梯，標題給人看審查列表。分支命名完成就同時啟動 PR 查詢與描述草擬，不等 push。整條呼叫鏈只查一次 `gitea.sh pr-of-branch`；分支已有開啟中的 PR 時不重開，改用該次查詢帶回的標題、base 與描述比對三項，只有不一樣的那幾項才送出 API 呼叫；標題只問還描述不描述得了目前的內容，不拿分支名比對，免得每跑一次就把繁中標題改回 slug 並通知所有審查者。收尾回報使用 `jsc-meta/references/pr-report.md` 的 PR 資訊表格。
 
 <!-- JSC-SKILLS:END -->
 

plugin.json

@@ -1,6 +1,13 @@
 {
   "name": "jsc-git",
-  "version": "0.0.4",
+  "version": "0.1.8",
   "description": "Commit 分組認可與 Push Request 建立",
-  "skills": "./skills/"
+  "skills": "./skills/",
+  "jsc": {
+    "requires": {
+      "jsc-gitea": ">=0.1.8",
+      "jsc-hooks": ">=0.2.8",
+      "jsc-meta": ">=0.2.2"
+    }
+  }
 }

references/behaviors.md

@@ -0,0 +1,23 @@
+# jsc-git 技能行為清單
+
+本頁記錄 jsc-git 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
+
+## commit
+
+| 項目 | 內容 |
+| --- | --- |
+| 觸發時機 | 工作區有待提交的檔案變更時叫用。`jsc-git:pr` 的步驟 2 也會叫用它。要推送或開 PR 時不叫用這一支，改叫 `jsc-git:pr`。 |
+| 關鍵步驟 | 用 `git status --porcelain` 盤點所有變更路徑、同時跑 `jsc-hooks/hooks/comment-scope.sh sweep` 掃過工作區的註解、依「同型別加同需求或功能」把路徑分組、每組一次 `git add` 加一次 `git commit`、訊息寫成 `{type}({scope}): {message}`、校準本分支既有的 PR、最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-git:commit {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。 |
+| 外部呼叫 | `git status --porcelain`、`git add`、`git commit`、`git diff`、`jsc-hooks/hooks/comment-scope.sh sweep`、`jsc-gitea/tools/gitea.sh pr-of-branch`（僅獨立執行時）、`jsc-git:pr`（校準既有 PR）、`jsc-ask:ask`（問訊息風格）。分組與訊息草稿交給 sub agent 處理。 |
+| 完成條件 | 註解掃描退出 0，或每一則剩餘警告都被判為誤判並說明理由，或腳本不在這台機器上並回報。`git status --porcelain` 印出空白。步驟 5 回報四種結果之一：因為 `jsc-git:pr` 是呼叫方而略過查詢、本分支沒有開啟中的 PR、`jsc-git:pr` 回報三個項目各自相符或已更新、查詢失敗並指名失敗原因。收尾一定要寫一筆 `skill-end` 狀態事件：每一組都提交完且工作區乾淨是 `ok`，`jsc-hooks` 的 Bash 閘門把提交擋在門外是 `blocked`，提交都進去了但既有 PR 沒校準成功是 `degraded`，`git add` 或 `git commit` 中途回非零、工作區還髒是 `failed`，盤點結果是空的、根本沒有變更可提交是 `aborted`。 |
+| 可驗證跡象 | 本地 git 歷史多出一批 commit，`git log --oneline` 看得到，每一筆標題是 `{type}({scope}): {message}` 且訊息含繁體中文。工作區乾淨。註解掃描要求的修正直接改在原始碼檔案裡。獨立執行且本分支有開啟中的 PR 時，Gitea 上那條 PR 的標題、描述、前置依賴由 `jsc-git:pr` 更新。這一支不推送、不建立 PR、不寫 wiki 頁。跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-git:commit`，`status` 與 `exit` 兩欄對得上上一列講的判準，沒有變更可提交那一輪看得到 `aborted`；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。 |
+
+## pr
+
+| 項目 | 內容 |
+| --- | --- |
+| 觸發時機 | 工作做完要送審時叫用。既有 PR 在新 commit 之後要重新同步時也叫用。只想提交不想推送時不叫用這一支，改叫 `jsc-git:commit`。 |
+| 關鍵步驟 | 先用 `jsc-git/tools/base-branch.sh {呼叫方基底}` 驗證呼叫方傳進來的基底、叫 `jsc-git:commit` 提交全部變更、用 `jsc-git/tools/pick-type.sh` 從 commit 標題選出型別、用 `jsc-git/tools/slugify.sh` 組出階梯狀目標分支名、用 `jsc-git/tools/base-branch.sh --derive {目標分支}` 推導基底並和呼叫方基底比對、以 `git checkout -b {目標分支} origin/{基底分支}` 建分支並 `git push -u origin` 推上去、用 `gitea.sh pr-of-branch` 查一次開啟中的 PR、沒有就用 `gitea.sh pr-create` 開新 PR 並用 `gitea.sh pr-depend` 掛前置依賴、已經有就只更新標題、描述、前置依賴三項裡不同的那幾項、回覆已處理的 PR 意見、回報，最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-git:pr {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。PR 標題寫一句繁體中文摘要，說明這條 PR 做了什麼，不套用分支名；校準既有 PR 時只問標題還描述不描述得了目前的內容，不拿分支名比對。 |
+| 外部呼叫 | `jsc-git/tools/base-branch.sh`、`jsc-git/tools/pick-type.sh`、`jsc-git/tools/slugify.sh`、`templates/pr-description.md`、`jsc-git:commit`、`jsc-gitea/tools/gitea.sh` 的 `pr-of-branch`、`pr-create`、`pr-edit`、`pr-depend`、`comment-reply`、`jsc-gitea:wiki`（讀 PLAN 頁與 ANALYZE 頁）、`jsc-ask:ask`（基底衝突與分支不存在時發問）、`jsc-meta/references/guidelines.md` 的「PR 分支階梯」、`jsc-meta/references/pr-report.md`、`git checkout`、`git cherry-pick`、`git push`、`git ls-remote`。分支標題摘要與描述草稿交給 sub agent 處理。 |
+| 完成條件 | 握有一個 PR 網址，送出的標題是一句繁體中文摘要，不是分支名。前置依賴已經處理完：`pr-depend` 印出 `OK` 行，或 PR 標題冠上 `WIP:` 且描述指名前置 PR，或描述寫「無」前置 PR 並在回報裡說明。既有 PR 的三個校準項目各自回報為相符或已更新，標題那一項說明拿什麼內容去判定，送出的 API 呼叫數等於不同的項目數。每一則已處理的意見握有回覆連結或記下失敗理由。回報含 `{owner}/{repo}`、PR 編號、PR 網址、PR 摘要四欄，並指名基底分支、目標分支、更新過的校準項目、自動建立的功能主幹、沒回覆到的意見。收尾一定要寫一筆 `skill-end` 狀態事件：拿到 PR 網址且前置依賴處理完是 `ok`，`base-branch.sh` 回 3、4、7、8、9 讓分支還沒推上去就停住是 `blocked`，`pr-depend` 回 4 退成 `WIP:` 或有意見沒回覆到是 `degraded`，`pick-type.sh` 回 3、推送失敗、`pr-create` 回 4、`pr-edit` 回非零是 `failed`，`pick-type.sh` 回 2 代表沒有可提交的變更、沒有 PR 好開，是 `aborted` 不是 `failed`，使用者在確認關卡喊停也是 `aborted`。 |
+| 可驗證跡象 | origin 上多出目標分支的 ref，`git ls-remote --heads origin` 查得到。Gitea 上多出一條 PR，標題是一句繁體中文摘要、分支名仍是 ASCII，兩者不一樣。既有 PR 的標題與描述只在內容變了才被 `pr-edit` 改過，依賴被 `pr-depend` 掛上。PR 描述照 `templates/pr-description.md` 生成，各節不留空。功能主幹不在 origin 上時，`jsc-git/tools/base-branch.sh --derive` 會自動從 develop 建出 `{類型}/{功能}/main` 並推上 origin。本地 git 歷史含 `jsc-git:commit` 建立的 commit，目前分支切到目標分支。PR 意見的回覆留在 Gitea 那幾則意見底下。描述檔草稿寫在暫存檔。這一支不寫 wiki 頁，只讀 PLAN 頁與 ANALYZE 頁。跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-git:pr`，`status` 與 `exit` 兩欄對得上上一列講的判準；沒有可提交的變更那一輪，事件上是 `aborted` 加結束碼 2，和開出 PR 的那一輪一眼分得開；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。 |

skills/commit/SKILL.md

@@ -1,15 +1,46 @@
 ---
 name: commit
-description: Group all pending file changes by conventional type and feature, then commit each group as {type}({scope}): {message}. Message style is full (What/Why/How/Who), brief (one line from git diff), or custom, chosen via decision tree. Use whenever changes must be committed; not for push or PR creation.
+description: 'Group all pending file changes by conventional type and feature, then commit each group as {type}({scope}): {message}. Before committing, sweep the working tree with jsc-hooks/hooks/comment-scope.sh so no comment carrying document tracking information enters a commit. Message style is full (What/Why/How/Who), brief (one line from git diff), or custom, chosen via decision tree. Once the commits land, an open PR on the current branch gets its title, description, and prerequisite dependency calibrated through jsc-git:pr. Use whenever changes must be committed; not for push or PR creation.'
 ---
 
 # commit — group and commit file changes
 
 ## Steps
 
-1. Track every file change: inspect all changes with `git status --porcelain` first, then `git add` group by group. Never `git add -A` and commit everything at once.
-2. Group the changes by same type plus same requirement or feature. One group is one commit.
-3. Commit each group with the format `{type}({requirement or feature}): {message}`.
+1. Track every file change: inspect all changes with `git status --porcelain` first. That inventory is this step's own work; the `git add` that follows is group by group, one add per group as step 4 commits it, never one bulk add here. `git add -A` followed by one bulk commit is blocked in code by the `jsc-hooks` PreToolUse `Bash` guard, which rejects that command pair before it runs. Only claude has a PreToolUse stage; on codex, copilot, antigravity and kiro that guard never fires, so on those four CLIs this step is the only thing holding the rule — add group by group there as well. Done when `git status --porcelain` has run and its full path list is held. That list is what step 3 groups, so this step never waits on the grouping.
+2. Sweep the comments about to be committed: run `jsc-hooks/hooks/comment-scope.sh sweep` over this working tree. Start the sweep at the same time as step 1's inventory: both only read the working tree, and neither needs the other's result. Step 3's grouping is not part of that pair — it needs step 1's path list — but it may run while this sweep is still going. Every fix the sweep demands still lands before step 4 runs the first commit. A code comment states why the code is written this way, never where the work is documented; the rule text and its allow list live in one place only, `jsc-review/references/comment-scope.md`.
+   - The script exits 0 in silence when it finds no git working tree and when `jsc-hooks` is not on this machine. **If the script is not found, skip this step, say so in the report and commit anyway** — missing infrastructure is not a violation.
+   - Exit 2 means a hit. Fix every comment line the warning points at, in place, then run the sweep again until it exits 0, and commit only after that.
+   - The warning is written for a person and a model to judge, **not a hard block**. When it is a false positive, say plainly why and carry on with the commit; never delete a useful comment just to keep the script quiet.
+   - Done when one of these is true and reported: the sweep exited 0, or every remaining warning is reported with the reason it is a false positive, or the script was not found on this machine.
+3. Group the changes by same type plus same requirement or feature. One group is one commit. Grouping takes step 1's path list as its input, so it starts once that inventory is held; step 2's sweep may still be running alongside it. Done when every path on step 1's list sits in exactly one group, and each group carries one type and one requirement or feature.
+4. Commit each group with the format `{type}({requirement or feature}): {message}`. Done when `git status --porcelain` returns empty; report done only then.
+5. Calibrate the open PR of this branch. Who called this run decides whether a lookup happens at all:
+   - `jsc-git:pr` called this run → skip the lookup. That skill runs the single open-PR lookup of the chain in its own step 6 and owns the calibration from there. Done when the report names `jsc-git:pr` as the caller and states that the lookup was skipped.
+   - This run is standalone → look the PR up once with `jsc-gitea/tools/gitea.sh pr-of-branch {owner}/{repo} {current branch}`. On exit 0 the script prints line 1 `number<TAB>{PR number}`, line 2 `title<TAB>{title}`, line 3 `base<TAB>{base}`, line 4 the marker `body`, and line 5 onward the description.
+     - Exit 0 → hand the PR number together with the returned title, base and description to `jsc-git:pr`, which compares title, description and prerequisite dependency and updates only what differs, without repeating the lookup. That hand-off does not loop back here: the tree is already clean, and `jsc-git:pr` as the caller makes this step skip its lookup.
+     - Exit 3 (no open PR on this branch) → nothing to calibrate.
+     - Exit 2 (usage error) → the `{owner}/{repo}` or the branch argument is missing or malformed. Correct the arguments and rerun.
+     - Exit 4 (API call failed) → report the failure and leave the PR state as unknown. Never read a failed call as "no open PR": that leaves a stale title on a branch that just gained commits.
+     - Any other non-zero → treat it as exit 4.
+   - Done when the report states exactly one of these: the lookup was skipped because `jsc-git:pr` called this run, the branch has no open PR, `jsc-git:pr` reported each of the three items as matched or updated, or the lookup failed and the failure is named.
+6. Record how this run ended, as the very last thing this skill does:
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-git:commit {status} {exit} "{detail}"`
+
+   Resolve that path the way step 2 already resolves `jsc-hooks/hooks/comment-scope.sh` — the sibling plugin directory, no separate lookup rule for this one call. **A missing script is not a failure here: skip this step in silence and let the run end as it stands**, the same way step 2 commits anyway when the sweep is not installed. The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. Commits that landed stay landed whether or not the run could be recorded.
+
+   | status | This skill's case |
+   | --- | --- |
+   | `ok` | Every group is committed, `git status --porcelain` prints nothing, and step 5 stated one of its four outcomes. A step 2 sweep that was skipped because the script is not on this machine is still `ok` — say so in `{detail}`, since a run judged without the sweep is worth telling apart from one the sweep passed |
+   | `blocked` | The `jsc-hooks` PreToolUse `Bash` guard rejected the commit before git ran — a bulk `git add -A` pair, or a message carrying no Traditional Chinese — so no commit landed and the working tree is exactly as it was |
+   | `degraded` | Every group is committed and the tree is clean, but the close-out is short: step 5's `pr-of-branch` returned 4, or the `jsc-git:pr` calibration failed, so the open PR still carries a title written before these commits |
+   | `failed` | A `git add` or `git commit` returned non-zero part-way through, leaving some groups committed and the tree dirty. Report the group that broke; a partial commit set is what the next run has to reconcile |
+   | `aborted` | Step 1's inventory came back empty, so there was nothing to commit and nothing was attempted. Also the user stopping the run at the grouping or the message-style question. This is not a success: a run that committed nothing must not read like a run that committed everything |
+
+   `{exit}` is the exit code of whatever decided the status, `0` for `ok`. `{detail}` is one short line well under 200 characters: group and commit counts plus exit codes, never commit messages, branch names, or personal data.
+
+   Done when the command has run, or the script was absent and this step was skipped.
 
 ## Type table
 
@@ -36,5 +67,5 @@ Ask the user per the `jsc-ask:ask` rules. Skip the question when the question re
 ## Rules
 
 1. The grouping and message drafting details **MUST run as a sub agent**. The main agent only confirms the grouping and runs the commits.
-2. Write messages in UTF-8 Traditional Chinese (the type and scope stay in English), per the STE100 output rule.
-3. Never push. Push and PR belong to `jsc-git:pr`.
+2. Write messages in UTF-8 Traditional Chinese (the type and scope stay in English), per the STE100 output rule. The `jsc-hooks` PreToolUse `Bash` guard rejects a `git commit` whose message carries no Traditional Chinese. That guard runs on claude only; on codex, copilot, antigravity and kiro nothing blocks such a message, so on those four CLIs this rule carries the whole load.
+3. Never push, and never create a PR. Step 5 only calibrates a PR that already exists; pushing and creating PRs belong to `jsc-git:pr`.

skills/pr/SKILL.md

@@ -1,29 +1,105 @@
 ---
 name: pr
-description: Commit all changes via jsc-git:commit, create a target branch named from the highest-priority commit type plus a summarized title, push, then open a Gitea PR with the templated description against the base branch the caller passed in (falling back to develop, main, master only when none was given). Branch priority is revert > fix > feat > perf > refactor > test > docs > style > chore. Use when work is ready for review; not for plain commits.
+description: Commit all changes via jsc-git:commit, name a ladder-shaped target branch, derive the base with jsc-git/tools/base-branch.sh (sub-feature → feat/{feature}/main → develop → master; fix → develop → master, no level skipping), push, then open a Gitea PR with the templated description. When the branch already has an open PR, compare its title, description, and prerequisite dependency, and update only the items that differ. Use when work is ready for review, or when an open PR needs re-syncing after new commits; not for plain commits.
 ---
 
 # pr — create a Push Request
 
+The ladder rules live in one place only: section 「PR 分支階梯」 of `jsc-meta/references/guidelines.md`. `jsc-git/tools/base-branch.sh --derive` is the running implementation of that section. Read the rung a branch belongs to there; never hand-pick a base, and never restate the ladder table in this file.
+
+Every script path in this file starts with its plugin's own directory name — `jsc-git/tools/…` for this plugin's, `jsc-gitea/tools/…` and `jsc-hooks/tools/…` for the others — and is resolved against the tool root the caller supplies, never against this skill's own directory. These three scripts sit at the plugin root, not under `skills/pr/`, so dropping the plugin directory name leaves a path that resolves against whatever the current directory happens to be — the right script inside this repo, a different domain's script outside it, or nothing at all and exit 127. That failure is worse than it looks: step 4 says never hand-pick a base, and an agent that cannot run the deriver is one step away from picking one anyway, which turns a wrong path into a PR opened against the wrong rung.
+
 ## Steps
 
-1. Call `jsc-git:commit` to commit every file change first.
-2. Pick the base branch. **A base branch passed in by the caller wins over everything else** — `jsc-sdlc:implement` passes the analysis page's source branch, and silently retargeting that PR at `develop` would merge a single work package straight past the feature branch it belongs to. Only when no caller supplied one: use `develop` when it exists on the remote, else `main`, else `master`. Verify the chosen base exists on the remote (`git fetch --prune origin` first, then `git branch -r`); it does not exist → report and stop, never fall back silently.
-3. Create the target branch from the remote base branch:
-   1. Take the type with the highest priority across all commits: `revert > fix > feat > perf > refactor > test > docs > style > chore`.
-   2. Summarize one title from all commit messages.
-   3. Branch names allow **ASCII only**; always slugify as `{type}/{requirement or feature}-{title}`. Translate the requirement and title into a short English phrase first, then call `tools/slugify.sh {type} {phrase}` to produce the final slug (example: translate a non-English request to English first, then slugify — "export report" → export-report → feat/order-export-report). No spaces, parentheses, colons, or any non-ASCII character.
-4. Run `git push -u origin {target branch}`.
-5. Create the PR: `jsc-gitea/tools/gitea.sh pr-create {owner}/{repo} {target branch} {base branch} "{branch name}" {description file}`.
-   - Title = branch name.
+1. **Validate the caller's base first.** A caller may pass a base in (`jsc-sdlc:implement` passes the analysis page's source branch). Whether that base is legal depends on origin alone, not on the target branch name, so settle it before any naming work. Skip the whole step when no caller base was passed, and record "no caller base" for step 4. Otherwise run `jsc-git/tools/base-branch.sh {caller base}` and branch on its exit code:
+   - 0 → keep the printed name; step 4 cross-checks it against the derived base.
+   - 2 (too many arguments) → the base arrived as several words. Quote it as one argument and rerun.
+   - 3 (cannot reach origin) → stop and report that origin is unreachable. Nothing downstream works without the remote.
+   - 4 (caller base not on origin) → stop, report the caller base, and ask the user per the `jsc-ask:ask` rules which existing branch was meant. Never substitute another branch.
+   - 5 (develop, main and master all missing on origin) → the script only reaches this code with no argument, so the caller base was dropped on the way in. Stop and report that the argument never reached the script.
+   - 6 (empty string) → the caller's base variable is unset. Stop and ask the caller for the real branch name. Never rerun with the argument removed: that silently falls back to `develop`.
+   - 7, 8, 9 → these belong to `--derive` mode only. Seeing one means the wrong mode ran. Stop and report which command line was used.
+   - Done when the script printed one branch name, or the run is recorded as having no caller base.
+2. Call `jsc-git:commit` to commit every file change. Tell it that `jsc-git:pr` is the caller, so it skips its own open-PR lookup — step 6 here is the only such lookup in this chain. Done when `git status --porcelain` prints nothing.
+3. Build the target branch name in ladder shape:
+   1. Pipe the subjects of step 2's commits into `jsc-git/tools/pick-type.sh` (`git log --format=%s {range} | jsc-git/tools/pick-type.sh`), which owns the type priority order. Exit 0 → take the printed type. Exit 2 (no input) → step 2 produced no commits, so there is nothing to open a PR for; stop and report. Exit 3 (no ladder type in the input) → stop, report the subjects, and correct them to `{type}({scope}): {message}` before retrying. Done when the script printed exactly one type.
+   2. Summarize one title from all commit messages, as a single Traditional Chinese sentence saying what this PR does. This sentence is the PR title steps 7 and 8 use; step 3.3 only borrows its meaning to build the ASCII slug. Done when one title line covers every commit in the range and reads as one Traditional Chinese sentence.
+   3. Translate the feature and the title into short English phrases, then build the name with `jsc-git/tools/slugify.sh`. `fix` takes one call: `jsc-git/tools/slugify.sh fix {change phrase}` → `fix/order-export-crash`. Every other type takes two calls, feeding the first result back in as the type: `jsc-git/tools/slugify.sh feat {feature phrase}` → `feat/order-export`, then `jsc-git/tools/slugify.sh feat/order-export {sub-feature phrase}` → `feat/order-export/report-filter`. Done when the name has the shape its ladder row requires; exit 2 (non-ASCII input) or exit 3 (empty slug) → re-translate into an English phrase and retry, never hand-build the branch name.
+   - The name is the only input step 6's lookup and the description draft need. Start both the moment this step ends, and run them alongside steps 4 and 5; neither waits for the push.
+4. Resolve the base branch:
+   - Run `jsc-git/tools/base-branch.sh --derive {target branch}`. Exit 0 → the script printed one branch name.
+   - Exit 2 (too many arguments) → the branch name arrived as several words. Quote it as one argument and rerun.
+   - Exit 3 (cannot reach origin) → stop and report that origin is unreachable.
+   - Exit 4, 5 or 6 → these belong to caller mode. Seeing one means the `--derive` flag was dropped. Rerun with the flag.
+   - Exit 7 (no unique legal base), 8 (derived base missing on origin) or 9 (auto-create failed) → report the script's message and stop. Never fall back to `develop`.
+   - Step 1 held a caller base → compare the two names. Same → use it. Different → the pair skips a rung, so stop, report the caller base, the derived base, and the ladder row that applies per `jsc-meta/references/guidelines.md`, and ask the user per the `jsc-ask:ask` rules whether to rename the branch or correct the caller base. Never silently retarget the PR.
+   - The feature trunk missing on origin is not an error: the script creates it from `develop`, pushes it, and prints 「已自動從 develop 建立功能主幹 {分支}」 to stderr. Capture that line; step 9 has to report it.
+   - Done when one base name is held, and the caller base either matched it or the user settled the mismatch.
+5. Put the branch on origin, in one pass: run `git checkout -b {target branch} origin/{base branch}` so the branch starts at the remote base, bring step 2's commits onto it (`git cherry-pick` them when they landed on another branch), then run `git push -u origin {target branch}`. Done when `git branch --show-current` prints the target branch, `git log --oneline origin/{base branch}..HEAD` lists exactly step 2's commits, and `git ls-remote --heads origin` shows the target branch's ref.
+6. Look up the open PR of the target branch: `jsc-gitea/tools/gitea.sh pr-of-branch {owner}/{repo} {target branch}`. Launch it as soon as step 3 named the branch. This is the only open-PR lookup in the whole chain: step 8 reuses this output and never calls `pr-get`. On exit 0 the script prints line 1 `number<TAB>{PR number}`, line 2 `title<TAB>{title}`, line 3 `base<TAB>{base}`, line 4 the marker `body`, and line 5 onward the description.
+   - Exit 0 → hold the PR number, title, base and body; skip step 7 and go to step 8, because the PR exists and only needs calibrating.
+   - Exit 3 (no open PR on that branch) → go to step 7 and create one.
+   - Exit 2 (usage error) → the `{owner}/{repo}` or the branch argument is missing or malformed. Correct the arguments and rerun.
+   - Exit 4 (API call failed) → stop and report the failure. Never read a failed call as "no open PR": that opens a second PR on a branch that already has one.
+   - Any other non-zero → treat it as exit 4 and stop.
+   - Done when either the PR number plus its title, base and body are held, or exit 3 confirmed the branch has no open PR.
+7. Create the PR, then hang its prerequisite on it. Run `jsc-gitea/tools/gitea.sh pr-create {owner}/{repo} {target branch} {base branch} "{branch name}" {description file}`. Ask the user to confirm before this call runs.
+   - Title = step 3.2's summary: one Traditional Chinese sentence saying what this PR does. Never pass the branch name as the title. A branch name and a title carry different jobs — the branch name is a machine-readable ASCII slug that the ladder and `jsc-git/tools/base-branch.sh` parse, while the title is the one line a human reads in the review list, where a column of long slugs shows who touched the repo but never what changed. The STE100 output rule in `jsc-meta/references/ste100.md` names PR titles and descriptions explicitly, and a hook enforces it; binding the title to the branch name is what put the two rules in conflict, so the title gives way to the language rule and the branch name stays ASCII per rule 4.
    - Write the description into a temp file first, using `templates/pr-description.md` (a Traditional Chinese template; the generated description stays in Traditional Chinese per the STE100 output rule).
-6. **Prerequisite PR blocking**: when the description lists a prerequisite Push Request, run
+   - Exit 0 → the command prints a PR URL; keep it.
+   - Exit 2 (description file not found) → write the description file, then rerun.
+   - Exit 1 → an older `gitea.sh`, whose `pr-create` never checks the description file and lets the read throw instead. Same cause and same handling as exit 2: correct the description file path, then rerun.
+   - Exit 4 (the API rejected the request) → report the script's message and stop. Never retry against a different base.
+   - Any other non-zero → treat it as exit 4 and stop.
+
+   **Prerequisite PR blocking**: with the PR URL in hand, and only when the description lists a prerequisite Push Request, run
    `jsc-gitea/tools/gitea.sh pr-depend {owner}/{repo} {this PR number} {prerequisite owner}/{repo} {prerequisite PR number}`
-   to add the dependency. Gitea then blocks merging until the prerequisite PR closes. If the API is unavailable, degrade: prefix the PR title with `WIP:` (Gitea blocks merging natively) and remove it once the prerequisite is done.
-7. Report the PR URL.
+   to add the dependency. Gitea then blocks merging until the prerequisite PR closes.
+   - Exit 0 → the command prints `OK {owner}/{repo}#{number} depends on ...`.
+   - Exit 2 (usage error) → an argument is missing or malformed. Correct it and rerun.
+   - Exit 4 (the dependency API call failed) → degrade: prefix the PR title with `WIP:`, which Gitea blocks merging on natively, and record in the PR description that the prefix comes off once the prerequisite PR closes.
+   - Any other non-zero → treat it as exit 4 and degrade the same way.
+
+   Done when a PR URL is held, the title sent to `pr-create` was the Traditional Chinese sentence and not the branch name, **and** the prerequisite is settled — `pr-depend` printed its `OK` line, or the PR title starts with `WIP:` and the description names the prerequisite PR, or the description names no prerequisite and that is stated. A PR created here goes straight to step 9.
+8. **Calibrate an existing PR** (step 6 returned a PR number): compare three items against what this run produced, using the title, base and description step 6 already returned. Send an API call only for the items that differ.
+    1. Title against what this PR now contains. Read the existing title and ask one question only: does it still describe the PR's current content, now that step 2's commits are in? Yes → leave it alone. No → draft a replacement, again one Traditional Chinese sentence saying what this PR does. The branch name never enters this comparison. Comparing them would rewrite a good Traditional Chinese title back into an ASCII slug on every run and notify every reviewer each time, which is the opposite of what a title is for: the branch name is the machine's handle on the ladder, the title is what a human reads in the review list.
+    2. Description against a freshly drafted description from `templates/pr-description.md`.
+    3. Prerequisite PR dependency against the one the description names.
+    - Title or description differs → write the new description to a temp file and run `jsc-gitea/tools/gitea.sh pr-edit {owner}/{repo} {pr number} "{title}" {description file}`, which carries both items in one call. Ask the user to confirm before this call runs. Exit 0 → updated. Exit 2 (description file not found) → write the file and rerun. Exit 4 or any other non-zero → report the script's message and stop, and say plainly that the PR still holds its old title and description.
+    - The dependency differs → run `pr-depend` with the exit code branching of step 7. Ask the user to confirm before this call runs.
+    - All three match → change nothing. Every needless edit notifies every reviewer, so silence is the correct outcome here.
+    - Done when each of the three items is reported as either matched or updated, the title verdict states which content the title was judged against rather than any branch name, and the number of API calls made equals the number of items that differed.
+9. Reply to the handled comments, then report the run.
+
+    If this run follows PR comment fixes and the caller supplied handled comment ids, reply to each comment first with `jsc-gitea/tools/gitea.sh comment-reply`. The reply content and the comment type mapping live in `jsc-meta/references/pr-report.md`; the exit codes belong here. Run one call per handled comment and branch on each call's own exit code:
+    - Exit 0 → the command prints the reply link. Keep it against that comment id.
+    - Exit 2 (the reply file is missing, or the kind is not `issue`, `review` or `inline`) → correct the reply file path or the kind, then rerun that one call.
+    - Exit 4 (the API call failed), or any other non-zero → record that comment id with the reason it failed and carry on with the remaining comments. One failed reply never ends the round.
+
+    Then report the PR with the table format in `jsc-meta/references/pr-report.md`, followed by the base branch, the target branch, which of the three calibration items were updated, the feature trunk the script auto-created when step 4 printed that line, and every comment that got no reply.
+
+    Done when every handled comment holds either a reply link or a recorded failure reason, and the report includes the PR table columns `{owner}/{repo}`, PR number, PR URL and PR summary, names all branch and calibration details, and names the comments that got no reply.
+10. Record how this run ended, as the very last thing this skill does:
+
+    `jsc-hooks/tools/report-status.sh skill-end jsc-git:pr {status} {exit} "{detail}"`
+
+    Resolve that path the way this file already resolves `jsc-gitea/tools/gitea.sh` — the sibling plugin directory, no separate lookup rule for this one call. **A missing script is not a failure here: skip this step in silence and let the run end as it stands.** The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. A PR that is open stays open whether or not the run could be recorded.
+
+    | status | This skill's case |
+    | --- | --- |
+    | `ok` | A PR URL is held, the prerequisite is settled by a `pr-depend` exit 0 or by a description that names none, and every handled comment holds a reply link. Calibrating an existing PR and changing none of the three items is `ok` as well: silence is the correct outcome there |
+    | `blocked` | The ladder refused before anything was pushed: `base-branch.sh` exit 3 (origin unreachable), exit 4 (the caller base is not on origin), exit 7 (no unique legal base), exit 8 (the derived base is missing on origin) or exit 9 (the auto-create failed). No branch reached origin and no PR was opened |
+    | `degraded` | The PR is open but part of the close-out did not land: `pr-depend` exit 4 sent the run to the `WIP:` fallback, so the dependency is not on the PR, or a handled comment ended with a recorded failure instead of a reply link |
+    | `failed` | The run got partway and then git or the API refused: `pick-type.sh` exit 3 (commits exist but no subject carries a ladder type), a push that failed, `pr-create` exit 4, or a non-zero `pr-edit` that left the old title and description in place |
+    | `aborted` | **`pick-type.sh` exit 2 — step 2 produced no commit, so there is nothing to open a PR for.** That is a run which correctly stopped, not a run that failed and not a run that succeeded; recording it as anything else is what made a round with no change look identical to a round that shipped eight PRs. The user declining the confirmation before `pr-create`, `pr-edit` or `pr-depend` is `aborted` too |
+
+    `{exit}` is the exit code of whatever decided the status, `0` for `ok` — so the no-change round above carries `aborted` with `2`. `{detail}` is one short line well under 200 characters: counts and exit codes plus which of the three calibration items moved, never the PR title, the PR number, branch names, or personal data.
+
+    Done when the command has run, or the script was absent and this step was skipped.
 
 ## Rules
 
 1. No template section may stay empty: fill the literal 「無」 when there is no plan page, analyze page, or prerequisite PR.
-2. Take the plan page and analyze page links from the `jsc-sdlc` wiki pages; the analyze link must point at the work package heading anchor.
-3. Branch title summarization (step 3.2) and description drafting MUST run as a sub agent.
+2. Read the `jsc-sdlc` plan page and analyze page through `jsc-gitea:wiki`, which resolves `JSC_WIKI_REPO_PLAN` for the plan page and `JSC_WIKI_REPO_ANALYZE` for the analyze page from the inherited environment, falls back to `JSC_WIKI_REPO`, and asks only when neither is set. Each page type reads its own variable only; a page type never borrows another type's variable. Take both links from the pages read this way; the analyze link must point at the work package heading anchor.
+3. Branch title summarization (step 3.2) and description drafting MUST run as a sub agent. The description sub agent starts right after step 3 and runs alongside steps 4 and 5, so steps 7 and 8 already hold a draft.
+4. Branch names are ASCII only (`a-z0-9`, `/`, `-`). Traditional Chinese phrases go through `jsc-git/tools/slugify.sh` first; `jsc-git/tools/base-branch.sh --derive` rejects anything else. PR titles and descriptions take the opposite rule: they stay Traditional Chinese per `jsc-meta/references/ste100.md`. The two never copy each other.

tools/base-branch.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env sh
+# base-branch.sh — 決定 PR 的基底分支。
+# 用法: base-branch.sh [caller-base]
+#       base-branch.sh --derive [branch]
+#
+# 模式一（既有）: 呼叫方傳入的分支最優先；呼叫方沒傳，才依序試 develop、main、master。
+#       「有沒有傳」看參數個數，不看參數內容：呼叫方寫 base-branch.sh "$SOURCE_BRANCH"
+#       而變數沒設定時，那是空字串，不是沒傳。若當成沒傳就會悄悄退回 develop，
+#       把單一工作包直接合進 develop——這支腳本存在的目的就是擋這件事。
+#
+# 模式二（--derive）: 從分支名推出唯一合法的上一階基底，禁止越級。
+#       沒傳 branch 就取目前分支。階梯如下：
+#         feat、docs、style、refactor、perf、test、chore、revert：
+#           {類型}/{功能}/{子功能} → {類型}/{功能}/main → develop → master
+#           {子功能} 可以多層（例：feat/a/b/c），推導一律「去掉最後一段後接 /main」。
+#         fix：
+#           fix/{修改} → develop → master
+#       推不出唯一合法基底就中止（退出碼 7），由呼叫端問使用者，不猜、也不退回 develop。
+#       功能主幹 {類型}/{功能}/main 不在 origin 時，自動以 origin/develop 為起點建立並推上去，
+#       再把建立了哪一條分支印到 stderr。
+#
+# 分支名只允許 ASCII（a-z0-9 與 /、-）。中文簡述先交給同目錄的 slugify.sh 轉成 ASCII slug，
+# 再組成分支名，這支腳本不接受非 ASCII 分支名。
+#
+# 輸出: 選中的分支名（一行）。錯誤訊息一律印繁中到 stderr。
+# 結束碼: 0=stdout 印出一個基底分支名，兩種模式共用。直接拿它開 PR。
+#         2=參數過多（兩種模式共用）。分支名要用引號包成單一參數，再重跑。
+#         3=連不上 origin，git fetch 失敗（兩種模式共用）。先確認遠端可以連線，再重跑。
+#         4=（呼叫方模式）呼叫方指定的分支不在 origin 上。停下來問使用者原本要的是哪一條，
+#           不要自行改用其他分支。
+#         5=（呼叫方模式）origin 上找不到 develop、main、master。這個碼只在完全沒傳參數時
+#           才會出現，所以真正的問題通常是基底參數在路上掉了。請由呼叫方指定基底分支。
+#         6=（呼叫方模式）傳進來的是空字串。回去補上分支變數的值，不要改成整個參數不傳——
+#           不傳會悄悄退回 develop。
+#         7=（--derive 模式）推不出唯一合法基底：站在斷頭狀態、站在 master、分支名含非 ASCII
+#           或其他不允許的字元、類型不在階梯表內、feat 這類階梯少了功能層，或 fix 寫成多層。
+#           照 stderr 的訊息修分支名再重跑，不要退回 develop。
+#         8=（--derive 模式）推導出的基底不在 origin 上，而且它不是可以自動建立的功能主幹。
+#           先把那條分支建出來並推上 origin，再重跑。
+#         9=（--derive 模式）自動建立功能主幹失敗：origin 上沒有 develop，或推送被拒。
+#           先建好 develop，或確認推送權限，再重跑。
+set -u
+
+MODE=caller
+if [ "$#" -ge 1 ] && [ "$1" = "--derive" ]; then
+  MODE=derive
+  shift
+fi
+
+if [ "$#" -gt 1 ]; then
+  echo "用法: base-branch.sh [caller-base] 或 base-branch.sh --derive [branch]" >&2
+  exit 2
+fi
+
+ARGC=$#
+ARG=${1:-}
+
+if [ "$ARGC" -eq 1 ] && [ -z "$ARG" ]; then
+  echo "錯誤: 傳入空字串當分支名。請確認分支變數有值，或整個參數不要傳。" >&2
+  exit 6
+fi
+
+if ! git fetch --prune origin >/dev/null 2>&1; then
+  echo "錯誤: 無法向 origin 取得遠端分支。請確認遠端可以連線，再重試。" >&2
+  exit 3
+fi
+
+remote_has() {
+  [ -n "$(git ls-remote --heads origin "refs/heads/$1" 2>/dev/null)" ]
+}
+
+if [ "$MODE" = "caller" ]; then
+  if [ "$ARGC" -eq 1 ]; then
+    if remote_has "$ARG"; then
+      printf '%s\n' "$ARG"
+      exit 0
+    fi
+    echo "錯誤: 呼叫方指定的基底分支 $ARG 不在 origin 上。請確認分支名，不要自行改用其他分支。" >&2
+    exit 4
+  fi
+
+  for candidate in develop main master; do
+    if remote_has "$candidate"; then
+      printf '%s\n' "$candidate"
+      exit 0
+    fi
+  done
+
+  echo "錯誤: origin 上找不到 develop、main、master。請由呼叫方指定基底分支。" >&2
+  exit 5
+fi
+
+# 以下是 --derive 模式。
+BRANCH=$ARG
+if [ -z "$BRANCH" ]; then
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+fi
+
+if [ -z "$BRANCH" ] || [ "$BRANCH" = "HEAD" ]; then
+  echo "錯誤: 取不到目前分支名（可能在斷頭狀態）。請先切到分支，或直接把分支名當參數傳進來。" >&2
+  exit 7
+fi
+
+if printf '%s' "$BRANCH" | LC_ALL=C grep -q '[^a-z0-9/-]'; then
+  echo "錯誤: 分支名 $BRANCH 含分支名不允許的字元。分支名只允許 ASCII 小寫、數字、連字號與斜線；中文簡述請先交給 slugify.sh。" >&2
+  exit 7
+fi
+
+TYPE=${BRANCH%%/*}
+SEGMENTS=$(printf '%s' "$BRANCH" | tr '/' '\n' | grep -c '')
+LAST=${BRANCH##*/}
+HEAD_PART=${BRANCH%/*}
+
+ladder_type() {
+  case "$1" in
+    feat|docs|style|refactor|perf|test|chore|revert) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+BASE=""
+TRUNK_AUTOCREATE=no
+
+if [ "$BRANCH" = "develop" ]; then
+  BASE=master
+elif [ "$BRANCH" = "master" ]; then
+  echo "錯誤: master 已經是階梯頂端，推不出上一階基底分支。請確認是不是站錯分支。" >&2
+  exit 7
+elif [ "$TYPE" = "fix" ]; then
+  if [ "$SEGMENTS" -eq 2 ]; then
+    BASE=develop
+  else
+    echo "錯誤: 分支 $BRANCH 不符合 fix 階梯。fix 只有 fix/{修改} → develop → master 一條路，不接受多層分支名。" >&2
+    exit 7
+  fi
+elif ladder_type "$TYPE"; then
+  if [ "$SEGMENTS" -lt 3 ]; then
+    echo "錯誤: 分支 $BRANCH 少了功能層，推不出唯一合法基底。$TYPE 階梯為 $TYPE/{功能}/{子功能} → $TYPE/{功能}/main → develop → master，請補上功能層再重試。" >&2
+    exit 7
+  elif [ "$LAST" = "main" ]; then
+    BASE=develop
+  else
+    BASE="$HEAD_PART/main"
+    TRUNK_AUTOCREATE=yes
+  fi
+else
+  echo "錯誤: 分支 $BRANCH 的類型 $TYPE 不在階梯表內，推不出唯一合法基底。請改用 feat、fix、docs、style、refactor、perf、test、chore、revert 其中一種類型。" >&2
+  exit 7
+fi
+
+if remote_has "$BASE"; then
+  printf '%s\n' "$BASE"
+  exit 0
+fi
+
+if [ "$TRUNK_AUTOCREATE" = "no" ]; then
+  echo "錯誤: 推導出的基底分支 $BASE 不在 origin 上，而且它不是可以自動建立的功能主幹。請先建立 $BASE，再重試。" >&2
+  exit 8
+fi
+
+# 功能主幹不存在就自動補一條：直接把 origin/develop 推成新分支，
+# 不動本機工作區，省下切分支與切回來的來回。
+if ! remote_has develop; then
+  echo "錯誤: origin 上沒有 develop，無法自動建立功能主幹 $BASE。請先建立 develop，再重試。" >&2
+  exit 9
+fi
+
+if ! git push origin "refs/remotes/origin/develop:refs/heads/$BASE" >/dev/null 2>&1; then
+  echo "錯誤: 自動建立功能主幹 $BASE 失敗。請確認遠端推送權限，或手動從 develop 建立 $BASE。" >&2
+  exit 9
+fi
+
+echo "已自動從 develop 建立功能主幹 $BASE，並推上 origin。" >&2
+printf '%s\n' "$BASE"
+exit 0

tools/pick-type.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+# pick-type.sh — 從一組 commit 型別中選出優先度最高的一個。
+# 用法: pick-type.sh {型別或 commit 標題}...
+#       git log --format=%s {範圍} | pick-type.sh
+#
+# 說明: 優先序固定為 revert > fix > feat > perf > refactor > test > docs > style > chore。
+#       這支腳本是該優先序的唯一真實來源，SKILL.md 不再抄一份。
+#       帶參數就讀參數，一個參數算一項；沒帶參數就讀標準輸入，一行算一項。
+#       每一項只取冒號、左括號、驚嘆號之前的字，所以 commit 標題整行餵進來也認得出型別。
+#       認不得的項目直接略過，不影響其他項目。
+#
+# 輸出: 勝出的型別（一行，例如: feat）。
+# 結束碼: 0 選出型別；2 沒有收到任何輸入；3 輸入裡沒有階梯表內的型別。
+#         錯誤訊息一律印繁中到 stderr。
+set -u
+
+if [ "$#" -gt 0 ]; then
+  RAW=$(printf '%s\n' "$@")
+else
+  RAW=$(cat)
+fi
+
+if [ -z "$(printf '%s' "$RAW" | tr -d '[:space:]')" ]; then
+  echo "錯誤: 沒有收到任何型別。請把 git log 取出的型別集合當參數傳入，或從標準輸入餵進來。" >&2
+  exit 2
+fi
+
+NORM=$(printf '%s\n' "$RAW" \
+  | sed -e 's/[(:!].*$//' -e 's/[[:space:]]//g' \
+  | tr '[:upper:]' '[:lower:]')
+
+for candidate in revert fix feat perf refactor test docs style chore; do
+  if printf '%s\n' "$NORM" | grep -qx "$candidate"; then
+    printf '%s\n' "$candidate"
+    exit 0
+  fi
+done
+
+echo "錯誤: 輸入裡沒有階梯表內的型別。請確認 commit 訊息符合 {類型}({範圍}): {訊息} 格式，型別限 revert、fix、feat、perf、refactor、test、docs、style、chore。" >&2
+exit 3

tools/slugify.sh

@@ -4,6 +4,12 @@
 # 規則: 全部轉小寫，非 a-z0-9 的字元換成連字號，
 #       連續連字號合併成一個，並去除開頭與結尾的連字號。
 # 輸出: {type}/{slug}（例如: slugify.sh feat "export report" → feat/export-report）
+# 結束碼: 0=stdout 印出 {type}/{slug}，直接拿去當分支名。
+#         1=參數少於兩個。補上 type 與 phrase 再重跑。
+#         2=type 或 phrase 含非 ASCII 字元。先把描述翻成英文短語再重跑，
+#           不要自己動手拼分支名。
+#         3=phrase slug 化之後是空字串（裡面一個 a-z0-9 都沒有）。換一句英文短語再重跑。
+#       錯誤訊息都印到 stderr，其中 2 與 3 印繁體中文。
 set -u
 
 if [ "$#" -lt 2 ]; then
@@ -17,4 +23,14 @@ PHRASE="$*"
 
 slug=$(printf '%s' "$PHRASE" | tr '[:upper:]' '[:lower:]' | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//')
 
+if printf '%s%s' "$TYPE" "$PHRASE" | LC_ALL=C grep -q '[^ -~]'; then
+  echo "錯誤: 分支名只允許 ASCII。請先把標題翻譯成英文短語，再交給 slugify.sh。" >&2
+  exit 2
+fi
+
+if [ -z "$slug" ]; then
+  echo "錯誤: 標題 slug 化後是空字串，組不出分支名。請先把標題翻譯成英文短語，再交給 slugify.sh。" >&2
+  exit 3
+fi
+
 printf '%s/%s\n' "$TYPE" "$slug"