meta/skills/ste100-sync/SKILL.md

---
name: ste100-sync
description: Sync the STE100 language rules with upstream speak-human-tw. Compare the pinned upstream version in references/ste100.md against the raw upstream frontmatter version before cloning anything, distill applicable changes and confirm each one via decision tree, refresh ste100-lint.sh patterns and jsc-hooks simplified.txt, re-lint all jsc repos in parallel, then open a PR via jsc-git pr. Use on periodic maintenance or when upstream releases a new version; not for editing local-only rules.
---

# ste100-sync

Keep `references/ste100.md` in sync with its upstream source, [speak-human-tw](https://github.com/Raymondhou0917/speak-human-tw) (MIT).

## Steps

1. Compare versions before fetching anything large — the common case is that upstream has no new release, and a clone done first is then wasted every time:
   1. Read the pinned version from the「上游版本」line in `references/ste100.md`. Completion condition: the pinned version string is in hand.
   2. Read the upstream `version` from the raw `SKILL.md` frontmatter over HTTPS, without cloning. When the raw read fails — network error, a moved path, or no `version` line in the frontmatter — fall back to the `--depth 1` clone and read the same field from the working copy. Completion condition: the upstream version string is in hand, and the report names which route produced it, raw or clone.
   3. Same version: report「上游沒有新版」and stop, without cloning. Completion condition: either the run stops here, or the upstream version is newer than the pinned one.
2. Newer version — get the changelog. Clone the upstream repo (`--depth 1`) when step 1.2 did not already clone it, and read the `changelog` field in its `SKILL.md` frontmatter. Completion condition: the changelog entries newer than the pinned version are in hand.
3. Distill the changes into a change list. **MUST run as a sub agent**:
   - Walk the changelog entries newer than the pinned version.
   - Keep only changes that apply to technical documents and conversation: Taiwan term replacements, punctuation rules, de-AI patterns, humanize targets.
   - Drop marketing-copy scenes, eval material, and workflow-mode changes.
   - Decide nothing and edit no file. Report one line per candidate change: the rule, the upstream wording, and what it would change in `references/ste100.md` or in the lint patterns.

   Completion condition: every kept changelog entry appears as one line in the distilled list.
4. Present the distilled list via the `jsc-ask:ask` decision tree, one question per change (adopt / drop / adapt). Every option states its impact scope (example: adopting a term replacement changes the `TERMS` pattern, so every repo re-linted in step 7 can gain new hits). `references/ste100.md` is the single source of truth for the whole skill set, so no change lands without a recorded decision. Completion condition: every distilled change has a recorded decision.
5. Apply the adopted and adapted changes to `references/ste100.md`. Keep its trimmed structure. Update the「上游版本」line. Completion condition: every adopted change is visible in the file and the「上游版本」line shows the new upstream version.
6. If the replacement table or the cliché list changed, update the `TERMS`, `CLICHES` and `SIMPLIFIED_FALLBACK` patterns in `tools/ste100-lint.sh`. `SIMPLIFIED` is the runtime variable the lint builds from the shared character table, not an editable pattern: the real source is `jsc-hooks/hooks/simplified.txt`, which `ste100-guard.sh` reads too, and `SIMPLIFIED_FALLBACK` is only the built-in backup for machines without `jsc-hooks`. A simplified-character change therefore lands in `simplified.txt` first and in `SIMPLIFIED_FALLBACK` second — editing the lint alone leaves the hook enforcing the old table. Completion condition: `sh -n tools/ste100-lint.sh` passes, each newly adopted term hits on a test string, and any simplified-character change is in `jsc-hooks/hooks/simplified.txt` as well.
7. Run `tools/ste100-lint.sh` over every jsc repo (`tools/sync-domains.sh` prints the repo paths). The repos are independent, so lint them **in parallel**, one run per repo. Route each exit code: 0 — that repo is clean; 1 — hits printed as `{檔案}:{行號}:{類別}:{命中內容}`; 2 — no target was given, so fix the arguments and rerun, never read it as clean. Fix hits in files this repo owns. Completion condition: the lint exits 0 for this repo, and hits in other repos are reported with `file:line` for their owners.
8. Run `tools/sync-skill-manifest.sh .` to sync the README's 「Skills 目錄」 section and bump the manifests. Route each exit code: 0 — the README block and all three manifests are synced; 1 — `skills/`, `README.md`, the `JSC-SKILLS` markers, a `SKILL.md`, a manifest, or a manifest `version` field is missing, so fix the named cause on stderr and rerun; 2 — usage error, the script takes exactly one argument; any other code — the script runs under `set -e`, so treat it as an environment fault and stop, never as a successful sync. Completion condition: all three manifests show the same new version.
9. Open a PR via `jsc-git:pr`. Completion condition: a PR URL comes back and is reported with the table format in [`../../references/pr-report.md`](../../references/pr-report.md).
10. Report this run's outcome to the local event stream — the last step of every run, **the step 1.3 early stop included**. Run:

    `jsc-hooks/tools/report-status.sh skill-end jsc-meta:ste100-sync {status} {exit code} [detail]`

    Resolve `jsc-hooks` the same way step 6 resolves `jsc-hooks/hooks/simplified.txt`: the sibling checkout in the workspace. On the step 1.3 early stop, where `tools/sync-domains.sh` has not run, that sibling path is the only source. **When the script is not on this machine, skip this step in silence and close the run as normal.** A reporting path that is absent must never fail the run it reports on, and this call's own exit code never changes what this skill reports.

    Pick `{status}` from what the run actually did:

    | status | Use it when |
    | --- | --- |
    | `ok` | upstream had a new version and every adopted change is in `references/ste100.md`, the lint runs clean here, the manifests are bumped and the PR is open — **and also when step 1.3 stopped the run on 「上游沒有新版」**, because that is this skill's normal ending, not an abort |
    | `blocked` | a gate or a missing prerequisite stopped the run before any comparison — the call itself was refused, or neither the raw read nor the clone could reach upstream, so no version could be compared |
    | `failed` | the run broke mid-way — `sh -n tools/ste100-lint.sh` kept failing after the pattern edit, or `sync-skill-manifest.sh` could not be resolved |
    | `degraded` | the sync landed with a part missing — this repo lints clean but hits in other repos were only handed to their owners, or a simplified-character change reached the lint and not `jsc-hooks/hooks/simplified.txt` |
    | `aborted` | the user stopped the run, or the user dropped every distilled change so nothing was left to apply |

    `{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.

    The matching `skill-start` comes free from the hook, which fires when the skill loads. The comparison and the sync happen in the model turns after that, so no hook can see how the run ended — a `start` with no `end` reads as an abort, which is why writing the `end` is this skill's own job, and why the 「上游沒有新版」 path must write one too.

    Completion condition: one `skill-end` line for this run is appended to `$JSC_HOME/usage/events.jsonl`, or the script was absent and the final report says so.

## Notes

- Generated wiki content, commit messages, and PR descriptions stay in Traditional Chinese per the guidelines; only the rule distillation is at stake here.
- This skill fits the maintenance flow: list it as a maintenance method for the `plugins/meta` repo in `jsc-sdlc:maintain`.