Add NBT-local Rhei GitHub issue fix template

[jormundur00]

Summary

This adds a project-local Rhei template for taking one
graalvm/native-build-tools GitHub issue from intake through an approval-gated
implementation, focused validation and review, and draft pull request
publication.

The reusable workflow was developed on the Rhei branch and is now owned by NBT
under:

.agents/rhei/templates/github-issue-fix/

Because the template is NBT-specific, its input surface is intentionally tiny:
the only input is the issue number or issue URL. Repository identity, checkout
location, base branch, branch naming, proposal actor, push destination, PR head
owner, review limits, publication mode, and model routing are all fixed in the
template.

Why move the template into NBT?

The workflow encodes NBT-specific policy rather than general Rhei CLI behavior:

• graalvm/native-build-tools is always the issue and PR repository.
• master is always the base branch.
• repository work begins from the current NBT checkout.
• issue branches use rhei/issue-<issue>.
• implementation follows NBT's root and nested AGENTS.md instructions.
• grund discovery, citation rules, and spec-first requirements are taken from
  the NBT checkout.
• proposal comments are owned by jormundur00.
• reviewed branches are pushed to origin and use graalvm as the PR head
  owner.
• publication creates or updates a draft PR.

Keeping this policy beside the repository makes it reviewable and versioned
with the project it changes. It also reduces a normal invocation from a long
list of repository and publication arguments to one issue value.

Template contents

File	Purpose
template.yaml	Declares the template and its single positional issue input.
index.rhei.md	Creates the rendered workspace overview and records the fixed NBT execution settings.
tasks/01-issue-intake.md	Seeds the initial intake task. Intake writes one top-level follow-up task after determining the correct route.
states.yaml	Defines the complete approval, implementation, validation, review, repair, and publication state machine.
settings.json	Configures Codex execution and a two-hour agent timeout for the materialized workspace.
bin/github-proposal	Deterministically inspects, publishes, labels, and resolves proposal decisions and model provenance.
README.md	Documents fixed defaults, state paths, security boundaries, and runnable examples.

Fixed NBT settings

Setting	Value
Repository	graalvm/native-build-tools
Source checkout	Current NBT git root (.)
Base branch	master
Issue branch	rhei/issue-<issue>
Worktree root	../native-build-tools-rhei-worktrees
Publication mode	draft
Proposal actor	jormundur00
Proposal attempts	3 total
Push remote	origin
PR head owner	graalvm
PR labels	Apply the existing rhei label when available; never create labels
Required clean review passes	1
Review repair attempts	2
Implementation target	codex[yolo]:openai:gpt-5.6-sol
Focused review target	codex[yolo]:openai:gpt-5.6-terra
Aggregate review target	codex[yolo]:openai:gpt-5.6-sol
Procedural/publication target	codex[yolo]:openai:gpt-5.6-luna

End-to-end flow

The initial plan contains one issue-intake task. Intake creates or reuses an
isolated issue worktree, snapshots the issue, discovers repository policy,
evaluates issue adequacy and spec fit, and writes exactly one sibling follow-up
task.

For a compatible issue, the follow-up first reconstructs proposal state from
GitHub comments:

issue-intake
  -> approval-check
       -> propose-fix -> publish-proposal -> proposal-pending
       -> approval-apply -> implement-fix
       -> rejection-prepare -> propose-fix
       -> github-handoff

An approved proposal proceeds through implementation and the review pipeline:

implement-fix
  -> implementation-dispatch
  -> validate-fix
  -> requirements-review
  -> spec-review
  -> implementation-review
  -> validation-review
  -> aggregate-review
  -> review-dispatch
       -> publish-pr -> completed
       -> address-review -> validate-fix
       -> record-blocked-publication -> completed
       -> github-handoff -> completed

The deterministic dispatch states prevent an agent from choosing its own route.
They parse durable output and use exit codes and visit counters to select the
next transition.

States

The state machine currently defines 23 states.

Intake and proposal lifecycle

