Skip to content
Merged
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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
- **`muster link`**: wire harness entrypoints so the main session acts as **orchestrator** (plan, delegate, verify) and **worker** subagents stay scoped.
- **`muster doctor`**: kit on disk, link manifest, optional harness CLI probe.

The orchestrator keeps coordination small, delegates bounded work, parallelizes independent tasks, and integrates and verifies worker changes. Use `gh-stacking` for dependent pull requests. After required checks are green, add the exact GitHub comment `@mergify queue` and wait for Mergify, merge, and post-merge CI events. Do not poll or sleep while waiting.
The orchestrator keeps coordination small, delegates bounded work, parallelizes independent tasks, and integrates and verifies worker changes. Use `gh-stacking` for dependent pull requests. Wait for GitHub Actions, required checks, and required reviews on the reviewed PR head. Personal repositories use a normal protected GitHub merge pinned to that head; no queue is required. `rckt-corp` uses native GitHub `enqueuePullRequest` with the exact reviewed `expectedHeadOid` and explicit `dequeuePullRequest`, preserving `rckt-corp/apple-signing`'s queue exemption and signing workflow. Other organizations follow their configured repository flow. Never bypass protections or forge checks. Verify the actual merge and post-merge CI on its exact commit. Do not poll or sleep while waiting.

## Install

Expand Down
8 changes: 7 additions & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,13 @@ muster is a **policy distribution and link** tool for interactive coding-agent h

The native harness handles task assignment, worker handoffs, concurrency, worktrees, and event waits. Muster does not define a task/result schema or run worker processes. Codex workers use Luna Medium; other harnesses use their native model settings.

The orchestrator should delegate bounded tasks, parallelize independent work, use `gh-stacking` for dependent pull requests, and wait on lifecycle events or callbacks rather than polling. When checks are green, it adds the exact `@mergify queue` GitHub comment and verifies the subsequent Mergify, merge, and post-merge CI events.
The orchestrator should delegate bounded tasks, parallelize independent work, use `gh-stacking` for dependent pull requests, and wait on lifecycle events or callbacks rather than polling. Delivery depends on repository ownership and configuration, after GitHub Actions and required reviews pass on the reviewed head:

- Personal repositories use normal protected GitHub merging, pinned to the reviewed head with `--match-head-commit`. An absent queue is expected and does not block this flow.
- `rckt-corp` repositories use GitHub's native `enqueuePullRequest` with `expectedHeadOid` matching the reviewed PR head, and `dequeuePullRequest` for removal. A required queue that is missing or rejects entry is a blocker; direct merge is not its fallback. `rckt-corp/apple-signing` retains its existing signing-specific workflow and queue exemption.
- Other organizations follow the repository's configured delivery flow, including its queue when configured.

Every path preserves branch protections and required reviews, rejects forged checks/statuses, and verifies the actual merge and post-merge CI on the exact merge commit. Queue labels, statuses, comments, and accepted merge or enqueue requests are not evidence that a merge occurred.

## Related

Expand Down
21 changes: 20 additions & 1 deletion kit/embed_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,32 @@ func TestOrchestrationPolicyRequiresNativeParallelEventDrivenWorkflow(t *testing
"gh-stacking",
"lifecycle events or callbacks",
"Do not poll, sleep",
"@mergify queue",
"GitHub Actions, required checks, and required reviews",
"For personal repositories",
"normal GitHub protected merge pinned to the reviewed head",
"--match-head-commit",
"No merge queue is required",
"its absence is expected",
"rckt-corp/apple-signing",
"queue exemption",
"For other organizations",
"enqueuePullRequest",
"expectedHeadOid",
"exact reviewed PR head",
"dequeuePullRequest",
"do not replace it with a direct merge",
"Never bypass branch protection, forge check or status results",
"actual merge",
"that exact commit",
"post-merge CI",
} {
if !strings.Contains(string(orchestrator), required) {
t.Errorf("orchestrator policy missing %q", required)
}
}
if strings.Contains(string(orchestrator), "@mergify queue") {
t.Error("orchestrator policy must not mandate a queue provider through a hardcoded bot comment")
}
worker, err := Source.ReadFile("policy/worker.md")
if err != nil {
t.Fatal(err)
Expand Down
10 changes: 7 additions & 3 deletions kit/policy/orchestrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,13 @@ You are the default orchestrator for this harness session. Use its native worker

## GitHub delivery

- On a pull request, wait until required checks and reviews are green before adding the exact GitHub comment `@mergify queue`.
- After commenting, wait for the Mergify event or callback and verify Mergify's response and the actual merge. Then wait for post-merge CI on the target branch and verify it is green.
- Never infer queue success, merge completion, or post-merge CI from the comment. Prefer event-driven waits or callbacks. A dedicated worker may watch GitHub checks or merge state with a command such as `gh run watch` while the orchestrator continues independent work; do not have the orchestrator block on that watcher.
- Identify whether the repository belongs to a personal account or an organization, and refresh its delivery instructions and branch protections. Wait until GitHub Actions, required checks, and required reviews pass on the exact reviewed PR head before performing an authorized merge or queue operation.
- For personal repositories, use a normal GitHub protected merge pinned to the reviewed head, such as `gh pr merge --match-head-commit <reviewed-head>` with a permitted merge method. No merge queue is required; its absence is expected and is not a blocker or a fallback. If the head changes, refresh checks and reviews before merging.
- For `rckt-corp` repositories other than `rckt-corp/apple-signing`, use GitHub's native merge queue: call `enqueuePullRequest` with `expectedHeadOid` set to the exact reviewed PR head. If the head changes, refresh checks and reviews before enqueueing again. Use `dequeuePullRequest` to remove a queued PR when work is parked, authorization is revoked, or the user asks to dequeue. If the required queue is absent, unknown, or rejects entry, report the blocker; do not replace it with a direct merge. Do not infer queue operations from labels, statuses, or comments.
- Preserve `rckt-corp/apple-signing`'s existing signing-specific delivery instructions and queue exemption. For other organizations, follow the repository's configured delivery flow, including its merge queue when one is configured.
- Never bypass branch protection, forge check or status results, or treat an unmet required review as optional. Report the unmet prerequisite and wait for it to be satisfied.
- Verify any queue response and then the actual merge. Record the merge commit and wait for post-merge CI on that exact commit on the target branch; verify the required runs are green. Report missing or unavailable post-merge CI explicitly.
- Never infer merge completion or post-merge CI from a merge or enqueue request. Prefer lifecycle events or callbacks. A dedicated worker may watch GitHub checks or merge state with a command such as `gh run watch` while the orchestrator continues independent work; do not have the orchestrator block on that watcher.
- Do not publish, release, or perform another irreversible action without the authorization required by the user or repository policy.

## Completion report
Expand Down
Loading