feat(release): add mandatory canary publish gate

[rickylabs]

Summary

Adds the mandatory canary publish channel and composed publish-readiness gate for NetScript releases. The canary reuses the production OIDC publisher, dispatches and awaits the exact canary-pinned production E2E run, and records a SHA-bound green-pair status that stable publication must verify.

This remains a draft. Do not merge: the supervisor-triggered IMPL-EVAL returned FAIL_FIX; findings F1/F2 are repaired at 64184deb, and a fresh supervisor verdict is pending.

Scope

• Archetype / area: Archetype 6 — release tooling and CI
• Closes release: canary publish channel — mandatory authenticated pre-publish gate with post-canary live production CI, + publish-readiness automation #811
• Integrates merged PR fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810 by calling its canonical release:preflight; no scanner logic is duplicated.

Slices

• S1 harness bootstrap and locked design — 1c84e197
• S2 shared release preparation and canary cut — 4f60ab36
• S3 composed publish-readiness verdict — 5a41004f
• S4 canary workflow and green-pair enforcement — ed4573aa
• S5 mandatory canary-first doctrine and mirror — cce21549
• S6 initial evidence handoff — ddd4242e
• S7 supervisor FAIL_FIX repair: merge current main, real detector test, live red proofs — 64184deb

Definition of Done

• release:canary derives <target>-canary.N from existing JSR versions, uses the shared stable-cut gates, creates no release PR, and retains only its provenance tag after workflow cleanup.
• release-canary.yml runs readiness, provisioning, the existing real-publish path, and the exact canary-pinned e2e-cli-prod run without marking a release Latest.
• The green pair is recorded for the content SHA and release:publish fails closed without a matching successful pair.
• Publish readiness reports structured evidence for new-package, publish-set, lockstep/residue/versionless-specifier, provisioning, and canonical import-attribute preflight checks.
• Every new readiness check is proven to fail on a seeded violation; the complete release test suite is green.
• fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810 integration is documented in both PR bodies and its preflight implementation is reused rather than duplicated.
• The canonical release skill and generated mirror mandate canary-first publishing, generated-assets preflight, exact-version/min-age handling, same-semver retry, yanking policy, and no ad-hoc publication.
• Required type/check/lint/fmt, skill-sync, no-suppression, and changed-file quality gates pass.
• Current origin/main is merged and the three conflicts are resolved.
• Live seeded text-import, versionless-specifier, and README-standard violations each fail publish:readiness with the required evidence.
• Fresh supervisor-triggered IMPL-EVAL returns PASS on the repaired head.

Validation

• PLAN-EVAL — PASS in separate session.
• Supervisor IMPL-EVAL — FAIL_FIX on pre-merge head ddd4242e: F1 missing real fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810 detector; F2 conflicts with current main.
• Repair head — 64184deb, a merge commit with parents ddd4242e and current main aa14e452.
• Real detector unit — PASS: readiness test spawns the actual preflight-text-imports.ts CLI against a seeded text-import fixture; the mocked detector throw is removed.
• Live text-import seed — required FAIL, exit 1: import-attribute-preflight reports generated-constant remediation, deno publish rejects ("import attribute type of text is unsupported") even though it is runtime-stable and --dry-run accepts it denoland/deno#35546, and authenticated-canary sunset.
• Live versionless seed — required FAIL, exit 1: versionless-specifiers reports the required version.
• Live first-publish README seed — required FAIL, exit 1: first-publish reports missing production H1/install/quick/docs requirements.
• Seed-free deno task publish:readiness — PASS, exit 0, all eight composed rows green.
• Full release-tools suite — PASS, 61/61.
• Release TypeScript check/lint/fmt — PASS on 32 files; check includes --unstable-kv.
• Repair-file quality scan — PASS, 0 findings / 0 allowances.
• Skill mirror sync — PASS, 17 skills / 21 mirrored files.

Harness

• Run dir: .llm/runs/feat-811-release-canary--canary-readiness/
• Repair evidence: .llm/runs/feat-811-release-canary--canary-readiness/repair-evidence.md
• Phase: FAIL_FIX repair complete; fresh supervisor IMPL-EVAL pending.
• The earlier generator-arranged Qwen PASS artifact is retained as history but is non-authorizing for this supervisor repair cycle. No self-evaluation is claimed.

Integration with #810

Merged PR #810 owns the import-attribute scanner and its conditional sunset. Current main is now merged into this branch, so publish:readiness delegates to the real canonical detector. The real-fixture test and live seed prove that boundary. Lift the ban only after denoland/deno#35546 is fixed, merged, and released in the pinned Deno version and an authenticated canary text-import probe is green.

OWNER actions after merge

