From 742f36d077db72ebe547a326299c624107ecadeb Mon Sep 17 00:00:00 2001 From: POWERFULMOVES <142271328+POWERFULMOVES@users.noreply.github.com> Date: Thu, 6 Aug 2026 17:29:23 -0400 Subject: [PATCH 1/3] docs(registry): enroll Agent Zero + Archon integrations in living-docs tracking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Neither integration had ANY entry in living_docs_registry.yaml, so `make docs-reconcile-check` was structurally blind to their docs drifting away from their code. That is the root cause behind a cluster of defects found in a read-only audit of both integrations: - .claude/context/agent-zero-orchestration.md (165d) and pmoves/docs/TAC/TAC_AGENT_ZERO.md (106d) document an /mcp/* API and an agent.zero.* / agent.task.* NATS family that were NEVER implemented — including copy-pasteable curl and `nats sub` commands that cannot work. Real endpoints are /healthz, /mcp/commands, /mcp/execute ({cmd, arguments}); real subjects are agentzero.task.v1 and agentzero.memory.update. - Four Archon docs (169d-234d) still describe the pre-0.6.0 Python/Supabase split-port architecture. Archon 0.6.0 (#2217) is TypeScript/Bun on a single port, 3090, with /api/health. - Prometheus probed a dead Archon port AND path, reporting it permanently DOWN (fixed separately in #2448). Enrolls the four docs that are actually canonical: AGENT_ZERO_API.md live-state, probed from /openapi.json services/agent-zero/README.md env vars, build, make targets ARCHON_MINT_CONTRACT_REVIEW.md authoritative mint-pipeline current state SERVICE_HEALTH_ENDPOINTS.md the doc that would have caught #2448 Severity P2 (warn, never gate) is deliberate, not timidity. Freshness is measured from last-commit date (docs_reconcile.py:174-185), and two of these are already outside budget — AGENT_ZERO_API.md at 81d, SERVICE_HEALTH_ENDPOINTS.md at 155d. Enrolling them at P1 would fail CI on merge for pre-existing staleness this PR did not cause. Promote to P1 after a refresh pass brings them inside budget. Verified: `docs_reconcile.py --check` exits 1 both WITH and WITHOUT this change (pre-existing P1 findings: .claude/BOOTSTRAP.md 102d, AGNOTE4482_SITREP.md 10d, dashboard 163 commits behind HEAD). The entire delta from this commit is the two P2 warnings above — CI status is unchanged. Registry parses, 24 tracked entries, no missing paths, `renderable:` section intact. Co-Authored-By: Claude Opus 5 (1M context) --- pmoves/configs/living_docs_registry.yaml | 39 ++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/pmoves/configs/living_docs_registry.yaml b/pmoves/configs/living_docs_registry.yaml index 907f775cdd..f0978dd791 100644 --- a/pmoves/configs/living_docs_registry.yaml +++ b/pmoves/configs/living_docs_registry.yaml @@ -105,6 +105,45 @@ tracked: severity: P2 description: "A2UI Renderer (port 8107) — Remotion animation engine for creator pipeline" + # ── Agent Zero integration ───────────────────────────────────────────── + # Enrolled 2026-08-06. Previously untracked — which is why this integration's + # docs drifted from its code unnoticed. Two other docs + # (.claude/context/agent-zero-orchestration.md, pmoves/docs/TAC/TAC_AGENT_ZERO.md) + # documented an /mcp/* API and an agent.zero.* / agent.task.* NATS family that + # were never implemented, including copy-pasteable curl and `nats sub` commands + # that cannot work. Those are retired in the companion commit. + # + # Severity P2 (warn, do not gate) is deliberate: freshness is measured from + # last-commit date, and AGENT_ZERO_API.md is already outside budget. Enrolling + # at P1 would fail CI the moment this merges. Promote to P1 after a refresh + # pass brings them inside budget. + - path: pmoves/docs/operations/AGENT_ZERO_API.md + freshness_days: 30 + severity: P2 + description: "Agent Zero live-state API — probed from /openapi.json; canonical endpoint reference for the outer supervisor (:8080)" + - path: pmoves/services/agent-zero/README.md + freshness_days: 60 + severity: P2 + description: "Agent Zero service README — env vars, build (upstream agent0ai base + PMOVES overlay), make targets" + + # ── Archon integration ───────────────────────────────────────────────── + # Enrolled 2026-08-06, same root cause. Archon 0.6.0 (#2217) replaced the + # Python service with a TypeScript/Bun app on a single port (3090, /api/health), + # but four untracked docs still described the pre-0.6.0 Python/Supabase + # split-port architecture and nothing reconciled them against the code. + - path: pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md + freshness_days: 60 + severity: P2 + description: "Archon mint-contract current state — archon.mint.* implementation + registration gaps; authoritative over the mint-agent command doc" + + # ── Cross-service health-endpoint truth ──────────────────────────────── + # The doc that would have caught the Archon blackbox probe pointing at a dead + # port and path (#2448). Untracked until now. + - path: pmoves/docs/operations/SERVICE_HEALTH_ENDPOINTS.md + freshness_days: 90 + severity: P2 + description: "Per-service health endpoint truth — reference for compose healthchecks and Prometheus blackbox probes" + # ============================================================================ # Renderable entries (Lane 2228, 2026-08-02) From 97917a0b2229e1bb0f9aaa60a4ab8a0c798dad9c Mon Sep 17 00:00:00 2001 From: POWERFULMOVES <142271328+POWERFULMOVES@users.noreply.github.com> Date: Thu, 6 Aug 2026 17:42:17 -0400 Subject: [PATCH 2/3] docs: mark superseded Agent Zero + Archon docs, fix broken bootstrap pointers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion to the registry-enrollment commit. Six docs describe systems that no longer exist — or in two cases, never existed. They are BANNERED, not deleted, because they have real inbound references that deletion would break: .claude/CLAUDE.md, four TAC docs, INTEGRATIONS_OVERVIEW.md, SERVICE_DOCS_MATRIX.md, and pmoves/scripts/update_service_logs.py (a script reads UPDATE_NOTES). Agent Zero — documents an API that was never implemented: .claude/context/agent-zero-orchestration.md (165d) pmoves/docs/TAC/TAC_AGENT_ZERO.md (106d) Both describe /mcp/health, /mcp/agents, /mcp/subordinate/create, a POST /mcp/execute {task, context, priority} body, and an agent.zero.* / agent.task.* NATS family. Verified against pmoves/services/agent-zero/main.py: none exist. Real endpoints are /healthz, /config/environment, /metrics, /mcp/commands, POST /mcp/execute {cmd, arguments}, /tasks, /jobs/{context_id}, /sessions, /memory CRUD, /events/publish. Real subjects are agentzero.task.v1 and agentzero.memory.update (controller.py:144). This is not merely stale prose: the orchestration doc ships copy-pasteable curl and `nats sub` commands that 404 or never fire. Archon — describes the pre-0.6.0 Python/Supabase service: pmoves/docs/integrations/ARCHON_INTEGRATION.md (169d) pmoves/docs/services/archon/UPDATE_NOTES.md (184d) pmoves/docs/services/archon/README.md (234d) pmoves/docs/services/archon/HEADLESS_RUNBOOK.md (234d) Archon 0.6.0 (#2217) is TypeScript/Bun on a single port 3090 with /api/health, Postgres via DATABASE_URL. The docs still claim Supabase storage, /healthz on :8091, an MCP server on :8051, PydanticAI on :8052, and a separate UI on :3737. Host ports 3737/8091 are compat aliases onto container 3090, not services. Also fixes three broken references in .claude/CLAUDE.md: - Tier-2 pointed at PMOVES-Agent-Zero/.claude/CLAUDE.md, which does not exist (no .claude/ directory in that submodule at all). Any agent following the documented load order got a failed read and silently proceeded with no submodule context. - "Additional References" listed agent-zero-orchestration.md as THE MCP API reference — the fictional one above. - A context-loop note pointed at pmoves/docs/ARCHON_INTEGRATION.md; the real path is pmoves/docs/integrations/ARCHON_INTEGRATION.md, and it is superseded. Each banner names the canonical replacement so the reader is redirected, not just warned off. Not included, pending an operator decision: .claude/commands/agents/{execute, subordinate,task-status}.md are three user-invocable slash commands built entirely on the same nonexistent endpoints. execute and task-status can be rewritten against /tasks + /jobs/{context_id}; subordinate cannot — subordinate creation has no implementation to point at. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/CLAUDE.md | 6 +++--- .claude/context/agent-zero-orchestration.md | 18 ++++++++++++++++++ pmoves/docs/TAC/TAC_AGENT_ZERO.md | 15 +++++++++++++++ pmoves/docs/integrations/ARCHON_INTEGRATION.md | 11 +++++++++++ .../docs/services/archon/HEADLESS_RUNBOOK.md | 12 ++++++++++++ pmoves/docs/services/archon/README.md | 13 +++++++++++++ pmoves/docs/services/archon/UPDATE_NOTES.md | 11 +++++++++++ 7 files changed, 83 insertions(+), 3 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index b7a6101f81..783b22210d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -38,7 +38,7 @@ Per PR #1378 MOF Architecture: PMOVES is a Metal-Organic Framework for distribut - `PMOVES-agents.md/` — AGENTS.md format reference + agent taxonomy/persona docs (Tier-2 *always-relevant*: load when discussing agent class, taxonomy, or AGENTS.md format) - `PMOVES-Archon/.claude/CLAUDE.md` — agent service architecture - `PMOVES-BoTZ/.claude/CLAUDE.md` — skills marketplace framework (legacy/archived per 2026-04-19) -- `PMOVES-Agent-Zero/.claude/CLAUDE.md` — orchestration patterns +- Agent Zero — the submodule has **no** `.claude/CLAUDE.md` (verified 2026-08-06). Use `pmoves/services/agent-zero/README.md` for the service, and `pmoves/docs/operations/AGENT_ZERO_API.md` for the live API surface. - `skills/` — skills constellation (5 forks registered in `.gitmodules`: Pmoves-skills, agent-sandbox, fork-repository, awesome-agent-skills, claude-d3js — run `git submodule update --init skills/` to populate); load `skills/README.md` first - Load only when working directly on that subsystem. @@ -64,7 +64,7 @@ Detail files live in `.claude/context/`: - `testing-strategy.md` — testing workflow + PR requirements - `security-patterns.md` — cross-cutting security patterns (auth, secrets, hardening) - `observability-patterns.md` — Prometheus, Grafana, Loki, TensorZero metrics -- `agent-zero-orchestration.md` — MCP API reference, task flow, subordinate model +- ~~`agent-zero-orchestration.md`~~ — **SUPERSEDED, do not use as an API reference.** It documents `/mcp/health`, `/mcp/agents`, `/mcp/subordinate/create` and an `agent.zero.*` NATS family that were never implemented. Canonical: `pmoves/docs/operations/AGENT_ZERO_API.md` (probed from `/openapi.json`). - `tier-architecture.md` — 7-tier env security model, network segmentation - `chrome-extension.md` — Chrome Extension integration (8 services, message protocol, auth) - `tensorzero.md` — TensorZero detailed documentation @@ -116,7 +116,7 @@ When conflicts occur: main PMOVES.AI patterns take precedence; document exceptio **Solution:** - Each agent loads only its direct tier - Use MCP APIs for cross-agent communication, not shared context -- Reference integration docs (e.g., `pmoves/docs/ARCHON_INTEGRATION.md`) instead of duplicating +- Reference integration docs instead of duplicating (note: `pmoves/docs/integrations/ARCHON_INTEGRATION.md` is **superseded** — it describes the pre-0.6.0 Python/Supabase Archon; current state is `.claude/CATALOG.md` + `pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md`) Full audit: `pmoves/docs/CLAUDE_CONTEXT_AUDIT.md`. diff --git a/.claude/context/agent-zero-orchestration.md b/.claude/context/agent-zero-orchestration.md index 9bd129547e..4002731e0b 100644 --- a/.claude/context/agent-zero-orchestration.md +++ b/.claude/context/agent-zero-orchestration.md @@ -1,3 +1,21 @@ +> [!CAUTION] +> **SUPERSEDED — DO NOT USE AS AN API REFERENCE (marked 2026-08-06).** +> +> This document describes an Agent Zero MCP API that **was never implemented**. Verified +> against `pmoves/services/agent-zero/main.py`: +> +> | Documented here | Reality | +> |---|---| +> | `GET /mcp/health` | does not exist — real: `GET /healthz` | +> | `GET /mcp/agents` | does not exist | +> | `POST /mcp/subordinate/create` | does not exist | +> | `POST /mcp/execute` `{task, context, priority}` | real shape is `{cmd, arguments}` | +> | `agent.zero.*` / `agent.task.*` NATS subjects | real: `agentzero.task.v1`, `agentzero.memory.update` | +> +> The `curl` and `nats sub` examples below **cannot work**. Retained for historical intent only. +> +> **Canonical:** `pmoves/docs/operations/AGENT_ZERO_API.md` (probed from live `/openapi.json`). + # Agent Zero Orchestration Patterns Detailed reference for Agent Zero's MCP API, task coordination, and subordinate agent model. diff --git a/pmoves/docs/TAC/TAC_AGENT_ZERO.md b/pmoves/docs/TAC/TAC_AGENT_ZERO.md index 6cda1b06df..0790e2c13d 100644 --- a/pmoves/docs/TAC/TAC_AGENT_ZERO.md +++ b/pmoves/docs/TAC/TAC_AGENT_ZERO.md @@ -1,3 +1,18 @@ +> [!CAUTION] +> **SUPERSEDED for API/subject detail (marked 2026-08-06).** +> +> The endpoint and NATS-subject tables in this TAC repeat the invented API from +> `.claude/context/agent-zero-orchestration.md` — `/mcp/health`, `/mcp/agents`, +> `/mcp/subordinate/create`, and the `agent.zero.*` subject family. None exist in +> `pmoves/services/agent-zero/main.py`. +> +> Real endpoints: `/healthz`, `/config/environment`, `/metrics`, `/mcp/commands`, +> `POST /mcp/execute` `{cmd, arguments}`, `/tasks`, `/jobs/{context_id}`, `/sessions`, +> `/memory` CRUD, `/events/publish`. +> Real subjects: `agentzero.task.v1`, `agentzero.memory.update`. +> +> **Canonical:** `pmoves/docs/operations/AGENT_ZERO_API.md`. TAC roadmap items below remain valid. + # TAC Tree: Agent Zero > Technology-Architecture-Context tree for the Agent Zero control-plane orchestrator — the primary L1 coordinator with embedded agent runtime and MCP API. diff --git a/pmoves/docs/integrations/ARCHON_INTEGRATION.md b/pmoves/docs/integrations/ARCHON_INTEGRATION.md index beac04ded5..d70e1d6181 100644 --- a/pmoves/docs/integrations/ARCHON_INTEGRATION.md +++ b/pmoves/docs/integrations/ARCHON_INTEGRATION.md @@ -1,3 +1,14 @@ +> [!CAUTION] +> **SUPERSEDED — describes the pre-0.6.0 Archon (marked 2026-08-06).** +> +> Archon 0.6.0 (#2217) replaced the Python service with a **TypeScript/Bun** app serving +> HTTP + UI on a **single port 3090**, health at **`/api/health`**, backed by a dedicated +> Postgres. This document's split-port / Supabase-backed / nested-`external/`-submodule +> model no longer matches anything that runs. +> +> **Canonical:** `.claude/CATALOG.md` (ports/health) and +> `pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md` (mint pipeline current state). + # Archon External Integration Architecture > **Part of the [PMOVES.AI Integration Layer](INTEGRATIONS_OVERVIEW.md)** | Category: Integration Architecture diff --git a/pmoves/docs/services/archon/HEADLESS_RUNBOOK.md b/pmoves/docs/services/archon/HEADLESS_RUNBOOK.md index e14eaf1575..e43b0d8983 100644 --- a/pmoves/docs/services/archon/HEADLESS_RUNBOOK.md +++ b/pmoves/docs/services/archon/HEADLESS_RUNBOOK.md @@ -1,3 +1,15 @@ +> [!CAUTION] +> **SUPERSEDED — targets endpoints that no longer exist (marked 2026-08-06).** +> +> References `/healthz`, `/ready`, `/mcp/describe`, an MCP bridge on `:8051`, and a +> clone-at-build `ARCHON_VENDOR_ROOT` / `ARCHON_GIT_REF` pattern. None of these exist in +> Archon 0.6.0, whose Dockerfile builds directly from the submodule source with no such ARG. +> +> Current surface: `/api/health`, `/api/workflows*`, `/api/codebases*`, `/api/conversations*`, +> `/api/providers*`, `/api/auth/*`, `/api/runs/:id/artifacts`, `/webhooks/github`. +> +> **Canonical:** `.claude/CATALOG.md`. + Archon Headless Bring‑Up — MCP/API Self‑Connectivity Targets diff --git a/pmoves/docs/services/archon/README.md b/pmoves/docs/services/archon/README.md index 6f5a96978d..339c953d27 100644 --- a/pmoves/docs/services/archon/README.md +++ b/pmoves/docs/services/archon/README.md @@ -1,3 +1,16 @@ +> [!CAUTION] +> **SUPERSEDED — pre-0.6.0 architecture (marked 2026-08-06).** +> +> Claims here that are no longer true: Supabase-backed storage (`SUPABASE_URL` / +> `SUPABASE_SERVICE_KEY`), `/healthz` on `:8091`, a separate MCP server on `:8051`, a +> PydanticAI agents service on `:8052`, and a distinct UI service on `:3737`. +> +> Archon 0.6.0 is a single unified TypeScript/Bun server on **3090** with **`/api/health`**, +> Postgres via `DATABASE_URL`, no MCP subserver. Host ports 3737 and 8091 are compat +> aliases onto container 3090 — they are not separate services. +> +> **Canonical:** `.claude/CATALOG.md`. + # Archon Service – Supabase Wiring, Bring-Up, and Smokes This guide documents how Archon is wired to Supabase in the PMOVES.AI stack, and how to bring it up and validate it alongside the rest of the agents. diff --git a/pmoves/docs/services/archon/UPDATE_NOTES.md b/pmoves/docs/services/archon/UPDATE_NOTES.md index d3ee5cd2b3..c830d4a886 100644 --- a/pmoves/docs/services/archon/UPDATE_NOTES.md +++ b/pmoves/docs/services/archon/UPDATE_NOTES.md @@ -1,3 +1,14 @@ +> [!CAUTION] +> **SUPERSEDED — last synced against the pre-0.6.0 Python Archon (marked 2026-08-06).** +> +> The commits listed below belong to the old Python service that Archon 0.6.0 (#2217) +> replaced. Retained as history; do not read as current state. +> +> **Canonical:** `.claude/CATALOG.md` and `pmoves/docs/handoffs/ARCHON_MINT_CONTRACT_REVIEW.md`. +> +> Note: `pmoves/scripts/update_service_logs.py` references this file — retained rather than +> deleted so that tooling does not break. + # archon — Update Notes _Last synced: 2025-11-07T15:48:32Z_ From 7b5d9486d2b687569a863c4280417ecd765e61cc Mon Sep 17 00:00:00 2001 From: POWERFULMOVES Date: Fri, 7 Aug 2026 18:12:23 -0400 Subject: [PATCH 3/3] fix(docs-gen): preserve manual prefix above generated Update Notes heading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CodeRabbit (Major): the SUPERSEDED banner #2449 adds to archon/UPDATE_NOTES.md would be wiped by update_service_logs.py on rerun. extract_manual_prefix() preserves any hand-authored content above the '# — Update Notes' H1. Co-Authored-By: Claude Opus 4.8 --- pmoves/scripts/update_service_logs.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/pmoves/scripts/update_service_logs.py b/pmoves/scripts/update_service_logs.py index ca7e50e411..09e7eb7af9 100644 --- a/pmoves/scripts/update_service_logs.py +++ b/pmoves/scripts/update_service_logs.py @@ -220,6 +220,24 @@ def collect_services(filter_names: Optional[List[str]] = None) -> List[Path]: return candidates +def extract_manual_prefix(path: Path) -> str: + """Return any manually-authored content above the generated H1 heading. + + ``render_markdown`` rewrites the whole file, so a hand-written banner above + the ``# — Update Notes`` heading (e.g. a SUPERSEDED caution) would be + silently wiped on the next rerun. Preserve it verbatim so the helper is safe + to re-run against legacy service docs. + """ + try: + lines = path.read_text(encoding="utf-8").splitlines(keepends=True) + except (OSError, UnicodeDecodeError): + return "" + for i, line in enumerate(lines): + if line.startswith("# ") and "— Update Notes" in line: + return "".join(lines[:i]) + return "" + + def update_service(service_path: Path, limit: int, dry_run: bool) -> Optional[Path]: doc_dir = DOCS_ROOT / service_path.name if not doc_dir.exists(): @@ -230,6 +248,11 @@ def update_service(service_path: Path, limit: int, dry_run: bool) -> Optional[Pa markdown = render_markdown(service_path.name, commits, versions) update_path = doc_dir / "UPDATE_NOTES.md" + # Preserve a hand-authored prefix (e.g. a SUPERSEDED banner) above the + # generated heading so a rerun does not silently discard it. + if update_path.exists(): + markdown = extract_manual_prefix(update_path) + markdown + if not dry_run: update_path.write_text(markdown, encoding="utf-8") return update_path