build(agents): protect replacement Go enforcement paths

Problem

The ports in #588 replace shell enforcement with Go commands. The shell scripts that enforce merge policy sit under protected path patterns in .agents/agent-skills.conf, so a change to them needs owner review. The Go packages that will replace them have no comparable scrutiny yet, so a later change could loosen enforcement without a reviewer being told to look for it at the exact head.

Part of #588.

Acceptance criteria

AC1: A pull request that changes any file in a covered replacement package (the enforcement packages named in Scope and the file that registers agentrepo subcommands) is classified as changing a golden file. The existing golden-file waiver then applies unchanged: the required reviewer's approval on the exact head that states Loosens: no lets a golden-only change merge with no owner approval, a missing or duplicated Loosens answer refuses, and Loosens: yes reaches the operator. None of these paths joins owner_paths or constitutional_paths.
AC2: Protection is preserved and bounded. Every path matched by the existing golden_paths, constitutional_paths and owner_paths patterns before this change is still matched afterwards, and none gains or loses a match. The deliberately unprotected cases stay unprotected, and pure helper packages with no enforcement role are excluded, as the existing negative cases at tests/skills/agent-merge-pr/policy.bats:354,380 already require. The stale-head, deletion and rename checks apply the heightened-review requirement to the new paths.
AC3: Rollout order is provable. build(agents): protect replacement Go enforcement paths #753 merges before any pull request that switches a caller to a Go enforcement replacement. Each such port issue lists build(agents): protect replacement Go enforcement paths #753 under its own Dependencies, and its pull request cites the merged build(agents): protect replacement Go enforcement paths #753 commit as evidence. A port that is not yet filed acquires the prerequisite by listing build(agents): protect replacement Go enforcement paths #753 under Dependencies, which refinement checks.

Scope and non-goals

Covered: the packages and cmd entry points that hold replacement enforcement (merge policy, gates, signing, review stamps, confirmation, delegation), and the file that registers agentrepo subcommands, because registering a replacement is itself a change to what runs. The coverage boundary is exactly those paths. Pure helpers with no enforcement role (formatting, path utilities) stay outside it.

Non-goal: a Go port. This issue ports nothing and adds no subcommand, probe or fallback. Non-goal: loosening or reordering any existing pattern.

Approach

Meet AC1 to AC3. The pattern edits and the order of the test work are the implementer's choice.

Dependencies

Blocks the enforcement ports that follow it: #755, #756 and the later ports in #588 that move enforcement into Go. #754 does not move enforcement and is not blocked by this issue. No blockers of its own. Refinement also reconciles the owner-protection wording in #588 and #755 with this issue's golden-only classification.

Size

XS. One pull request.

Verify plan

AC1: for each covered path class, a policy case that changes a file there and expects the golden-file finding. One case per class shows a missing Loosens answer refusing, Loosens: no from the required reviewer passing with no owner approval, and Loosens: yes reaching the operator, with no owner-review label in any of them.
AC2: a case that runs a fixed list of paths matched by each existing pattern before and after and compares the results; the negative cases for excluded helpers and unprotected paths; and a stale-head, deletion and rename case for a new path, each keeping the heightened-review requirement.
AC1 (registration and construction): include one case per covered path class and one for the registration file; mise run test-hooks tests/skills/agent-merge-pr shows each case failing against the old patterns and passing against the new ones.
AC3: at refinement, refactor(agents): port skill capability and worktree context discovery to Go #755 and refactor(agents): port the gh-post requirement adapter to Go #756 list build(agents): protect replacement Go enforcement paths #753 as a blocker in their own bodies. At merge of each port, its description cites the merged build(agents): protect replacement Go enforcement paths #753 commit.
Definition of done: D1 each AC is verified at the merged head, with the commands and results cited in the pull request's Verification. D2 an independent review approves the exact merged head, and every finding has a recorded disposition. D3 required checks pass with no gate loosened. D4 the leak scans the repository specifies are clean, and every post made for this work (comments, descriptions) passes the per-post leak review before it is posted. D5 every commit is signed. D6 the documentation matches, or the description says No doc impact with the reason. D7 every commit carries an Assisted-by trailer and the pull request carries the provenance:agent-assisted label. D8 the change stays within the pull request size limits. D9 follow-up work, including deferred review findings, is filed as issues, each with a Problem section and numbered acceptance criteria and linking this issue; the pull request's Related section lists them, and any code that defers work links its issue. D10 the merge closes this issue through a closing reference, the project board shows the state Done, and a final Status: comment names the merge commit.

