issue-to-pr git:20260723.6e5370bA

Immutable. This exact content is served forever at /api/v1/blob/27a4c8fb5e5f4bf2.

---
name: issue-to-pr
description: Govern a scafld-backed issue-to-PR lane with native scafld review and handoff surfaces.
runx:
  category: code
---

# Issue to PR

Drive one bounded thread-driven change through the scafld 2.4-compatible
lifecycle and package the result as a provider-agnostic draft pull-request
packet.

The graph separates cognition from mutation. Agent phases author the scafld
markdown spec and the bounded repo change bundle. Deterministic `fs.write` and
`fs.apply_bundle` phases are the only places files are written to disk. scafld
owns the workflow kernel: `plan`, `validate`, `approve`, `build_to_review`,
`status`, `review`, `complete`, and `handoff`. runx owns the explicit authoring
boundaries, deterministic writes, receipts, and final outbox packaging.

Branch creation and provider PR mutation are outside scafld. The caller or
adapter prepares the branch, then passes the intended branch into this lane.
The lane records that branch in the draft PR packet, and the GitHub adapter
fails closed if the workspace checkout does not match it. The final
`issue-to-pr-push-outbox` step is the only provider push boundary.

## Lifecycle

The graph runs:

`scafld plan` -> read the CLI-owned draft -> complete its markdown body ->
write spec -> read spec -> validate -> approve -> read approved spec -> read declared files -> author fix bundle ->
write fix bundle -> build to review -> status -> read current branch -> review
-> complete -> final status -> handoff -> package draft PR outbox -> adapter
push.

There are no translation projection steps. `scafld handoff` is the human handoff
surface, `build_to_review` drives bounded native `scafld build` advances until
the task is review-ready, and `scafld review` is the native review boundary.

## Thread Story

The lane should leave one coherent source-thread story, not a stream of every
internal event. The durable milestones are:

- source signal and the bounded request
- accountable decision that a PR is justified
- scafld spec approval and declared scope
- build and validation result
- adversarial review result
- draft PR publication
- human merge gate
- final provider outcome when observed

Comments and PR bodies should summarize those gates with enough evidence for a
reviewer to act. They must not publish raw local paths, secrets, full command
dumps, or duplicate retry comments. User-facing labels should use plain terms
such as spec authoring, fix authoring, review, and human merge gate.


## Spec Authoring Contract

The `issue-to-pr-author-spec` boundary must emit a full scafld
2.4-compatible markdown document, not YAML and not a reduced project brief.
`scafld plan` is the sole owner of lifecycle front matter. The graph reads that
exact draft and supplies it as `planned_spec_contents`; the author must preserve
the complete front-matter block exactly and complete only the markdown body.
It must never synthesize, normalize, repair, or reorder lifecycle fields.
Keep the CLI-created top-level title; add the required sections beneath it.

It must also emit `context_files`, a deduplicated array of at most sixteen
concrete repo-relative paths whose current contents are needed to implement the
spec. This is bounded authoring evidence, not a projection of scafld state.
Include the relevant files from `repo_snapshot.recommended_files`, the smallest
production targets, and targeted tests when they exist. Native
`fs.read_bundle` hydrates this list; no Runx tool parses the spec Markdown or
guesses file ownership from prose.

The body must include the standard scafld 2 sections: Current State, Summary,
Context, Objectives, Scope, Dependencies, Assumptions, Touchpoints, Risks,
Acceptance, at least one Phase section, Rollback, Review, Self Eval,
Deviations, Metadata, Origin, Harden Rounds, and Planning Log.

`scafld validate` is the only schema gate after the deterministic write. If the
author changes the CLI-owned header, validation must fail rather than a Runx
tool guessing how to repair it.

All changed-file declarations must use concrete repo-relative paths in
backticks under Context / Files impacted and Phase / Changes. Do not declare
scafld-managed control-plane artifacts under `.scafld/specs`,
`.scafld/reviews`, `.scafld/runs`, or old `.ai` governance paths as repo-change
scope.

Documentation and process requests still need a concrete repo file. Prefer
existing docs surfaces supplied by `repo_snapshot.existing_files` or
`repo_context`, and declare at least one non-governance repo file for an
approved `issue-to-pr` lane. Do not leave the repo-change scope empty after the
decision layer has approved a PR.

Validation commands must run against the current workspace state after the fix
bundle is written. Do not depend on git history ranges such as `HEAD~1` or
merge-base comparisons. Validation commands, when present, must be direct
repo-local checks such as test, lint, build, or file-content commands. Never use
runx runtime internals or `graph/scafld/tools/scafld-cli.mjs` as a validation command;
scafld is already the lifecycle runner around the task.

