# Fairway Agent Operating Model Purpose: - Define how agents coordinate work in GPUaaS using Fairway. - Make Fairway the durable coordination record across Codex, Claude, Gemini, tmux, shell, and other provider sessions. - Prevent work from becoming invisible in provider chat history or ad hoc lane monitors. Required startup reading: - Every agent/session working on GPUaaS platform-foundation, Docusaurus, stabilization, UAT, ops, or production-readiness work must read this document before claiming or delegating work. - Orchestrator and provider sessions that create worktrees, delegate parallel work, merge lane commits, or push `master` must also read `doc/operations/Shared_Service_Lane_Worktree_Model_v1.md`. - Review-heavy or high-risk work must also read `doc/operations/Fairway_Review_Operating_Model.md` before closing, reviewing, merging, or promoting work. - `AGENTS.md` remains the general repository context. This document is the focused Fairway operating model. ## 0. Path Convention Durable operating docs and reusable prompts must not hardcode a specific operator laptop path. Use these variables in examples and prompts: ```bash export GPUAAS_REPO="${GPUAAS_REPO:-$(pwd)}" export FAIRWAY_REPO="${FAIRWAY_REPO:-../fairway}" export WORKTREE_PARENT="${WORKTREE_PARENT:-$(dirname "$GPUAAS_REPO")}" ``` `GPUAAS_REPO` is the active GPUaaS checkout or worktree. `FAIRWAY_REPO` is the local Fairway checkout used for CLI commands. `WORKTREE_PARENT` is the directory where sibling lane worktrees are created. Local `tmp-ux` memory files and Fairway evidence may retain absolute paths when they are historical execution records; promote them into durable docs only after rewriting paths with this convention. ## 1. Source Of Truth Active platform-foundation Fairway config: ```text $GPUAAS_REPO/.fairway/platform-foundation-config.toml ``` Active platform-foundation queue source: ```text $GPUAAS_REPO/.fairway/platform-foundation-implementation-track.yaml ``` Active Docusaurus portal config: ```text $GPUAAS_REPO/.fairway/docusaurus-config.toml ``` Legacy queue: ```text $GPUAAS_REPO/doc/governance/Agent_Work_Queue.yaml ``` `Agent_Work_Queue.yaml` is historical context only. Do not use it as the active queue. If legacy work is still valid, promote it into the active Fairway queue with current owner, parent, dependencies, source paths, target paths, review domains, risk, and acceptance checks. ## 2. Core Rule ```text Durable lane, replaceable provider attachment. ``` The Fairway task/lane is durable. Provider sessions are execution attachments. Codex, Claude, Gemini, tmux, shell, and browser sessions can all work on a lane, but task state, ownership, checkpoints, evidence, handoffs, reviews, and merge gates live in Fairway. Do not treat provider chat history as task authority. Do not mark work complete from a chat summary alone. Completion requires Fairway evidence and normal Fairway gates. Provider and utility event adapters are privileged local CLI inputs. They translate a trusted local operator or agent attachment into Fairway session, checkpoint, handoff, usage, and evidence records. They are not independent approval authority, review authority, release authority, or permission to add remote MCP/provider behavior. If an adapter records a `done` checkpoint, the task still needs the normal evidence, review, merge, and release gates for its risk level. For implementation parallelism, the durable lane should normally be the platform shared-service/code-ownership lane, not the provider thread and not a generic backend/frontend bucket. Use `doc/operations/Shared_Service_Lane_Worktree_Model_v1.md` to classify work into lanes such as `platform-iam`, `platform-ops`, `provider-runtime`, `app-runtime`, `billing-audit`, `frontend-portal`, `release-env`, and `security-compliance`. Normal post-PSSM flow: ```text shared-service lane worktree -> local lane commit -> Fairway evidence and reviews -> orchestrator merge/cherry-pick to master -> focused local gates on master -> master push and CI monitor ``` Remote task branches are exceptional. Record Fairway push-intent before pushing a specialist branch. The orchestrator owns integration and should push `master` as the normal remote validation path. For reviewed lane closeout, orchestrator ownership includes the full loop: review-thread steering, required Fairway reviews, missing profile-gate evidence, `merge-ready`, task status, merge to `master`, push to all configured remotes, deploy-run creation, CI monitoring with `scripts/ops/local_ci_monitor.sh`, deploy-run closeout, and final active reconciliation. Do not stop at Fairway handoffs or reviewer chat summaries. Use the reusable prompt in `doc/operations/Fairway_Orchestrator_Steering_Prompts.md` section `Reviewed Lane Closeout Instruction` whenever handing this work to the orchestrator. ## 2a. Parallel Tooling Work Is Not A Stop Signal Architecture or Fairway-product work in another thread is usually parallel tooling work, not an approval gate for GPUaaS stabilization. Do not wait on the architecture/Fairway thread only because it is updating Fairway docs, dashboard, provider adapters, release tooling, or coordination rules. Continue autonomously when the current GPUaaS task has clear acceptance criteria and can be tracked with the Fairway commands already available. Wait for the architecture/user thread only when one of these is true: - destructive, production-impacting, or credential-sensitive action needs explicit approval; - a required secret, token, certificate, or external credential is missing; - the environment is blocked and the task cannot make meaningful progress; - required review is pending and no non-conflicting ready task is available; - scope is ambiguous enough that a reasonable implementation choice would be risky; - a missing Fairway capability prevents correct task state, evidence, review, or session tracking. If none of those apply, proceed to the next ready non-conflicting GPUaaS task, record the provider session/checkpoints/evidence, and reconcile before ending. If a task is blocked, mark that exact task `blocked` with the reason and create a scoped follow-up. Do not leave the provider session idle waiting for general Fairway improvements. ## 2b. Use A Second Provider For Current External Behavior When a task stalls on current vendor, platform, or provider behavior, do not burn hours in one provider session. After one serious local evidence pass, consult a second current-info source such as Gemini, web search, vendor docs, or another agent with relevant context. Use this rule for issues such as Apple signing/notarization, Cloudflare, Pomerium, GitHub/GitLab runners, Homebrew policy changes, Kubernetes/kind, container registries, MAAS/LXD, OpenClaw, Keycloak, and provider-specific networking or deployment behavior. The second source is advisory, not authority. Bring the finding back into the repo by validating it locally or against the environment, then record it as Fairway evidence or a checkpoint with: - the original symptom and local evidence; - the external/current-info source consulted; - the confirmed interpretation or rejected hypothesis; - the next action, follow-up task, or unblock decision. If the second source identifies a real vendor/platform prerequisite, keep the implementation task blocked only when no safe local progress remains. Otherwise create a scoped ops/provider follow-up and continue the next ready task. ## 2c. Execution Surface Selection Use the execution surface that matches the work. ```text Desktop thread = control/review surface. CLI or tmux with bypass = trusted execution attachment. Fairway = durable coordination and audit state. ``` Codex Desktop threads are appropriate for architecture, review, steering, planning, screenshots, browser checks, cross-thread coordination, and operator-visible status checks. They may still route shell commands through an approval layer even when the thread appears to have full access. Do not depend on Desktop threads for unattended deploy, CI, UAT, or repeated Kubernetes validation loops. For trusted long-running ops work, prefer a CLI or tmux-backed provider attachment using Codex CLI with the explicit bypass mode: ```bash codex --dangerously-bypass-approvals-and-sandbox ``` Use this mode only when the task scope, target environment, and rollback or stop conditions are already explicit in Fairway. Good candidates: - CI monitoring and retry validation; - platform-control deploy validation; - Kubernetes rollout/status loops; - repeated smoke, UAT, and QA harness runs; - branch/worktree closeout; - Fairway reconciliation and utility monitor loops. Bypass mode removes interactive guardrails, so it increases the Fairway burden: 1. register the CLI/tmux session as the provider attachment; 2. record a `started` provider event or active checkpoint before editing; 3. keep checkpoints current during CI/deploy waits; 4. attach evidence for commands that decide task state; 5. end the provider session and reconcile before stopping. Do not use bypass mode for ambiguous scope, destructive cleanup, production mutation, secret handling, or live failure injection unless the Fairway task has explicit approval evidence, rollback criteria, and review domains. If a Desktop thread begins asking for repeated approvals during trusted ops execution, move the execution attachment to CLI/tmux instead of burning time approving each command. ### Sandbox-Limited Desktop Operations Codex Desktop shells can inherit the app's filesystem sandbox even when the process runs as the logged-in user. A Desktop thread may be able to read the repo and edit workspace files but still be unable to create files under `.git`. The usual symptom is: ```text fatal: Unable to create '.git/index.lock': Operation not permitted ``` Do not treat this as a stale Git lock until it is verified. If `.git/index.lock` does not exist and a normal Terminal/iTerm shell can commit, the issue is the Desktop execution surface, not the repository. Use a tmux or SSH session that was started outside the Codex Desktop sandbox as the controlled execution attachment for approved command boundaries: ```bash tmux new -d -s gpuaas-git tmux send-keys -t gpuaas-git 'cd /Users/subash/dev/GPUasService && git status --short --branch' C-m tmux capture-pane -pt gpuaas-git -S -200 ``` SSH to the same host is also acceptable when it creates a normal login session outside the Desktop sandbox. In both cases, the model is: ```text Fairway decides and records. Desktop coordinates and reviews. tmux/SSH executes only the approved command boundary. ``` Use named sessions for stable ownership. Recommended local names: | Session | Purpose | |---|---| | `gpuaas-git` | Commit-boundary staging/commit/readback only. | | `gpuaas-orchestrator` | Long-running orchestration, CI, deploy, or UAT watches. | | `gpuaas-ops-harness` | Ops harness execution and environment validation. | Any Desktop thread may drive a tmux/SSH lane only when the Fairway task already contains the command boundary or the thread has recorded it as a checkpoint. For commit-boundary work, the prompt or checkpoint must name the exact reviewed files to stage, the validation already run, and the intended commit message. Capture the tmux/SSH output back into the Desktop thread and record Fairway evidence with the resulting commit SHA, `merge-ready` readback, and active reconciliation result. Do not use a shared tmux/SSH lane for ambiguous scope, destructive cleanup, production mutation, secret handling, or live drill work unless the explicit Fairway approval and rollback evidence exists. ## 2d. Desktop Thread Steering And Response Checks Fairway handoffs and Desktop thread steering are different operations. Definitions: | Term | Meaning | |---|---| | Fairway handoff recorded | Durable Fairway task handoff/checkpoint exists. It is visible in Fairway, but no message has necessarily been sent to a provider thread. | | Thread steered | A prompt was actually sent to an existing Codex Desktop thread using a thread messaging tool. | | Thread checked | The target thread was read after steering and its latest status/response was summarized back into the coordinator or Fairway evidence. | Do not say "sent to the review thread" or "handoff added to the thread" unless the Desktop thread tool actually accepted a message for that thread. If only Fairway was updated, say "Fairway handoff recorded; manual/thread steering still required." When the Desktop app exposes thread tools, use this sequence: 1. Discover available thread tools before claiming capability. Search for `send_message_to_thread`, `read_thread`, and `list_threads`. 2. If needed, confirm the target thread with `list_threads` using the role, title, or thread id. 3. Send the exact steering prompt with `send_message_to_thread`. 4. Record a Fairway handoff/checkpoint or notification that includes the target thread id, role, task id, and summary of what was sent. 5. Later call `read_thread` on the same thread id to verify whether it is working, waiting, blocked, finished, or asking for input. 6. Copy the result back into Fairway as evidence, review, checkpoint, or handoff. Provider chat is not the durable record. When thread tools are not exposed in the current session: 1. Record the Fairway handoff/checkpoint normally. 2. Produce a clearly labeled manual relay block for the human operator: ```text Manual thread relay required target_thread: role: task: prompt: ``` 3. Do not claim the thread was steered. 4. Mark the task or coordinator checkpoint as waiting only when no alternate ready work exists. Otherwise continue non-conflicting ready work. Orchestrator owns review coordination until Fairway has a dedicated controller that can route and confirm provider notifications. The orchestrator should: - know the active review/control thread ids from its current memory file; - route review requests through Fairway and thread steering where tools allow; - use `read_thread` or manual operator feedback to collect reviewer verdicts; - record reviews with `fairway record review`; - rerun `fairway merge-ready ` after required reviews land; - push only after merge-ready and closeout gates pass. Reviewers should never be asked to approve from a vague chat summary. Steering prompts must include repo path, task id, commit or worktree path, changed files, validation already run, requested domains, and the exact verdict format: approve or changes requested with concrete blockers. ## 2e. Provider Goal Anchoring Long-running Codex sessions can lose the active thread after compaction, monitor handback, CI wait, review wait, or account/surface switching. Use a provider goal for work that spans more than one short burst. The coordination roles are distinct: | Layer | Authority | |---|---| | Fairway task | Durable work unit, task state, reviews, evidence, handoffs, and merge gates. | | `tmp-ux` memory file | Local provider-independent resume packet and current priority/order. | | Provider goal | Active Codex/session objective and completion criteria. | | Orchestrator prompt | Current steering instruction that points at the Fairway task and memory file. | Use a provider goal when any of these are true: - the task will cross CI, deploy, UAT, review, or approval waits; - the task may continue after context compaction; - the provider session is orchestrating parallel lanes; - the task depends on a local working-memory file; - the provider has previously stopped after one subtask and waited for another prompt. Goal text should be narrow and verifiable. It must include: - the active Fairway config path; - the current working-memory file path; - the exact task or batch scope; - stop conditions; - what evidence/reviews/CI/deploy state count as complete; - forbidden actions such as destructive cleanup, production mutation, or runner scaleout without approval. Example goal for a stabilization orchestrator: ```text Goal: Drive GPUaaS stabilization through the next CI-runtime optimization batch. Use Fairway as source of truth with config $GPUAAS_REPO/.fairway/platform-foundation-config.toml. Keep $GPUAAS_REPO/tmp-ux/gpuaas-stabilization-operating-model-2026-06-10.md updated. Do not start runner scaleout unless OPS-CI-RUNNER-ADMIN-METRICS-ACCESS-001 is unblocked with sanitized runner inventory and host headroom evidence. Create or update Fairway tasks for CI runtime optimization, coordinate parallel lanes, collect evidence, route reviews, merge through master, monitor CI, and stop only when active reconciliation is clean or a documented blocker requires user input. ``` A provider goal is not a Fairway status change. It does not approve reviews, claim ownership, or make work merge-ready. The provider must still register the session, record checkpoints, attach evidence, update the memory file, and run active reconciliation before stopping. ## 3. Agent Startup Checklist Before starting work: 1. Read `AGENTS.md`. 2. Read this document. 3. Read `doc/operations/Fairway_Review_Operating_Model.md` for high-risk, review-heavy, merge, release, or promotion work. 4. Identify the active Fairway config for the track. 5. Check the task tree and task detail. 6. Register or refresh the active provider session for the task. 7. Claim or set the task `in_progress`. 8. Immediately record a start checkpoint or provider event for the same task. 9. Confirm `fairway session status` shows the active session before editing. 10. Keep evidence paths, command output summaries, and handoffs attached to the Fairway task. The session update, task state update, and start checkpoint are one coordination transaction. Do not mark a task `in_progress` and then begin work without a matching active session/checkpoint. If an agent is working on the task, the wall must be able to show who is working on it. Exception for short direct coordinator work: a coordinator/orchestrator may temporarily leave a task as `in_progress` without an active session only when the work is expected to complete in one short burst, a fresh checkpoint explains the active owner and why no session is attached, and the task is closed, reset, blocked, or handed off before the burst ends. This exception is for quick coordination fixes only. Stabilization, UAT, production-readiness, delegated provider work, tmux/Claude/Codex external work, and anything expected to span multiple checkpoints must use a provider session plus a `started` provider event. Useful commands: ```bash cd "$FAIRWAY_REPO" go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ status-report go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ tree go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ task-detail ``` ## 3a. Local Transcript And Memory Retention Fairway is the durable coordination record. Provider transcripts, local working memory, context packets, and local LLM prompts are temporary support artifacts. They must never become an unreviewed second system of record. Allowed local storage: - `.fairway/transcripts/` may store provider-visible progress, final answers, command summaries, and sanitized excerpts that explain task state. - `tmp-ux/` and other local working-memory directories may store short-lived notes, scratch reports, screenshots, sanitized fixture output, and intermediate summaries needed to complete a task. - generated context packets and evidence packets may store task ids, owned paths, commands, acceptance criteria, review domains, deterministic results, sanitized findings, and links or paths to approved evidence. - local LLM prompts may store only deterministic sanitized packets generated by repository utilities or human-reviewed summaries derived from those packets. Prohibited local storage: - secrets, tokens, passwords, raw credentials, private keys, service-account material, session cookies, bearer headers, Stripe signing material, SSH keys, kubeconfigs, registry credentials, or certificate private material; - tenant names, customer names, tenant identifiers, user PII, billing/payment references, incident-sensitive details, or environment data that would expose another tenant or customer; - raw production logs, raw database exports, raw request/response bodies, raw webhook payloads, or raw provider transcripts that contain the preceding sensitive data; - private infrastructure URLs in broad prompts or packets unless the exact URL is required for an ops evidence artifact and does not contain credentials, tokens, customer identifiers, or tenant-sensitive path/query content. Retention and cleanup: - keep `.fairway/transcripts/` and `tmp-ux/` artifacts local-only and out of commits unless a specific sanitized artifact is intentionally promoted to reviewed evidence; - prune task transcripts, local memory notes, prompts, and packet drafts after task closeout, merge, or when they are no longer needed for active review; - treat 30 days after task closeout as the normal maximum local retention for non-evidence transcripts and scratch memory unless a reviewer explicitly asks to preserve a sanitized artifact; - immediately redact or delete any artifact found to contain prohibited content and record a security/governance follow-up if the source utility allowed it. Local LLM use: - optional local LLM summaries must consume deterministic sanitized packets, not raw logs, raw transcripts, secret catalogs, raw incident material, or direct environment dumps; - LLM output is advisory and may not decide task status, review approval, deploy readiness, branch deletion, release readiness, or policy exceptions; - if a useful summary needs sensitive detail, replace that detail with stable aliases such as `tenant-redacted`, `private-url-redacted`, `credential-redacted`, or `incident-detail-redacted`, and link only to the approved evidence location when access is appropriate. Required order when an agent starts or switches tasks: ```bash cd "$FAIRWAY_REPO" go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ session upsert \ --id \ --role \ --backend \ --provider \ --task-id \ --status running go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ --as \ claim go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ checkpoint record \ --state active \ --owner \ --summary "provider session started work" go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ session status ``` If the provider session is a Codex thread that is executing a task owned by another lane, keep the task role unchanged and register the provider session with the provider's role. Example: an orchestrator Codex thread may work on a `backend` task; the task remains backend-owned, while the active session records `role=orchestrator`, `backend=codex-thread`, and `task_id=`. After YAML edits, import the active queue: ```bash cd "$FAIRWAY_REPO" go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ import "$GPUAAS_REPO/.fairway/platform-foundation-implementation-track.yaml" ``` ## 4. Provider Session Events When delegating to or monitoring an external provider session, feed runtime state back into Fairway. Provider events are accepted only as local coordination inputs from the current Fairway operator context. Before using an adapter, verify the session id, task id, role, worktree, branch, and transcript/artifact path match the lane being updated. Do not use provider events to retarget an existing session to a different task, revive a terminal session, or convert a transcript/chat summary into pass evidence. Required event points: | Provider/session state | Fairway provider event | |---|---| | Session begins work | `started` | | Session is running normally | `running` or refreshed session metadata | | Waiting on approval | `waiting_on_approval` | | Waiting on user/input/dependency | `waiting_on_input` | | No progress or stale | `stale` or `no_progress` | | Failed or blocked by execution problem | `failed` | | Work completed | `completed` | Completion events should include evidence or a handoff path. Waiting, stale, and failed events should include the specific blocker and the next required action. Completion evidence must point to the command output, artifact, reviewed diff, CI/deploy/UAT result, or other durable proof that supports the state change. A transcript may be attached as context, but it is not sufficient completion evidence by itself. If the provider finished but the result still needs another owner to inspect, record a handoff instead of pass evidence. Provider-event checkpoints and session lifecycle are related but separate. After a provider finishes, verify that the Fairway session row is no longer `running`. If the adapter records completion evidence but leaves the session active, explicitly end or reconcile the session: ```bash go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ session end --status ended --reason "provider completed" ``` For tmux-backed sessions, also run `session reconcile --dry-run` when the pane or process is expected to have exited. Reconcile can only detect stale sessions when the session record still has PID or tmux pane metadata. ## 5. Provider Event Adapter Use the Fairway provider event adapter: ```text ../fairway/examples/session-adapters/provider-event.sh ``` For GPUaaS tracks with non-default config files, place a temporary Fairway wrapper earlier in `PATH` so the adapter writes to the correct Fairway DB: ```bash export GPUAAS_REPO="${GPUAAS_REPO:-$(pwd)}" export FAIRWAY_REPO="${FAIRWAY_REPO:-../fairway}" tmpdir=$(mktemp -d /tmp/gpuaas-fairway-adapter.XXXXXX) cat > "$tmpdir/fairway" <<'EOF' #!/usr/bin/env bash cd "$FAIRWAY_REPO" exec go run ./cmd/fairway --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" "$@" EOF chmod +x "$tmpdir/fairway" ``` Example provider event: ```bash PATH="$tmpdir:$PATH" ../fairway/examples/session-adapters/provider-event.sh \ --provider claude \ --backend tmux \ --external-session-id \ --role \ --task-id \ --state started \ --summary "delegated provider session started" \ --transcript .fairway/transcripts/.log ``` Then emit follow-up events for waiting, stale, failure, and completion: ```bash PATH="$tmpdir:$PATH" ../fairway/examples/session-adapters/provider-event.sh \ --provider claude \ --backend tmux \ --external-session-id \ --role \ --task-id \ --state completed \ --summary "completed implementation and attached evidence" \ --artifact .fairway/evidence/-verification.log \ --transcript .fairway/transcripts/.log ``` If completion needs review or continuation rather than evidence, use `--handoff-to ` and summarize the next action. Do not use the adapter to record approval; reviewers must still use `fairway record review`. Important: some provider CLIs buffer output. For example, `claude -p` can leave the transcript empty while the process is still running and then write the final answer at completion. Do not treat transcript byte growth as the only liveness signal. Use provider events, tmux/PID liveness, explicit heartbeats, and final session reconciliation together. ## 6. Lane Monitor Fallback Small lane-monitor scripts may be used as fallback detection for stale, idle, or waiting sessions. They do not replace Fairway provider events. If a monitor detects waiting, stale, no-progress, failure, or completion, record that state in Fairway using provider events or checkpoints. The monitor is only a detector. Fairway remains the durable coordination record. ## 7. Parallel Work Guidance Use parallel provider sessions only when the tasks have clear boundaries and can produce independent evidence. Good candidates for Claude/tmux or other external provider sessions: - ops readiness map; - UAT coverage matrix; - cert-manager lifecycle readiness; - GitOps decision packet; - database operations readiness; - Kubernetes runtime baseline; - user-safe error presentation test plan; - docs/source-of-truth classification. Good candidates for Codex verification: - queue reconciliation; - imports and Fairway runtime state checks; - commits; - CI/script execution; - code/test verification; - cross-track steering; - final evidence checks. ## 8. Commit Boundary Rule Commit work at meaningful task or review checkpoints. Do not use one large end-of-day commit as the normal process. Documentation-only work uses the same boundary: when a doc update is complete, reviewed or sanity-checked, and evidence/status is recorded when applicable, commit it as its own coherent slice. Default rule: ```text one coherent task outcome -> evidence -> review when required -> commit ``` Before committing a task slice: 1. Attach or update Fairway evidence for the task. 2. Decide the task state: `done`, `blocked`, `todo`, `needs_review`, or an explicit follow-up task. 3. Run `git diff --check`. 4. Run focused tests and relevant `bash -n` checks for changed scripts. 5. Complete required Fairway reviews for medium/high/critical work, or record a documented waiver. 6. Commit only the coherent, reviewed, merge-ready slice. If a work burst produces both completed fixes and blocked findings, commit the completed fixes/evidence and create or update separate Fairway tasks for the blocked findings. Do not hide partial work inside an unrelated commit. Large multi-task commits are reserved for explicit dirty-tree recovery or repository cleanup checkpoints, and the commit message or evidence must state that reason. Deploy, UAT, and release validation should run from a clean committed SHA whenever possible. ## 9. Deploy Run And Finding Taxonomy Use Fairway to make CI/CD/UAT operations measurable. For each meaningful release or deploy attempt, create one lightweight deploy-run task. Example: ```text DEPLOY-DEV-RUN-20260605-001 ``` The deploy-run task records: - source SHA or release branch; - target environment and profile; - CI result; - deploy or rollout result; - smoke/UAT result; - evidence paths; - final status and next action. Create child or follow-up tasks only for actionable findings: | Prefix | Use for | |---|---| | `CI-FIX-*` | Build, test, lint, generated contract, or CI runner failure. | | `CD-FIX-*` | Promotion, deploy script, image freshness, rollout, secret wiring, or cluster apply failure. | | `UAT-BUG-*` | Product/runtime behavior found by UAT. | | `OPS-FIX-*` | Environment, observability, credential, backup, network, or capacity issue. | | `HARNESS-FIX-*` | UAT/test harness false positive, false negative, flake, or sequencing issue. | | `DOC-FIX-*` | Docs or runbook mismatch found during operation. | Use tags or metadata when available: ```yaml kind: deploy-run | ci-fix | cd-fix | uat-bug | ops-fix | harness-fix | doc-fix environment: kind | dev | demo | staging | prod phase: preflight | ci | deploy | smoke | uat | rollback source_sha: detected_by: ci expected_gate: frontend_test severity: blocker | high | medium | low owner_domain: ops | backend | frontend | security | governance ``` Use `doc/operations/DevSecOps_Escape_Rate_Classifier_v1.md` as the canonical vocabulary for `detected_by` and `expected_gate`. Every actionable `CI-FIX-*`, `CD-FIX-*`, `UAT-BUG-*`, `OPS-FIX-*`, `HARNESS-FIX-*`, and `DOC-FIX-*` task should carry those classifier fields in metadata, evidence, or the attached summary artifact. Use `unknown` only as a temporary value and create or update a governance follow-up because escape-rate metrics cannot be trusted while either classifier is unknown. Pick the prefix from the owning remediation surface and the earliest expected gate before stopping at task creation. Creating a task or handing off review is not a stop condition when the fix is bounded, approved, credentialed, non-destructive, and not production-impacting. Stop only for missing approval, missing credentials, destructive or production-impacting action, unclear scope, required review changes, or failed validation that needs another owner. Do not encode tenant names, customer names, secrets, tokens, private URLs, or incident-sensitive details in classifier metadata. Store sensitive detail only in the approved evidence location with normal redaction. Do not bury defects inside deploy-run evidence. A deploy run should close as `done` when clean, `blocked` when an environment/deploy prerequisite prevents completion, or `done` with explicit follow-up tasks when deploy succeeded but findings remain. Do not create child tasks for one-off transient noise unless it recurs or changes operator action. ## 9a. Security Rule Selection Evidence GPUaaS rule-pack adoption is defined in `doc/operations/Fairway_Rule_Pack_Adoption_Plan_v1.md`. The adopted split is `fairway-run/fairway-rules-platform` for reusable Fairway/platform operating rules and `subashram/fairway-rules-gpuaas` for GPUaaS product/domain rules. This is advisory-first until deterministic local gates and reviewed Fairway core rule-source support exist. High-risk or critical tasks that touch authn/session, authz/tenant boundaries, secrets/PKI, runtime execution, Kubernetes/edge/IaC, supply chain, data protection/logging, or MCP/tooling automation must record `security-rule-selection` evidence before review. Use `doc/operations/Fairway_Security_Rule_Selection_Evidence_v1.md` as the canonical schema. The evidence must identify selected external rule families, affected source paths, applicability rationale, non-applicable rationale, required review domains, the reviewer domain that prepared or accepted the selection, residual risk, and follow-up tasks when needed. This evidence is review input only. It does not approve the task, waive findings, satisfy release gates by itself, replace security scans or supply-chain evidence, or authorize remote CodeGuard MCP/provider tooling. GPUaaS contract, tenant-isolation, privacy, policy, audit, and production-readiness rules remain authoritative when they are stricter. ## 10. CI And Deploy Wait Windows Treat CI, deploy, smoke, and UAT waits as part of the operating model. A 15-20 minute pipeline is long enough for useful parallel work, but also long enough to create stale Fairway state and unrelated dirty-tree changes if the handoff is not explicit. For reusable steering text to send to orchestrator or track sessions, use `doc/operations/Fairway_Orchestrator_Steering_Prompts.md`. Before moving attention away from a running pipeline or deploy, record a checkpoint or deploy-run update with: - pipeline or deploy URL when available; - source SHA or release branch; - target environment; - expected completion window as an absolute time or `+N minutes`; - what decision depends on the result; - the next safe action while waiting. The orchestrator starts the integration loop and records the deploy-run state. Long-running CI/CD monitoring may be handed to an Ops/DevOps provider session when the run is not the direct blocker for the orchestrator's current assigned milestone. The handoff must name the deploy-run task, source SHA, pipeline or deploy URL, target environment, expected window, safe rerun command, stop conditions, and forbidden actions. The receiving Ops/DevOps session owns first-pass classification and creates or updates the scoped follow-up task before handing code/product work back to the owning lane. Use wait windows for bounded, non-conflicting work: - prepare review notes for the same task; - clean up evidence and classify logs; - update runbooks or docs directly related to the run; - triage the next ready task without editing the same deploy path; - consult a second provider/current-info source for external platform behavior; - create follow-up task shells for clear findings. Do not use a pending pipeline as permission to keep editing the same worktree in a way that invalidates the SHA under test. If meaningful parallel work is needed, start a separate Fairway task and provider session, and use a separate worktree when code edits could collide. If the run exceeds the expected completion window by more than half the original estimate, record a `stale`, `awaiting_input`, or equivalent checkpoint before continuing. Silent waits should be visible on the wall. When the pipeline or deploy completes: 1. update the deploy-run or checkpoint with pass, fail, partial, or blocked; 2. create or update `CI-FIX-*`, `CD-FIX-*`, `UAT-BUG-*`, `OPS-FIX-*`, `HARNESS-FIX-*`, or `DOC-FIX-*` tasks for actionable findings; 3. close, reset, or block the waiting Fairway task explicitly; 4. reconcile active sessions before ending the work block. Architecture Control should not be the default CI/CD monitor. It arbitrates only milestone blockers, repeated process gaps, ambiguous ownership, production/destructive risk, or security-sensitive failures. Normal pipeline duration, failed-job trace collection, flake triage, deploy monitor tooling, and release verification improvements belong in Ops/DevOps optimization tasks. The purpose is to keep momentum without hiding defects or accumulating one large uncommitted batch. Commit completed slices at task or review boundaries before using them for deploy, smoke, UAT, or release validation. ## 11. Stabilization Phase Rule During the post-PSSM stabilization phase: 1. Do not start new product feature work unless it directly fixes a stabilization blocker. 2. Finish pre-UAT readiness gates before another broad UAT run. 3. Classify remaining work as launch blocker, confidence hardening, future scale hardening, or deferred non-goal. 4. Keep UAT, stress, ops readiness, and production evidence visible in Fairway. 5. Any exception to start feature work must record owner, reason, blast radius, expiry, and stabilization impact. Primary stabilization anchors: - `PSSM-STABILIZATION-FIRST-EXIT-GATE-001`; - `PSSM-UAT-READINESS-GATES`; - `PROD-STRESS-READINESS-HARNESS`; - `OPS-PROD-READINESS-BACKLOG`. ## 12. Do Not Bypass Fairway Gates The provider event adapter must not bypass: - task status rules; - evidence requirements; - review approval; - handoff requirements; - merge readiness; - release/profile gates. Use normal Fairway commands for those actions. ## 13. Handoff Expectations Every delegated or parallel session should leave one of: - evidence artifact; - handoff note; - blocked reason with next action; - review request; - completed provider event with evidence path. The handoff should include: - task ID; - files changed or inspected; - commands run; - validation result; - remaining risk; - next recommended action.