Risks

A pattern that is too broad flags unrelated changes for heightened review. A pattern that is too narrow leaves an enforcement path unprotected. The per-path cases pin both. Undo: revert the commit, which returns to the current patterns.

Operator authority

A standing rule names the operator: the single edit to .agents/agent-skills.conf needs the owner's exact-head review. Adding the new paths means adding them to golden_paths in .agents/agent-skills.conf, and that file is itself golden, constitutional and an owner path today. This one pull request therefore needs that review at merge. No mechanism avoids it, because the pattern lists are read from that file. The edit only tightens, grants no write authority, and is the only owner request in this work: later changes to the covered Go paths take the agent-waivable golden route.

Refinement: NOT READY — scope, protection semantics, and verification need clarification
Model: gpt-6.1-sol

Checked

Read live #753, its comments (none), and named issue #588. Used an independent clone and verified origin identifies tbhb-dev/devtools. Compared repository claims against origin/main at f130498bd7383fe02f8b9d21965f555866abd98c.

AC1: Observable in principle, but “each protected replacement package” leaves the coverage boundary undefined. Define the enforcement responsibilities covered, including dispatcher registration, without prescribing package layout.
AC2: States a useful compatibility outcome. Its verification needs to retain the existing positive and negative protection cases.
AC3: Specifies test maintenance rather than a single observable product outcome. Put the named suite and case requirements in Verify; state the protection behavior as the criterion.
Parity: The configuration-only scope does not replace a shell algorithm, so a full shell-to-Go exit/output contract is unnecessary if the unrelated port text is removed. Existing protection behavior and exceptions still need an explicit preservation contract.
Repository evidence: Current protection patterns name shell enforcement and configuration paths, without Go replacement coverage (.agents/agent-skills.conf:4, .agents/agent-skills.conf:5, .agents/agent-skills.conf:9). Dispatcher registration exists at internal/agentrepo/command.go:85.

Gaps

High — The body describes two different changes. Scope and Dependencies say configuration extension only; Approach prescribes a Go subcommand, caller probing, fallback behavior, and generated output. Risks and Undo describe that port rather than protection configuration. Remove those port requirements and align Risks and Undo with protection changes. Under the requirements-only rule, command structure and generation design belong in the pull request.
High — AC1 does not resolve the existing owner-approval exception. Current policy can waive golden-only findings after a qualifying exact-head App review (packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:576). Constitutional findings prevent that golden-only waiver (packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:523). Specify whether replacement enforcement always requires owner approval, as AC1 says, or retains the existing exception. Preserve the intended policy tier of each migrated responsibility; merely matching a golden pattern does not prove unconditional owner approval.
High — The coverage boundary and rollout condition are not verifiable. Identify which enforcement responsibilities this issue protects and make protection before caller activation an explicit acceptance outcome. “No blockers” is credible for advance protection, but the body does not establish how coverage remains complete as replacement responsibilities arrive. This needs a behavioral boundary, not a prescribed directory structure.
High — Operator authority is incorrect. “None” conflicts with Dependencies, Replace complex shell with tested Go, starting with gates and merging #588’s owner-review requirement, and the existing protection of the configuration itself (.agents/agent-skills.conf:4, .agents/agent-skills.conf:5). State that the protection update requires the existing exact-head owner approval process. This grants no implementation or publication authority.
Medium — Verify does not prove every AC. “Failing case first” alone does not establish expected results, and AC2 should already pass before adding protection. Map AC1 to missing approval, stale-head approval, qualifying current-head approval, and the chosen exception semantics. Map AC2 to all retained protected and deliberately unprotected cases, including deletion and rename behavior. Existing examples are at tests/skills/agent-merge-pr/policy.bats:109, tests/skills/agent-merge-pr/policy.bats:124, tests/skills/agent-merge-pr/policy.bats:220, and tests/skills/agent-merge-pr/policy.bats:346. Include the dispatcher and rollout outcome explicitly.
Medium — Completion requirements lack planning coverage. Neither build(agents): protect replacement Go enforcement paths #753 nor named Replace complex shell with tested Go, starting with gates and merging #588 explicitly covers D1–D10 below. Add a completion contract covering these obligations, including AC-indexed merged-head evidence and exact-head review. The current size estimate and generic gate references cover only fragments.

