docs: Update architecture docs for anchor mechanism [doc-updater]

[james-in-a-box]

Update documentation to reflect the agent anchor mechanism added in #1260:

• README.md: Added "Agent anchor / post-compaction recovery" entry to the documentation table, linking to the new anchor-recovery.md guide.
• docs/architecture/README.md: Added agent-anchor.schema.json to the Schemas section, and added anchor write-scoping (agents limited to their own anchor file via AGENT_ANCHOR_ID) to the Access Control section.
• docs/architecture/orchestrator.md: Added anchor API endpoints (/api/v1/anchors/*) and progress API endpoints to the Orchestrator API reference section.

The feature itself was already well-documented in docs/guides/anchor-recovery.md, shared/egg_anchor/README.md, docs/reference/orchestrator-cli.md, and docs/development/STRUCTURE.md — all updated as part of the original PR. These changes fill the remaining gaps in the architecture overview and top-level README discoverability.

Triggered by: #1260

Test plan:

• Verify links in README.md documentation table resolve correctly
• Verify agent-anchor.schema.json entry matches the actual file at .egg/schemas/agent-anchor.schema.json
• Verify anchor API endpoints match orchestrator/routes/anchors.py

Authored-by: egg

[egg-reviewer]

No agent-mode design concerns. This is a documentation-only PR adding discoverability for the anchor mechanism (README table entry, schema reference, API endpoints). No agent workflow or prompt changes.

— Authored by egg

[egg-reviewer]

Documentation Accuracy Issues

This PR documents API endpoints that don't match the actual implementation. For a docs PR whose stated purpose is filling "remaining gaps in the architecture overview," incorrect endpoint references create confusion rather than closing gaps.

Blocking

1. GET /pipelines/{id}/progress/alerts does not exist — the real path is /pipelines/{id}/health/alerts

docs/architecture/orchestrator.md line 401 documents:

GET /pipelines/{id}/progress/alerts - List active health alerts

The actual route is defined in orchestrator/routes/health.py:181:

@health_bp.route("/pipelines/<pipeline_id>/health/alerts", methods=["GET"])

The health_bp blueprint has prefix /api/v1, making the real path /api/v1/pipelines/{id}/health/alerts. There is no /progress/alerts route anywhere in the progress blueprint or any other blueprint.

Placing this under the "progress" subsection in the docs and using the wrong URL path means anyone following the documentation will get 404s.

Fix: Change to GET /pipelines/{id}/health/alerts and move it out of the progress group, or place it under a dedicated health subsection (which already exists earlier in the same file under health endpoints, where it arguably belongs instead of being duplicated here).

2. GET /anchors/ endpoint does not exist

docs/architecture/orchestrator.md line 408 documents:

GET /anchors/ - List all anchors for a pipeline (requires ?pipeline_id=)

No such route exists in orchestrator/routes/anchors.py. The only routes registered on the anchors_bp blueprint are:

• /<agent_id> (GET/POST/DELETE)
• /team/<pipeline_id> (GET)
• /gc/<pipeline_id> (POST)

There is no root GET / handler. This documents a phantom endpoint.

Fix: Remove this line, or implement the endpoint if it's intended functionality.

3. POST /anchors/gc/{pipeline_id} endpoint exists but is not documented

orchestrator/routes/anchors.py:280 defines a garbage collection endpoint:

@anchors_bp.route("/gc/<pipeline_id>", methods=["POST"])
def gc_anchors(pipeline_id: str):

This endpoint handles anchor cleanup for completed/failed pipelines (archiving or setting TTLs). It's not mentioned in the documentation added by this PR.

Fix: Add POST /anchors/gc/{pipeline_id} to the anchors section.

Summary

Two of the five documented anchor/progress endpoints have incorrect paths or don't exist, and one real endpoint is omitted. The README and architecture/README changes are accurate and fine. The orchestrator.md endpoint documentation needs corrections before merge.

— Authored by egg

[james-in-a-box]

Agreed. All three issues fixed in 1210e6c:

1. Health alerts path: Changed GET /pipelines/{id}/progress/alerts → GET /pipelines/{id}/health/alerts and moved it next to the existing health endpoint (matches orchestrator/routes/health.py:181).
2. Phantom GET /anchors/: Removed — no such route exists in orchestrator/routes/anchors.py.
3. Missing GC endpoint: Added POST /anchors/gc/{pipeline_id} (matches orchestrator/routes/anchors.py:280).

— Authored by egg

[egg-reviewer]

Re-review: previous feedback fully addressed in 1210e6c. Health alerts path corrected, phantom endpoint removed, GC endpoint added. No agent-mode design concerns — documentation-only changes.

— Authored by egg

[egg-reviewer]

Re-review: All Issues Fixed

Verified the three blocking issues from the previous review against the implementation:

1. Health alerts path — Fixed. GET /pipelines/{id}/health/alerts now matches orchestrator/routes/health.py:181 and is positioned next to the existing GET /pipelines/{id}/health endpoint.
2. Phantom GET /anchors/ — Removed. Only the five real endpoints are documented.
3. Missing GC endpoint — Added. POST /anchors/gc/{pipeline_id} matches orchestrator/routes/anchors.py:280.

Cross-checked all documented endpoints against blueprint registrations:

• health_bp prefix /api/v1 → health/alerts path correct
• progress_bp prefix /api/v1/pipelines → progress GET/POST paths correct
• anchors_bp prefix /api/v1/anchors → all five anchor paths correct

README link target (docs/guides/anchor-recovery.md) and schema reference (.egg/schemas/agent-anchor.schema.json) both exist. Access control description matches the enforcement documented in anchor-recovery.md:141-143.

No issues found.

— Authored by egg

[james-in-a-box]

egg review completed. View run logs

4 previous review(s) hidden.