pi-update
Load to check the kendex Pi extensions against a Pi release, fix what breaks, and record the verdict.
vanillagreencom · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add vanillagreencom/kendex --skill pi-update技能说明
name: pi-update description: "Load to check the kendex Pi extensions against a Pi release, fix what breaks, and record the verdict." summary: "Pi compatibility audit: capture the target release, audit its changelogs, apply the pi-hooks blocking rule, prove the real extensions against its SDK, fix forward, record one verdict, notify the fleet and hand publication to npm-deploy."
Project Instructions
Problems with a kendex-owned skill go through kendex report; check ownership in the file first.
Pi update
Checks pi-extensions/* against a Pi release and records one verdict. The record is pi-extensions/pi-update.audit.md, the one compatibility record. The marker pi-extensions/pi-update.state.json only says which releases were read. The rule the verdict applies is pi-extensions/AGENTS.md.
Release handling
- Pin nothing, freeze nothing, hold no release back. Fleet lanes follow the vendor's latest Pi through the fleet's
fleet-cli-update. Aholdverdict stops a peer floor from rising, never a lane from updating. - Start the run as soon as a new release is seen.
- The Linear item a new Pi release creates, and every follow-up a failing run files, is priority High (2), never Backlog. A failing run is fixed forward, never by pinning Pi to an older release.
Input
- No argument: the target is npm's current
latestof@earendil-works/pi-coding-agent. - A version: that version is the target. Every source is still fetched.
- A pasted changelog: the authoritative entry list for the range; changelog fetching is skipped. The target is the highest released version header in the paste, and step 1 captures that version.
1. Capture the target
Read the target once, at the start, and use these values for the whole run:
npm view @earendil-works/pi-coding-agent@<latest|version> version dist.integrity gitHead
gh api repos/earendil-works/pi/commits/v<version> --jq .sha
The two commit values must match; a mismatch stops the run. Record the version, the integrity, the upstream source commit and git rev-parse HEAD as the run-start head.
Create this run's own directory with mkdir -p tmp/pi-update && mktemp -d tmp/pi-update/run.XXXXXX; <run> is the path it prints, and the record's Evidence names it. A retry starts a new <run>. Write the candidate record under tmp/pi-update/. The committed pi-update.audit.md keeps the last cleared record until step 6 replaces it.
2. Audit the range
-
Marker. In scope is every released version header above
lastVersionand at or below the target. A target at or belowlastVersionmeans nothing to audit: refreshlastRunandlastRunHead, commit the marker, stop.lastVersionandlastDatenever move backward. -
First run (marker absent): propose a baseline, the newest Pi version named in
git log, and ask the user to confirm it before any work. Seed the marker there. -
Sources. Enumerate every changelog on each run; never trust a stored list:
gh api 'repos/earendil-works/pi/git/trees/main?recursive=1' --jq '.tree[].path | select(endswith("/CHANGELOG.md"))' gh api repos/earendil-works/pi/contents/<path> -H "Accept: application/vnd.github.raw"A source key is the path without
packages/and/CHANGELOG.md. Record every key in the marker'ssourcesCovered; report a key present last run and absent now. https://pi.dev/news/releases is a cross-check only. A## [Unreleased]block is a heads-up, never in scope. -
Classify each entry into one bucket:
- Required parity fix: Pi changed a behaviour, event shape, provider input or setting that an extension overrides, mirrors, reads or copied.
- Optional improvement: a new Pi field, helper or event that could simplify an extension that is still correct.
- Non-impact: outside every extension surface. One line of reason each.
-
Triage by import. A source reaches every package that imports its npm package (
coding-agentis@earendil-works/pi-coding-agent,aiis@earendil-works/pi-ai,agentis@earendil-works/pi-agent-core,tuiis@earendil-works/pi-tui, and so on). Find them on each run, never from a stored list:grep -rlE "['\"]@earendil-works/pi-<name>['\"/]" pi-extensions/*/ --include='*.ts' --include='*.mjs' --include='*.js' --exclude-dir=node_modules --exclude-dir=tests --exclude-dir=__tests__. For anaientry that names a provider, also greppi-extensions/*/for that provider id: a package that registers the provider is in reach. A source that no package imports is Non-impact. -
For each Required or Optional entry, cite the affected
path::symboland read the Pi source when a field name is unclear.
3. Apply the blocking rule
Read pi-extensions/pi-hooks/pi-contract.json for the events and calls pi-hooks uses; never a fixed list. Check every ### Breaking Changes entry in range, from every source, against it. The rule for an entry that names one is pi-extensions/AGENTS.md. List each Breaking Changes entry in the record's Verdict table with the contract names it carries.
4. Prove behaviour against the target
Package suites run on older pinned Pi versions and fake hosts, so a green suite does not prove a contract change. For every Required entry and every blocking entry:
- One install location. Node resolves an import from the importing file's own directories, so an install beside a package is invisible to it. Copy the whole
pi-extensionstree without anynode_modules, so a test that imports a sibling package by relative path finds it. Each time this step runs, make a new directory withmktemp -d <run>/work.XXXXXXand copy into it withrsync -a --exclude node_modules pi-extensions <that directory>/.<copy>ispi-extensions/<package>inside that directory. In<copy>, run `npm install --no-save --