refactor(分支規則): 分支確認改用 sdlc 自帶的 references/branch.md,移除對 jsc-shared 的相依

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-24 17:37:12 +08:00
co-authored by Claude Opus 5
parent 4b5385175b
commit b5f28e57f9
4 changed files with 48 additions and 3 deletions
+1
View File
@@ -51,6 +51,7 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/jsc.git),安
| `templates/deliver-page.md`、`templates/deliver-contents.md` | 交付頁(API 文件、新舊參數標示、驗證方式)與交付目錄 |
| `templates/maintain-contents.md` | 維護目錄(截止日 NULL = 永久維護) |
| `references/tdd.md` | 接縫、紅綠循環規則、反模式 |
| `references/branch.md` | 分支規則:分析前確認來源分支、寫檔前確認目標分支、判定遠端預設分支、不破壞未提交變更 |
| `references/consensus.md` | 規劃與分析的提問規則:一輪不算問完、共識的兩個判定條件、未決項處理 |
| `references/deliver-formats.md` | 交付內容型別:API 文件必備欄位、範例資料優先序、既有端點的新舊參數標示 |
+44
View File
@@ -0,0 +1,44 @@
# 分支規則 — SDLC 各階段動工前的分支確認
分析要讀對分支的程式碼,實作要寫進對的分支。兩件事都不能從「目前 checkout 的分支」推定使用者的意圖。
## 先確認,再動工
| 階段 | 要確認的分支 | 確認時機 |
| --- | --- | --- |
| `analyze` | **來源分支**——哪條分支的程式碼算現況 | 讀任何程式碼之前 |
| `implement` | **目標分支**——這批工作要合併進哪條分支 | 寫任何檔案之前 |
確認方式:
1. 先把事實攤開:目前分支、工作區是否乾淨、遠端有哪些分支(`git branch -r`)、下節判定出的遠端預設分支。
2. 依 `jsc-ask:ask` 的決策樹詢問,每個選項都要標明影響範圍。分析錯分支會產出對不上程式碼的工作包;目標分支錯了則 PR 會開到錯的地方。
3. 把確認結果寫進產出(分析頁的來源分支欄、PR 的目標分支),後續步驟一律沿用同一個答案,不再自行改判。
4. 使用者沒回答就**不預設** `develop`/`master`;預設值只在使用者明確同意後才成立。
## 判定遠端預設分支
1. 先用 `git symbolic-ref --quiet refs/remotes/origin/HEAD`,結果形如 `refs/remotes/origin/<預設分支>`。
2. 取不到時退而用 `git remote show origin`,找輸出中的 `HEAD branch:` 那行。
3. 兩者都取不到 → 回報並停止,**不臆測** `master`/`main`。
需要基準或後備分支時(例如 PR 目標):`origin/develop` 存在就用 `develop`;否則 `origin/master` 存在就用 `master`;兩者皆無則回報並停止。
## 只讀階段不動工作區
`analyze` 是 logic-only 階段:
- 需要換分支才能讀到正確現況時,**停下來請使用者自己切換**。
- 不代為 `switch`、不 `stash`、不動工作區、不建分支。
## 實作階段的分支選擇
- **只有來源分支與目標分支同名時才開新的工作分支**:同名就不可在該分支上直接 commit,改從已更新到最新的目標分支建立新工作分支,後續操作都以新分支為準。不同名就在目前分支處理。
- 新分支名稱要可讀且不覆蓋既有分支;本地或遠端已存在同名分支時,換一個時間戳或短 hash。
- 切換或建立分支屬不可忽略的狀態變更,要在輸出中講清楚原因與結果分支名稱。
## 不破壞既有工作
- 工作區有未提交變更時,先提醒使用者 commit 或備份,**絕不**強制丟棄。
- 未提交變更導致切換分支或 pull 失敗 → 停止並回報,請使用者處理。
- **絕不** `reset --hard`/`checkout -f`/`clean`。
+1 -1
View File
@@ -21,7 +21,7 @@ All wiki reads and writes go through `jsc-gitea:wiki`.
2. **Confirm the source branch** — the branch whose code counts as the current state:
1. Report the working directory's current branch, plus the remote branches available (`git branch -r`) and whether the working tree is clean.
2. Ask per `jsc-ask:ask` rules which branch the analysis reads from; state the impact scope on every option (analysing the wrong branch produces work packages for code that does not exist).
3. When the chosen branch is not the current one, **stop and ask the user to switch**. This stage never switches branches, never stashes, and never touches the working tree — see `/jsc-shared:spec-git-safety`.
3. When the chosen branch is not the current one, **stop and ask the user to switch**. This stage never switches branches, never stashes, and never touches the working tree — rules in `references/branch.md`.
4. Record the confirmed branch and its head sha on the analysis page. Completion condition: the user has confirmed the branch explicitly; never infer it from the current checkout alone.
3. Read `PLAN_CONTENTS` via `jsc-gitea:wiki` for plans whose status is the literal 「未分析」 (name and HASH), and read `ANALYZE_CONTENTS` for existing analyses.
4. Let the user choose per `jsc-ask:ask` rules: **extend an existing analysis** or **analyze a new plan**. State the impact scope on every option.
+2 -2
View File
@@ -16,10 +16,10 @@ All wiki reads and writes go through `jsc-gitea:wiki`.
3. **Never claim a capability tag you have not verified with that script**, and never substitute your own judgement for its verdict. Non-zero exit = blocked: relay the script's message verbatim, stop the skill, do nothing else this turn. Do not run `unlock` to get past the gate; only the user may decide that.
4. Exit 0 means the stage is locked. From now until the next stage's gate runs, the sdlc-gate hook blocks every prompt whose model stops satisfying the tags.
2. **Confirm the target branch** — do this **before writing any file**:
1. Report the current branch, whether the working tree is clean, and which of `origin/develop` / `origin/master` exist, plus the remote default branch resolved per `/jsc-shared:spec-git-safety`.
1. Report the current branch, whether the working tree is clean, and which of `origin/develop` / `origin/master` exist, plus the remote default branch resolved per `references/branch.md`.
2. Ask per `jsc-ask:ask` rules which branch this work merges into; state the impact scope on every option (the answer decides the PR target and, when it collides with the current branch, forces a new working branch).
3. Uncommitted changes in the working tree → warn first and let the user commit or back them up; never discard them.
4. Apply `/jsc-shared:spec-git-safety` to the confirmed target: source branch and target branch sharing a name means creating a new working branch instead of committing on the target; report the resulting branch name.
4. Apply `references/branch.md` to the confirmed target: source branch and target branch sharing a name means creating a new working branch instead of committing on the target; report the resulting branch name.
5. Record the confirmed target branch on the analysis page next to the work ticket, and reuse it as the PR target in `jsc-git:pr`. Completion condition: the user has confirmed the target branch explicitly; never fall back to `develop` silently.
3. **Generate a work ticket**: format `TICKET_{yyyyMMdd}_{HHmmss}_{HASH}`. `{HASH}` = the shared wiki hash for `{owner}/{repo}`, computed by `jsc-gitea/tools/hash-id` (see `jsc-gitea:wiki`). Try to rename the current session to the ticket name (skip when the CLI does not support it).
4. Read `ANALYZE_CONTENTS` via `jsc-gitea:wiki` and list what is unfinished: plan name, HASH, work package number, count of open items. A selectable work package must satisfy all three: **unfinished, dependency-free (or all dependencies done), and not holding a work ticket**.