Skip to content

[Worktree-Based Execution] Add dedicated PAW worktree execution#292

Merged
lossyrob merged 21 commits intomainfrom
feature/worktree-based-execution
Mar 22, 2026
Merged

[Worktree-Based Execution] Add dedicated PAW worktree execution#292
lossyrob merged 21 commits intomainfrom
feature/worktree-based-execution

Conversation

@lossyrob
Copy link
Owner

@lossyrob lossyrob commented Mar 14, 2026

Closes #291

Summary

This PR adds dedicated worktree execution to PAW so a workflow can run in an isolated execution checkout while preserving the caller checkout. It hardens worktree initialization and reuse, makes execution mode a first-class contract across prompts and docs, and expands regression coverage around current-checkout and dedicated-worktree behavior.

Changes

  • add explicit worktree execution bootstrap/reuse support, including portable execution metadata plus local registry-backed reuse/recovery
  • preserve caller checkout state while routing PAW git work and .paw/work/worktree-based-execution/ artifacts through the execution checkout
  • fix remote-only target branch handling so dedicated worktrees follow the matching remote-tracking branch instead of silently recreating the branch from base
  • align agent, skill, and documentation language around the established execution checkout contract
  • strengthen regression coverage for current-checkout compatibility, worktree bootstrap/recovery, PR-strategy branch ancestry/isolation, and remote-only branch creation
  • upgrade the live integration harness to the current Copilot SDK permission contract and default live workflow runs to claude-sonnet-4.6

Testing

  • npm run lint
  • ./scripts/lint-prompting.sh agents/PAW.agent.md
  • ./scripts/lint-prompting.sh skills/paw-git-operations/SKILL.md
  • ./scripts/lint-prompting.sh skills/paw-init/SKILL.md
  • npm test
  • source .venv/bin/activate && mkdocs build --strict
  • cd tests/integration && npx tsc --noEmit
  • cd tests/integration && npx tsx --test tests/skills/*.test.ts
  • cd tests/integration && npx tsx --test tests/workflows/current-checkout-regression.test.ts tests/workflows/worktree-bootstrap.test.ts tests/workflows/git-branching.test.ts tests/workflows/worktree-pr-strategy.test.ts

Breaking Changes

None.

Deployment

  • paw.enableWorktreeExecution now defaults to true; setting it to false forces current-checkout mode and hides dedicated worktree selection.

Artifacts

Notes

  • The historical CodeResearch open questions for execution metadata, repository/worktree validation, and multi-checkout integration coverage were resolved by the shipped implementation and tests in this branch.

🐾 Generated with PAW

lossyrob and others added 14 commits March 13, 2026 13:36
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- fix remote-only target branch worktree creation
- narrow execution-checkout contract wording to initialization/reuse
- strengthen PR-strategy ancestry and isolation coverage

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@lossyrob lossyrob added the enhancement New feature or request label Mar 14, 2026
lossyrob and others added 7 commits March 14, 2026 01:33
- define repository_identity and execution_binding formats in agent/skill text
- state explicitly that CLI sessions treat them as exact WorkflowContext strings
- extend contract-content coverage for the clarified wording

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- add repo-level guidance that CLI does not execute src/
- scope worktree docs and skill contracts by platform
- remove dead-template execution-contract assertions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- replace runtime narration with direct agent instructions
- keep platform differences in templated skill sections only where needed
- update contract tests to assert semantics rather than explanatory phrasing

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Fix heading hierarchy in paw-git-operations: Execution Checkout Contract
  was breaking Strategy-Based Branching Logic's children
- Merge redundant worktree-mode bullets in PAW.agent.md and paw-git-operations
- Consolidate overlapping CLI recovery guidance in paw-init
- Token savings: PAW.agent -34, paw-git-operations -29, paw-init -92

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove incorrect restriction that worktree mode requires an explicit target
branch. paw-init already auto-derives feature/<work-id> regardless of
execution mode — the derived branch becomes the worktree target.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@lossyrob lossyrob merged commit 0ed00fc into main Mar 22, 2026
1 check passed
@lossyrob lossyrob deleted the feature/worktree-based-execution branch March 22, 2026 06:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support worktree-based PAW execution without switching the caller's branch

1 participant