Split

XS, one PR is reasonable after narrowing this to protection configuration and focused regression coverage. Keep Go implementation, caller switching, and fallback removal in their separate issues. No further split is needed for the configuration-only piece.

Definition of done

The definition of done for #753 (Feature). Tick each item and give its evidence.

Boxes indicate planning coverage, not completed work. None is fully covered by the reviewed issue text.

Round: 1 of 3

Refinement: NOT READY — rollout evidence, regression coverage, and completion contract remain incomplete
Model: gpt-6.1-sol

Checked

Read live #753, its Round 1 comment once, and named issues #588, #754, #755 and #756. Verified the independent clone’s origin identifies tbhb-dev/devtools. Repository references below describe origin/main at f130498bd7383fe02f8b9d21965f555866abd98c.

Round 1 findings:

Partly resolved — conflicting scope and implementation prescriptions. “Non-goal: a Go port” removes the unrelated subcommand, fallback and generation work. Risks and undo now concern protection changes. However, Approach still dictates pattern editing and test order, and AC3 prescribes a particular test file and case structure outside Operator authority.
Resolved — protection tier and exception. “The existing waiver for golden-only changes applies” explicitly preserves the exception, and AC1 excludes constitutional classification. This matches golden-only waiver evaluation at packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:576; constitutional findings are distinct at packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:523.
Partly resolved — coverage boundary and rollout. Scope now identifies enforcement responsibilities, dispatcher registration and excluded helpers. AC4 explicitly requires protection “before any caller switches”. Its verification still does not establish that ordering or complete dependency coverage.
Resolved — Operator authority. “The owner's exact-head review at merge” correctly recognizes protection of the configuration itself. It is both golden and constitutional at .agents/agent-skills.conf:4 and .agents/agent-skills.conf:5. No write authority is granted.
Partly resolved — verification. AC1 now names the golden finding, owner requirement and waiver outcome. AC2 adds a before/after comparison, but only for previously matching paths. Retained negative cases and stale-head approval behavior remain absent from the plan.
Unresolved — completion requirements. The live Verify plan still ends with AC-specific checks and dependency inspection. Neither build(agents): protect replacement Go enforcement paths #753 nor the named issues supplies the complete D1–D10 completion contract.

The configuration currently lacks replacement Go protection (.agents/agent-skills.conf:4, .agents/agent-skills.conf:9). Dispatcher registration is an existing enforcement surface at internal/agentrepo/command.go:85.

Gaps

Medium — Requirements still prescribe implementation. Move the pattern-editing procedure, test order, and AC3’s named test-file/case structure into the eventual pull request. Keep observable requirements in the issue: enforcement changes receive the chosen protection, dispatcher changes are included, and unrelated helpers remain outside it. Verification may name the existing suite without making its internal organization an acceptance criterion.
High — AC4’s proposed check does not prove rollout ordering. A dependency reference in a future port PR description does not establish that build(agents): protect replacement Go enforcement paths #753 merged before caller activation. The proposed refinement-time check also cannot inspect PR descriptions that do not yet exist.

