# Agent Production Deployment Requirements

## Status entering deployment

```yaml
code_development: COMPLETED
repository_commit: NOT_CREATED
production_deployment: NOT_STARTED
reason_repository_commit_missing:
  current ChatGPT GitOps runtime has AIOS_GITOPS_WRITES_ENABLED=false
```

The code bundle is an input artifact. The Agent must place it on a non-main
integration branch, review it, run acceptance tests, merge it through protected
main and deploy the API adapter. The Agent must not regenerate or materially
rewrite the supplied implementation without recording the new diff and tests.

## Frozen production state

Before any change, verify:

```yaml
main_oid: 875d41c3101093149414292067fd700dc214d4d3

V2R1C5:
  tag_oid: 9e65bd59baea392294c0f253046d3ab116f63145
  peeled_target_oid: aa60e891547abd7e215af7cf2bf3f21fd23541da
  baseline_version: V2R1C5
  baseline_status: PRODUCTION_DEPLOYED
  target_oid: aa60e891547abd7e215af7cf2bf3f21fd23541da
  evidence_closure_oid: 5e2cf8276f5093f3352b9a3252c701a44c5ab807
```

If authoritative `main` no longer equals the approved base OID, stop with
`MANUAL_OWNER_REVIEW_REQUIRED / AUTHORIZED_BASE_OID_DRIFT`. Do not silently
rebase the bundle onto a different base.

## Bootstrap sequence — no additional Owner interaction

Use the following order so that the approved V2R1C6 base OID remains valid and
the bridge does not create its own authorization deadlock:

1. Verify the supplied archive/patch SHA-256.
2. Install the bundle into a temporary root-owned staging directory outside the
   Git worktrees.
3. Start a localhost-only temporary instance of
   `aios_authorized_task_writer_api.py` on a dedicated port or Unix socket.
4. Bind it to the existing authenticated Owner registry and the exact
   `writer:provision` scope. Do not expose it through the public gateway.
5. Execute the live V2R1C6 provisioning request while `main` still equals
   `875d41c3101093149414292067fd700dc214d4d3`.
6. Verify `READY_FOR_CODE_AUTHORING`, the exact branch OID, writer scope and
   negative policy tests.
7. Use the newly created scoped writer to commit this reviewed bundle onto:
   `agent/v2r1c6-mainline-reconciliation-20260805`.
8. Stop and remove the temporary bootstrap service and revoke its temporary
   runtime credential. Preserve its signed grant receipt and audit logs.
9. Open a protected PR from the V2R1C6 branch. Deploy the permanent bridge only
   from the reviewed merge commit.

The temporary service is a control-plane bootstrap, not a production release.
It must retain:

```yaml
listen_scope: localhost_only
production_change_authorized: false
tag_change_authorized: false
baseline_change_authorized: false
main_write_authorized: false
```

This order avoids asking the Owner to approve a second base OID merely because
the bridge implementation itself advanced `main`.

### Alternative platform-maintenance path

If policy prohibits a temporary localhost bootstrap service, use an existing
Owner-approved platform-maintenance executor to create:

```yaml
branch: patch/owner-authorization-writer-bridge-20260806
base_ref: refs/heads/main
base_oid: 875d41c3101093149414292067fd700dc214d4d3
direct_main_push: false
force_push: false
tag_write: false
baseline_write: false
production_deploy_during_integration: false
```

Merging that branch before V2R1C6 provisioning changes the authoritative base
OID. In that alternative only, a new exact Owner base-OID amendment is required.
The Agent must never substitute the newer `main` OID automatically.

## Files to install on the branch

Copy with the same relative paths:

```text
active-runtime/app/authorized_task_writer_provisioning.py
active-runtime/app/aios_authorized_task_writer_api.py
docs/gitops/authorized-task-writer-provisioning.md
docs/gitops/openapi-authorized-task-writer-fragment.yaml
deploy/systemd/aios-gitops-model-api-authorized-writer-bridge.conf.example
scripts/smoke_authorized_task_writer_provisioning.py
tests/test_authorized_task_writer_provisioning.py
```

Merge the OpenAPI fragment into:

```text
docs/gitops/openapi-chatgpt-actions.yaml
```

The final schema must expose:

```yaml
operationId: provisionAuthorizedTaskWriter
path: POST /api/task-writer/provision-authorized
x-openai-isConsequential: true
```

Do not deploy the fragment as a second standalone OpenAPI document.

## Required review of existing API integration

The adapter expects the existing API handler to provide:

```python
handler.need(scope)
handler.body()
handler.sendj(value, status=200)
api.H.do_POST
api.main()
```

