project-version-baseline

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

1. 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.)
2. 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.

1. Confirm target: report shows the latest stable; the dev host should already run it.
2. 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).
3. 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).
4. 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).
5. bash scripts/ci/all.sh && bash tests/hooks/run.sh — Position 14 must be green (mirrors consistent).
6. 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.