Skip to content

Harden detached-first Codex worktree creation - #1499

Open
Chris0Jeky wants to merge 22 commits into
mainfrom
issue-1498/worktree-helper
Open

Harden detached-first Codex worktree creation#1499
Chris0Jeky wants to merge 22 commits into
mainfrom
issue-1498/worktree-helper

Conversation

@Chris0Jeky

@Chris0Jeky Chris0Jeky commented Jul 26, 2026

Copy link
Copy Markdown
Owner

Summary

  • preserve tracked and untracked coordinator-checkout state while creating detached issue worktrees
  • refresh explicit remote bases without local-ref shadowing, including slash-containing remotes and symbolic remote HEAD bases such as origin/HEAD
  • reject alternate, traversing, rooted, case-variant, junction-backed, symlink-backed, or uninspectable worktree roots
  • reserve the final target, validate raw target guard/initializer bytes, and emit no worker command when reviewed artifacts differ
  • keep branch creation behind an exact-target, fail-fast initializer using pinned native Git and exact worktree/base binding
  • remove an unused helper-created worktree after a late branch collision without force
  • add a disposable 28-case Windows PowerShell regression harness and enforce it in reusable docs governance
  • synchronize active protocol, runbook, root instructions, and Codex/Claude worker skills

Closes #1498

Verification

  • dotnet test backend/Taskdeck.sln -c Release (not applicable locally: no backend product behavior changed; fresh hosted required lanes pending)
  • frontend typecheck/build/vitest (not applicable locally: no frontend product behavior changed; fresh hosted required lanes pending)
  • Playwright smoke/E2E (not applicable locally: no UI behavior changed; fresh hosted required lanes pending)
  • powershell.exe -NoLogo -NoProfile -NonInteractive -File scripts/git/Test-New-CodexIssueWorktree.ps1 — 28/28
  • failure-ledger projection and synchronization tests — 11/11
  • PowerShell parser — 4/4 files, zero errors
  • .claude/settings.json and .mcp.json parse
  • mirrored Taskdeck skill validators — 4/4
  • configured agent-hook smoke
  • docs, Golden Principles, and GitHub-operations governance — 3/3
  • git diff --check origin/main...HEAD
  • DCO trailers — 22/22 exact-range commits

The 28 cases cover dirty-source preservation, detached HEAD, complete remote-name matching, remote freshness and symbolic default resolution, fully-qualified refs, guard/switch order, exact-worktree/base binding, source and target artifact bytes, PATH shim bypass, headless permission posture, missing executables, linked-worktree identity, reparse containment, tags, revision ranges, metacharacters, invalid Windows refs, dry-run missing bases, collisions, cleanup, and native Git failure diagnostics.

Documentation

  • docs/STATUS.md — required docs governance names the hosted Windows worktree-helper gate
  • docs/TESTING_GUIDE.md — canonical local invocation recorded
  • docs/IMPLEMENTATION_MASTERPLAN.md (not updated by this PR: roadmap and priorities did not change)
  • docs/WORKTREE_AGENT_PROTOCOL.md
  • docs/tooling/CODEX_AUTONOMY_RUNBOOK.md
  • root AGENTS/CLAUDE and active Codex/Claude worktree skills

Review

  • all 18 existing review threads are resolved and were revalidated after the current base refresh
  • finding-to-fix evidence and base-refresh evidence posted for exact head ccc6ddc8b5331c0fe44bfb5bba367a6622b917d1
  • fresh independent adversarial review on exact head
  • fresh Codex review on exact head

CI workflow validation

  • Required CI exact-head Windows 28-case job
  • CI Extended exact-head result
  • CodeQL exact-head result

Tracking

  • closing link remains exactly Closes #1498
  • issue and PR project Status/Priority need final merge-readiness reconciliation after hosted gates

Risk notes

  • Security impact: avoids PATH-first batch-shim reparsing and validates the actual target handoff bytes before printing commands.
  • Behavior change: creation is detached-first and state-preserving; branch creation happens only after the exact guard/initializer handoff.
  • Residual trust boundary: executable paths and helper-created artifacts are pinned/byte-checked at defined points, not continuously authenticated; same-user replacement after handoff emission remains outside this slice.
  • Cleanup uses plain git worktree remove; no force cleanup is introduced.
  • Current base 88eb6776 is merged in signed commit ccc6ddc8; fresh review and hosted gates are required before merge.

Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Self-review on exact head 4360576b4d720b5eb4d60428b0505ce5d01683a9 found and resolved all issues before opening this draft:

HIGH

  1. PATH-first Git batch shim permitted command splitting. The ignored git.cmd forwards unquoted %*; a benign metacharacter ref attempted a second command. Git ref validation is not a sufficient boundary.

MEDIUM

  1. -WhatIf broke internal native capture. Inherited WhatIfPreference suppressed temp-file redirection/cleanup and made repo discovery fail.

    • Fixed in 20e956a8: raw async process capture has no temp-file provider operations. Targeted what-if passes.
  2. Revision-set bases were accepted as one commit. rev-list -n 1 silently selected from inputs such as origin/main~1..origin/main.

    • Fixed in 20e956a8: single-revision rev-parse --verify --end-of-options plus commit-type validation. Targeted range rejection passes.
  3. Claude worker guidance oriented before the mandatory guard.

    • Fixed in 4360576b: guard, then printed native-Git switch, then orientation.
  4. The user-invocable issue-to-pr skill still switched the coordinator checkout.

    • Fixed in 4360576b: route through detached helper creation and the guarded handoff.

Verification

  • Exact-head targeted PS5 cases: what-if, git-add-failure, batch-shim-bypass, and revision-range-base — all pass.
  • Additional focused behavior cases passed during implementation, including dirty-state preservation/detached HEAD, handoff ordering, executable guard/branch sequence, metacharacter containment, and paths with spaces.
  • Failure-ledger renderer tests 11/11; three governance gates; four mirrored Taskdeck skill validators; diff check; DCO 2/2 — pass.
  • Independent pre-PR diff review found no remaining issue after these fixes.

The new hosted Windows job is intentionally the first complete 13-case run.

@Chris0Jeky

Copy link
Copy Markdown
Owner Author

@codex review

Please review exact head 4360576b4d720b5eb4d60428b0505ce5d01683a9. Focus on PowerShell 5.1 process/argument correctness, detached-first worktree safety, batch-shim containment, negative-test fidelity, active guidance consistency, and the reusable Windows CI gate. Report every severity.

@Chris0Jeky Chris0Jeky left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent adversarial review A — exact head 4360576b4d720b5eb4d60428b0505ce5d01683a9

Verdict

No findings.

  • CRITICAL: none
  • HIGH: none
  • MEDIUM: none
  • LOW: none

