# GitHub Issues Work Payload Template V01

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

References:

- [#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)
- [#356 Implement GitHub Issues queue-backed agent work engine MVP v01](https://github.com/pinklon/ai-capability-discipline/issues/356)
- [PR #357 Implement GitHub Issues queue-backed agent work engine MVP v01](https://github.com/pinklon/ai-capability-discipline/pull/357)
- [#287 Queue-backed multi-agent work engine evaluation](https://github.com/pinklon/ai-capability-discipline/issues/287)
- [#277 Backlog triage dependency and supersession workflow](https://github.com/pinklon/ai-capability-discipline/issues/277)

## Purpose

This v01 follows PR #359 by adding the smallest repo-local GitHub issue-body work payload template after the read-only queue planner. The planner from PR #359 consumes deterministic committed fixtures. Before any live read-only export or GitHub inspection path exists, future issues need a stable issue-body shape that humans can author and validators can reason about.

The template solves a narrow problem: future work items need to express planner-readable metadata in the GitHub issue body without making the issue body an execution trigger. The template standardizes objective, parent issue, dependency state, required labels, execution surface, risk class, parallelism class, allowed files or domains, forbidden zones, validation commands, acceptance criteria, closeout receipt requirements, approval gates, lock and lease expectations, retry policy, rollback expectations, non-mutation boundaries, close semantics, and post-closeout next action classification.

## Relationship To The Work Engine MVP

The work engine MVP from PR #357 defined the state model, transition evidence, payload schema concepts, parallelism classes, claim locks, leases, planner lanes, and closeout proof requirements. This template turns the payload portion of that model into a concrete GitHub issue-body authoring surface.

The template does not replace GitHub Issues, PRs, branches, validation receipts, owner decisions, or closeout reports. It makes issue bodies less ambiguous so the existing work engine concepts can be represented consistently before any later export path or planner integration reads live issue content.

## Relationship To The Queue Planner

The read-only queue planner from PR #359 consumes committed deterministic fixtures and emits serial, safe-parallel, blocked, owner-decision, high-risk, lock-conflict, stale-lock, invalid-item, validation, closeout, and non-mutation report sections.

This template is the authoring contract that can later feed those fixture shapes. It does not parse live GitHub issues. It does not export live GitHub issue bodies. It does not call GitHub APIs. It does not mutate live GitHub issues or PRs. Live read-only export should come later through a separate owner-approved issue after the template has proven stable in committed examples.

## Payload Shape

The issue template includes human-readable sections and a fenced YAML structured payload block. The structured block is deterministic and planner-aligned, but it is still only field guidance. It is not policy and it is not an execution surface.

Required payload fields:

| Field | Requirement |
|---|---|
| `objective` | Concrete work outcome. |
| `parent_issue` | Parent, epic, source issue, or standalone rationale. |
| `dependencies` | Each dependency must include an explicit state. |
| `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` | Planner-aligned parallelism classifier. |
| `allowed_files_or_domains` | Exact file paths, directories, generated artifact families, or GitHub-only domains. |
| `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, lease, stale-lock, branch, and collision expectations. |
| `retry_policy` | Conditions for retry after failure. |
| `rollback_expectations` | Expected rollback or recovery posture. |
| `non_mutation_boundary` | Explicit proof that the template does not trigger mutation or execution. |
| `close_semantics` | What closes and what is only referenced. |
| `post_closeout_next_action` | Next action classification after closeout. |

## Safe Parallelism Support

Safe parallelism depends on precise work boundaries. The template requires issue authors to name allowed files or domains, forbidden zones, dependency states, validation commands, approval gates, and lock or lease expectations. That gives a future planner enough evidence to distinguish a safe-parallel item from serial-required work, blocked work, owner-decision work, high-risk gated work, and mutually exclusive file or runtime surfaces.

The template does not decide concurrency by itself. It records the fields a planner needs to make a conservative decision from committed data or a later read-only export.

## Owner Decision Gates

Owner decision gates remain explicit. If acceptance criteria, authority, dependency state, source authority, close semantics, or post-closeout next action is unclear, the issue should say `owner clarification required` and route to the owner-decision lane. The template preserves that route by requiring approval gates and post-closeout next action classification instead of letting missing information become an assumption.

## Non-Mutation Boundary

The template is a documentation and validation artifact. It does not mutate live GitHub issues or PRs, labels, milestones, assignees, comments, issue state, PR state, branches, source registries, Preview source sets, Production source sets, Cloudflare, provider/model configuration, runtime retrieval, browser-side retrieval, or package authority.

It does not add live GitHub issue export. It does not parse live GitHub issues. It does not trigger implementation work from template content. It does not add autonomous polling, a webhook loop, a scheduled loop, an external queue provider, Linear integration, Jira integration, a custom database, MCP behavior, OKF implementation, or Google SDLC implementation.

#269 remains closed. #271 remains closed. `codex-automerge` was not applied.

## Difference From Autonomous Execution

Autonomous execution starts work from a queue event, poller, webhook, scheduler, or external worker loop. This template does none of that. It only standardizes issue-body metadata so humans and repo-local validators can inspect whether future work is ready, blocked, high-risk, owner-gated, serial, or safe to parallelize.

Any future live read-only export, live issue parser, or controlled worker would need a separate issue, explicit approval, fixture coverage, validation, and closeout receipt before it exists.

## Fixture Coverage

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

- valid safe-parallel item
- valid serial-required item
- valid blocked-by-dependency item
- valid owner-decision-required item
- valid high-risk-gated item
- invalid missing required labels
- invalid missing objective
- invalid missing dependency state
- invalid missing validation commands
- invalid missing closeout receipt requirements
- invalid forbidden-zone omission
- invalid close semantics omission
- invalid post-closeout next action omission

## Validation Strategy

The focused validator proves that the issue template exists, required human-readable sections exist, a fenced structured payload example exists, the deterministic fixture exists, valid examples pass, invalid examples fail for the expected reasons, required labels match the allowed existing label set, constrained classifier values are enforced, dependency states are explicit, validation commands are required, acceptance criteria are required, closeout receipt requirements are required, forbidden zones are required, close semantics are required, post-closeout next action classification is required, and the non-mutation boundary is present.

The validator also statically checks that this v01 does not introduce live GitHub mutation, live GitHub export, autonomous execution, webhook behavior, external queue provider behavior, or protected source/runtime/provider surfaces.

## Post-Closeout Next Action

After this template lands, the next action remains an explicit owner decision point. A later issue may add live read-only export from GitHub issue bodies into committed fixtures, but that work should not start from this template and should not mutate GitHub issues or PRs.