# Orchestration Architecture Index V01

Issue: [#370](https://github.com/pinklon/ai-capability-discipline/issues/370)

References:

- [#356 GitHub Issues queue-backed agent work engine MVP](https://github.com/pinklon/ai-capability-discipline/issues/356)
- [PR #357 GitHub Issues queue-backed agent work engine MVP](https://github.com/pinklon/ai-capability-discipline/pull/357)
- [#358 Add read-only queue planner and parallelism report v01](https://github.com/pinklon/ai-capability-discipline/issues/358)
- [PR #359 Add read-only queue planner and parallelism report v01](https://github.com/pinklon/ai-capability-discipline/pull/359)
- [#360 Add GitHub issue-body work payload template v01](https://github.com/pinklon/ai-capability-discipline/issues/360)
- [PR #361 Add GitHub issue-body work payload template v01](https://github.com/pinklon/ai-capability-discipline/pull/361)
- [#362 Add live read-only GitHub issue export to committed planner fixture v01](https://github.com/pinklon/ai-capability-discipline/issues/362)
- [PR #363 Add live read-only GitHub issue export to committed planner fixture v01](https://github.com/pinklon/ai-capability-discipline/pull/363)
- [#364 Add exported-issue planner integration report v01](https://github.com/pinklon/ai-capability-discipline/issues/364)
- [PR #365 Add exported-issue planner integration report v01](https://github.com/pinklon/ai-capability-discipline/pull/365)
- [#366 Add human-mediated orchestration lane operating packet v01](https://github.com/pinklon/ai-capability-discipline/issues/366)
- [PR #367 Add human-mediated orchestration lane operating packet v01](https://github.com/pinklon/ai-capability-discipline/pull/367)
- [#368 Add human-mediated orchestration dry-run receipt v01](https://github.com/pinklon/ai-capability-discipline/issues/368)
- [PR #369 Add human-mediated orchestration dry-run receipt v01](https://github.com/pinklon/ai-capability-discipline/pull/369)

## Purpose

This index is the canonical repo-local architecture reference for the current orchestration stack. It consolidates the landed GitHub Issues queue-backed model, read-only planner, issue-body payload template, read-only export fixture, exported planner report, human-mediated operating packet, and dry-run receipt into one readable map.

The current control plane remains Tony plus Codex, manually mediated. Planner output does not trigger implementation. No autonomous worker loop exists.

This index is consolidation only. It adds no live GitHub mutation behavior, no source mutation, no Cloudflare mutation, no runtime/provider mutation, no browser retrieval mutation, and no package-authority mutation.

## Canonical Landed Orchestration Layers

| Layer | Issue | PR | Artifact/document path | Fixture path | Validator path | Generated report or receipt path | Responsibility | Input artifacts | Output artifacts | Non-goals and forbidden behavior |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Model: GitHub Issues queue-backed agent work engine MVP | #356 | #357 | `docs/product-architecture/github_issues_agent_work_engine_mvp_v01.md` | `validation/fixtures/github_issues_agent_work_engine_mvp_v01.json` | `validation/scripts/check_github_issues_agent_work_engine_mvp.py` | Not applicable | Defines state model, transitions, parallelism classes, claim/lock/lease model, validation, and closeout proof requirements. | Backlog workflow, queue-backed work engine evaluation, repo issue and PR ceremony patterns. | Repo-local model and deterministic fixture for later planner work. | Not autonomous execution, polling, webhook loop, scheduled loop, external queue provider, Linear/Jira/custom DB/MCP behavior, source registry mutation, source-set mutation, Cloudflare change, provider/model change, runtime retrieval change, browser retrieval, OKF implementation, Google SDLC implementation, package-authority change, reopening #269 or #271, or `codex-automerge`. |
| Planner: read-only queue planner and parallelism report | #358 | #359 | `docs/product-architecture/github_issues_queue_planner_v01.md` | `validation/fixtures/github_issues_queue_planner_v01.json` | `validation/scripts/check_github_issues_queue_planner.py` | Script output only from `scripts/github_issues_queue_planner.py` | Classifies deterministic work-item fixtures into serial, safe-parallel, blocked, owner-decision, high-risk gated, lock-conflict, stale-lock, invalid, validation, and closeout sections. | Work engine model, deterministic queue planner fixture. | JSON or Markdown planner report over committed data. | Does not mutate live GitHub, create branches, trigger execution, run autonomous polling, add webhook loops, integrate external queues, mutate source registries or source sets, change Cloudflare, provider/model, runtime retrieval, browser retrieval, package authority, reopen #269 or #271, or apply `codex-automerge`. |
| Model: GitHub issue-body work payload template | #360 | #361 | `docs/product-architecture/github_issues_work_payload_template_v01.md` | `validation/fixtures/github_issues_work_payload_template_v01.json` and `validation/fixtures/github_issues_work_payload_source_v01.json` | `validation/scripts/check_github_issues_work_payload_template.py` | Not applicable | Defines human-readable issue sections plus fenced YAML payload shape for planner-readable work metadata. | Work engine model and read-only planner lane contract. | Valid and invalid issue-body payload examples. | Does not parse live GitHub issues, export live issue bodies, mutate GitHub, trigger implementation, add autonomous polling, add webhook loops, integrate external queues, mutate source registries or source sets, change Cloudflare, provider/model, runtime retrieval, browser retrieval, package authority, reopen #269 or #271, or apply `codex-automerge`. |
| Export fixture: live read-only GitHub issue export to committed planner fixture | #362 | #363 | `docs/product-architecture/github_issues_read_only_export_fixture_v01.md` | `validation/fixtures/github_issues_exported_planner_fixture_v01.json` | `validation/scripts/check_github_issues_read_only_export_fixture.py` | Deterministic generated fixture from `scripts/github_issues_read_only_export_fixture.py` | Normalizes issue-body payload records into committed planner-readable fixture data and preserves rejected payload handling. | Issue-body payload source fixture, optional explicit live read-only GitHub issue inspection mode. | Normalized committed export fixture and rejected payload records. | Does not mutate live GitHub issues or PRs, labels, milestones, assignees, comments, state, branches, planner execution, autonomous loops, external queues, source registries or source sets, Cloudflare, provider/model, runtime retrieval, browser retrieval, package authority, reopen #269 or #271, or apply `codex-automerge`. |
| Report: exported-issue planner integration report | #364 | #365 | `docs/product-architecture/github_issues_exported_planner_report_v01.md` | `validation/fixtures/github_issues_exported_planner_report_v01.json` | `validation/scripts/check_github_issues_exported_planner_report.py` | JSON and Markdown report output from `scripts/github_issues_exported_planner_report.py` | Consumes the committed exported fixture, adapts normalized records into planner-compatible input, maps records into planner lanes, and preserves rejected-before-planning records. | Read-only export fixture and queue planner model. | Exported planner report with lanes, rejected records, validation, closeout, metadata, and non-mutation confirmations. | Does not call live GitHub during validation, mutate GitHub, trigger implementation, create branches, add autonomous loops, integrate external queues, mutate source registries or source sets, change Cloudflare, provider/model, runtime retrieval, browser retrieval, package authority, reopen #269 or #271, or apply `codex-automerge`. |
| Operating packet: human-mediated orchestration lane operating packet | #366 | #367 | `docs/product-architecture/human_mediated_orchestration_lane_operating_packet_v01.md` | `validation/fixtures/human_mediated_orchestration_lane_operating_packet_v01.json` | `validation/scripts/check_human_mediated_orchestration_lane_operating_packet.py` | `validation/receipts/AI_Capability_Playbook_HUMAN_MEDIATED_ORCHESTRATION_LANE_OPERATING_PACKET_V01_2026-06-29.md` | Defines how Tony and Codex manually interpret planner lanes, prevent duplicate work, prevent branch/file collision, use claim/lease evidence, document owner decisions, and preserve closeout receipts. | Work engine model, planner report, issue-body payload template, read-only export fixture, exported planner report. | Manual operating packet and deterministic lane decision fixture. | Does not implement autonomous execution, create a worker loop, trigger implementation from planner output, mutate GitHub, integrate external queues, mutate source registries or source sets, change Cloudflare, provider/model, runtime retrieval, browser retrieval, package authority, reopen #269 or #271, or apply `codex-automerge`. |
| Dry-run receipt: human-mediated orchestration proof | #368 | #369 | `docs/product-architecture/human_mediated_orchestration_dry_run_receipt_v01.md` | `validation/fixtures/human_mediated_orchestration_dry_run_receipt_v01.json` | `validation/scripts/check_human_mediated_orchestration_dry_run_receipt.py` | `validation/receipts/AI_Capability_Playbook_HUMAN_MEDIATED_ORCHESTRATION_DRY_RUN_RECEIPT_V01_2026-06-29.md` | Proves the operating packet can interpret planner lanes and produce safe manual next-action posture from committed fixtures without starting work. | Human-mediated operating packet, exported planner report fixture, lane decision fixture, queue planner model, issue-body payload template, work engine model. | Static dry-run receipt covering safe-parallel, serial, blocked, owner-decision, high-risk gated, rejected-before-planning, duplicate/collision, and stale or missing claim cases. | Does not start implementation, create child issues, create branches, mutate GitHub, add autonomous execution, integrate external queues, mutate source registries or source sets, change Cloudflare, provider/model, runtime retrieval, browser retrieval, package authority, reopen #269 or #271, or apply `codex-automerge`. |

## End-To-End Flow

1. Issue-body payload template: a human-authored issue can carry structured work metadata in fenced YAML while remaining human-readable and non-executing.
2. Read-only export fixture: committed or explicitly read-only issue inspection normalizes issue payloads into planner fixture records and rejects unsafe or malformed records before planning.
3. Exported planner report: normalized records are adapted into planner-compatible input, classified, and reported with rejected-before-planning records preserved.
4. Queue planner lane classification: planner logic separates serial, safe-parallel, blocked, owner-decision, high-risk gated, lock-conflict, stale-lock, invalid, validation, and closeout evidence.
5. Human-mediated lane operating packet: Tony plus Codex manually interpret planner lanes, verify current repo and GitHub state, and apply duplicate, collision, dependency, owner, risk, label, validation, closeout, and claim gates.
6. Human-mediated dry-run receipt: deterministic receipt evidence proves the manual lane interpretation and stop posture without live mutation or implementation.
7. Human-created child ticket or stop decision: a safe-parallel candidate may become a human-created child ticket prompt only after all gates pass. Blocked, owner-decision, high-risk, rejected, duplicate, collision, or stale/missing claim cases stop.

## Artifact Dependency Graph

| From | To | Dependency meaning |
| --- | --- | --- |
| Work engine MVP | Queue planner | Supplies states, transitions, parallelism classes, lock/lease concepts, validation, and closeout requirements. |
| Queue planner | Issue-body payload template | Supplies planner lane fields that issue authors need to express. |
| Issue-body payload template | Read-only export fixture | Supplies the structured issue-body contract that can be normalized. |
| Read-only export fixture | Exported planner report | Supplies normalized records and rejected records. |
| Queue planner | Exported planner report | Supplies classification logic and lane vocabulary. |
| Exported planner report | Human-mediated operating packet | Supplies advisory lane output for manual interpretation. |
| Human-mediated operating packet | Human-mediated dry-run receipt | Supplies the manual gate model and stop posture. |
| Human-mediated dry-run receipt | Human-created child ticket or stop decision | Supplies proof that the next action remains manual and non-executing. |

## Vocabulary Boundaries

| Term | Current meaning | Boundary |
| --- | --- | --- |
| Model | Repo-local state, transition, payload, parallelism, lock, lease, validation, and closeout contract. | Not an executor. |
| Planner | Read-only classifier over deterministic data. | Planner output does not trigger implementation. |
| Export fixture | Deterministic committed normalization of issue payload records. | Not a live mutation path. |
| Report | Read-only lane and evidence output. | Not a command queue. |
| Operating packet | Manual instructions for Tony plus Codex. | Not automation. |
| Dry-run receipt | Static proof of lane interpretation and stop posture. | Not an execution receipt. |
| Human-mediated decision | Owner or operator decision to create a child ticket, stop, clarify, or defer. | The decision remains outside planner output. |
| future worker concept, not implemented | A later owner-approved architecture question about identity, permissions, loop semantics, retry, audit, and recovery. | No worker design or worker loop is implemented here. |

## Lane Ownership

| Lane or condition | Owner of next action | Required posture |
| --- | --- | --- |
| serial | Tony plus Codex manually sequence one item at a time. | Verify ordered prerequisite, active branch, worktree, open PRs, file scope, generated artifacts, validation, and closeout requirements before any child ticket. |
| safe-parallel | Tony plus Codex may prepare a candidate child-ticket prompt only after all gates pass. | Duplicate, branch/file collision, dependency closure, labels, validation, closeout receipt, and claim/lease evidence must be current and clear. |
| blocked | Tony plus Codex stop. | Wait for dependency closure evidence, missing artifact availability, resolved PR state, or explicit owner decision. |
| owner-decision | Tony owns the decision. Codex records the exact question and waits. | Output is owner decision evidence, not implementation. |
| high-risk gated | Tony owns explicit approval and separate ticket creation. | Stop until protected-boundary approval and separate high-risk ticket evidence exist. |
| rejected-before-planning | Tony plus Codex repair or leave rejected through an explicit issue-update path. | Rejected records never enter lane handling and never start work. |

## Evidence And Receipt Requirements

The manual control plane depends on evidence before action:

- Claim/lease evidence: claim actor, branch, base commit, lock id, claimed timestamp, lease expiration, and stale or conflicting claim status.
- Duplicate checks: matching title, objective, parent issue, allowed files, validation contract, existing issue, existing PR, and closeout state.
- Branch/file collision checks: active branches, open PRs, changed files, generated artifacts, validation receipt paths, and protected artifact overlap.
- Dependency closure evidence: dependency issue state, PR state, merge or closeout proof, validation receipt, and unambiguous dependency semantics.
- Owner decision evidence: explicit Tony instruction, selected option or decision, date, evidence location, and boundary changes or preserved boundaries.
- Validation evidence: focused validators, existing orchestration validators, backlog and Codex ceremony validators, context-pack validation, `python3 -B validation/scripts/run_all.py`, `git diff --check`, and residue scan.
- Closeout receipt evidence: issue URL, PR URL, branch, commit SHA, changed files, validation results, run_all result, diff check, worktree state, residue result, #269/#271 state, `codex-automerge` state, and forbidden-scope confirmation.

## What Is Proven

- GitHub Issues can be modeled as the near-term queue substrate.
- Issue bodies can carry structured work payloads.
- Read-only export can normalize issue payloads into committed fixtures.
- Exported fixtures can feed planner reports.
- Planner reports can classify work into lanes.
- Human-mediated packet can interpret those lanes.
- Dry-run receipt can prove safe manual next-action posture.
- Rejected, blocked, owner-decision, high-risk, duplicate/collision, and stale/missing claim cases stop instead of proceeding.

## What Is Not Proven

- Autonomous execution.
- Worker identity.
- Worker permissions.
- GitHub write behavior by a worker.
- Parallel Codex execution at scale.
- Webhook handling.
- Scheduled polling.
- External queue integration.
- Linear/Jira/custom DB/MCP integration.
- Source Registry Admin live apply.
- Cloudflare mutation.
- Runtime/provider mutation.
- Browser retrieval mutation.
- Package-authority mutation.

## Future Work That Remains Gated

Future worker concept, not implemented, remains a gated architecture question. Any later worker work would require a separate owner-approved issue that defines identity, permissions, event source, loop behavior, retry, recovery, audit, lease renewal, GitHub write posture, failure handling, and closeout authority.

Future integrations with webhook handling, scheduled polling, external queues, Linear, Jira, custom databases, MCP behavior, Source Registry Admin live apply, Cloudflare mutation, runtime/provider mutation, browser retrieval mutation, or package-authority mutation remain out of scope until separately approved.

## Forbidden Scope

This index and its validator must not add autonomous execution, worker design beyond naming future gated work, a worker loop, a webhook loop, scheduled polling, scheduled execution, an external queue provider, Linear behavior, Jira behavior, custom DB behavior, MCP behavior, live GitHub issue or PR mutation, labels mutation, milestone mutation, assignee mutation, comment mutation, issue state mutation, PR state mutation, branch state mutation, merge state mutation, planner-triggered implementation, automatic child issue creation, automatic branch creation, GitHub write behavior, source registry mutation, Preview source-set mutation, Production source-set mutation, source enablement, source disablement, source retirement, source promotion, source apply behavior, Cloudflare CLI/API use, Cloudflare Access/WAF change, provider/model configuration change, runtime retrieval semantics change, browser-side provider calls, browser-side current-source retrieval, package-authority change, reopening #269, reopening #271, or `codex-automerge`.

## Validation

The focused validator is `validation/scripts/check_orchestration_architecture_index.py`.

The deterministic companion fixture is `validation/fixtures/orchestration_architecture_index_v01.json`.

The validation receipt is `validation/receipts/AI_Capability_Playbook_ORCHESTRATION_ARCHITECTURE_INDEX_V01_2026-06-29.md`.

The validator proves required mappings, flow, proven/not-proven sections, future gated work, forbidden boundaries, product-architecture discoverability, context-pack inclusion, and run_all wiring.