From b5f28e57f9a8c6454e08de3ed86118003f9eb7f0 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 24 Aug 2026 17:37:12 +0800 Subject: [PATCH] =?UTF-8?q?refactor(=E5=88=86=E6=94=AF=E8=A6=8F=E5=89=87):?= =?UTF-8?q?=20=E5=88=86=E6=94=AF=E7=A2=BA=E8=AA=8D=E6=94=B9=E7=94=A8=20sdl?= =?UTF-8?q?c=20=E8=87=AA=E5=B8=B6=E7=9A=84=20references/branch.md=EF=BC=8C?= =?UTF-8?q?=E7=A7=BB=E9=99=A4=E5=B0=8D=20jsc-shared=20=E7=9A=84=E7=9B=B8?= =?UTF-8?q?=E4=BE=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 1 + references/branch.md | 44 +++++++++++++++++++++++++++++++++++++++ skills/analyze/SKILL.md | 2 +- skills/implement/SKILL.md | 4 ++-- 4 files changed, 48 insertions(+), 3 deletions(-) create mode 100644 references/branch.md diff --git a/README.md b/README.md index 5d791b5..1ef7dab 100644 --- a/README.md +++ b/README.md @@ -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 文件必備欄位、範例資料優先序、既有端點的新舊參數標示 | diff --git a/references/branch.md b/references/branch.md new file mode 100644 index 0000000..d1e4b11 --- /dev/null +++ b/references/branch.md @@ -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`。 diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md index a69aa7b..6554ff1 100644 --- a/skills/analyze/SKILL.md +++ b/skills/analyze/SKILL.md @@ -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. diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index d64c6e4..1a12b72 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -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**.