gh-address-cr

Auditable pull request review-resolution workflow for AI coding agents.

gh-address-cr is a deterministic CLI runtime plus a thin Codex skill/plugin adapter. It coordinates GitHub review threads, local AI review findings, evidence, replies, resolves, and final-gate proof in one PR-scoped session.

It is not a code-review producer and not a generic GitHub bot. The runtime owns state and side effects; agents return structured evidence and the runtime publishes GitHub replies/resolves.

Project architecture governance lives in AGENTS.md. The installed skill contract remains skill/SKILL.md.

60-second quickstart

Install the runtime:

pipx install gh-address-cr
gh-address-cr --help
gh-address-cr agent manifest

Install the Codex/agent skill adapter:

npx skills add https://github.com/RbBtSn0w/gh-address-cr --skill skill
npx skills check

Build the Codex community plugin payload:

python3 scripts/build_plugin_payload.py --output dist/plugin/gh-address-cr

Then install from the generated marketplace path when working from a built checkout or release artifact:

codex plugin marketplace add .agents/plugins/marketplace.json
codex plugin marketplace upgrade
codex plugin add gh-address-cr@gh-address-cr-community

When to use it

Use it when:

• a pull request has unresolved GitHub review threads
• an AI review producer emits normalized findings for the PR
• stale or outdated review threads need explicit evidence and handling
• completion requires a fresh gh-address-cr final-gate <owner/repo> <pr_number> proof

Do not use it as:

• a replacement for a code-review producer
• a generic GitHub issue bot
• a ChatGPT Apps SDK app or MCP server
• a shortcut for posting GitHub replies or resolving threads outside the runtime

First PR walkthrough

gh-address-cr active-pr --repo owner/repo
gh-address-cr review owner/repo 123
gh-address-cr address owner/repo 123 --lean
gh-address-cr agent publish owner/repo 123
gh-address-cr final-gate owner/repo 123

GitHub stacked pull requests (generally available since 2026-10-06) are supported as an additive workflow. On hosts without the feature (for example an older GitHub Enterprise Server) stack context is reported as unavailable. Normal commands remain scoped to the selected PR layer and report stack_context; use final-gate owner/repo 123 --stack only for a fresh bottom-up gate through that PR. gh-address-cr does not create, checkout, rebase, push, modify, queue, merge, or unstack a stack; use GitHub's gh stack workflow for stack management.

Feedback is fixed on the owning member branch, never on whichever upper branch happens to be checked out. A separately authorized stack-management workflow may then cascade the change upward; after it pushes rewritten members, discard old ActionRequests and obtain fresh revision-bound evidence before publishing.

