odylith-release-planning

Release Planning

CLI-First Non-Negotiable

• CLI-first is non-negotiable for both Codex and Claude Code. Remove all hand-authoring for places where Odylith CLI should be doing the heavy-lifting. When an Odylith CLI command exists for an operation, you must call the CLI command and you must not hand-edit governed files the CLI owns. Hand-authoring governed truth where a CLI exists is a hard policy violation, not a stylistic preference. The authoritative policy, CLI surface enumeration, allowed hand-edit surfaces, and failure-mode handling live in odylith/agents-guidelines/CLI_FIRST_POLICY.md, anchored by Casebook learning CB-104. The rule travels through routed spawn_agent leaves on Codex and Task-tool subagents on Claude Code, so delegated work inherits the same contract.

Use this skill when the operator wants to define releases, name a release, inspect release scope, or add, remove, and move backlog workstreams between release targets such as current, next, a version, a tag, or a named release.

Goal

• Keep release-planning truth explicit, auditable, and repo-local.
• Make natural phrasing like "add B-123 to current release" map to one deterministic CLI and source contract.
• Keep release planning separate from umbrella execution waves and separate from the canonical maintainer publication lane.
• Governance-learning: release claims require fresh governance learning. Do not build, publish, or claim release readiness while escaped defects, failed simulations, contract changes, topology changes, or proof checkpoints are still only in chat memory. Search existing Casebook and related governance truth first, read prior failed mechanisms, do not repeat a fix path that already failed, and route new mechanism-level learning through Casebook, Radar/plans, Registry, Atlas, and Compass before release closeout.

Keep It Separate

• Use release planning when the question is "what release should this workstream ship in?" Example: B-067 -> 0.1.11.
• Do not use this skill for umbrella sequencing questions such as "what should happen in W1, W2, and W3?" That is program or execution-wave planning under the Radar umbrella contract, not odylith release ....
• The same workstream may participate in both because release target and execution order are different truths.

Canonical Source Truth

• odylith/radar/source/releases/releases.v1.json Release registry with immutable release_id, optional version, tag, name, notes, lifecycle state, and explicit alias ownership.
• odylith/radar/source/releases/release-assignment-events.v1.jsonl Append-only add, remove, and move history for workstream targeting.

Canonical Commands

./.odylith/bin/odylith release list --repo-root .
./.odylith/bin/odylith release show current --repo-root .
./.odylith/bin/odylith release create release-2026-04 --repo-root . --alias current --version 0.1.11
./.odylith/bin/odylith release update current --repo-root . --name "Boringly Trustworthy"
./.odylith/bin/odylith release add B-123 current --repo-root .
./.odylith/bin/odylith release move B-123 next --repo-root .
./.odylith/bin/odylith release remove B-123 --repo-root .
./.odylith/bin/odylith validate backlog-contract --repo-root .
./.odylith/bin/odylith sync --repo-root . --check-only --runtime-mode standalone

Selector Rules

• Resolve releases by exact release_id, alias, exact version, exact tag, or unique exact name.
• Prefer release:<id> when a human name or version could collide.
• Treat current release, release current, next release, and release next as alias phrasing, not fuzzy search.
• Ambiguous selectors must fail closed. Do not guess.

Mapping Natural Requests

• "Add B-123 to current release"
  • odylith release add B-123 current
• "Move B-123 to next release"
  • odylith release move B-123 next
• "Remove B-123 from release 0.1.11"
  • odylith release remove B-123 0.1.11
• "Name the release"
  • odylith release update <selector> --name "..." or set --name during create

Guardrails

• release_id is immutable after creation.
• current and next are explicit aliases owned by source truth, not inferred from semver or dates.
• The current active release remains visible in governed read surfaces until it is explicitly updated to shipped or closed. Zero targeted workstreams is an empty state, not implicit GA.
• Changing the current or next alias only changes the release selector. It does not move any workstreams. Never bulk-retarget older active work just because the target release changed.
• Move only the explicit workstream ids that are part of the current release slice. Older release workstreams, including completed work, keep their original release history so Radar and Compass filters stay truthful.
• Finished work removed during release closeout may still appear in governed read surfaces as completed release members; that history does not make the workstream an active target again.
• One workstream may have at most one active release target at a time. Use move, not a second add, when work carries forward.
• finished, parked, and superseded workstreams cannot stay in active releases.
• shipped and closed releases are terminal for active planning. Move alias ownership off them before lifecycle closure.
• Release name is explicit operator-owned source truth. Matching authored release notes may exist for the same version, but they must never rename or override the release-planning record without explicit maintainer authorization.
• In practice, release names only change through an explicit odylith release create ... --name or odylith release update ... --name operation.
• If name is blank, release-planning surfaces may fall back to version, then tag, then release_id; they must never inherit a release-note title as the release name.

Working Flow

1. Inspect the current release catalog and alias ownership first.
2. Create or update the release definition if the target release does not yet exist or needs a new name, version, tag, or alias.
3. Add, move, or remove workstreams through the release CLI rather than by editing source files manually.
4. Run at least odylith validate backlog-contract --repo-root . after release mutations.
5. If the release change affects governed read surfaces, refresh or prove them through odylith sync --check-only --runtime-mode standalone.
6. When the release actually ships to GA, move aliases as needed and explicitly mark the record shipped or closed; until then, expect the current release to remain visible even if it has zero targeted workstreams.