For any code change, the approved spec must declare at least one targeted
test/spec file in the changed-file scope and include at least one executable
validation command that exercises that target. This applies even when the source
thread does not explicitly request coverage; code PRs are not publishable from
this lane without targeted test/spec scope or grounded scafld validation
evidence. If the source thread asks for tests, specs, regression coverage,
focused coverage, or request/service coverage, the targeted coverage requirement
cannot be softened to a generic smoke check. If no existing test/spec path is
declared but the repository layout makes a conventional path inferable, declare
that new test/spec file. If no grounded test/spec path or command can be
inferred from the repo snapshot, stop with a missing-evidence reason instead of
publishing a code-only PR.

Preserve source-thread context in the spec's Summary, Origin, and Planning Log
so later PR packaging can explain why the lane ran and what evidence justified
the mutation. Return the exact written document as `spec_contents` and the
bounded evidence paths as `context_files`.

## Fix Authoring Contract

The `issue-to-pr-apply-fix` boundary must emit a bounded `fix_bundle` with
`files: [{ path, contents }]` for every repo file needed to satisfy the approved
spec. For documentation or process changes, the approved spec, source thread,
repo snapshot, repo context, and declared file contents are sufficient when they
identify a narrow edit.

When `repo_snapshot.recommended_files` contains concrete repo-relative files,
treat those files as actionable target evidence even if the generated spec is
worded conservatively. Read the recommended file and the nearest relevant test
or spec before blocking. If the source thread includes a runtime exception,
backtrace, failing command, or named behavior and the recommended file exists,
prefer the smallest conventional fix plus targeted regression coverage over an
empty bundle.

For any production code change, `fix_bundle.files` must include the smallest
production fix and a targeted test/spec file, even when the source request does
not explicitly ask for coverage. Do not publish a code-only fix bundle from this
lane. If the approved spec, source thread, or acceptance criteria asks for
tests, specs, regression coverage, focused coverage, or request/service
coverage, the targeted test/spec file must directly cover that requested
behavior. If no test file exists, create the narrow conventional test file when
the repository structure makes that path inferable; otherwise block with the
missing path and evidence reason.

If a declared file has `exists: false` and the approved spec intentionally
creates it, write the new file when the desired contents are inferable from the
spec and thread. Do not block solely because the file has no prior contents.

Return `fix_bundle.status: blocked` with `files: []` only when no concrete
repo-relative target is declared, a required existing file cannot be read, or
the requested behavior cannot be inferred after inspecting the supplied target
files. The blocked reason must name the missing evidence and path because an
empty file bundle is a terminal policy denial before `write-fix`.

## Inputs

- `task_id`: scafld task id.
- `thread_title`: canonical title and default spec title.
- `thread_body`: full thread body or request text when available.
- `thread_locator`: canonical locator for the bounded thread.
- `thread`: portable thread for the current signal surface.
- `outbox_entry`: existing pull-request outbox entry when refreshing a draft.
- `harness`: optional `runx.harness.v1` packet for the governed run boundary.
- `signal`: optional `runx.signal.v1` packet. Preserve source references,
  fingerprint, authenticity, and evidence references as stateful context
  instead of reparsing source-thread prose.
- `decision`: optional `runx.decision.v1` packet. Preserve the accountable
  selection rationale, selected act, and closure when the caller already made
  the lane decision.
- `target_repo`: intended repository slug for PR packaging.
- `operational_policy`: optional `runx.operational_policy.v1` packet used to
  admit the source, target repo, runner, and source-thread route before PR
  packaging.
- `source_id`: optional operational policy source id.
- `runner_id`: optional operational policy runner id.
- `repo_snapshot`: compact structured snapshot of the target repo.
- `repo_snapshot_path`: optional path to a fuller repo snapshot artifact.
- `repo_context`: textual summary of repo shape and validation hooks.
- `size`: scafld size, default `small`.
- `risk`: scafld risk, default `low`.
- `base`: base ref for PR packaging, default `main`.
- `fixture`: workspace root containing `.scafld`.
- `scafld_bin`: explicit scafld executable path.
- `provider`, `provider_command`, `provider_binary`, `model`: optional native
  scafld review provider overrides.

## Structured Output

On success, the lane emits:

- `draft_pull_request`: provider-agnostic PR draft state derived from scafld
  handoff, build, review, completion, status, and current git branch.
- `outbox_entry`: a `pull_request` outbox entry suitable for adapter push.
- `push`: adapter push result plus refreshed `thread` when the adapter supports
  push.
- Story metadata suitable for one source-thread reviewer update that summarizes
  the lifecycle gates and points at the human merge decision.

## Agent task contracts

### `issue-to-pr-author-spec`