I reviewed the complete exact-head diff with the requested PowerShell 5.1 lens: the ProcessStartInfo argv boundary and fallback quoting, native-Git selection, exit/stdout/stderr propagation, single-commit base resolution, detached/state-preserving behavior, guard-before-branch handoff, negative-test fidelity/cleanup, mirrored worker guidance, and the reusable Windows gate.

I also re-read every existing PR conversation surface immediately before submitting this review: two top-level comments, no submitted reviews, and no review threads. The earlier self-review findings are represented by fixes in this head and have focused regression coverage; I found no unaddressed comment or bot finding.

Evidence

  • Exact-head local Windows PowerShell 5.1 full harness: 13/13 passed
  • PowerShell parser: 0 errors across helper and harness
  • git diff --check 6fd3936...4360576: passed
  • Hosted exact-head Docs Governance / Worktree Helper (Windows PowerShell): success

Residual risks / test gaps

  • The harness exercises paths containing spaces and metacharacter containment, but does not fuzz every legal Git-ref/Windows command-line edge (for example embedded quotes or trailing backslashes).
  • Abrupt process termination during worktree creation/cleanup is not fault-injected.
  • Overall merge readiness is not established by this review: at the last exact-head check, E2E Smoke / E2E Smoke was still in progress, and the PR body retains the explicit #1496-first merge-order gate.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4360576b4d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
Comment thread .claude/skills/issue-to-pr/SKILL.md
Comment thread docs/WORKTREE_AGENT_PROTOCOL.md Outdated
Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
Comment thread docs/WORKTREE_AGENT_PROTOCOL.md Outdated
@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Independent adversarial review B — exact head 4360576b4d720b5eb4d60428b0505ce5d01683a9

MEDIUM

  1. -WorktreeRoot can escape the repository containment boundary.

    scripts/git/New-CodexIssueWorktree.ps1 accepts WorktreeRoot unchanged, joins it to the repository root, and creates the resulting parent/worktree without canonicalizing or verifying containment. Values such as ..\outside, rooted paths, or unapproved in-repository roots can create a linked worktree outside the required .worktrees/ area and leave Git/filesystem state in an unintended location.

    Required fix: canonicalize repository root and target; reject traversal, rooted, and unapproved custom roots outside the permitted .worktrees subtree; add negative regressions proving no target directory or worktree registration is created.

Residual risk / gate state

  • Existing discussion was inspected before the finding.
  • Hosted 13/13 passed on this head but lacks the containment-negative cases.
  • Alternative native-Git resolution (for example Cygwin or an earlier non-batch git.exe) remains untested.
  • E2E was still running; the draft and Use verified Python launchers for agent hooks #1496-first merge-order hold remain binding.

Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Fix evidence for the MEDIUM containment finding in comment 5083711997:

  • Fix commit: ff8c54c96fb70077d9117f371ab0d873f207a30d
  • Canonicalizes the repository and requested root, rejects rooted inputs, rejects any logical root other than .worktrees, and verifies the resolved root equals the approved repository subtree before any directory or Git mutation.
  • Adds three disposable negative cases:
    • worktree-root-traversal
    • worktree-root-rooted
    • worktree-root-unapproved
  • Every negative case proves the target path stays absent and the exact git worktree list --porcelain registration set is unchanged.
  • Updates the protocol/runbook to state the helper's single approved root.

Exact-head local evidence on ff8c54c9:

  • all three containment cases pass under Windows PowerShell 5.1;
  • default dirty-state/detached success and WhatIf still pass;
  • docs, Golden Principles, and GitHub-operations governance gates pass;
  • git diff --check passes;
  • DCO trailers are present on 3/3 commits.

All review and CI evidence from 4360576b is superseded. The hosted workflow will provide the first complete 16-case run on this head.

@Chris0Jeky

Copy link
Copy Markdown
Owner Author

@codex review

Please re-review exact head ff8c54c96fb70077d9117f371ab0d873f207a30d. The prior-head review is stale. Focus especially on the new .worktrees containment validation, rooted/traversal/custom-root negative fidelity, no-registration proof, and any regression to the earlier PowerShell/native-Git safety fixes.

@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Independent adversarial re-review B — exact head ff8c54c96fb70077d9117f371ab0d873f207a30d

Verdict

This head is not clean yet. The prior lexical WorktreeRoot finding is substantially fixed, but one physical-containment gap remains, the six existing bot threads are still unresolved/current, and the PR body is stale.

HIGH

  1. The printed PowerShell handoff still proceeds after a failed guard or branch command.

    scripts/git/New-CodexIssueWorktree.ps1:229-231 still prints two independent native-command lines without checking $LASTEXITCODE. In Windows PowerShell 5.1, a nonzero child-process exit is not terminating, so a pasted sequence can run switch -c after a failed guard and create the branch in the wrong checkout; a failed switch can likewise leave subsequent work running detached. This is the still-unresolved P1 thread. Print a fail-fast handoff and exercise both failure paths as an actual sequential PowerShell invocation.

MEDIUM

  1. The containment check is lexical only and can still cross an existing reparse point.

    scripts/git/New-CodexIssueWorktree.ps1:141-170 uses Path.GetFullPath and string equality. That collapses rooted/traversal forms but does not resolve or reject a filesystem junction/symlink. If the ignored .worktrees entry already redirects outside the repository, the comparison still succeeds and lines 186/210/212 create and register the worktree through that external target.

    Reject an existing .worktrees reparse point (or resolve and prove its physical target is inside the repository) before any filesystem/Git mutation. Add a disposable junction/symlink case proving both the external target and git worktree list --porcelain remain unchanged.

  2. Five existing P2 threads remain current on this head. Commit ff8c54c9 changes only containment validation/tests and two root-contract paragraphs, so it does not address:

    Each needs a fix or an evidence-backed invalidation in its thread before the PR can be called clean.

LOW

  1. The PR body still describes the superseded head.

    It continues to say 13 cases, 2/2 DCO commits, and an awaited 13-case hosted job, while this head has 16 cases, 3 commits, and a successful exact-head Windows helper check. Refresh the verification/CI metadata and re-check linked-issue metadata after the body edit.

Prior finding disposition and evidence

  • Rooted, .. traversal, and alternate logical roots are now rejected before mutation.
  • The three new negative cases check target absence and exact worktree-registration equality.
  • The protocol and autonomy runbook now state that this helper accepts only repository .worktrees/.
  • Exact-head hosted Docs Governance / Worktree Helper (Windows PowerShell) is green.
  • I read all five top-level comments, six unresolved review threads, two submitted reviews, the PR/issue bodies, and the issue comment before posting.

Residual gate state

No broad local suite was run for this timeboxed review. Several required jobs were still in progress at the last exact-head snapshot. The PR remains draft, and its explicit #1496-first merge-order hold remains binding.

@Chris0Jeky Chris0Jeky left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent adversarial re-review A — exact head ff8c54c96fb70077d9117f371ab0d873f207a30d

