Repository navigation
refactor(agents): port skill capability and worktree context discovery to Go #755
Description
Problem
The shell libraries packages/agents/source/lib/lib.sh (902 lines), agent.sh (173 lines) and worktree-ready.sh (42 lines) hold the repository, worktree, harness and session discovery that every skill uses. The logic is shell, and a masked Git failure there produces partial output that callers treat as valid.
Part of #588.
Acceptance criteria
- AC1: Given the new subcommand is absent from an older
agentrepo, when a caller needs a discovery value, then it uses the existing shell path with the same output, streams and status as today. - AC2: Given the subcommand is present and succeeds, when a caller needs a discovery value, then the Go result is used and equals the shell result on the recorded corpus.
- AC3: Given the subcommand is present and exits non-zero, when a caller needs a discovery value, then the caller refuses with a diagnostic on standard error, no value reaches standard output, and the shell path does not run.
- AC4: Given the subcommand prints complete-looking output and then exits non-zero, or prints partial output, when a caller needs a discovery value, then the caller refuses as in AC3 and never uses the printed text.
- AC5: Given a Git failure (not a repository, a failing
rev-parse, an unreadable Git directory), when any migrated value is requested, then the failure status and message reach the caller and no partial value is printed. - AC6: Given an unborn
HEAD, a worktree other than the main checkout, a harness variable set to each documented value and each precedence combination, and a path with and without a leading~/, when the values are requested, then each result equals the shell result. - AC7: Given the worktree readiness check, when mise configuration is untrusted, the trust query fails, Vale returns a status below 2, Vale reports missing styles, or Vale fails for another configuration reason, then the status, message and stream equal the shell script's. Absent configuration or tools are covered too: no
mise.tomlor.mise.toml, or nomiseon PATH, skips the trust check, and no.vale.inior novaleon PATH exits 0 without a probe. In each state and the check never changes trust, downloads anything or writes outside the state directory. - AC8: Given a consumer on an older binary, when it runs after this change, then configuration, flags, streams, statuses and state formats are unchanged and no configuration change is needed. The binary floor does not rise.
- AC9: Generated skill output is regenerated in the same PR in the documented order, and
mise run check-generated-skillspasses. - AC10: Given the scoped agent context and the digest, when
dt_agent_contextordt_digestmeets an interrupted operation, a detachedHEAD, an initial commit, a commit-only merge exception (packages/agents/source/lib/agent.sh:49), or a checksum producer that fails (including one that prints before failing,packages/agents/source/lib/lib.sh:93), then the Go path returns the same status, standard output and standard error as the shell function, and a producer failure always propagates.
Scope and non-goals
Migrates:
- repository root and Git directory discovery (
dt_root,dt_git_dir), with Git run under the pinned formatting settings - repository naming through the common Git directory, so every worktree of one clone reports the main checkout's name (
dt_repo_name) - the per-worktree state directory under the worktree's own Git directory, created on first use (
dt_state_dir) - the file digest, using SHA-256 whichever tool the host has (
dt_digest) - the commit at
HEAD, or the wordunbornbefore the first commit (dt_head) - harness detection and session identity:
DEVTOOLS_HARNESSfirst, then the Claude session variables, then the Codex thread variable, then the library's own path, thenunknown; the session id prefers the Claude value over the Codex one (dt_harness,dt_session_id) - expansion of a leading
~/in a configured path (dt_path) - the operation-in-progress and detached-
HEADchecks (dt_agent_contextinagent.sh) - the worktree readiness check (
worktree-ready.sh): untrusted mise configuration, a failed trust query, missing Vale styles, and any other Vale configuration failure
Non-goal, owned by other issues in #588: the agentrepo resolver and configuration bridge, review policy, prompts and stamps, confirmation and delegation, GitHub calls, gates, signing, and the unattended bounds and reporting.
Each migrated function keeps its current output on standard output, its diagnostics on standard error, its exit status and its side effects (the state directory creation and nothing else).
Approach
Port the discovery to tested Go behind a new agentrepo subcommand. The shell callers probe for it without writes. An older binary that lacks it keeps the frozen shell path. A supported command that fails or returns partial output refuses and never falls back. Regenerate skills from the canonical sources. Write the AC3 and AC4 cases first and watch them fail.
Dependencies
Blocked by the replacement-protection issue #753, so the new Go package falls under golden-file protection before any caller switches to it. That change takes one owner-approved edit to the pattern file, and later changes to the package take the golden-only waiver, with owner escalation kept for detected loosening and other holds. The XS follow-up that removes the shell fallback after supported-release evidence exists is tracked as #772. This issue touches a gate path, so its pull request needs exact-head owner review at merge. It grants no write authority.
Size
S: one context boundary over the existing configuration APIs.
Verify plan
- AC1: a stub
agentrepowithout the subcommand; assert the shell result and an unchanged transcript. - AC2: the recorded corpus run through the shell and the Go command, asserting equal results and that the Go path ran.
- AC3: a stub that exits non-zero; assert refusal, empty standard output and no shell invocation.
- AC4: a stub that prints a full value then exits non-zero, and one that prints a truncated value; assert refusal in both.
- AC5: failing Git stubs for each of the three conditions (not a repository, a failing
rev-parse, an unreadable Git directory); assert the nonzero status and the diagnostic reach the caller's standard error unchanged and that standard output stays empty. - AC6: the existing cases at
tests/skills/source/lib/lib.bats:166,178cover only part of the matrix, so this issue adds a table-driven Go test and a Bats case for each remaining row: unbornHEAD, a linked worktree,DEVTOOLS_HARNESSvalues,CLAUDE_CODE_SESSION_IDversusCODEX_THREAD_IDprecedence, and a leading~/. Each row runs the shell and Go paths and compares results. - AC7: stubs for mise and Vale in each state, including the untrusted result (
worktree-ready.sh:13), a failing trust query (:29), the missing-config and missing-tool exits, and each Vale failure; compare transcripts against the recorded shell results and assert no trust change, download or write outside the state directory. - AC8: run the existing cases unchanged against an older stub binary.
- AC9:
mise run generate-skills,mise run skill-tokens,apm installleave no diff;mise run check-generated-skills. - AC10: table-driven shell-versus-Go comparison of status, standard output and standard error for each refusal and the commit-only merge exception, and for a checksum producer that fails silently and one that prints before failing (extends
tests/skills/source/lib/masked-status.bats:18,23).
Risks
A fallback that runs after a supported command failed would mask an enforcement error. AC3 and AC4 pin that. Undo: revert the change.
Operator authority
None.
Activity
tbhb-agent commentedon Oct 26, 2026
Refinement: NOT READY — behavior coverage and verification need a concrete contract
Model: gpt-6.1-sol
Checked
https://github.com/tbhb-dev/devtools.git. Checkedorigin/mainatf130498bd7383fe02f8b9d21965f555866abd98c.packages/agents/source/lib/lib.sh:902,packages/agents/source/lib/agent.sh:173, andpackages/agents/source/lib/worktree-ready.sh:42.Gaps
High — Parity is asserted broadly without defining the migration boundary. “Context discovery” does not establish which behaviors in these multifunction libraries migrate and which remain out of scope. Relevant contracts include repository naming through the common Git directory, per-worktree state creation, checksum failure propagation, unborn HEAD, harness precedence, session precedence, and path expansion (
packages/agents/source/lib/lib.sh:70,packages/agents/source/lib/lib.sh:85,packages/agents/source/lib/lib.sh:93,packages/agents/source/lib/lib.sh:103,packages/agents/source/lib/lib.sh:115,packages/agents/source/lib/lib.sh:133,packages/agents/source/lib/lib.sh:270). Define the included behaviors and their outputs, streams, statuses, and side effects; explicitly exclude the remaining workflow behavior.High — AC1 combines distinct outcomes and leaves failure behavior ambiguous. Separate absent capability, available capability, failed execution, and partial output into independently observable requirements. State the refusal status, diagnostic stream, whether usable stdout may escape, and whether fallback runs. Cover complete-looking output followed by nonzero exit as well as incomplete successful output. The existing regression helper checks rejection status, not absence of leaked output (
tests/skills/source/lib/masked-status.bats:18). Preserve loader selection and version behavior explicitly (packages/agents/source/lib/lib.sh:140).High — AC2’s cited tests do not establish complete readiness parity. Existing readiness cases cover untrusted mise configuration and missing Vale styles (
tests/skills/source/lib/lib.bats:185,tests/skills/source/lib/lib.bats:204). The original also handles missing configuration/tools, trust-query failure, Vale statuses below 2, and other Vale configuration failures (packages/agents/source/lib/worktree-ready.sh:13,packages/agents/source/lib/worktree-ready.sh:29). Add observable outcomes for those branches and preserve the check’s prohibition on changing trust or downloading dependencies (packages/agents/source/lib/worktree-ready.sh:2).High — Verification does not prove every AC. “Reject partial Git output … then port the Bats cases” lacks an AC-by-AC evidence mapping. It does not demonstrate capability fallback, supported-command refusal without fallback, unchanged floor, configuration compatibility, or AC3’s generated-output consistency. Identify checks and expected results for each AC, including evidence that the new path is actually exercised. Replace complex shell with tested Go, starting with gates and merging #588 supplies general integration and generation expectations, but does not resolve this issue’s mapping. Generated consistency has an existing checkable contract (
tools/generate-skills.sh:144).Medium — The body prescribes design outside Operator authority. “A Go package that reuses the existing
agentrepo configAPIs” mandates packaging and API reuse. Retain the Go migration objective, but express configuration compatibility as requirements. Move design choices to the PR unless the operator records them as binding decisions.High — Dependency and owner authority are unresolved locally. “Protection issue … (P2)” does not identify a reviewable prerequisite, and the separate fallback-removal issue is also unnamed. Link the prerequisite and specify the protection outcome required before rollout. “Touches a gate path” correctly signals sensitivity, but does not state owner authority. The current source paths are protected (
.agents/agent-skills.conf:4,.agents/agent-skills.conf:5,.agents/agent-skills.conf:9); Replace complex shell with tested Go, starting with gates and merging #588 requires owner protections to follow replacement enforcement code. State that owner review is required and that this issue grants no operational write authority.Split
S is plausible for one PR after the boundary is explicit. The file lengths include substantial unrelated workflow behavior, so they do not establish migration size. Keep protection work as a linked prerequisite and fallback retirement as a linked follow-up. No additional split is justified by the live text alone.
Definition of done
The definition of done for #755 (Feature). Tick each item and give its evidence.
Boxes indicate planning coverage, not completed work. None is fully covered by #755 or its named parent.
D1 The author verified each AC on the merged head, and the Verification section of the pull request cites each AC ID with its evidence: the command and its result, or a link.
Evidence: Neither issue requires merged-head verification with per-AC PR evidence.
D2 An independent reviewer approved the exact merged head, and the author resolved each finding or filed it as a follow-up.
Evidence: Neither issue specifies this completion requirement.
D3 The required checks pass on that head, and any loosened gate has the owner's approval of that exact head.
Evidence: Replace complex shell with tested Go, starting with gates and merging #588 AC8 requires checks, but does not fully specify this exact-head gate-loosening requirement.
D4 The leak scans come back clean: gitleaks, devtools'
check-leaks.shwith the repository's private-strings list, and the leak review of each post.Evidence: Replace complex shell with tested Go, starting with gates and merging #588 mentions scanner gates without requiring this complete set.
D5 The author signed each commit, the squash included.
Evidence: Preserving signing behavior in Replace complex shell with tested Go, starting with gates and merging #588 does not require signing every delivery commit.
D6 The docs match the change (README,
docs/, CHANGELOG or help text), or the Verification section says "No doc impact" and why.Evidence: Neither issue specifies documentation verification or a justified exemption.
D7 The commits and the squash have Assisted-by trailers, and the pull request has the
provenance:agent-assistedlabel.Evidence: Neither issue requires these delivery artifacts.
D8 The pull request stays within the size limits, or the owner approved its exact head over the hard limit.
Evidence: The S estimate does not establish compliance with PR size limits or exception authority.
D9 The author files follow-ups and deferred findings as issues with at least a Problem and numbered AC and lists them under the Related section of the pull request. Any work left in the code links its issue.
Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 mentions fallback retirement without a linked issue or these follow-up requirements.
D10 The merge closes the issue through a closing reference and the board shows Done. The final
Status:comment names the merge commit.Evidence: Neither issue specifies this closure evidence.
Round: 1 of 3
tbhb-agent commentedon Oct 26, 2026
Refinement: NOT READY — verification still leaves required behavior unproved
Model: gpt-6.1-sol
Checked
Read the live #755 body, its Round 1 comment once, and both named issues, #588 and #753. Verified the independent clone’s origin is
https://github.com/tbhb-dev/devtools.git. Source references below are againstorigin/mainatf130498bd7383fe02f8b9d21965f555866abd98c.Round 1 findings:
Resolved — migration boundary. The scope now identifies the individual functions and excludes unrelated workflows. “Each migrated function keeps its current output” supplies the general streams, status and side-effect contract. The listed behavior matches repository naming, state creation, digest handling, harness/session precedence and path expansion in
packages/agents/source/lib/lib.sh:75,packages/agents/source/lib/lib.sh:85,packages/agents/source/lib/lib.sh:93,packages/agents/source/lib/lib.sh:115,packages/agents/source/lib/lib.sh:133andpackages/agents/source/lib/lib.sh:270.Resolved — capability and execution outcomes. AC1–AC4 separately cover absence, success, nonzero execution and partial output. “The shell path does not run” closes the fallback ambiguity. AC8 preserves compatibility and the binary floor, currently declared at
packages/agents/source/lib/lib.sh:140.Partly resolved — readiness parity. AC7 now includes trust-query failure, Vale statuses below 2 and other configuration errors, including “the trust query fails”. However, its verification still omits the original missing-configuration and missing-tool branches at
packages/agents/source/lib/worktree-ready.sh:13,packages/agents/source/lib/worktree-ready.sh:29andpackages/agents/source/lib/worktree-ready.sh:30. See Gap 1.Partly resolved — verification coverage. Every AC now has an entry, and AC2 explicitly checks “that the Go path ran”. Several entries nevertheless do not prove their complete AC, particularly AC5–AC7. See Gap 1.
Resolved — prescribed package/API design. The former packaging and API-reuse mandate has been removed. The revised requirement that “no configuration change is needed” states an observable compatibility outcome. No additional layout, library or driver decision is needed.
Partly resolved — dependencies and authority. “Blocked by the replacement-protection issue build(agents): protect replacement Go enforcement paths #753” identifies the prerequisite and protection outcome. Exact-head owner review and absence of write authority are explicit, consistent with
.agents/agent-skills.conf:4and.agents/agent-skills.conf:9. The claimed fallback-removal issue remains unidentified. See Gap 2.No additional split or implementation-design requirement is warranted.
Gaps
High — the Verify plan does not prove the full behavior contract.
The remaining omissions are concrete:
tests/skills/source/lib/lib.bats:166). Session checks cover two combinations (tests/skills/source/lib/lib.bats:178). Neither cited suite supplies the promised unborn-HEAD, linked-worktree and leading-~/parity matrix. The masked-status helper asserts rejection status alone (tests/skills/source/lib/masked-status.bats:18).packages/agents/source/lib/agent.sh:49. Digest failure propagation likewise needs an explicit place in the recorded corpus or verification mapping (packages/agents/source/lib/lib.sh:93).Action: Extend the existing verification entries with the missing fixtures and expected outcomes. Explicitly associate operation-context and digest parity with an AC and its corpus cases. Require separate status, stdout, stderr and side-effect assertions where the AC promises them. This needs observable checks, not implementation design.
Medium — the fallback-retirement dependency remains untraceable.
The Dependencies section states that a separate XS issue owns fallback removal, but supplies no issue reference. Consequently, its existence, release-evidence condition and scope cannot be checked from the named issues.
Action: Link the existing retirement issue, or describe retirement as deferred follow-up work to be filed rather than asserting an unidentified issue already owns it. Keep retirement outside this change.
Split
S remains plausible for one PR. The revised scope identifies one discovery/context boundary and retains protection work in #753. No further split is justified. Fallback retirement should remain a traceable separate follow-up.
Definition of done
The definition of done for #755 (Feature). Tick each item and give its evidence.
Boxes indicate planning coverage, not completed work. None is fully covered by the live #755 body or its named issues.
D1 The author verified each AC on the merged head, and the Verification section of the pull request cites each AC ID with its evidence: the command and its result, or a link.
Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 maps verification entries to AC IDs, but does not require merged-head verification and per-AC evidence in the PR.
D2 An independent reviewer approved the exact merged head, and the author resolved each finding or filed it as a follow-up.
Evidence: Exact-head owner review is required, but the complete independent-review and finding-resolution requirement is absent.
D3 The required checks pass on that head, and any loosened gate has the owner's approval of that exact head.
Evidence: Replace complex shell with tested Go, starting with gates and merging #588 AC8 requires checks, and refactor(agents): port skill capability and worktree context discovery to Go #755 requires exact-head owner review; the complete same-head gate-loosening condition is not stated.
D4 The leak scans come back clean: gitleaks, devtools'
check-leaks.shwith the repository's private-strings list, and the leak review of each post.Evidence: Replace complex shell with tested Go, starting with gates and merging #588 requires applicable scanner gates, without identifying this complete set.
D5 The author signed each commit, the squash included.
Evidence: Preserving signing behavior in Replace complex shell with tested Go, starting with gates and merging #588 does not require signing each delivery commit and squash.
D6 The docs match the change (README,
docs/, CHANGELOG or help text), or the Verification section says "No doc impact" and why.Evidence: The named issues do not require documentation verification or a justified exemption.
D7 The commits and the squash have Assisted-by trailers, and the pull request has the
provenance:agent-assistedlabel.Evidence: These delivery requirements are absent from the named issues.
D8 The pull request stays within the size limits, or the owner approved its exact head over the hard limit.
Evidence: The S estimate does not establish PR size-limit compliance or exception approval.
D9 The author files follow-ups and deferred findings as issues with at least a Problem and numbered AC and lists them under the Related section of the pull request. Any work left in the code links its issue.
Evidence: Fallback retirement is mentioned, but its issue is unidentified and the complete follow-up requirements are absent.
D10 The merge closes the issue through a closing reference and the board shows Done. The final
Status:comment names the merge commit.Evidence: The named issues do not specify this closure evidence.
Round: 2 of 3
tbhb-agent commentedon Oct 26, 2026
Refinement: NOT READY — scoped failure parity still lacks explicit verification coverage
Model: gpt-6.1-sol
Checked
Read the live #755 body, its Round 2 comment once, and named issues #753, #772 and #588. Verified the independent clone’s origin is
https://github.com/tbhb-dev/devtools.git. Source references are againstorigin/mainatf130498bd7383fe02f8b9d21965f555866abd98c.Round 2 findings:
Resolved — AC5 failure propagation. The Verify plan now covers all three failure conditions and requires the status and diagnostic to reach the caller “unchanged”, with empty stdout. This supplies the previously missing assertions.
Resolved — AC6 matrix. The plan explicitly adds coverage for “each remaining row” and compares shell and Go results. AC6 and Scope establish the complete harness/session precedence and path-expansion contract. Existing behavior is defined at
packages/agents/source/lib/lib.sh:104,packages/agents/source/lib/lib.sh:115,packages/agents/source/lib/lib.sh:133andpackages/agents/source/lib/lib.sh:270.Resolved — AC7 readiness branches and side effects. AC7 and its verification now include “missing-config and missing-tool exits”, transcript comparison, and assertions against trust changes, downloads and writes outside the state directory. These match the branches at
packages/agents/source/lib/worktree-ready.sh:13,packages/agents/source/lib/worktree-ready.sh:29andpackages/agents/source/lib/worktree-ready.sh:30.Partly resolved — overall verification coverage. The AC5–AC7 omissions above are repaired. However, the Round 2 finding about operation-context and digest failure parity remains: AC2 still refers only to the “recorded corpus”, without identifying these cases. See Gap 1.
Resolved — fallback retirement. Dependencies now names “tracked as refactor(agents): remove the shell fallback for discovery and worktree readiness #772”. That issue is open, explicitly depends on refactor(agents): port skill capability and worktree context discovery to Go #755, and conditions retirement on a shipped supported release and the N-2 window excluding binaries without the command.
The protection dependency is traceable: #753 AC4 requires protections to land before callers switch. #755 requires exact-head owner review and grants no write authority, consistent with
.agents/agent-skills.conf:4and.agents/agent-skills.conf:9.No additional implementation-design requirement or new blocker is warranted.
Gaps
High — the verification corpus still does not explicitly cover scoped operation-context and digest failures.
Scope includes
dt_agent_contextanddt_digest, but no verification entry identifies their failure cases. AC2 covers successful discovery; AC5 covers Git failures. Neither explicitly proves the operation-policy refusals and checksum-producer failures already called out in Round 2.The relevant observable contracts are:
packages/agents/source/lib/agent.sh:49.packages/agents/source/lib/lib.sh:93. The existing regression checks rejection status alone, rather than separate output streams (tests/skills/source/lib/masked-status.bats:18,tests/skills/source/lib/masked-status.bats:23).Action: Explicitly associate these cases with an AC and its verification corpus. Require shell/Go comparison of status, stdout and stderr for operation-context outcomes and digest failures, including a checksum producer that prints output before failing. This closes the existing verification gap without prescribing implementation design.
Split
S remains plausible for one PR. Keep replacement protection in #753 and fallback retirement in #772. No further split is justified by the live text.
Definition of done
The definition of done for #755 (Feature). Tick each item and give its evidence.
Boxes indicate planning coverage, not completed work. None is fully covered by the live body or its named issues. These checklist omissions are not additional implementation blockers.
D1 The author verified each AC on the merged head, and the Verification section of the pull request cites each AC ID with its evidence: the command and its result, or a link.
Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 maps checks to AC IDs, but does not require merged-head verification with per-AC evidence in the PR.
D2 An independent reviewer approved the exact merged head, and the author resolved each finding or filed it as a follow-up.
Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 requires exact-head owner review, but not the complete independent-review and finding-resolution requirement.
D3 The required checks pass on that head, and any loosened gate has the owner's approval of that exact head.
Evidence: Replace complex shell with tested Go, starting with gates and merging #588 AC8 requires checks and refactor(agents): port skill capability and worktree context discovery to Go #755 requires exact-head owner review; the complete same-head gate-loosening condition is absent.
D4 The leak scans come back clean: gitleaks, devtools'
check-leaks.shwith the repository's private-strings list, and the leak review of each post.Evidence: Replace complex shell with tested Go, starting with gates and merging #588 requires applicable scanner gates without specifying this complete set.
D5 The author signed each commit, the squash included.
Evidence: Replace complex shell with tested Go, starting with gates and merging #588 preserves signing behavior, but does not require signing each delivery commit and squash.
D6 The docs match the change (README,
docs/, CHANGELOG or help text), or the Verification section says "No doc impact" and why.Evidence: refactor(agents): remove the shell fallback for discovery and worktree readiness #772 requires a future migration-note update; the named issues do not establish this documentation requirement for refactor(agents): port skill capability and worktree context discovery to Go #755.
D7 The commits and the squash have Assisted-by trailers, and the pull request has the
provenance:agent-assistedlabel.Evidence: These delivery requirements are absent from the named issues.
D8 The pull request stays within the size limits, or the owner approved its exact head over the hard limit.
Evidence: The S estimate does not establish size-limit compliance or exact-head exception approval.
D9 The author files follow-ups and deferred findings as issues with at least a Problem and numbered AC and lists them under the Related section of the pull request. Any work left in the code links its issue.
Evidence: refactor(agents): remove the shell fallback for discovery and worktree readiness #772 supplies a Problem and numbered AC for fallback retirement, but the PR Related listing and code-link requirements remain unspecified.
D10 The merge closes the issue through a closing reference and the board shows Done. The final
Status:comment names the merge commit.Evidence: The named issues do not specify this closure evidence.
Round: 3 of 3
tbhb-agent commentedon Oct 26, 2026
Refinement: READY — prior verification gaps are resolved
Model: gpt-6.1-sol
Checked
Read live #755, its Round 2 comment, and named issues #753, #772 and #588. Verified the independent clone’s origin identifies
tbhb-dev/devtools. Checked source againstorigin/mainatf130498bd7383fe02f8b9d21965f555866abd98c.Round 2 findings:
Resolved — AC5 failure propagation. Verification names all three failure conditions and requires the status and diagnostic to arrive “unchanged”, with empty stdout. This covers the missing caller-level assertions. Existing discovery propagation appears at
packages/agents/source/lib/lib.sh:77andpackages/agents/source/lib/lib.sh:87.Resolved — AC6 parity matrix. The plan adds comparisons for “each remaining row”, explicitly naming unborn HEAD, linked worktrees, harness values, session precedence and leading
~/. AC6 also requires each documented harness value and precedence combination. These contracts matchpackages/agents/source/lib/lib.sh:104,packages/agents/source/lib/lib.sh:115,packages/agents/source/lib/lib.sh:133andpackages/agents/source/lib/lib.sh:270. The cited existing tests provide only partial coverage, as the body now acknowledges (tests/skills/source/lib/lib.bats:166,tests/skills/source/lib/lib.bats:178).Resolved — AC7 readiness branches and side effects. The plan includes “missing-config and missing-tool exits”, transcript comparisons, and assertions against trust changes, downloads and writes outside the state directory. AC7 specifies the skipping behavior. This matches the branches at
packages/agents/source/lib/worktree-ready.sh:13,packages/agents/source/lib/worktree-ready.sh:29,packages/agents/source/lib/worktree-ready.sh:30andpackages/agents/source/lib/worktree-ready.sh:34.Resolved — operation-context and digest verification. AC10 and its verification entry now explicitly compare status, stdout and stderr for interrupted operations, detached HEAD, initial-commit refusal, the commit-only merge exception and both checksum failure forms. These cover
packages/agents/source/lib/agent.sh:49andpackages/agents/source/lib/lib.sh:93, extending the status-only regression helper attests/skills/source/lib/masked-status.bats:18.Resolved — fallback retirement. Dependencies names “tracked as refactor(agents): remove the shell fallback for discovery and worktree readiness #772”. That issue owns removal of precisely the migrated fallback and requires both a shipped supported release and an N-2 window excluding binaries without the command.
The remaining verification mapping is sufficient: AC1–AC4 distinguish absent capability, successful Go execution, failed execution and rejected partial output; AC8 checks older-binary compatibility; AC9 checks generated consistency, supported by
tools/generate-skills.sh:144.#753 is a traceable rollout prerequisite: its AC4 requires protection to merge before callers switch and requires the port PR to cite that merge. #755 explicitly requires exact-head owner review and grants no write authority. No additional implementation-design decision or blocking defect remains.
Gaps
None.
Split
One discovery/context migration remains a plausible S-sized change. Keep replacement protection in #753 and fallback retirement in #772. No further split is warranted.
Definition of done
The definition of done for #755 (Feature). Tick each item and give its evidence.
Boxes indicate planning coverage, not completed work. The live issue and named issues do not fully cover any complete checklist item below; these omissions do not introduce implementation blockers.
D1 The author verified each AC on the merged head, and the Verification section of the pull request cites each AC ID with its evidence: the command and its result, or a link.
Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 maps checks to every AC, but does not require merged-head verification and per-AC evidence in the PR.
D2 An independent reviewer approved the exact merged head, and the author resolved each finding or filed it as a follow-up.
Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 requires exact-head owner review, without the complete independent-review and finding-resolution requirement.
D3 The required checks pass on that head, and any loosened gate has the owner's approval of that exact head.
Evidence: Replace complex shell with tested Go, starting with gates and merging #588 AC8 requires checks and refactor(agents): port skill capability and worktree context discovery to Go #755 requires exact-head owner review, but the complete same-head gate-loosening condition is not explicit.
D4 The leak scans come back clean: gitleaks, devtools'
check-leaks.shwith the repository's private-strings list, and the leak review of each post.Evidence: Replace complex shell with tested Go, starting with gates and merging #588 requires applicable scanner gates without specifying this complete set.
D5 The author signed each commit, the squash included.
Evidence: Replace complex shell with tested Go, starting with gates and merging #588 preserves signing behavior; it does not require signing every delivery commit and squash.
D6 The docs match the change (README,
docs/, CHANGELOG or help text), or the Verification section says "No doc impact" and why.Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 does not specify documentation verification or a justified exemption.
D7 The commits and the squash have Assisted-by trailers, and the pull request has the
provenance:agent-assistedlabel.Evidence: These delivery artifacts are not required by refactor(agents): port skill capability and worktree context discovery to Go #755 or its parent.
D8 The pull request stays within the size limits, or the owner approved its exact head over the hard limit.
Evidence: The S estimate does not establish size-limit compliance or exact-head exception approval.
D9 The author files follow-ups and deferred findings as issues with at least a Problem and numbered AC and lists them under the Related section of the pull request. Any work left in the code links its issue.
Evidence: refactor(agents): remove the shell fallback for discovery and worktree readiness #772 supplies a Problem and numbered AC for fallback retirement, but PR linkage and the complete deferred-finding requirements remain unspecified.
D10 The merge closes the issue through a closing reference and the board shows Done. The final
Status:comment names the merge commit.Evidence: refactor(agents): port skill capability and worktree context discovery to Go #755 does not specify these closure artifacts.
Round: 1 of 3