docs: Document orchestrator worktree architecture [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from PR #617 which fixed the orchestrator to read verdict/draft/check files from per-pipeline worktrees instead of the main repository.

Changes

• docs/architecture/orchestrator.md: Add "Per-Pipeline Worktrees" section explaining how the orchestrator mounts and reads from .egg-worktrees to access pipeline artifacts written by agent containers
• docs/guides/deployment.md: Clarify HOST_HOME comment to explain it's needed for orchestrator to mount .egg-worktrees and read pipeline artifacts

Context

The code changes in #617 were internal fixes to existing functionality (the orchestrator was reading from the wrong path), but the worktree architecture was not fully documented. This update clarifies how the orchestrator interacts with gateway-created per-pipeline worktrees.

Triggered by: #617

— Authored by egg

[egg-reviewer]

No agent-mode design concerns. This is a documentation-only PR clarifying the orchestrator's worktree architecture — no workflows, prompts, or agent design patterns are affected.

— Authored by egg

[egg-reviewer]

Documentation Review

The documentation structure and placement are appropriate. The "Per-Pipeline Worktrees" section logically follows the "Pipeline State Persistence" section, and the deployment.md comment improvement is helpful. However, there are factual inaccuracies that will mislead readers.

Issues

1. Review file path pattern is wrong (orchestrator.md line 54)

The docs say:

.egg-state/reviews/{issue}-{phase}-{reviewer}.json

The actual pattern in orchestrator/routes/pipelines.py:819-821 is:

.egg-state/reviews/{issue}-{phase}-{reviewer_type}-review.json

Two errors: the variable is reviewer_type (not reviewer), and the filename has a -review suffix before .json. A reader using this doc to locate or construct review file paths will fail.

2. Draft file path pattern is inaccurate (orchestrator.md line 53)

The docs say:

.egg-state/drafts/{issue}-{analysis|plan}.md

The actual patterns in orchestrator/routes/pipelines.py:839-850 are:

• .egg-state/drafts/{issue}-analysis.md (refine phase)
• .egg-state/drafts/{issue}-{phase}.md (other phases, e.g. plan)
• No draft for implement phase (return None)

The {analysis|plan} notation suggests only two possible values, but the code accepts any phase name. Additionally, analysis is not a phase name — it's a special case mapping from the refine phase. The docs should reflect the actual logic.

3. Check file path is overly vague (orchestrator.md line 55)

The docs say:

.egg-state/checks/*.json

The actual path used in orchestrator/routes/pipelines.py:1506 is specifically:

.egg-state/checks/implement-results.json

A glob pattern suggests many check files; the code reads exactly one. This matters for someone trying to understand the data flow.

4. "read-only" claim for orchestrator mount is incorrect (orchestrator.md line 48)

The docs say:

Orchestrator mounts /home/egg/.egg-worktrees (read-only)

In docker-compose.yml:133, the orchestrator volume mount is:

- ${HOST_HOME:-/home/egg}/.egg-worktrees:/home/egg/.egg-worktrees

There is no :ro flag — this is a read-write mount. The gateway mount (docker-compose.yml:75) is also read-write. Whether the orchestrator should mount read-only is a separate question, but the docs should not state a restriction that isn't enforced.

deployment.md change

The HOST_HOME comment update (deployment.md line 73) is accurate and an improvement over the previous generic comment. No issues.

Summary

The four issues above are all factual inaccuracies in the new documentation section. Since this PR's purpose is to document the worktree architecture correctly, these need to be fixed before merge.

— Authored by egg

[james-in-a-box]

All four issues fixed in 436776c:

1. Review file path: Updated to {issue}-{phase}-{reviewer_type}-review.json — fixed both the variable name and the -review suffix.
2. Draft file path: Now documents the actual logic — refine maps to analysis, implement returns None, other phases use {phase}.
3. Check file path: Replaced glob pattern with the specific implement-results.json path.
4. Read-only claim: Removed the incorrect (read-only) annotation since docker-compose.yml has no :ro flag on the orchestrator mount.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns. The delta since last review (436776c) fixes factual inaccuracies in documentation per the other reviewer's feedback — file path patterns, phase mapping logic, and mount flag accuracy. No agent workflows, prompts, or design patterns are affected.

— Authored by egg

[egg-reviewer]

Re-Review — All Issues Fixed

Verified the delta from f8951e8 → 436776c against the source code. All four issues from the previous review have been correctly addressed:

1. Review file path — Fixed. Now matches orchestrator/routes/pipelines.py:822: {issue}-{phase}-{reviewer_type}-review.json.
2. Draft file path — Fixed. Documents the refine→analysis special case, implement→None, and generic {phase} fallback, matching orchestrator/routes/pipelines.py:824-850.
3. Check file path — Fixed. Replaced glob with the specific implement-results.json, matching orchestrator/routes/pipelines.py:1506.
4. Read-only claim — Fixed. Removed the incorrect (read-only) annotation. docker-compose.yml:133 has no :ro flag.

No new issues found in the updated content. The contract path (.egg-state/contracts/{issue}.json) is correct per shared/egg_contracts/loader.py:57. The WORKTREE_BASE_DIR and gateway/worktree_manager.py cross-references exist. The integration test named volume claim is accurate (integration_tests/*/docker-compose.yml). The deployment.md HOST_HOME comment improvement is factually correct.

LGTM — no blocking issues.

One minor observation (non-blocking): the "Key files read from worktrees" section lists contracts, but the orchestrator also writes contracts to worktrees (orchestrator/routes/pipelines.py:1756-1778). The heading "read from" is technically incomplete. Consider "Key artifact files in worktrees" or similar if you want precision, but this is cosmetic.

— Authored by egg

[james-in-a-box]

Agreed. Renamed the heading from "Key files read from worktrees" to "Key artifact files in worktrees" in 059eecc, since the orchestrator also writes contracts to worktrees.

— Authored by egg

[egg-reviewer]

No agent-mode design concerns. The delta since last review (436776c → 059eecc) is a single heading rename ("Key files read from worktrees" → "Key artifact files in worktrees") addressing cosmetic feedback. No agent workflows, prompts, or design patterns are affected.

— Authored by egg

[egg-reviewer]

Re-Review — Delta from 436776c → 059eecc

The only change since my last review is the heading rename: "Key files read from worktrees" → "Key artifact files in worktrees" (commit 059eecc). This addresses my previous non-blocking suggestion about the heading being incomplete since the orchestrator also writes contracts to worktrees.

Verification

Re-verified all documented claims against source code. Everything remains accurate:

• WORKTREE_BASE_DIR: Matches orchestrator/routes/pipelines.py:60 and gateway/worktree_manager.py:45
• Review file path: Pattern matches pipelines.py:819-821
• Draft file paths: refine→analysis, implement→None, generic {phase} all match pipelines.py:839-850
• Check results path: Matches pipelines.py:1506
• Contract path: Matches shared/egg_contracts/loader.py:23,57
• Volume mount: No :ro flag in docker-compose.yml:133 — correctly not claimed as read-only
• Integration test volumes: Named worktrees volume confirmed in both integration test docker-compose files

No issues found. LGTM.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

egg feedback addressed. View run logs

10 previous review(s) hidden.