feat(pkg-update): 加入註解界線規則與 README 同步說明

What：在 pkg-update 技能的步驟 3.5 新增註解界線規則，並在 README.md 的 pkg-update 段落同步同一份指引。 Why：套件更新途中常會為了鎖版本或繞道不相容而留註解，過去沒有界線，容易把文件相關資訊寫進程式碼註解，造成註解與文件重複、且內容很快過期。 How：規則正文留在 jsc-review 的 references/comment-scope.md，這裡只放指引與連結、不重複清單。註解只寫鎖版本或繞道的原因；第三方套件的 issue 連結屬白名單，用來說明繞道成因與解除條件；內部議題編號、工作包編號、人名與 @ 提及、產生來源署名一律不得寫。步驟 3.5 另附可檢核的完成條件，並指向 jsc-hooks 的 comment-scope.sh 即時告警與修正回檢流程。 Who：jsc-pkg 的 pkg-update 技能，以及 README.md 的技能說明區塊。
2026-08-26 19:00:37 +08:00
parent 4bf662ce0b
commit 992d9c759c
2 changed files with 3 additions and 0 deletions
@@ -39,6 +39,7 @@ Exit 4 and exit 5 are the two codes whose meaning depends on the tool, so read t
   2. Route every exit code per the table above. The skip route covers `latest-version.sh` exit 4 (package not found in the registry), `apply-version.sh` exit 3 (no version source file) and `apply-version.sh` exit 4 (package absent from the file): record the package and the reason, move on to the next package, and never abort the whole ecosystem. The stop route covers exit 1, exit 2, `latest-version.sh` or `apply-version.sh` exit 5 (a required command is missing) and `apply-version.sh` exit 6 (project directory not found): report the code and end the run without entering step 5. This substep is done when every exit code seen has taken exactly one route.
   3. Run `tools/install-deps.sh {ecosystem} {project dir}` once, after every package of that ecosystem is applied. Exit 0 means the install finished. Exit 3 means this ecosystem has no dependency source file, which is the same documented skip as substep 2: record the ecosystem and the reason, and install nothing. Exit 1, exit 2, exit 4 and exit 6 take the stop route — exit 6 is a missing project directory, so report it instead of skipping it. Only another non-zero code is a real install failure and goes to step 5. This substep is done when the exit code is recorded together with the route it took.
   4. The sub agent returns one row per package from substep 1: name, old version, new version — or `skipped` plus the reason. It also returns the `install-deps.sh` exit code and its route. The ecosystem is done only when every package appears in exactly one row.
+   5. **Comments this step writes.** Holding a package at an older version, or coding around an incompatibility, sometimes needs a comment in the version source file or in the code. Write **why** the pin or the workaround exists, never a tracking number. The one this skill trips over most: **a third-party package's issue link is on the allow list** — it is what states the cause of the workaround and the condition for removing it, as in `// works around github.com/foo/bar/issues/88; drop this pin once that ships`. Out of a comment: internal issue ids, work package ids, personal names, `@` mentions and generated-by credits. Full list and allow list: `jsc-review/references/comment-scope.md`. `jsc-hooks/hooks/comment-scope.sh` compares every write against that list right after the file is written and prints a warning on a hit; fix the comment on the spot, then continue this step. Completion condition: every comment line this step added names a reason, carries no internal issue id, work package id, personal name, `@` mention or generated-by credit, and every `comment-scope.sh` warning this step received has been fixed and re-checked with no warning left.
 4. Run `tools/build-test.sh {ecosystem} {project dir}` for every ecosystem and route on the exit code:
   - 0 → this ecosystem passed.
   - 1, 2, 4 or 6 → stop route. Report the code and the missing argument, ecosystem, command or directory, and enter no further step. Exit 4 means the toolchain is broken, not that the packages are broken, so reverting would destroy files for nothing.