# Fairway Review Operating Model Purpose: - Make code, architecture, security, ops, frontend, and governance review expectations explicit for Fairway-tracked work. - Prevent high-risk tasks from being closed only because implementation evidence exists. - Use track sessions with context as review attachments, while keeping Fairway as the durable record. ## Poiesis Lineage This operating model descends from the earlier Poiesis workflow prototype: context-driven agents, contract-first planning, reviewer/QA/red-team feedback loops, and human approval for important decisions. What changed in GPUaaS/Fairway is operational maturity. Poiesis expressed the theory; Fairway applies it to live provider sessions, dirty worktrees, tmux and Codex/Claude attachments, queue state, dashboard visibility, evidence artifacts, UAT/deploy loops, and stale-work reconciliation. Carry forward these Poiesis principles: - Specialization comes from context, contracts, and task metadata rather than hardcoded provider identity. - High-risk work needs reviewer, QA, and red-team style scrutiny before human approval. - Automation can iterate and surface findings, but Fairway evidence and human release judgment remain authoritative. - Low-risk work should not pay the cost of a heavy review loop. ## Review Authority Fairway task metadata defines the expected review domains: ```yaml review_domains: - governance - ops - backend risk_level: high ``` The task owner produces implementation evidence. Review domains provide independent approval or requested changes. Provider chat summaries are not review evidence unless the review is recorded in Fairway. Provider-event and utility-event adapter records are implementation or coordination inputs, not reviewer decisions. A `done` checkpoint or `pass` evidence row created by an adapter can support review, but it does not approve the task, waive a declared review domain, authorize release/promotion, or prove that the emitting provider was allowed to change task authority. Reviewers should treat adapter-produced records like any other local CLI evidence: verify the task id, session/worktree binding, artifact path, command/result claim, and required review domains before approving. ## Domain Triggers Use these defaults when creating or reviewing tasks. | Domain | Required when work touches | |---|---| | `architecture` | architecture docs, ownership boundaries, IAM/billing hierarchy, PSSM model, policy inheritance, domain route ownership, target operating models | | `security` | auth, IAM, MFA, Pomerium/proxy authz, API keys, service accounts, secrets, PKI, audit/logging, network edge, terminal access, data exposure, compliance/security gaps | | `ops` | deploy, UAT, runbooks, readiness gates, CI/CD, GitOps, backup/restore, observability/on-call, environment parity, Kubernetes/runtime posture | | `backend` | Go services, API handlers, workers, schema access, runtime controllers, SDK/server contracts, backend tests | | `frontend` | web UI, browser UAT, Docusaurus portal UX/content structure, dashboard-facing product flows | | `governance` | Fairway queue changes, evidence rules, task lifecycle, release gates, process docs, boundary guards | ## Risk-Based Review Default posture for GPUaaS stabilization is lightweight, risk-scaled review. Full-matrix review is an escalation for boundary decisions, not the normal shape for every task. This is the first-class operating model until Architecture Control explicitly changes it after evidence that a heavier process improves speed, quality, or safety. | Risk | Minimum review | |---|---| | `low` | Owner self-check plus durable evidence is acceptable unless a domain trigger says otherwise. | | `medium` | At least one independent reviewer from a primary `review_domains` entry. | | `high` | At least two review domains, normally the owner-adjacent domain plus the highest-risk cross-cutting domain. | | `critical` / launch | `architecture`, `security`, and `ops` are required, plus `backend` or `frontend` when code/UI changed. | High-risk stabilization and production-readiness tasks should not rely on `review: not_required` as the final word. Until Fairway enforces this automatically, the coordinator should route review manually before merge or release promotion. ## Risk-Scaled Review Inheritance Fairway reviews are a risk-control tool, not a ceremony. Do not require the full critical review matrix for every child task when the child task only narrows, documents, or validates an already-approved blocked posture. That pattern increases token spend and cycle time without reducing risk. Any proposed process increase must name the expected benefit before it becomes the default. Use this test: ```text Will this review or gate improve speed, quality, or safety enough to justify its coordination cost? ``` If the answer is uncertain, pilot it on a bounded slice and measure whether it reduced rework, caught defects, improved rollback safety, or shortened cycle time. If it does not, remove or narrow the process and invest in preflight, tests, UAT flow coverage, or tool automation. Apply the automate-after-repetition rule to deterministic review and coordination work: - first occurrence: handle it manually and learn the real workflow; - second occurrence: capture the checklist, command, packet shape, or query; - third occurrence: automate it or create a scoped automation task. Common automation candidates include Fairway state summaries, review-wait and merge-ready checks, commit-boundary handling, preflight packet generation, UAT coverage diffs, CI/deploy monitor handbacks, evidence redaction/validation, and delivery/token/process overhead reporting. Automation is not a substitute for review at real boundary exits such as live/source-prod mutation, credentials, public exposure, sensitive-operation enforcement, deploy/release, or external claims. For pre-user, pre-production stabilization, review cost must be justified by expected defect discovery or risk reduction. A reviewer should be able to state what defect class the review is likely to catch that the evidence, preflight, tests, or UAT coverage would not catch. If that answer is weak, use a lighter review profile and invest the saved effort in reproducible preflight, tests, flow coverage, or tool automation. ## Security Control Maturity Ramp Security-sensitive product work should not automatically inherit the full CISO control-attestation model during early development. GPUaaS currently optimizes for secure, fast feature delivery: ```text feature works -> tests/preflight/UAT -> release gate -> external/control claim ``` Use the lightweight engineering model while the work is still pre-user, pre-production, and not making external claims: - implementation owned by the feature lane; - focused tests, non-live preflights, and UAT evidence; - one accountable reviewer or grouped review where useful; - explicit non-claims for incomplete controls. Escalate to the formal CISO/control model only when the task crosses one of these boundaries: - production cutover or source/prod mutation; - public exposure or release promotion; - credential reset/submission, break-glass, or privileged recovery; - sensitive-operation enforcement; - compliance, customer, auditor, or board-facing claim; - regulated evidence retention/custody requirement. If someone proposes full-matrix review, custody evidence, exact windows, multi-approver packets, or compliance mapping before those boundaries, the request must state the concrete risk being reduced. If the best answer is "because the control document says so", keep the lighter model and improve preflight, tests, UAT coverage, or automation instead. Use this default shape unless the task declares stricter gates: | Work unit | Minimum review | Full matrix required when | |---|---|---| | Micro slice | One independent accountable reviewer from the primary affected domain, plus durable evidence. | The slice changes runtime behavior, broadens authority, mutates an environment, touches secrets/credentials, or weakens a safety gate. | | Grouped cleanup or grouped harness/docs slice | One accountable reviewer for each primary affected domain, with one batch artifact covering all included task ids. | The group crosses unrelated ownership boundaries or includes a live/prod-impacting action. | | Epic, launch, deploy, live window, production-readiness claim, or external compliance claim | Full required domain matrix from task metadata and risk triggers. | Always. | Review inheritance is allowed only when the child task is explicitly within an already-reviewed parent or packet and does not expand authority. The review record must name the parent, the inherited decision, the residual risk, and the reason the narrower review is enough. Review inheritance is not allowed for: - live MFA/drill/window authorization; - source/prod mutation; - credential reset, credential submission, token/API matrices, or break-glass; - public exposure or deploy/push/merge approval; - sensitive-operation gate implementation; - a change that turns a deferred, blocked, or report-only posture into an enforcing posture. For those cases, use the full matrix at the exact approval boundary. For small child fixes that keep the same blocked posture, prefer a single accountable review or grouped review packet and reserve the full matrix for the epic or release closeout. ## Safe Preflight Iteration Zone When a task has an approved non-live or disposable boundary, that boundary is the engineering workspace. Inside it, agents should be able to iterate on setup, readback, classifier, harness, and provider-shape fixes with lightweight evidence and one accountable review, as long as all of these remain true: - no source/prod mutation; - no live-window execution; - no public exposure change; - no break-glass action; - no credential reset or credential submission outside the approved disposable packet; - no token/API sensitive-operation matrix; - no sensitive-operation enforcement; - rollback/cleanup remains scoped to the disposable target; - redaction and artifact rules are preserved. Full review is required when leaving that safe boundary, not for every internal iteration inside it. Boundary exits include live-window authorization, deploy or release promotion, source/prod mutation, public exposure, credential or break-glass action, sensitive-operation enforcement, production-readiness claims, and external compliance/customer claims. ## Step-Back Trigger Fairway coordination should detect when a lane is looping. Repeated approved child slices are not progress if the end-to-end flow keeps failing for new reasons. When a task produces two or three meaningful failures after being treated as nearly ready, the coordinator should recommend a causal reset instead of another review packet. The reset packet should include: - failure chain and artifact links; - repeated layer or assumption being corrected; - unknown provider/product/harness/environment behavior; - proof required before the next retry; - whether current review policy is adding assurance or just coordination cost; - a lighter review plan for safe-boundary discovery. The purpose is not to weaken safety. It is to prevent review/process loops from hiding the real engineering question. ## Security Rule Selection Review For high-risk or critical work touching security-sensitive surfaces, reviewers must expect `security-rule-selection` evidence before final approval. The canonical schema is `doc/operations/Fairway_Security_Rule_Selection_Evidence_v1.md`. The evidence should show selected 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 any follow-up tasks. It is a routing and review input, not an approval, waiver, or release authorization. Use these default routing triggers unless the task declares stricter review domains: | Trigger | Tags | Review domains | |---|---|---| | Authn/session | `surface:authn`, `surface:session`, `surface:iam` | `security`, `backend`, `architecture`; add `frontend` for browser/session UX | | Authz/tenant boundary | `surface:authz`, `surface:tenant-boundary`, `surface:admin-api` | `security`, `architecture`, `backend`; add `governance` for policy/process changes | | Secrets/PKI | `surface:secrets`, `surface:pki`, `surface:credentials` | `security`, `ops`, `architecture`; add `backend` when service code changes | | Runtime execution | `surface:runtime`, `surface:node-agent`, `surface:terminal`, `surface:app-runtime` | `security`, `backend`, `ops`, `architecture` | | Kubernetes/edge/IaC | `surface:kubernetes`, `surface:edge`, `surface:iac`, `surface:runner` | `ops`, `security`, `architecture`; add `backend` for controller/service coupling | | Supply chain/dependencies | `surface:supply-chain`, `surface:dependencies`, `surface:ci-cd`, `surface:registry` | `security`, `ops`, `governance`; add `backend` or `frontend` for package/runtime owners | | Data protection/logging | `surface:data-protection`, `surface:logging`, `surface:audit`, `surface:storage` | `security`, `governance`, `backend`; add `ops` for observability/export paths | | MCP/tooling/automation | `surface:mcp`, `surface:local-automation`, `surface:agent-security` | `security`, `ops`, `architecture`, `governance` | If the evidence is missing, partial, or inconsistent with the changed paths, request changes or require a scoped follow-up before approval. If the selection identifies a deterministic product, security, CI, deploy, UAT, harness, ops, or documentation finding, ensure the follow-up task includes `detected_by` and `expected_gate` classifiers from `doc/operations/DevSecOps_Escape_Rate_Classifier_v1.md`. For local automation and provider-event changes, review must include the trust boundary: the adapter may reject impossible lifecycle transitions and obvious session/task mismatches, but Fairway review remains the authority for approval. Do not accept transcript-only completion evidence for adapter-driven closeout; require a durable artifact, a concrete command result, or an explicit handoff. ## Stabilization Defaults Apply these defaults unless a task states a stricter rule: | Work type | Review domains | |---|---| | UAT harness/readiness | `governance`, `ops`, `backend` | | Kind/dev provider fixtures | `ops`, `backend`, `governance` | | Proxmox/bootstrap/node-agent | `ops`, `backend`, `security` | | Production stress | `ops`, `backend`, `governance`; add `security` for auth, proxy, terminal, or data exposure | | Secrets/PKI/MFA/proxy | `security`, `ops`, `architecture`, `backend` | | GitOps/Kubernetes baseline | `ops`, `governance`, `security`, `architecture` | | Security architecture docs | `architecture`, `security`, `ops`, `governance` | | MFA or approval-gated browser journey live window | `product-quality` or `integration`, `architecture`, `security`, `ops`; add `backend` or `frontend` when service/session claims or browser UX changed | ## Flow-Contract Review For Approval-Gated Journeys For MFA drills and comparable approval-gated browser journeys, exact-window review packets must include a Product Quality / Integration flow-contract review input. Reviewers should not approve only because the latest local delta is safe. The packet must show why the configured provider state should produce the expected browser outcome. Minimum review input: - realm/profile, client, redirect/callback route, browser-flow tree, and provider version; - users, groups, roles, required actions, break-glass, and service/non-human exclusions; - expected browser state sequence for each persona; - helper classifiers and handling for unknown, blocked, and negative states; - non-live/disposable proof or an explicit waiver with owner, expiry, residual risk, and Fairway task; - rollback/delete, source-realm readback, redaction, and closeout evidence paths. Use `doc/operations/MFA_Flow_Contract_Product_Quality_Review_Model_v1.md` for the MFA-specific review checklist. If this input is missing, record `changes` even when ops, security, backend, or harness-local checks are individually correct. ## Track Sessions With Context Use dedicated track sessions for review-heavy work: - architecture review session, - security review session, - ops review session, - backend review session, - frontend review session, - governance/release review session. The durable identity remains the Fairway task. The track session is a provider attachment with reviewer context. Required reviewer session behavior: 1. Read `AGENTS.md`, this document, and `doc/operations/Fairway_Agent_Operating_Model.md`. 2. Register the reviewer provider session against the task being reviewed. 3. Record a checkpoint with review scope, changed files, and evidence being reviewed. 4. Record the review in Fairway with verdict `approve` or `changes`. 5. If changes are requested, include concrete file/behavior findings and the next owner. 6. End or retarget the provider session after the review burst. For changes touching CI scripts, release gates, generated artifacts, YAML/JSON, promotion wiring, or API/SDK contracts, reviewer evidence must include the exact verification command and artifact path reviewed. Generated SDK/client artifacts require `CODEGEN_ENFORCE_CLEAN=1 bash scripts/ci/sdk_codegen_smoke.sh` evidence when `doc/api/**` or codegen behavior changes, including description-only OpenAPI edits. ## Current Manual Workflow Until Fairway has risk-based review enforcement: ```bash cd "$FAIRWAY_REPO" go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ task-detail go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ route review go run ./cmd/fairway \ --config "$GPUAAS_REPO/.fairway/platform-foundation-config.toml" \ record review --reviewer --verdict approve --reason "" ``` For high-risk work, repeat `record review` for each required domain. Do not merge or promote release candidates until required reviews are present or a documented waiver exists. ## Review-To-Commit Workflow Reviews should produce a clean, committed task slice, not only chat approval. Documentation review is included in this rule; approved docs should be committed promptly instead of remaining as ambient worktree changes. Required flow: 1. Task owner implements the slice and attaches Fairway evidence. 2. Task owner runs focused verification and records command results. 3. Required reviewers inspect changed files, behavior, evidence, and risk. 4. Reviewers record `approve` or `changes` in Fairway. 5. Owner fixes review findings and reruns focused verification. 6. Owner commits the reviewed, merge-ready slice. 7. Deploy, UAT, or release validation proceeds from the committed SHA. If a task is partially complete, commit only the completed reviewed portion and create or update Fairway follow-up tasks for the blocked remainder. Do not carry many unrelated reviewed tasks uncommitted in the same worktree. Large multi-task commits are acceptable only as explicit dirty-tree recovery or repository cleanup checkpoints. ## Fairway Product Gap Fairway should eventually derive review requirements from `review_domains` and `risk_level`, apply configurable risk-based review policy, and block done transitions when required reviews are absent. Current Fairway task detail and merge-ready checks expose missing approved domains from declared `review_domains`; risk-based derivation remains follow-up product work.