stable-release
The stable-release skill promotes an already-shipped rolling release (vX.Y.Z) of the DOS kernel to a named stable channel by verifying a green kernel test suite, a clean truth syscall result, and a completed soak window. It writes an evidence file and adds a stable/<codename> git tag to the same commit without building new artifacts or bumping versions. Use this skill when you want to mark a particular rolling release as trustworthy for production after manual or scheduled promotion.
git clone --depth 1 https://github.com/anthony-chaudhary/dos-kernel /tmp/stable-release && cp -r /tmp/stable-release/.claude/skills/stable-release ~/.claude/skills/stable-releaseSKILL.md
# Stable Release — a named channel on top of rolling `/release` (DOS)
`/release` ships a rolling tag (`vX.Y.Z`) whenever DOS lands user-visible change.
That tag promises "this commit merged" — it does **not** promise "the substrate
was provably trustworthy here." This skill adds a second, less-frequent channel
that does make that promise.
A stable release is a **promotion of an already-shipped commit**, not a new
build. No new version is minted. No new wheel or zip is produced. The gate is
read at promote time, frozen into an evidence file, and a second annotated tag
(`stable/<codename>`) is pinned on the same commit.
> **This is the DOS adaptation of `job`'s stable-release skill.** job gates on
> apply-loop hero metrics (silent-failure share, PSV verified-success rate,
> funnel-stage regressions) and KEEP-slot baselines from `execution-state.yaml` +
> `baselines.yaml`. **None of that exists in DOS** — DOS is a domain-free trust
> substrate, not an apply pipeline; it has no runtime funnel, no hero metric, no
> baseline ledger. So the gate is re-grounded on the only "known-good" signals
> DOS actually has: a green kernel suite, a clean truth syscall, and a soak
> window. See "The gate" below.
**Trunk is `master`.** The stable tag is pinned on a commit reachable from
`master`; the push targets `master`'s remote.
**The kernel-vs-tooling boundary.** The gate context script
(`scripts/stable_release_context.py`) and this skill are **dev/release tooling
that operates ON the package** — never imported BY `dos.*`. The
"kernel imports no host, no `scripts/`" litmus in `CLAUDE.md` stays intact.
## Relationship to other systems
| System | Owns | Stable-release reads | Stable-release writes |
|---|---|---|---|
| `/release` (`scripts/release_bump.py`) | rolling `vX.Y.Z` tag, version markers | the latest `vX.Y.Z` as promotion candidate | nothing — never re-bumps |
| the kernel suite (`pytest`) | substrate correctness | exit code (green == eligible) | nothing |
| the truth syscall (`dos verify`) | ground-truth adjudication | exit + verdict (well-formed == eligible) | nothing |
| git tags | the channel itself | `stable/*` collision check + previous-stable | one new `stable/<codename>` tag |
The spec deliberately introduces **no** new state machine, database table, or
pipeline event. It reuses git tags + the suite + the syscall.
## When to invoke
The user (or a scheduled cron) invokes this skill. Typical triggers:
- After a `/release` that landed a meaningful kernel change and you want a
rollback anchor that says "the substrate was provably good here."
- Quarterly hygiene — pick the highest `vX.Y.Z` that satisfies the gate.
- After a regression rollback, to mark the recovered state.
**Cadence — the two-channel contract.** Rolling `vX.Y.Z` tags ship continuously:
`/release` is deliberately cheap, and a coherent unit that clears the mechanical
gates (suite, leak scan, CI, the publish ci-green witness) just ships — several
per week is healthy. The stable channel is the deliberate counterweight: an
infrequent, gate-driven promotion that answers "which version do I pin in
production." There is still **no fixed calendar** — the gate either passes or it
doesn't — but the working rhythm is: promote the highest soaked-green tag
(a) after a milestone (a new syscall family, a major/ABI bump, the first
PyPI-published era), or (b) when a meaningful run of rolling tags has accumulated
since the last stable — every few weeks, not every few days. Rolling moves fast
*because* stable exists to absorb the trust question; stable can afford its soak
window *because* rolling carries the urgency.
## Codename convention
Operator picks one short word at promote time, prefixed by year-month:
`stable/2026-06-aardvark`. Memorable, sortable, and rollback becomes meaningful
(`git checkout stable/2026-06-aardvark` says "the substrate was good here" in a
way `git checkout v0.3.0` never claimed).
Validate: `^\d{4}-\d{2}-[a-z][a-z0-9-]{2,20}$` (the context script enforces this).
Reject ambiguous reuses by checking `git tag -l 'stable/*-<codename>'`.
---
## Step 1 — Pre-digest the gate context
One helper collapses every gate read into one JSON payload:
```bash
python scripts/stable_release_context.py --codename <codename>
# --from vX.Y.Z pin the candidate (default: latest semver tag)
# --window-days N min soak age for the candidate tag (default 3)
# --skip-pytest smoke / dry inspection only (do NOT use for a real promote)
# --force-promote report blockers but mark all_green-eligible (records rationale)
```
The script returns:
```json
{
"candidate_tag": "v0.3.0",
"candidate_sha": "abc123…",
"codename": "2026-06-aardvark",
"window_days": 3,
"previous_stable": {"tag": "stable/2026-05-zephyr", "sha": "…"},
"tag_collision": false,
"idempotency": {
"tag_exists": false, "tag_sha": null, "tag_matches_candidate": null,
"evidence_file_exists": false, "evidence_path": "docs/stable-releases/2026-06-aardvark.md"
},
"gate": {
"pytest_suite_green": {"name": "...", "pass": true, "exit_code": 0, "summary_tail": "..."},
"ci_green": {"name": "...", "pass": true, "verdict": "GREEN", "advisory": false, "reason": "..."},
"dos_verify_clean": {"name": "...", "pass": true, "exit_code": 1, "verdict": {...}},
"tag_age": {"name": "...", "pass": true, "age_days": 5.2, "window_days": 3}
},
"summary": {"all_green": true, "blockers": [], "forced": false}
}
```
If `summary.all_green` is `false`, the skill **stops** and reports the failing
rows — exactly which gate row blocked promotion and its reading. This is the
entire point of the skill; never paper over a red gate.
> **`dos_verify_clean` exits 1 on a healthy no-plan repo — that is a PASS.** The
> truth syscall's exit code carries the *ship verdict* (0 shipped / 1 not), not
> execution health. The gate probes with a sentinel `(plan, phase)` that never
> shipped, so a healthy syscall returns `shippeAdjudicate a GitHub issue's "this is resolved" claim from witnesses the claimant didn't author — then close it carrying the evidence, or refuse with the typed gap. Use when an issue looks already-solved, after landing a fix that should have closed one, or to sweep open issues for silently-resolved ones.
Pick the next most important open GitHub issue this agent can actually complete, make its done-condition true, land it with witnesses (suite + parity + commit-audit), and priority-tag every issue touched along the way. Use when asked to "work the backlog", "complete the next most important issue", or to fix a specific issue number end-to-end.
Cut a versioned release of the DOS kernel — bump the version, draft release notes, commit, tag, push to master, and create a GitHub release. The tag push triggers the gated PyPI publish pipeline (publish.yml); the skill surfaces the run and its approval gate.
One automatic plan-class lifecycle tick. Reads the DECLARED class set + transition list from the workspace `[lifecycle]` table (not a hardcoded taxonomy), evaluates each trigger, spawns a read-only JUDGE-rung adjudicator (the `dos.judges` seam — advisory, fail-to-abstain) to approve/defer each candidate transition, applies the gated transitions as plan-meta edits + one commit per cycle, and logs to the run archive. Failsafes (per-cycle cap, per-plan cooldown, a veto class) are `[lifecycle]` data; the judge content is a host `dos.judges` driver. Every path/class comes from `dos doctor --json`. Use to garden a plan portfolio's lifecycle automatically, judge-gated. The DOS lifecycle gardener (SKP Axis 5, docs/207 Phase 5c).
Run /dos-dispatch on a recurring cadence, alternating with /dos-replan when the backlog drains — the dispatch→replan→dispatch cycle. The continue/stop/next-mode decision is the kernel's typed loop decision, not inline prose: each iteration is classified (`dos gate`) into a verdict and the loop's counters (drained-twice, the unclear/dirty-zero breakers, the iteration cap) drive the next step. Several loops on disjoint lanes run concurrently, each taking its own lane lease via `dos arbitrate`. Driven entirely by `dos` verbs + the workspace's `dos.toml`. The DOS reference loop workflow (SKP Axis 5).
End-to-end plan-and-ship for one lane — snapshot the portfolio with /dos-next-up, take a lane lease via `dos arbitrate` so parallel dispatches don't collide, gate the empty case via `dos gate`, ship the packet, and archive the run under the configured run dir. Driven entirely by `dos` verbs + the workspace's `dos.toml`; names no host path, lane, or commit convention. Use when you want to plan and ship the next batch on one lane in a single command, with concurrency safety. The DOS reference dispatch workflow (SKP Axis 5).
Ground a "keep working until the goal is met" stop condition in a witness the agent did not author, instead of letting the agent self-certify "done". A harness goal/Stop-hook condition is normally checked by the model re-reading its OWN work — consistency, not grounding. This skill turns the operator's goal into checkable EFFECT claims and wires `dos hook stop` so the Stop is refused until git ancestry (a shipped phase) or an effect read-back corroborates the claimed effect. Driven by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Use when you want a self-stopping agent (or a `/loop` worker) to be unable to declare a goal complete on its own say-so. The single-agent self-stop analogue of `dos-witness-claim`.
Snapshot a repo's phased-plan portfolio and produce a parallel-agent dispatch packet, driven entirely by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Walks the configured plans glob, audits each candidate pick against `dos verify` for its true shipped/unshipped status, renders a self-contained packet to the configured output dir, and reports a typed gate verdict via `dos gate`. Use when you want a "where are we / what's next / who-does-what" snapshot of any repo that has a few plan docs and real commits. This is the DOS reference workflow (SKP Axis 5); a host may use it, fork it, or ignore it.