The new traversal/rooted/unapproved-input checks are correctly placed before filesystem or worktree mutation, and the exact-head hosted 16-case Windows helper job is green. The head is not clean for review, however: all six existing Codex threads remain applicable, and the containment fix leaves one additional physical-path escape.

HIGH

  1. The printed PowerShell handoff is not fail-fastscripts/git/New-CodexIssueWorktree.ps1:229-231.

    A nonzero native exit does not terminate Windows PowerShell 5.1. If the guard fails because the worker is in the coordinator checkout, a pasted/runs-as-a-block handoff still reaches switch -c and can create the issue branch in the wrong checkout. If branch creation fails, later worker steps can continue on detached HEAD.

    Expected fix/test: emit explicit $LASTEXITCODE checks after both commands, or replace the pair with one fail-fast handoff script. Exercise guard failure from the coordinator and branch-collision failure, proving no wrong-checkout branch and no subsequent work.

MEDIUM

  1. Containment is lexical and can still escape through a reparse pointscripts/git/New-CodexIssueWorktree.ps1:163-170.

    Path.GetFullPath normalizes syntax but does not resolve a directory junction/symlink. If the approved .worktrees path is a reparse point to a directory outside the repository, the requested and expected strings compare equal while Git/files are created outside the containment boundary.

    Expected fix/test: reject an existing .worktrees reparse point (or resolve and verify its final physical target) before mutation; add a disposable junction/symlink regression proving no target and no registration are created.

  2. The mandatory guard still re-enters the PATH-first Git shimscripts/worktree_guard.ps1:8, printed from New-CodexIssueWorktree.ps1:230.

    The helper selects an argv-safe native Git executable, but its first printed command invokes a guard that runs & git. Under the very batch-shim condition this PR contains, the guard can fail or execute shim behavior before the pinned executable is used. The current shim case stops at helper execution and does not exercise the handoff.

    Expected fix/test: pass the selected executable into the guard (or otherwise pin it there) and run the complete guard-then-branch sequence with the failing/sentinel batch shim first on PATH.

  3. The replacement flow no longer guarantees a branch from latest main.claude/skills/issue-to-pr/SKILL.md:35-47.

    The old path pulled origin/main; the new helper only resolves the locally cached remote-tracking ref. This conflicts with the execution guide's “Branch from latest main” rule and can start work from a stale commit while appearing to use the remote base.

    Expected fix/test: refresh the explicit remote ref with the selected native Git executable without touching coordinator files/branch, or add an equally fail-closed freshness contract before resolving the commit.

  4. The canonical worker prompt omits the required branch commanddocs/WORKTREE_AGENT_PROTOCOL.md:104-116.

    Copying the template tells the worker only to run the guard, so it can implement and commit on detached HEAD. The autonomy-runbook template already includes the missing second command.

    Expected fix: add the helper's printed native-Git switch -c command as the second, post-guard prompt command.

  5. The documented Bash path cannot execute the printed branch handoffdocs/WORKTREE_AGENT_PROTOCOL.md:87-95.

    Bash is explicitly supported for the guard, but the helper emits only PowerShell syntax with a Windows path. A Bash worker cannot complete the newly mandatory second step.

    Expected fix/test: either require the entire helper handoff to run under PowerShell, or print/document and exercise a safely quoted Bash-compatible native-Git command.

LOW

  1. Annotated-tag bases regress from the previous Git behaviorscripts/git/New-CodexIssueWorktree.ps1:199-206.

    rev-parse --verify returns the annotated tag object's SHA and cat-file -t then rejects it as tag, although the previous git worktree add accepted and peeled a tag that points to a commit.

    Expected fix/test: resolve one commit via a single protected <base>^{commit} argument, or explicitly narrow and document the parameter contract; cover annotated and non-commit tags while retaining revision-range rejection.

Discussion and gate state

I re-read all five top-level comments, both submitted reviews, and all six unresolved review threads immediately before submitting this review. The six prior Codex findings above remain unresolved and non-outdated on this head. Exact-head Docs Governance / Worktree Helper (Windows PowerShell) is green; several broader exact-head jobs were still running, so merge readiness is not claimed. No broad local suite was run for this timeboxed re-review.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ff8c54c96f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/git/New-CodexIssueWorktree.ps1
Comment thread docs/WORKTREE_AGENT_PROTOCOL.md Outdated
Comment thread .claude/skills/taskdeck-worktree-issue-worker/SKILL.md Outdated
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Review-fix evidence — exact head ed238b9ed8f444c5bc6d4461ed4ac0eca3adf698

All findings from the ff8c54c9 review round are resolved in signed commits cf15853b (behavior/tests) and ed238b9e (mirrored guidance):

  • HIGH fail-through handoff and PATH-first guard Git: both PowerShell and native Git are absolute-path pinned; $? plus null-safe $LASTEXITCODE gates stop on guard, native nonzero, missing-Git, and missing-PowerShell failures.
  • MEDIUM stale origin/main: recognized remote branches are fetched by explicit refspec inside the same ShouldProcess decision as resolution and creation.
  • MEDIUM physical containment: existing non-directory, junction, symlink, or uninspectable .worktrees roots fail closed and are rechecked before git worktree add.
  • MEDIUM incomplete worker prompt / Bash mismatch: the protocol, runbook, Codex skills, and Claude skills require the complete printed PowerShell-only handoff; the generic Bash guard is scoped to worktrees that do not need detached-first branch creation.
  • LOW annotated-tag regression: exact ${BaseBranch}^{commit} peeling accepts annotated tags while revision ranges still fail.
  • LOW child-process contract: docs no longer claim a child powershell -File exports environment/location back to its parent.
  • LOW diagnostic and regression gaps: guard exit codes are now deterministic (isolated 0, main 1, non-repo/missing Git 2), ordinary non-repo errors retain the right diagnostic, and -WhatIf proves the stale remote-tracking ref is unchanged.
  • LOW stale PR body counts: updated separately to the current five signed commits and 21-case suite.

Verification on this exact tree before push:

  • powershell.exe -NoLogo -NoProfile -NonInteractive -File scripts/git/Test-New-CodexIssueWorktree.ps121/21 passed
  • failure-ledger renderer tests — 11/11 passed via py -3.14
  • four affected Taskdeck skill validators — 4/4 passed
  • docs governance, Golden Principles, and GitHub operations governance — 3/3 passed
  • git diff --check — passed
  • DCO trailers — 5/5 commits

All six Codex inline threads have a finding-to-fix reply and are resolved. Fresh exact-head review and CI are required because this push invalidates every earlier round.

@Chris0Jeky

Copy link
Copy Markdown
Owner Author

