refactor(leaks): port publication-scoped scans to Go

Problem

Part of #588. This is the publication commit-addition slice of #329, dependent on #817 for the whole-object and shared push-selection boundary.

At origin/main (a0347a715fab580ece45edfcb3d13509620459a8), publication scans have a distinct matching and selection contract (.devtools/scripts/check-leaks.sh:494, .devtools/scripts/check-leaks.sh:631, .devtools/scripts/check-leaks.sh:716). They check committed additions after an explicit base, use that base's pattern policy, and compare changed binary occurrences. Moving only the whole-object scanner in #817 would leave this publication enforcement behind.

Acceptance criteria

AC1: Publication requires the supplied DEVTOOLS_LEAK_BASE to resolve to a readable commit and requires complete history; its pattern rules and path allowances come from that base, never the checkout or index under review.
AC2: Every selected commit's full metadata retains its current findings, including messages and author/committer data, even if later commits remove the value from file contents.
AC3: Added text and new path names retain the frozen shell's publication findings and locations, including rename targets, empty files, deletion followed by re-addition and merge changes; removed base content cannot cancel an added-text finding.
AC4: Changed binaries tolerate inherited occurrences and reject new occurrences according to the existing per-rule and matched-value contract, including overlapping matches, anchored and empty matches, renamed binaries and documentation-domain exceptions.
AC5: Publication results depend on committed bytes, not staged or unstaged removals, and remain unchanged by diff presentation settings or attributes that would otherwise hide content or shift reported lines.
AC6: For each supplied tip that resolves to a commit, publication-scoped pushes scan the commits reachable from that tip but not from the explicit base, regardless of destination-known history.
AC7: Publication-scoped pushes preserve refactor(leaks): port whole-object range and push scans to Go #817 AC2, AC3, AC4, AC5, AC6, AC7 and AC8 for the shared whole-object and push-selection boundary.
AC8: Publication results retain statuses 0/1/2, stream placement, ordering, numbered text or binary locations and opaque sensitive names; incomplete input fails instead of passing, and values and their escaped display forms never appear in output.
AC9: Non-functional: existing consumer entry points end as thin shell wrappers that probe Go subcommand support without writes or consuming input, use the frozen shell unchanged when binary or capability is absent, and preserve supported execution's streams and status without fallback or repeat execution after failure.
AC10: Non-functional: the Go path works on Linux, macOS and Windows while preserving N-2 consumer configuration and the current task's explicit-versus-default mode selection.
AC11: Non-functional: adoption documentation describes the unchanged distinction between publication additions, staged comparison and whole-object scans, including compatibility fallback and rollback.
AC12: Non-functional: no temporary matched content remains after success or failure.

Scope and non-goals

In scope: --publish and base-relative commit scanning under DEVTOOLS_LEAK_MODE=publish, including task invocation. Hook wiring means only --pre-push and --pre-push-hook mode handling; it excludes hook installation. #817 owns the shared whole-object and push-selection boundary; AC7 requires compatibility with its final AC2, AC3, AC4, AC5, AC6, AC7 and AC8 rather than a second definition here. Source evidence includes .devtools/scripts/check-leaks.sh:549, .devtools/scripts/check-leaks.sh:620, .devtools/scripts/check-leaks.sh:716, .devtools/scripts/check-leaks.sh:770, .devtools/scripts/check-leaks.sh:862 and .devtools/tasks/leaks.toml:6. PR publication currently invokes this scope at packages/agents/source/skills/pr/shared/scripts/create-pr.sh:190.

Coverage: .devtools/scripts/check-leaks.bats:151; publication matching cases from .devtools/scripts/check-leaks.bats:1774 up to, but excluding, the test starting at .devtools/scripts/check-leaks.bats:1885, which belongs to #817 together with the cases at .devtools/scripts/check-leaks.bats:1890 and .devtools/scripts/check-leaks.bats:1913; and base, isolation, task and binary cases from .devtools/scripts/check-leaks.bats:1932 through the test starting at .devtools/scripts/check-leaks.bats:2095. Shared whole-object and tag cases belong to #817. Caller regressions start at tests/skills/pr/scripts/pr-workflow.bats:621, tests/skills/pr/scripts/pr-workflow.bats:633, tests/skills/pr/scripts/pr-workflow.bats:642, tests/skills/pr/scripts/pr-workflow.bats:650, tests/skills/pr/scripts/pr-workflow.bats:658 and tests/skills/pr/scripts/pr-workflow.bats:680; they verify unchanged publication invocation, not new PR workflow behavior.

