From c579a604d651a5ce554f563015917a1de570241a Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Tue, 17 Mar 2026 09:01:35 +0000 Subject: [PATCH 1/2] docs: Update architecture docs for agent anchor mechanism Update documentation to reflect changes from 669809e6: - README.md: Add anchor recovery guide to documentation table - docs/architecture/README.md: Add agent-anchor.schema.json to schemas list and anchor write-scoping to access controls - docs/architecture/orchestrator.md: Add anchor and progress API endpoints to the orchestrator API reference Triggered by: #1260 (Add agent anchor mechanism for post-compaction recovery) Authored-by: egg --- README.md | 1 + docs/architecture/README.md | 2 ++ docs/architecture/orchestrator.md | 10 ++++++++++ 3 files changed, 13 insertions(+) diff --git a/README.md b/README.md index 1c5bf0cec8..bfb3b9af4e 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,7 @@ See [action/README.md](action/README.md) for full documentation and [GitHub Auto | **Architecture & security model** | [Architecture Overview](docs/architecture/README.md) | | **SDLC pipeline details** | [SDLC Pipeline Guide](docs/guides/sdlc-pipeline.md) | | **Concurrent execution mode** | [Concurrent Execution Guide](docs/guides/concurrent-execution.md) | +| **Agent anchor / post-compaction recovery** | [Anchor Recovery Guide](docs/guides/anchor-recovery.md) | | **Agent roles & permissions** | [Agent Roles Reference](docs/reference/agent-roles.md) | | **Agent recovery & circuit breaker** | [Agent Recovery Reference](docs/reference/agent-recovery.md) | | **Post-agent auto-commit** | [Post-Agent Commit Reference](docs/reference/post-agent-commit.md) | diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 4807b61503..3783d4c572 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -34,6 +34,7 @@ See the [main README](../../README.md) for the architecture diagram. - Filesystem-level readonly mounts (phase-protected `.egg-state/` directories mounted readonly) - Commit-time validation (staged files checked against phase restrictions before commit) - Agent role-based file access (Coder, Tester, Documenter have distinct write permissions; default warn-only, configurable to enforce via `EGG_AGENT_RESTRICTIONS_ENFORCE`) +- Anchor file write-scoping (agents can only write their own `.egg-state/agent-anchors/{agent-id}.json`, enforced via `AGENT_ANCHOR_ID`) - Role-based contract mutations (implementer, reviewer, human roles with field-level permissions) - No merge capability (gateway has no merge endpoint) - Force push and destructive operations blocked @@ -60,6 +61,7 @@ Contracts are JSON documents that track issue progress through SDLC phases, task - `.egg/schemas/yaml-tasks.schema.json` – Structured appendix format for plan documents (used by plan parser) - `.egg/schemas/phase-permissions.schema.json` – Allowed git/gh operations and file restrictions per SDLC phase - `.egg/schemas/checkpoint.schema.json` – Agent checkpoint structure (session context, transcripts, tool calls) +- `.egg/schemas/agent-anchor.schema.json` – Agent anchor structure for post-compaction state recovery **Role-based ownership**: Each contract field is owned by a specific role: - `implementer`: `tasks[].commit`, `tasks[].notes`, `tasks[].files_affected` diff --git a/docs/architecture/orchestrator.md b/docs/architecture/orchestrator.md index 4dc0f78133..aecde50ca6 100644 --- a/docs/architecture/orchestrator.md +++ b/docs/architecture/orchestrator.md @@ -396,6 +396,16 @@ Fixed IPs: - `GET /pipelines/{id}/deployment-check/status` - Poll devserver status - `POST /pipelines/{id}/deployment-check/teardown` - Tear down devserver - `GET /pipelines/{id}/health` - On-demand pipeline health check (all tiers) +- `GET /pipelines/{id}/progress` - Query structured progress events +- `POST /pipelines/{id}/progress` - Emit a structured progress event (CLI: `egg-orch progress emit`) +- `GET /pipelines/{id}/progress/alerts` - List active health alerts + +**Anchors (`/api/v1/anchors/`)** +- `POST /anchors/{agent_id}` - Create or update an agent anchor (stored in Redis; validated against schema) +- `GET /anchors/{agent_id}` - Get an agent's anchor (cross-agent reads via API) +- `DELETE /anchors/{agent_id}` - Delete an anchor +- `GET /anchors/team/{pipeline_id}` - Get team anchor (orchestrator-generated projection of all agent anchors) +- `GET /anchors/` - List all anchors for a pipeline (requires `?pipeline_id=`) **MCP Server (`/mcp`)** - `GET /health` - MCP server health check From 1210e6cc28cc1871533dab0317f3064b8b36a18c Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Tue, 17 Mar 2026 09:10:42 +0000 Subject: [PATCH 2/2] docs: Fix incorrect API endpoint paths in orchestrator architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix health alerts endpoint: /progress/alerts → /health/alerts (matches orchestrator/routes/health.py:181) - Remove phantom GET /anchors/ endpoint (no such route exists) - Add missing POST /anchors/gc/{pipeline_id} endpoint (defined in orchestrator/routes/anchors.py:280) --- docs/architecture/orchestrator.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/orchestrator.md b/docs/architecture/orchestrator.md index aecde50ca6..56750e5290 100644 --- a/docs/architecture/orchestrator.md +++ b/docs/architecture/orchestrator.md @@ -396,16 +396,16 @@ Fixed IPs: - `GET /pipelines/{id}/deployment-check/status` - Poll devserver status - `POST /pipelines/{id}/deployment-check/teardown` - Tear down devserver - `GET /pipelines/{id}/health` - On-demand pipeline health check (all tiers) +- `GET /pipelines/{id}/health/alerts` - List active health alerts - `GET /pipelines/{id}/progress` - Query structured progress events - `POST /pipelines/{id}/progress` - Emit a structured progress event (CLI: `egg-orch progress emit`) -- `GET /pipelines/{id}/progress/alerts` - List active health alerts **Anchors (`/api/v1/anchors/`)** - `POST /anchors/{agent_id}` - Create or update an agent anchor (stored in Redis; validated against schema) - `GET /anchors/{agent_id}` - Get an agent's anchor (cross-agent reads via API) - `DELETE /anchors/{agent_id}` - Delete an anchor - `GET /anchors/team/{pipeline_id}` - Get team anchor (orchestrator-generated projection of all agent anchors) -- `GET /anchors/` - List all anchors for a pipeline (requires `?pipeline_id=`) +- `POST /anchors/gc/{pipeline_id}` - Garbage-collect anchors for a completed/failed pipeline **MCP Server (`/mcp`)** - `GET /health` - MCP server health check