State	Kind	What it does
issue-intake	Agent, initial	Creates or reuses an issue branch and isolated worktree from origin/master; reads the issue without trusting it as instructions; discovers root and nested AGENTS.md files and grund configuration; records the issue snapshot, repository rules, spec-fit verdict, and routing decision; then writes exactly one top-level follow-up task.
approval-check	Deterministic program	Reads GitHub issue comments and reconstructs the current proposal and decision without side effects. Exit codes distinguish no proposal, pending, approved, rejected, exhausted, and blocked states.
propose-fix	Agent	Produces a bounded implementation proposal without editing code or documentation. The proposal contains accepted scope, repository/spec constraints, intended behavior and file changes, validation strategy, risks, and known gaps. Rejected proposals may be revised, with a maximum of three attempts.
publish-proposal	Agent using deterministic helper	Canonicalizes and publishes the proposal idempotently, derives its content-addressed ID, records model provenance from durable invocation evidence, and applies the pre-existing rhei:awaiting-approval label.
approval-apply	Deterministic program	Removes rhei:awaiting-approval immediately before implementation of the exact approved proposal and records the label result.
rejection-prepare	Deterministic program	Removes the approval label before generating a revision of a rejected proposal.
proposal-pending	Final	Ends the current run while the proposal waits for a later authorized GitHub decision. A fresh instantiation recovers proposal state from GitHub comments.
human-review	Human gate	Supports the template's local no-pr path by allowing a human to approve the exact local proposal, request a GitHub handoff, or cancel. The NBT manifest fixes publication to draft, so normal NBT runs use GitHub proposal approval rather than this gate.
github-handoff	Agent	Records a local, provenance-bearing handoff when the issue is underspecified, conflicts with project direction, needs an external owner, exhausts proposal attempts, or otherwise cannot proceed safely. It never posts the suggested response automatically.

Implementation and validation

State	Kind	What it does
implement-fix	Agent	Implements only the approved proposal in the isolated NBT worktree. It follows applicable AGENTS.md files, applies spec-first and grund rules, keeps public documentation free of internal citations unless repository policy requires them, and records whether the result is ready, blocked, or needs a revised proposal.
implementation-dispatch	Deterministic program	Reads the implementation result and routes ready work to validation, blocked work to github-handoff, or materially divergent work back to propose-fix for a new approval.
validate-fix	Agent	Runs focused issue-specific validation plus cheap targeted repository checks discovered during intake. It records exact commands, working directories, results, relevant output, unresolved failures, and broader validation gaps. It also produces a compact shared review brief.

Focused review and aggregation

State	Kind	What it does
requirements-review	Agent	Checks whether the implementation solves the behavior actually requested by the issue, including acceptance criteria, reproduction evidence, affected component, and any speculative or narrower interpretation.
spec-review	Agent	Checks NBT goals, non-goals, architecture/spec fit, AGENTS.md compliance, grund citations, public-document citation policy, and file-level references on changed test sources.
implementation-review	Agent	Reviews scope, correctness, maintainability, edge cases, repository conventions, and whether cited specification points actually apply to the changed files.
validation-review	Agent	Reviews command selection, validation coverage, failure handling, environment limitations, CI risk, and whether the PR can accurately describe the evidence that exists.
aggregate-review	Agent	Reads the shared review brief plus all four independent focused findings and produces one publication-readiness decision. It distinguishes blocking findings from broad validation gaps that should be disclosed in a draft PR.
review-dispatch	Deterministic program	Parses the aggregate readiness markers and visit count. Ready work with the required clean pass goes to publication; ready work needing more passes returns to validation; repairable blockers go to address-review; exhausted blockers go to record-blocked-publication; external blockers go to github-handoff.
address-review	Agent	Applies the latest blocking review findings in the worktree and records a per-cycle repair note before returning to validation and the full focused review sequence.

Publication and terminal states