@codex review exact head ed238b9ed8f444c5bc6d4461ed4ac0eca3adf698. Please re-check the full PR after the review-fix commits; all prior review and CI evidence is superseded.

Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Exact-head CI recovery for superseded head ed238b9e:

  • Required CI run 30205938364, Windows helper job 89803879215, failed because hosted Windows PowerShell wrapped the semantic phrase not inside a git repository across whitespace in a long temporary path diagnostic.
  • The guard behavior and exit code were correct; the test compared presentation instead of normalized semantic text.
  • Fixed in signed commit 82627c8e with one shared whitespace-normalizing assertion helper, also applied to the existing native-Git stderr assertion.
  • Local exact-tree verification on 82627c8e: full Windows PowerShell harness 21/21 passed and git diff --check passed.

The failed run is understood and superseded. Fresh exact-head CI and review are required.

@Chris0Jeky

Copy link
Copy Markdown
Owner Author

@codex review

Please review exact head 82627c8ed3813aa201ac44a7124022a050b382f9. The only delta after the full review-fix head is a presentation-independent whitespace assertion for hosted Windows PowerShell diagnostics. Re-check the full PR and all current discussion; report every severity.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 82627c8ed3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated

@Chris0Jeky Chris0Jeky left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent adversarial security/docs review — exact head 82627c8ed3813aa201ac44a7124022a050b382f9

Verdict

This head is not clean: four MEDIUM findings and two LOW findings remain.

MEDIUM

  1. A refreshed remote base can be shadowed by a local refscripts/git/New-CodexIssueWorktree.ps1:224-258, especially line 249.

    For origin/main, the helper fetches into refs/remotes/origin/main but then resolves the ambiguous shorthand origin/main^{commit}. Git resolves tags, then local heads, before remote-tracking refs, so a local tag or branch named origin/main can win and detach the worktree at the wrong commit while the helper reports that it refreshed origin/main. See Git's documented refname precedence.

    Required fix/test: for a recognized remote, resolve the fully qualified refs/remotes/<remote>/<branch>^{commit}; add conflicting local tag and/or branch fixtures and prove HEAD equals the freshly fetched remote OID.

  2. Option-looking remote names are not terminated before git fetchscripts/git/New-CodexIssueWorktree.ps1:242-243.

    remote get-url -- <name> intentionally treats an option-looking name as data, but the later fetch passes $candidateRemote without --. A configured remote such as -u is consumed as a fetch option and the generated refspec becomes the repository argument; an option such as --upload-pack=... can select a program. This breaks the argv boundary the PR is intended to harden.

    Required fix/test: insert -- before the remote argument and add a safe leading-dash remote regression proving the intended remote/ref is fetched with no option interpretation or canary execution.

  3. The guard can accept a coordinator/standalone checkout under a .worktrees ancestorscripts/worktree_guard.ps1:44-53 and the resulting branch command at scripts/git/New-CodexIssueWorktree.ps1:285.

    The current guard uses substring markers only. A primary checkout such as C:/dev/.worktrees/Taskdeck therefore passes, and the printed switch -c moves that coordinator checkout instead of failing closed. This is also the current exact-head Codex thread: #1499 (comment).

    Required fix/test: verify the actual linked-worktree relationship (for example, canonical Git dir differs from the common dir) in addition to the approved path marker; add a standalone/coordinator repo nested under .worktrees and prove the handoff stops before branch creation.

  4. The headless Claude authorization contract still does not cover the printed handoffdocs/WORKTREE_AGENT_PROTOCOL.md:69-86, .claude/settings.json:10-15,51, and unresolved thread #1499 (comment).

    The committed rules allow relative powershell -File ... and git switch shapes, while the helper prints dynamically absolute & '<PowerShell>' ... and & '<Git>' switch -c ... commands. The documented --allowedTools example covers only the generic relative guard, and acceptEdits auto-approves edits/common filesystem operations—not arbitrary Git commands (permission modes). A noninteractive worker can therefore remain blocked on detached HEAD. The trust explanation also conflicts with the current statement that trust verification is disabled for ordinary -p runs (security docs).

    Required fix/test: prefer one stable reviewed relative wrapper that performs the pinned guard-plus-switch sequence and can be narrowly allowlisted; otherwise define an explicit launch authorization covering the exact whole dynamic block. Add a headless permission-contract regression and remove acceptEdits as a sufficient standalone remedy.

LOW

  1. Post-run verification contradicts preserved coordinator statedocs/WORKTREE_AGENT_PROTOCOL.md:166-170.

    The expected state says unrelated changes are absent, but this PR intentionally permits and preserves pre-existing tracked/untracked changes. That wording can pressure a coordinator to clean user-owned state.

    Required fix: require branch/status to match the pre-creation baseline, including unchanged pre-existing user changes, with no newly introduced coordinator changes.

  2. The PR body/review ledger is stale against live exact-head state.

    It still names ed238b9e for fresh review, reports DCO 5/5, and says all six inline threads are resolved. Live state is head 82627c8e, six signed commits, and two unresolved threads (the two MEDIUM threads linked above). The two other late ff8c54c9 threads—reparse-root containment and the worker-prompt branch command—now have correct fix replies and are resolved.

    Required fix: update the body to exact-head counts/evidence, address/reply to both applicable threads, resolve only after fixes, and re-check linked-issue metadata after the body edit.

Evidence

  • Read all 10 top-level comments, 13 submitted reviews, and all 10 review threads immediately before posting; 8 threads are resolved and 2 remain applicable/unresolved.
  • Local Windows PowerShell harness: 21/21 passed.
  • Four changed Taskdeck skill validators: 4/4 passed.
  • PowerShell parser checks and git diff --check 6fd39367...82627c8e: passed.
  • Exact-head hosted state: all 37 check runs completed with no failing conclusion; Windows helper, CodeQL, workflow lint, required CI, and CI Extended are green/skipped as designed.
  • DCO trailers are present on 6/6 commits.
  • No files or refs were changed by this review.

Residual risks / test gaps

  • The harness does not execute a post-helper branch-collision case where switch -c itself returns a native nonzero; the current gate appears correct, but that regression remains worth adding.
  • Native Git/PowerShell paths are pinned, not identity/hash/publisher pinned; same-path replacement remains outside this slice.
  • A same-user TOCTOU race can replace .worktrees after its last reparse check and before git worktree add.
  • Abrupt termination during worktree creation/cleanup is not fault-injected.
  • The draft and its explicit #1496-first merge-order hold remain binding; this review does not authorize merge.

@Chris0Jeky
Chris0Jeky marked this pull request as ready for review July 26, 2026 14:50
@Chris0Jeky
Chris0Jeky marked this pull request as draft July 26, 2026 14:53
@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Independent adversarial correctness review — exact head 82627c8ed3813aa201ac44a7124022a050b382f9 (base 6fd3936718b7a997d000276b38347ebd3988a5be)

Verdict

