# ChatGPT Web operations architecture

audience: AI coding agents first.

## Outcome

Make ChatGPT Web sole reasoning agent for Overdeck project work, delivery, local deployment, k3s operations, and recovery. Local/workstation/cluster components MUST remain deterministic execution services. No local AI agent participates. System MUST remain usable when Claude and Codex quotas are exhausted.

status: SUPERSEDED — R0 incremental delivery replaces all-or-nothing execution; see `docs/plans/2026-08-14-chatgpt-operations-incremental-delivery.md`.
task IDs: #2 umbrella; #45 incremental redesign; R0 blockers #40/#41/#43/#44; deferred #3/#4/#5/#6
source request: Owner supplied “ChatGPT Web Operations Architecture” after review rejected unrestricted bearer-to-shell package. Build purpose-specific services behind Cloudflare Access and an Actions Gateway. Preserve complete end-to-end ChatGPT capability without permanent unrestricted workstation shell, arbitrary SSH, broad secrets, or Kubernetes cluster-admin. Owner correction: create specs, plans, task/subtask decomposition, and `/claudex-workflow` now; use `gpt-5.6-terra/high` coders and `gpt-5.6-sol/low` reviewers; MUST NOT launch implementation until owner explicitly says to start.

## Acceptance criteria

ChatGPT Web can independently:

1. Discover registered project, workspace, task, audit, deployment, and cluster state.
2. Claim an isolated workspace.
3. Read, search, compare-and-swap write, patch, build, and test registered projects through isolated k3s Jobs.
4. Inspect retained logs, status, diffs, hashes, tests, artifacts, and current workspace state.
5. Commit, push task branch, request guarded landing, and poll landing status through dedicated operations.
6. Deploy landed Overdeck `main` locally by commit hash through fixed canonical deployment workflow; verify installed result; roll back only to recorded known-good revision.
7. Inspect and perform routine typed k3s maintenance without exposing arbitrary `kubectl` or cluster-admin.
8. Recover supported incidents through registered deterministic procedures.
9. Use temporary exceptional authority only through externally activated, scoped, expiring, revocable, audited break-glass grants.
10. Complete every operation without local AI or Claude/Codex quota.
11. Ensure stolen routine Action credential cannot grant unrestricted workstation shell, arbitrary SSH, broad secrets, or Kubernetes cluster-admin.

## Preserved WIP

- Rejected package and review remain unchanged at `/home/user/Projects/overdeck/temp-user/overdeck-actions-layer/`.
- Review receipt: `docs/plans/2026-08-13-review-gpt-actions-operator.md` in `wt/review-gpt-actions-layer`.
- Current architecture planning worktree: `/home/user/Projects/overdeck/.worktrees/review-gpt-actions-layer`.
- Shared checkout WIP remains untouched.

## Constraints

### Core authority boundary

- NEVER expose one permanent bearer token spanning workstation shell, SSH, Kubernetes administration, secrets, and deployment.
- Authenticate at Cloudflare Access AND application layer.
- Require verified owner identity, rotation, revocation, replay protection, request IDs, idempotency keys, strict request size, and rate limits.
- Never expose SSH, Kubernetes API, repository filesystems, controller, collector, or workstation services directly.
- Keep Actions Gateway deterministic: authenticate, validate, route, audit, rate-limit, and return status. No model. No planning.

### Project execution

- Accept registered project, source revision, claimed workspace/worktree, supported workflow or constrained project command, explicit resources, network policy, and expected artifacts.
- Run non-root; NEVER privileged; NEVER host PID/IPC/network; NEVER host filesystem mounts.
- Use read-only base image, bounded writable workspace, seccomp, dropped capabilities, dedicated service account, namespace isolation, restricted outbound network, CPU/memory/storage/process/concurrency/runtime/output bounds, and cleanup after receipt preservation.
- Isolate persistent project volumes by project.
- Raw execution, if unavoidable, MUST remain inside project containers with no host, deployment, cluster-admin, SSH, or secret authority.

### Workspace and Git

- Maintain registered project/repository registry. NEVER accept arbitrary roots or remotes.
- Provide typed list/create-or-claim/read/search/write/patch/status/diff/test/commit/push/landing/rollback operations.
- Require compare-and-swap hashes for file mutation.
- Protect shared main, deploy copies, `.git`, ignored files, credentials/environment files, escaping symlinks, and unregistered repositories/remotes.
- Scope Git credentials to exact repository and operation; general jobs receive no reusable broad credential.

### Cluster service

- Keep coding-job identity separate from cluster identity.
- Expose typed registered-resource operations only: inspect health/resources/logs/usage; restart/rollback/scale approved workload; apply registered release; rollout status; cordon/uncordon/drain registered node; registered recovery; storage/network inspection; retention cleanup.
- NEVER accept arbitrary `kubectl` or arbitrary manifests.
- Use narrow namespace/resource/verb RBAC.
- Require external, exact, short-lived, single-use approval for deletion, persistent-volume changes, node drain, upgrades, secret changes, security policy, privileged workloads, host mounts, or cluster-wide RBAC. GPT cannot create approval.

### Local Overdeck deployment

- `deployOverdeckLocal` accepts landed commit hash only.
- Verify trusted remote existence, membership in landed `main`, required delivery evidence, clean controlled deploy copy, and no unrelated modifications.
- Invoke canonical fixed path/arguments/environment only.
- Capture bounded logs; verify services and live endpoints; record deployed and previous known-good revisions; return receipts.
- Roll back only to recorded known-good revision.
- NEVER accept arbitrary command, script, path, environment, or service name.

