Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions config/scripts/orchestration-skill-guidance.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -367,6 +367,21 @@ describe('owned orchestration references', () => {
)
})

it('binds placement to the Run and states what an omitted --worktree resolves to', () => {
const reference = squash(readReference('placement-and-remote.md'))

expect(reference).toContain('Decide placement once per Run')
expect(reference).toContain('do not re-derive it per Task')
expect(reference).toContain('a per-Task reading splits one Run across both lineages')
expect(reference).toContain(
"An omitted `--worktree` resolves to `current`, the coordinator's own workspace"
)
// Remote start has no usable default: the resolved `current` is rejected.
expect(reference).toContain(
'The `current` default is rejected the same way, so `--on` requires an explicit placement'
)
})

it('owns FIFO mail, Dispatch addresses, groups, questions, and gates', () => {
const reference = readReference('messaging-and-gates.md')

Expand Down
15 changes: 11 additions & 4 deletions skill-guides/orchestration/references/placement-and-remote.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ current or an exact existing workspace by default. Create a worktree only when
the user requested one or a concrete checkout or filesystem conflict makes
sharing unsafe.

Decide placement once per Run. Choose where the lanes run when you open the Run
and reuse that choice for every later `worker-start`; do not re-derive it per
Task. Tasks decomposed from one objective read as dependent and independent at
the same time, so a per-Task reading splits one Run across both lineages.

```text
# Current workspace; setup is not rerun.
ORCA orchestration worker-start --task <task_id> --worktree current --agent codex --json
Expand All @@ -21,6 +26,7 @@ ORCA orchestration worker-start --task <task_id> --worktree new-child --name <na
ORCA orchestration worker-start --task <task_id> --worktree new-top-level --name <name> --agent codex --setup run --json
```

An omitted `--worktree` resolves to `current`, the coordinator's own workspace.
Current and exact existing workspaces create a fresh terminal unless
`--terminal` is explicit. Folder workspaces are first-class; do not invoke Git
or require worktree lineage when the selected workspace is a folder.
Expand Down Expand Up @@ -53,10 +59,11 @@ ORCA orchestration worker-start --task <task_id> --on <environment> --worktree n
```

Remote `current` and `new-child` are invalid because they are ambiguous across
servers. Use an exact discovered remote workspace, or `new-top-level` with an
exact remote repository selector. After start, route every follow-up, read,
stop, and cleanup by Dispatch ID; never repeat `--on` or substitute a remote
terminal handle.
servers. The `current` default is rejected the same way, so `--on` requires an
explicit placement: an exact discovered remote workspace, or `new-top-level`
with an exact remote repository selector. After start, route every follow-up,
read, stop, and cleanup by Dispatch ID; never repeat `--on` or substitute a
remote terminal handle.

```text
ORCA orchestration worker-show --dispatch <dispatch_id> --json
Expand Down
4 changes: 2 additions & 2 deletions src/cli/bundled-skill-guides.ts

Large diffs are not rendered by default.