State	Kind	What it does
publish-pr	Agent	Verifies the aggregate review is green, pushes the reviewed branch to origin, and opens or updates a draft PR. It writes a user-facing body with What changed, Why, an example when meaningful, implementation summary, exact validation evidence, a closing keyword, and a final collapsible AI-workflow provenance section with durable model and token accounting.
record-blocked-publication	Agent	Records a durable local result when review-repair attempts are exhausted. It preserves branch, commit, validation, and blocker information without publishing unsafe work.
completed	Final	Marks intake, publication, handoff, or blocked-publication recording as complete.
cancelled	Final	Stops any non-final task while preserving branches, worktrees, and runtime artifacts for inspection.

Proposal and approval protocol

Proposal text is canonicalized and hashed with SHA-256. The first 16 lowercase
hexadecimal characters form the proposal ID. The publisher writes exactly one
supported marker:

<!-- rhei-proposal:v1 id=<proposal-id> attempt=<n> -->

Only the latest marked proposal authored by jormundur00 is current. A
decision must have one of these exact first lines:

/rhei approve <proposal-id>
/rhei reject <proposal-id>

Rejection feedback may follow on later lines, but it remains untrusted evidence
rather than agent instructions. The decision author must currently have
write, maintain, or admin permission on the repository. Stale IDs,
malformed commands, outside collaborators, and users with only read or
triage permission cannot route implementation.

GitHub comments are the cross-run source of truth. A fresh run can recover a
pending, approved, or rejected proposal without depending on the previous
workspace's runtime files. Marker checks and label operations are idempotent so
partial retries do not duplicate comments.

Security boundary

Issue titles, bodies, comments, code blocks, attachments, linked content, and
reproduction instructions are treated as untrusted evidence. Intake explicitly
forbids:

• executing issue-supplied commands or scripts;
• following arbitrary issue-supplied URLs;
• installing tools requested by issue content;
• reading secrets or credential files;
• accepting issue text as a change to workflow policy;
• making GitHub writes during intake.

Suspected prompt injection is preserved in the issue snapshot and recorded as a
spec-fit risk. Repository instructions read directly from the checkout remain
authoritative.

How to run it

Run commands from the Native Build Tools repository root.

Minimal invocation

rhei instantiate github-issue-fix 1234 --execute

The issue number is the only varying template input. Without --output, Rhei
materializes ./github-issue-fix.

Keep an issue-specific workspace

rhei instantiate github-issue-fix 1234 \
  --output .agents/rhei/runs/issue-1234 \
  --execute

Use an issue URL

rhei instantiate github-issue-fix \
  https://github.com/graalvm/native-build-tools/issues/1234 \
  --output .agents/rhei/runs/issue-1234 \
  --execute

Render and validate without executing agents

rhei instantiate github-issue-fix 1234 --dry-run

Inspect a materialized workspace

rhei validate .agents/rhei/runs/issue-1234
rhei run .agents/rhei/runs/issue-1234 --dry-run

Continue after proposal approval or rejection

After a repository member posts the exact approval or rejection command, start
a fresh workspace for the same issue:

rhei instantiate github-issue-fix 1234 \
  --output .agents/rhei/runs/issue-1234-approved \
  --execute

The new run reconstructs the proposal decision from GitHub.

Validation performed for this PR

• rhei templates discovers github-issue-fix as a project template.
• rhei instantiate github-issue-fix --list-inputs reports only the required
  issue input.
• numeric issue instantiation passes.
• full GitHub issue URL instantiation passes.
• a materialized workspace passes rhei validate.
• the materialized workspace passes rhei run --dry-run.
• bin/github-proposal --help succeeds.
• git diff --check passes.
• grund check passes.

Scope

This PR deliberately ports only the NBT-owned template. It does not move the
Rhei CLI implementation, Rhei functional specifications, Rhei E2E tests,
Rhei changelog entries, or the rendered Rhei example workspace.

[vjovanov]

Hmm, this should be a separate knob for effort. Also, we should use high.

[vjovanov]

We need effort here as well? The effort should be a variable.

Also, the whole target should be a variable as I might use claude

[vjovanov]

No terra, ever. Luna high or extra high. But again, call it a small model and allow to cofigure.