### Secrets

- Service needing secret owns it. General jobs and raw execution NEVER receive deployment, Cloudflare, SSH, Kubernetes, or workstation credentials.
- Inject only for exact operation; keep unavailable through logs/files; prefer short-lived; scope by repository/namespace/target/operation; rotate/revoke; omit from responses/audits.

### Break glass

- Activate outside GPT conversation with owner authentication.
- Scope to workstation, cluster, or named nodes; short expiry; single-use/session-bound; explicit allowed scope; secrets excluded unless explicitly granted; command/result audit; resource/output bounds; immediate revocation; automatic expiry; final receipt.
- Prefer constrained isolated administrative shell.
- Repeated stable break-glass need MUST become typed operation.

### Audit and observability

- Append-only independent retention.
- Record caller identity, time, operation, target, request/operation IDs, approval, command/manifest hash, before/after state, limits, exit, duration, truncation/timeout, changed files/hashes, deployment/rollback revision.
- Return progress, logs, diffs, tests, rollout, and deployment without host paths or secrets.

## API contract

### Context

- `getOperatorContext`
- `listProjects`
- `listWorkspaces`
- `getTask`
- `getAuditReceipt`

### Project work

- `createWorktree`
- `readFile`
- `searchFiles`
- `writeFile`
- `patchFile`
- `startProjectJob`
- `getProjectJob`
- `getDiff`
- `commitChanges`

### Delivery

- `pushTaskBranch`
- `requestGuardedLanding`
- `getLandingStatus`
- `deployOverdeckLocal`
- `getLocalDeployment`
- `rollbackOverdeckLocal`

### Cluster

- `getClusterHealth`
- `listClusterResources`
- `getWorkloadLogs`
- `restartWorkload`
- `rollbackWorkload`
- `scaleWorkload`
- `applyRegisteredRelease`
- `cordonNode`
- `uncordonNode`
- `drainNode`
- `runRegisteredRecovery`
- `getClusterOperation`

### Exceptional authority

- `useBreakGlassGrant`
- `getBreakGlassStatus`

DO NOT add routine general `exec`.

## Authority matrix

| Capability | Routine project job | Cluster service | Workstation deploy service | Break glass |
|---|---:|---:|---:|---:|
| Edit project worktree | Yes | No | No | Scoped |
| Build and test | Yes | No | No | Scoped |
| Commit and task-branch push | Scoped | No | No | Scoped |
| Land through guarded flow | Dedicated operation | No | No | Scoped |
| Inspect cluster | No | Yes | No | Yes |
| Routine cluster recovery | No | Typed operations | No | Yes |
| Cluster-admin | No | No | No | Temporary only |
| Deploy Overdeck locally | No | No | Fixed operation | Temporary broader repair |
| Arbitrary workstation shell | No | No | No | Temporary only |
| Read secrets | No | No | No | Explicit exceptional scope only |

## Execution steps

### Phase 1 — Safe project execution

1. Map current Overdeck gateway, project registry, Factory/k3s Job, workspace, audit, identity, and observability seams.
2. Specify and implement edge-identity validation plus application authentication, replay/idempotency/rate/request-size enforcement.
3. Implement registered-project/workspace APIs and isolated k3s project jobs with full resource/network/security bounds.
4. Implement file/status/diff/test/commit/task-push operations and append-only receipts.
5. Prove cross-project isolation, secret absence, resource enforcement, replay rejection, idempotency, and live ChatGPT Action compatibility.

### Phase 2 — Guarded delivery

1. Implement guarded landing request/status adapter using established Overdeck delivery process.
2. Implement deterministic workstation deployment by landed commit hash.
3. Implement installed-state proof and known-good rollback.
4. Prove no arbitrary path/command/environment/service input reaches workstation deployment.

### Phase 3 — Cluster operations

1. Implement read-only cluster visibility with narrow RBAC.
2. Add typed registered-resource restart, rollback, scaling, release, node, cleanup, and recovery operations.
3. Add external high-impact approval verifier.
4. Prove coding jobs hold no cluster credentials and GPT cannot manufacture approval.

### Phase 4 — Exceptional recovery

1. Implement externally activated break-glass grant store and verifier.
2. Implement constrained temporary administrative execution with automatic expiry/revocation and complete audit.
3. Prove secret exclusion, scope, single-use/session binding, resource bounds, and final receipt.
4. Promote repeated stable emergency operations into typed APIs.

## Current receipt

- Task #2 umbrella is now IDLE; documentation tasks #7–#11 completed. Implementation tasks #3–#6 remain pending and unclaimed.
- Owner architecture captured as authoritative replacement for rejected unrestricted operator.
- Five decomposed specs written and self-reviewed: trust plane, project execution, guarded delivery, cluster operations, break glass.
- Five indexed implementation plans written; each is IDLE.
- Paused workflow authored at `.claude/workflows/chatgpt-web-operations.js` with 11 disjoint task file sets across five dependency waves.
- Workflow model contract: `gpt-5.6-terra/high` coder; `gpt-5.6-sol/low` reviewer; coder fix plus reviewer recheck on blockers.
- Workflow static check: 11 tasks, zero cross-task file overlap, no launch performed.
- No implementation started; no worker/process executing.
- Existing package MUST NOT be incrementally patched into this design; authority model changes are architectural.

## Next executable action

Wait for owner start instruction. Then invoke `/claudex-workflow` with `.claude/workflows/chatgpt-web-operations.js`; verify resolved agent model metadata before allowing Wave 1 to continue.