From e6e3e176ef0bdfee9ffcd59817ace58b66d4474d Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 26 Aug 2026 19:00:07 +0800 Subject: [PATCH] =?UTF-8?q?feat(maintain):=20maintain=20=E6=AD=A5=E9=A9=9F?= =?UTF-8?q?=E5=8A=A0=E4=B8=8A=E8=A8=BB=E8=A7=A3=E7=95=8C=E7=B7=9A=E8=A6=8F?= =?UTF-8?q?=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What：步驟 3 新增 3.3「註解只寫原因」，原 3.3、3.4 順延為 3.4、3.5。 Why：維護階段常改到既有註解，議題編號、commit hash、分支名、人名與 @ 提及很容易順手留在註解裡，讓註解變成追蹤記錄。 How：規則正文放在 jsc-review 的 references/comment-scope.md，本技能只寫指引與完成條件，不重複清單；並指向 jsc-hooks 的 comment-scope.sh 當寫檔後的即時警告。 Who：jsc-sdlc 的 maintain 技能。 --- skills/maintain/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/maintain/SKILL.md b/skills/maintain/SKILL.md index 84fc9da..1ff2bd1 100644 --- a/skills/maintain/SKILL.md +++ b/skills/maintain/SKILL.md @@ -23,7 +23,8 @@ All wiki reads and writes go through `jsc-gitea:wiki`. - build warning elimination Completion condition: the user has picked the methods to apply, and every picked method is either applied or reported with the reason it could not be. - 3. Commit the changes to a new branch per `jsc-git:commit`, push, then open a PR per `jsc-git:pr` back to the branch of step 3.1, passing it explicitly as the base. Completion condition: the PR exists, and you have reported its URL and number. - 4. Update the project's last-maintained field (the zh-TW column 「前次維護時間」) in `MAINTAIN_CONTENTS` to today. Completion condition: `MAINTAIN_CONTENTS` shows today's date in 「前次維護時間」 for that project, saved on the wiki. + 3. **A code comment states why the code is written this way; it never states where the work is tracked.** Issue numbers, commit hashes, branch names, people's names and `@` mentions stay out of every code comment this project's maintenance touches — including the comments the cleanup method rewrites. Full list and the allowed exceptions: `jsc-review/references/comment-scope.md`. `jsc-hooks/hooks/comment-scope.sh` compares each file after it is written and prints a warning; fix the flagged line at once, then carry on. Completion condition: this project's diff holds no comment line carrying an issue number, a commit hash, a branch name, a person's name or an `@` mention, and every warning the hook printed is fixed. + 4. Commit the changes to a new branch per `jsc-git:commit`, push, then open a PR per `jsc-git:pr` back to the branch of step 3.1, passing it explicitly as the base. Completion condition: the PR exists, and you have reported its URL and number. + 5. Update the project's last-maintained field (the zh-TW column 「前次維護時間」) in `MAINTAIN_CONTENTS` to today. Completion condition: `MAINTAIN_CONTENTS` shows today's date in 「前次維護時間」 for that project, saved on the wiki. 4. The main agent reports the summary: maintenance methods applied per project, PR links, and failure reasons. The report and all generated wiki content, commits, and PR descriptions stay Traditional Chinese per the STE100 rule. Completion condition: the summary names every project read in step 2, each with its applied methods and either a PR link or the reason it was skipped. 5. **Stage report — the last thing this stage does, including when no project was in window.** Run `tools/stage-report.sh maintain` with one `--page MAINTAIN:{page}` per wiki page this run wrote (`MAINTAIN_CONTENTS` counts), plus `--worklog` and `--worklog-heading` when a work log entry exists. No work log yet: write this stage's log content to a file and pass `--pending-file {file} --log-hash {HASH}` so it is held for the next `jsc-log:worklog` run. Rules and exit codes: `references/stage-report.md`. Exit 1 is a warning, never a block. Completion condition: the script's output is reported to the user verbatim, and every wiki page this run wrote appears in it.