This head is not clean. I found one HIGH, one additional MEDIUM, and two LOW correctness findings. I also independently confirm the three correctness-impacting MEDIUM findings already recorded in the exact-head security/docs review.

HIGH

  1. The printed handoff is not bound to the worktree the helper createdscripts/worktree_guard.ps1:44-54, scripts/git/New-CodexIssueWorktree.ps1:282-287.

    The guard accepts any current checkout whose path contains an allowed marker. The following switch -c then runs in that current directory; the block carries no expected top-level, common Git directory, or detached base SHA from the newly created worktree. Running the block from a different genuine .worktrees checkout therefore passes the guard and creates/switches the planned issue branch in the wrong active worktree, while the intended new worktree remains detached.

    This broadens the current marker-only coordinator-checkout thread: checking only “linked worktree versus main checkout” would still accept the wrong linked worktree.

    Required fix/test: bind a stable wrapper/guard invocation to the exact canonical top-level and Git common directory (and preferably the expected detached base OID) produced by this helper, verify them immediately before branch creation, and add a second-valid-worktree negative case proving no branch or checkout state changes in either wrong checkout.

MEDIUM

  1. The active root instructions still describe the obsolete generic-guard/exported-state flowAGENTS.md:89-92, CLAUDE.md:191-198, .claude/README.md:23-28.

    The helper intentionally leaves the new worktree detached until its complete PowerShell-only handoff runs. But the repo-wide instructions still say the first command is only the generic PowerShell/Bash guard, direct workers to an exported WT_PROJECT_DIR, and in CLAUDE.md refer to an inline guard/exported variable. A worker following the highest-visibility instructions can omit branch creation, try to consume parent-shell state that a child PowerShell process cannot export, or translate only part of the required handoff.

    Required fix/test: synchronize the repo-wide Codex/Claude guidance with the detached-first complete-block contract (preserving law parity where applicable), and add a governance assertion so these entrypoints cannot drift from the protocol/worker skills again.

  2. Three MEDIUM findings from the exact-head security/docs review are independently confirmed and remain applicable:

    • after fetching a recognized remote, resolve the fully qualified refs/remotes/<remote>/<branch>^{commit}; the shorthand at line 249 can be shadowed by a same-named local tag/head;
    • terminate options before the configured remote passed to git fetch at line 243, and cover a safe leading-dash remote;
    • the headless Claude authorization contract still does not authorize the dynamically absolute guard-plus-native-Git block; use one stable, narrowly allowlisted wrapper or an explicit whole-block launch contract and regression.

    The security review's marker-only guard finding is subsumed by the broader HIGH finding above.

LOW

  1. Slug validation does not enforce its lowercase-only contractscripts/git/New-CodexIssueWorktree.ps1:198-200.

    PowerShell's -notmatch is case-insensitive, so a slug such as UpperCase passes despite the diagnostic requiring lowercase. The $ anchor also permits a final line feed.

    Required fix/test: use a case-sensitive match with an absolute end anchor (for example -cnotmatch and \z), and add uppercase/final-LF negative cases. The current Invalid_Slug test cannot catch the case bug because the underscore already makes it invalid.

  2. Two negative-test contracts remain weaker than their claimsscripts/git/Test-New-CodexIssueWorktree.ps1:427-432,533-544.

    The missing-Git guard case asserts only exit code 2, not the distinct setup diagnostic or absence of the ordinary “not inside a git repository” message. The invalid slug/branch cases assert exit/message but not unchanged target/worktree registration state as the containment cases do.

    Required fix/test: assert the setup-failure diagnostic distinction and snapshot target/registration state around invalid-input cases.

Conversation and evidence

  • Read all 10 pre-existing top-level comments, all 14 submitted reviews, and all 10 review threads immediately before posting. Eight threads were resolved; two remained unresolved/applicable: the headless authorization thread and the marker-only guard thread.
  • Local Windows PowerShell 5.1 helper harness: 21/21 passed.
  • PowerShell 5.1 parser: zero errors in the helper, harness, and guard.
  • git diff --check 6fd39367...82627c8e: passed.
  • Exact-head hosted checks were complete with no failing conclusion at the final snapshot.
  • DCO trailers: 6/6.
  • No repository files, refs, or PR code were changed by this review.

Residual gate state

The tests do not exercise wrong-valid-worktree handoff, local-ref shadowing, uppercase/final-LF slugs, or a native switch -c collision in the post-helper block. Native executable paths are pinned by path rather than identity/hash, and the reparse containment check retains a same-user check-to-use race.

This review does not authorize merge. The #1496-first merge-order hold remains binding. At posting time the PR was open and unmerged; GitHub reported it as ready-for-review rather than draft, so the coordinator should restore draft state if that transition was unintended.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 82627c8ed3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
Comment thread .github/workflows/reusable-docs-governance.yml
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Review-fix evidence — exact head 43407cbcb4c3a20dc9dbb3fa729f8579ce267bf0

All findings from the final 82627c8e security/docs review (4781983803) and correctness review (5084007633) are addressed in three signed commits:

  • 825ddaaa — exact handoff and authorization boundary
    • adds one stable relative initializer that pins native Git, runs the guard first, binds the exact helper-created worktree and detached base, and stops on every failure;
    • makes the generic guard require a real linked-worktree/common-directory relationship, so main, misleading nested-.worktrees, and the wrong valid worktree all fail before branch creation;
    • adds the narrow committed/headless wrapper permission contract and regressions; acceptEdits and disabled -p trust verification are no longer presented as standalone authorization.
  • 7a728271 — remote/input correctness
    • resolves the fully qualified refreshed remote-tracking ref, option-delimits fetch, and matches the longest complete configured remote name, including remotes containing /;
    • uses case-sensitive \z slug validation and covers uppercase/final-LF rejection;
    • strengthens invalid-input, missing-executable, collision, target, and registration-state assertions.
  • 43407cbc — active guidance and required-gate documentation
    • synchronizes AGENTS, CLAUDE, .claude/README, protocol, runbook, and five worker/orchestrator skills with the exact detached-first wrapper contract;
    • captures and compares coordinator branch/status baselines, preserving pre-existing user state;
    • records the Windows helper job and local command in STATUS/TESTING.

Exact-head local verification after push:

  • helper harness 23/23;
  • failure-ledger tests 11/11;
  • PowerShell parser 4/4, zero errors;
  • Taskdeck skill validators 4/4;
  • docs / Golden Principles / GitHub-operations governance 3/3;
  • settings JSON, 53-obligation global law parity, git diff --check, and DCO 9/9 — pass.

Finding-specific replies are posted on all four threads that were still open before this push. The PR body now matches this exact head, 23-case suite, and nine signed commits; it retains exactly Closes #1498, draft state, and the #1496-first merge-order hold. Fresh exact-head CI, two independent adversarial reviews, Codex, linked-issue verification, and thread-resolution confirmation remain required.

@Chris0Jeky