Require evidence that build(agents): protect replacement Go enforcement paths #753 is merged before a dependent caller-switch change lands, and check blocker references in the dependent issues themselves. refactor(agents): port skill capability and worktree context discovery to Go #755 and refactor(agents): port the gh-post requirement adapter to Go #756 currently name build(agents): protect replacement Go enforcement paths #753 as a blocker. docs(inventory): refresh the shell migration inventory and owners #754 describes inventory work, says it has no blockers, and is incorrectly included among enforcement ports. Correct that dependency classification and state how later enforcement ports acquire the prerequisite.
Medium — Verification still omits material protection boundaries. AC2’s fixed list of previously matched paths covers positive examples only. Scope excludes helpers, and Risks claims the cases constrain excessive matching, but no negative check is planned. Retain existing deliberately unprotected cases and add representative excluded-helper checks; existing positive and negative assertions are at tests/skills/agent-merge-pr/policy.bats:346 and tests/skills/agent-merge-pr/policy.bats:397.

Explicitly retain the existing missing/current-owner, stale-head and deletion/rename checks rather than requiring duplicate tests: tests/skills/agent-merge-pr/policy.bats:109, tests/skills/agent-merge-pr/policy.bats:124, and tests/skills/agent-merge-pr/policy.bats:220. Include evidence that new protection supplies the intended owner-path signal as well as the golden finding; those outputs are computed separately at packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:508 and packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:528.
Medium — D1–D10 still lack complete planning coverage. Add a completion contract covering the checklist below. AC-indexed checks, an XS estimate and owner approval cover portions of it, but do not establish merged-head evidence, full independent review, signing, leak checks, provenance, documentation disposition, follow-up handling or closure reporting.

Split

XS, one PR remains reasonable for protection configuration and focused regression coverage. No further split is needed. Go ports and caller activation remain in their separate issues.

Definition of done

The definition of done for #753 (Feature). Tick each item and give its evidence.

Boxes indicate planning coverage, not completed work. No item is fully covered by the live issue or its named issues.

Round: 2 of 3

Refinement: NOT READY — completion coverage and AC3 still need refinement
Model: gpt-6.1-sol

Checked

Read live #753, its Round 1 comment once, and named issues #588, #754, #755 and #756. Verified the independent clone’s origin identifies tbhb-dev/devtools. Repository evidence describes origin/main at f130498bd7383fe02f8b9d21965f555866abd98c.

Round 1 findings:

Partly resolved — conflicting scope and implementation prescriptions. “Non-goal: a Go port” removes the unrelated implementation work. Approach leaves implementation choices open, and Risks concerns protection changes. AC3 still makes test construction an acceptance requirement; see Gap 1.
Resolved — protection tier and exception. “The existing waiver for golden-only changes applies” settles the exception, and AC1 excludes constitutional classification. These are distinct policy outcomes at packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:523 and packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:576.
Resolved — coverage boundary and rollout. Scope identifies enforcement responsibilities, registration and excluded helpers. “build(agents): protect replacement Go enforcement paths #753 merges before any pull request that switches a caller” establishes ordering. AC4 requires blocker references and merged-commit evidence; refactor(agents): port skill capability and worktree context discovery to Go #755 and refactor(agents): port the gh-post requirement adapter to Go #756 name build(agents): protect replacement Go enforcement paths #753 as a blocker, while docs(inventory): refresh the shell migration inventory and owners #754 is correctly excluded.
Resolved — Operator authority. “The owner's exact-head review at merge” correctly recognizes protection of the configuration itself at .agents/agent-skills.conf:4 and .agents/agent-skills.conf:5. It grants no write authority.
Resolved — behavioral verification. Verify now covers golden classification, owner requirements, the waiver, retained pattern matches, negative cases, stale approval, deletion, rename, registration and rollout. Existing approval and path-boundary evidence is at tests/skills/agent-merge-pr/policy.bats:109, tests/skills/agent-merge-pr/policy.bats:124, tests/skills/agent-merge-pr/policy.bats:220 and tests/skills/agent-merge-pr/policy.bats:346. The targeted command accepts the specified directory at mise.toml:590.
Partly resolved — completion requirements. “The independent review approves the exact merged head” and the new completion paragraph add substantial coverage, but several explicit D1–D10 obligations remain unstated; see Gap 2.

The current patterns lack replacement Go coverage at .agents/agent-skills.conf:4 and .agents/agent-skills.conf:9. Registration exists at internal/agentrepo/command.go:85. No additional scope, dependency or authority defect was found.

