| name | project-version-baseline |
| description | Audit and update the agent-runtime-kit version baseline: check README/harness-shape mirrors against runtime-roots.yaml and nils-cli-pin.yaml, report installed-vs-latest, and guide the codex/claude product-floor bump ceremony.
|
| argument-hint | [check|report|bump <codex|claude> <version>] |
| allowed-tools | Bash, Read, Edit |
Project Version Baseline
Maintains the agent-runtime-kit "version baseline" — the codex / claude product
floors and the nils-cli surface pin — and keeps every human-facing mirror in
sync with its source of truth. Invoke it to answer "is there a newer
codex/claude I should bump to?", to diagnose a baseline-audit (Position 14)
failure, or to drive a product-floor bump end to end.
Contract
Prereqs:
- Run inside the
agent-runtime-kit git work tree.
python3 on PATH. For report, optionally npm (latest-version lookups are
best effort and degrade to ? when offline).- For a bump: a clean managed worktree (
git-cli worktree add … --kind chore),
host agent-runtime on-pin (Position 2), and the semantic-commit /
forge-cli surfaces available.
Inputs:
check (default) — deterministic consistency gate.report — advisory installed-vs-latest probe + the gate result.bump <product> <version> — guided product-floor bump (manual edit steps
below; the skill does not auto-rewrite files).
Outputs:
check / report: a status table and per-check ok / FAIL lines.bump: edits to the product-floor lockstep set, a re-pinned golden if needed,
a green scripts/ci/all.sh, and a filled min-version-bump PR body.
Exit codes:
0: gate passed (check) or advisory printed (report).1: drift detected, or a prerequisite is missing.2: usage error.
Failure modes:
- Not inside the git work tree, or
scripts/ci/version-baseline-audit.py absent.
- A mirror format changed and the audit regex no longer matches (update the
audit alongside the doc).
Scripts
- Canonical audit (run from the repo root):
python3 scripts/ci/version-baseline-audit.py [check|report] — the same
implementation scripts/ci/all.sh Position 14 runs.
- Skill wrapper:
.agents/skills/project-version-baseline/scripts/project-version-baseline.sh [check|report] — a thin delegate to the canonical audit (resolves the repo
root via git rev-parse, so it works from any cwd inside the work tree).
Where the baseline lives (and the update rule)
| Category | Source of truth | Mirrors (kept in sync) | Rule |
|---|
| Product floor (codex / claude) | manifests/runtime-roots.yaml (min_version, recommended_version, min_version_effective_from) | README.md "Version baseline" table; docs/source/harness-shape-<product>.md "Version Floors" statement | move in lockstep during a bump |
| nils-cli surface pin | docs/source/nils-cli-pin.yaml (pinned_tag) | README.md row; docs/source/nils-cli-surface.md; "pinned snapshot" line in each harness-shape doc | owned by meta:nils-cli-bump; this skill only verifies the prose mirrors match |
Per-surface min_product | manifests/surfaces.yaml | rendered into SUPPORT_MATRIX.md (+ golden); per-surface tables in harness-shape docs | independent of the floor; moves only when a surface gains a real dependency (see PR #344) — do NOT bulk-move |
| Rendered / golden | manifests/surfaces.yaml + templates | SUPPORT_MATRIX.md, tests/golden/** | never hand-edit; regenerated by agent-runtime render |
Workflow
A. "What can be updated?" / audit
python3 scripts/ci/version-baseline-audit.py report — prints
floor/installed/latest for codex & claude (verdict current / update available / HOST BELOW FLOOR) and the nils-cli pin, then the consistency
gate result. (Or the skill wrapper above from any cwd.)- If the gate reports drift, fix the mirror that disagrees with its source of
truth (the table above names the owner), or run a bump (Section B).
B. Product-floor bump ceremony (codex or claude)
Only the product floor moves here. Follow
.github/PULL_REQUEST_TEMPLATE/min-version-bump.md.
- Confirm target:
report shows the latest stable; the dev host should already
run it.
- Edit the lockstep set to the new version:
manifests/runtime-roots.yaml — <product>.min_version and
recommended_version → new version; min_version_effective_from → a
forward date (~14-day runway from today).README.md "Version baseline" row for the product (value + (effective …)).docs/source/harness-shape-<product>.md "Version Floors" statement
(min_version / recommended_version and min_version_effective_from).
- Do NOT touch per-surface
min_product in manifests/surfaces.yaml,
SUPPORT_MATRIX.md / goldens, or the nils-cli pin (those are independent /
rendered / owned by meta:nils-cli-bump).
agent-runtime render --product codex && … --product claude && … --target support-matrix, then confirm git diff -- tests/golden/ is clean (a pure
floor bump produces no golden churn).bash scripts/ci/all.sh && bash tests/hooks/run.sh — Position 14 must be
green (mirrors consistent).- Commit via
semantic-commit (chore(runtime): …) and open the PR via
forge-cli, filling the min-version-bump template (include
agent-runtime doctor --product <product> --suggest-upgrade output).
Boundary
Project-local skill. It must not mutate the nils-cli pin (defer to
meta:nils-cli-bump), per-surface min_product, rendered product output,
golden snapshots, global runtime homes, credentials, sessions, or caches.
