Release Lane Change Boundary

Alignment briefing for a standard way to keep canary experiments and general-release edits from mixing across skill source, conventions, package metadata, task docs, and promotion work.

alignment_statusreview
date2026-07-06
categoryqa-meta
recommended COArelease-lane contract plus audit gate

Problem

Recent planning crossed two different release lanes: a normal `master` interrogation upgrade and a canary-only review-surface experiment. The failure mode is not specific to interrogation pages. Any future source change can accidentally import canary conventions, artifacts, branch assumptions, package metadata, or task handoff language into general-release work unless the task states its lane and a verification gate enforces that boundary.

Risk: If canary and general-release edits share task language without lane metadata, agents can promote experimental behavior by editing canonical `packs/**/SKILL.md`, package exports, or convention registries on `master`.

Boundary Principles

Declare the lane first.

Every non-trivial task should state whether it is `general`, `canary`, `promotion`, `hotfix`, or `research/prototype` before implementation starts.

Separate lanes, not source truth.

Keep canonical skill source under `packs/**` unless a promotion task deliberately changes it. Canary can use branches or overlays.

Promotion is a distinct lane.

A canary result becomes general-release behavior only through an explicit promotion task with target behavior, source evidence, and verification.

Audit disallowed surfaces.

General tasks should fail if they add canary-only conventions, paths, or metadata outside a promotion lane.

Courses Of Action

COADescriptionProsRisksFit
A. Task metadata only Add `Release lane`, `Allowed surfaces`, and `Disallowed surfaces` blocks to active tasks. Fast, visible, easy to apply across all work. Soft control. Depends on agents reading and honoring it. Useful baseline, not sufficient alone.
B. Lane contract plus audit Create a shared release-lane convention and add an audit that checks active task lane, branch, and touched disallowed surfaces. Standardized, mechanical, applies beyond interrogation upgrades, low source churn. Needs a small parser and a maintained convention registry for lane-sensitive surfaces. Recommended default.
C. Canary overlay directory Keep canonical skills in `packs/**`, but store experiment patches or overlay files under `canary-overlays/<experiment>/`. Clear experiment boundary without duplicating full skill trees. Requires overlay tooling and promotion rules if experiments become common. Useful for long-running experiments.
D. Separate canary/general source trees Duplicate skill source into separate canary and general directories. Very visible separation. High drift, duplicated archives/changelogs, unclear package ownership, hard promotion path. Do not use by default.

Do We Need Separate Directories?

No, not as the default source-of-truth model. A full split between canary and general skill directories solves visibility by creating a worse maintenance problem: duplicated mirror files, duplicated archives and changelogs, package staging ambiguity, and manual promotion diffing.

Preferred boundary: one canonical skill tree, explicit release-lane metadata, branch policy, disallowed-surface audit, and optional canary overlays for long-lived experiments.

Separate directories are only justified if a canary experiment needs long-lived divergent definitions that cannot be represented as a branch, generated staging area, or overlay patch. Even then, the directory should be an overlay, not a second canonical skill source.

Recommendation

Adopt COA B as the repo standard, with COA C available for larger experiments:

  1. Create `docs/release-lane-convention.md` defining `general`, `canary`, `promotion`, `hotfix`, and `research/prototype` lanes.
  2. Add a required `### Release Lane` block to active tasks in `tasks/todo.md` and future roadmap backlog items.
  3. Add `scripts/audit-release-lane.mjs` and call it from `scripts/audit-task-docs.mjs` or the standard verification list.
  4. Represent canary-specific behavior through canary branches and, when needed, `canary-overlays/<experiment>/` patch directories.
  5. Require promotion tasks to name the canary source, target general behavior, accepted files, and verification gates.

Implementation Shape

Task Block

### Release Lane

- Lane: general
- Branch: master
- Allowed surfaces: [packs, scripts, tests, docs, exports]
- Disallowed surfaces: [canary-only conventions, canary publish metadata, experimental review surfaces]
- Promotion source: none

Canary Block

### Release Lane

- Lane: canary
- Branch: canary/<experiment>
- Allowed surfaces: [canary branch, canary overlays, canary package metadata]
- General release impact: none until promotion
- Promotion path: explicit promotion task required

Promotion Block

### Release Lane

- Lane: promotion
- Branch: master
- Promotion source: canary/<experiment> @ <commit>
- Target behavior: <specific behavior to graduate>
- Rejected canary behavior: <behavior that stays out>

Approval Gates

Gate 1 - Standardize Release Lane Metadata

Should future non-trivial tasks require a `### Release Lane` block before implementation?

Gate 2 - Add Mechanical Audit Enforcement

Should the repo add a release-lane audit that fails disallowed surface changes for the active lane?

Gate 3 - Directory Split Policy

Should the repo avoid separate full canary/general skill source directories by default?

Compile Responses

Use this YAML to continue with an implementation task after reviewing the briefing.