aios/docs/gitops/repository-discovery-p0-runbook.md

Repository Discovery P0 Runbook

This runbook covers the read-only repository discovery surface and the governed workflow used to publish a change to it. It does not authorize a production deployment, a protected-ref update, a tag operation, or a runtime mode change.

Safety invariants

Before any operation, record the repository identity and the exact authority OID. The only repository identity in this contract is aios/aios. A floating ref is resolved once; all subsequent reads in the response are bound to the returned full resolved_oid (or resolved_from_oid and resolved_to_oid for a diff) and, for files, the returned blob_oid.

The following invariants remain frozen for this P0:

AIOS_GITOPS_WRITES_ENABLED=false
legacy_global_writes_enabled=false
18893 runtime_mode=IMMUTABLE_STAGING
direct bare-repository writes/pushes=forbidden
direct Task DB writes=forbidden

Discovery is a read-only operation. It does not acquire a WriterLease and it does not create a Task. Any implementation change still has to use the formal Task → TaskPrincipal → TaskLease/claim/heartbeat → WriterLease → commitFilesGoverned path. A request to discovery must never be used as a write-capability probe.

Execution-plane preflight

1. Prefer the formal HTTPS control plane at the configured public API/Bridge endpoint. If raw SSH fails before authentication, preserve that evidence and do not retry arbitrary usernames, keys, ports, or shell commands.
2. Read runtime, capability, snapshot, and OpenAPI facts. Confirm that the authority identity and OID are the expected ones, and record whether the discovery routes are actually deployed on that plane.
3. Classify the available plane as A (network-enabled Codex profile), B (attested online worker), C (formal HTTPS control plane), or D (existing executor/coordinator). Select only a supported plane; do not invent a new SSH or credential path.
4. Treat a readable runtime or a candidate branch as evidence of availability, not as authorization to write.

The durable discovery record is execution-plane-discovery.json. It must not be included in the governed source change unless the task explicitly allowlists it.

Read operations

The canonical Bridge routes are:

Operation	Method	Required query fields	Optional query fields
listRepositoryTree	GET /v2/repository/tree	repository, ref, limit	prefix, depth, cursor
searchRepositorySource	GET /v2/repository/search	repository, ref, query, max_matches, max_bytes	path_globs, cursor
getDiffIndex	GET /v2/repository/diff-index	repository, from, to, limit	path_prefix, cursor
readRepositoryFile	GET /v2/repository/file	repository, ref, path	max_bytes

The Actions adapter exposes the corresponding read-only legacy paths under /api/repository/*; the OpenAPI document records each mapping with x-aios-legacy-path.

Every request is bounded. Repository identity is allowlisted, refs are limited to a branch/tag/full commit form, paths are normalized POSIX-relative paths, and traversal, option-like paths, shell metacharacters, and ambiguous refs fail closed. Search skips binary blobs and enforces its cumulative byte bound. Tree, search, and diff responses are paginated. A cursor is an HMAC- bound record containing the operation, repository, resolved OID, complete query, and offset; never edit or manually construct one.

The diff endpoint returns an index only: status, path, optional old path, and bounded additions/deletions. It never returns a patch body. The file endpoint returns bounded text plus content_base64, resolved_oid, and blob_oid.

Publishing an implementation change

1. Preserve the existing dirty worktree. Create a new isolated worktree at the exact authority OID and use a task-scoped branch.
2. Run discovery unit, pagination, cursor, identity, traversal, binary, max-byte, immutable-head, and large-diff tests. Run the Bridge/OpenAPI/ Actions drift tests and compile checks.
3. Obtain a formal governed Task and keep its exact task, job, generation, idempotency, branch, and base-OID identities. Claim and heartbeat through the supported control plane; do not edit the Task DB or copy a credential.
4. Acquire the Task-bound principal and WriterLease. Submit the allowlisted source files through commitFilesGoverned, then reconcile the Job if the result is uncertain.
5. Independently read back the authority Git ref, the remote Git API ref, and the control-plane projection. Completion requires three-way equality to the governed commit OID, plus the required deployment/acceptance/restart/ official-verification evidence for any release claim.

If the discovery routes are absent from the live OpenAPI/runtime surface, stop at local validation. Report the implementation and tests as local evidence and mark governed Task, WriterLease, governed commit, and post-commit readback as NOT_VERIFIED.

Failure and recovery

• REPOSITORY_NOT_ALLOWED, identity mismatch, invalid path/ref, invalid cursor, or ambiguous ref is a client or security rejection; do not broaden the allowlist.
• An unavailable authority repository or missing cursor secret is a runtime configuration failure; do not disable cursor signing or fall back to a workspace checkout.
• A timeout, oversized output, or large diff is bounded failure. Narrow the prefix/page or repair the existing supported runtime, never return an unbounded patch.
• On Windows, a missing fcntl means POSIX integration is unverified. Keep the Python compile and portable unit evidence, then rerun the HTTP and file locking probes on the supported Linux runtime.

No recovery step in this runbook resets, cleans, overwrites, force-pushes, or auto-commits a user worktree.