# Controlled Worker Design Packet V01

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

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)
- [#370 Add orchestration architecture index v01](https://github.com/pinklon/ai-capability-discipline/issues/370)
- [PR #371 Add orchestration architecture index v01](https://github.com/pinklon/ai-capability-discipline/pull/371)

## Purpose And Non-Executable Boundary

This packet defines the design boundary for a possible future controlled worker. It is architecture and governance only. It does not implement a worker, worker loop, polling loop, scheduled execution, webhook-triggered execution, external queue provider, Linear integration, Jira integration, custom database behavior, MCP server behavior, MCP client behavior, live GitHub issue or PR mutation, source mutation, Cloudflare mutation, provider/model mutation, runtime retrieval mutation, browser retrieval mutation, package-authority mutation, or autonomous execution.

The current control plane remains Tony plus Codex, manually mediated. Planner output remains advisory. A human-created issue and explicit owner instruction remain required before implementation work starts.

## Design Packet Versus Implementation

This design packet names constraints that any later worker proposal must satisfy before code exists. It is not a runtime component, daemon, scheduler, listener, command processor, queue adapter, GitHub App, webhook receiver, browser client, package-authority updater, Cloudflare controller, source registry administrator, or MCP tool.

No worker is implemented by this packet. No worker loop is implemented by this packet. No GitHub issue or PR mutation path is implemented by this packet.

## Worker Identity Model

A future controlled worker concept would require a separately approved identity record before implementation. The identity record would include:

| Field | Required posture |
| --- | --- |
| Worker id | Stable repo-local identifier approved in a future issue. |
| Actor owner | Human owner accountable for activation, suspension, and closeout review. |
| Execution surface | Explicitly classified as local, CI, managed service, or other approved surface before use. |
| Credential posture | No ambient credential inheritance. Any credential would be separately approved, scoped, rotated, and revocable. |
| Claim identity | Claims must identify the claim actor, branch, issue, base commit, lock id, claimed timestamp, and lease expiration. |
| Receipt identity | Receipts must record the same worker id, owner, execution surface, source inputs, outputs, validation, and stop posture. |

The identity model is design-only. It does not create credentials, service accounts, GitHub Apps, API tokens, browser sessions, MCP clients, Cloudflare bindings, source registry rights, or package-authority rights.

## Permission Model

A future controlled worker concept would start from least privilege and fail closed.

| Permission class | Design posture |
| --- | --- |
| Read repo files | May be proposed only for explicit repo paths required by the future ticket. |
| Read committed planner fixtures | May be proposed for deterministic planning evidence. |
| Read live GitHub metadata | May be proposed only as explicit read-only inspection, with no label, milestone, assignee, comment, issue state, PR state, branch state, or merge state mutation. |
| Write repo files | Requires a human-created issue, bounded file list, branch, validation contract, review, and PR. |
| Write GitHub metadata | Not authorized by this packet. Any future proposal requires separate owner approval and a separate implementation ticket. |
| Source registry or source-set mutation | Not authorized. |
| Cloudflare mutation | Not authorized. |
| Provider, model, runtime, browser, or package-authority mutation | Not authorized. |

The permission model does not grant runtime permissions. It defines what a future proposal must ask for and what it must refuse by default.

## Allowed Future Actions, Design-Only

The following actions may be discussed in a future owner-approved design or implementation ticket, but this packet does not execute them:

- Read deterministic repo-local fixtures.
- Read product architecture notes and validation receipts.
- Classify committed work-item records into advisory lanes.
- Produce repo-local dry-run reports over committed fixture data.
- Identify missing owner gates, stale leases, duplicate work, branch/file collisions, and validation gaps.
- Recommend a stop, clarify, defer, or human-created child-ticket posture.
- Produce a closeout receipt template for later human review.

All allowed actions are design-only here. They do not start implementation, create branches, create child issues, mutate GitHub, call Cloudflare, change sources, change runtime behavior, call providers, retrieve current sources from the browser, or change package authority.

## Prohibited Actions

A future controlled worker must refuse these actions unless a later owner-approved issue explicitly changes the boundary and the required validators are updated:

- Autonomous execution.
- Worker loop behavior.
- Polling.
- Scheduled execution.
- Webhook-triggered execution.
- External queue provider integration.
- Linear integration.
- Jira integration.
- Custom database behavior.
- MCP server behavior.
- MCP client behavior.
- Live GitHub issue or PR mutation.
- Label, milestone, assignee, comment, issue state, PR state, branch state, or merge state mutation.
- Planner output triggering implementation.
- Planner output creating child issues.
- Planner output creating branches.
- Source registry mutation.
- Preview source-set mutation.
- Production source-set mutation.
- Source enablement, disablement, retirement, promotion, or apply behavior.
- Cloudflare CLI or API use.
- Cloudflare Access or 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.
- Applying `codex-automerge`.

## Claim And Lease Model

Any future worker proposal must keep claims and leases as evidence, not ambient permission.

| Claim or lease element | Required design posture |
| --- | --- |
| Claim actor | Must identify the human or approved worker identity making the claim. |
| Branch | Must be explicit and issue-scoped. |
| Base commit | Must be recorded before work starts. |
| Lock id | Must be deterministic and tied to issue, branch, and file scope. |
| Claimed timestamp | Must be recorded in UTC. |
| Lease expiration | Must be explicit. Stale leases stop work. |
| Conflicting claim | Stops work until the conflict is resolved manually. |
| Missing claim | Stops work before implementation. |
| Lease renewal | Requires explicit evidence and cannot be automatic in this packet. |

Claim and lease evidence cannot override owner gates, protected boundaries, dirty worktrees, stale baselines, failed validation, duplicate tickets, branch/file collisions, or hard no-mutation constraints.

## Stop Conditions

The future controlled worker concept must stop when any of these conditions are present:

- Missing, closed, superseded, or mislabeled work issue.
- Dirty local worktree after sync.
- Repo-controlled `__pycache__`, `.pyc`, or `.wrangler` residue after validation.
- Local HEAD cannot resolve the expected remote baseline after fetch.
- Duplicate issue or PR already covers the same bounded work.
- Branch or file collision exists.
- Dependency issue or PR is incomplete.
- Claim is missing, stale, conflicting, or outside the approved file scope.
- Required owner gate is missing.
- Work crosses source registry, source-set, Cloudflare, provider/model, runtime retrieval, browser retrieval, package-authority, GitHub mutation, Linear, Jira, custom DB, MCP, polling, webhook, scheduler, or external queue boundaries.
- Focused validator, related orchestration validators, governance validators, context-pack validation, `python3 -B validation/scripts/run_all.py`, or `git diff --check` fails.

Stopping is a valid outcome. A stop posture must produce evidence rather than partial mutation.

## Owner Gate Requirements

Owner gates remain human-mediated. Tony plus Codex is the active control plane for this packet.

| Gate | Required evidence before later action |
| --- | --- |
| New implementation ticket | Human-created or explicitly owner-approved issue with exact scope, labels, files, validations, and boundaries. |
| High-risk behavior | Separate owner approval with protected-boundary language preserved in the issue. |
| GitHub write behavior | Separate owner approval and validator coverage before any mutation path exists. |
| Source or Cloudflare behavior | Separate owner approval, source-set posture, rollback, and receipts before any mutation path exists. |
| Runtime, provider, browser, or package authority behavior | Separate owner approval and architecture update before any mutation path exists. |
| External queue, Linear, Jira, custom DB, or MCP behavior | Separate owner approval and adapter-specific architecture before any integration exists. |

No owner gate is implied by this design packet. Approval must be explicit and issue-local.

## Validation Requirements

Any later worker proposal must include deterministic validation before runtime behavior is considered:

- Focused validator for the specific worker proposal.
- Fixture coverage for valid and invalid worker-boundary examples.
- Orchestration validators for the existing queue-backed, read-only planner, payload template, export fixture, exported report, human-mediated operating packet, dry-run receipt, and architecture index layers.
- Governance validators for backlog label enforcement, backlog workflow, backlog closure governance, and Codex ceremony.
- Context-pack validation if product architecture or corpus-visible files are touched.
- Full validation with `python3 -B validation/scripts/run_all.py`.
- Whitespace validation with `git diff --check`.
- Residue scan for repo-controlled `__pycache__`, `.pyc`, and `.wrangler`, excluding `.git`, `.venv`, and `node_modules`.

Validators must not mutate live GitHub, source registries, source sets, Cloudflare, provider/model configuration, runtime retrieval, browser retrieval, package authority, Linear, Jira, custom databases, or MCP behavior.

## Rollback Expectations

Because this packet is design-only, rollback for this change means reverting repo-local documentation, fixture, validator, receipt, discoverability, and context-pack artifacts through normal Git review.

Any later worker implementation proposal must define rollback before implementation. At minimum, rollback must cover:

- Stop switch or suspension posture.
- Credential revocation posture.
- Claim and lease cancellation posture.
- Branch cleanup posture.
- GitHub metadata recovery posture if a future ticket ever approves GitHub writes.
- Source, Cloudflare, runtime, provider, browser, and package-authority non-mutation confirmation.
- Validation and closeout receipt after rollback.

Rollback cannot depend on an autonomous loop to repair itself.

## Closeout Receipt Expectations

A future controlled worker closeout receipt must include:

- Issue URL.
- PR URL, if a PR exists.
- Branch name.
- Commit SHA.
- Starting and final local HEAD.
- Worktree status.
- Residue scan result.
- Changed files.
- Validation commands and results.
- Claim and lease evidence.
- Owner gates satisfied or missing.
- Stop conditions encountered or explicitly absent.
- Rollback posture.
- Confirmation that no worker loop, webhook loop, scheduled loop, polling loop, external queue, GitHub mutation behavior, source mutation, Cloudflare mutation, provider/runtime/browser/package-authority mutation, Linear/Jira/custom DB/MCP behavior, #269/#271 reopen, or `codex-automerge` was introduced unless separately approved by a later issue.

## Human-Mediated Control-Plane Relationship

This packet preserves Tony plus Codex as the human-mediated control plane.

The human-mediated control plane:

- Verifies issue and PR state before work starts.
- Creates or approves child tickets.
- Chooses whether safe-parallel work may proceed.
- Handles owner-decision and high-risk gated lanes.
- Confirms branch, file, claim, lease, validation, and closeout evidence.
- Stops work when boundaries are unclear or violated.

The packet does not replace Tony with an autonomous execution engine.

## Relationship To Existing Orchestration Architecture Layers

| Existing layer | Relationship to this packet |
| --- | --- |
| GitHub Issues queue-backed agent work engine MVP | Supplies state, transition, parallelism, claim, lock, lease, validation, and closeout vocabulary. |
| Read-only queue planner and parallelism report | Supplies advisory lane classification over deterministic data. |
| GitHub issue-body work payload template | Supplies structured work metadata for human-authored issues. |
| Read-only GitHub issue export fixture | Supplies committed planner fixture posture and rejected payload handling. |
| Exported-issue planner integration report | Supplies lane output that remains advisory and non-executing. |
| Human-mediated orchestration lane operating packet | Supplies manual lane interpretation, duplicate prevention, collision prevention, owner gates, and closeout posture. |
| Human-mediated orchestration dry-run receipt | Supplies proof that lane interpretation can stop safely without starting work. |
| Orchestration architecture index | Supplies the canonical map of the landed stack and the distinction between proven, not-proven, and future-gated behavior. |

This packet adds the future controlled-worker boundary layer on top of that stack. It does not convert any existing layer into an executor.

## What Is Proven

- A controlled worker can be discussed as a future architecture question without implementing it.
- Worker identity, permissions, allowed actions, prohibited actions, claims, leases, stop conditions, owner gates, validation, rollback, and receipts can be specified before implementation.
- The existing orchestration stack remains human-mediated.
- Invalid worker-boundary examples can be rejected by deterministic fixture validation.

## What Is Not Proven

- Autonomous execution.
- Worker implementation.
- Worker loop behavior.
- Polling behavior.
- Scheduled execution.
- Webhook-triggered execution.
- GitHub write behavior by a worker.
- 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

Any later controlled worker implementation remains gated behind a separate owner-approved issue. That issue would need to define identity, permissions, event source, execution surface, loop posture, retry posture, failure handling, claim and lease renewal, GitHub write posture, validation, rollback, audit, suspension, and closeout authority before code exists.

Until that separate approval exists, the only valid posture is design-only documentation, deterministic fixtures, focused validation, and manual closeout evidence.

## Forbidden Scope

This packet and its validator must not add autonomous execution, a worker implementation, a worker loop, polling, scheduled execution, webhook-triggered execution, external queue provider integration, 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_controlled_worker_design_packet.py`.

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

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

The validator proves required sections, required boundary terms, valid and invalid fixture examples, forbidden implementation and mutation behavior, product-architecture discoverability, context-pack inclusion, and run_all wiring.