Skip to content
21 changes: 7 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,17 +93,17 @@ The overseer is phase-scoped: it is spawned at the start of each pipeline phase
egg structures work into phases with mandatory human gates:

```
┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────┐
│ REFINE │─────▶│ PLAN │─────▶│ IMPLEMENT │─────▶│ PR │
└────┬─────┘ └────┬─────┘ └──────────────┘ └────┬─────┘
│ │ │
Human gate Human gate Human merge
┌──────────┐ ┌──────────┐ ┌─────────────────────────────────────┐
│ REFINE │─────▶│ PLAN │─────▶│ IMPLEMENT │
└────┬─────┘ └────┬─────┘ └─────────────────────────────────────┘
│ │ │ │
Human gate Human gate Context PR opened Human merges
at phase start context + slice PRs
```

1. **Refine**: Agents analyze the task, research the codebase, produce requirements. Reviewers validate. Human approves before planning.
2. **Plan**: Architect recommends approach, task planner breaks it into discrete tasks with acceptance criteria, risk analyst flags concerns. Human approves before any code is written.
3. **Implement**: The plan's tasks are split into a **DAG of independent slices** — each slice runs as its own agent team on its own integration branch with its own BRC consensus and stacked PR. Slices whose dependencies are satisfied run concurrently (up to `EGG_ORCH_MAX_PARALLEL_SLICES`, default 2 per pipeline; a separate `EGG_ORCH_GLOBAL_MAX_PARALLEL_SLICES` cap, default 4, bounds the total across all running pipelines); slices with unmet dependencies wait in subsequent waves. Within each slice, the coder writes code, the tester writes regression tests and adversarially probes the coder's implementation for bugs (NACKing with failing tests as bug reports), and the documenter updates docs. Code and contract reviewers provide line-level feedback; security and concurrency lens reviewers add targeted cross-file analysis and block consensus on a NACK. Cycles continue until all checks pass and BRC consensus is reached for that slice. See [Slice-DAG Implement Phase](docs/architecture/slice-dag.md) for the full model.
4. **PR**: Orchestrator auto-creates the PR from plan metadata. Only a human can merge via GitHub UI.
3. **Implement**: The plan's tasks are split into a **DAG of independent slices** — each slice runs as its own agent team on its own integration branch with its own BRC consensus and stacked PR. Slices whose dependencies are satisfied run concurrently (up to `EGG_ORCH_MAX_PARALLEL_SLICES`, default 2 per pipeline; a separate `EGG_ORCH_GLOBAL_MAX_PARALLEL_SLICES` cap, default 4, bounds the total across all running pipelines); slices with unmet dependencies wait in subsequent waves. Within each slice, the coder writes code, the tester writes regression tests and adversarially probes the coder's implementation for bugs (NACKing with failing tests as bug reports), and the documenter updates docs. Code and contract reviewers provide line-level feedback; security and concurrency lens reviewers add targeted cross-file analysis and block consensus on a NACK. Cycles continue until all checks pass and BRC consensus is reached for that slice. See [Slice-DAG Implement Phase](docs/architecture/slice-dag.md) for the full model. A context PR (`egg/<pipeline_id>/work → main`) is opened automatically at the plan→implement boundary; slice PRs stack on it. Only a human can merge via GitHub UI.

For **Jira epic-mode pipelines** (when `jira_ticket` resolves to a Jira Epic), an **Apply** phase is inserted between Plan and Implement: the `applier` role drives Jira mutations (epic Description writes, child ticket creates/edits, link creates, Won't-Do handoffs) on operator approval, before code implementation begins. Pass `mode='fresh'` (no existing children) or `mode='reassess'` (existing children to classify) to `submit_task`; `mode='auto'` (default) detects which to use at submit time.

Expand Down Expand Up @@ -139,13 +139,6 @@ Within each phase, specialized agents run concurrently via BRC (enabled by defau
│ ✓ reviewer_security ✓ reviewer_concurrency │
│ [1h11m] │
╚═══════════════════════════════════════════════╝
│
▼
╔════════════╗
│ ✓ PR │
│ complete │
│ [2s] │
╚════════════╝
```

## Architecture
Expand Down
49 changes: 27 additions & 22 deletions docs/architecture/sdlc-pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ For operational details, CLI commands, and triggering instructions, see the [SDL
**The core guarantee**: An agent cannot bypass verification gates or self-approve its own work. All state transitions are enforced structurally through role-based mutations and gateway policy enforcement.

**Key properties:**
- **Phased execution**: Work progresses through defined phases (refine → plan → implement → pr)
- **Phased execution**: Work progresses through defined phases (refine → plan → implement); implement is terminal — the context PR opens at the plan→implement boundary
- **Role-based control**: Implementer, Reviewer, and Human roles have distinct permissions
- **Human-in-the-loop**: Critical transitions pause for human approval
- **Audit trail**: All mutations are logged for accountability
Expand Down Expand Up @@ -39,12 +39,13 @@ This architecture implements **structural enforcement**: the agent physically ca
┌─────────────────────────────────────────────────────────────────────────┐
│ SDLC Pipeline │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │
│ │ Refine │───▶│ Plan │───▶│ Implement │───▶│ PR │ │
│ │ (Human) │ │ (Human) │ │ (Reviewer) │ │ (Human) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ │
│ │ Refine │───▶│ Plan │───▶│ Implement │ │
│ │ (Human) │ │ (Human) │ │ (Reviewer; context PR │ │
│ └─────────────┘ └─────────────┘ │ opened at phase start) │ │
│ └─────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Contract State │ │
│ │ .egg-state/contracts/{identifier}.json │ │
Expand All @@ -65,8 +66,7 @@ This architecture implements **structural enforcement**: the agent physically ca
|-------|---------|---------------|
| **refine** | Problem analysis and requirements gathering | Human approval |
| **plan** | Implementation planning with task breakdown | Human approval |
| **implement** | Task execution and code changes | All checks pass (CI + PR review) |
| **pr** | Pull request creation and merge | Human merge |
| **implement** | Task execution and code changes; context PR opened automatically at phase start | All checks pass + human merge (terminal phase) |

### Role Permissions

Expand All @@ -83,7 +83,7 @@ The contract is a JSON document tracking the complete state of an issue through

```json
{
"schemaVersion": "1.1",
"schemaVersion": "1.2",
"issue": { "number": 133, "title": "...", "url": "..." },
"current_phase": "implement",
"slices": [{
Expand Down Expand Up @@ -132,10 +132,12 @@ The contract is a JSON document tracking the complete state of an issue through
> derivable as `egg/<pipeline_id>/work` and the program-level title and
> description live on the standard `pr.title` / `pr.description`. The
> sole remaining context-PR field is `pr.context_pr_number` (still the
> PR number of the `egg/<pipeline_id>/work → main` context PR). This is
> a **clean break** (cq-2 resolution): in-flight contracts that contain
> the removed fields fail to load until migrated, and there is no
> backwards-compat shim — see [v1.1 → v1.2 schema migration note](#schema-v11--v12-migration-note-2777).
> PR number of the `egg/<pipeline_id>/work → main` context PR). Pre-1.2
> contracts on disk load transparently: a `model_validator(mode="wrap")`
> migration (`Contract._migrate_schema_version_to_1_2`) strips the three
> removed keys before Pydantic constructs `PRMetadata` and bumps
> `schemaVersion` to `"1.2"`; the new value is persisted on the next
> save. See [v1.1 → v1.2 schema migration note](#schema-v11--v12-migration-note-2777).
>
> **Context-PR mechanism (#2777 collapse).** The context PR is opened
> **up-front at the plan→implement boundary**, **hard-required** and
Expand All @@ -161,21 +163,24 @@ The contract is a JSON document tracking the complete state of an issue through
Operational impact:

- **In-flight contracts on disk** that still contain any of the three
removed fields will **fail to load** under v1.2. Per feedback-1 Q5,
there were no in-flight pipelines requiring compatibility at the
v1.2 cut-over; new pipelines start at v1.2 and never write the
removed fields load transparently under v1.2: the
`Contract._migrate_schema_version_to_1_2` wrap-mode migration strips
the three removed keys before Pydantic constructs `PRMetadata` and
bumps `schemaVersion` to `"1.2"`. The new value is persisted on the
next contract save. New pipelines start at v1.2 and never write the
removed fields.
- **Planner authoring**: plan YAML must no longer emit
`pr.context_title` or `pr.context_description` — those keys are
rejected at parse time. Use `pr.title` and `pr.description` to frame
the work→main context PR.
- **PR-phase removal**: there is no longer a separate "PR" pipeline
stage. The context PR opens up-front at plan→implement boundary
(hard-required, idempotent via `GatewayClient._lookup_open_pr`) and
per-slice PRs are opened inline by `create_slice_pr` (also
idempotent via the same `gh pr list --head ... --base ... --state
open` pre-flight, #2777). The legacy `_should_skip_pr_phase_auto_pr`
skip gate and the PR-phase route/runner were removed.
(hard-required, idempotent via `GatewayClient.list_open_prs` with a
client-side head+base filter) and per-slice PRs are opened inline by
`create_slice_pr` (also idempotent via the narrower
`GatewayClient._lookup_open_pr` server-side filter, #2777 cq-8). The
legacy `_should_skip_pr_phase_auto_pr` skip gate and the PR-phase
route/runner were removed.

## HITL (Human-in-the-Loop) Mechanism

Expand Down
Loading
Loading