From f5d37b584463fd4e97393da69c3969a957ca2bac Mon Sep 17 00:00:00 2001
From: Rickylabs <eric.chautems@gmail.com>
Date: Sat, 18 Jul 2026 23:44:40 +0200
Subject: [PATCH] docs(release-skill): canary versions must encode their target
 release (doctrine for #888)

Refs #888
---
 .agents/skills/netscript-release/SKILL.md | 10 ++++++++++
 .claude/skills/netscript-release/SKILL.md | 10 ++++++++++
 2 files changed, 20 insertions(+)

diff --git a/.agents/skills/netscript-release/SKILL.md b/.agents/skills/netscript-release/SKILL.md
index 5a304e745..64a8aad0e 100644
--- a/.agents/skills/netscript-release/SKILL.md
+++ b/.agents/skills/netscript-release/SKILL.md
@@ -84,6 +84,16 @@ prerelease version. For stable target `<next-version>`, the version is `<next-ve
 `N` is one greater than the highest matching version found across all workspace-member JSR metadata
 (including yanked versions), with existing git tags as a collision guard.
 
+**Canary versioning doctrine (owner decision, 2026-07-18, tracked as #888):** the canary version
+must encode the release it is tied to — `<target-version>-canary.N` for the ACTUAL target,
+including prereleases: the beta.12 cut publishes `0.0.1-beta.12-canary.1`, and only the real stable
+cut publishes `0.0.1-canary.N`. The beta.11 cut published `0.0.1-canary.1` because
+`validateStableTarget` in `.llm/tools/release/canary.ts` still refuses prerelease targets — that is
+accepted debt for beta.11 only, not a template. When dispatching `release-canary.yml` for a
+prerelease cut before #888 lands, the `target-version` input must be the eventual stable version
+(the tool derives `<stable>-canary.N` and binds the pair status to the content SHA, which is what
+authorizes the prerelease tag); after #888 lands, pass the real prerelease target instead.
+
 The workflow invokes `deno task release:canary -- <next-version>` to perform the shared coordinated
 bump/gates and create the ephemeral branch plus provenance tag without a release PR. Operators may
 use `--dry-run` in a disposable checkout to rehearse preparation, but must not run a non-dry canary
diff --git a/.claude/skills/netscript-release/SKILL.md b/.claude/skills/netscript-release/SKILL.md
index 5a304e745..64a8aad0e 100644
--- a/.claude/skills/netscript-release/SKILL.md
+++ b/.claude/skills/netscript-release/SKILL.md
@@ -84,6 +84,16 @@ prerelease version. For stable target `<next-version>`, the version is `<next-ve
 `N` is one greater than the highest matching version found across all workspace-member JSR metadata
 (including yanked versions), with existing git tags as a collision guard.
 
+**Canary versioning doctrine (owner decision, 2026-07-18, tracked as #888):** the canary version
+must encode the release it is tied to — `<target-version>-canary.N` for the ACTUAL target,
+including prereleases: the beta.12 cut publishes `0.0.1-beta.12-canary.1`, and only the real stable
+cut publishes `0.0.1-canary.N`. The beta.11 cut published `0.0.1-canary.1` because
+`validateStableTarget` in `.llm/tools/release/canary.ts` still refuses prerelease targets — that is
+accepted debt for beta.11 only, not a template. When dispatching `release-canary.yml` for a
+prerelease cut before #888 lands, the `target-version` input must be the eventual stable version
+(the tool derives `<stable>-canary.N` and binds the pair status to the content SHA, which is what
+authorizes the prerelease tag); after #888 lands, pass the real prerelease target instead.
+
 The workflow invokes `deno task release:canary -- <next-version>` to perform the shared coordinated
 bump/gates and create the ephemeral branch plus provenance tag without a release PR. Operators may
 use `--dry-run` in a disposable checkout to rehearse preparation, but must not run a non-dry canary