Gaps

Medium — AC3 prescribes test construction rather than a product outcome. Move the per-protection cases, separate registration case and red/green comparison into Verify. AC1 already requires protection of both replacement packages and registration; retain that observable behavior without prescribing how tests are organized.
Medium — The completion paragraph does not fully cover the requested definition of done. Complete the contract with:
- AC-indexed evidence verified on the merged head, using commands and results or links.
- Disposition of every independent-review finding.
- The named leak scans and review of each post.
- Explicit Assisted-by trailers and the provenance label.
- A reason when declaring no documentation impact.
- Follow-up issue content, Related references and links from deferred code.
- Closing reference, board Done state and final Status: comment naming the merge commit.
These are remaining parts of the Round 1 completion finding, not additional implementation requirements.

Split

XS, one PR remains reasonable for protection configuration and focused regression coverage. No further split is needed. Go implementation and caller activation remain in their separate issues.

Definition of done

The definition of done for #753 (Feature). Tick each item and give its evidence.

Ticks indicate planning coverage, not completed work.

Round: 3 of 3

Refinement: NOT READY — AC3 and follow-up completion coverage remain incomplete
Model: gpt-6.1-sol

Checked

Read live #753, its Round 1 comment once, and named issues #588, #754, #755 and #756. Verified the independent clone’s origin identifies tbhb-dev/devtools. Repository evidence below refers to origin/main at f130498bd7383fe02f8b9d21965f555866abd98c.

Round 1 findings:

Partly resolved — conflicting scope and implementation prescriptions. “Non-goal: a Go port” removes the unrelated port work. Approach leaves implementation choices open, and Risks concerns protection changes. AC3 still prescribes test construction; see Gap 1.
Resolved — protection tier and exception. “The existing waiver for golden-only changes applies” preserves the exception, and AC1 excludes constitutional classification. These outcomes are distinct at packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:523 and packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:576.
Resolved — coverage boundary and rollout. “build(agents): protect replacement Go enforcement paths #753 merges before any pull request that switches a caller” establishes ordering. Scope identifies enforcement responsibilities, registration and excluded helpers. AC4 requires dependent-issue blockers and merged-commit evidence. refactor(agents): port skill capability and worktree context discovery to Go #755 and refactor(agents): port the gh-post requirement adapter to Go #756 list build(agents): protect replacement Go enforcement paths #753 under Dependencies; docs(inventory): refresh the shell migration inventory and owners #754 correctly remains unblocked.
Resolved — Operator authority. “The owner's exact-head review at merge” correctly recognizes the configuration’s existing protection at .agents/agent-skills.conf:4 and .agents/agent-skills.conf:5. The issue grants no write authority.
Resolved — behavioral verification. “Missing-owner, current-owner, stale-head, deletion and rename” checks now accompany positive and negative path coverage, waiver behavior, registration and rollout evidence. Relevant existing cases appear at tests/skills/agent-merge-pr/policy.bats:109, tests/skills/agent-merge-pr/policy.bats:124, tests/skills/agent-merge-pr/policy.bats:220 and tests/skills/agent-merge-pr/policy.bats:346. The targeted suite accepts a directory argument at mise.toml:590.
Partly resolved — completion requirements. “D1 each AC is verified at the merged head” begins a substantial completion contract. Follow-up requirements and the final board state remain incomplete; see Gap 2.

Current patterns lack replacement Go coverage at .agents/agent-skills.conf:4 and .agents/agent-skills.conf:9. Dispatcher registration exists at internal/agentrepo/command.go:85. No additional dependency, size or authority defect was found.

Gaps

Medium — AC3 prescribes test construction rather than an observable protection outcome. Move its policy-case coverage and old-pattern/new-pattern comparison into Verify, which already contains those checks. AC1 supplies the observable protection requirement, including registration. Keep acceptance criteria about behavior without prescribing the test structure.
Medium — The completion contract omits parts of D9 and D10. D9 requires follow-up issues stating scope and linking build(agents): protect replacement Go enforcement paths #753, but does not require a Problem and numbered AC, listing under the PR’s Related section, or issue links from deferred code. Add those obligations and explicitly include deferred findings. D10 requires the board’s final status without identifying Done; specify that state.

