pikasTech-HWLAB/docs/reference/runner-issue-visibility-handoff.md

HWLAB Runner GitHub Visibility Handoff

This contract records the runner visibility rule that surfaced in pikasTech/HWLAB#51 and supports the downstream work behind #7, #42, and #39.

GitHub issues are auxiliary context only. The task prompt must carry the full objective, background, constraints, acceptance criteria, and validation commands. Do not assume issue comments, PR discussion, or GitHub REST issue data are readable inside the runner unless a preflight proves it.

Prompt Contract

Use this shape when queueing work for the runner:

Repository: pikasTech/HWLAB
Branch: main
Task: <full task objective>
Issue context: <paste the relevant issue summary here, do not rely on live issue reads>

Background
- <current runner facts that matter>
- <upstream context or blocked assumptions>

Constraints
- <hard repo or environment limits>
- <forbidden actions>

Acceptance
- <what must exist when the task is done>
- <what must not change>

Validation
- <exact commands or checks>

Final response
- commit id
- changed paths
- validation commands
- upstream repair advice, if the runner still lacks GitHub visibility

Required Prompt Rules

• The prompt must be self-contained.
• The prompt must not depend on unread issue comments.
• The prompt must include the repo path, branch, objective, acceptance, and constraints.
• The prompt must include any runner-specific limitations that affect the work.
• The prompt must include the exact validation commands the runner should execute.

Known Runner Contract

The D601 Code Queue runner class may have git transport access while GitHub REST issue and PR visibility is unavailable. In the confirmed #42 follow-up path, git fetch and git ls-remote worked, but GitHub repo, issue, and pull-request REST reads returned 404, gh was not installed, and GH_TOKEN / GITHUB_TOKEN were absent.

Treat that as a prompt-handoff requirement, not as a reason to omit task context.

Read-Only Preflight

Use the companion preflight script to check the current runner visibility:

node scripts/runner-issue-visibility-preflight.mjs

The preflight must stay read-only and must not print token values.

Upstream Repair Suggestions

• Add gh to the runner image or another GitHub visibility helper with stable CLI access.
• Inject a read-only GH_TOKEN or GITHUB_TOKEN into the runner environment when issue/PR visibility is required.
• Add a queue preflight that checks git transport, GitHub repo, issue, and PR visibility before dispatch.
• Fail fast when GitHub visibility is missing, and require the prompt to carry the full task context.