Stacked-member requests and validation evidence are bound to the validated content of the member (revision_binding.v2, keyed by the head commit's tree, which already contains the trunk and every lower layer). A change to the member's own or a lower layer's content invalidates that evidence before reply/resolve side effects, so refresh and revalidate the owning layer. A rebase that leaves the content unchanged, a push to a higher layer, or the position renumbering after a lower member merges does not. For an already-terminal GitHub thread or local finding, record that fresh proof with agent evidence add --item-id <item_id> --commit <sha> --files <paths> --validation <cmd=passed>; the runtime attaches the current stack binding. Each stacked PR has its own CR session and evidence lifecycle. For example, a three-member stack is handled with address owner/repo 101, address owner/repo 102, and address owner/repo 103; resolve and publish findings in the session for the owning PR reported by stack_context.selected_pr. A finding seen on the top PR but introduced by a lower PR must be handed back to that lower PR. Run each member's layer final-gate separately, and use final-gate ... --stack only for explicitly requested bottom-up aggregate proof. After gh stack sync or gh stack rebase, or after GitHub rebases the remaining members when a lower one merges, refresh every affected member; revalidate only the members whose content changed before publishing again. Stack merge remains an atomic, contiguous, bottom-up GitHub operation.

Sandbox-safe session state

PR-scoped commands persist their session, evidence, and final-gate artifacts in one state directory. In a restricted agent runtime, choose a writable directory explicitly and reuse it for the full PR session:

export GH_ADDRESS_CR_STATE_DIR="/path/to/writable/gh-address-cr-state"
gh-address-cr review owner/repo 123

Use the same value for review, address, agent next, agent submit, agent publish, and final-gate; changing it starts a different local session view. If the configured directory is unavailable, the runtime returns STATE_DIR_NOT_WRITABLE with this override as the recovery action.

Each PR workspace uses runtime.sqlite3 as its authoritative, versioned runtime store. JSON and JSONL files in the live workspace are read-only projections; session.json carries its source revision and evidence.jsonl.meta.json carries the JSONL projection revision without changing the JSONL row format. session.json is written as compact, key-sorted JSON. Runtime schema v3 marks it dirty after bounded commands and rewrites it at explicit full-load, reporting, export, and recovery boundaries; consumers that require current data must verify its embedded revision or request materialization. Incremental evidence remains current after command commits. Read JSON with a parser rather than by line. Editing or deleting these projections does not change runtime truth. Unsupported schemas, recovery-bundle divergence, stale revisions, and bounded writer contention fail explicitly instead of falling back to uncoordinated file writes.

Completion means the latest final gate reports:

• zero unresolved review threads
• zero pending reviews for the authenticated login
• no blocking session items
• terminal GitHub threads have durable reply evidence
• a readable Markdown summary via completion_summary.markdown or PR Completion Summary Guidance
• a telemetry coverage label and structured efficiency report path; a command that exits 5 because the PR still needs work (for example address or final-gate blocking on an open thread) counts in needs_action_count, not as a failure in success_rate or the inefficiency flags
• the efficiency report's runtime (version, origin of package, editable, vcs, or local for another non-editable local install, and the commit for a git install), so reports from a development checkout and from a release can be compared with python3 scripts/compare_telemetry_by_runtime.py (add --baseline and --candidate runtime labels to fail on a success-rate drop or new flag kinds)
• an advisory cr-lifecycle.v1 report at cr-metrics.json; exact lead-time aggregates exclude inferred observation times, and report failures never change the gate verdict or exit code
• an audit summary path with a sha256 hash

A zero unresolved-thread count alone is not sufficient.

OpenTelemetry traces

otel-tracing.v2 is the versioned public behavior and architecture boundary for process tracing.

• Process-level observability owner: the CLI process
• External inputs: command invocation and environment-based telemetry opt-out
• Span projection: one root span per CLI invocation
• Export policy: OTLP/HTTP through the configured relay
• Side-effect boundary: tracing observes runtime behavior and remains separate from PR-scoped workflow telemetry
• Artifact truth boundary: trace artifacts are observability outputs, not runtime truth
• Recovery and replay: tracing is fail-open and must not block command completion

The installed CLI exports one process-level OTLP/HTTP trace to the production Gateway by default:

https://telemetry-gateway.hamiltonsnow.workers.dev/v1/traces

Development and PR-preview builds (a .devN development-release version) default to the development Gateway instead, so pre-merge traffic never reaches the production dataset:

https://telemetry-gateway-development.hamiltonsnow.workers.dev/v1/traces

Published releases, including beta and rc pre-releases, report to the production Gateway, and a local version segment (+...) does not change that: only a .devN release is routed away. An unrecognized version string also falls back to production.

For controlled environment canaries, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT may target the exact HTTPS development or staging Gateway origin. The client adds the anonymous admission profile only for these three allowlisted origins; it does not add it to arbitrary custom collectors.

The service name is gh-address-cr. The client contains no API key; the Cloudflare Worker as the security relay injects backend credentials. To disable network tracing:

export DISABLE_TELEMETRY=1
# or
export DO_NOT_TRACK=1

Tests use the same stable service identity. As a distributable CLI, gh-address-cr does not claim a hosted deployment.environment.name; gateway-owned admission and destination configuration provide isolation.

The CLI entrypoint initializes tracing before dispatch and calls shutdown_telemetry() in a finally block. It attempts to flush spans for up to 2.2 seconds, including a 2-second exporter timeout, then returns fail-open if the gateway remains unavailable. For a custom operation:

from opentelemetry.trace import Status, StatusCode

from gh_address_cr.telemetry import initialize_telemetry, shutdown_telemetry

tracer = initialize_telemetry()
try:
    with tracer.start_as_current_span("my-task") as span:
        span.set_attribute("cli.argument", "value")
        try:
            run_task()
        except Exception as error:
            span.record_exception(RuntimeError(type(error).__name__))
            span.set_status(Status(StatusCode.ERROR))
            raise
finally:
    shutdown_telemetry()

Do not attach tokens, raw prompts, usernames, machine identifiers, or local paths as span attributes.

CLI span attributes for AI agent scenarios

Every CLI invocation also emits exactly one gh-address-cr.cli span (kind INTERNAL) carrying a fixed set of attributes, so agent hosts can correlate tool calls without extra instrumentation:

• process.executable.name, process.pid, process.parent_pid, process.exit.code — execution identity and the honest exit code (including non-zero Status-to-Action codes; these are not errors)
• error.type — present only when an exception actually propagated (a crash), drawn from a bounded set: keyboard_interrupt, timeout, _OTHER
• process.command_args, gen_ai.tool.call.arguments — sanitized argv via sanitize_cli_argv(...); only the executable/command skeleton stays literal, while every option and value slot is replaced with "[redacted]" in place (position-preserving), never dropped
• gen_ai.operation.name (execute_tool), gen_ai.tool.name — GenAI tool vocabulary for the invoked command
• gen_ai.conversation.id (+ .source), gen_ai.agent.name — passive session correlation. Set GH_ADDRESS_CR_CONVERSATION_ID (preferred, vendor-neutral) or CLAUDE_CODE_SESSION_ID (passive fallback) to a stable per-session value so repeated invocations group together; set AI_AGENT to label the calling agent. All three are absent when no session env is set.
• vcs.change.id, vcs.provider.name (github), vcs.repository.name — for PR-scoped commands only (owner/repo <pr_number>); vcs.repository.name is a stable one-way hash, never the plain owner/repo string. vcs.change.state appears only when already available from session data. Non-PR commands (version, doctor) carry no vcs.* attributes.
• The root CLI span may also include phase events for long-running workflows such as preflight, session load, ingestion, gate evaluation, summary emission, and nested command-session or subprocess milestones. These events keep the single-span contract intact while making the Honeycomb timeline easier to read.

Subprocess arguments are never exported. Child process spans and their start/end events carry only the executable identity, a bounded operation category, attempts, duration, exit outcome, and bounded error classification. They never carry GraphQL, URLs, repository names, thread identifiers, reply bodies, local paths, standard streams, or hashes of those values.

Endpoint precedence follows the standard OTLP variables: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT with /v1/traces, then the release-channel default described above. Requests to the approved gateway carry otel-gateway-profile: anonymous-client-v1; custom Collector endpoints do not inherit that header.

A malformed or missing TRACEPARENT never blocks or changes the CLI's exit code; a well-formed one makes the span a child of that remote context. See docs/rfcs/026-cli-otel-agent-integration/contracts/cli-otel-span-attributes.md for the full enforced contract.

Public surface

Primary commands:

• active-pr
• review
• address
• final-gate

Advanced integration commands:

• threads
• findings
• adapter
• review-to-findings
• agent manifest
• agent classify
• agent next
• agent next --batch
• agent submit
• agent resolve — supported GitHub-thread item, files, batch, and stale command shapes with --disposition fix|trivial|reject|clarify|defer
• agent evidence
• agent publish
• agent leases
• agent reclaim
• command-session
• doctor

High-level commands emit machine-readable JSON summaries by default. Use --machine to explicitly request structured output, --human when a person needs narrative output, and --lean where supported for low-token agent context.

Every final efficiency summary reports one coverage label: complete, partial, runtime-only, or unavailable. The runtime records process and workflow telemetry for the surviving core path and keeps telemetry fail-open: reduced coverage is reported in the summary, but it does not change the review verdict by itself. For GitHub review-thread replies, the current shortcut is agent resolve; it records classification internally, so no separate agent classify round-trip is needed. Use only the item, files, batch, and stale shapes documented by agent manifest; their flags are validated together rather than forming an unrestricted product. Local findings use agent classify → agent next → response skeleton → agent submit and must not publish GitHub side effects. Shared files/validation evidence is not the same as a shared reviewer answer. Use agent resolve --input <batch-response.json> with per-thread summary/why entries for ordinary multi-thread handling. Commit evidence is hydrated by the runtime during publish, so independent worker evidence does not need to wait for a final commit hash. Use agent resolve --why <why> only for a homogeneous repeated concern. When resolve reports PER_THREAD_EVIDENCE_REQUIRED, run agent next --batch --agent-id <id> to claim eligible GitHub review threads and write a fillable batch-response-skeleton.json before agent resolve --input <batch-response.json>.

When exactly one PR session is cached, PR-scoped commands such as address, review, threads, and final-gate may omit <owner/repo> <pr_number>. No-session and multi-session cases fail loud with NO_ACTIVE_PR_SCOPE or AMBIGUOUS_PR_SCOPE.

Use agent resolve <item_id> --disposition trivial only for documentation or typo-only GitHub review threads, and agent resolve --stale for STALE/outdated threads. The runtime rejects security-sensitive, API-sensitive, performance, or ambiguous comments with TRIVIAL_THREAD_NOT_ELIGIBLE; normal reply, resolve, validation, and final-gate evidence still applies.

Agents that need a schema-defined triage handoff emit workflow_decision.v1 JSON with schema_version, request_id, item_id, decision, and reason.

command-session --input <json>|- executes multiple one-shot runtime commands inside one process and returns one result per operation. Failed operations do not suppress later operations.

agent orchestrate remains an optional advanced surface. The default supported path is still single-agent review / address / agent resolve / agent publish / final-gate; no orchestration session is required for normal PR handling. Its versioned worker-packet.v2 contains a dispatch-receipt.v2 projection that references the canonical runtime lease_id, request binding, and committed revision. The orchestration session owns delivery only: lease conflict, expiry, status, and release decisions remain in the runtime store, and lost dispatches are rebuilt from canonical leases. The --token accepted by agent orchestrate submit is the opaque delivery token from that receipt (the canonical lease's resume token), not a second lease.

Architecture and Packaging

gh-address-cr is the preferred and stable automation entrypoint.

• Published skill payload: the entire skill/ directory
• Repo-level verification harness: tests/
• If a rule or instruction must ship with the installed skill, it must live inside skill/

When blast radius requires kernel-style modeling, the design follows external facts -> events -> projections -> policy -> command plan/outbox. Architecture Preflight must name the artifact truth boundary, any self-referential completion risk, and the recovery model. If review feedback keeps adding edge cases without reducing state space, stop expanding conditionals and update the architecture spec instead.

Runtime and adapter boundary

The deterministic implementation belongs to the Python runtime package:

• console entrypoint: gh-address-cr
• module entrypoint: python3 -m gh_address_cr
• source package: src/gh_address_cr/

The packaged skill remains under skill/ and acts as a thin adapter:

• skill/SKILL.md explains agent behavior
• skill/runtime-requirements.json declares runtime compatibility
• skill/agents/ and skill/references/ provide hints and reference docs

The Codex plugin payload is generated from skill/ into a build artifact such as dist/plugin/gh-address-cr:

python3 scripts/build_plugin_payload.py --output dist/plugin/gh-address-cr
python3 scripts/build_plugin_payload.py --check

The OpenAI curated Plugin Directory is not a self-service publish target in this repository. The committed .agents/plugins/marketplace.json points at the generated community distribution artifact.

Command Topology (ASCII)

active-pr
review
review [--auto-simple]
address [--lean|--summary]
threads [--lean|--summary]
findings --input <json|->
adapter <adapter_cmd...>
doctor
command-session --input <operations.json|->
final-gate
review-to-findings --input <finding-blocks.md|->
submit-feedback
submit-action <action-request.json>
version / --version
--machine
--human

manifest
classify
next --role <role>
next --batch
submit
resolve <item_id>
resolve <item_id> --disposition trivial
resolve <item_id> --disposition defer --why <why>
resolve --input <batch-response.json>
resolve --why <why>
resolve --disposition reject|clarify|defer --why <why>
resolve --stale
evidence add
evidence list
publish
leases
reclaim
orchestrate start/status/step/resume/stop/submit/autopilot

WAITING_FOR_EXTERNAL_REVIEW
WAITING_FOR_SIMPLE_ADDRESS
PER_THREAD_EVIDENCE_REQUIRED -> next --batch
producer output
session items
agent classify
ActionResponse or BatchActionResponse
agent submit or agent resolve --input <batch-response.json>
accepted evidence
agent publish (GitHub thread side effects only)
final-gate
completion_summary_line
completion_summary
runtime-owned leases + request_id values
agent resolve --input <batch-response.json> validates lease ownership and request context

Stable machine summary fields:

• status
• repo
• pr_number
• item_id
• item_kind
• counts
• artifact_path
• reason_code
• waiting_on
• next_action
• primary_action (kind, command, item_id, why_now, requires_human)
• context (bounded PR, check, changed-file, and selected-item context). The selected item's comment_excerpt holds at most 500 characters; when it is cut, comment_excerpt_truncated is true and full_comment_command names the threads command whose rows carry the full review body
• commands
• exit_code

Use --lean or --summary when reducing token load. Machine summaries also surface the current-login pending review count.

review, address, and threads may be run without a PR target. Resolution prefers the current GitHub repository and branch's unique OPEN PR, then a same-repository unique ACTIVE session, then a globally unique ACTIVE session. Explicit targets always win. Ambiguous targets, detached HEAD, missing OPEN PRs, and GitHub authentication or network failures fail with a diagnostic; query failures never fall back to potentially stale cached state.

For the shortest repeatable loop, run gh-address-cr address, execute the one primary_action.command when it is non-null, and run gh-address-cr address again. Before executing, fill any evidence placeholders (<sha>, <paths>, <text>, <cmd=passed>) from the fix you made; an unresolved review thread is recommended as an item-scoped agent resolve, which records classification itself. The action vocabulary is deliberately small: claim, resolve, publish, wait, run_final_gate, repair_environment, and complete. command=null is valid whenever the next step needs new human/agent evidence, waiting, environment repair, or represents completion; read why_now rather than inventing an action.

Zero-argument success rate is measured only across eligible invocations: those with a unique current-branch OPEN PR or an eligible unique ACTIVE session, while GitHub CLI, authentication, and network prerequisites are available. Ineligible invocations remain visible but do not enter the success rate denominator.

Advanced / Developer Integration

The public user flow above does not require manual --input, producer selection, or mode routing.

For explicit automation or repository-root invocation, the main command is: gh-address-cr review <owner/repo> <pr_number>.

adapter is for adapter-produced findings plus PR orchestration.

review handles both local findings and GitHub review threads in one run. findings handles local findings only; it does not process GitHub review threads.

findings --sync requires an explicit --source. review-to-findings does not accept arbitrary Markdown. It only accepts the fixed finding block format.

The wrapper --human and --machine belong before adapter; remaining flags are passed through to the adapter command unchanged.

$gh-address-cr --human adapter <owner/repo> <pr_number> <adapter_cmd...>
$gh-address-cr adapter <owner/repo> <pr_number> <adapter_cmd...> --human --machine
gh-address-cr --human adapter owner/repo 123 python3 tools/review_adapter.py
gh-address-cr adapter owner/repo 123 python3 tools/review_adapter.py --base main --human

Any external review producer may satisfy the handoff.

• producer-request.md
• incoming-findings.json
• incoming-findings.md
• WAITING_FOR_EXTERNAL_REVIEW
• source-scoped producer result
• [] is a valid explicit producer result

Published fix replies surface exactly one canonical Review signal: line when severity or reviewer priority evidence exists.

Workflow Patterns

Automatic Review Workflow

1. Run gh-address-cr review <owner/repo> <pr_number>.
2. Ingest existing findings or wait for external review handoff.
3. Route GitHub threads through agent resolve and agent publish. Route local findings through agent classify → agent next → response skeleton → agent submit; do not publish GitHub side effects for local findings.
4. Finish with final-gate.

for GitHub thread fix: fix_reply

• summary
• files

for GitHub thread clarify or defer: reply_markdown

Minimal user prompt:

Run gh-address-cr review for this PR, follow the machine summary, and finish with final-gate.

Ready-to-use prompt variants:

• Short generic: Review this PR through gh-address-cr and follow the runtime status map.
• Existing GitHub review threads (address / 处理评审): Use $gh-address-cr address PR #123.
• Explicit $code-review producer: For a full mixed review (review / 完整审查), use Use $gh-address-cr review PR #123 with $engineering:code-review as the findings producer.
• Any external review producer: Any external review producer may satisfy the handoff if it emits findings JSON or fixed finding blocks.

For the explicit $engineering:code-review composition, override its default Markdown report and require findings JSON with title, body, path, and line; use [] when no findings exist. Ingest it with findings --input - --sync --source code-review, then continue review.

如果你自己就是外部 review producer，请直接输出 findings JSON 或固定 finding blocks。

不要只输出普通 Markdown 审查报告。

Advanced producer categories:

• adapter-produced findings
• fixed finding block conversion
• explicit findings --sync --source <producer> handoff

Runtime Distribution

Install the released runtime CLI:

• pipx install gh-address-cr
• uv tool install gh-address-cr

Install with Homebrew:

• brew tap RbBtSn0w/tap
• brew install gh-address-cr
• brew upgrade gh-address-cr
• brew test gh-address-cr

GitHub-direct runtime validation install:

• pipx install git+https://github.com/RbBtSn0w/gh-address-cr.git

Local editable development install:

• python3 -m pip install -e .

Packaged skill install:

• npx skills add https://github.com/RbBtSn0w/gh-address-cr --skill skill

The packaged skill does not install the runtime CLI package.

Current Public Contract

Use runtime 3.16.0, protocol 1.1, skill contract 1.1, and dispatch-receipt.v2. The current public commands are:

• review
• address
• threads
• findings
• final-gate

The shipped runtime, packaged skill, Python package, console entrypoint, and plugin remain named gh-address-cr.

Troubleshooting

When machine output is ambiguous, inspect:

• status
• reason_code
• waiting_on
• next_action
• primary_action
• commands
• artifact_path

Outdated / STALE GitHub threads still count as unresolved until explicitly handled. Prefer agent resolve --stale.

Additional Repository Files

• Privacy
• Security
• Terms

Development checks

Run the local verification gate before submitting changes:

ruff check src tests scripts/build_plugin_payload.py
python3 -m unittest discover -s tests
python3 -m gh_address_cr --help
python3 -m gh_address_cr agent manifest
python3 scripts/build_plugin_payload.py --output dist/plugin/gh-address-cr
python3 scripts/build_plugin_payload.py --check

An authorized disposable GitHub stack can be provisioned, exercised, verified, and explicitly cleaned with the manifest-scoped E2E harness:

python3 scripts/e2e_stacked_pr_sandbox.py provision --manifest /var/tmp/gh-address-cr-stack-e2e.json
python3 scripts/e2e_stacked_pr_sandbox.py exercise --manifest /var/tmp/gh-address-cr-stack-e2e.json
python3 scripts/e2e_stacked_pr_sandbox.py cleanup --manifest /var/tmp/gh-address-cr-stack-e2e.json

Scenario actions reproduce what GitHub GA does to a live stack, and refresh records the resulting head/base drift in the manifest after proving the pull requests are still the recorded fixture, so verify and cleanup keep working without hand-editing it. rebase commits a change to the bottom layer and cascades it with gh stack rebase and gh stack push; merge-bottom squash-merges the bottom layer with gh stack merge, which makes GitHub rebase and retarget the remaining members. Both need the gh stack extension and leave the sandbox main with the merged fixture files (merging cannot be undone by cleanup).

python3 scripts/e2e_stacked_pr_sandbox.py rebase --manifest /var/tmp/gh-address-cr-stack-e2e.json
python3 scripts/e2e_stacked_pr_sandbox.py merge-bottom --manifest /var/tmp/gh-address-cr-stack-e2e.json
python3 scripts/e2e_stacked_pr_sandbox.py refresh --manifest /var/tmp/gh-address-cr-stack-e2e.json

fix-evidence resolves the middle layer's thread as a fix with validation evidence, which is the only scenario that exercises revision-bound evidence; gate then reports each layer's own final-gate verdict. Running rebase (the bottom layer's content changes) after fix-evidence yields FINAL_GATE_STALE_REVISION_EVIDENCE for the middle layer, while merge-bottom (GitHub rebases the rest, content unchanged) leaves it PASSED.

The default target is the repository's designated demo sandbox. Other targets must contain a sandbox marker or be explicitly authorized with --allow-non-sandbox.

Package smoke:

rm -rf dist build
python3 -m build
python3 -m twine check dist/*

Dogfooding an unreleased runtime

To address review comments on a real PR with an unreleased runtime, pin a commit instead of using gh-address-cr from PATH (usually the release) or python3 -m gh_address_cr (an editable install that follows whichever branch is checked out). scripts/dogfood_env.sh installs one commit non-editably into its own venv and prints the exports that select it, so the runtime stays fixed while you check out the PR branch:

eval "$(scripts/dogfood_env.sh --ref develop)"

The pinned commit is printed on stderr and in the first export line. Then run the normal workflow on the PR branch:

gh-address-cr address <owner/repo> <pr_number> --lean
gh-address-cr agent resolve <owner/repo> <pr_number> <item_id> --commit <sha> --files <paths> --summary "..." --why "..." --validation "unit-tests=passed@4200ms"
gh-address-cr agent publish <owner/repo> <pr_number>
gh-address-cr final-gate <owner/repo> <pr_number>

Notes:

• Only committed code is installed; rerun the script after the runtime changes. Use --no-install in a new shell to reuse the last pinned build.
• Sessions live in a separate state directory (GH_ADDRESS_CR_STATE_DIR, default under ~/.cache/gh-address-cr-dogfood, override the root with --home or GH_ADDRESS_CR_DOGFOOD_HOME), so they do not mix with sessions created by the released runtime.
• Efficiency reports from the pinned build record runtime.origin=vcs and the commit. Compare them with release runs with python3 scripts/compare_telemetry_by_runtime.py.
• tests/test_dogfood_env_script.py covers the script without a network install. Set GH_ADDRESS_CR_DOGFOOD_INSTALL_TEST=1 to also run the real pinned install.

Repository model

This repository has two scopes:

• repository root: development, verification, CI, release metadata, and contributor guidance
• skill/: the installable and published skill folder

The product/runtime identity remains gh-address-cr: the Python package, console entrypoint, repository URL, SKILL.md frontmatter name, plugin name, and /gh-address-cr invocation must not be renamed.