Delivery architecture¶

Normal path¶

GitHub Issue
  → exact Issue-linked branch and registered worktree
  → focused implementation checks
  → review-stable required profile
  → pull request at an exact head SHA
  → exact-head hosted validate
  → eligible merge
  → Issue/check/commit readback
  → remote and local topic-branch cleanup

GitHub and Git are the system of record. Ordinary work never pushes directly to main. Existing user changes are not included, tested, or removed. A failed, skipped, stale, or unavailable hosted validation blocks acceptance until the isolated self-hosted runner/workflow produces a new exact-head success.

Verification relationship¶

Focused checks provide fast iteration evidence. The required profile proves a review-stable repository candidate. Merge acceptance requires evidence bound to the pull request head. Release gates are cumulative and separate from merge.

The disposable self-hosted runner receives no host mount, Docker socket, or delivery credential. Local test results are iteration evidence, never merge evidence.

The executable contract is trusted delivery. Its current-only candidate request identity is ai-teams-delivery-request/v1; the earlier unreleased identity is rejected.

Recurrence acceptance¶

Terminal learning requires a lifecycle for every observed recurring event, independently of whether the coordinator calls it a learning candidate or an operator error. Unresolved work needs a live, independently open Issue; the current Issue cannot close while it is its own unresolved tracker.

Current-Issue remediation uses event-specific Work Item acceptance: the actual Issue evidence comment binds the failure signature, current acceptance criterion, reviewed cause/correction/regression, and accepted candidate. Terminal readback checks that binding and the real PR artifacts before persistence. It does not infer causal correctness from green CI. Coordinator review still owns causal adequacy; source delivery and later effectiveness remain distinct.

The normal zero-event path needs no provider read or manually authored claim file. For recurring events, the terminal owner generates mechanical claim fields and pending lifecycle entries; it does not invent evidence or choose remediation. See the contract and Decision #1220. Automatic host event capture remains unavailable where the host does not expose it. Target recovery and cleanup ordering use the bounded route below.

Workspace operation entry¶

The next slice of Decision #1220 keeps prepare_workspace.py as the owner. Its no-effect --describe returns canonical instructions, the actual argument parser and shared conditional rules. Malformed invocations receive that same guidance before repository or preparation work. Invalid local Python is checked before creating a worktree; valid virtualenv paths preserve their identity.

Discovery does not attest that an agent read a rule and grants no readiness or edit authority. Existing host/user policy, exact worktree, runtime checks, claim and one-shot lease still govern execution. Valid normal calls add no receipt or mandatory description call. This consolidates input-shape knowledge rather than introducing a workflow engine. See the operation contract. Installed adoption and later effectiveness remain pending; source acceptance does not establish whole-delivery speedup.

Search, preflight and terminal recovery¶

The search operation returns its query owner's schema and example through search --describe or search-github --describe. Invalid query input returns the same contract before opening SQLite or calling a provider. Normal calls require no description call and no new input document.

The repository quality operation composes PR acceptance metadata, Issue linkage and design applicability before its existing CI profile. Its --describe exposes the existing design-input document; run --profile ci --pr-input INPUT selects existing isolated local preflight and checks actual origin and exact clean candidate identity before and after CI. Supplied Issue text remains a local snapshot; hosted authoritative readback and exact-head validate still gate merge. There is no second verification policy.

For completed delivery, policy-selected cleanup precedes final evidence. The terminal router checks exact local/remote refs and the canonical Issue worktree, including detached registrations, from a surviving root. The canonical keep mode retains local work explicitly; ask requires its existing policy decision. Blocked/failed delivery retains work and cannot claim completed cleanup.

Each persistence target reads back the immutable payload before writing. A matching target is reused; new Issue writes enter the existing receipt gate and require exact comment readback. Lost responses and late readback failures resume with target discovery, without replaying successful writes or rebuilding execution history. An uncertain previous effect with no matching target blocks another write. There is no finalization ledger, scheduler, or automatic semantic remediation. Receipt storage and optional persistence remain separate owners.

These source-level mechanisms implement the remaining operation-boundary slices of Decision #1220. Installed-host adoption, capture completeness on unsupported hosts, and later recurrence absence are not established by local tests or a merge.

Unified project status and Decision Inbox¶

The finite decision_inbox.py entry point composes live bounded GitHub Issue reads, the existing product marker/reconstruction owner and Project State. ai-teams-decision/v2 adds explicit same-Goal/Bet workstream scope and guidance; v1 stays readable with migration-required guidance. Scoped holds are derived only from pending decisions and do not acquire worker or permission authority. Unlinked open Issues are reported separately without inferred product links.

Decision actions reuse the GitHub current-revision update and operation-receipt owners, preserve surrounding Issue prose, and verify one exact readback. A read-before-write check is not atomic GitHub compare-and-swap. Competing writes must remain serialized by the caller; uncertain effects are never retried. The optional Control Lite observer uses a read-only connection and repository filter; it performs no schema creation, lease recovery or job mutation and exposes no payloads or lease tokens. See the canonical contract for bounds, lifecycle, compatibility and authority.

Outcome evaluation and Next Bet proposals¶

outcome_evaluation.py connects the existing deployment store, Observation Plan, Control Lite jobs and product-state transitions. Its explicit schedule operation requires successful exposure and current Goal/Bet/plan revisions. Collection starts no earlier than the observation window and still needs the Evidence Source adapter's read authority. Technical deployment validation is not outcome confirmation.

A revision-bound semantic assessment records confirmed, contradicted, pending or unavailable. Confirmed/contradicted outcome Evidence proposes a legal Bet transition and one pending Decision. Missing observation or an implementation failure produces no Next Bet proposal; a Goal-premise contradiction asks for a Goal decision without changing it. Current provider revisions and causal review remain required before any independently authorized product update.

The optional Control Lite extension evaluates one Evidence revision once and recovers its original proposal after restart without generating another replan. An existing authoritative Decision identity also prevents duplicate proposals. The finite CLI starts no background worker and grants no provider write, deployment, credential or approval authority. See the canonical outcome contract for schemas, bounds, replay behavior and retained product-effectiveness limits.