|
|
|
@@ -1,15 +1,17 @@
|
|
|
|
|
---
|
|
|
|
|
name: pr
|
|
|
|
|
description: Commit all changes via jsc-git:commit, name a ladder-shaped target branch, derive the base with tools/base-branch.sh (sub-feature → feat/{feature}/main → develop → master; fix → develop → master, no level skipping), push, then open a Gitea PR with the templated description. When the branch already has an open PR, compare its title, description, and prerequisite dependency, and update only the items that differ. Use when work is ready for review, or when an open PR needs re-syncing after new commits; not for plain commits.
|
|
|
|
|
description: Commit all changes via jsc-git:commit, name a ladder-shaped target branch, derive the base with jsc-git/tools/base-branch.sh (sub-feature → feat/{feature}/main → develop → master; fix → develop → master, no level skipping), push, then open a Gitea PR with the templated description. When the branch already has an open PR, compare its title, description, and prerequisite dependency, and update only the items that differ. Use when work is ready for review, or when an open PR needs re-syncing after new commits; not for plain commits.
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
# pr — create a Push Request
|
|
|
|
|
|
|
|
|
|
The ladder rules live in one place only: section 「PR 分支階梯」 of `jsc-meta/references/guidelines.md`. `tools/base-branch.sh --derive` is the running implementation of that section. Read the rung a branch belongs to there; never hand-pick a base, and never restate the ladder table in this file.
|
|
|
|
|
The ladder rules live in one place only: section 「PR 分支階梯」 of `jsc-meta/references/guidelines.md`. `jsc-git/tools/base-branch.sh --derive` is the running implementation of that section. Read the rung a branch belongs to there; never hand-pick a base, and never restate the ladder table in this file.
|
|
|
|
|
|
|
|
|
|
Every script path in this file starts with its plugin's own directory name — `jsc-git/tools/…` for this plugin's, `jsc-gitea/tools/…` and `jsc-hooks/tools/…` for the others — and is resolved against the tool root the caller supplies, never against this skill's own directory. These three scripts sit at the plugin root, not under `skills/pr/`, so dropping the plugin directory name leaves a path that resolves against whatever the current directory happens to be — the right script inside this repo, a different domain's script outside it, or nothing at all and exit 127. That failure is worse than it looks: step 4 says never hand-pick a base, and an agent that cannot run the deriver is one step away from picking one anyway, which turns a wrong path into a PR opened against the wrong rung.
|
|
|
|
|
|
|
|
|
|
## Steps
|
|
|
|
|
|
|
|
|
|
1. **Validate the caller's base first.** A caller may pass a base in (`jsc-sdlc:implement` passes the analysis page's source branch). Whether that base is legal depends on origin alone, not on the target branch name, so settle it before any naming work. Skip the whole step when no caller base was passed, and record "no caller base" for step 4. Otherwise run `tools/base-branch.sh {caller base}` and branch on its exit code:
|
|
|
|
|
1. **Validate the caller's base first.** A caller may pass a base in (`jsc-sdlc:implement` passes the analysis page's source branch). Whether that base is legal depends on origin alone, not on the target branch name, so settle it before any naming work. Skip the whole step when no caller base was passed, and record "no caller base" for step 4. Otherwise run `jsc-git/tools/base-branch.sh {caller base}` and branch on its exit code:
|
|
|
|
|
- 0 → keep the printed name; step 4 cross-checks it against the derived base.
|
|
|
|
|
- 2 (too many arguments) → the base arrived as several words. Quote it as one argument and rerun.
|
|
|
|
|
- 3 (cannot reach origin) → stop and report that origin is unreachable. Nothing downstream works without the remote.
|
|
|
|
@@ -20,12 +22,12 @@ The ladder rules live in one place only: section 「PR 分支階梯」 of `jsc-m
|
|
|
|
|
- Done when the script printed one branch name, or the run is recorded as having no caller base.
|
|
|
|
|
2. Call `jsc-git:commit` to commit every file change. Tell it that `jsc-git:pr` is the caller, so it skips its own open-PR lookup — step 6 here is the only such lookup in this chain. Done when `git status --porcelain` prints nothing.
|
|
|
|
|
3. Build the target branch name in ladder shape:
|
|
|
|
|
1. Pipe the subjects of step 2's commits into `tools/pick-type.sh` (`git log --format=%s {range} | tools/pick-type.sh`), which owns the type priority order. Exit 0 → take the printed type. Exit 2 (no input) → step 2 produced no commits, so there is nothing to open a PR for; stop and report. Exit 3 (no ladder type in the input) → stop, report the subjects, and correct them to `{type}({scope}): {message}` before retrying. Done when the script printed exactly one type.
|
|
|
|
|
2. Summarize one title from all commit messages. Done when one title line covers every commit in the range.
|
|
|
|
|
3. Translate the feature and the title into short English phrases, then build the name with `tools/slugify.sh`. `fix` takes one call: `tools/slugify.sh fix {change phrase}` → `fix/order-export-crash`. Every other type takes two calls, feeding the first result back in as the type: `tools/slugify.sh feat {feature phrase}` → `feat/order-export`, then `tools/slugify.sh feat/order-export {sub-feature phrase}` → `feat/order-export/report-filter`. Done when the name has the shape its ladder row requires; exit 2 (non-ASCII input) or exit 3 (empty slug) → re-translate into an English phrase and retry, never hand-build the branch name.
|
|
|
|
|
1. Pipe the subjects of step 2's commits into `jsc-git/tools/pick-type.sh` (`git log --format=%s {range} | jsc-git/tools/pick-type.sh`), which owns the type priority order. Exit 0 → take the printed type. Exit 2 (no input) → step 2 produced no commits, so there is nothing to open a PR for; stop and report. Exit 3 (no ladder type in the input) → stop, report the subjects, and correct them to `{type}({scope}): {message}` before retrying. Done when the script printed exactly one type.
|
|
|
|
|
2. Summarize one title from all commit messages, as a single Traditional Chinese sentence saying what this PR does. This sentence is the PR title steps 7 and 8 use; step 3.3 only borrows its meaning to build the ASCII slug. Done when one title line covers every commit in the range and reads as one Traditional Chinese sentence.
|
|
|
|
|
3. Translate the feature and the title into short English phrases, then build the name with `jsc-git/tools/slugify.sh`. `fix` takes one call: `jsc-git/tools/slugify.sh fix {change phrase}` → `fix/order-export-crash`. Every other type takes two calls, feeding the first result back in as the type: `jsc-git/tools/slugify.sh feat {feature phrase}` → `feat/order-export`, then `jsc-git/tools/slugify.sh feat/order-export {sub-feature phrase}` → `feat/order-export/report-filter`. Done when the name has the shape its ladder row requires; exit 2 (non-ASCII input) or exit 3 (empty slug) → re-translate into an English phrase and retry, never hand-build the branch name.
|
|
|
|
|
- The name is the only input step 6's lookup and the description draft need. Start both the moment this step ends, and run them alongside steps 4 and 5; neither waits for the push.
|
|
|
|
|
4. Resolve the base branch:
|
|
|
|
|
- Run `tools/base-branch.sh --derive {target branch}`. Exit 0 → the script printed one branch name.
|
|
|
|
|
- Run `jsc-git/tools/base-branch.sh --derive {target branch}`. Exit 0 → the script printed one branch name.
|
|
|
|
|
- Exit 2 (too many arguments) → the branch name arrived as several words. Quote it as one argument and rerun.
|
|
|
|
|
- Exit 3 (cannot reach origin) → stop and report that origin is unreachable.
|
|
|
|
|
- Exit 4, 5 or 6 → these belong to caller mode. Seeing one means the `--derive` flag was dropped. Rerun with the flag.
|
|
|
|
@@ -42,7 +44,7 @@ The ladder rules live in one place only: section 「PR 分支階梯」 of `jsc-m
|
|
|
|
|
- Any other non-zero → treat it as exit 4 and stop.
|
|
|
|
|
- Done when either the PR number plus its title, base and body are held, or exit 3 confirmed the branch has no open PR.
|
|
|
|
|
7. Create the PR, then hang its prerequisite on it. Run `jsc-gitea/tools/gitea.sh pr-create {owner}/{repo} {target branch} {base branch} "{branch name}" {description file}`. Ask the user to confirm before this call runs.
|
|
|
|
|
- Title = branch name.
|
|
|
|
|
- Title = step 3.2's summary: one Traditional Chinese sentence saying what this PR does. Never pass the branch name as the title. A branch name and a title carry different jobs — the branch name is a machine-readable ASCII slug that the ladder and `jsc-git/tools/base-branch.sh` parse, while the title is the one line a human reads in the review list, where a column of long slugs shows who touched the repo but never what changed. The STE100 output rule in `jsc-meta/references/ste100.md` names PR titles and descriptions explicitly, and a hook enforces it; binding the title to the branch name is what put the two rules in conflict, so the title gives way to the language rule and the branch name stays ASCII per rule 4.
|
|
|
|
|
- Write the description into a temp file first, using `templates/pr-description.md` (a Traditional Chinese template; the generated description stays in Traditional Chinese per the STE100 output rule).
|
|
|
|
|
- Exit 0 → the command prints a PR URL; keep it.
|
|
|
|
|
- Exit 2 (description file not found) → write the description file, then rerun.
|
|
|
|
@@ -58,15 +60,15 @@ The ladder rules live in one place only: section 「PR 分支階梯」 of `jsc-m
|
|
|
|
|
- Exit 4 (the dependency API call failed) → degrade: prefix the PR title with `WIP:`, which Gitea blocks merging on natively, and record in the PR description that the prefix comes off once the prerequisite PR closes.
|
|
|
|
|
- Any other non-zero → treat it as exit 4 and degrade the same way.
|
|
|
|
|
|
|
|
|
|
Done when a PR URL is held **and** the prerequisite is settled — `pr-depend` printed its `OK` line, or the PR title starts with `WIP:` and the description names the prerequisite PR, or the description names no prerequisite and that is stated. A PR created here goes straight to step 9.
|
|
|
|
|
Done when a PR URL is held, the title sent to `pr-create` was the Traditional Chinese sentence and not the branch name, **and** the prerequisite is settled — `pr-depend` printed its `OK` line, or the PR title starts with `WIP:` and the description names the prerequisite PR, or the description names no prerequisite and that is stated. A PR created here goes straight to step 9.
|
|
|
|
|
8. **Calibrate an existing PR** (step 6 returned a PR number): compare three items against what this run produced, using the title, base and description step 6 already returned. Send an API call only for the items that differ.
|
|
|
|
|
1. Title against the target branch name.
|
|
|
|
|
1. Title against what this PR now contains. Read the existing title and ask one question only: does it still describe the PR's current content, now that step 2's commits are in? Yes → leave it alone. No → draft a replacement, again one Traditional Chinese sentence saying what this PR does. The branch name never enters this comparison. Comparing them would rewrite a good Traditional Chinese title back into an ASCII slug on every run and notify every reviewer each time, which is the opposite of what a title is for: the branch name is the machine's handle on the ladder, the title is what a human reads in the review list.
|
|
|
|
|
2. Description against a freshly drafted description from `templates/pr-description.md`.
|
|
|
|
|
3. Prerequisite PR dependency against the one the description names.
|
|
|
|
|
- Title or description differs → write the new description to a temp file and run `jsc-gitea/tools/gitea.sh pr-edit {owner}/{repo} {pr number} "{title}" {description file}`, which carries both items in one call. Ask the user to confirm before this call runs. Exit 0 → updated. Exit 2 (description file not found) → write the file and rerun. Exit 4 or any other non-zero → report the script's message and stop, and say plainly that the PR still holds its old title and description.
|
|
|
|
|
- The dependency differs → run `pr-depend` with the exit code branching of step 7. Ask the user to confirm before this call runs.
|
|
|
|
|
- All three match → change nothing. Every needless edit notifies every reviewer, so silence is the correct outcome here.
|
|
|
|
|
- Done when each of the three items is reported as either matched or updated, and the number of API calls made equals the number of items that differed.
|
|
|
|
|
- Done when each of the three items is reported as either matched or updated, the title verdict states which content the title was judged against rather than any branch name, and the number of API calls made equals the number of items that differed.
|
|
|
|
|
9. Reply to the handled comments, then report the run.
|
|
|
|
|
|
|
|
|
|
If this run follows PR comment fixes and the caller supplied handled comment ids, reply to each comment first with `jsc-gitea/tools/gitea.sh comment-reply`. The reply content and the comment type mapping live in `jsc-meta/references/pr-report.md`; the exit codes belong here. Run one call per handled comment and branch on each call's own exit code:
|
|
|
|
@@ -77,10 +79,27 @@ The ladder rules live in one place only: section 「PR 分支階梯」 of `jsc-m
|
|
|
|
|
Then report the PR with the table format in `jsc-meta/references/pr-report.md`, followed by the base branch, the target branch, which of the three calibration items were updated, the feature trunk the script auto-created when step 4 printed that line, and every comment that got no reply.
|
|
|
|
|
|
|
|
|
|
Done when every handled comment holds either a reply link or a recorded failure reason, and the report includes the PR table columns `{owner}/{repo}`, PR number, PR URL and PR summary, names all branch and calibration details, and names the comments that got no reply.
|
|
|
|
|
10. Record how this run ended, as the very last thing this skill does:
|
|
|
|
|
|
|
|
|
|
`jsc-hooks/tools/report-status.sh skill-end jsc-git:pr {status} {exit} "{detail}"`
|
|
|
|
|
|
|
|
|
|
Resolve that path the way this file already resolves `jsc-gitea/tools/gitea.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 script swallows its own write errors and exits 0 even then, so nothing branches on its code either. A PR that is open stays open whether or not the run could be recorded.
|
|
|
|
|
|
|
|
|
|
| status | This skill's case |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| `ok` | A PR URL is held, the prerequisite is settled by a `pr-depend` exit 0 or by a description that names none, and every handled comment holds a reply link. Calibrating an existing PR and changing none of the three items is `ok` as well: silence is the correct outcome there |
|
|
|
|
|
| `blocked` | The ladder refused before anything was pushed: `base-branch.sh` exit 3 (origin unreachable), exit 4 (the caller base is not on origin), exit 7 (no unique legal base), exit 8 (the derived base is missing on origin) or exit 9 (the auto-create failed). No branch reached origin and no PR was opened |
|
|
|
|
|
| `degraded` | The PR is open but part of the close-out did not land: `pr-depend` exit 4 sent the run to the `WIP:` fallback, so the dependency is not on the PR, or a handled comment ended with a recorded failure instead of a reply link |
|
|
|
|
|
| `failed` | The run got partway and then git or the API refused: `pick-type.sh` exit 3 (commits exist but no subject carries a ladder type), a push that failed, `pr-create` exit 4, or a non-zero `pr-edit` that left the old title and description in place |
|
|
|
|
|
| `aborted` | **`pick-type.sh` exit 2 — step 2 produced no commit, so there is nothing to open a PR for.** That is a run which correctly stopped, not a run that failed and not a run that succeeded; recording it as anything else is what made a round with no change look identical to a round that shipped eight PRs. The user declining the confirmation before `pr-create`, `pr-edit` or `pr-depend` is `aborted` too |
|
|
|
|
|
|
|
|
|
|
`{exit}` is the exit code of whatever decided the status, `0` for `ok` — so the no-change round above carries `aborted` with `2`. `{detail}` is one short line well under 200 characters: counts and exit codes plus which of the three calibration items moved, never the PR title, the PR number, branch names, or personal data.
|
|
|
|
|
|
|
|
|
|
Done when the command has run, or the script was absent and this step was skipped.
|
|
|
|
|
|
|
|
|
|
## Rules
|
|
|
|
|
|
|
|
|
|
1. No template section may stay empty: fill the literal 「無」 when there is no plan page, analyze page, or prerequisite PR.
|
|
|
|
|
2. Read the `jsc-sdlc` plan page and analyze page through `jsc-gitea:wiki`, which resolves `JSC_WIKI_REPO_PLAN` for the plan page and `JSC_WIKI_REPO_ANALYZE` for the analyze page from the inherited environment, falls back to `JSC_WIKI_REPO`, and asks only when neither is set. Each page type reads its own variable only; a page type never borrows another type's variable. Take both links from the pages read this way; the analyze link must point at the work package heading anchor.
|
|
|
|
|
3. Branch title summarization (step 3.2) and description drafting MUST run as a sub agent. The description sub agent starts right after step 3 and runs alongside steps 4 and 5, so steps 7 and 8 already hold a draft.
|
|
|
|
|
4. Branch names are ASCII only (`a-z0-9`, `/`, `-`). Traditional Chinese phrases go through `tools/slugify.sh` first; `tools/base-branch.sh --derive` rejects anything else.
|
|
|
|
|
4. Branch names are ASCII only (`a-z0-9`, `/`, `-`). Traditional Chinese phrases go through `jsc-git/tools/slugify.sh` first; `jsc-git/tools/base-branch.sh --derive` rejects anything else. PR titles and descriptions take the opposite rule: they stay Traditional Chinese per `jsc-meta/references/ste100.md`. The two never copy each other.
|
|
|
|
|
admin
jiantw83andClaude Opus 5