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.

Upgrading from 2.x? 3.0 is a breaking release: the agent fix, agent trivial-fix, agent fix-all, agent resolve-stale, and agent submit-batch commands are replaced by a single agent resolve.

Project architecture governance lives in .specify/memory/constitution.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 are supported as an additive public-preview workflow. 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 current head revision and stack topology. A head update or reorder invalidates that evidence before reply/resolve side effects, so refresh and revalidate the owning layer. 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, refresh every affected member and revalidate its changed revision 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.

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 compact metrics line via completion_summary_line or PR Completion Summary Guidance
• a telemetry coverage label and structured efficiency report path
• 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

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 documented application default. 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 specs/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 — (<item_id> | --files/--file | --input) x (--disposition fix|trivial|reject|clarify) x (--stale)
• agent evidence
• agent publish
• agent leases
• agent reclaim
• command-session
• doctor

High-level commands emit machine-readable JSON summaries by default. Use --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 single mutating entrypoint is agent resolve; it records classification internally, so no separate agent classify round-trip is needed. It resolves along three independent axes: disposition (--disposition fix|trivial|reject|clarify), selection (an <item_id>, --files/--file, or --input), and condition (--stale). 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 may emit workflow_decision.v1 JSON with schema_version, request_id, item_id, decision, and reason. Existing Markdown decision blocks remain a documented compatibility path, but JSON avoids whitespace-sensitive parsing.

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.

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 --input <batch-response.json>
resolve --why <why>
resolve --disposition reject|clarify --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)
• 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. 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. Resolve items through agent resolve and publish through agent publish.
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.

Upgrade from skill-shim usage:

• Install the runtime CLI with pipx or uv tool
• Keep --skill skill for the packaged adapter
• Homebrew tap distribution remains available

Compatibility Inventory

Preserved Public Contracts:

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

Unsupported historical root commands:

• legacy_scripts

Removed Or Unsupported Surfaces:

• removed migration/evaluation command surfaces
• legacy script entrypoints

Internal Naming Rule:

• the shipped runtime and packaged skill remain 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

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/*

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.