feat: worktree-native workspace for parallel branch work (#22)

* feat: worktree-native workspace for parallel branch work

Add four new abilities — workspace-worktree-add|list|remove|prune — and a
matching "workspace worktree" CLI subcommand. The workspace now stores each
branch in its own directory at <workspace>/<repo>@<branch-slug>, so multiple
agent sessions can edit different branches of the same repo simultaneously
without stepping on each other.

All existing read/write/git abilities accept the new <repo>@<branch-slug>
handle alongside bare repo names; resolution happens through Workspace::
parse_handle() and a single resolve_repo_path() call site.

Mutating ops on the primary checkout (bare <repo>) now require
allow_primary_mutation=true / --allow-primary-mutation. The default-deny
codifies the "primary tracks the deployed branch, hands off" rule that
lived as informal discipline before. Worktrees are always allowed.

clone rejects @-suffixed names; remove refuses to delete a primary that has
linked worktrees attached; git push only enforces fixed_branch on the
primary, freeing worktrees to push any branch.

Includes pure-PHP smoke test for handle parsing/slugify (tests/
smoke-worktree-handles.php, 32/32 passing) and a manual end-to-end test
plan (tests/TESTING.md). AGENTS.md generator and README updated to teach
the worktree-first workflow.

* fix: live-test fixups from dogfooding on intelligence-chubes4

Found and fixed during end-to-end testing on the intelligence-chubes4
site (DATAMACHINE_WORKSPACE_PATH=~/Developer):

- Ability callbacks now declare `array|WP_Error` return types so the
  primary-mutation guard (and other WP_Error returns) propagate cleanly
  instead of throwing a TypeError in WorkspaceAbilities::*.
- Add `--allow-primary-mutation` to the `workspace git` CLI docblock
  so WP-CLI accepts the flag.
- `workspace list` now surfaces `kind` (primary|worktree) and `repo`
  columns so the new on-disk model is visible.
- `workspace-worktree-list` allows `branch_slug` and `branch` to be
  null in its output schema (primaries have no slug; detached heads have
  no branch).
- New `external` field on worktree-list output. Worktrees outside the
  workspace path (e.g. /private/tmp/dm-worktrees/post-tracking from a
  manual `git worktree add`) now report their absolute path as the
  handle instead of a mangled relative slice.
- New `Workspace::resolve_default_base()` helper. `worktree add` defaults
  to `origin/HEAD` when --from is omitted (per design), with a safe
  fallback to plain HEAD if origin/HEAD is unset.

Live test summary on intelligence-chubes4:
- ✓ workspace list shows primary/worktree split
- ✓ worktree add data-machine-code test/smoke (created)
- ✓ worktree list discovers both in-workspace and external worktrees
- ✓ git status data-machine-code@test-smoke
- ✓ primary mutation guard fires (blocked by existing write_enabled
  policy first; both gates work)
- ✓ clone --name=foo@bar rejected (`@` reserved for worktrees)
- ✓ worktree remove cleans the directory and prunes the registry
- ✓ end-to-end on mcp-context-wporg with explicit --from=origin/main

Note: workspace read/write/edit/ls still hit the pre-existing Studio
WASM mount limitation when paths are outside the site folder. Tracked
elsewhere; unrelated to this PR.

Author: chubes4

README.md

@@ -45,18 +45,45 @@ wp datamachine-code workspace path
 wp datamachine-code workspace list
 wp datamachine-code workspace clone https://github.com/org/repo.git
 wp datamachine-code workspace show repo-name
-wp datamachine-code workspace read repo-name src/main.php
-wp datamachine-code workspace ls repo-name src/
-wp datamachine-code workspace write repo-name path/to/file.txt @content.txt
-wp datamachine-code workspace edit repo-name path/to/file.txt --old="foo" --new="bar"
+
+# Worktrees — one per branch, parallel-safe
+wp datamachine-code workspace worktree add repo-name fix/foo
+wp datamachine-code workspace worktree list
+wp datamachine-code workspace worktree remove repo-name fix/foo
+wp datamachine-code workspace worktree prune
+
+# All read/write/git ops accept either <repo> (primary) or <repo>@<branch-slug> (worktree)
+wp datamachine-code workspace read repo-name@fix-foo src/main.php
+wp datamachine-code workspace ls repo-name@fix-foo src/
+wp datamachine-code workspace write repo-name@fix-foo path/to/file.txt @content.txt
+wp datamachine-code workspace edit repo-name@fix-foo path/to/file.txt --old="foo" --new="bar"
 wp datamachine-code workspace remove repo-name
-wp datamachine-code workspace git status repo-name
-wp datamachine-code workspace git pull repo-name
-wp datamachine-code workspace git add repo-name --paths=src/file.php
-wp datamachine-code workspace git commit repo-name --message="fix: something"
-wp datamachine-code workspace git push repo-name
-wp datamachine-code workspace git log repo-name
-wp datamachine-code workspace git diff repo-name
+wp datamachine-code workspace git status repo-name@fix-foo
+wp datamachine-code workspace git pull repo-name@fix-foo
+wp datamachine-code workspace git add repo-name@fix-foo --path=src/file.php
+wp datamachine-code workspace git commit repo-name@fix-foo "fix: something"
+wp datamachine-code workspace git push repo-name@fix-foo
+wp datamachine-code workspace git log repo-name@fix-foo
+wp datamachine-code workspace git diff repo-name@fix-foo
+```
+
+### Worktrees: parallel-safe branch work
+
+The workspace is **worktree-native**. Each branch lives in its own directory at
+`<workspace>/<repo>@<branch-slug>` (slashes in branch names become dashes). Multiple
+agent sessions can edit different branches of the same repo simultaneously without
+stepping on each other.
+
+The primary checkout (bare `<repo>`) is **read-only by default** for mutating
+operations — pass `--allow-primary-mutation` to override. The default-deny is
+intentional: the primary tracks the deployed branch, and silent branch-switches
+on it are how parallel agents corrupt each other's work.
+
+```
+~/.datamachine/workspace/
+├── data-machine/                    ← primary, hands-off by default
+├── data-machine@fix-foo/            ← worktree for fix/foo
+└── data-machine@feat-bar/           ← worktree for feat/bar
 ```
 
 ## Requirements

data-machine-code.php

@@ -294,9 +294,11 @@ function datamachine_code_load_chat_tools() {
 - Discover available handlers: `{$wp} datamachine handlers list`
 
 **Code (data-machine-code):** All code changes go through the managed workspace and GitHub — never edit site files directly.
-- Workspace: `{$wp} datamachine-code workspace clone|read|write|edit|git` — clone repos, create branches, edit files, commit, and push
+- Workspace: `{$wp} datamachine-code workspace clone|worktree|read|write|edit|git` — clone repos, create per-branch worktrees, edit files, commit, and push
 - GitHub: `{$wp} datamachine-code github issues|pulls|repos|comment` — create PRs, manage issues, comment on reviews
-- **Workflow:** clone → branch → edit → commit → push → PR. The workspace is a git checkout separate from the live site.
+- **Workflow:** clone → `worktree add <repo> <branch>` → edit → commit → push → PR. Operate on the `<repo>@<branch-slug>` handle (e.g. `data-machine@fix-foo-bar`); never branch-switch the primary checkout.
+- **Why worktrees:** every parallel session gets its own checkout on disk. Multiple agents can cook features in the same repo without stepping on each other.
+- **Primary is read-only by default:** mutating ops on bare `<repo>` handles require `--allow-primary-mutation`. The primary tracks the deployed branch — leave it alone unless you really mean it.
 - **Rule:** Never modify files under `wp-content/plugins/` or `wp-content/themes/` directly. Those paths are for **reading source** only. All code changes must go through the workspace so they are tracked in git and reviewed via pull requests.
 
 **System:** `{$wp} datamachine system health|prompts|run`

docs/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to Data Machine Code will be documented in this file.
 
+## [Unreleased]
+
+### Added
+- Worktree-native workspace: each branch lives in its own directory at `<workspace>/<repo>@<branch-slug>`. Multiple agent sessions can edit different branches of the same repo simultaneously.
+- Four new abilities: `datamachine/workspace-worktree-add|list|remove|prune`.
+- New CLI subcommand: `wp datamachine-code workspace worktree add|list|remove|prune`.
+- All read/write/git abilities accept the new `<repo>@<branch-slug>` handle format alongside bare repo names.
+- Pure-PHP smoke test for handle parsing and slug generation (`tests/smoke-worktree-handles.php`).
+- Manual end-to-end test plan (`tests/TESTING.md`).
+
+### Changed
+- `clone` rejects names containing `@` — that suffix is reserved for worktrees.
+- `remove` refuses to delete a primary checkout that has linked worktrees attached.
+- `git push` only enforces the `fixed_branch` policy on the primary checkout. Worktrees may push any branch.
+- Mutating ops (`git pull|add|commit|push`) on a primary checkout require `--allow-primary-mutation` (CLI) / `allow_primary_mutation: true` (ability input). Worktrees are always allowed. Default-deny prevents parallel agents from clobbering the deployed branch.
+
 ## [0.4.0] - 2026-04-15
 
 ### Added