Overlap: preserve origin/main's exported *_PRIVATE_STRINGS handling and existing incomplete-input refusal. All #501 behavior changes remain non-goals: worktree/machine source resolution, precedence, fail-closed checks for unreadable configured sources, source notices and provisioning. All #551/#573 behavior changes remain non-goals: devtools:gitleaks local/ci mode selection, origin base resolution, full-index snapshot scanning, caller changes and local history reduction. This port closes none of those issues.

Non-goals: changing the inherited-value policy, adding a publication base resolver, changing PR review/cache/write authority, narrowing CI, .devtools/scripts/install-pre-push.sh and hook installation (#819), the shared-hooks work in #277, recursively scanning submodules or broadening detection beyond the existing literal limitations. #277 is not a blocker for this mode-handling scope. Whole-object behavior, tag payloads, ref-line parsing, OID widths, destination discovery and zero-line hook/manual selection remain owned by #817; this issue only verifies their unchanged integration under AC7. Removing the frozen compatibility path requires separate N-2 follow-up work under D9.

Approach

Port the scoped requirements to Go while retaining the frozen shell compatibility behavior and #817's shared contract. Implementation choices remain open within these requirements.

Dependencies

Blocked by #753 before replacement activation; cite the merged protection evidence. #817 is a prerequisite for the shared boundary used by AC7; verify its final AC2, AC3, AC4, AC5, AC6, AC7 and AC8. #329 tracks the containing migration. #819 owns the installer, and #277 is not a dependency of this issue. #501 and #551/#573 retain the exclusions above. #661 governs N-2 compatibility; #333 owns binary distribution without creating a higher minimum pin for this port.

Size

M. One pull request for publication commit additions and task/mode handling using #817's shared boundary; no installer work.

Verify plan

Write failing Go cases for an added text occurrence, a changed binary's new matched value and base-relative selection independent of destination history first. Port the publication-specific Bats cases before reducing their shell coverage; retain #817's shared regression coverage.

AC1: missing, invalid and unreadable base, shallow history, unreadable base policy and attempted weakening of base patterns/allowances in both checkout and index. Compare accepted base forms and outcomes with the frozen shell; do not introduce the gitleaks resolver from fix(leaks): scope local gates to branch history and the staged tree #551.
AC2, AC3: inherited base values, unrelated edits, commit metadata, additions later removed, removed-and-added occurrences, renames into private names, deletion/re-addition, empty files, symlinks, gitlinks and merge changes. Compare exact commit/path/line findings and absence of inherited-only text findings.
AC4: unchanged inherited binary matches; extra occurrences; equal category counts with different matched values; anchored and zero-length patterns; overlapping literal and pattern occurrences; rename plus modification; and exempt documentation names followed by a real match. Compare counts, rule labels and binary locations with the frozen shell.
AC5: staged and unstaged removal of committed findings, binary attributes, size thresholds, external diff settings, context and inter-hunk overrides, and unreadable diff-order settings, independently and combined; the same committed finding and line remain.
AC6: multiple commit tips and a destination that already knows commits after the publication base. Assert that each tip retains its full base-relative commit-addition findings; destination exclusions must not reduce that commit selection.
AC7: run refactor(leaks): port whole-object range and push scans to Go #817's shared regression fixtures in publication mode and cite their evidence against refactor(leaks): port whole-object range and push scans to Go #817 AC2, AC3, AC4, AC5, AC6, AC7 and AC8. Verify integration with publication commit results without changing or duplicating that boundary's requirements or claiming its Bats cases.
AC8: missing blobs, failed Git operations and incomplete producer output, sensitive names with newlines/backslashes, and a configured literal matching the escaped display form. Capture streams separately, compare statuses and order and search for all synthetic values and escaped forms.
AC12: assert temporary matched content is removed after success and each failure class.
AC9: real entry-point fixtures with absent binary/capability, supported clean/finding/error results and output-then-error; probe must preserve ref input and arguments, supported failure must run once with no fallback, and operational probe errors must refuse.
AC10: unchanged task defaults, explicit range unaffected by publication defaults, scoped hook input, native platform tests and N-2 fixtures; shell parity where available. Record the same 100-commit publication fixture over 20 warm process runs for each implementation, excluding builds, and investigate regressions.
AC11: compare help/adoption text with the exercised entry points and verify rollback in a disposable fixture.
Run mise run test-leaks and the affected PR workflow regressions with the branch binary, then mise run check, fresh coverage and both coverage-floor tasks. Check build(agents): protect replacement Go enforcement paths #753's enforcement and registration protection. If maintained skill sources change, run generation, token measurement and deployment in order and mise run check-generated-skills.
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

Binary category totals can conceal newly introduced values, and display escaping can itself expose a configured literal. Current regression cases cover both. Confusing destination-relative objects with base-relative commit additions can silently narrow a scoped push. Undo: revert this PR to restore the frozen publication path and its callers.

Operator authority

standing rule names the operator: #753 must protect replacement enforcement before activation, with its required exact-head owner review; existing publication and merge authority remain required. The thin-wrapper migration requirement follows #329 and #588.

Refinement: NOT READY — #817 and #818 both define the whole-object push boundary, and #277 disposition is unrecorded
Model: gemini-4-argon-high

Checked

Verified in an independent clone that origin identifies tbhb-dev/devtools and origin/main resolves to a0347a715fab580ece45edfcb3d13509620459a8.
Read live tbhb-dev/devtools#818 (open, Feature, label change:feat, zero comments) and the issues named by its body or required by the refinement check: #329, #588, #817, #501, #551, #573, #753, #661, #333, and #277.
Verified all origin/main source and test references in #818:
- .devtools/scripts/check-leaks.sh:494 (scan_publish header and stream/decoder contract through .devtools/scripts/check-leaks.sh:618), .devtools/scripts/check-leaks.sh:549 (count_matches binary per-rule and matched-value counting), .devtools/scripts/check-leaks.sh:620 (publish_diff environment/config isolation), .devtools/scripts/check-leaks.sh:631 (emit_publish), .devtools/scripts/check-leaks.sh:672 (emit_publish_pre_push), .devtools/scripts/check-leaks.sh:770 (base-pinned .leak-allow and .leak-patterns resolution through .devtools/scripts/check-leaks.sh:812), and .devtools/scripts/check-leaks.sh:862 (publication stream and whole-object stream dispatch through .devtools/scripts/check-leaks.sh:872).
- .devtools/tasks/leaks.toml:6 (devtools:lint-leaks mapping DEVTOOLS_LEAK_MODE=publish to --publish when invoked with zero positional arguments).
- packages/agents/source/skills/pr/shared/scripts/create-pr.sh:190 (invoking devtools:lint-leaks under DEVTOOLS_LEAK_MODE=publish and DEVTOOLS_LEAK_BASE=$leak_base, alongside create-pr.sh:193 and create-pr.sh:207).
- .devtools/scripts/check-leaks.bats:151 (mode-spanning documentation tailnet domain test) and .devtools/scripts/check-leaks.bats:1774 through .devtools/scripts/check-leaks.bats:2095 (extending to .devtools/scripts/check-leaks.bats:2104).
- tests/skills/pr/scripts/pr-workflow.bats:626, tests/skills/pr/scripts/pr-workflow.bats:654, and tests/skills/pr/scripts/pr-workflow.bats:663 (lines inside the publication caller regression tests starting at tests/skills/pr/scripts/pr-workflow.bats:621, :650, and :658).
Checked whole-object boundary ownership between tbhb-dev/devtools#817 and tbhb-dev/devtools#818: both issues currently define the whole-object tag/non-commit payload and pre-push ref-line/destination-selection boundary without referencing each other (Gap 1).
Checked that #501 and #551/#573 behavior changes remain non-goals: #818 keeps #501's worktree/machine source resolution, fail-closed configured-source checks, source notices, and provisioning in #501, and keeps #551/#573's devtools:gitleaks --mode local/--mode ci, origin base resolver, full-index snapshot scan, and local history reduction in #551 (with minor wording cleanup noted in Gap 3).
Checked tbhb-dev/devtools#277 (cited as a pre-push installer prerequisite by parent #329): #277 is open with labels: [] (not refinement:ready and not done; its Round 1 refinement comment is Refinement: NOT READY), and #818 does not state #277's disposition relative to #818's claimed hook wiring (Gap 2).
Checked Operator authority against .agents/agent-skills.conf:4-9 and tbhb-dev/devtools#753: #818 accurately records that #753 must protect the replacement Go enforcement and agentrepo subcommand registration paths before activation, with exact-head owner review required, and that existing publication and merge authority remain required.

Gaps

Blocker — #817 and #818 both define the whole-object and pre-push ref/destination boundary without one owning it and the other referencing it.
At origin/main, emit_publish_pre_push (.devtools/scripts/check-leaks.sh:672-726) and the dispatcher (.devtools/scripts/check-leaks.sh:865-869) reuse emit_objects (.devtools/scripts/check-leaks.sh:352-411) and scan (.devtools/scripts/check-leaks.sh:134-247) for ref names, non-commit push tips, and outgoing tag/non-commit payloads, while duplicating emit_pre_push's ref-line validation and git ls-remote destination selection (.devtools/scripts/check-leaks.sh:443-492). Currently, #817 (AC2–AC8, Coverage at .devtools/scripts/check-leaks.bats:1890 and .devtools/scripts/check-leaks.bats:1913) and #818 (AC6, AC7, Scope and non-goals covering .devtools/scripts/check-leaks.bats:1774 through :2095 and "Whole-object path-association quirks stay unchanged wherever that scan is reused", and Verify plan for AC6, AC7) both specify the whole-object tag/payload and pre-push ref-line/destination contract, and neither issue names the other.
Action: Have #817 own the whole-object scanning boundary (and shared push ref-line/destination discovery), and update #818 (Problem, AC6, AC7, Scope and non-goals, Dependencies, and Verify plan) to reference #817 explicitly, list #817 in Dependencies, and scope #818 to the publication commit-addition contract (--publish and base-relative commit scanning in DEVTOOLS_LEAK_MODE=publish) plus delegating ref names and outgoing non-commit/tag objects during scoped pushes to #817's boundary.
Blocker — tbhb-dev/devtools#277 is neither refinement:ready nor done, and #818 leaves its pre-push hook boundary ambiguous relative to #329 and #277.
Parent #329 states that the pre-push installer needs the shared-hooks fix from #277. Live #277 is open with no refinement:ready label and a Refinement: NOT READY Round 1 review. Meanwhile, #818 states under Size that it covers the publication scan contract and its task and hook wiring while listing installing hooks under Non-goals, without mentioning #277 or .devtools/scripts/install-pre-push.sh:72-74.
Action: Clarify in #818's Scope and non-goals, Dependencies, and Size whether "hook wiring" means only the --pre-push / --pre-push-hook mode handling under DEVTOOLS_LEAK_MODE=publish in .devtools/scripts/check-leaks.sh:778,847-850 (leaving .devtools/scripts/install-pre-push.sh and #277 out of scope for #818), or, if #818 touches .devtools/scripts/install-pre-push.sh, list #277 as a blocker and wait until #277 is refinement:ready or done.
Minor (non-blocking) — tighten #501 and #551/#573 non-goal wording and pr-workflow.bats line citations in Scope and non-goals.
- Scope and non-goals says AC2 to AC4 and AC8 absorb #501's retained private-list matching and incomplete-input refusal for this mode. That behavior already exists at origin/main (.devtools/scripts/check-leaks.sh:116-127,514-520,613), whereas #501 is strictly about loading private strings across worktrees/machine refs, failing closed on unreadable configured sources, and reporting the source. Reword Overlap and Non-goals to state directly that #818 preserves origin/main's exported *_PRIVATE_STRINGS handling while all #501 and #551/#573 behavior changes remain non-goals.
- tests/skills/pr/scripts/pr-workflow.bats:626, :654, and :663 point inside test bodies rather than the @test declarations at tests/skills/pr/scripts/pr-workflow.bats:621, :633, :642, :650, :658, and :680.
Minor (non-blocking) — AC9 prescribes a specific probing mechanism not named in #818's Operator authority.
AC9 requires thin shell wrappers (the operator port rule recorded in #329 and #588), but also prescribes the specific mechanism (that probe Go subcommand support without writes or consuming input). Either cite the #329/#588 thin-wrapper operator rule in #818's Operator authority and keep AC9 focused on observable N-2 fallback and single-execution stream/status behavior, or move the subcommand-probe mechanism note to Approach.

Split

No further split of #818 is needed (Size: M, one PR) once #818 references #817 as the owner of the whole-object boundary and keeps hook installation (.devtools/scripts/install-pre-push.sh and #277) out of scope.

Definition of done

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

A ticked box below indicates planning coverage in the issue's acceptance criteria and verification plan, not completed work.

Round: 1 of 3

Refinement: READY — publication commit-addition boundary, #817 delegation, and #277/#819 exclusions are clear and verifiable
Model: gemini-4-argon-high

Checked

Verified in an independent clone that origin identifies tbhb-dev/devtools and origin/main resolves to a0347a715fab580ece45edfcb3d13509620459a8.
Read live tbhb-dev/devtools#818 (open, Feature, label change:feat, Round 1 refinement comment) and every issue named in its body: #588, #329, #817 (and its Round 1 comment), #819, #277, #501, #551, #573, #753, #661, and #333.
Verified all origin/main path:line claims in #818:
- .devtools/scripts/check-leaks.sh:494 (scan_publish header and stream/decoder contract through .devtools/scripts/check-leaks.sh:618), .devtools/scripts/check-leaks.sh:549 (count_matches per-rule and matched-value binary counting through .devtools/scripts/check-leaks.sh:581), .devtools/scripts/check-leaks.sh:620 (publish_diff diff-setting isolation through .devtools/scripts/check-leaks.sh:629), .devtools/scripts/check-leaks.sh:631 (emit_publish through .devtools/scripts/check-leaks.sh:670), .devtools/scripts/check-leaks.sh:716 (emit_publish_pre_push commit-tip versus whole-object split inside .devtools/scripts/check-leaks.sh:672-726), .devtools/scripts/check-leaks.sh:770 (base-pinned .leak-allow and .leak-patterns resolution through .devtools/scripts/check-leaks.sh:812), and .devtools/scripts/check-leaks.sh:862 (publication stream and whole-object stream dispatch through .devtools/scripts/check-leaks.sh:878).
- .devtools/tasks/leaks.toml:6 (devtools:lint-leaks mapping DEVTOOLS_LEAK_MODE=publish to --publish when invoked with zero positional arguments).
- packages/agents/source/skills/pr/shared/scripts/create-pr.sh:190 (publication leak gate invocation alongside packages/agents/source/skills/pr/shared/scripts/create-pr.sh:189, :193, and :207).
- tests/skills/pr/scripts/pr-workflow.bats:621, tests/skills/pr/scripts/pr-workflow.bats:633, tests/skills/pr/scripts/pr-workflow.bats:642, tests/skills/pr/scripts/pr-workflow.bats:650, tests/skills/pr/scripts/pr-workflow.bats:658, and tests/skills/pr/scripts/pr-workflow.bats:680 (exact @test lines for publication caller regressions).
- .devtools/scripts/check-leaks.bats:151, .devtools/scripts/check-leaks.bats:1774 through .devtools/scripts/check-leaks.bats:1889, .devtools/scripts/check-leaks.bats:1890, .devtools/scripts/check-leaks.bats:1913, and .devtools/scripts/check-leaks.bats:1932 through .devtools/scripts/check-leaks.bats:2104 (the test starting at .devtools/scripts/check-leaks.bats:2095). Note that .devtools/scripts/check-leaks.bats:1885 (@test "AC2 an added binary file is named by the binary marker") exercises publish_finding (run_check --publish) rather than tag objects, so it is part of the publication-specific Bats cases covered by #818 AC4, AC8, and Verify plan ("Port the publication-specific Bats cases before reducing their shell coverage"), while #817 claims the shared tag cases at .devtools/scripts/check-leaks.bats:1890 and .devtools/scripts/check-leaks.bats:1913; there is no overlap between #817 and #818.
Checked Round 1 gaps:
- Boundary with #817: #817 owns the whole-object and shared push-selection boundary (#817 AC2–AC8), while #818 owns the publication commit-addition contract (AC1–AC6, AC8), cites #817 AC2, AC3, AC4, AC5, AC6, AC7, and AC8 in AC7, Scope and non-goals, Dependencies, and Verify plan, and lists #817 as a prerequisite.
- Disposition of #277 and #819: #818 defines hook wiring as --pre-push and --pre-push-hook mode handling only, excludes .devtools/scripts/install-pre-push.sh and hook installation (owned by #819), and records that #277 is not a dependency or blocker for this scope.
- Non-goal boundaries with #501 and #551/#573: Scope and non-goals and Dependencies preserve origin/main's exported *_PRIVATE_STRINGS handling and incomplete-input refusal while keeping all #501 and #551/#573 behavior changes out of scope.
- Operator authority: cites #753 (exact-head owner review for protected replacement enforcement and registration paths under .agents/agent-skills.conf:4-9), existing publication and merge authority, and the thin-wrapper migration requirement from #329 and #588.
Checked AC1–AC12 and Verify plan: every AC is observable, testable, scoped to one outcome, free of unapproved implementation prescriptions, covers non-functional requirements (AC9–AC12), and has a concrete verification check in Verify plan.

Gaps

None

Split

No further split is needed. #818 is sized M (one pull request) covering publication commit-addition scanning and task/mode handling on top of #817's shared whole-object and push-selection boundary, with pre-push hook installation separated into #819.

Definition of done

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

A ticked box below indicates planning coverage in the issue's acceptance criteria and verification plan, not completed work.

Round: 2 of 3

Navigation Menu

Repository navigation

refactor(leaks): port publication-scoped scans to Go #818

Problem

Acceptance criteria

Scope and non-goals

Approach

Dependencies

Size

Verify plan

Risks

Operator authority

Checked

Gaps

Split

Definition of done

Checked

Gaps

Split

Definition of done

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

refactor(leaks): port publication-scoped scans to Go #818

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

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions