# Shared Service Lane Worktree Model v1 Status: current operating model for post-PSSM stabilization Owner: Architecture / Orchestrator / Platform Operations ## Purpose GPUaaS work should run in parallel along code ownership boundaries, not along provider thread names or generic backend/frontend labels. The platform shared services model only helps if independent service areas can make progress in separate worktrees and then merge back through a controlled `master` lane. This document defines the lane model to use after the current cleanup is reconciled. ## Core Rules ```text Shared-service lane owns implementation. Orchestrator owns integration. master is the only normal remote integration branch. Remote task branches are exceptional and require Fairway push-intent. ``` Use local worktrees for parallel implementation. Specialist lanes may commit locally and attach Fairway evidence, but they should not push remote branches unless the task records explicit Fairway push-intent. The orchestrator is the merge lane: 1. creates or assigns lane worktrees; 2. verifies lane evidence and required reviews; 3. merges or cherry-picks reviewed lane commits into `master`; 4. runs focused local gates on `master`; 5. pushes `master`; 6. monitors CI using deterministic utilities; 7. records deploy-run/CI evidence and closes Fairway state. ## Lanes | Lane | Primary Code Boundary | Typical Work | Required Review Bias | |---|---|---|---| | `platform-iam` | `packages/platform/iam`, identity endpoints, Keycloak/Pomerium docs and config | MFA, RBAC, service accounts, auth context, session posture | security, architecture, backend, ops when live IdP changes | | `platform-ops` | `packages/platform/statusops`, evidence, observability, `scripts/ops`, runbooks | status, evidence, public/admin diagnostic surfaces, utility layer, runbook automation | ops, governance, backend | | `provider-runtime` | `cmd/node-agent`, provisioning worker, MAAS/LXD/provider packages | node lifecycle, bootstrap, self-update, recovery, task signing, worker liveness | ops, backend, architecture | | `app-runtime` | `packages/products/appplatform`, app catalog/runtime routes, managed ingress | app launch, workload state, app connect, OpenClaw/Jupyter/vLLM, route readiness | backend, ops, frontend when UX changes | | `billing-audit` | platform billing, usage, ledger, audit packages and contracts | billing attribution, usage records, immutable ledger, audit evidence | backend, governance, security | | `frontend-portal` | `packages/web`, Docusaurus/docs portal | v3 UX, account/security UX, operator pages, docs portal | frontend, architecture, security when auth-sensitive | | `release-env` | `scripts/ci`, `infra/k8s`, deploy/runbook/env automation | CI/CD, kind/dev/staging deploy, artifact freshness, environment profiles | ops, governance, backend | | `security-compliance` | security docs/gates, scan/waiver scripts, threat model, tenant isolation docs/tests | security review, waivers, scan gates, abuse cases, tenant isolation | security, architecture, governance | Fairway tasks should declare source paths, target paths, review domains, and tags that make the owning lane obvious. If the owning lane is ambiguous, the orchestrator should classify it before dispatch. ## Worktree Naming Use predictable worktree names so cleanup and closeout utilities can reason about lane ownership. `WORKTREE_PARENT` is the directory that contains the main GPUaaS checkout and sibling lane worktrees. ```text $WORKTREE_PARENT/gpuas-platform-iam- $WORKTREE_PARENT/gpuas-platform-ops- $WORKTREE_PARENT/gpuas-provider-runtime- $WORKTREE_PARENT/gpuas-app-runtime- $WORKTREE_PARENT/gpuas-billing-audit- $WORKTREE_PARENT/gpuas-frontend-portal- $WORKTREE_PARENT/gpuas-release-env- $WORKTREE_PARENT/gpuas-security-compliance- ``` Use one worktree per lane batch. Do not use one new worktree per tiny fix when the fixes are part of the same coherent lane batch. ## Parallelism Rules Parallel work is allowed when lane target paths do not materially overlap. Good parallel batches: - `platform-iam` MFA decision review while `provider-runtime` validates node-agent self-update. - `platform-ops` functional escape review while `app-runtime` fixes OpenClaw route mismatch. - `release-env` CI monitor utility fix while `frontend-portal` updates docs. Serialize or batch when: - two lanes touch the same package, route file, schema, contract, or deploy script; - one lane's acceptance depends on another lane's unmerged commit; - both lanes need to push `master` in the same CI window; - the live environment would be mutated in conflicting ways. If two lanes repeatedly need the same files, treat that as an architecture signal. Create a boundary cleanup task instead of normalizing cross-lane edits. ## Merge And Push Flow Specialist lane: ```text claim Fairway task register provider session implement in lane worktree run focused gates attach evidence commit locally request review / handoff to orchestrator ``` Orchestrator: ```text inspect lane worktree verify Fairway evidence and reviews merge/cherry-pick to master run local gate selector and focused gates record deploy-run if pushing push master only monitor CI with local utility close or reset Fairway tasks clean lane worktree after closeout ``` When the orchestrator runs from Codex Desktop, `.git` writes may be blocked by the app sandbox even though normal workspace edits work. If staging or commit fails with `.git/index.lock: Operation not permitted`, use the controlled tmux/SSH execution lane described in `doc/operations/Fairway_Agent_Operating_Model.md`. The Fairway task or checkpoint must still name the exact reviewed files, validation evidence, and commit message before any tmux/SSH command is sent, and the captured output, commit SHA, `merge-ready`, and reconciliation readback must be recorded after. Normal remote push policy: | Push target | Default | Requirement | |---|---|---| | `master` | allowed by orchestrator after local gates | Fairway task evidence, coherent batch, CI monitor | | task branch | not normal | Fairway `push-intent` with reason and closeout path | | release branch | promotion only | platform-control release policy | | provider/specialist remote branch | exceptional | explicit review/integration/backup push-intent | ## Review Rules Review domains come from lane, risk, and touched files. Minimum review bias: - `platform-iam`: security + backend; architecture for policy or provider-flow decisions; ops for live IdP or Pomerium changes. - `platform-ops`: ops + governance; backend when read models or APIs change. - `provider-runtime`: ops + backend; architecture for lifecycle or trust boundary changes. - `app-runtime`: backend + ops; frontend when product UX changes; governance for SDK/developer contract changes. - `billing-audit`: backend + governance; security for audit/tenant boundary. - `frontend-portal`: frontend + architecture; security for auth/MFA/account surfaces. - `release-env`: ops + governance; backend when deployment behavior changes service wiring. - `security-compliance`: security + architecture + governance. Do not self-approve the same implementation identity. If the reviewer belongs to the same broad role but is independent, record the reviewer identity and the review domain separately. ## Current Stabilization Mapping After the active orchestrator batch is reconciled, use this mapping: | Current Work | Lane | |---|---| | `PSSM-KIND-UAT-OCI-STATUS-RUNTIME-APPROVAL-001` and node-agent follow-ups | `provider-runtime` | | OpenClaw/Jupyter/app workload sequencing blockers | `app-runtime` | | `OPS-FUNCTIONAL-ESCAPE-REVIEW-20260609-001` | `platform-ops` | | API-first ad hoc ops sweep and diagnostics scripts | `platform-ops` with backend review | | MFA browser-flow decision and live-drill unblock plan | `platform-iam` / `security-compliance` | | runner, cert-manager, Cloudflare evidence/export tasks | `release-env` / `platform-ops` | ## Closeout Requirements Before a lane is considered closed: 1. Fairway task is `done`, `blocked`, or explicitly reset with reason. 2. Evidence includes local gate command, result, artifact path, and source SHA. 3. Required reviews or waivers are recorded. 4. Lane commit is merged to `master` or preserved with push-intent. 5. `master` CI/deploy-run evidence is recorded when pushed. 6. `fairway reconcile active --dry-run` is clean or the remaining finding is intentionally assigned to a follow-up task. 7. Lane worktree is clean or deliberately preserved with owner and task id. ## Anti-Patterns - Spinning a new remote branch for every thread. - Pushing every specialist branch to CI before orchestrator merge. - Treating generic backend/frontend as the durable lane when the real boundary is platform IAM, provider runtime, app runtime, or release environment. - Continuing direct DB/kubectl diagnostics without creating an API-first read-model or utility follow-up. - Allowing CI to be the first proof of behavior that can be checked with a focused local or kind functional probe. - Leaving `in_progress` tasks without active provider session or status decision after evidence has been recorded.