Replace complex shell with tested Go, starting with gates and merging #588

Problem

Complex shell is frozen by operator direction. Replace its behavior with tested Go, delete the shell implementation being replaced, and retain a thin exec shim only where an existing executable path must remain.

Baseline: origin/main at 226a50c0b33c0b2733b2886dec2d72d711e362de, confirmed against git ls-remote origin refs/heads/main. The existing checkout matched that commit. Inspection was read-only with GH_CONFIG_DIR=~/.config/gh-agent; no 1Password access or publication occurred.

The inventory contains 100 maintained shell files and 14,183 physical lines, including comments and blank lines. It excludes generated skill copies, Bats files, test fixtures, vendored dependencies, and inline task bodies. Two coupled Python helpers are listed separately because leaving them behind would leave the gate and merge implementation fragmented.

Existing Go implementations provide a starting point:

• agentrepo checks evaluate / internal/checks: saved check evaluation.
• agentrepo review run / internal/review: reviewer deadlines and process cleanup.
• agentrepo config / internal/config: machine and repository configuration.
• commit-lint / internal/commitlint: message shape, trailers, identity policy, and outgoing commit checks.
• gh-post / internal/ghpost: scanned GitHub content publication.
• guard-markdown / internal/markdown and internal/hookio: Markdown checks and Write/Edit hook handling.
• ssh-sign / internal/signing: signing infrastructure, rather than the complete unattended commit verification workflow.

agenthooks, agentcontext, and agentstore currently expose version commands only; they are command skeletons, not completed shell replacements.

Acceptance criteria

