jiantw83
bf68ee3436
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就 中止的技能，在紀錄裡長得一模一樣。 start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾 步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在 原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。 status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜 跳過，回報失敗一律不改變技能自己的結論。
72 lines
8.7 KiB
Markdown
72 lines
8.7 KiB
Markdown
---
|
|
name: commit
|
|
description: 'Group all pending file changes by conventional type and feature, then commit each group as {type}({scope}): {message}. Before committing, sweep the working tree with jsc-hooks/hooks/comment-scope.sh so no comment carrying document tracking information enters a commit. Message style is full (What/Why/How/Who), brief (one line from git diff), or custom, chosen via decision tree. Once the commits land, an open PR on the current branch gets its title, description, and prerequisite dependency calibrated through jsc-git:pr. Use whenever changes must be committed; not for push or PR creation.'
|
|
---
|
|
|
|
# commit — group and commit file changes
|
|
|
|
## Steps
|
|
|
|
1. Track every file change: inspect all changes with `git status --porcelain` first. That inventory is this step's own work; the `git add` that follows is group by group, one add per group as step 4 commits it, never one bulk add here. `git add -A` followed by one bulk commit is blocked in code by the `jsc-hooks` PreToolUse `Bash` guard, which rejects that command pair before it runs. Only claude has a PreToolUse stage; on codex, copilot, antigravity and kiro that guard never fires, so on those four CLIs this step is the only thing holding the rule — add group by group there as well. Done when `git status --porcelain` has run and its full path list is held. That list is what step 3 groups, so this step never waits on the grouping.
|
|
2. Sweep the comments about to be committed: run `jsc-hooks/hooks/comment-scope.sh sweep` over this working tree. Start the sweep at the same time as step 1's inventory: both only read the working tree, and neither needs the other's result. Step 3's grouping is not part of that pair — it needs step 1's path list — but it may run while this sweep is still going. Every fix the sweep demands still lands before step 4 runs the first commit. A code comment states why the code is written this way, never where the work is documented; the rule text and its allow list live in one place only, `jsc-review/references/comment-scope.md`.
|
|
- The script exits 0 in silence when it finds no git working tree and when `jsc-hooks` is not on this machine. **If the script is not found, skip this step, say so in the report and commit anyway** — missing infrastructure is not a violation.
|
|
- Exit 2 means a hit. Fix every comment line the warning points at, in place, then run the sweep again until it exits 0, and commit only after that.
|
|
- The warning is written for a person and a model to judge, **not a hard block**. When it is a false positive, say plainly why and carry on with the commit; never delete a useful comment just to keep the script quiet.
|
|
- Done when one of these is true and reported: the sweep exited 0, or every remaining warning is reported with the reason it is a false positive, or the script was not found on this machine.
|
|
3. Group the changes by same type plus same requirement or feature. One group is one commit. Grouping takes step 1's path list as its input, so it starts once that inventory is held; step 2's sweep may still be running alongside it. Done when every path on step 1's list sits in exactly one group, and each group carries one type and one requirement or feature.
|
|
4. Commit each group with the format `{type}({requirement or feature}): {message}`. Done when `git status --porcelain` returns empty; report done only then.
|
|
5. Calibrate the open PR of this branch. Who called this run decides whether a lookup happens at all:
|
|
- `jsc-git:pr` called this run → skip the lookup. That skill runs the single open-PR lookup of the chain in its own step 6 and owns the calibration from there. Done when the report names `jsc-git:pr` as the caller and states that the lookup was skipped.
|
|
- This run is standalone → look the PR up once with `jsc-gitea/tools/gitea.sh pr-of-branch {owner}/{repo} {current branch}`. On exit 0 the script prints line 1 `number<TAB>{PR number}`, line 2 `title<TAB>{title}`, line 3 `base<TAB>{base}`, line 4 the marker `body`, and line 5 onward the description.
|
|
- Exit 0 → hand the PR number together with the returned title, base and description to `jsc-git:pr`, which compares title, description and prerequisite dependency and updates only what differs, without repeating the lookup. That hand-off does not loop back here: the tree is already clean, and `jsc-git:pr` as the caller makes this step skip its lookup.
|
|
- Exit 3 (no open PR on this branch) → nothing to calibrate.
|
|
- Exit 2 (usage error) → the `{owner}/{repo}` or the branch argument is missing or malformed. Correct the arguments and rerun.
|
|
- Exit 4 (API call failed) → report the failure and leave the PR state as unknown. Never read a failed call as "no open PR": that leaves a stale title on a branch that just gained commits.
|
|
- Any other non-zero → treat it as exit 4.
|
|
- Done when the report states exactly one of these: the lookup was skipped because `jsc-git:pr` called this run, the branch has no open PR, `jsc-git:pr` reported each of the three items as matched or updated, or the lookup failed and the failure is named.
|
|
6. Record how this run ended, as the very last thing this skill does:
|
|
|
|
`jsc-hooks/tools/report-status.sh skill-end jsc-git:commit {status} {exit} "{detail}"`
|
|
|
|
Resolve that path the way step 2 already resolves `jsc-hooks/hooks/comment-scope.sh` — the sibling plugin directory, no separate lookup rule for this one call. **A missing script is not a failure here: skip this step in silence and let the run end as it stands**, the same way step 2 commits anyway when the sweep is not installed. The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. Commits that landed stay landed whether or not the run could be recorded.
|
|
|
|
| status | This skill's case |
|
|
| --- | --- |
|
|
| `ok` | Every group is committed, `git status --porcelain` prints nothing, and step 5 stated one of its four outcomes. A step 2 sweep that was skipped because the script is not on this machine is still `ok` — say so in `{detail}`, since a run judged without the sweep is worth telling apart from one the sweep passed |
|
|
| `blocked` | The `jsc-hooks` PreToolUse `Bash` guard rejected the commit before git ran — a bulk `git add -A` pair, or a message carrying no Traditional Chinese — so no commit landed and the working tree is exactly as it was |
|
|
| `degraded` | Every group is committed and the tree is clean, but the close-out is short: step 5's `pr-of-branch` returned 4, or the `jsc-git:pr` calibration failed, so the open PR still carries a title written before these commits |
|
|
| `failed` | A `git add` or `git commit` returned non-zero part-way through, leaving some groups committed and the tree dirty. Report the group that broke; a partial commit set is what the next run has to reconcile |
|
|
| `aborted` | Step 1's inventory came back empty, so there was nothing to commit and nothing was attempted. Also the user stopping the run at the grouping or the message-style question. This is not a success: a run that committed nothing must not read like a run that committed everything |
|
|
|
|
`{exit}` is the exit code of whatever decided the status, `0` for `ok`. `{detail}` is one short line well under 200 characters: group and commit counts plus exit codes, never commit messages, branch names, or personal data.
|
|
|
|
Done when the command has run, or the script was absent and this step was skipped.
|
|
|
|
## Type table
|
|
|
|
| Type | Purpose |
|
|
| --- | --- |
|
|
| feat | add or change a feature |
|
|
| fix | fix a bug |
|
|
| docs | documentation |
|
|
| style | formatting; no change to how the code runs |
|
|
| refactor | code change that neither adds a feature nor fixes a bug |
|
|
| perf | improve performance |
|
|
| test | add tests |
|
|
| chore | build process or tooling change |
|
|
| revert | revert an earlier commit |
|
|
|
|
## Message format (pick one of three)
|
|
|
|
Ask the user per the `jsc-ask:ask` rules. Skip the question when the question record or this session already holds a convention.
|
|
|
|
1. **Full**: covers What, Why, How, and Who (which feature).
|
|
2. **Brief**: one sentence summarized from `git diff`.
|
|
3. **Custom**: the user types the message.
|
|
|
|
## Rules
|
|
|
|
1. The grouping and message drafting details **MUST run as a sub agent**. The main agent only confirms the grouping and runs the commits.
|
|
2. Write messages in UTF-8 Traditional Chinese (the type and scope stay in English), per the STE100 output rule. The `jsc-hooks` PreToolUse `Bash` guard rejects a `git commit` whose message carries no Traditional Chinese. That guard runs on claude only; on codex, copilot, antigravity and kiro nothing blocks such a message, so on those four CLIs this rule carries the whole load.
|
|
3. Never push, and never create a PR. Step 5 only calibrates a PR that already exists; pushing and creating PRs belong to `jsc-git:pr`.
|