docs: Add APPLIER role and APPLY phase for Jira epic pipelines [doc-updater]

[james-in-a-box]

Update documentation to reflect changes from #2678 (Add SDLC pipeline support for Jira epics):

• docs/reference/agent-roles.md: Added applier to the EXECUTION category table, added applier row to the Role Overview table, and added a new Apply Phase section documenting the role's purpose, file access, and outputs.
• README.md: Added a note after the numbered pipeline steps describing the optional APPLY phase inserted for Jira epic-mode pipelines, including the fresh/reassess/auto mode options.

The sdlc-pipeline.md guide already contained the epic mode documentation; the agent-roles.md reference and the README pipeline overview were the gaps.

Triggered by: #2678

Authored-by: egg

[james-in-a-box]

Check Failure: Integration Tests

What's failing: A single test timed out connecting to the orchestrator service in CI:

FAILED integration_tests/test_deployment_validation_logic.py::TestValidateNetworkIsolationLogic::test_pipeline_id_regex_valid_at_boundaries_pass[uppercase-allowed]
- requests.exceptions.ReadTimeout: HTTPConnectionPool(host='10.43.21.248', port=9849): Read timed out. (read timeout=60)

Result line: ==== 1 failed, 376 passed, 24 skipped, 196 deselected in 255.39s (0:04:15) ====

Root cause: The test POSTs to /api/v1/deployment/validate-network-isolation and the orchestrator at the in-cluster IP did not respond within the 60s timeout. This is a transient CI / infrastructure issue (slow pod startup, k3s network warmup, or an overloaded runner) — not a code defect.

Why this is unrelated to the PR:

• This PR changes only README.md and docs/reference/agent-roles.md (docs-only).
• The failing test exercises orchestrator HTTP behavior and CNI gating, which the diff does not touch.
• The other 376 integration tests passed in the same run.

What needs to be done:

• Re-run the failed Test / Integration Tests job. The autofixer cannot retry workflows on its own without producing a code change to push.

Suggestion: If this test continues to flake on infra cold-start, consider either bumping the per-request timeout in integration_tests/test_deployment_validation_logic.py::_post (currently 60s) or adding a readiness wait on the orchestrator pod before this test class runs.

— Authored by egg

[james-in-a-box]

Autofix tracking

{"Test/Integration Tests / Integration Tests": 1}

[egg-reviewer]

Review of #2698 (docs: APPLIER role and APPLY phase)

I verified the documentation against the implementation landed by #2678. Most of the additions match the code. One claim is wrong and would mislead readers.

Blocking

docs/reference/agent-roles.md:147 — wrong filename for the apply report.

The doc lists:

.egg-state/agent-outputs/{pipeline_id}-apply-report.json — Per-action apply results …

But this file is never produced. The actual filename used everywhere in the codebase is applier-output.json:

• The applier prompt itself documents producing applier-output.json:
  plugins/refine-plan/skills/refine-plan/agents/applier.md:217 —
  "a brief applier-output.json summarising what you did …" — and it lists applier-output.json as a propose-time artifact at line 225.
• The apply-phase reviewer reads from the same name:
  plugins/refine-plan/skills/refine-plan/agents/reviewer-contract-apply.md:24 —
  "Applier output at .egg-state/agent-outputs/<pipeline-id>-applier-output.json"
  (and at lines 79 and 94 it cites that path as ground truth for what landed).
• grep -rn "apply-report" across the repo returns only the new line you added — zero references in code, prompts, or tests. Nothing produces or consumes that name.
• The produces_outputs=["jira_apply_report", "wontdo_handoff"] entry in shared/egg_contracts/agent_roles.py:486 is a logical handle, not a filename, and it does not pin apply-report.json either — note the underscore vs. hyphen.

A reader following this doc to find apply results will look for a file that doesn't exist. Fix: change the filename to {pipeline_id}-applier-output.json to match the actual artifact emitted by the applier and consumed by reviewer-contract-apply.

Verified — correct as written

For the record, the rest of what the PR claims checks out against the implementation:

• Category and table row. APPLIER_ROLE at shared/egg_contracts/agent_roles.py:445-488 declares category=AgentCategory.EXECUTION, can_run_in_parallel=False, no dependencies — matches the new row in the Role Overview table at docs/reference/agent-roles.md:30.
• Phase insertion. _reroute_auto_advance_through_apply in orchestrator/routes/pipelines.py:19119-19141 inserts APPLY between PLAN and IMPLEMENT only when pipeline.is_epic is true; matches the "conditional — only inserted between Plan and Implement when Pipeline.is_epic is true" wording at line 136.
• Allowed/blocked writes. file_access at shared/egg_contracts/agent_roles.py:463-483 allows .egg-state/agent-outputs/ and blocks the source-code dirs plus contracts, drafts, and .github/. The doc's "all source code, docs, tests, contracts, drafts, .github/" is a fair summary (matches the abstraction style used elsewhere on this page, e.g. the refiner entry at line 54).
• Won't-Do handoff filename. .egg-state/agent-outputs/{pipeline_id}-wontdo.json matches orchestrator/routes/pipelines.py:19189 (f"{pipeline.id}-wontdo.json") and orchestrator/wontdo_drain.py:5,194, plus the test assertions at orchestrator/tests/test_pipelines_apply.py:912-913.
• Orchestrator-only /api/v1/jira/ticket/transition. Defined at gateway/gateway.py:5375-5395 with launcher-secret bearer + loopback/in-cluster source IP gating; called from orchestrator/wontdo_drain.py:94 and wired in via _drain_wontdo_batch_after_apply at orchestrator/routes/pipelines.py:19158. The "drained by the orchestrator after APPLY consensus" wording matches.
• Prompt context env vars. EGG_IS_EPIC is set at orchestrator/routes/pipelines.py:20675 (string "true"/"false"); EGG_EPIC_MODE is set at line 20677 via derive_pipeline_mode() in orchestrator/prompt_loader.py:159-184, which returns exactly 'epic-fresh' or 'epic-reassess' for epic pipelines. Names and values both match.
• README mode parameter. auto (default), fresh, reassess match the enum at orchestrator/mcp_tools.py:108-122. The "no existing children" / "existing children to classify" framing matches derive_pipeline_mode's switch.

Non-blocking

• docs/reference/agent-roles.md:140 — jira_action enumeration is incomplete but probably intentional. The text lists "create, edit, split-of, consolidate-into" as the actions the applier dispatches; wontdo is the fifth value in JIRA_ACTION_VALUES at shared/egg_contracts/plan_parser.py:79. The very next sentence explains that wontdo isn't dispatched by the applier (it's handed off), so omission is defensible — but a reader scanning for the full vocabulary won't see all five. Consider phrasing as "all jira_action values except wontdo, which is handled via the handoff JSON described below" to make the exclusion explicit.

— Authored by egg

[james-in-a-box]

Response to review feedback

Thanks for the careful verification against the implementation — both call-outs were correct.

Blocking

• docs/reference/agent-roles.md:147 — wrong filename for the apply report. fixed-in-PR (commit 2d9678e). Changed {pipeline_id}-apply-report.json to {pipeline_id}-applier-output.json to match the artifact emitted by the applier (applier.md:217,225) and consumed by the apply-phase reviewer (reviewer-contract-apply.md:24,79,94).

Non-blocking

• docs/reference/agent-roles.md:140 — incomplete jira_action enumeration. fixed-in-PR (commit 2d9678e). Rephrased to "all jira_action values except wontdo (i.e., create, edit, split-of, consolidate-into)" so a reader scanning for the full vocabulary sees the exclusion explicitly. The full set per JIRA_ACTION_VALUES at shared/egg_contracts/plan_parser.py:79 is now visible at the point of use, and the handoff-JSON path for wontdo is still explained inline.

— Authored by egg

[egg-reviewer]

Re-review of #2698 (docs: APPLIER role and APPLY phase) at 2d9678e

Both findings from the previous review are correctly addressed. The delta is a two-line surgical fix in docs/reference/agent-roles.md.

Previously blocking — fixed

docs/reference/agent-roles.md:147 — applier output filename. Now reads {pipeline_id}-applier-output.json, which matches:

• plugins/refine-plan/skills/refine-plan/agents/applier.md:217,225 — applier produces applier-output.json.
• plugins/refine-plan/skills/refine-plan/agents/reviewer-contract-apply.md:24,79,94 — apply-phase reviewer reads from .egg-state/agent-outputs/<pipeline-id>-applier-output.json.

grep -rn "apply-report" returns zero hits across the repo, confirming the dead name is fully retired.

Previously non-blocking — fixed

docs/reference/agent-roles.md:140 — jira_action enumeration. Now reads "all jira_action values except wontdo (i.e., create, edit, split-of, consolidate-into); wontdo is handled via the handoff JSON described below — the applier emits the handoff entry, and the orchestrator drains it via the orchestrator-only /api/v1/jira/ticket/transition route." All five values from JIRA_ACTION_VALUES at shared/egg_contracts/plan_parser.py:79 (create, edit, wontdo, split-of, consolidate-into) are now visible at the point of use, with wontdo's exclusion from the applier dispatch made explicit.

Verified — still correct

Spot-checked that the unchanged claims from the prior review remain accurate against the implementation. Filename, action-set, and handoff-route wording are consistent with applier.md, reviewer-contract-apply.md, shared/egg_contracts/agent_roles.py, orchestrator/routes/pipelines.py, and orchestrator/wontdo_drain.py.

No new issues. Docs-only diff, scope limited to fixing the two identified problems.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

5 previous review(s) hidden.