Copy link
Copy Markdown
Owner Author

@codex review

Please review exact head 43407cbcb4c3a20dc9dbb3fa729f8579ce267bf0. All prior review and CI evidence is stale. Re-check the full PR and every existing comment/thread, with emphasis on exact-worktree/base binding, linked-worktree identity, configured remote parsing and option boundaries, PowerShell 5.1 fail-closed behavior, headless permission semantics, negative-test fidelity, and guidance/hosted-gate drift. Report every severity.

@Chris0Jeky

Copy link
Copy Markdown
Owner Author

Independent adversarial security/docs review — exact head 43407cbcb4c3a20dc9dbb3fa729f8579ce267bf0 (base 6fd3936718b7a997d000276b38347ebd3988a5be)

Verdict

This head is not clean: one MEDIUM headless-permission/trust-boundary finding remains.

MEDIUM

  1. The documented headless dontAsk contract is not closed over effective local permissionsdocs/WORKTREE_AGENT_PROTOCOL.md:75-92; the new string-only regression is scripts/git/Test-New-CodexIssueWorktree.ps1:447-468.

    The protocol says that, because a linked worktree does not physically contain the gitignored .claude/settings.local.json, its worker session uses only committed permissions plus explicit launch rules; it then presents --allowedTools plus --permission-mode dontAsk as fail-closed. Current Claude Code documentation says the opposite for effective permissions: persistent approvals are saved at the main repository root through worktrees and apply to sessions in those worktrees, while local project settings have higher precedence than shared project settings (permissions, settings precedence).

    Consequently, an existing main-checkout local allow such as a broad PowerShell/Bash rule remains effective for the headless worker. dontAsk denies only commands that are not already allowed; adding --allowedTools does not make the wrapper the sole effective authorization. This leaves the claimed narrow/fail-closed handoff boundary dependent on uninspected user-local state, precisely where the protocol says it is absent.

    Required fix/test: correct the protocol to distinguish physical file location from effective worktree permissions, and do not claim a narrow fail-closed launch merely from --allowedTools + dontAsk. Define a supported clean/reviewed effective-permission launch posture (or explicitly document this as residual user-local trust), then add a regression that models a main-checkout local allow and verifies the stated contract against the effective configuration rather than only asserting documentation/settings strings.

Review evidence

  • Confirmed the remote PR head immediately before posting: 43407cbcb4c3a20dc9dbb3fa729f8579ce267bf0.
  • Read the PR body, linked issue Make the Codex worktree helper preserve user state and start detached #1498, all 11 top-level PR comments, all 24 REST review comments/replies, and all submitted reviews before reaching this independent conclusion.
  • Independently inspected the final helper, initializer, guard, full 23-case harness contract, .claude/settings.json, worker guidance, STATUS/TESTING updates, and reusable CI workflow.
  • The final code correctly addresses the prior ref-shadowing, option-delimited remote, linked-worktree identity, exact worktree/base binding, argv, and fail-fast findings.
  • Exact-head hosted state at this review: CodeQL and the Windows helper gate are green; API Integration (windows-latest) is still in progress, so CI is not yet an exact-head green merge gate.

Residual risks

  • Native Git and PowerShell executables are pinned by path, not binary identity; same-user replacement remains outside this slice.
  • The .worktrees reparse check has the documented same-user check-to-use race.
  • Abrupt termination during creation/cleanup is not fault-injected.
  • The PR remains draft and its #1496-first merge-order hold remains binding.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