Split

XS, one PR is reasonable for protection configuration and focused regression coverage. No further split is needed. Go implementation and caller activation remain separate work.

Definition of done

The definition of done for #753 (Feature). Tick each item and give its evidence.

Ticks indicate planning coverage, not completed work.

Round: 1 of 3

Refinement: READY — protection scope, rollout, and completion requirements are covered
Model: gpt-6.1-sol

Checked

Read live #753, its Round 1 findings, and named issues #588, #754, #755 and #756. Verified the independent clone’s origin identifies tbhb-dev/devtools. Repository evidence refers to origin/main at f130498bd7383fe02f8b9d21965f555866abd98c.

Round 1 findings:

Resolved — conflicting scope and implementation prescriptions. “Non-goal: a Go port” confines the change to protection. Approach leaves implementation choices open; test construction now appears in Verify.
Resolved — protection tier and exception. “The existing waiver for golden-only changes applies” preserves the exception, and AC1 excludes constitutional classification. These are distinct outcomes at packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:523 and packages/agents/source/skills/merge-pr/shared/scripts/merge-policy.py:576.
Resolved — coverage boundary and rollout. Scope names enforcement responsibilities, registration and excluded helpers. “build(agents): protect replacement Go enforcement paths #753 merges before any pull request that switches a caller” establishes ordering. AC3 requires dependency references and merged-commit evidence. Both refactor(agents): port skill capability and worktree context discovery to Go #755 and refactor(agents): port the gh-post requirement adapter to Go #756 list build(agents): protect replacement Go enforcement paths #753 under Dependencies; docs(inventory): refresh the shell migration inventory and owners #754 remains outside enforcement rollout.
Resolved — Operator authority. “The owner's exact-head review at merge” correctly recognizes protection of the configuration at .agents/agent-skills.conf:4 and .agents/agent-skills.conf:5. It grants no write authority.
Resolved — verification coverage. “Missing-owner, current-owner, stale-head, deletion and rename” checks accompany classification, waiver, retained matches, negative cases and registration coverage. Existing behavioral evidence appears at tests/skills/agent-merge-pr/policy.bats:109, tests/skills/agent-merge-pr/policy.bats:124, tests/skills/agent-merge-pr/policy.bats:220 and tests/skills/agent-merge-pr/policy.bats:346. Verify maps AC3 to dependent-issue and port-merge evidence.
Resolved — completion requirements. “Definition of done” now explicitly covers D1–D10, including follow-up issue contents, Related references, deferred-code links and board state Done.

Current patterns lack replacement Go coverage at .agents/agent-skills.conf:4 and .agents/agent-skills.conf:9. Dispatcher registration exists at internal/agentrepo/command.go:85. The proposed verification covers every AC, and no additional dependency, authority or requirements-only defect remains.

Gaps

None.

Split

XS, one PR is reasonable for protection configuration and focused regression coverage. No further split is needed. Go ports and caller activation remain separate work.

Definition of done

The definition of done for #753 (Feature). Tick each item and give its evidence.

Ticks indicate planning coverage, not completed work.

Round: 2 of 3

build(agents): protect replacement Go enforcement paths

test(agents): pin the pre-replacement protection baseline

build(agents): protect replacement Go enforcement paths

test(agents): pin the pre-replacement protection baseline

build(agents): protect replacement Go enforcement paths #753

Description

Problem

Acceptance criteria

Scope and non-goals

Approach

Dependencies

Size

Verify plan

Risks

Operator authority

Activity

tbhb-agent commented on Oct 26, 2026

Checked

Gaps

Split

Definition of done

tbhb-agent commented on Oct 26, 2026

Checked

Gaps

Split

Definition of done

tbhb-agent commented on Oct 26, 2026

Checked

Gaps

Split

Definition of done

tbhb-agent commented on Oct 26, 2026

Checked

Gaps

Split

Definition of done

tbhb-agent commented on Oct 26, 2026

Checked

Gaps

Split

Definition of done

43 remaining items

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions