feat: worktree-native workspace for parallel branch work

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