Confirm these contracts against the branch before merge. If the live API has a
different authentication object shape, make the smallest adapter-only change
and rerun every test. The core provisioning policy must remain unchanged.

The API authorization registry must grant `writer:provision` only to the
authenticated Owner role. Agents and ordinary writer tokens must not receive
this scope.

## Privilege boundary

The API service must remain non-root.

Install a root-owned sudoers rule that allows the API service identity to run
only these exact commands with `sudo -n --`:

```text
/usr/local/libexec/aios-grant-signer-adapter
/usr/local/libexec/aios-grant-validator
/usr/local/libexec/aios-task-writer-provisioner
```

Do not allow:

```text
/bin/sh
/bin/bash
/usr/bin/env
/usr/bin/git
wildcard executable paths
SETENV
arbitrary environment preservation
```

The governed tools themselves must validate their `--grant-dir` and
`--result-json` paths. Their binaries must be root-owned, non-symlink, regular,
executable and not group/world writable.

The signer must access its private signing material only through a runtime
secret reference. No signing key or token may enter Git, API output, the
provisioning receipt or systemd environment text.

## Runtime paths and permissions

Create:

```text
/var/lib/aios-gitops/authorized-writer-bridge
/var/lib/aios-gitops/authorized-writer-bridge/receipts
/var/lib/aios-gitops/authorized-writer-bridge/locks
```

Required properties:

```yaml
owner: API service identity
mode: "0700"
symlink: false
persistent: true
```

The directory contains redacted receipts only. Temporary signed grant
directories are deleted after success or failure.

## Required staging environment

Configure the API service:

```text
AIOS_GITOPS_REPOSITORY_IDENTITY=aios/aios
AIOS_GITOPS_AUTHORITY_GIT_DIR=/data/aios-gitops/repo.git
AIOS_GITOPS_AUTHORIZED_WRITER_STATE_ROOT=/var/lib/aios-gitops/authorized-writer-bridge
AIOS_GITOPS_GRANT_SIGNER_ADAPTER=/usr/local/libexec/aios-grant-signer-adapter
AIOS_GITOPS_GRANT_VALIDATOR=/usr/local/libexec/aios-grant-validator
AIOS_GITOPS_TASK_WRITER_PROVISIONER=/usr/local/libexec/aios-task-writer-provisioner
AIOS_GITOPS_OWNER_PROVISION_SCOPE=writer:provision
AIOS_GITOPS_GOVERNED_USE_SUDO=true
AIOS_GITOPS_SUDO_PATH=/usr/bin/sudo
```

Use `aios_authorized_task_writer_api.py` as the API entrypoint. It delegates
all pre-existing routes and adds only the new endpoint.

## Pre-merge tests

Run from the repository root:

```bash
python3 -m unittest -v tests/test_authorized_task_writer_provisioning.py
python3 scripts/smoke_authorized_task_writer_provisioning.py
python3 -m py_compile \
  active-runtime/app/authorized_task_writer_provisioning.py \
  active-runtime/app/aios_authorized_task_writer_api.py
```

Required result:

```yaml
unit_tests:
  total: 9
  failures: 0
  errors: 0
smoke: PASS
py_compile: PASS
```

Also run all existing GitOps API and isolated writer tests affected by:

```text
aios_chatgpt_actions_api
aios_isolated_writer_api
isolated_writer_authz
isolated_writer_token_registry
single_owner_governance
OpenAPI schema validation
```

Any regression blocks merge.

## Staging API acceptance

### Negative authentication

An Agent or non-Owner credential calling the endpoint must receive:

```yaml
http_status: 403
error: OWNER_AUTHORIZATION_REQUIRED
```

### Negative scope tests

Requests enabling any of the following must be denied before signer execution:

```text
production_change_authorized=true
tag_change_authorized=true
baseline_change_authorized=true
main_write_authorized=true
allowed_operations containing tag/main/baseline/admin operations
missing required denied operation
one_time_use=false
expiry over 1800 seconds
```

### Drift and conflict tests

Verify:

```yaml
wrong_base_oid:
  http_status: 409
  error: AUTHORIZED_BASE_OID_DRIFT

existing_unreceipted_target_branch:
  http_status: 409
  error: EXISTING_BRANCH_OID_CONFLICT
```

### Governed tool failures

Independently inject and verify fail-closed behavior for:

```text
signer unavailable
signer signature absent
validator signature_valid=false
validator signer_trusted=false
validator plan expired
provisioner grant_consumed=false
provisioner writer scope enables main/tag/baseline/force push
any required negative policy test false
```

