# Queue-Backed Multi-Agent Work Engine Evaluation V01

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

Related references:

- [#274 Tool-agnostic invariant-driven agent operating model](https://github.com/pinklon/ai-capability-discipline/issues/274)
- [#275 Artifact consistency audit and propagation workflow](https://github.com/pinklon/ai-capability-discipline/issues/275)
- [#277 Backlog triage dependency and supersession workflow](https://github.com/pinklon/ai-capability-discipline/issues/277)
- [#285 OKF-compatible bundle and derived retrieval index architecture](https://github.com/pinklon/ai-capability-discipline/issues/285)
- [#286 Google New SDLC candidate-source evaluation](https://github.com/pinklon/ai-capability-discipline/issues/286)
- [#269 Source Registry Admin Layer v01](https://github.com/pinklon/ai-capability-discipline/issues/269)

## Governance Boundary

This artifact is an architecture evaluation and operating-model note. It is not a queue engine, queue worker, autonomous polling agent, webhook loop, scheduled execution loop, custom database, Linear integration, Jira integration, MCP server implementation, runtime behavior change, Production change, Preview change, Cloudflare Access/WAF change, provider/model configuration change, source activation, package authority change, or bypass of GitHub issue/PR governance.

The recommendation here is intentionally conservative: use GitHub Issues and pull requests as the default near-term durable queue/state substrate, and treat Linear, Jira, custom databases, OKF projections, and MCP tools as future adapters unless a later owner-approved issue justifies and implements them.

## Problem

The repo already uses issues, branches, pull requests, receipts, validation results, generated artifacts, and closeout evidence as durable work state. That is a lightweight queue-backed work model, but it is implicit. As more agent-assisted work routes through tool-agnostic roles, backlog triage, artifact consistency audits, candidate-source evaluations, and future retrieval/index work, the repo needs a clear answer to whether a queue-backed, stateful, auditable multi-agent work engine belongs in the architecture.

The question is not whether to create autonomous agents now. The question is how to model future delegated work so structured payloads, state transitions, locks, human gates, receipts, validation evidence, and issue/PR governance remain explicit before any heavier orchestration layer is considered.

## Decision Drivers

- Preserve GitHub issue and PR governance as the human-readable control plane.
- Keep agent work invariant-driven and tool-agnostic, as defined by #274.
- Keep artifact consistency and controlled propagation review explicit, as defined by #275.
- Keep backlog triage, dependency, supersession, blocked, ready, deferred, and needs-clarification states coherent, as defined by #277.
- Keep OKF, database, vector, and MCP layers as future projections or tools, not authority, as defined by #285.
- Preserve #286's distinction between ad-hoc prompting and governed agentic engineering.
- Keep #269 as a future source-administration dependency only, not as a queue implementation.
- Avoid uncontrolled autonomous loops, duplicate execution, stale claims, hidden agent coupling, and evidence-free state mutation.

## Recommendation

Adopt the queue-backed work engine pattern as a future operating-model architecture pattern, but do not implement a production queue engine now.

Near-term default:

```text
GitHub issue = durable work item and human-readable queue entry
Issue labels/body/comments = explicit state, constraints, and evidence trail
Branch = scoped execution workspace
Pull request = review, validation, and merge gate
Validation receipt = durable closeout evidence
Human owner = approval authority for high-risk state transitions
```

Future target:

```text
Structured work payload
  -> GitHub issue or future adapter ticket
  -> state machine with explicit transitions
  -> scoped agent claim with lock/lease metadata
  -> repo-local execution branch
  -> receipts, artifacts, validation evidence, and PR review
  -> human approval gates
  -> done, deferred, blocked, failed, cancelled, or follow-up issue
```

GitHub Issues/PRs should remain the default near-term substrate because they already provide review history, branch and PR linkage, issue references, comments, labels, permissions, audit trail, and close semantics. Linear, Jira, and custom databases should be treated as future adapters unless a later issue proves GitHub cannot support a specific required state or evidence property.

## Prompt Mode Versus Work Mode

| Mode | Description | Repo posture |
|---|---|---|
| Prompt mode | Imperative conversational request and response. The operator supplies context, constraints, and next steps inside a chat. | Useful for exploration, but too ephemeral for auditable multi-agent execution. |
| Work mode | Declarative structured payload with objective, constraints, dependencies, approval gates, state transitions, validation commands, receipts, and definition of done. | Preferred for durable delegated work, issue-backed execution, and future queue/state-machine orchestration. |

Prompt mode may create a candidate plan. Work mode should own execution. A work item is not ready for agent execution until the objective, constraints, forbidden zones, validation, human gates, and closeout evidence are explicit enough to prevent guessing.

## Component Relationship

| Component | Role | Boundary |
|---|---|---|
| Prompt mode | Human-agent interaction for exploration, planning, clarification, or closeout. | Does not by itself create durable authority or execution approval. |
| Work mode | Structured execution contract for issue-backed work. | Requires explicit payload, constraints, acceptance criteria, and evidence expectations. |
| Ticket payload | Declarative work item carried by issue body, frontmatter, JSON block, or future OKF concept. | Must remain reviewable in GitHub even if projected elsewhere. |
| Queue/state machine | Durable state representation for work item lifecycle. | Near-term default is GitHub Issues/PRs, not an external queue service. |
| Agent worker | Scoped executor that claims a work item and performs allowed actions. | Future concept only in this issue. No worker, poller, webhook, or loop is implemented. |
| Human approval gates | Required control points for risky transitions and irreversible mutations. | Owner approval remains outside agent autonomy. |
| Receipts and validation evidence | Durable proof for state transitions, PR readiness, closeout, rollback, or failure. | Must attach to issue, PR, committed receipt, or linked artifact. |

## Candidate State Model

| State | Meaning | Required evidence |
|---|---|---|
| `ready` | Work item is complete enough for scheduling, but not yet assigned to an execution slot. | Issue has objective, constraints, labels, acceptance criteria, non-goals, and dependency status. |
| `queued` | Work item is intentionally placed in an execution queue or batch. | Queue marker, priority, target execution surface, and dependency check. |
| `claimed` | A human or agent has acquired the item for bounded work. | Claim actor, timestamp, branch expectation, lease duration, and stale-claim rule. |
| `agent-working` | Claimed work is actively being executed. | Active branch, current plan, touched scope, and latest progress receipt or comment. |
| `needs-input` | Work cannot proceed without owner clarification or missing context. | Exact question, blocked decision, attempted deterministic probes, and no-guessing statement. |
| `blocked` | Work is stopped by an external dependency, failed gate, unavailable permission, or missing prerequisite. | Blocker, owner or system needed, affected acceptance criteria, and resume condition. |
| `review-ready` | Work is implemented and ready for human review. | PR, diff summary, validation results, residue scan, boundary confirmations, and known limitations. |
| `done` | Work is merged or otherwise closed according to issue close semantics. | Merge commit or closure evidence, final receipt, validation evidence, and issue/PR linkage. |
| `failed` | Work ended unsuccessfully and needs triage. | Failure mode, logs or validation output, rollback status, residue state, and recommended next action. |
| `deferred` | Work is intentionally postponed. | Deferral reason, dependency, revisit condition, and owner decision if required. |
| `cancelled` | Work should not proceed. | Cancellation actor, reason, and confirmation that no active branch, lock, or worker remains. |

## Transition Rules

| From | To | Allowed actor | Required evidence | Human approval |
|---|---|---|---|---|
| `ready` | `queued` | Owner, Backlog Triage Agent with approval, or maintainer | Dependency review and queue rationale | Required when priority or sequencing changes active work. |
| `queued` | `claimed` | Repo-local executor, approved agent worker, or maintainer | Claim metadata, lease, branch name, and execution surface | Not required for routine docs/issues if already queued. |
| `claimed` | `agent-working` | Claim holder | Current plan, scope, and no-conflict check | Required if work expands beyond approved scope. |
| `claimed` | `queued` | Owner, maintainer, or claim holder | Claim release reason and residue check | Not required when voluntarily releasing stale-free work. |
| `agent-working` | `needs-input` | Claim holder | Exact missing input and deterministic probes attempted | Required to resume if answer changes scope. |
| `agent-working` | `blocked` | Claim holder or auditor | Failed gate, unavailable dependency, or permission boundary | Required to override a hard blocker. |
| `agent-working` | `review-ready` | Claim holder | PR, validation, receipts, diff summary, and boundary confirmations | Required before merge or protected artifact promotion. |
| `review-ready` | `done` | Human reviewer or authorized merge actor | Review approval, merge commit, final validation, closeout receipt | Required. |
| `review-ready` | `agent-working` | Reviewer or claim holder | Requested changes and retained lock or renewed lease | Required if requested change expands scope. |
| Any active state | `failed` | Claim holder, auditor, or maintainer | Failure evidence, rollback status, and follow-up recommendation | Required to retry high-risk work. |
| Any non-terminal state | `deferred` | Owner or backlog triage with approval | Deferral reason and revisit condition | Required. |
| Any non-terminal state | `cancelled` | Owner | Cancellation reason and cleanup proof | Required. |

Terminal states are `done`, `failed`, `deferred`, and `cancelled` unless a later owner-approved issue defines reopen semantics.

## Actor And Tool Boundaries

| Actor/tool | Allowed actions | Forbidden actions without explicit approval |
|---|---|---|
| Human owner | Approve scope, priority, high-risk transitions, merge, cancellation, and external integrations. | None inside repo governance, but owner decisions still require receipts for operational claims. |
| Planner | Inspect, classify, propose options, state risks, define acceptance checks. | File mutation, runtime mutation, queue mutation, merge, source activation. |
| Executor | Implement approved scoped changes, run validation, create branch and PR when authorized. | Scope expansion, runtime/source/provider/MCP changes, autonomous loops, external queue integration. |
| Auditor | Review diffs, receipts, invariants, validation, state transitions, and closeout evidence. | Mutating controlled artifacts or issue state without approval. |
| Backlog Triage Agent | Recommend labels, dependencies, supersession, blocked/ready/deferred classification, and execution order. | Closing, relabeling, reprioritizing, or bulk mutation without approval. |
| Future agent worker | Claim, execute, update state, and emit receipts within a bounded work payload. | Polling, webhook execution, scheduled loops, cross-agent delegation, runtime mutation, database writes, or MCP mutation unless separately approved. |
| Future MCP tools | Could expose controlled queue read/update tools with transition validation. | This issue does not add or modify MCP server behavior. |

## Lock And Lease Semantics

A future queue/state substrate needs locks because duplicate agents can otherwise execute the same issue, push conflicting branches, or emit contradictory receipts.

Minimum lock fields:

```json
{
  "lock_id": "aicd-287-example-lock",
  "work_item_id": "github-issue-287",
  "claimed_by": "codex-local-repo-executor",
  "claimed_at": "2026-06-27T00:00:00Z",
  "lease_expires_at": "2026-06-27T02:00:00Z",
  "branch": "docs/example-branch",
  "base_commit": "937e1f48db1bd8fa92112628d30f244629ff7209",
  "state": "claimed",
  "renewal_count": 0,
  "stale_after_minutes": 120
}
```

Rules:

- A work item may have only one active claim unless explicitly split into child issues.
- A claim must record actor, execution surface, branch, base commit, timestamp, lease expiry, and stale-claim rule.
- A claim holder must renew or release the lease before expiry when work continues.
- A stale claim may be reclaimed only after evidence shows no active work, no open PR conflict, and no uncommitted repo residue.
- Reclaiming a stale claim must create a receipt or issue comment describing the abandoned claim and chosen resume point.
- Lock metadata must never replace Git history, PR review, validation receipts, or owner approval.

## Structured Work-Item Payload Schema

The near-term schema should be representable inside a GitHub issue body as fenced JSON or YAML frontmatter. A later OKF-compatible bundle could project the same payload into concept files, but GitHub remains the human-readable control plane.

Recommended JSON sketch:

```json
{
  "schema": "aicd.work_item.v0.1",
  "work_item_id": "github-issue-287",
  "title": "Evaluate queue-backed multi-agent work engine and state-machine orchestration v01",
  "objective": "Evaluate whether queue-backed stateful multi-agent work belongs in the repo architecture.",
  "requesting_actor": "owner",
  "owner": "repo-maintainer",
  "assigned_execution_surface": "codex-local-repo-executor",
  "repository": "pinklon/ai-capability-discipline",
  "repo_path": "<local checkout path>",
  "base_branch": "main",
  "target_branch": "docs/queue-backed-agent-work-engine-eval-v01",
  "source_artifacts": [
    "docs/product-architecture/tool_agnostic_invariant_driven_agent_operating_model_v01.md",
    "docs/product-architecture/artifact_consistency_audit_propagation_workflow_v01.md",
    "docs/product-architecture/backlog_triage_dependency_supersession_workflow_v01.md",
    "docs/product-architecture/okf_derived_retrieval_index_architecture_v01.md",
    "docs/product-architecture/google_sdlc_vibe_coding_candidate_evaluation_v01.md"
  ],
  "dependencies": ["#274", "#275", "#277", "#285", "#286"],
  "future_dependencies": ["#269"],
  "constraints": [
    "do not implement a production queue engine",
    "do not integrate Linear or Jira",
    "do not create queue workers",
    "do not add polling, webhook, or scheduled loops",
    "do not change runtime, source, provider, package, Cloudflare, or MCP behavior"
  ],
  "state_model": ["ready", "queued", "claimed", "agent-working", "needs-input", "blocked", "review-ready", "done", "failed", "deferred", "cancelled"],
  "definition_of_done": [
    "architecture note added",
    "discoverability updated",
    "validation passed",
    "draft PR opened",
    "no merge without explicit owner instruction"
  ],
  "validation_commands": [
    "python3 -B scripts/build_context_pack.py",
    "python3 -B validation/scripts/check_queue_backed_agent_work_engine_evaluation.py",
    "python3 -B validation/scripts/run_all.py"
  ],
  "required_receipts": [
    "diff summary",
    "validation results",
    "residue scan",
    "boundary confirmations"
  ],
  "risk_class": "operating-model-architecture",
  "approval_gates": [
    "plan confirmation before edits",
    "human PR review before merge",
    "separate owner approval for any runtime, external queue, worker, database, MCP, or source activation work"
  ],
  "lease": {
    "duration_minutes": 120,
    "stale_claim_rule": "reclaim only after no active PR conflict and no repo residue"
  },
  "retry_policy": "retry only after failure evidence is reviewed and a new claim or follow-up issue is approved",
  "rollback_expectations": "docs-only rollback through Git revert or follow-up PR; no runtime rollback needed",
  "output_artifact_contract": "architecture note, validation receipt, context-pack regeneration if registered as corpus input"
}
```

## Queue/State Substrate Comparison

| Substrate | Strengths | Limits | Recommendation |
|---|---|---|---|
| GitHub Issues/PRs | Already canonical for repo work, durable, reviewable, linkable to commits, labels, branches, PRs, receipts, and close semantics. | Labels and comments are weak state machinery unless conventions and validators are explicit. | Default near-term substrate. |
| Linear | Strong product queue UX, assignment, cycles, and state workflows. | Adds external dependency, parallel authority surface, API integration, and migration burden. | Future adapter only. |
| Jira | Strong enterprise workflow, audit, custom fields, and permissions. | Heavy operational burden, schema drift risk, and not the repo's current governance surface. | Future adapter only if enterprise workflow requires it. |
| Custom DB | Strong control over state model, locks, leases, queries, and worker coordination. | Highest implementation and authority risk, requires hosting, backups, auth, migrations, and reconciliation with GitHub. | Reject near-term. Reconsider only as derived projection or later orchestrator substrate. |

The analysis does not justify moving away from GitHub now. GitHub already satisfies the repo's most important governance properties: human-readable issue intent, PR review, commit linkage, validation receipts, labels, and closeout evidence. The missing pieces are structured payload conventions, explicit state transition rules, lock/lease semantics, and validation, not a new queue provider.

## OKF And MCP Future Interaction

OKF-compatible bundles could later represent work payload concepts, state definitions, approval gates, controlled resource identifiers, and artifact relationships. OKF should describe the static semantic contract for work items, not execute work.

MCP could later expose controlled queue read/update tools, but only after a separate issue defines strict transition validation, identity, permissions, receipts, and failure behavior. A future MCP tool must not make dynamic queue output package authority unless the output is captured, reviewed, committed, and validated through Git-controlled artifacts.

Recommended layering:

```text
GitHub issue/PR = near-term queue and approval control plane
OKF-compatible work concept = future static semantic payload projection
MCP queue tools = future controlled mutation/read interface
Database or tracker adapter = future derived state projection or integration path
Git commit, PR, receipt = durable authority and closeout evidence
```

This issue implements none of those future layers.

## Relationship To Existing Work

| Issue | Lesson incorporated |
|---|---|
| #274 | Queue-backed work must preserve tool-agnostic roles, invariant-driven execution, execution-surface classification, and the rule that the human owner must not become the execution engine. |
| #275 | State transitions and architecture decisions must trigger artifact consistency review when controlled artifacts may drift. |
| #277 | Queue state must align with backlog triage concepts such as ready, blocked, deferred, needs-clarification, dependency, supersession, and close semantics. |
| #285 | OKF, database, vector, and MCP layers should remain generated projections or controlled future tools. Git remains canonical. |
| #286 | Agentic engineering requires context, harnesses, evals, trajectory evidence, review, and observability. Queue-backed orchestration is not a license for autonomous loops. |
| #269 | Source Registry Admin Layer remains a future dependency for source operations only. It is not required to evaluate or implement queue-backed work state. |

## Risk Analysis

| Risk | Control |
|---|---|
| Race conditions between agents | Single active claim per work item, branch/base commit metadata, and stale-claim rules. |
| Stale locks and abandoned work | Lease expiry, renewal evidence, reclaim receipt, and residue scan. |
| Duplicate execution | Claimed state must be visible on the issue or queue substrate before work begins. |
| Hidden agent-to-agent coupling | Communicate only through structured work items, receipts, branches, and PRs. |
| Schema drift across tools | Keep GitHub issue payload as the human-readable source and validate required fields. |
| Payload-size limits | Keep compact issue payload plus links to committed artifacts and receipts. |
| Comment sludge | Require state transition summaries and committed receipts for durable evidence. |
| Unauthorized mutation | Human approval gates for external providers, runtime, sources, MCP, databases, merges, and protected artifacts. |
| Uncontrolled loops | No polling, webhook, scheduled, recursive, or cross-agent execution loops without separate approval. |
| Cascading loop failures | No loop-of-loops architecture in the near term. Future loops require kill switches, leases, budgets, and failure isolation. |
| Source authority confusion | Ticket references do not promote sources or package authority. Source lanes stay separate. |
| Human approval bypass | Review-ready to done requires human review or explicit authorized merge instruction. |
| Observability gaps | Require validation results, receipts, diff summaries, branch/commit evidence, and closeout reports. |
| Cost and token amplification | Prefer structured payloads, bounded context packs, and deterministic validators over repeated broad context reconstruction. |

## Human Approval Gates

Allowed without further approval:

- analyze queue-backed architecture
- compare queue/state substrates
- propose work-item schema
- propose state transition rules
- propose lock/lease semantics
- create docs-only architecture notes and validation receipts inside an approved issue scope

Requires explicit approval:

- adding an external queue provider
- integrating Linear or Jira APIs
- creating a custom database
- creating persistent queue workers
- adding autonomous polling, webhook, or scheduled loops
- enabling agent-to-agent execution loops
- changing issue/PR closeout semantics
- mutating Production or Preview runtime behavior
- changing Cloudflare Access/WAF
- changing provider/model configuration
- changing source registry posture
- enabling new sources
- changing package authority
- adding or modifying MCP server behavior
- applying `codex-automerge`
- merging a PR

## Validation Strategy

Near-term docs-only validation should confirm:

- architecture note contains the governance boundary, recommendation, state model, transition rules, actor boundaries, lock/lease semantics, payload schema, substrate comparison, OKF/MCP future relationship, and risk analysis
- product architecture README and HTML index link the note
- context-pack builder includes the note only when intended as controlled corpus input
- generated `context-pack/` and `docs/context-pack/` outputs are regenerated after corpus registration
- `run_all.py` includes the focused validator
- final receipt records validation results, residue scan, generated artifact changes, and boundary confirmations

Future implementation validation, if separately approved, would also need state-transition tests, stale-lease tests, duplicate-claim tests, permission-boundary tests, failed-transition tests, and audit-log tests. Those are not implemented here.

## Follow-Up Child Issues

Do not create these automatically from #287 unless the owner approves.

1. Define a compact GitHub issue frontmatter/JSON payload convention for future work-mode tickets.
2. Add a read-only queue-state lint that classifies issue readiness without mutating GitHub.
3. Evaluate whether labels or issue-body fields should carry `ready`, `queued`, `claimed`, `needs-input`, `blocked`, `review-ready`, `deferred`, and `cancelled` states.
4. Evaluate an OKF-compatible work-item concept model after OKF exporter work exists.
5. Evaluate a future MCP queue resource/tool interface with strict transition validation.
6. Revisit Linear, Jira, or database adapters only after GitHub substrate limits are evidenced.

## Boundary Confirmations

This issue confirms:

- no production queue engine is implemented
- no queue worker is implemented
- no autonomous polling agent is implemented
- no webhook loop is implemented
- no scheduled execution loop is implemented
- no Linear or Jira integration is implemented
- no custom database is implemented
- no MCP server behavior is added or modified
- no Production runtime behavior is changed
- no Preview runtime behavior is changed
- no Cloudflare Access/WAF behavior is changed
- no provider/model configuration is changed
- no source is enabled
- no package authority is changed
- no GitHub issue/PR governance is bypassed
- no `codex-automerge` is applied by this architecture note
- no merge is authorized by this architecture note

## Final Recommendation

Treat the queue-backed multi-agent work engine as a valid future architecture pattern, but keep the repo on GitHub Issues/PRs as the default substrate now. The repo should formalize structured work payloads, explicit state transitions, lock/lease semantics, human approval gates, and receipt requirements before considering workers, external trackers, databases, or MCP queue tools.

The right next step is not a production queue engine. It is a governed work-mode contract that makes today's issue/PR workflow precise enough to support future adapters without weakening human control.