# GitHub Issues Agent Work Engine MVP V01

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

References:

- [#277 Backlog triage dependency and supersession workflow](https://github.com/pinklon/ai-capability-discipline/issues/277)
- [#287 Queue-backed multi-agent work engine evaluation](https://github.com/pinklon/ai-capability-discipline/issues/287)
- [PR #290 Queue-backed agent work engine evaluation](https://github.com/pinklon/ai-capability-discipline/pull/290)

## Governance Boundary

This MVP defines repo-local mechanics for a GitHub Issues based queue and state-machine model. It is not an autonomous worker, polling loop, webhook-triggered execution loop, scheduled loop, external queue provider, Linear integration, Jira integration, custom database, MCP server behavior, runtime retrieval change, Cloudflare change, provider or model configuration change, browser-side provider call, browser-side current-source retrieval, source registry mutation, Preview source-set mutation, Production source-set mutation, package-authority change, OKF implementation, Google SDLC implementation, or source lifecycle action.

GitHub Issues and PRs remain the near-term durable queue substrate. Linear, Jira, custom databases, MCP queue tools, and OKF projections remain future adapters only unless a later owner-approved issue authorizes them.

## MVP Purpose

The current repo workflow already uses issues, PRs, branches, validation receipts, comments, and closeout reports as durable work evidence. The missing implementation layer is a repo-owned contract that answers these execution questions before work starts:

- What work is ready?
- What work is blocked?
- What work can run in parallel?
- What work must run serially?
- What work requires owner approval?
- Which agent or execution surface should handle it?
- What validation and receipts are required?
- What locks or leases prevent duplicate execution?
- What closeout proof is mandatory?

This MVP answers those questions through committed documentation, deterministic fixtures, and a focused validator. It does not execute work automatically.

## Work Item State Model

| State | Meaning | Required evidence |
|---|---|---|
| `ready` | Issue has enough objective, boundary, dependency, label, and acceptance detail to be scheduled. | Required labels, objective, dependencies, forbidden zones, validation commands, acceptance criteria, and closeout receipt requirements. |
| `queued` | Work is intentionally placed into an execution lane. | Queue rationale, execution surface, risk class, parallelism class, dependency classification, and owner approval if priority changes active work. |
| `claimed` | One actor has acquired the work item for bounded execution. | Claim actor, branch, base commit, lock id, claimed timestamp, lease expiration, and collision check. |
| `agent-working` | Claimed work is actively in progress. | Current plan, touched files or domains, progress receipt, latest validation status if available, and active lease. |
| `needs-input` | Work cannot proceed without owner clarification or missing context. | Exact question, deterministic probes attempted, no-guessing statement, and resume condition. |
| `blocked` | Work is stopped by dependency, permission, failed validation, collision, or unavailable prerequisite. | Blocker, affected acceptance criteria, required actor, and unblock condition. |
| `review-ready` | Work is implemented and ready for review. | Draft or ready PR, diff summary, validation results, residue scan, boundary confirmations, and issue label state. |
| `done` | Work is closed according to issue and PR semantics. | Merge or closure evidence, final validation receipt, issue/PR linkage, closeout proof, and residue state. |
| `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. | Owner or triage decision, deferral reason, revisit condition, and dependency link if applicable. |
| `cancelled` | Work should not proceed. | Owner cancellation, cleanup proof, and confirmation no active branch, PR, lock, or lease remains. |

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

## State Transition Model

| From | To | Required evidence | Approval gate |
|---|---|---|---|
| `ready` | `queued` | Dependency review, lane assignment, and queue rationale. | Required when priority or sequencing changes active work. |
| `queued` | `claimed` | Claim metadata, lock id, lease expiration, branch, base commit, and collision check. | Not required for already queued routine repo work. |
| `claimed` | `agent-working` | Confirmed plan, scoped files or domains, and active lease. | Required if scope expands beyond the issue. |
| `claimed` | `queued` | Claim release reason and residue check. | Not required for clean voluntary release. |
| `agent-working` | `needs-input` | Exact missing input and deterministic probes attempted. | Required to resume if the answer changes scope. |
| `agent-working` | `blocked` | Failed gate, unavailable dependency, collision, or permission boundary. | Required to override a hard blocker. |
| `agent-working` | `review-ready` | PR, validation, receipts, diff summary, label-state proof, and boundary confirmations. | Required before merge or protected artifact promotion. |
| `review-ready` | `done` | Review or authorized merge, merge commit or closure proof, final validation, and closeout receipt. | Required. |
| `review-ready` | `agent-working` | Requested changes and retained or renewed lease. | Required if requested changes expand scope. |
| any active state | `failed` | Failure evidence, rollback status, and next recommendation. | Required to retry high-risk work. |
| any non-terminal state | `deferred` | Deferral reason and revisit condition. | Required. |
| any non-terminal state | `cancelled` | Cancellation reason and cleanup proof. | Required. |

The validator fixture includes an invalid transition from `done` to `agent-working` to prove terminal-state protection.

## Work Payload Schema

Near-term payloads should be representable in a GitHub issue body as fenced JSON, YAML frontmatter, or a committed fixture. The human-readable GitHub issue remains the control plane.

Required schema fields:

| Field | Requirement |
|---|---|
| `objective` | Concrete work outcome. |
| `parent_issue` | Parent, epic, or `null` with standalone rationale. |
| `dependencies` | Blocking, informational, sequencing, supersession, and owner-decision dependencies. |
| `required_labels` | Existing repo labels required at issue creation. |
| `execution_surface` | `github-api-only`, `codex-local-repo-executor`, or `insufficient-execution-surface`. |
| `risk_class` | `routine-docs`, `governance`, `runtime-adjacent`, `source-governance`, or `high-risk`. |
| `parallelism_class` | Classifier output listed below. |
| `allowed_files_or_domains` | Exact file paths, directories, generated artifact families, or GitHub-only domains allowed for the work. |
| `forbidden_zones` | Explicit no-touch surfaces. |
| `validation_commands` | Deterministic commands required before review-ready or done. |
| `acceptance_criteria` | Checkable completion criteria. |
| `closeout_receipt_requirements` | Required closeout proof fields. |
| `approval_gates` | Owner or maintainer decisions needed before risky transitions. |
| `lock_lease` | Claim id, claimed by, branch, base commit, claimed timestamp, lease expiration, stale-after rule, and renewal count. |
| `retry_policy` | Conditions for retry after failure. |
| `rollback_expectations` | Expected rollback or recovery posture. |

## Parallelism Classifier

| Classifier result | Meaning | Required handling |
|---|---|---|
| `safe-parallel` | Work can run beside other active items because allowed files or domains do not overlap and no shared runtime/source surface is touched. | May be placed in the safe parallel lane after dependency and lock checks. |
| `serial-required` | Work touches shared files, generated mirrors, release artifacts, closeout semantics, or state that should not be changed concurrently. | Place in ordered serial lane. |
| `blocked-by-dependency` | Work depends on an open issue, unmerged PR, missing artifact, failed validation, or unavailable permission. | Place in blocked lane with unblock condition. |
| `owner-decision-required` | Work has unclear acceptance, ambiguous authority, priority tradeoff, or missing approval. | Place in owner decision lane. |
| `mutually-exclusive-file-runtime-surface` | Work collides with another active item on the same file family, runtime surface, source-set surface, or PR closeout surface. | Prevent duplicate claim and route to serial or blocked lane. |
| `high-risk-gated` | Work touches protected release, runtime, Cloudflare, provider/model, source registry, source set, browser-side retrieval, package authority, MCP behavior, external queue provider, or autonomous loop surfaces. | Requires explicit owner approval and high-risk gate evidence before claim. |

Classifier order is conservative: dependency blockers and owner decisions outrank safe parallelism, and high-risk gates prevent automatic execution.

## Claim Lock Lease Model

A work item may have only one active claim unless the owner explicitly splits the work into child issues.

Required lock fields:

```json
{
  "lock_id": "aicd-356-claim-001",
  "work_item_id": "github-issue-356",
  "claimed_by": "codex-local-repo-executor",
  "execution_surface": "codex-local-repo-executor",
  "branch": "codex/github-issues-agent-work-engine-mvp-v01",
  "base_commit": "739157c683246c86b04706bfb77d8462a881a8f5",
  "claimed_at": "2026-06-28T23:40:00Z",
  "lease_expires_at": "2026-06-29T01:40:00Z",
  "stale_after_minutes": 120,
  "renewal_count": 0,
  "state": "claimed"
}
```

Rules:

- A claim must be visible in issue, PR, fixture, or receipt evidence before work enters `agent-working`.
- A second claim on the same work item is invalid unless the existing claim is released, expired and recovered, or the owner splits the work.
- Stale lock recovery requires lease expiration, no active PR conflict, no uncommitted repo residue, and an abandoned-work recovery receipt.
- Lease renewal must preserve the same work item and claim holder unless ownership transfer is approved.
- Lock metadata never replaces Git history, PR review, validation receipts, or owner approval.

## Planner Output

The planner produces five lanes:

| Lane | Contents | Required output |
|---|---|---|
| ordered serial lane | Work classified as `serial-required` or colliding with shared surfaces. | Ordered list with reason and collision surface. |
| safe parallel lane candidates | Work classified as `safe-parallel`. | Candidate list with non-overlap evidence. |
| blocked lane | Work classified as `blocked-by-dependency`. | Blocker and unblock condition. |
| owner decision lane | Work classified as `owner-decision-required`. | Exact decision question and no-guessing statement. |
| high-risk gated lane | Work classified as `high-risk-gated`. | Gate reason and required owner approval. |

## Fixture Coverage

The deterministic fixture `validation/fixtures/github_issues_agent_work_engine_mvp_v01.json` covers:

- valid parallel work items
- conflicting work items
- missing labels
- missing dependencies
- stale lock
- owner approval required
- invalid state transition

The focused validator treats those fixtures as the executable contract for the MVP.

## Relationship To Existing Work

| Reference | How this MVP uses it |
|---|---|
| #277 | Reuses backlog triage concepts for required labels, dependencies, supersession, ready/blocked/deferred classification, and human approval gates. |
| #287 | Implements the repo-local mechanics that #287 evaluated: state model, payload schema, lock/lease rules, planner lanes, and validation. |
| PR #290 | Preserves the design-only boundary by implementing only docs, fixtures, and validation, not a queue worker, autonomous loop, external provider, custom database, MCP behavior, or runtime mutation. |

## Validation Strategy

The focused validator must prove:

- required states are present
- allowed and forbidden state transitions are enforced
- payload schema fields are present
- no-new-label rule is enforced against existing repo labels
- dependency and parallelism classification cases are deterministic
- lock/lease behavior detects stale and conflicting claims
- closeout receipt requirements are present
- run_all includes the focused validator
- context-pack registration and generated mirrors are present if the note is corpus-visible

## Boundary Confirmations

This MVP confirms:

- no autonomous worker loop was added
- no external queue provider was integrated
- no Linear or Jira integration was added
- no custom database was added
- no MCP server behavior was added or modified
- no source registry was mutated
- no Preview source set was mutated
- no Production source set was mutated
- no source was enabled, disabled, retired, promoted, or applied
- no Cloudflare CLI/API was used
- no Cloudflare Access/WAF change was made
- no provider/model configuration was changed
- no runtime retrieval semantics were changed
- no browser-side provider calls were added
- no browser-side current-source retrieval was added
- package authority was not changed
- OKF implementation was not started
- Google SDLC implementation was not started
- #269 remains closed
- #271 remains closed after authorized parent closeout
- `codex-automerge` was not applied

## Post-Closeout Next Action

After this MVP lands, the next action is an explicit owner decision point. Candidate follow-ups are:

1. Add a read-only issue-state lint that classifies live GitHub issues without mutating them.
2. Add an issue-body payload template for work-mode tickets.
3. Add a planner report command that reads committed fixtures or exported issue data and emits lane assignments.
4. Evaluate future adapters only after GitHub substrate limits are evidenced.

No follow-up should start automatically from this MVP.