foreach ($marker in $AllowedMarkers) {
$markerNormalized = $marker -replace "/", "\"
if ($normalized.Contains($markerNormalized)) {
$isAllowed = $true

P3 Badge Match allowed worktree markers case-insensitively on Windows

On Windows, the helper accepts -WorktreeRoot .WORKTREES because its root comparisons use OrdinalIgnoreCase, but this marker check uses case-sensitive String.Contains. If Git preserves the supplied casing in rev-parse --show-toplevel, the helper successfully creates the detached worktree and then its printed initializer rejects that same worktree as unrecognized; use the existing OS-specific path comparison here or require canonical casing in the helper.

AGENTS.md reference: AGENTS.md:L89-L91

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/git/Test-New-CodexIssueWorktree.ps1
Comment thread scripts/git/Test-New-CodexIssueWorktree.ps1 Outdated
Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
@Chris0Jeky

Chris0Jeky commented Jul 26, 2026

Copy link
Copy Markdown
Owner Author

Independent adversarial Git/PowerShell correctness review — exact head 43407cbcb4c3a20dc9dbb3fa729f8579ce267bf0 (base 6fd3936718b7a997d000276b38347ebd3988a5be)

Verdict

This exact head is not clean: one MEDIUM and two LOW correctness findings remain. The separately posted exact-head headless-permission finding is also still merge-blocking; the findings below are from this independent correctness pass.

MEDIUM

  1. The printed handoff re-enters PATH/command resolution for the PowerShell hostscripts/git/New-CodexIssueWorktree.ps1:298-301; the current regression only shims Git at scripts/git/Test-New-CodexIssueWorktree.ps1:471-502.

    The helper carefully carries an absolute argv-safe Git executable into the initializer, but launches that boundary through bare powershell. In a PowerShell worker this can resolve a function/alias or a PATH-first powershell.cmd/.bat before powershell.exe. A forwarding batch shim can reparse the arguments in the same way this PR already demonstrated for git.cmd; this is especially material because Git accepts metacharacters such as & in a valid branch name. The fail-fast lines only observe what that resolved command reports, so a lossy or hostile shim can run before the exact-worktree/base checks.

    Required fix/test: run the initializer through the already-running trusted host or pin and validate the intended PowerShell application without reopening a batch boundary. Add a PATH-first powershell.cmd sentinel regression using an otherwise valid metacharacter branch, and prove the sentinel/canary is never invoked and the intended initializer alone creates the branch.

LOW

  1. -WhatIf returns success for a base that cannot resolvescripts/git/New-CodexIssueWorktree.ps1:251-274; the test at scripts/git/Test-New-CodexIssueWorktree.ps1:768-785 covers only a valid base.

    Base refresh and all base lookup/type validation are inside ShouldProcess. Exact-head probe:

    powershell ... New-CodexIssueWorktree.ps1 -IssueNumber 999999 -Slug review-probe -BaseBranch refs/heads/definitely-missing-review-probe -WhatIf
    # exit 0; reports that it would create the worktree
    

    That makes the dry-run false-green even though the real command is guaranteed to fail, weakening the missing-base fail-closed contract. Validate non-mutating base facts before returning success (and use a no-ref-update remote dry-run/explicit limitation where freshness requires network access), with missing local/remote-base -WhatIf regressions that also prove refs, registrations, and targets remain unchanged.

  2. The helper and guard disagree about .worktrees casing on Windowsscripts/git/New-CodexIssueWorktree.ps1:173-193 versus scripts/worktree_guard.ps1:85-103.

    The helper deliberately accepts .WORKTREES as the approved root using OrdinalIgnoreCase, but the guard tests path markers with case-sensitive String.Contains. On Windows a newly created uppercase spelling can therefore be accepted and registered by the helper, then rejected by the first mandatory handoff. A direct exact-head guard probe with -AllowedMarkers '\.WORKTREES\' in the genuine lowercase linked worktree exits 1, demonstrating the comparison mismatch.

    Required fix/test: use the platform path comparison for marker matching (or require one exact spelling consistently in both scripts), and cover a case-variant helper-created linked worktree through the full initializer handoff.

Evidence

  • Read the PR body, linked issue Make the Codex worktree helper preserve user state and start detached #1498, all 14 top-level PR comments, all 24 REST review comments/replies, and all 19 submitted reviews before posting.
  • Remote head/base confirmed immediately before this post: 43407cbcb4c3a20dc9dbb3fa729f8579ce267bf0 / 6fd3936718b7a997d000276b38347ebd3988a5be.
  • Exact-head Windows PowerShell 5.1 helper harness: 23/23 passed.
  • Exact-object git diff --check: passed. The full exact-head harness executed successfully before concurrent uncommitted work appeared in the shared implementation worktree; production-script parser checks were zero-error, while the later test-file parser read the concurrent working copy and is not claimed as exact-head evidence.
  • Exact-head REST checks: Windows helper, CodeQL, required backend/API lanes, workflow lint, and security lanes green; E2E Smoke / E2E Smoke was still in progress at the final pre-post snapshot.
  • No repository file, ref, commit, branch, or worktree registration was changed by this review. One disposable extra probe command was blocked before execution; no probe state was created.

Residual risk / gate state

Executable paths remain identity/hash-unpinned after resolving them; same-user replacement and the documented reparse check-to-use race remain. Abrupt termination during creation/cleanup is not fault-injected. The PR remains draft and its explicit #1496-first merge-order hold remains binding; this review does not authorize merge.

Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
@Chris0Jeky
Chris0Jeky marked this pull request as ready for review July 26, 2026 23:52

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 43407cbcb4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
Comment thread scripts/git/New-CodexIssueWorktree.ps1 Outdated
…elper

Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>

# Conflicts:
#	docs/TESTING_GUIDE.md

Copy link
Copy Markdown
Owner Author

Parked gate checkpoint — 2026-07-27

PR #1499 remains at remote head 43407cbcb4c3a20dc9dbb3fa729f8579ce267bf0; nothing new was pushed. Local-only work merged current main as signed 87b53b04121d9d2c13b1016171909b1490e4a114 and prepared guard-first, target-byte, remote-default, and race-safety repairs.

The bounded full harness reached 23 passing cases, then hit a distinct functional red in target-artifact-smudge: the disposable smudge setup did not alter the checked-out target guard, so the helper exited 0 and emitted worker commands instead of rejecting the target artifact. The attempt ceiling is reached. No repair commit, later harness cases, governance pass, push, fresh review, thread resolution, or exact-head CI is claimed.

This PR is parked under #1498. Do not merge it until the target-smudge contract is repaired, the complete harness and governance matrix pass, the local work is signed/pushed, every existing finding is mapped/replied/resolved, and fresh exact-head independent/Codex reviews plus CI/CI Extended/CodeQL are green.

@Chris0Jeky Chris0Jeky moved this from Review to Blocked in Taskdeck Execution Jul 27, 2026
Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>
…elper

Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>

# Conflicts:
#	.claude/skills/taskdeck-issue-batch-orchestrator/SKILL.md
#	.codex/skills/taskdeck-issue-batch-orchestrator/SKILL.md

Copy link
Copy Markdown
Owner Author

Exact-head review-fix evidence — 0d95cef2f7cdc273513646e1c40ff03763dd3e75

All 10 previously unresolved threads are now replied to with finding-specific evidence and resolved. The signed additive branch includes the earlier local repair series, e7185fa9 for the final fail-closed behavior/tests/docs, and signed merge 0d95cef2 of current main (397ba9d2). The two merge conflicts were limited to mirrored batch-orchestrator skills; the resolution preserves both the landed structured-patch discipline and this PR's exact guard/initializer handoff.

Finding map

  • Headless authorization/effective settings: exact full-command rule, reviewed setting sources, no generic project PowerShell grant, and host-setting restoration — PASS [5]-[6].
  • Wrong checkout / independent linked-layout guard: direct standalone-under-.worktrees guard probe plus exact-target binding — PASS [8].
  • Remote names, fully qualified refs, and remote symbolic HEAD: longest-complete remote matching, option-delimited fetch, refs/... bypass, and live default resolution — PASS [1], [2], [25].
  • Exact base and artifact trust: detached-head mismatch, missing/divergent historical artifacts, raw source/target byte verification — PASS [10], [23]-[24].
  • PowerShell/Git command boundaries: already-running host plus pinned argv-safe Git under PATH-first powershell.cmd and git.cmd sentinels — PASS [7].
  • Required Windows gate documentation: STATUS/TESTING and workflow contract retained; docs governance green.

Reproduced blocker and repair

The old target-artifact-smudge fixture used cmd /c, which Git-for-Windows invoked such that the guard was consumed as commands from stdin. The filter exited 2; because it was non-required, Git wrote the original bytes and the helper correctly saw no mismatch. The repaired fixture uses deterministic Git clean/smudge commands: smudge emits the guard object id, clean maps it back to the reviewed blob so the disposable worktree remains removable without --force. PASS [24] proves mismatch rejection plus target and registration cleanup.

Final local verification after the base merge

  • helper harness: 28/28
  • failure-ledger projection/synchronization: 11/11
  • PowerShell parser: 4/4
  • mirrored Taskdeck skill validators: 4/4
  • configured agent-hook smoke: pass
  • settings and MCP JSON: pass
  • docs / Golden Principles / GitHub-operations governance: 3/3
  • git diff --check origin/main...HEAD: pass
  • DCO across the exact PR range: 21/21
  • worktree: clean

Fresh exact-head independent review, Codex review, and hosted CI/CI Extended/CodeQL are now required; this comment does not authorize merge.

…elper

Signed-off-by: Chris0Jeky <jeky.tck@gmail.com>

Copy link
Copy Markdown
Owner Author

Exact-head base-refresh evidence — ccc6ddc8b5331c0fe44bfb5bba367a6622b917d1

The current origin/main head 88eb6776ffd0ccaa5a6c87a88cbba31588dc9390 was merged additively with signed merge commit ccc6ddc8. The merge was conflict-free; the PR-owned worktree-helper changes are unchanged from the previously reviewed/fixed code.

Fresh exact-head verification after that base refresh:

  • worktree-helper regression harness: 28/28 passed
  • failure-ledger renderer/synchronization tests: 11/11 passed
  • PowerShell parser: 4/4 files, zero errors
  • settings/MCP JSON parsing: passed
  • mirrored Taskdeck skill validators: 4/4 passed
  • configured agent-hook smoke: passed
  • docs, Golden Principles, and GitHub-operations governance: 3/3 passed
  • git diff --check origin/main...HEAD: passed
  • exact-range DCO: 22/22 commits signed off
  • worktree: clean
  • all 18 existing review threads: resolved and revalidated against this base refresh

The earlier finding-to-fix replies remain applicable because the base-only merge did not alter the repaired helper/harness logic. Fresh independent and Codex reviews plus terminal hosted checks are still required before this PR is called merge-ready.

Copy link
Copy Markdown
Owner Author

@codex review

Please perform a fresh review of PR #1499 at exact head ccc6ddc8b5331c0fe44bfb5bba367a6622b917d1 against base 88eb6776ffd0ccaa5a6c87a88cbba31588dc9390. Focus on correctness, security/fail-closed behavior, dirty-source preservation, remote/ref resolution, artifact byte validation, cleanup, and whether the 28-case regression harness genuinely exercises the changed contracts. Please account for all existing discussion; all 18 prior threads are resolved.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ccc6ddc8b5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +770 to +775
$initializerAllowRule = "PowerShell($initializerInvocation)"
Write-Host "Claude Code task-scoped initializer allow rule (additive PowerShell transport):"
Write-Host "`$initializerAllowRule = @'"
Write-Host $initializerAllowRule
Write-Host "'@"
Write-Host '# Pass as one argv value: claude ... --allowedTools $initializerAllowRule'

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Authorize the required guard command for headless workers

In the documented unattended claude -p --permission-mode dontAsk flow, this is the only emitted PowerShell allow rule, but the required handoff starts with the separate guard invocation at lines 781-783. The protocol states that unmatched commands are denied under dontAsk, and .claude/settings.json no longer grants this PowerShell guard, so a headless worker cannot execute the mandated first command and never reaches the authorized initializer. Emit an exact guard rule as well, or authorize the complete six-line handoff as one bounded command.

AGENTS.md reference: AGENTS.md:L89-L92

Useful? React with 👍 / 👎.

Comment on lines +463 to +465
$removeResult = Invoke-GitCommand -Arguments @("worktree", "remove", $Worktree)
if ($removeResult.ExitCode -ne 0) {
throw "Could not remove helper-created worktree '$Worktree' after handoff verification failed (exit code $($removeResult.ExitCode)).$(Format-GitContext $removeResult.Output)"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Clean up dirty artifact-verification failures

When a checkout/smudge filter changes a target handoff artifact and its clean filter does not canonicalize those bytes back to the index blob, artifact verification fails with a Git-dirty worktree and this unforced removal refuses to delete it; git worktree -h documents -f as forcing removal of dirty or locked worktrees. The helper consequently leaves both the registered worktree and target path behind, blocking retries precisely when byte protection fires. The harness misses this because its target-smudge clean filter always reproduces the reviewed blob, making Git regard the altered checkout as clean; cleanup should safely handle a verified helper-created dirty target and the regression case should exercise that state.

Useful? React with 👍 / 👎.

Comment thread docs/TESTING_GUIDE.md
Comment on lines +1481 to +1484
- Windows `Worktree Helper (Windows PowerShell)` runs
`powershell -NoLogo -NoProfile -NonInteractive -File scripts/git/Test-New-CodexIssueWorktree.ps1`
as a 26-case harness enforcing detached-first creation, clean source helper/guard/initializer
artifacts (including local clean-filter canaries and index-hidden byte changes), independent

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Report the actual 28-case harness count

The test script's default case list contains 28 cases and the workflow invokes that full default, but this canonical testing documentation still calls it a 26-case harness; docs/STATUS.md repeats the same stale count. This misstates the required gate being reviewed, so update both canonical descriptions to 28 (or derive the count rather than duplicating it).

AGENTS.md reference: AGENTS.md:L113-L118

Useful? React with 👍 / 👎.

Comment on lines +717 to +720
if ($PSCmdlet.ShouldProcess($worktreeDir, "Refresh the base when remote and create a detached worktree from $BaseBranch")) {
if ($null -ne $candidateRemote) {
$remoteRefspec = "+refs/heads/$candidateBranch`:refs/remotes/$candidateRemote/$candidateBranch"
$fetchResult = Invoke-GitCommand -Arguments @("fetch", "--no-tags", "--no-recurse-submodules", "--", $candidateRemote, $remoteRefspec)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preflight target collisions before refreshing remote refs

When the derived .worktrees/codex-… target already exists, the helper performs this force-fetch before Reserve-WorktreeTarget detects the collision, so an invocation that is guaranteed to fail still updates the caller's remote-tracking ref. The same ordering lets -WhatIf report success for an occupied target because the reservation is inside the skipped ShouldProcess block. Restore a non-mutating target-existence preflight before remote operations and ShouldProcess, while retaining the later atomic reservation to close races.

Useful? React with 👍 / 👎.

[string]::IsNullOrWhiteSpace($commonGitDirectory.Output)) {
Exit-WithInitializerError "git switch -c failed and the unused helper-created worktree could not be scheduled for removal because Git could not resolve the common directory." 2
}
$repoRoot = Split-Path -Parent $commonGitDirectory.Output.Trim()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Bind late-collision cleanup to the actual Git directory

For a checkout initialized with --separate-git-dir, or for a submodule repository, the parent of --git-common-dir is not the repository's worktree root. This assignment therefore makes the scheduled child run git -C in an unrelated directory; it exits 128 after the initializer has already returned, silently leaving the unused worktree path and registration behind after a late branch collision. Invoke cleanup through the verified common Git directory itself or otherwise resolve an actual registered worktree instead of assuming a conventional <root>/.git layout.

AGENTS.md reference: AGENTS.md:L89-L92

Useful? React with 👍 / 👎.

Comment on lines +679 to +680
if (-not $BaseBranch.StartsWith($remotePrefix, [System.StringComparison]::Ordinal) -or
$BaseBranch.Length -le $remotePrefix.Length) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject case-variant remote shorthand before local resolution

On Windows, if the configured remote is origin but the caller supplies Origin/main, this ordinal prefix check does not recognize it as a remote base. The fallback rev-parse can nevertheless resolve a loose refs/remotes/origin/main through the case-insensitive filesystem, so the helper silently uses the stale tracking ref without performing the promised remote refresh. Canonicalize against configured remote names or reject case variants instead of allowing them to fall through as local revisions, and cover this Windows-specific resolution path in the harness.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Blocked

Development

Successfully merging this pull request may close these issues.

Make the Codex worktree helper preserve user state and start detached

1 participant