Complete the draft created by scafld plan as a scafld 2.4-compatible markdown spec.
Use thread_title, thread_body, thread_locator, thread, outbox_entry, target_repo, repo_snapshot,
repo_snapshot_path, and repo_context to keep the spec grounded in the actual request and
repository. Treat planned_spec_contents as the exact scafld-owned source document: preserve its
entire front-matter block byte-for-byte, do not add, remove, reorder, normalize, or repair any
lifecycle field. Preserve the CLI-created top-level title and complete the markdown body below it. The body must include Current State, Summary, Context,
Objectives, Scope, Dependencies, Assumptions, Touchpoints, Risks, Acceptance, at least one Phase
section, Rollback, Review, Self Eval, Deviations, Metadata, Origin, Harden Rounds, and Planning
Log. Declare changed repo files in Context / Files impacted and Phase / Changes using concrete
repo-relative paths in backticks. Do not declare scafld-managed control-plane artifacts under
.scafld/specs, .scafld/reviews, .scafld/runs, or old .ai governance paths as repo-change scope.
Validation commands must be executable in the current workspace after the fix bundle is written.
Do not depend on git history ranges such as HEAD~1. When validation commands are included, use
direct repo-local checks such as tests, lint, build, or file-content commands. Do not use runx
runtime internals or graph/scafld/tools/scafld-cli.mjs as validation commands; scafld is already the
lifecycle runner around this graph. For any code change, declare at least one targeted test/spec
file in Files impacted and Phase / Changes and include at least one executable validation
command that exercises that target. Do this even when the source thread does not explicitly
request coverage; code PRs are not publishable from this lane without either targeted test/spec
scope or grounded scafld validation evidence. When the source thread or acceptance criteria asks
for tests, specs, regression coverage, focused coverage, or request/service coverage, this
coverage requirement is mandatory and cannot be softened to a generic smoke check. If no
existing test/spec path is declared but the repository layout makes a conventional path
inferable, declare that new test/spec file. If no grounded test/spec path or command can be
inferred from the repo snapshot, stop with a missing-evidence reason instead of publishing a
code-only PR. If a required file path cannot be grounded from the thread or repository evidence,
keep the scope narrow and state the assumption instead of inventing a file. When the approved
lane is documentation or process work, prefer existing documentation surfaces from
repo_snapshot.existing_files or repo_context, and declare at least one non-governance repo file;
issue-to-pr is a PR lane, so an approved spec must not leave the repo-change scope empty.
Preserve source-thread context in Summary, Origin, and Planning Log so the eventual reviewer
story can explain why this lane ran and what evidence justified mutation. Return context_files as
a deduplicated array of at most sixteen concrete repo-relative files needed to implement the
approved scope. Include relevant repo_snapshot.recommended_files, production targets, and
targeted tests. The list is bounded read context, not scafld lifecycle state; do not include
governance artifacts or infer paths not grounded in repository evidence.

### `issue-to-pr-apply-fix`

Produce the bounded fix bundle described by the approved scafld 2 markdown spec. Use
repo_snapshot, repo_snapshot_path, repo_context, approved spec contents, current thread context,
and declared_file_context. Review declared_file_context.files and
declared_file_context.missing before deciding what to edit. This is the native
`fs.read_bundle` result with `{ repo_root, file_count, total_bytes, files, missing }`;
each present file has `{ path, contents, bytes, truncated, content_digest }`. Treat present
contents as already read source evidence, and use the allowed `fs.read` tool when the approved
spec requires another grounded file. `fix_bundle.files` must be an
array of { path, contents } entries covering every repo file needed to satisfy the approved
spec. For documentation or process changes, the approved spec, thread, repo_snapshot,
repo_context, and current declared file contents are sufficient when they identify a narrow
edit; do not return an empty bundle when one scoped docs edit is possible. For any existing
file, contents must be the complete current file with the smallest necessary edit applied;
preserve unrelated sections, headings, prose, tables, links, setup instructions, and ordering
exactly. Never replace an existing file with only the new section or a shortened summary. If a
declared file list is sparse but repo_snapshot.recommended_files contains concrete repo-relative
files, treat those recommended files as actionable target evidence. Read the recommended file
and the nearest relevant test or spec before blocking. When the source thread includes a runtime
exception, backtrace, failing command, or named behavior and a recommended file exists, prefer
the smallest conventional fix plus targeted regression coverage over an empty bundle. For any
production code change, fix_bundle.files must include both the smallest production fix and a
targeted test/spec file, even when the source request does not explicitly ask for coverage. Do
not publish a code-only fix bundle from this lane. When the approved spec, source thread, or
acceptance criteria asks for tests, specs, regression coverage, focused coverage, or
request/service coverage, the targeted test/spec file must directly cover that requested
behavior. If no test file exists, create the narrow conventional test file when the repository
structure makes that path inferable; otherwise block with the missing path and evidence reason.
If no fix is possible after inspecting the target paths, the blocked reason must name the exact
path and missing evidence. If a declared file has exists: false and the approved spec
intentionally creates it, write the new file when the desired contents are inferable from the
spec and thread. Do not widen scope. Do not hand-edit scafld lifecycle files. Return
fix_bundle.status: blocked with a reason and an empty files array only when no concrete
repo-relative target is declared, a required existing file cannot be read, or the requested
behavior cannot be inferred after inspecting the supplied target files without inventing
requirements; name the missing evidence and path in the reason because an empty bundle is a
terminal policy denial.