1. AC1: Every inventoried complex shell implementation is replaced by Go tests and Go code. Replaced algorithms are deleted; required executable paths contain only forwarding shims.
2. AC2: Each migration ports the relevant Bats behavior into Go tests and retains sufficient integration coverage to verify arguments, streams, exit statuses, and generated entry points.
3. AC3: Gates and the merge path migrate first, hooks second, and remaining workflows and tooling third.
4. AC4: Authority remains machine-selected. Confirmation precedence, exact-head approvals, owner overrides, trusted review policy, stamp bindings, signing checks, and evidence retention remain covered by tests.
5. AC5: Empty or unreadable checks cannot become success. Protected writes remain pinned to reviewed state, and uncertain writes are never retried automatically.
6. AC6: Canonical sources generate both harness packages and their deployments without hand edits. Removed helpers disappear from generated output.
7. AC7: Replacement binaries are available before matching skill deployments require their commands. No new shell fallback duplicates migrated Go behavior.
8. AC8: Required Go, integration, generation, lint, and packaging checks pass, and the replacement enforcement code is covered by golden-file protection (build(agents): protect replacement Go enforcement paths #753) before operational rollout.

Scope and non-goals

Inventory risk: H affects enforcement, authority, Git state, publication, cleanup, or sensitive scanning; M affects reports, generation, or tool execution; L is an existing forwarding shim. G marks paths matched by the current golden and owner-path patterns.

Counterparts below are partial unless explicitly stated otherwise. — means no implemented Go counterpart was found. hookio supplies hook infrastructure, not the listed guard’s rules.

Coupled non-shell implementations:

Out of scope: replacing Git, GitHub CLI, mise, prek, external linters, or tokenizers; changing repository policy as a side effect; rewriting unrelated Python analysis tools; changing vendored upstream code.

Published paths under scripts/ retain their filenames and calling conventions. Their replacement shims execute Go without maintaining a second implementation.

Approach

Use small migrations that remove complete leaf algorithms before retiring their containing libraries. The first two Features below modify disjoint maintained files and can be built in parallel. Remaining complex shell stays frozen during that transition.

Ordered Features:

1. Port strict review-verdict parsing to Go — S. Remove dt_verdict and port its Bats cases.
2. Port exact-head merge approval selection to Go — S. Remove ma_approved and port reviewer/owner approval cases. Build alongside Feature 1.
3. Replace the remaining shell check judge. Resolve and test compatibility differences before connecting attended merge reporting to internal/checks.
4. Move gate execution and pass caching to Go. Replace gates.py; preserve fingerprints, forced reruns, logs, invalidation, and clean-tree requirements.
5. Move shared gate readiness, review state, and confirmation into Go. Retire readiness shell, verdict/stamp orchestration, persistent bounds, and configuration fallbacks after binary rollout.
6. Move pinned merge readers and policy inspection into Go. Cover review pagination, complete local diffs, required checks, base rulesets, APM ownership, and owner-path reporting.
7. Move squash briefing and lint orchestration into Go. Preserve issue references, sign-off policy, attribution, and dictionaries read from the pinned PR head.
8. Move merge execution and recovery into Go. Preserve live rechecks, dependent PR retargeting, exact-head writes, remote verification, reporting, and conservative cleanup. Delete the remaining merge shell and coupled policy helper.
9. Replace Bash workflow guards with Go hooks. Preserve scoped allowlists, activation state, refusal messages, and exit-2 behavior.
10. Replace public commit hooks and pre-push installation with Go. Preserve published paths, stdin replay, stages, and external linter invocation.
11. Replace prose guard state and suppression checks with Go. Preserve canonical paths, single-edit release, dictionary snapshots, and refusal boundaries.
12. Replace remaining commit and PR workflows with Go. Cover signing verification, preview lint, draft parsing, validation, properties, leased pushes, publication, and reports.
13. Replace rebase and conflict-resolution shell with Go. Preserve pinned Git settings, marker exceptions, classifications, union verification, and recovery evidence.
14. Replace watchers, diagnosis, and context gathering with Go. Preserve event streams, time bounds, error statuses, and worktree isolation.
15. Replace remaining tooling and deployed adapters with Go. Include leak scanning, generation, hygiene, version checks, lint adapters, and language-task helpers.
16. Replace release and bootstrap orchestration with Go. Preserve release authority and establish a distribution path that works before mise provisions a Go toolchain.

Each larger Feature is divided into XS/S implementation PRs before coding.

Generation is part of each migration. A normal shared skill script has one source and four tracked outputs, across the two packages and two local deployments. lib.sh is broader: one source and 20 tracked outputs across five skill families. Edit canonical sources, then run generation, token measurement, and deployment in the documented order. Never repair generated copies individually.

The first two Features change different generated script paths. Their shared merge-pr token metadata may overlap; regenerate that metadata from the combined tree instead of merging counts by hand.

Dependencies

• Existing Go command structure and configuration readers.
• Existing Bats suites as behavioral evidence, including failure and partial-output cases.
• A release/deployment sequence that installs new Go commands before deploying callers.
• One owner-approved edit to the pattern file (build(agents): protect replacement Go enforcement paths #753) that adds the replacement Go enforcement paths to the golden patterns before operational rollout; current shell path patterns do not automatically protect new Go files. Later changes to those paths take the golden-file route, where the required reviewer's exact-head Loosens: no review waives the finding and detected loosening or other holds still go to the operator.
• An explicit compatibility decision for the legacy merge check judge: its malformed-input, unknown-state, tied-run, and status-context behavior differs from internal/checks.
• A bootstrap distribution decision before replacing tools/mise-bootstrap.

Size

L epic

Verify plan

For each Feature:

• Port relevant Bats cases into Go tests before removing the implementation.
• Test arguments, output, statuses, malformed input, and subprocess failures using local fixtures and stubs.
• Run targeted Go and Bats suites against binaries built from the branch.
• Regenerate canonical package output, token records, and deployments; run mise run check-generated-skills.
• Run applicable lint, architecture, packaging, and scanner gates.

Before closing the epic, run the full repository checks, Go race tests where applicable, hook regressions, and deployment audits. Recount maintained shell and verify that retained entry points contain only forwarding logic. Perform no real commit, publication, merge, or release as a test.

Risks

The highest risks are changing authorization while translating it, accepting partial subprocess output, stale review bindings, repeating an uncertain write, and deleting valuable work during cleanup.

Go check evaluation is not a drop-in behavioral replacement for the remaining jq judge. That migration needs an explicit tested contract.

Mandatory Go commands introduce rollout dependencies. Generated copies multiply mechanical changes, and shared token metadata requires regeneration after parallel work integrates. Bootstrap replacement also cannot assume the toolchain it currently installs already exists.

Operator authority

A standing rule names the operator: the freeze and migration order are operator direction, and the single pattern-file edit in #753 needs the owner's exact-head review.

Changes to golden/owner-tier paths require the existing owner review process. Unattended merges involving golden files require an exact-head APPROVED review from machine-configured merge_owner; policy changes cannot authorize themselves. The Go replacements are covered by the golden-file route through #753, whose single pattern-file edit needs the owner's exact-head review.

This epic grants no commit, publication, merge, release, identity, or pre-approval authority.