None may create or modify a Git ref.

## Live V2R1C6 provisioning request

After protected merge and API deployment, authenticate as the Owner and submit
exactly:

```json
{
  "task_id": "V2R1C6_TASK_SCOPED_WRITER_PROVISIONING",
  "repository": "aios/aios",
  "base_ref": "refs/heads/main",
  "base_oid": "875d41c3101093149414292067fd700dc214d4d3",
  "target_branch": "agent/v2r1c6-mainline-reconciliation-20260805",
  "owner_authorization_reference": "chat-owner-authorization:v2r1c6:20260806",
  "one_time_use": true,
  "expires_in_seconds": 900,
  "production_change_authorized": false,
  "tag_change_authorized": false,
  "baseline_change_authorized": false,
  "main_write_authorized": false,
  "allowed_operations": [
    "create_worktree",
    "create_target_branch_if_absent",
    "commit_to_target_branch",
    "push_target_branch"
  ],
  "denied_operations": [
    "direct_main_push",
    "force_push",
    "tag_create",
    "tag_update",
    "tag_delete",
    "branch_delete",
    "repository_admin",
    "baseline_write",
    "production_deploy",
    "production_marker_write",
    "history_rewrite"
  ]
}
```

This request must be executed by the localhost-only bootstrap instance before
the bridge code advances `main`. The endpoint must never infer “current main”.

If the Agent chooses the alternative merge-first path, it must stop after the
merge and obtain an exact Owner amendment for the new merge OID. It must not
silently replace the approved OID.

## Success response

Require:

```yaml
status: READY_FOR_CODE_AUTHORING
grant_consumed: true
branch: agent/v2r1c6-mainline-reconciliation-20260805
branch_oid: <exact amended authorized base OID>
base_oid: <same exact OID>
main_unchanged: true

writer_scope:
  workspace_role: task-scoped-isolated-writer
  writes_enabled: true
  allowed_branch: agent/v2r1c6-mainline-reconciliation-20260805
  allowed_base_oid: <exact amended authorized base OID>
  allowed_routes:
    - POST /api/commit-file
  allow_main_write: false
  allow_tag_write: false
  allow_baseline_write: false
  allow_force_push: false
```

All seven negative policy results must be true.

Submit the identical request a second time. It must return the same grant and
branch attestation with:

```yaml
idempotent: true
```

It must not run the provisioner again.

## Production postchecks

After API deployment and writer provisioning, independently verify:

```yaml
existing_routes_regression: PASS
new_endpoint: PASS
main_ref: expected reviewed merge commit
V2R1C5_tag_oid: 9e65bd59baea392294c0f253046d3ab116f63145
V2R1C5_peeled_target: aa60e891547abd7e215af7cf2bf3f21fd23541da
V2R1C5_baseline_unchanged: true
new_release_tag_created: false
production_baseline_changed: false
```

The deployment of this control-plane bridge does not authorize a V2R1C6
production release. It only enables scoped code authoring.

## Rollback

If the new API route fails:

1. Stop accepting new provisioning calls.
2. Restore the previous API entrypoint.
3. Restart and verify all existing routes.
4. Preserve receipts and logs.
5. Revoke any task writer capability already minted.
6. Do not delete a branch or rewrite a tag.
7. Revert the protected-main bridge commit through an ordinary reviewed revert
   PR if source rollback is required.

## Required final Agent report

```yaml
STATUS: COMPLETED | PARTIALLY_COMPLETED | BLOCKED | FAILED

INTEGRATION:
  branch:
  commit:
  protected_pr:
  merge_commit:
  files_changed:

TESTS:
  unit:
  smoke:
  py_compile:
  regression:
  fault_injection:

DEPLOYMENT:
  service:
  entrypoint:
  runtime_status:
  endpoint_status:
  rollback_verified:

PROVISIONING:
  owner_authorization_reference:
  approval_plan_id:
  grant_id:
  grant_digest_sha256:
  signing_key_identity:
  branch:
  branch_oid:
  workspace_path:
  grant_consumed:
  idempotent_replay:

CONSISTENCY:
  main_oid:
  V2R1C5_tag_oid:
  V2R1C5_peeled_target_oid:
  baseline_version:
  baseline_changed:
  tags_changed:

SECRETS:
  runtime_secret_reference_used:
  plaintext_secret_logged:
  plaintext_secret_committed:

BLOCKERS:

GOVERNANCE:
  force_push_used: false
  tag_rewritten: false
  direct_main_push: false
  secrets_committed: false
  owner_approval_respected: true
```