diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 6ae9456..dfd6681 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.0.8", + "version": "0.0.9", "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index b514edd..add53b7 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.0.8", + "version": "0.0.9", "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）", "skills": "./skills" } diff --git a/README.md b/README.md index a0e5097..3afd1d6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # jsc-sdlc — 開發生命週期 -jsc 技能組的 sdlc domain：規劃 → 分析 → 實作 → 維護四個階段，全程以 wiki 頁追蹤（`PLAN_CONTENTS`、`PLAN_{HASH}`、`ANALYZE_CONTENTS`、`ANALYZE_{HASH}`、`REPO_CONTENTS`、`REPO_{HASH}`、`DELIVER_CONTENTS`、`DELIVER_{HASH}`、`MAINTAIN_CONTENTS`）。工作包完成即交付：實作階段會詢問交付文件要產生成 `DELIVER_{HASH}` wiki 頁或 Gitea 議題留言。另有異常頁（`ERROR_CONTENTS`、`ERROR_{HASH}`）記錄 hook 或流程失敗。每次切換階段先過模型閘門：由 `jsc-hooks/hooks/sdlc-gate.sh lock {stage}` 從 transcript 讀出**實際**模型 id，比對該階段的必要能力標籤（plan、analyze 需 `reasoning-max`；implement 需 `coding`；maintain 任意），不符就拒絕上鎖、該階段不得執行。判定全在程式層，模型不得自評標籤。通過後鎖定到下一階段的閘門重新上鎖；同一階段內把模型換成不合格的，下一輪提示會被 hook 以 exit 2 擋下。分析前先與使用者確認來源分支，寫檔前先確認目標分支。 +jsc 技能組的 sdlc domain：規劃 → 分析 → 實作 → 維護四個階段，全程以 wiki 頁追蹤（`PLAN_CONTENTS`、`PLAN_{HASH}`、`ANALYZE_CONTENTS`、`ANALYZE_{HASH}`、`REPO_CONTENTS`、`REPO_{HASH}`、`DELIVER_CONTENTS`、`DELIVER_{HASH}`、`MAINTAIN_CONTENTS`）。工作包完成即交付：實作階段會詢問交付文件要產生成 `DELIVER_{HASH}` wiki 頁或 Gitea 議題留言。另有異常頁（`ERROR_CONTENTS`、`ERROR_{HASH}`）記錄 hook 或流程失敗。每次切換階段先過模型閘門：由 `jsc-hooks/hooks/sdlc-gate.sh lock {stage}` 從 transcript 讀出**實際**模型 id，比對該階段的必要能力標籤（plan、analyze 需 `reasoning-max`；implement 需 `coding`；maintain 任意），不符就拒絕上鎖、該階段不得執行。判定全在程式層，模型不得自評標籤。通過後鎖定到下一階段的閘門重新上鎖；同一階段內把模型換成不合格的，下一輪提示會被 hook 以 exit 2 擋下。分析前先與使用者確認來源分支，寫檔前先確認目標分支。**所有參考與來源分支一律取遠端的 `origin/{分支}`，動作前先 `git fetch --prune origin`；本地分支不可作為基準，本地與遠端不一致就停下回報。** ## 安裝、更新、移除 @@ -34,11 +34,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 ### `implement` -實作：先確認目標分支 → 產生工作證鎖定「未完成、無相依、無工作證」的工作包（交付工作包優先）→ 交付工作包開工前先確認交付內容（API 文件／由使用者輸入，見 `references/deliver-formats.md`） → 逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄。 +實作：先確認目標分支 → 產生工作證鎖定「未完成、無相依、無工作證」的工作包（交付工作包優先）→ 交付工作包開工前先確認交付內容（API 文件／由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{分析頁來源分支}` 建立 worktree**（`.worktree/{分析頁 HASH}/{repo}`，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → 開 PR，成功後才移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄。 ### `maintain` -維護：讀取維護期內的專案，每個專案一個 sub agent：切 develop/master → 至少五種建議維護方法 → commit / push / PR → 更新前次維護時間。僅適用於維護期內已交付的專案；尚在實作中或未登記於 `MAINTAIN_CONTENTS` 的專案不適用。 +維護：讀取維護期內的專案，每個專案一個 sub agent：fetch 後切 develop、master 並對齊 `origin/{該分支}` → 至少五種建議維護方法 → commit / push / PR → 更新前次維護時間。僅適用於維護期內已交付的專案；尚在實作中或未登記於 `MAINTAIN_CONTENTS` 的專案不適用。 @@ -53,7 +53,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | `templates/deliver-page.md`、`templates/deliver-contents.md` | 交付頁（API 文件、新舊參數標示、驗證方式）與交付目錄 | | `templates/maintain-contents.md` | 維護目錄（截止日 NULL = 永久維護） | | `references/tdd.md` | 接縫、紅綠循環規則、反模式 | -| `references/branch.md` | 分支規則：分析前確認來源分支、寫檔前確認目標分支、判定遠端預設分支、不破壞未提交變更 | +| `references/branch.md` | 分支規則：**一律以遠端 `origin/{分支}` 為準、動作前先 fetch**、分析前確認來源分支、寫檔前確認目標分支、實作一律在 `.worktree/{HASH}/{repo}` 內進行（建立前問分支、PR 成功後移除）、判定遠端預設分支、不破壞未提交變更 | | `references/consensus.md` | 規劃與分析的提問規則：一輪不算問完、共識的兩個判定條件、未決項處理 | | `references/deliver-formats.md` | 交付內容型別：API 文件必備欄位、範例資料優先序、既有端點的新舊參數標示 | diff --git a/plugin.json b/plugin.json index b1ca2e0..54c4762 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-sdlc", - "version": "0.0.8", + "version": "0.0.9", "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）", "skills": "./skills/" } diff --git a/references/branch.md b/references/branch.md index d1e4b11..c90eb77 100644 --- a/references/branch.md +++ b/references/branch.md @@ -2,6 +2,24 @@ 分析要讀對分支的程式碼，實作要寫進對的分支。兩件事都不能從「目前 checkout 的分支」推定使用者的意圖。 +## 總則：一律以遠端為準，不吃本地分支 + +SDLC 各階段引用的參考分支與來源分支，**一律指遠端的 `origin/{分支}`**。本地分支不可作為基準。 + +理由：本地分支可能落後遠端、可能有沒推上去的 commit、也可能是別的工作留下的狀態。以本地為基準，分析會對著過時的程式碼做，實作會從錯誤的起點長出來，而且錯了不會有任何徵兆。 + +| 項目 | 規則 | +| --- | --- | +| 動作之前 | 先 `git fetch --prune origin`。**沒 fetch 就用 `origin/{分支}` 等於用快取**，遠端追蹤參照可能已經過時，連分支被刪掉都看不出來 | +| 列分支 | `git branch -r`，不看 `git branch` | +| 基準與比對 | 一律寫 `origin/{分支}`，例如 `git rev-list --count origin/master..origin/develop` | +| 建立 worktree | 從 `origin/{來源分支}` 建，不從本地同名分支建 | +| 判定預設分支 | `refs/remotes/origin/HEAD`（見〔判定遠端預設分支〕） | + +**本地與遠端不一致時一律停下回報**，不自行 `pull`、不自行 `reset`、不自行切換。要不要同步是使用者的決定。 + +`origin` 以外的遠端名稱（例如 `upstream`）：先問使用者以哪個遠端為準，不臆測。 + ## 先確認，再動工 | 階段 | 要確認的分支 | 確認時機 | @@ -11,7 +29,7 @@ 確認方式： -1. 先把事實攤開：目前分支、工作區是否乾淨、遠端有哪些分支（`git branch -r`）、下節判定出的遠端預設分支。 +1. 先 `git fetch --prune origin`，再把事實攤開：目前分支、工作區是否乾淨、遠端有哪些分支（`git branch -r`，不看本地）、下節判定出的遠端預設分支。 2. 依 `jsc-ask:ask` 的決策樹詢問，每個選項都要標明影響範圍。分析錯分支會產出對不上程式碼的工作包；目標分支錯了則 PR 會開到錯的地方。 3. 把確認結果寫進產出（分析頁的來源分支欄、PR 的目標分支），後續步驟一律沿用同一個答案，不再自行改判。 4. 使用者沒回答就**不預設** `develop`／`master`；預設值只在使用者明確同意後才成立。 @@ -28,15 +46,59 @@ `analyze` 是 logic-only 階段： +- **工作目錄的 HEAD 必須與 `origin/{來源分支}` 指向同一個 commit**。落後、超前或分歧都代表讀到的不是遠端現況——停下來回報差距（`git rev-list --left-right --count origin/{來源分支}...HEAD`），請使用者自己處理。 - 需要換分支才能讀到正確現況時，**停下來請使用者自己切換**。 - 不代為 `switch`、不 `stash`、不動工作區、不建分支。 ## 實作階段的分支選擇 +- 判斷同名與否，兩邊都用遠端的分支名（`origin/{來源分支}` 與 `origin/{目標分支}`）。 - **只有來源分支與目標分支同名時才開新的工作分支**：同名就不可在該分支上直接 commit，改從已更新到最新的目標分支建立新工作分支，後續操作都以新分支為準。不同名就在目前分支處理。 - 新分支名稱要可讀且不覆蓋既有分支；本地或遠端已存在同名分支時，換一個時間戳或短 hash。 - 切換或建立分支屬不可忽略的狀態變更，要在輸出中講清楚原因與結果分支名稱。 +## 實作一律在 worktree 內進行 + +`implement` 動任何程式碼之前，先 `git fetch --prune origin`，再從**分析頁記錄的來源分支的遠端版本**（`origin/{來源分支}`）建立 git worktree。所有修改都在 worktree 內，主工作目錄的分支與工作區完全不動。 + +### 路徑 + +``` +{工作目錄}/.worktree/{分析頁 HASH}/{repo} +``` + +- `{分析頁 HASH}`：`ANALYZE_{HASH}` 的 HASH 部分，不含 `ANALYZE_` 前綴。 +- `{repo}`：存取庫名稱，不含 owner（`HP/WebService.Buy` → `WebService.Buy`）。不同 owner 的同名存取庫同時出現時，才改用 `{owner}-{repo}` 避免蓋掉，並在輸出中說明。 +- 一份分析涉及多個存取庫時，每個存取庫各一個 worktree，並列在同一個 HASH 目錄下。 + +### 建立前先問分支怎麼處理 + +依 `jsc-ask:ask` 的決策樹詢問，每個選項標明影響範圍。固定兩個選項： + +| 選項 | 指令 | 影響 | +| --- | --- | --- | +| 以來源分支為基準開新工作分支 | `git worktree add -b {工作分支} {路徑} "origin/{來源分支}"` | commit 落在新分支，來源分支不動 | +| 直接簽出來源分支 | `git worktree add --track -b {來源分支} {路徑} "origin/{來源分支}"` | 建立追蹤遠端的本地分支再簽出；本地已存在同名分支時指令會失敗，此時先確認它與遠端一致才可改用 `git worktree add {路徑} {來源分支}`，不一致就停下回報 | + +**不得自行預設**，也不得跳過詢問。 + +### 建立時的鐵則 + +- **分支名與路徑一律加引號**：來源分支可能含中文、空白或多層斜線（例如 `feat/一址通/查地址/完整版/P2`），不加引號會被切斷。 +- 找不到該存取庫的本地 clone → **停下來問使用者路徑**，不自行 clone、不臆測位置。 +- 目標路徑已存在 → 不覆蓋。先確認它是不是同一份工作的 worktree（`git worktree list`），是就沿用，不是就回報並停止。 +- 把 `.worktree/` 加進該存取庫的 `.git/info/exclude`（不動使用者的 `.gitignore`，那是專案共用檔）。 +- 建立後在輸出中明確列出：worktree 路徑、簽出的分支、來源分支，以及 `origin/{來源分支}` 當下的 commit sha——那是這次實作的起點，要能事後追。 + +### 移除時機 + +**PR 建立成功後自動移除**：`git worktree remove {路徑}`。 + +- 只有 `jsc-git:pr` 回報 PR 建立成功才移除；PR 失敗就保留，讓使用者能接手處理。 +- worktree 內還有未提交變更時**不移除**，回報並停止——那些變更沒有進 PR，移除等於丟掉。 +- 移除後順手 `git worktree prune` 清掉殘留記錄。 +- 同一份分析的多個 worktree 全部移除後，若 `.worktree/{HASH}/` 已空就一併刪掉那層目錄。 + ## 不破壞既有工作 - 工作區有未提交變更時，先提醒使用者 commit 或備份，**絕不**強制丟棄。 diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md index 6554ff1..899488f 100644 --- a/skills/analyze/SKILL.md +++ b/skills/analyze/SKILL.md @@ -19,14 +19,14 @@ 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 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. + 1. Run `git fetch --prune origin` first — without it, every `origin/...` reference is stale cache. Then report the working directory's current branch, the **remote** branches available (`git branch -r`; never `git branch`) 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 — 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. **The current state is always the remote branch `origin/{來源分支}`, never the local one.** The working directory's HEAD must point at the same commit as `origin/{來源分支}`; behind, ahead or diverged all mean you would be analysing code that is not what the remote holds. Report the gap (`git rev-list --left-right --count origin/{來源分支}...HEAD`) and stop — this stage never switches branches, never stashes, never pulls and never touches the working tree. Rules in `references/branch.md`. + 4. Record the confirmed branch and the head sha **of `origin/{來源分支}`** 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. 5. Analyze the plan page's user stories one by one against the **current state**, **questioning until consensus** per `references/consensus.md` (the single authority for both planning and analysis): every answer produces the next question, and consensus needs both no output-changing unknown **and** the user's explicit confirmation. Never assume a missing detail, and never start the WBS while any item is still open. Current state means: - 1. Every file in the working directory, on the branch confirmed in step 2. + 1. Every file in the working directory, at the commit `origin/{來源分支}` points to (verified in step 2). 2. **Reuse existing methods and endpoints whenever possible**: - Check the `REPO_{HASH}` inventory page first. Re-inventory when the feature or endpoint is missing, or when the recorded commit sha differs from the current one. - Re-inventory **MUST run as a sub agent**: analyze the repository's features and endpoints, attach the current commit sha, write back to `REPO_{HASH}` with `templates/repo-page.md`, and update `REPO_CONTENTS` per `templates/repo-contents.md`. diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 1a12b72..ad481f8 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -description: SDLC implementation stage. Gate on capability tags enforced in code by sdlc-gate (implement requires coding), confirm the target branch before writing any file, then claim a ready work package from ANALYZE_CONTENTS with a work ticket and complete its TDD todos one by one, updating the wiki after every item. A delivery package confirms its content type (API document or user-defined) before its first todo. Ends with jsc-review code-review, then always asks which delivery-document format to produce (DELIVER_{HASH} wiki page or Gitea issue comment) before an optional MAINTAIN_CONTENTS entry. Use when analysis is done and code must be written; not for planning or analysis. +description: SDLC implementation stage. Gate on capability tags enforced in code by sdlc-gate (implement requires coding), confirm the target branch before writing any file, then claim a ready work package from ANALYZE_CONTENTS with a work ticket, create a worktree from the analysis page's source branch under .worktree/{分析頁 HASH}/{repo}, and complete its TDD todos one by one inside it, updating the wiki after every item. A delivery package confirms its content type (API document or user-defined) before its first todo. Ends with jsc-review code-review, opens the PR and only then removes the worktree, asks which delivery-document format to produce (DELIVER_{HASH} wiki page or Gitea issue comment), and optionally registers the project in MAINTAIN_CONTENTS. Use when analysis is done and code must be written; not for planning or analysis. --- # implement @@ -16,7 +16,7 @@ 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 `references/branch.md`. + 1. Run `git fetch --prune origin` first — every `origin/...` reference is stale cache without it. Then report the current branch, whether the working tree is clean, which of `origin/develop` / `origin/master` exist, and the remote default branch resolved per `references/branch.md`. **Branches are always the remote ones; local branches are never the basis.** 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 `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. @@ -29,18 +29,31 @@ All wiki reads and writes go through `jsc-gitea:wiki`. 2. Chose API 文件 → follow `references/deliver-formats.md`: all parameters listed (not just the main ones), each with name, type, required flag, example, data source and new-versus-existing status; sample values take real sources first and are labelled `真實：{來源}` or `推論：無來源`; **an existing endpoint must mark new versus old parameters both ways** — the status column (🆕 新增 / ⚠️ 變更 / ❌ 移除 / blank for untouched) and a `diff` code block for colour. HTML `style` attributes get filtered by the wiki, so never rely on them. 3. Chose 由使用者輸入 → produce exactly what the user described; do not force the API document layout onto it. 4. Record the confirmed type in the analysis page's 交付型別 column and save it before starting the todos. -7. List every open item of the work package and implement them **one at a time**: +7. **Create the worktree — before touching any code**. Full rules in `references/branch.md`: + 1. Run `git fetch --prune origin`, then read the **source branch** and the repositories involved from the analysis page. The worktree is built from `origin/{來源分支}` — **never from a local branch of the same name**, which may be behind, ahead or diverged. Every code change happens inside the worktree; the main working directory's branch and working tree stay untouched. + 2. Path: `{工作目錄}/.worktree/{分析頁 HASH}/{repo}` — the HASH without the `ANALYZE_` prefix, the repo name without its owner. One worktree per repository, all under the same HASH directory. + 3. **Ask per `jsc-ask:ask` rules how to handle the branch**, with the two fixed options: create a new working branch off the remote source branch (`git worktree add -b {工作分支} {路徑} "origin/{來源分支}"`), or check the source branch out with remote tracking (`git worktree add --track -b {來源分支} {路徑} "origin/{來源分支}"`). State the impact scope on each. **Never assume, never skip the question.** + 4. **Quote every branch name and path**: source branches carry Chinese characters, spaces and multiple slashes (for example `feat/一址通/查地址/完整版/P2`), and an unquoted argument gets split. + 5. No local clone of that repository → stop and ask the user for its path; never clone on your own initiative and never guess the location. + 6. Add `.worktree/` to that repository's `.git/info/exclude` — never edit the user's shared `.gitignore`. + 7. Report the worktree path, the checked-out branch, the source branch and the commit sha `origin/{來源分支}` pointed at — that sha is this implementation's starting point and must stay traceable. Completion condition: every involved repository has a worktree and you have reported all of them. +8. List every open item of the work package and implement them **one at a time**, **inside the worktree**: - Follow the TDD loop: red before green, one slice at a time; rules and anti-patterns in `references/tdd.md` (refactoring belongs to the review stage). - After each item, flip its `[ ]` to `[x]` on the analysis page and save to the wiki before starting the next item. -8. When all items are done, call `jsc-review:code-review` and wait for the review; on failure, fix and re-review until it passes. -9. **Delivery document** — a finished work package is a delivery, so **always ask before producing it; never pick a format silently and never skip this step**: +9. When all items are done, call `jsc-review:code-review` and wait for the review; on failure, fix and re-review until it passes. +10. **Open the PR, then remove the worktree** — in that order, never the reverse: + 1. Call `jsc-git:pr` with the target branch confirmed in step 2. Commits come from inside the worktree. + 2. **Only after `jsc-git:pr` reports the PR was created successfully**, run `git worktree remove {路徑}` for each worktree, then `git worktree prune`. PR creation failed → keep the worktree so the user can take over. + 3. Uncommitted changes still inside a worktree → **do not remove it**; report and stop. Those changes never reached the PR, and removing would throw them away. + 4. Once every worktree of this analysis is gone and `.worktree/{HASH}/` is empty, delete that directory too. +11. **Delivery document** — a finished work package is a delivery, so **always ask before producing it; never pick a format silently and never skip this step**: 1. Ask per `jsc-ask:ask` rules which format to produce. The options are fixed: **a `DELIVER_{HASH}` wiki page** or **a Gitea issue comment**. State the impact scope on each (the wiki page lives beside the plan and analysis pages; the issue comment reaches whoever follows that issue). 2. Both formats use the same structure — `templates/deliver-page.md`, in Traditional Chinese. Only the destination differs. 3. Wiki page: write `DELIVER_{HASH}` through `jsc-gitea:wiki`, where `{HASH}` comes from `jsc-gitea/tools/hash-id` over `{owner}/{repo}` plus the work package number (for example `plugins/sdlc#WP-01`), so each work package gets its own page instead of overwriting the previous one. A new page is added to `DELIVER_CONTENTS` per `templates/deliver-contents.md`. 4. Issue comment: confirm the issue number with the user (propose the one referenced by the work package or the PR; never guess), then post via `gitea/tools/gitea.sh api POST /repos/{owner}/{repo}/issues/{n}/comments` with the body passed in as a UTF-8 file — real newlines, never a literal `\n`. 5. Sample values follow the analysis page's 資料來源 column: `真實：{來源}` for real sources, `推論：無來源` for reasoned ones. Personal data never goes in — keep the field and format, drop the value. 6. Completion condition: the chosen format has actually been produced, and you have reported where it landed (wiki page name, or the comment URL). -10. Ask per `jsc-ask:ask` rules whether to register this project for maintenance: append to `MAINTAIN_CONTENTS` with `templates/maintain-contents.md`. Required: repository `{owner}/{repo}`, maintenance method, start date. Optional: end date (NULL = maintain forever), last-maintained time. +12. Ask per `jsc-ask:ask` rules whether to register this project for maintenance: append to `MAINTAIN_CONTENTS` with `templates/maintain-contents.md`. Required: repository `{owner}/{repo}`, maintenance method, start date. Optional: end date (NULL = maintain forever), last-maintained time. ## Rules diff --git a/skills/maintain/SKILL.md b/skills/maintain/SKILL.md index 92404e3..d0e96f7 100644 --- a/skills/maintain/SKILL.md +++ b/skills/maintain/SKILL.md @@ -17,7 +17,7 @@ All wiki reads and writes go through `jsc-gitea:wiki`. 4. Exit 0 means the stage is locked. Run this gate only when the stage changes; inside the maintenance stage the lock already covers every project, so never re-gate between projects. 2. Read `MAINTAIN_CONTENTS` via `jsc-gitea:wiki` and filter projects **still inside their maintenance window**: start date ≤ today, and (end date is NULL or ≥ today). 3. Every project **MUST run as a sub agent** with this flow: - 1. Switch the project to the `develop` branch, falling back to `master`, and pull to latest. + 1. Run `git fetch --prune origin`, then switch the project to `develop`, falling back to `master`, and bring it up to `origin/{該分支}` — the remote is the basis, never the local branch. Local and remote diverged → report and skip that project; never `pull --rebase`, `reset` or discard anything on your own. 2. Propose **at least five** maintenance methods and apply the ones that fit the project, for example: - dependency updates (reuse `jsc-pkg:pkg-update`) - security vulnerability scan and patching diff --git a/templates/analyze-page.md b/templates/analyze-page.md index eb8240c..5aa68bc 100644 --- a/templates/analyze-page.md +++ b/templates/analyze-page.md @@ -7,7 +7,7 @@ - HASH：`{HASH}` - 對應計畫：[PLAN_{HASH}]({PLAN 頁絕對網址}) - 存取庫：`{owner}/{repo}` -- 來源分支：`{使用者確認的分支}`（head sha：`{sha}`） +- 來源分支：`origin/{使用者確認的分支}`（head sha：`{sha}`，取自遠端） - 狀態：未完成 - 建立時間：{yyyy-MM-dd HH:mm:ss}