Docs: add bump-toolchain-versions skill

[chenshengxin2026]

What

Adds .claude/skills/bump-toolchain-versions/SKILL.md — an SOP skill for
advancing the two external toolchain versions the CI pipelines depend on:

• ptoas — the assembler binary on the codegen -> device path
• pto-isa — the ISA header repo, pinned by a 40-char commit SHA

across the three repos (simpler, pypto, pypto-lib).

Why

The bump procedure has a strict ownership model (one source of truth per
artifact) and a required propagation order. Capturing it as a skill keeps the
process reproducible and prevents editing derived values by mistake.

Contents

• Ownership model: simpler/pto_isa.pin owns pto-isa; pypto/toolchain/versions.env
  owns ptoas; pypto-lib inherits both from pypto's main with no code edit
  under the current derive-from-pypto CI layout.
• Propagation order: simpler -> pypto -> pypto-lib.
• Fork-and-PR flow, value-gathering steps with self-checks, verification/monitoring,
  and a checklist.
• Known CI gotchas (cold-cache .tmp race on the first run of a new version,
  onboard flakes) so they are not misdiagnosed as a bad bump.

Documentation-only change under .claude/skills/; no runtime or kernel code is affected.

[gemini-code-assist]

Code Review

This pull request adds a new Claude skill documentation file (SKILL.md) that provides a comprehensive Standard Operating Procedure (SOP) for bumping CI toolchain versions (ptoas and pto-isa) across the simpler, pypto, and pypto-lib repositories. The document clearly outlines repository ownership, propagation steps, verification commands, and troubleshooting guidelines for common CI issues. No review comments were provided, and the added documentation is thorough and well-structured.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 24506b51-062f-4991-90cb-80591862011d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new SOP Markdown document describing the procedure for bumping ptoas and pto-isa toolchain versions across the simpler, pypto, and pypto-lib repositories, including ownership rules, PR creation steps, verification, and CI gotchas.

Changes

SOP Documentation

Layer / File(s)	Summary
New bump-toolchain-versions SOP .claude/skills/bump-toolchain-versions/SKILL.md	Adds a complete SOP describing ownership model for pto-isa and ptoas toolchain versions, user-confirmed version selection, sha256 validation, per-repo PR creation steps (simpler, pypto, pypto-lib), verification steps, CI gotchas, and a final checklist.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• hw-native-sys/pypto-lib#144: Also adds CLAUDE skill documentation targeting the pypto/simpler runtime submodule synchronization mechanics referenced in this SOP.

Poem

A hop, a skip, a version bump,
SHA-256 checked with a thump,
Three repos linked in tidy chain,
pto-isa, ptoas — no more pain.
This rabbit's SOP keeps CI sane! 🐇📜

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the documentation addition for the bump-toolchain-versions skill.
Description check	✅ Passed	The description is directly related to the new SOP skill and accurately describes its contents and purpose.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chenshengxin2026]

Updated the skill to fix a correctness issue in the pto-isa propagation model (synced from the same fix applied to the simpler/pypto copy).

Problem: the SOP treated "bump the runtime/ submodule pointer" as a mechanical step of a pto-isa bump. But pypto has no independent pto-isa knob — the toolchain job derives PTO_ISA_COMMIT only from runtime/pto_isa.pin (the simpler commit the submodule points at), and the guard forbids pinning it elsewhere. The submodule points at a whole simpler commit, so moving pypto's pto-isa necessarily moves the runtime by however many commits it lags simpler main. When that lag is non-trivial, it's really a runtime version bump (adaptation-prone) — the pypto team's routine chore(runtime) work, not a toolchain step.

Changes (content only; the $GH_USER/$GIT_NAME/$GIT_EMAIL de-hardcoding in this PR is untouched):

• Ownership model: added a ⚠️ consequence spelling out the coupling.
• Propagation order + Step 1 note: pto-isa version bump = the simpler pin PR; pypto pickup is a separate runtime-bump decision, not automatic.
• Step 2b rewritten to gate on the runtime lag — STOP and defer to the pypto team if the lag is non-trivial; only proceed (own PR, target simpler-main HEAD) if trivial and explicitly wanted. Uses git update-index --cacheinfo to move only the gitlink.
• Checklist updated to match.

PR scope is still a single file (.claude/skills/bump-toolchain-versions/SKILL.md); commit amended to keep the "add skill" history clean.