split projects 6/6: wf check split rules; docs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JEAjUkQRrCYX5MZhWxdtj2

3 files changed, 17 insertions, 1 deletions

diff --git a/docs/manual.md b/docs/manual.md
index 26661b6..c9f7bd1 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -238,3 +238,10 @@ wf add "Cave seams. Close the slit beside the lintel." -p 1 -e '<1h' --model son
 | A worker or batch does nothing | `wf list --runner` is empty: tasks lack a Done line (`wf batch --prep`), are blocked on an awaiting item, or wait on `After:`. `wf lanes` shows counts per lane. |
 | `wf check` errors after a hand edit | Read the message (duplicate id, broken `[[link]]`, bad section) and fix the item. Ids are never reused. |
 | `project format N is newer than this wf` | Update the tool: `git -C /projects/public/workflow pull`. |
+
+## Split projects (private home repo + public code repo)
+`code_root` in workflow.toml points at another git repo: TASKS/archive/specs stay in the private project, code goes to the
+code repo. `wf start` makes code worktrees (branch in the code repo, `.wf-home` file pointing back); `wf finish`/`wf merge`/
+`wf wip` commit private paths in the private repo and code paths in the code repo. `push = [cmd…]` runs in the private root
+after a merge (env `WF_MAIN`); `wf push` runs it by hand; failure writes `.wf/push-failed`. Add `.wf-home` to the code repo's
+`.gitignore`. The cloud lane is refused. `wf check` warns: no `push`, `.wf-home` not ignored, merged leftover code worktrees.
diff --git a/docs/multi-session.md b/docs/multi-session.md
index 628aad9..225809e 100644
--- a/docs/multi-session.md
+++ b/docs/multi-session.md
@@ -44,3 +44,7 @@ sessions/workers never lose a TASKS.md edit or race a merge-back.
 
 ## 4. Commits
 Shared rule: stage explicit paths, never `git add -A` / `git commit -a`.
+
+## Split projects
+Code worktrees come from `wf start <id> --worktree <path> --branch <b>` run in the private project: it creates them in the
+code repo (`code_root`) and writes `.wf-home` there. Inside such a worktree wf resolves the private project via `.wf-home`.
diff --git a/docs/orchestrator.md b/docs/orchestrator.md
index 845c527..f878855 100644
--- a/docs/orchestrator.md
+++ b/docs/orchestrator.md
@@ -35,7 +35,7 @@ The steps they automate:
 
 1. Pick: `wf list --runner --lane <lane>` → first id (lanes: `wf lanes`). Claim: `wf status <id> progress "worker"`. No commit of
    its own: `wf merge` or any later bookkeeping commit takes TASKS.md (and the claim) along; harmless.
-2. Worktree: `<main>/.worktrees/<lane>`; if a live session or another worker uses it, `<lane>-2`, `-3`, …
+2. Worktree: `<main>/.worktrees/<lane>` (split project: under the code repo, `<code_root top>/.worktrees/<lane>`); if a live session or another worker uses it, `<lane>-2`, `-3`, …
    (live interactive sessions: `~/.claude/sessions/*.json` field `cwd`). Branch `<lane>/<id>`.
 3. Spawn: Agent tool, `subagent_type: wf-worker`, `model: <task Model, none = opus>`, background, no worktree isolation
    (it blocks `wf merge` on the main checkout). Prompt:
@@ -150,3 +150,8 @@ TASKS.md, the log and the batch summaries.
 Safe to clear only with no background worker running. Tested (2026-10-05): `/clear` leaves a background
 subagent alive and its hand-back + completion notice reach the new context, but SIGKILLs its running Bash
 command (exit 137): a worker mid-test or mid-commit loses that step and reports a false failure or half state.
+
+## Split projects
+`code_root` = another git repo: worktrees and branches live in the code repo, `wf start` makes them (with `.wf-home`
+pointing at the private project). `wf orch post` checks the code repo. A done worker whose push (`push` key) failed
+leaves `.wf/push-failed`: the lane stops (`push-failed`); fix the push, delete the marker, continue.