sdlc/skills/maintain/SKILL.md

---

name: maintain description: SDLC maintenance stage. Gate on capability tags enforced in code by sdlc-gate (maintenance requires no specific tag, but the actual model id must be determinable from the transcript), read projects still inside their maintenance window from MAINTAIN_CONTENTS, then run one sub agent per project: switch to develop or master, propose at least five maintenance actions, commit to a new branch, push, and PR. Write a jsc-log:worklog entry per finished project and update the last-maintained timestamp afterward, then close with tools/stage-report.sh - model tag verdict, worklog link, every wiki link written. Use for periodic upkeep of delivered projects inside their maintenance window; not for projects still mid-implementation or not yet registered in MAINTAIN_CONTENTS.

maintain

Goal: run routine maintenance for every project in the maintenance contents page. All wiki reads and writes go through jsc-gitea:wiki.

Steps

1. Model gate and stage lock — run jsc-cli/tools/model-tags.sh sync, then jsc-hooks/hooks/sdlc-gate.sh lock maintain. This stage requires no specific capability tag; the gate passes as long as the script can determine the actual model id. Rules: references/model-gate.md. Completion condition: the script exited 0, and you have reported the stage, the required tag, the actual model id it read from the transcript, and the verdict.
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). Completion condition: you have listed every in-window project with its {owner}/{repo} and window dates, or reported that none is in window and stopped.
3. Every project MUST run as a sub agent with this flow. Completion condition: every project listed in step 2 has its sub agent finished, and each one ends in either a PR link or a recorded skip reason.

   1. Run git fetch --prune origin, then put the project on its maintenance branch and align it with origin/{branch}. Which branch that is, the remote-is-the-basis rule, the diverged case and the never-pull-never-reset rule all live in references/branch.md; never guess the branch name. Completion condition: the project's HEAD points at the same commit as origin/{branch}, or you have reported the gap and skipped this project.

   2. Propose at least five maintenance methods, then let the user pick per jsc-ask:ask rules — every option states its impact scope (which files it touches, whether it can break the build, how much review it costs). Candidates:

      • dependency updates (reuse jsc-pkg:pkg-update)
      • security vulnerability scan and patching
      • dead code and stale comment cleanup
      • test coverage reinforcement
      • docs and README synchronization
      • 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. 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. One project's maintenance is one finished task — call jsc-log:worklog right after its PR is open. A task is one of three things: one work package, one round of PR-comment fixes, or one standalone fix commit; this stage produces the third kind, one per project. Never let the stage end and then write a single catch-up entry, and never let a second project start before the first one's entry is saved — by then the elapsed time, the token counts and the difficulties are gone. Every entry appends to the same LOG_{HASH} page. Content parked earlier by tools/stage-report.sh --pending-file is merged into that same write and cleared only once the write succeeds; parked content is not a written log. Completion condition: this project's entry is saved on LOG_{HASH} before the next project's sub agent starts.

   6. 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 pointing at the entries step 3.5 wrote. --pending-file {file} --log-hash {HASH} is the fallback for a stage that stopped before any project finished: it holds the content for the next jsc-log:worklog run, and held content is not a written log. 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.