• Confirm repository workflow permissions allow actions: write, statuses: write, and contents: write for the canary workflow.
• Confirm JSR_API_TOKEN has package-edit permission for first-publish provisioning and that every new @netscript/* package is linked to rickylabs/netscript; OIDC remains the publish credential.
• Run the first live canary pair and yank obsolete/failed canary versions when appropriate; JSR versions are immutable and are never deleted.

Drift / Debt

• Significant base drift omitted fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810's detector on the original evaluated head; repaired by merging current main and adding real/live detection proofs.
• Resolved the stale OIDC wiring debt without claiming the first live canary has run.
• No new architecture debt.

[rickylabs]

[PHASE: RESEARCH]

Re-baselined issue #811, PR #810, and the complete release toolbelt against origin/main@a5adb706.

Findings

1. Stable cut and canary cut can share the existing coordinated bump/residue/gate machinery.
2. Canary numbering must scan JSR metadata across the full publish set to survive partial publishes.
3. The green pair can be represented as a SHA-bound commit status only after the exact dispatched e2e-cli-prod run is green.
4. fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810 remains the sole owner of import-attribute detection; this PR calls release:preflight.
5. Baseline release suite: 29 passed / 0 failed.

Next

• Separate OpenRouter/Qwen PLAN-EVAL; no implementation before PASS.

Artifact: .llm/runs/feat-811-release-canary--canary-readiness/research.md

[rickylabs]

[PHASE: PLAN]

Locked a six-slice contract-first design for shared cut preparation, composed readiness, the canary workflow, SHA-bound green-pair enforcement, and mandatory release doctrine.

Commit

• 1c84e197 — harness bootstrap, research, design checkpoint, evaluator brief, and resumable context.

Gate

• Existing release tests: 29/29 PASS.
• Implementation remains blocked until separate-session PLAN-EVAL returns PASS.

Artifact: .llm/runs/feat-811-release-canary--canary-readiness/plan.md

[rickylabs]

PLAN-EVAL — PASS

Separate evaluator: Claude Code + OpenRouter/Qwen 3.7 Max (high), direct-only session 55159172-5792-49dc-a7aa-be92f8dc80a6.

All 8 Plan-Gate items passed. The evaluator spot-checked the current release toolbelt and PR #810 boundary, confirmed the six implementation slices and negative-proof gates, and found no open decision that forces rework. Implementation is unblocked at commit 6353ec49.

Evidence: .llm/runs/feat-811-release-canary--canary-readiness/plan-eval.md.

[rickylabs]

Implementation — slice 2/6: shared preparation + canary cut

Commit: 4f60ab36

• Factored the existing stable-cut bump → residue → release-set/preflight → release:preflight → publish:dry-run → deno ci --prod sequence into prepare-release.ts; release:cut now consumes it.
• Added release:canary and canary.ts: strict stable target input, <target>-canary.N, N=max across every effective member’s JSR metadata (including yanked keys) plus tag collision guard, ephemeral release/canary-* branch, immutable tag, and no PR path.
• JSR absence is 404-only; other HTTP or malformed metadata fails closed.

Evidence:

• targeted deno check --unstable-kv: PASS
• focused stable/canary/preparation tests: 15 passed, 0 failed
• separate opposite-family review: SLICE_REVIEW_PASS (Claude Opus 4.8 medium fallback; Fable 5 route returned model_not_found, logged in drift)

Next: composed publish-readiness evidence and seeded negative checks.

[rickylabs]

Implementation — slice 3: composed publish readiness

Commit: 5a41004f

• Added publish:readiness with ordered structured evidence for publish-set completeness, Markdown pins, lockstep/residue, versionless specifiers, new packages, first-publish standards, provisioning dry-check, and the canonical release preflight.
• Reused the fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810 task boundary and preserved its denoland/deno#35546 plus authenticated-canary sunset criterion; no scanner logic was duplicated.
• First-publish checks apply only to JSR-absent effective publish members. Registry failures fail closed and dependent checks skip instead of consuming partial evidence.
• The shared stable/canary preparation path now requires readiness before dry-run and production install.

Evidence:

• full .llm/tools/release/ suite: 51 passed, 0 failed
• touched slice TypeScript: deno check --unstable-kv PASS
• live repository deno task publish:readiness: PASS, all 8 checks
• every readiness row has a seeded negative proof
• independent opposite-family review: initial FAIL on an orphaned Markdown audit; repaired and re-reviewed SLICE_REVIEW_PASS

This slice is pushed with the explicit refspec to feat/811-release-canary.

[rickylabs]

Implementation — slice 4: canary workflow + green-pair enforcement

Commit: ed4573aa

• Added release-canary.yml: composed readiness → provisioning → the canonical dry-run/preflight/real-publish path, then exact workflow-dispatch correlation and awaited canary-pinned e2e-cli-prod.
• Records release/canary-pair on the pre-bump content SHA only after both live stages pass; cleanup is best-effort and reported.
• Stable publishing and github-release.ts now fail closed unless the same content (or its exact coordinated version-only child) has a green pair.
• Added durable ~/.config/gh/hosts.yml token fallback through resolveGithubToken; Actions installation tokens use the repository-scoped status request as their validation boundary.
• Independent opposite-family re-review: SLICE_REVIEW_PASS (session f0845c4d-4498-45e5-ba0f-74ab8f92ca19).

Evidence: full release suite 59/59, focused slice suite 81/81, touched TypeScript check/format clean, and all three touched workflows parse under @std/yaml.

[rickylabs]

Implementation — slice 5: mandatory canary-first doctrine

Commit: cce21549

• Extended the netscript-release skill source and regenerated its Claude mirror.
• Stable publication now explicitly requires the same-content green pair: canary publish + exact canary-pinned e2e-cli-prod.
• Documented <target>-canary.N, immutable/yanked-version policy, retained provenance tags, best-effort ephemeral-branch cleanup, and the prohibition on local/ad-hoc publishing.
• Kept PR fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810's scanner as the canonical owner and documented its exact sunset: deno publish rejects ("import attribute type of text is unsupported") even though it is runtime-stable and --dry-run accepts it denoland/deno#35546 fixed/merged/released in pinned Deno and an authenticated text-import canary green.
• Closed the stale OIDC-wiring debt without claiming that the first live canary has already run.
• agentic:sync-claude:check: PASS (17 skills / 21 mirrored files).
• Independent opposite-family review: SLICE_REVIEW_PASS (session 35ff9ca6-7f3a-4afc-832a-8556fd852dfd).

[rickylabs]

[PHASE: IMPL-EVAL] [VERDICT: PASS]

Separate direct OpenRouter/Qwen IMPL-EVAL completed against implementation/handoff head fbabeb6b; final head ddd4242e adds only the evaluator artifact and closing harness records.

• Evaluator session: a06700df-b15b-43e4-a35b-e9d0a97c2f06
• Artifact: .llm/runs/feat-811-release-canary--canary-readiness/evaluate.md
• Independent tests: 59/59 release + 63/63 agentic = 122/122 PASS
• Deliverables: all 8 release: canary publish channel — mandatory authenticated pre-publish gate with post-canary live production CI, + publish-readiness automation #811 rows PASS; no blocking findings
• Final local gates: touched TS check/lint/fmt PASS, three-workflow YAML and contracts PASS, skill sync PASS, changed-file quality 0 findings / 0 allowances, no new suppressions
• fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810: canonical release:preflight reused; exact deno publish rejects ("import attribute type of text is unsupported") even though it is runtime-stable and --dry-run accepts it denoland/deno#35546 + authenticated-canary sunset retained
• Evidence hygiene: the same evaluator independently corrected initial metadata transcription errors and reissued IMPL_EVAL_VERDICT: PASS

The PR remains draft and is now labeled status:impl-eval. It has not been merged.

OWNER actions remain as documented in the PR body: confirm workflow permissions and JSR grants/linkage, then run the first live canary publish + canary-pinned production E2E pair and yank failed/obsolete immutable canaries as needed.

[rickylabs]

[PHASE: IMPL-EVAL REPAIR] [STATUS: F1/F2 FIXED — RE-EVAL PENDING]

Supervisor FAIL_FIX findings repaired at merge commit 64184deb:

• merged current origin/main aa14e452 (including fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810 detector 8a8a9537); PR is now mergeable;
• resolved cut.ts by retaining shared prepareRelease() and moving main's gen:publish-assets step/output staging into that shared stable+canary helper;
• resolved release skill source/mirror with canary-first policy plus generated-assets, exact-version/min-age, same-semver recovery, and canonical fix(mcp): registry-safe README embedding — JSR rejects text-import attributes #810 preflight/sunset content;
• replaced the mocked import-attribute throw with a test that spawns the real preflight-text-imports.ts CLI against a seeded fixture.

Live merged-head proofs:

• seeded with { type: 'text' } → exit 1, import-attribute-preflight: FAIL, generated-constant remediation, deno publish rejects ("import attribute type of text is unsupported") even though it is runtime-stable and --dry-run accepts it denoland/deno#35546, and authenticated-canary sunset;
• seeded versionless jsr:@netscript/contracts → exit 1, versionless-specifiers: FAIL;
• seeded registry-absent package with nonstandard README → exit 1, first-publish: FAIL with H1/install/quick/docs findings;
• all seeds removed; clean publish:readiness → exit 0, all 8 rows PASS.

Repair gates:

• release tools: 61/61 PASS;
• release check/lint/fmt: 32 files, 0 findings (--unstable-kv on check);
• skill sync: 17 skills / 21 mirrors PASS;
• repair-file quality: 0 findings / 0 allowances;
• local/remote head: 64184deb20fd2ecd6572897505078dfaa08a7351.

Evidence: .llm/runs/feat-811-release-canary--canary-readiness/repair-evidence.md.

PR remains draft at status:impl-eval. This is implementation evidence only, not a self-evaluation; a fresh supervisor-triggered IMPL-EVAL is still required. No merge performed.