From f36ea3754865f46e4a7338ebc5a3bb3a75d5df4a Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 19 May 2026 03:47:19 +0000 Subject: [PATCH] docs: define v1 stabilization dev lane policy --- docs/reference/ci.md | 2 ++ docs/reference/dev-environment.md | 2 ++ docs/reference/release-governance.md | 24 ++++++++++++++++++++++++ 3 files changed, 28 insertions(+) diff --git a/docs/reference/ci.md b/docs/reference/ci.md index a8df829b..d5161bcc 100644 --- a/docs/reference/ci.md +++ b/docs/reference/ci.md @@ -39,6 +39,8 @@ The CLI may be run from `master` if it remains backward compatible with the pinn CI/CD services should report their source commit, API/schema capability, supported environments and supported operations. CI diagnostics should include that information when rejecting an operation as unsupported. +During a `release/v1` stabilization window, CI should continue using the implemented dev desired-state contract rather than adding split-lane infrastructure. The `origin/master:deploy.json#environments.dev` service pins may point at v1 stabilization commits for validation, but CI must print the manifest commit and service commits it used. Explicit `dev-v1` and `dev-master` support is a later infrastructure change after v1 is stable. + Steps that call the Kubernetes API directly clear inherited proxy variables so service-account HTTPS calls to `kubernetes.default.svc` do not accidentally use the Code Queue image's Docker Compose proxy defaults. The rollout poll reads the Deployment main resource rather than the `/status` subresource, keeping CI RBAC limited to the same app/service resources it creates and deletes. The performance probe scans recent Code Queue tasks until it finds one with trace steps, so a newly selected task without persisted step detail does not make the whole gate fail before measuring the trace endpoints. diff --git a/docs/reference/dev-environment.md b/docs/reference/dev-environment.md index 1036f52f..2b6e3c80 100644 --- a/docs/reference/dev-environment.md +++ b/docs/reference/dev-environment.md @@ -34,6 +34,8 @@ The unrestricted public network entries are therefore production frontend, dev f The target release-governance model is to split stable maintenance validation from high-risk master integration, for example with explicit lanes such as `dev-v1` and `dev-master`. That split is not active until `deploy.json`, deploy commands, CI, frontend labels and diagnostics support it explicitly. Until then, the documented `environments.dev` behavior remains the active contract and must not be emulated through local manifest edits or hidden branch conventions. +During a `release/v1` stabilization window, this same implemented `environments.dev` lane is temporarily reserved for v1 validation. Use pushed commits and explicit `deploy.json` pins to validate v1 fixes; do not add a parallel `dev-v1`/`dev-master` schema in the middle of the stabilization window unless that split is the blocker for v1. The detailed phase rule lives in `docs/reference/release-governance.md`. + The persistent dev rollout currently supports only: - `backend-core` diff --git a/docs/reference/release-governance.md b/docs/reference/release-governance.md index 4f59afc7..b61a8712 100644 --- a/docs/reference/release-governance.md +++ b/docs/reference/release-governance.md @@ -40,6 +40,28 @@ UniDesk enters stabilization mode when core availability is threatened by contro Exit from stabilization requires CI/CD, deploy verification, Code Queue recoverability and dev/prod isolation to be demonstrably healthy. +## V1 Stabilization Window + +When `release/v1` is being stabilized, the current dev environment should be temporarily treated as the v1 validation lane. Do not add `dev-v1` and `dev-master` manifest lanes during the same window unless the absence of split lanes is the blocker for a v1 fix. + +The temporary rule is: + +- pause high-risk `master` feature and architecture work that would compete for dev, CI, Code Queue or deploy capacity; +- keep `origin/master:deploy.json#environments.dev` as the implemented command contract, but pin the relevant service commits to v1 stabilization commits when validating v1 fixes; +- document any temporary v1 pin in the related issue before relying on it; +- do not introduce dirty local manifests, hidden deploy refs, or implicit branch-based behavior; +- do not change `deploy.json` schema only to express the future split-lane target. + +The v1 stabilization task should move through these phases: + +1. Establish the v1 baseline from the last TypeScript backend-core commit and record which post-baseline fixes are candidates for backport. +2. Backport user-visible and operability fixes that preserve the existing architecture, especially Code Queue prompt/trace visibility, `/api/workdirs`, gateway diagnostics, and CI image-build stability. +3. Make the current dev lane validate v1 by pinning `environments.dev` service commits to the v1 fix set and running the existing dev/CI checks. +4. Promote only the verified v1 commits to production desired state through the normal commit-pinned deploy path. +5. After v1 is stable, implement explicit `dev-v1` and `dev-master` lanes or an equivalent schema, with CLI, CI, frontend labels, diagnostics and documentation updated together. + +Code Queue can implement bounded v1 bug fixes, tests and documentation patches when the task can run in an isolated worktree and does not require production mutation. Manual control is required for branch creation, v1 baseline selection, `deploy.json` pin changes, production deploys, recovery actions on active tasks, and any decision to resume high-risk master work. + ## CI/CD Runtime Versioning CI/CD server and control-plane services are production-like infrastructure. Their runtime version must be pinned by `deploy.json` to the production desired commit, not implicitly follow the operator's local worktree or the latest `master`. @@ -59,6 +81,8 @@ The target model is to separate a stable maintenance dev lane from a master inte This split must be implemented explicitly in `deploy.json`, deploy planning, deploy apply, CI, frontend labels and diagnostics. Until that work is done, existing commands continue to read the currently documented manifest ref such as `origin/master:deploy.json#environments.dev`; operators must not simulate split lanes through dirty local manifests, hidden branches, or undocumented runtime edits. +During a v1 stabilization window, the future split-lane implementation is deliberately deferred. The current `environments.dev` lane is reserved for v1 validation until the v1 release criteria are met, then the explicit split-lane work can proceed as a separate infrastructure change. + ## Feature Flags Feature flags are short-lived risk controls, not a long-term architecture partitioning mechanism. Prefer release lines, service boundaries and deployment boundaries for durable divergence.