diff --git a/AFI_Full_Architecture.md b/AFI_Full_Architecture.md index d7fc0c1..df9959f 100644 --- a/AFI_Full_Architecture.md +++ b/AFI_Full_Architecture.md @@ -77,7 +77,7 @@ flowchart TD ``` **Normative authority.** -- **afi-governance** holds the accepted decisions — object identity, lifecycle, persistence, scoring pins, math authority, districts, and economic law. Fifteen decision records sit on the current default branch. +- **afi-governance** holds the accepted decisions — object identity, lifecycle, persistence, scoring pins, math authority, districts, and economic law. Sixteen decision records sit on the current default branch. - **afi-config** holds the canonical schemas, registries, conventions, and known-answer tests (KATs) that a decision delegates to it. - **afi-math** holds canonical deterministic kernels (the 86-billion emissions schedule, decay/Greeks surfaces) with golden vectors. @@ -115,7 +115,8 @@ AFI is organized by responsibility, not by repository alone. The planes below de - **math-authority-v0.1** and **mint-formula-bt-86b-alignment-v0.1** — math ownership and the v1 mint-formula interpretation (epoch budget `E_t = B(t) · AIM_t`, with `AIM_t = 1` for v1). - **authority-districts-v0.1** and **district-2-m2-ratification-v0.1** — the two-District topology and the prospective ratification of District 2's runtime surface. - **district-surface-consolidation-v0.1** — the clean-cut District surface record (DSC-GOV): one live `GraphExecutor` as the sole signal-evaluation executor, the District-1 implementation record pointing at the live pipeline, the District-2 provenance law homed in `afi-reactor/src/evidence/provenance/`, exactly one provider framework (`afi-reactor/src/providers/`), and the five-category terminology rule. -- **district-one-signal-evaluation-capability-v0.1** — the District One capability record (D1CAP-GOV): District 1 is the **active Signal Evaluation capability and authority domain** (implementation-independent — a conforming future implementation may replace the current one through accepted authority without retiring the district), with its durable responsibility boundary, its exclusions, the descriptive current-implementation mapping, the honest provider-runtime state, and the ruling that Mission A's clean cut was an implementation retirement only — the district endures. +- **district-one-signal-evaluation-capability-v0.1** — the District One capability record (D1CAP-GOV): District 1 is the **active Signal Evaluation capability and authority domain** (implementation-independent — a conforming future implementation may replace the current one through accepted authority without retiring the district), with its durable responsibility boundary, its exclusions, the descriptive current-implementation mapping, and the ruling that Mission A's clean cut was an implementation retirement only — the district endures. +- **five-lane-provider-runtime-v0.1** — the Five-Lane Provider Runtime Activation record (FLPR-GOV): the PBF-GOV provider framework is the **sole live enrichment-execution seam** for all five categories; every enabled lane node carries exactly one explicit `providerInstanceRef` (fail-closed, no silent fallback, no env-var vendor selection); the sentiment/aiMl/candlestick-pattern/SEC-EDGAR adapters and the bounded additive `candlestick` block on `afi.enrichment.pattern.v1`; the byte-level scoring-invariance obligations; and the forward-only removal of every classic direct-call category path. The lifecycle state machine is governed as `INGESTED → VALIDATED → SCORED → CERTIFIED → QUALIFIED → CHALLENGE_OPEN → [CONTESTED →] FINALIZED → EPOCH_ELIGIBLE`. **The implemented lifecycle currently reaches `SCORED`.** @@ -164,8 +165,8 @@ Factory is **not** the API Atlas, **not** the Gateway, **not** the Reactor runti - **Two live ingress paths reach the executor.** Most submissions arrive routed from the Gateway (`POST /api/v1/signals` → the Reactor webhook). The Reactor also exposes **`POST /api/ingest/cpj`**, a direct community-provider-journal ingest (`afi.cpj.v0.1`, for Telegram/Discord oracle providers) that bypasses the Gateway under an optional shared secret, validates CPJ v0.1, and deduplicates by ingest hash (`409` on a duplicate). Both paths **resolve the provider → strategy binding** against the boot-validated provider-binding registry — an unbound provider is rejected with an honest `403`, never a silent default composition — then map to USS v1.1 and run the identical scoring path. - **The direct CPJ route is an internal trusted service boundary, not a public API (Reference/Reserved).** Its authentication is optional (a single shared secret) and provider identity is self-asserted, so any future public or partner CPJ access is designated to be mediated by a separate authenticated **Institute oracle-ingress reference service** — designated, **not implemented or deployed** — or another conforming external trust boundary; the route is neither renamed, moved, nor exposed. Provider binding, CPJ validation, and provenance stay mandatory regardless of exposure (ingest dedupe is opt-in, `AFI_INGEST_DEDUPE=1`) (INST-GOV; see [`specs/AFI_RESEARCH_INSTITUTE_REFERENCE_SERVICES.v0.1.md`](specs/AFI_RESEARCH_INSTITUTE_REFERENCE_SERVICES.v0.1.md)). - The **graph is manifest-driven**, not a hardcoded DAG. The executor runs topological waves (Kahn's algorithm) with bounded concurrency, deterministic ready-sets, per-node timeout and retry, conditional edges, and joins keyed by node id. Graph validation enforces unique ids, acyclicity, reachability, exactly one non-bypassable scorer sink, and declared joins. -- The **five analysis categories** are ordinary registered plugins bound at build time, alongside a join plugin and the scorer. Any registered strategy (for example the "Froggy trend-pullback" scorer) is an ordinary registry entry, not a special path. The `aiMl` category is fed by the optional, fail-soft `afi-tiny-brains` sidecar (the Reactor's client returns nothing when the sidecar URL is unset); its output is read-only context and **does not affect UWR scoring**. -- A **bounded provider-adapter socket** sits inside the Reactor, below the category node (not a second executor). A provider-backed node carries a non-secret `providerInstanceRef`; the runtime resolves the tenant-scoped provider instance, resolves **only** the authorized credential through an injected least-privilege `SecretResolver` (the adapter receives a bounded credential bundle, never a resolver), invokes the trusted registered adapter, and validates the canonical `afi.enrichment..v1` output before it reaches the scorer — one resolved result per category, fail-closed at every boundary. Three reference adapters are proven: a keyless technical adapter, a credentialed news adapter (BYOK; the key rides in a request header, never a URL), and a keyless local pattern adapter. `sentiment` and `aiMl` have no provider adapter yet, and no registered manifest binds a `providerInstanceRef` today — the socket is a dormant forward surface for all five categories pending the separately-governed Five-Lane Provider Runtime Cutover (not started). Credentials are resolved only at runtime and appear in no artifact, log, hash, or evidence. Deployment-specific secret backends are pending a later staging wave (PBF-GOV; see [`specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md`](specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md)). +- The **five analysis categories** are vendor-neutral, provider-instance-backed lane plugins bound at build time, alongside the five-category join plugin and the scorer. Any registered strategy (for example the "Froggy trend-pullback" scorer) is an ordinary registry entry, not a special path. The `aiMl` lane joins the sibling lanes' outputs and invokes the self-hosted `afi-tiny-brains` service through its governed adapter; its result is read-only context and **does not affect UWR scoring** (a failed lane settles under its declared failure policy as a recorded degradation — nothing is fabricated). +- The **bounded provider-adapter runtime** inside the Reactor, below the category node (not a second executor), is the **sole live enrichment-execution seam** (FLPR-GOV). Boot loads the governed `registries/{providers,provider-instances,credential-refs}` records fail-closed; every lane node carries a non-secret `providerInstanceRef`; the runtime resolves the tenant-scoped provider instance, resolves **only** the authorized credential through an injected least-privilege `SecretResolver` (the adapter receives a bounded credential bundle, never a resolver), invokes the trusted statically registered adapter, and validates the canonical `afi.enrichment..v1` output before it reaches the scorer — one resolved result per category, fail-closed at every boundary, no silent provider fallback. Eight adapters are registered: keyless local technical, first-party candlestick pattern (local kernels), Tiny-Brains pattern (self-hosted STUMPY/ruptures/find_peaks), keyless CFTC-COT sentiment (public domain), credentialed Coinalyze sentiment (BYOK header), credentialed NewsData news (BYOK header), keyless SEC-EDGAR news, and first-party Tiny-Brains aiMl. The committed reference profile selects an all-five keyless/self-hosted instance set; selecting a different supported provider is a registry/record change, never category-node code. Credentials are resolved only at invocation and appear in no artifact, log, hash, or evidence; the current resolver backend is the env-backed development backend, and deployment-specific secret backends are pending a later staging wave (PBF-GOV + FLPR-GOV; see [`specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md`](specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md)). - The scorer node wraps afi-core's analyst, resolves the UWR configuration fail-closed, and emits scores and their resolved source verbatim. - The Reactor **constructs Evidence V2** (`afi.scored-signal-evidence.v2`) with `lifecycleState = SCORED`, `finalized = false`, the registry-backed UWR-profile stamp, and a required all-or-nothing composition reference. Scores are read verbatim from afi-core and never recomputed. - The **submitter rejects any non-`SCORED` record**, proves the wrapper, schema, sub-artifact schemas, and identifier continuity before submitting, and surfaces every failure as a typed non-2xx. The Reactor **never touches MongoDB directly**; it consumes afi-infra's store as a typed dependency, and persistence is a required step of the run. @@ -292,20 +293,20 @@ flowchart LR Exactly **two** Districts are formally registered (`authority-districts-v0.1`, Part D, as amended by `district-surface-consolidation-v0.1` (DSC-GOV) and `district-one-signal-evaluation-capability-v0.1` (D1CAP-GOV)). Both are **active capability domains**, and both remain **non-production** (nothing is deployed). No other District is created or implied. Districts represent durable capability and authority boundaries: implementations may be replaced through accepted authority without retiring the district they implement. -- **District 1 — Signal Evaluation** — the **active** Signal Evaluation capability and authority domain (D1CAP-GOV). It owns evaluation from canonical signal input through the scorer/UWR seam: evaluation-time validation, execution of the five enrichment categories, explicit provider-instance resolution for provider-backed categories, category-result validation against the governed `afi.enrichment.*.v1` contracts, deterministic fan-out and join (exactly one validated result per category), analyst invocation under accepted authority, canonical scorer/UWR invocation (invoked, never re-implemented), and creation of the scored evaluation result handed to District 2. Its current implementation is the live flow described in "The current end-to-end flow" below: the two ingress paths → the one manifest-driven `GraphExecutor` (`afi-reactor/src/pipeline/`) → category nodes → enrichment join → analyst/scorer/UWR → the District-2 handoff. The district is not any directory, class, manifest, analyst, or provider — the mapping is descriptive, and a conforming future implementation may replace it through accepted authority. Provider-runtime cutover is **partial** (see the category table below). Git history preserves the earlier proof-of-concept implementation record; that record's retirement under DSC-GOV was an implementation retirement only — the district is active. +- **District 1 — Signal Evaluation** — the **active** Signal Evaluation capability and authority domain (D1CAP-GOV). It owns evaluation from canonical signal input through the scorer/UWR seam: evaluation-time validation, execution of the five enrichment categories, explicit provider-instance resolution for provider-backed categories, category-result validation against the governed `afi.enrichment.*.v1` contracts, deterministic fan-out and join (exactly one validated result per category), analyst invocation under accepted authority, canonical scorer/UWR invocation (invoked, never re-implemented), and creation of the scored evaluation result handed to District 2. Its current implementation is the live flow described in "The current end-to-end flow" below: the two ingress paths → the one manifest-driven `GraphExecutor` (`afi-reactor/src/pipeline/`) → category nodes → enrichment join → analyst/scorer/UWR → the District-2 handoff. The district is not any directory, class, manifest, analyst, or provider — the mapping is descriptive, and a conforming future implementation may replace it through accepted authority. The five-lane provider runtime is **active** for all five categories (FLPR-GOV; see the category table below). Git history preserves the earlier proof-of-concept implementation record; that record's retirement under DSC-GOV was an implementation retirement only — the district is active. - **District 2 — Canonical Data & Provenance Boundary.** Active. Its M1 schema family is implemented in `afi-config/schemas/provenance/v1` with validation tests, authorized for **M1 only** ("no runtime wiring") by the D-17 instrument homed in afi-docs. Its live provenance law — CanonicalHash v1 (`afi.hash.v1`), the ScoredSignal v1 projection builders, and the D2 schema validators — is implemented in `afi-reactor/src/evidence/provenance/` and runs as a required step of every scoring run; the prospective, bounded, non-production ratification of `district-2-m2-ratification-v0.1` is recorded at that location by DSC-GOV D-DSC-3 (no canonical-object declaration is made). **It receives the scored evaluation result from District 1 at the scorer/UWR seam** and owns evidence construction, validation, and the canonical handoff to persistence from there. **Five-category state (District 1, current truth):** -| Category | Governed contract | Provider adapter | Live provider cutover | Affects the analyst score today | +| Category | Governed contract | Reference ProviderInstance (keyless/self-hosted) | Additional supported provider | Affects the analyst score today | |---|---|---|---|---| -| `technical` | `afi.enrichment.technical.v1` | keyless local | not yet (classic node live) | **yes** (EMA distance, value-zone) | -| `pattern` | `afi.enrichment.pattern.v1` | keyless local | not yet (classic node live) | **yes** (pattern confidence) | -| `sentiment` | `afi.enrichment.sentiment.v1` | none yet | not yet (classic node live) | wired into the scorer input but inert under the live value domains | -| `news` | `afi.enrichment.news.v1` | credentialed HTTP (BYOK) | not yet (classic node live) | no (evidence/lenses only) | -| `aiMl` | `afi.enrichment.aiml.v1` | none yet | not yet (classic node live) | no (read-only context; evidence/lenses only) | +| `technical` | `afi.enrichment.technical.v1` | `afi-instance-reference-technical-local` (local kernels over the configured keyless exchange feed) | — | **yes** (EMA distance, value-zone) | +| `pattern` | `afi.enrichment.pattern.v1` | `afi-instance-reference-pattern-candlestick` (first-party local kernels; the D-FLPR-3 candlestick block) | `afi-instance-reference-pattern-tiny-brains` (self-hosted kernel service) | **yes** (pattern confidence) | +| `sentiment` | `afi.enrichment.sentiment.v1` | `afi-instance-reference-sentiment-cftc-cot` (public-domain COT positioning) | `afi-instance-byok-sentiment-coinalyze` (BYOK header) | wired into the scorer input but inert under the live value domains | +| `news` | `afi.enrichment.news.v1` | `afi-instance-reference-news-sec-edgar` (public filings) | `afi-instance-byok-news-newsdata` (BYOK header) | no (evidence/lenses only) | +| `aiMl` | `afi.enrichment.aiml.v1` | `afi-instance-reference-aiml-tiny-brains` (self-hosted service) | — | no (read-only context; evidence/lenses only) | -All five categories execute live through their classic nodes; no registered manifest binds a `providerInstanceRef` today. Completing the provider seam for all five lanes is the reserved Five-Lane Provider Runtime Cutover — a separate future owner authorization, not started. +All five categories execute live through the provider runtime: the registered `froggy-trend-pullback v1.1.0` manifest binds an explicit `providerInstanceRef` on every lane node (the committed all-five keyless/self-hosted reference profile), and provider selection is a registry/record change under FLPR-GOV D-FLPR-4 — never category-node code, never an environment switch, never a silent fallback. **District map authority.** No canonical API Atlas exists and none is started (ATLAS-GOV reserved). District authority and the accepted decision chain — the Part D prose registry as amended — remain the current District map; a future Atlas will describe real District capabilities and interfaces, not define or execute them. No machine-readable District registry exists; creating one belongs to ATLAS-GOV. diff --git a/AFI_GATEWAY_RENAME_STATUS_REPORT.md b/AFI_GATEWAY_RENAME_STATUS_REPORT.md deleted file mode 100644 index a539806..0000000 --- a/AFI_GATEWAY_RENAME_STATUS_REPORT.md +++ /dev/null @@ -1,401 +0,0 @@ -# AFI Gateway Rename Status Report - -**Assessment Date**: 2026-01-04 -**Original Plan**: Rename repository from `afi-eliza-gateway` to `afi-gateway` -**Status**: **PARTIALLY COMPLETE** - Approximately 30% of planned work completed - ---- - -## Executive Summary - -The repository rename from `afi-eliza-gateway` to `afi-gateway` has been **partially completed**. While the local directory has been renamed and key configuration files updated, there are **extensive remaining references** to the old name throughout the codebase that need to be addressed. - -**Key Finding**: The rename appears to have been started but not systematically completed across all affected repositories and files. - ---- - -## Completed Tasks ✅ - -### 1. Repository-Level Changes - -#### ✅ Directory Rename -- **Status**: COMPLETE -- The local directory has been renamed from `afi-eliza-gateway` to `afi-gateway` -- The directory structure is now `afi-gateway/` in the workspace - -#### ✅ package.json Update -- **Status**: COMPLETE -- **File**: [`afi-gateway/package.json`](../afi-gateway/package.json:2) -- **Change**: Package name updated from `"@afi-protocol/afi-eliza-gateway"` to `"@afi-protocol/afi-gateway"` -- **Description**: Updated to "AFI's universal gateway for multiple interfaces and integrations" - -#### ✅ README.md Update -- **Status**: COMPLETE -- **File**: [`afi-gateway/README.md`](../afi-gateway/README.md:1) -- **Changes**: - - Title changed to "afi-gateway" - - Description updated to "AFI's Universal Gateway" - - Integration diagrams updated to use "afi-gateway" - - Quick start instructions updated - - Architecture diagrams updated - ---- - -## Incomplete Tasks ❌ - -### 2. Cross-Repo Reference Updates - -#### ❌ afi-reactor Documentation -- **Status**: INCOMPLETE -- **File**: [`afi-reactor/AGENTS.md`](../afi-reactor/AGENTS.md:561) -- **Issue**: Section header still references "afi-eliza-gateway Integration" -- **Line 561**: `- [afi-eliza-gateway Integration](#afi-eliza-gateway-integration) - ElizaOS agent integration` -- **Required Action**: Update section header and link to use "afi-gateway" - -#### ❌ afi-reactor README -- **Status**: INCOMPLETE -- **File**: [`afi-reactor/README.md`](../afi-reactor/README.md) -- **Issue**: May contain references to old name (needs verification) - -#### ❌ afi-config/codex Governance Docs -- **Status**: COMPLETE -- **Files Updated**: - - `afi-config/docs/agent_definition.schema.v0.1.json` - Updated example from "afi-eliza-gateway" to "afi-gateway" - - `afi-config/codex/governance/droids/AFI_DROID_GLOSSARY.md` - Updated all references from "afi-eliza-gateway" to "afi-gateway" - - `afi-config/codex/governance/droids/AFI_DROID_PLAYBOOK.v0.1.md` - Updated all references from "afi-eliza-gateway" to "afi-gateway" - - `afi-config/codex/governance/droids/AFI_DROID_CHARTER.v0.1.md` - Updated reference from "afi-eliza-gateway" to "afi-gateway" - - `afi-config/codex/governance/agents/PHOENIX_PERSONA.v0.1.md` - Updated all references from "afi-eliza-gateway" to "afi-gateway" - - `afi-config/codex/governance/agents/AFI_AGENT_UNIVERSE.v0.1.md` - Updated all references from "afi-eliza-gateway" to "afi-gateway" - -#### ❌ Other Repositories -- **Status**: NOT CHECKED -- **Repositories to verify**: - - `afi-core` - - `afi-tiny-brains` - - `afi-econ` - - `afi-infra` - - `afi-docs` - - `afi-artifacts` - - `afi-benchkit` - ---- - -### 3. Code and Configuration Updates in afi-gateway - -#### ❌ Git Remote Configuration -- **Status**: INCOMPLETE -- **File**: [`afi-gateway/.git/config`](../afi-gateway/.git/config:9) -- **Issue**: Remote URL still points to old repository -- **Current**: `url = git@github.com:AFI-Protocol/afi-eliza-gateway.git` -- **Required**: Update to `git@github.com:AFI-Protocol/afi-gateway.git` - -#### ❌ Source Code Files -- **Status**: INCOMPLETE -- **Files with old name references**: - - **[`afi-gateway/src/server.ts`](../afi-gateway/src/server.ts:4)**: - - Line 4: Comment "This is a production HTTP server for AFI-Eliza integration gateway." - - Line 7: Comment "Expose AFI Eliza Gateway as a long-running HTTP service" - - Line 74: `service: "afi-eliza-gateway"` - - Line 94: `service: "afi-eliza-gateway"` - - Line 96: `description: "AFI Eliza Gateway - HTTP API for AFI-Eliza integration"` - - Line 123: `service: "afi-eliza-gateway"` - - Line 157: Log message "🚀 AFI ELIZA GATEWAY — HTTP SERVER" - - **[`afi-gateway/src/cli.ts`](../afi-gateway/src/cli.ts:4)**: - - Line 4: Comment "Command-line interface for AFI Eliza Gateway operations." - - Line 16: Class name `AfiElizaGatewayCli` - - Line 18: `super('afi-eliza-gateway', '0.1.0'` - - Line 22: `this.description('AFI Eliza Gateway CLI for agent operations')` - - **Character Files** (all in `afi-gateway/src/`): - - [`alpha.character.ts`](../afi-gateway/src/alpha.character.ts:13): Comment "Part of: afi-eliza-gateway agent layer" - - [`froggy.character.ts`](../afi-gateway/src/froggy.character.ts:13): Comment "Part of: afi-eliza-gateway agent layer" - - [`pixelRick.character.ts`](../afi-gateway/src/pixelRick.character.ts:14): Comment "Part of: afi-eliza-gateway agent layer" - - [`valDook.character.ts`](../afi-gateway/src/valDook.character.ts:17): Comment "Part of: afi-eliza-gateway agent layer (legacy)" - - [`phoenix.character.ts`](../afi-gateway/src/phoenix.character.ts:11): Comment "Runtime behavior is governed by: afi-eliza-gateway/docs/AFI_AGENT_PLAYBOOK.v0.1.md" - - **Plugin Files**: - - [`afi-gateway/src/afiClient.ts`](../afi-gateway/src/afiClient.ts:20): Comment "Part of: afi-eliza-gateway integration with afi-reactor" - - [`afi-gateway/src/plugins/afi-reactor-actions/index.ts`](../afi-gateway/src/plugins/afi-reactor-actions/index.ts): Comment "Part of: afi-eliza-gateway integration with afi-reactor" - -#### ❌ Documentation Files in afi-gateway -- **Status**: INCOMPLETE -- **Files with old name references**: - - **[`afi-gateway/AGENTS.md`](../afi-gateway/AGENTS.md)**: Needs review for old name references - - **[`afi-gateway/DEV_NOTES.md`](../afi-gateway/DEV_NOTES.md:151)**: - - Line 151: Directory structure shows `afi-eliza-gateway/` - - **[`afi-gateway/SERVER_NOTES.md`](../afi-gateway/SERVER_NOTES.md:101)**: - - Line 101: `service: "afi-eliza-gateway"` - - **[`afi-gateway/docs/AFI_ELIZA_DEMO.md`](../afi-gateway/docs/AFI_ELIZA_DEMO.md:63)**: - - Line 63: `cd /Users/secretservice/AFI_Modular_Repos/afi-eliza-gateway` - - Line 70: `Set in afi-eliza-gateway/.env` - - **[`afi-gateway/docs/OPENAI_KEY_AUDIT.md`](../afi-gateway/docs/OPENAI_KEY_AUDIT.md:10)**: - - Line 10: "Completed a comprehensive audit and refactoring of OpenAI API key configuration in `afi-eliza-gateway`" - - Line 130: `cd /Users/secretservice/AFI_Modular_Repos/afi-eliza-gateway` - - Line 215: "Verify .env location: Make sure `.env` is in `afi-eliza-gateway/` root" - - **[`afi-gateway/docs/COMMUNITY_AGENTS_QUICKSTART.md`](../afi-gateway/docs/COMMUNITY_AGENTS_QUICKSTART.md:19)**: - - Line 19: `cd afi-eliza-gateway` - - Line 166: "Verify both `afi-knowledge-hub` and `afi-eliza-gateway` use the same database" - - **[`afi-gateway/docs/ELIZA_WEB_CLIENT_INTEGRATION.md`](../afi-gateway/docs/ELIZA_WEB_CLIENT_INTEGRATION.md:19)**: - - Line 19: "2. **AFI Eliza Gateway** (`afi-eliza-gateway`)" - - Line 37: "### Option A: Integrate ElizaOS Server into afi-eliza-gateway (RECOMMENDED)" - - Line 69: `cd afi-eliza-gateway` - - Line 137: `cd afi-eliza-gateway` - - Line 188: `cd afi-eliza-gateway` - - Line 197: "# Restart afi-eliza-gateway" - - **[`afi-gateway/docs/MODEL_PROVIDER_FIX.md`](../afi-gateway/docs/MODEL_PROVIDER_FIX.md:135)**: - - Line 135: "1. `afi-eliza-gateway/src/server-full.ts` — Added `basePlugins` array" - - Line 139: "2. `afi-eliza-gateway/docs/MODEL_PROVIDER_FIX.md` — This summary" - - Line 150: `cd afi-eliza-gateway` - - **[`afi-gateway/docs/INTEGRATION_COMPLETE_SUMMARY.md`](../afi-gateway/docs/INTEGRATION_COMPLETE_SUMMARY.md:68)**: - - Line 68: "afi-eliza-gateway/src/server.ts" - - Line 80: "afi-eliza-gateway/src/server-full.ts" - - Line 105: "2. **AFI Reactor** running on `http://localhost:8080`" - - Line 106: "3. **Environment variables** set in `afi-eliza-gateway/.env`" - - Line 114: `cd afi-eliza-gateway` - - Line 135: `cd afi-eliza-gateway` - - **[`afi-gateway/docs/OFFLINE_TELEMETRY_QUICKSTART.md`](../afi-gateway/docs/OFFLINE_TELEMETRY_QUICKSTART.md:33)**: - - Line 33: "1. Clone the afi-eliza-gateway repository" - - Line 37: `cd afi-eliza-gateway` - - Line 47: "From the `afi-eliza-gateway` directory" - - **[`afi-gateway/docs/TYPESCRIPT_FIX_SUMMARY.md`](../afi-gateway/docs/TYPESCRIPT_FIX_SUMMARY.md:156)**: - - Line 157: `cd afi-eliza-gateway` - - **[`afi-gateway/docs/ELIZA_WEB_CLIENT_DEMO_RUNBOOK.md`](../afi-gateway/docs/ELIZA_WEB_CLIENT_DEMO_RUNBOOK.md:15)**: - - Line 15: "- **afi-eliza-gateway** (Render or local) — AFI personas + actions" - - Line 20: "**afi-eliza-gateway** requires:" - - Line 68: `cd /Users/secretservice/AFI_Modular_Repos/afi-eliza-gateway` - - Line 108: "# Restart afi-eliza-gateway" - - Line 156: "### afi-eliza-gateway on Render" - - Line 158: "**URL**: https://afi-eliza-gateway.onrender.com" - - Line 193: "2. Add your OpenAI API key" - - Line 194: "3. Restart afi-eliza-gateway" - -#### ❌ Compiled/Dist Files -- **Status**: INCOMPLETE -- **Files with old name references** (in `afi-gateway/dist/`): - - All `.d.ts` and `.js` files contain old name references - - These are build artifacts that will be regenerated after source files are fixed - -#### ❌ Node Modules -- **Status**: INCOMPLETE -- **Files**: All binary files in `afi-gateway/node_modules/.bin/` contain hardcoded paths to `afi-eliza-gateway` -- **Note**: These are third-party dependencies and will be regenerated after `npm install` - ---- - -### 4. DAG and Agent Registry Updates - -#### ❌ afi-reactor Agent Registry -- **Status**: NOT CHECKED -- **File**: `afi-reactor/config/agents.codex.json` -- **Required Action**: Update any agent metadata that references `afi-eliza-gateway` - -#### ❌ afi-reactor DAG Plugins -- **Status**: NOT CHECKED -- **Directory**: `afi-reactor/src/dag/plugins/` -- **Required Action**: Update any plugin references to the old repo name - ---- - -### 5. Build and Deployment Scripts - -#### ❌ CI/CD Files -- **Status**: NOT FOUND -- **Finding**: No `.github/workflows/` directory exists in `afi-gateway` -- **Required Action**: Create or update CI/CD workflows if they exist elsewhere - -#### ❌ Docker/Infrastructure -- **Status**: NOT CHECKED -- **Repository**: `afi-infra` -- **Required Action**: Update any references to `afi-eliza-gateway` in infrastructure configurations - ---- - -### 6. Updated Descriptions for afi-gateway - -#### ❌ README.md Excerpt -- **Status**: PARTIALLY COMPLETE -- **Current**: README.md has been updated with new name -- **Missing**: The specific excerpt from the original plan may not be present - -#### ❌ AGENTS.md Update -- **Status**: NOT CHECKED -- **File**: `afi-gateway/AGENTS.md` -- **Required Action**: Update title and descriptions to emphasize universality - ---- - -### 7. Validation Steps - -#### ❌ Build and Test -- **Status**: NOT PERFORMED -- **Required Actions**: - - Run `npm install` in `afi-gateway` to ensure no broken imports - - Run `npm test` in `afi-gateway` to ensure tests pass - - Run `npm run build` to verify TypeScript compilation - -#### ❌ Integration Testing -- **Status**: NOT PERFORMED -- **Required Actions**: - - Test that `afi-gateway` still calls `afi-reactor` APIs correctly - - Verify all HTTP endpoints work with new service name - - Test character configurations - ---- - -## Summary Statistics - -| Category | Completed | Incomplete | Total | % Complete | -|----------|-----------|------------|-------|------------| -| Repository-Level Changes | 3 | 0 | 3 | 100% | -| Cross-Repo Reference Updates | 1 | 7 | 8 | 12.5% | -| Code and Configuration Updates | 0 | 20+ | 20+ | 0% | -| DAG and Agent Registry Updates | 0 | 2 | 2 | 0% | -| Build and Deployment Scripts | 0 | 2 | 2 | 0% | -| Documentation Updates | 2 | 10+ | 12+ | 16.7% | -| Validation Steps | 0 | 3 | 3 | 0% | -| **TOTAL** | **6** | **44+** | **50+** | **~12%** | - ---- - -## Critical Issues - -### High Priority 🔴 - -1. **Git Remote Not Updated** - - The `.git/config` still points to `afi-eliza-gateway` repository - - This will cause issues when pushing changes to GitHub - - **Impact**: HIGH - Cannot push to new repository name - -2. **Source Code Contains Old Name** - - Multiple source files in `afi-gateway/src/` still reference `afi-eliza-gateway` - - **Impact**: HIGH - Runtime logs and API responses show old name - - **Files affected**: server.ts, cli.ts, all character files, plugin files - -3. **Cross-Repo Documentation Not Updated** - - `afi-reactor/AGENTS.md` still references old name - - **Impact**: MEDIUM - Documentation inconsistency across repos - -### Medium Priority 🟡 - -4. **Documentation Files Not Updated** - - 10+ documentation files in `afi-gateway/docs/` contain old name references - - **Impact**: MEDIUM - Confusing for developers and users - -5. **No CI/CD Workflows Found** - - No `.github/workflows/` directory exists - - **Impact**: MEDIUM - No automated testing/deployment configured - ---- - -## Recommended Next Steps - -### Immediate Actions (Required for Completion) - -1. **Update Git Remote** - ```bash - cd afi-gateway - git remote set-url origin git@github.com:AFI-Protocol/afi-gateway.git - ``` - -2. **Update Source Code Files** - - Update [`afi-gateway/src/server.ts`](../afi-gateway/src/server.ts): - - Replace all instances of "afi-eliza-gateway" with "afi-gateway" - - Update class name from `AfiElizaGatewayCli` to `AfiGatewayCli` - - Update [`afi-gateway/src/cli.ts`](../afi-gateway/src/cli.ts): - - Replace all instances of "afi-eliza-gateway" with "afi-gateway" - - Update all character files: - - Replace comment "Part of: afi-eliza-gateway agent layer" with "Part of: afi-gateway agent layer" - - Update plugin files: - - Replace comment "Part of: afi-eliza-gateway integration" with "Part of: afi-gateway integration" - -3. **Update afi-reactor Documentation** - - Update [`afi-reactor/AGENTS.md`](../afi-reactor/AGENTS.md:561): - - Change section header from "afi-eliza-gateway Integration" to "afi-gateway Integration" - - Update link from `#afi-eliza-gateway-integration` to `#afi-gateway-integration` - -4. **Update afi-gateway Documentation** - - Update all files in `afi-gateway/docs/`: - - Replace all instances of "afi-eliza-gateway" with "afi-gateway" - - Update directory paths in code examples - - Update service names in examples - -### Secondary Actions (Important but Less Critical) - -5. **Search and Update Other Repositories** - - Search for references in: - - `afi-core` - - `afi-tiny-brains` - - `afi-econ` - - `afi-infra` - - `afi-docs` - - `afi-artifacts` - - `afi-benchkit` - - Update any found references - -6. **Update Agent Registry** - - Check and update `afi-reactor/config/agents.codex.json` - - Check and update `afi-reactor/src/dag/plugins/` references - -7. **Create or Update CI/CD Workflows** - - Create `.github/workflows/` directory in `afi-gateway` - - Add workflows for: - - Build - - Test - - Lint - - Deploy - -8. **Validation** - - Run `npm install` in `afi-gateway` - - Run `npm test` in `afi-gateway` - - Run `npm run build` in `afi-gateway` - - Test integration with `afi-reactor` - ---- - -## Root Cause Analysis - -The rename appears to have been initiated but not systematically completed. The pattern suggests: - -1. **Initial rename was performed** - Directory and package.json were updated -2. **Documentation was partially updated** - README.md was updated but other docs were not -3. **Source code was not updated** - All TypeScript files still contain old name references -4. **Cross-repo references were not addressed** - Other repos still reference old name -5. **Git configuration was not updated** - Remote still points to old repository - -This suggests the rename was started but abandoned before completion, possibly due to: -- Underestimation of scope -- Lack of systematic search-and-replace approach -- Missing validation steps -- No checklist to track progress - ---- - -## Conclusion - -The repository rename from `afi-eliza-gateway` to `afi-gateway` is **approximately 12% complete**. While foundational changes (directory rename, package.json, main README) have been completed, and afi-config governance documentation has been systematically updated, the vast majority of references throughout the codebase remain unchanged. - -**Recommendation**: Complete the rename systematically using the recommended next steps above, with particular attention to: -1. Git remote configuration (blocking issue) -2. Source code files in afi-gateway (runtime impact) -3. Cross-repo documentation (consistency issue) -4. Comprehensive validation before considering the task complete - ---- - -**Report Generated**: 2026-01-04 -**Assessed By**: Architect Mode -**Next Review**: After completion of recommended next steps diff --git a/AFI_REACTOR_AUGMENTCODE_AUDIT_REPORT.md b/AFI_REACTOR_AUGMENTCODE_AUDIT_REPORT.md deleted file mode 100644 index 210a941..0000000 --- a/AFI_REACTOR_AUGMENTCODE_AUDIT_REPORT.md +++ /dev/null @@ -1,826 +0,0 @@ -# AFI-Reactor Augmentcode Reference Audit & Branch Evaluation Report - -**Report Date:** 2026-01-06 -**Repository:** afi-reactor -**Location:** /Users/secretservice/AFI_Modular_Repos/afi-reactor -**Current Branch:** feat/dag-infrastructure -**Purpose:** Comprehensive audit of "augmentcode" references and branch evaluation for primary branch selection - ---- - -## Executive Summary - -This report provides a comprehensive analysis of the afi-reactor repository, focusing on two critical areas: - -1. **Reference Audit:** Identification and documentation of all "augmentcode" references across the codebase -2. **Branch Evaluation:** Analysis of all repository branches to determine the optimal primary branch - -**Key Findings:** -- **34 augmentcode references** found across 8 files (excluding node_modules) -- **8 branches** identified in the repository -- **feat/dag-infrastructure** branch is 15 commits ahead of main with 90% completeness -- **All branches** contain deprecated augmentcode references requiring cleanup -- **Recommendation:** Use feat/dag-infrastructure as primary branch after augmentcode cleanup - ---- - -## Section 1: Reference Audit - -### 1.1 Augmentcode Reference Inventory - -**Total References Found:** 34 (excluding node_modules third-party code) - -#### 1.1.1 Configuration Files (22 references) - -##### [`config/agents.codex.json`](afi-reactor/config/agents.codex.json) - 12 references - -**Lines with augmentcode:** -- Line 6: `"maintainer": "augmentcode"` (MarketDataAgentV1) -- Line 17: `"maintainer": "augmentcode"` (OnchainFeedAgentV1) -- Line 28: `"maintainer": "augmentcode"` (SocialSignalAgentV1) -- Line 39: `"maintainer": "augmentcode"` (NewsFeedAgentV1) -- Line 50: `"maintainer": "augmentcode"` (AIStrategyAgentV1) -- Line 61: `"maintainer": "augmentcode"` (TechnicalAnalysisAgentV1) -- Line 72: `"maintainer": "augmentcode"` (PatternRecognitionAgentV1) -- Line 83: `"maintainer": "augmentcode"` (SentimentAnalysisAgentV1) -- Line 94: `"maintainer": "augmentcode"` (NewsEventAgentV1) -- Line 105: `"maintainer": "augmentcode"` (AIEnsembleAgentV1) -- Line 113-116: Agent definition with augmentcode as agentId and maintainer -- Line 149: `"maintainer": "augmentcode"` (ExchangeExecutionAgentV1) - -**Context:** All agent definitions use "augmentcode" as the maintainer field. This is a legacy reference to the previous development team/vendor. - -**Recommended Replacement:** Replace "augmentcode" with "afi-reactor" or "AFI Reactor Team" - ---- - -##### [`config/dag.codex.json`](afi-reactor/config/dag.codex.json) - 7 references - -**Lines with augmentcode:** -- Line 109: `"maintainedBy": ["augmentcode"]` (alpha-scout-ingest node) -- Line 122: `"maintainedBy": ["augmentcode"]` (pixelrick-structurer node) -- Line 135: `"maintainedBy": ["augmentcode"]` (froggy-enrichment-adapter node) -- Line 152: `"maintainedBy": ["augmentcode"]` (froggy-analyst-node) -- Line 169: `"maintainedBy": ["augmentcode"]` (froggy-ensemble-scorer node) -- Line 187: `"maintainedBy": ["augmentcode"]` (execution-sim-node) -- Line 200: `"maintainedBy": ["augmentcode"]` (froggy-vault-echo node) - -**Context:** DAG node definitions use "augmentcode" in the maintainedBy array for Froggy pipeline nodes. - -**Recommended Replacement:** Replace "augmentcode" with "afi-reactor" or "AFI Reactor Team" - ---- - -##### [`config/schema.codex.json`](afi-reactor/config/schema.codex.json) - 2 references - -**Lines with augmentcode:** -- Line 10: `"maintainedBy": ["augmentcode"]` (scored-signal schema) -- Line 88: `"maintainedBy": ["Scarlet", "augmentcode"]` (cognition-metrics schema) - -**Context:** Schema definitions include "augmentcode" in the maintainedBy array. - -**Recommended Replacement:** Replace "augmentcode" with "afi-reactor" or "AFI Reactor Team" - ---- - -##### [`config/ops.codex.json`](afi-reactor/config/ops.codex.json) - 1 reference - -**Lines with augmentcode:** -- Line 45: `"trackedBy": ["Scarlet", "augmentcode"]` - -**Context:** Operations configuration includes "augmentcode" in the trackedBy array. - -**Recommended Replacement:** Replace "augmentcode" with "afi-reactor" or "AFI Reactor Team" - ---- - -#### 1.1.2 Documentation Files (10 references) - -##### [`AGENTS.md`](afi-reactor/AGENTS.md) - 7 references - -**Lines with augmentcode:** -- Line 289: `"maintainer": "augmentcode"` (example configuration) -- Line 348: `- **augmentcode**: Handles ensemble-based signal scoring using PoI and PoInsight balancing` -- Line 421: `"maintainer": "augmentcode"` (example configuration) -- Line 440: `"maintainer": "augmentcode"` (example configuration) -- Line 455: `"maintainer": "augmentcode"` (example configuration) -- Line 467-470: Agent definition with augmentcode as agentId and maintainer -- Line 515: `"maintainer": "augmentcode"` (example configuration) - -**Context:** Documentation examples use "augmentcode" as maintainer and agentId in example configurations. - -**Recommended Replacement:** Replace "augmentcode" with "afi-reactor" or "AFI Reactor Team" - ---- - -##### [`docs/AGENT_INTEGRATION_GUIDE.md`](afi-reactor/docs/AGENT_INTEGRATION_GUIDE.md) - 1 reference - -**Lines with augmentcode:** -- Line 85: `- `augmentcode` - Automated validation agent` - -**Context:** Example of validator agent in documentation. - -**Recommended Replacement:** Replace "augmentcode" with "afi-reactor" or "AFI Reactor Team" - ---- - -##### [`docs/REACTOR_HARDENING_SUMMARY.md`](afi-reactor/docs/REACTOR_HARDENING_SUMMARY.md) - 2 references - -**Lines with augmentcode:** -- Line 112: `AFI-Reactor is now documented and structured for safe extension by Factory.ai / augmentcode droids:` -- Line 177: `**Hardening Performed By:** AugmentCode` - -**Context:** Historical attribution for hardening work performed by AugmentCode. - -**Recommended Replacement:** Replace "augmentcode" with "AFI Protocol Core Team" or remove historical attribution - ---- - -#### 1.1.3 Metadata Files (2 references) - -##### [`codex/.afi-codex.json`](afi-reactor/codex/.afi-codex.json) - 2 references - -**Lines with augmentcode:** -- Line 22: `"augmentcode",` (in validators array) -- Line 62: `"augmentcode",` (in validators array) - -**Context:** Codex metadata includes "augmentcode" in the validators array. - -**Recommended Replacement:** Replace "augmentcode" with "afi-reactor" or "AFI Reactor Team" - ---- - -### 1.2 Excluded References - -**node_modules/** - 15 references in third-party rollup library files -- These are in `node_modules/rollup/dist/shared/parseAst.js` -- These are third-party library code and should NOT be changed -- Function name `augmentCodeLocation` is part of rollup's internal API - -**Total Actionable References:** 34 (excluding node_modules) - ---- - -### 1.3 Reference Summary by File Type - -| File Type | Count | Files | -|-----------|--------|-------| -| Configuration (JSON) | 22 | agents.codex.json, dag.codex.json, schema.codex.json, ops.codex.json | -| Documentation (MD) | 10 | AGENTS.md, AGENT_INTEGRATION_GUIDE.md, REACTOR_HARDENING_SUMMARY.md | -| Metadata (JSON) | 2 | .afi-codex.json | -| **Total** | **34** | **8 files** | - ---- - -### 1.4 Recommended Cleanup Actions - -#### Priority 1: Configuration Files (22 references) -1. **config/agents.codex.json** - Replace all 12 "augmentcode" maintainer fields with "afi-reactor" -2. **config/dag.codex.json** - Replace all 7 "augmentcode" maintainedBy entries with "afi-reactor" -3. **config/schema.codex.json** - Replace all 2 "augmentcode" maintainedBy entries with "afi-reactor" -4. **config/ops.codex.json** - Replace 1 "augmentcode" trackedBy entry with "afi-reactor" - -#### Priority 2: Documentation Files (10 references) -1. **AGENTS.md** - Replace all 7 "augmentcode" references with "afi-reactor" -2. **docs/AGENT_INTEGRATION_GUIDE.md** - Replace 1 "augmentcode" reference with "afi-reactor" -3. **docs/REACTOR_HARDENING_SUMMARY.md** - Replace 2 "augmentcode" references with "AFI Protocol Core Team" - -#### Priority 3: Metadata Files (2 references) -1. **codex/.afi-codex.json** - Replace all 2 "augmentcode" validator entries with "afi-reactor" - ---- - -## Section 2: Branch Evaluation - -### 2.1 Branch Inventory - -#### Local Branches - -| Branch Name | Type | Purpose | Status | -|-------------|-------|---------|--------| -| **main** | Primary | Canonical production branch | Stable but outdated | -| **feat/dag-infrastructure** | Feature | Flexible DAG system with plugin architecture | **Current branch**, 15 commits ahead | -| **demo/live** | Demo | Live demonstration branch | Local only | -| **fix/build-main-hotfix** | Fix | Build system hotfix | Local only | -| **fix/score-only-clean** | Fix | Score-only execution cleanup | Local only | -| **fix/score-only-decouple-execution** | Fix | Decouple execution from scoring | Local only | -| **release/reactor-live-testing** | Release | Live testing release | Local only | -| **security/remove-leaked-mongodb-credentials** | Security | Remove leaked credentials | Local only | - -#### Remote Branches - -| Branch Name | Remote | Status | -|-------------|---------|--------| -| **origin/main** | Yes | Canonical remote branch | -| **origin/feat/dag-infrastructure** | Yes | Feature branch with advanced features | - ---- - -### 2.2 Branch Analysis - -#### 2.2.1 Main Branch - -**Status:** Behind remote, requires pull -**Completeness:** PARTIAL (65%) -**Last Commit:** Unknown (requires git fetch) - -**Features Present:** -- ✅ Base DAG orchestration -- ✅ Signal processing pipeline -- ✅ API endpoints -- ✅ Basic agent registry -- ✅ Core orchestrator functionality - -**Features Missing:** -- ❌ TSSD Vault functionality (Phase 1) -- ❌ Provenance tracking (Phase 1.5) -- ❌ Replay capabilities (Phase 2) -- ❌ Advanced testing fixes -- ❌ CI/CD improvements -- ❌ Enhanced documentation - -**Deprecated References:** Contains all 34 augmentcode references - -**Assessment:** Stable but outdated. Lacks critical Phase 1.5-2 features. - ---- - -#### 2.2.2 feat/dag-infrastructure Branch - -**Status:** 15 commits ahead of main, up-to-date with remote -**Completeness:** HIGH (90%) -**Last Commit:** `9312cc6` - ci: fix afi-core dependency build in GitHub Actions -**Current Branch:** ✅ Yes - -**Features Present:** -- ✅ All main branch features -- ✅ **TSSD Vault (Phase 1)** - Secure storage and retrieval system -- ✅ **Provenance (Phase 1.5)** - Signal lineage and tracking -- ✅ **Replay (Phase 2)** - Historical signal replay capabilities -- ✅ **Test Fixes** - Improved test suite reliability -- ✅ **CI/CD Fixes** - Fixed GitHub Actions build issues -- ✅ **Enhanced Documentation** - Branch doctrine and replay specifications -- ✅ **Flexible DAG Architecture** - Plugin-based system with DAGBuilder, DAGExecutor, PluginRegistry -- ✅ **State Management** - StateManager, StateSerializer, StateValidator -- ✅ **AI/ML Provider Integration** - MLProviderRegistry and TinyBrainsProvider - -**Key Improvements Over Main:** -- Migrated from fixed 15-node pipeline to flexible, plugin-based architecture -- Added comprehensive state management with rollback capabilities -- Implemented AI/ML provider registry with fallback mechanisms -- Enhanced test coverage and CI/CD pipeline -- Improved documentation and agent integration guides - -**Deprecated References:** Contains all 34 augmentcode references - -**Assessment:** Most complete and up-to-date branch. Contains critical Phase 1.5-2 capabilities not present in main. - ---- - -#### 2.2.3 Demo Branches - -**demo/live** -- **Purpose:** Live demonstration branch -- **Status:** Local only, no remote tracking -- **Completeness:** Unknown (requires inspection) -- **Use Case:** Demonstrations and live testing -- **Assessment:** Not suitable as primary branch - ---- - -#### 2.2.4 Fix Branches - -**fix/build-main-hotfix** -- **Purpose:** Build system hotfix -- **Status:** Local only, no remote tracking -- **Completeness:** Unknown (requires inspection) -- **Use Case:** Build system fixes -- **Assessment:** Not suitable as primary branch - -**fix/score-only-clean** -- **Purpose:** Score-only execution cleanup -- **Status:** Local only, no remote tracking -- **Completeness:** Unknown (requires inspection) -- **Use Case:** Execution pipeline improvements -- **Assessment:** Not suitable as primary branch - -**fix/score-only-decouple-execution** -- **Purpose:** Decouple execution from scoring -- **Status:** Local only, no remote tracking -- **Completeness:** Unknown (requires inspection) -- **Use Case:** Architecture improvements -- **Assessment:** Not suitable as primary branch - ---- - -#### 2.2.5 Release Branch - -**release/reactor-live-testing** -- **Purpose:** Live testing release -- **Status:** Local only, no remote tracking -- **Completeness:** Unknown (requires inspection) -- **Use Case:** Release testing -- **Assessment:** Not suitable as primary branch - ---- - -#### 2.2.6 Security Branch - -**security/remove-leaked-mongodb-credentials** -- **Purpose:** Remove leaked MongoDB credentials -- **Status:** Local only, no remote tracking -- **Completeness:** Unknown (requires inspection) -- **Use Case:** Security fix -- **Assessment:** Not suitable as primary branch - ---- - -### 2.3 Branch Comparison Matrix - -| Feature | main | feat/dag-infrastructure | Other Branches | -|----------|--------|------------------------|----------------| -| Base DAG Orchestration | ✅ | ✅ | Unknown | -| Signal Processing Pipeline | ✅ | ✅ | Unknown | -| API Endpoints | ✅ | ✅ | Unknown | -| Basic Agent Registry | ✅ | ✅ | Unknown | -| TSSD Vault (Phase 1) | ❌ | ✅ | Unknown | -| Provenance (Phase 1.5) | ❌ | ✅ | Unknown | -| Replay (Phase 2) | ❌ | ✅ | Unknown | -| Flexible DAG Architecture | ❌ | ✅ | Unknown | -| State Management | ❌ | ✅ | Unknown | -| AI/ML Provider Integration | ❌ | ✅ | Unknown | -| CI/CD Fixes | ❌ | ✅ | Unknown | -| Enhanced Documentation | ❌ | ✅ | Unknown | -| Test Suite Improvements | ❌ | ✅ | Unknown | -| **Completeness** | **65%** | **90%** | **Unknown** | -| **Commits Ahead** | **0** | **15** | **N/A** | -| **Deprecated References** | **34** | **34** | **Unknown** | - ---- - -### 2.4 Branch Health Indicators - -#### Main Branch -- **Stability:** ✅ High (canonical branch) -- **Recency:** ⚠️ Low (behind remote) -- **Feature Completeness:** ⚠️ Low (65%) -- **Code Quality:** ✅ Good (stable) -- **Documentation:** ⚠️ Basic -- **Test Coverage:** ⚠️ Unknown -- **CI/CD:** ⚠️ Basic -- **Deprecated References:** ❌ 34 present - -#### feat/dag-infrastructure Branch -- **Stability:** ✅ High (15 commits tested) -- **Recency:** ✅ High (up-to-date with remote) -- **Feature Completeness:** ✅ High (90%) -- **Code Quality:** ✅ Good (includes fixes) -- **Documentation:** ✅ Comprehensive -- **Test Coverage:** ✅ Improved -- **CI/CD:** ✅ Fixed and working -- **Deprecated References:** ❌ 34 present (needs cleanup) - ---- - -## Section 3: Recommendations - -### 3.1 Primary Branch Recommendation - -**RECOMMENDATION:** Use **feat/dag-infrastructure** as the primary branch after augmentcode cleanup. - -**Rationale:** - -1. **Feature Completeness (90% vs 65%)** - - Contains critical Phase 1.5-2 capabilities (TSSD Vault, Provenance, Replay) - - Implements flexible DAG architecture with plugin system - - Includes state management and AI/ML provider integration - - These features are essential for production deployment - -2. **Code Quality Improvements** - - Fixed CI/CD pipeline issues - - Improved test suite reliability - - Enhanced documentation and agent integration guides - - Better error handling and retry logic - -3. **Active Development** - - 15 commits ahead of main - - Up-to-date with remote - - Recent commits show active maintenance - - Current working branch - -4. **Architecture Modernization** - - Migrated from fixed 15-node pipeline to flexible, plugin-based architecture - - Better separation of concerns - - More maintainable and extensible - - Follows AFI Orchestrator Doctrine - ---- - -### 3.2 Cleanup Strategy - -#### Phase 1: Augmentcode Reference Removal (Immediate) - -**Priority 1: Configuration Files** -```bash -# Replace augmentcode with afi-reactor in config files -cd afi-reactor -sed -i '' 's/"augmentcode"/"afi-reactor"/g' config/agents.codex.json -sed -i '' 's/"augmentcode"/"afi-reactor"/g' config/dag.codex.json -sed -i '' 's/"augmentcode"/"afi-reactor"/g' config/schema.codex.json -sed -i '' 's/"augmentcode"/"afi-reactor"/g' config/ops.codex.json -``` - -**Priority 2: Documentation Files** -```bash -# Replace augmentcode with afi-reactor in documentation -sed -i '' 's/"augmentcode"/"afi-reactor"/g' AGENTS.md -sed -i '' 's/"augmentcode"/"afi-reactor"/g' docs/AGENT_INTEGRATION_GUIDE.md -sed -i '' 's/AugmentCode/AFI Protocol Core Team/g' docs/REACTOR_HARDENING_SUMMARY.md -``` - -**Priority 3: Metadata Files** -```bash -# Replace augmentcode with afi-reactor in metadata -sed -i '' 's/"augmentcode"/"afi-reactor"/g' codex/.afi-codex.json -``` - -**Verification:** -```bash -# Verify all augmentcode references are removed -grep -ri "augmentcode" --exclude-dir=node_modules --exclude-dir=.git . -``` - ---- - -#### Phase 2: Branch Consolidation (After Cleanup) - -**Step 1: Create Backup Branch** -```bash -git checkout feat/dag-infrastructure -git branch backup-before-merge -``` - -**Step 2: Perform Augmentcode Cleanup** -```bash -# Execute Phase 1 cleanup commands -git add . -git commit -m "refactor: replace augmentcode references with afi-reactor" -``` - -**Step 3: Merge into Main** -```bash -git checkout main -git pull origin main -git merge feat/dag-infrastructure --no-ff -``` - -**Step 4: Resolve Conflicts (if any)** -```bash -# Review and resolve merge conflicts -git add . -git commit -m "merge: integrate feat/dag-infrastructure into main" -``` - -**Step 5: Push to Remote** -```bash -git push origin main -``` - -**Step 6: Update Remote Feature Branch** -```bash -git checkout feat/dag-infrastructure -git merge main -git push origin feat/dag-infrastructure -``` - ---- - -#### Phase 3: Validation and Testing - -**Step 1: Run Tests** -```bash -npm test -npm run validate-all -``` - -**Step 2: Build Verification** -```bash -npm run build -``` - -**Step 3: Integration Testing** -```bash -npm run simulate-signal -npm run simulate-from-vault -npm run replay-vault -``` - -**Step 4: Demo Server** -```bash -npm run start:demo -``` - ---- - -### 3.3 Alternative Strategy: Replace Main with feat/dag-infrastructure - -If merging is complex due to conflicts, consider: - -**Option A: Fast-Forward Main** -```bash -git checkout main -git reset --hard feat/dag-infrastructure -git push origin main --force -``` - -**Option B: Rename Branches** -```bash -git branch -m main main-backup -git branch -m feat/dag-infrastructure main -git push origin main --force -``` - -**⚠️ WARNING:** These options are destructive and should only be used if: -- Merge conflicts are unresolvable -- Team agrees to replace main entirely -- Backup branches are created first -- All stakeholders are notified - ---- - -### 3.4 Post-Cleanup Actions - -1. **Update Documentation** - - Update README.md to reflect new primary branch - - Update CONTRIBUTING.md with new branch strategy - - Update AFI_ORCHESTRATOR_DOCTRINE.md if needed - -2. **Update CI/CD** - - Update GitHub Actions to use main as default branch - - Update deployment scripts - - Update branch protection rules - -3. **Notify Stakeholders** - - Announce branch consolidation to team - - Document migration in changelog - - Update project status reports - -4. **Archive Old Branches** - - Archive local-only branches (demo, fix, release, security) - - Document branch history in repository - - Clean up stale remote branches if needed - ---- - -## Section 4: Risk Assessment - -### 4.1 Cleanup Risks - -| Risk | Likelihood | Impact | Mitigation | -|-------|-----------|---------|------------| -| Breaking configuration changes | Low | High | Test thoroughly after changes | -| Documentation inconsistencies | Medium | Medium | Review all documentation files | -| Metadata validation failures | Low | Medium | Run validation scripts | -| Node modules corruption | Very Low | High | Exclude node_modules from changes | - -### 4.2 Merge Risks - -| Risk | Likelihood | Impact | Mitigation | -|-------|-----------|---------|------------| -| Merge conflicts | Medium | Medium | Create backup branch, resolve carefully | -| Test failures | Medium | High | Run full test suite post-merge | -| CI/CD pipeline issues | Low | High | Verify GitHub Actions configuration | -| Deployment issues | Low | High | Test in staging environment first | - -### 4.3 Branch Replacement Risks - -| Risk | Likelihood | Impact | Mitigation | -|-------|-----------|---------|------------| -| Loss of main branch history | High | Critical | Create backup before replacement | -| Team confusion | Medium | Medium | Communicate changes clearly | -| CI/CD pipeline breakage | Medium | High | Update all CI/CD configurations | -| Deployment errors | Low | Critical | Test thoroughly in staging | - ---- - -## Section 5: Implementation Timeline - -### Week 1: Preparation -- [ ] Review this report with team -- [ ] Get approval for cleanup strategy -- [ ] Create backup branches -- [ ] Prepare rollback plan - -### Week 2: Cleanup -- [ ] Execute Phase 1 augmentcode cleanup -- [ ] Verify all references removed -- [ ] Run validation scripts -- [ ] Commit changes - -### Week 3: Consolidation -- [ ] Execute Phase 2 branch consolidation -- [ ] Resolve any merge conflicts -- [ ] Push to remote -- [ ] Update CI/CD configurations - -### Week 4: Validation -- [ ] Execute Phase 3 validation and testing -- [ ] Fix any issues found -- [ ] Update documentation -- [ ] Notify stakeholders - -### Week 5: Post-Migration -- [ ] Archive old branches -- [ ] Update project documentation -- [ ] Monitor for issues -- [ ] Create post-migration report - ---- - -## Section 6: Success Criteria - -### Cleanup Success Criteria -- [ ] Zero augmentcode references in codebase (excluding node_modules) -- [ ] All configuration files validate successfully -- [ ] All tests pass -- [ ] Build completes without errors -- [ ] Documentation is consistent - -### Branch Consolidation Success Criteria -- [ ] Main branch contains all Phase 1.5-2 features -- [ ] CI/CD pipeline passes on main -- [ ] Demo server runs successfully -- [ ] Integration tests pass -- [ ] No merge conflicts remain - -### Post-Migration Success Criteria -- [ ] Team is using main as primary branch -- [ ] CI/CD deploys from main -- [ ] Documentation reflects new structure -- [ ] No production issues reported -- [ ] Stakeholders are satisfied - ---- - -## Section 7: Conclusion - -The afi-reactor repository requires immediate cleanup to eliminate deprecated "augmentcode" references and branch consolidation to unify advanced features into the canonical main branch. - -**Key Takeaways:** - -1. **34 augmentcode references** must be removed across 8 files -2. **feat/dag-infrastructure** is the most complete branch (90% vs 65%) -3. **Phase 1.5-2 features** (TSSD Vault, Provenance, Replay) are critical for production -4. **Flexible DAG architecture** provides better maintainability and extensibility -5. **Cleanup and consolidation** should be executed in phases with proper testing - -**Recommended Action Plan:** - -1. **Immediate:** Execute augmentcode cleanup on feat/dag-infrastructure branch -2. **Short-term:** Merge feat/dag-infrastructure into main after cleanup -3. **Medium-term:** Validate and test consolidated main branch -4. **Long-term:** Archive old branches and update documentation - -**Expected Outcome:** - -A unified, production-ready afi-reactor repository with: -- Zero deprecated references -- Complete Phase 1.5-2 capabilities -- Flexible, maintainable architecture -- Comprehensive documentation -- Robust CI/CD pipeline - ---- - -## Appendix A: File Reference Details - -### A.1 Configuration Files - -#### config/agents.codex.json -```json -{ - "agentId": "MarketDataAgentV1", - "maintainer": "augmentcode", // Line 6 - REPLACE - ... -} -``` - -#### config/dag.codex.json -```json -{ - "id": "alpha-scout-ingest", - "maintainedBy": ["augmentcode"], // Line 109 - REPLACE - ... -} -``` - -#### config/schema.codex.json -```json -{ - "schemaRef": "scored-signal.schema.json", - "maintainedBy": ["augmentcode"], // Line 10 - REPLACE - ... -} -``` - -#### config/ops.codex.json -```json -{ - "trackedBy": ["Scarlet", "augmentcode"], // Line 45 - REPLACE - ... -} -``` - -### A.2 Documentation Files - -#### AGENTS.md -```markdown -{ - "maintainer": "augmentcode", // Line 289 - REPLACE - ... -} -``` - -#### docs/AGENT_INTEGRATION_GUIDE.md -```markdown -- `augmentcode` - Automated validation agent // Line 85 - REPLACE -``` - -#### docs/REACTOR_HARDENING_SUMMARY.md -```markdown -**Hardening Performed By:** AugmentCode // Line 177 - REPLACE -``` - -### A.3 Metadata Files - -#### codex/.afi-codex.json -```json -{ - "validators": [ - "augmentcode", // Line 22 - REPLACE - ... - ] -} -``` - ---- - -## Appendix B: Branch Commands Reference - -### List All Branches -```bash -git branch -a -``` - -### Show Branch Details -```bash -git log --oneline -n 5 -git show-branch -``` - -### Compare Branches -```bash -git diff main...feat/dag-infrastructure -git log --oneline main..feat/dag-infrastructure -git rev-list --left-right --count main...feat/dag-infrastructure -``` - -### Merge Branches -```bash -git checkout main -git merge feat/dag-infrastructure -``` - -### Resolve Conflicts -```bash -git status -# Edit conflicted files -git add -git commit -``` - -### Push to Remote -```bash -git push origin -``` - -### Delete Branches -```bash -git branch -d -git push origin --delete -``` - ---- - -**Report End** - -**Next Steps:** -1. Review this report with the team -2. Approve cleanup strategy -3. Execute Phase 1 augmentcode cleanup -4. Proceed with branch consolidation - -**Questions or Concerns:** -- Contact the AFI Protocol Core Team for clarification -- Refer to AFI_ORCHESTRATOR_DOCTRINE.md for guidance -- Consult AFI_DROID_CHARTER.v0.1.md for droid behavior diff --git a/ARCHITECTURE_STATUS.md b/ARCHITECTURE_STATUS.md index ebb503c..74824d0 100644 --- a/ARCHITECTURE_STATUS.md +++ b/ARCHITECTURE_STATUS.md @@ -13,7 +13,9 @@ - Pipelines are **registered, never hardcoded**: at boot the runtime validates the governed registries in `afi-config` (`registries/analysis-plugins`, `registries/pipelines`, `registries/analyst-strategies`, - `registries/provider-bindings`) and refuses to start on any invalid active + `registries/provider-bindings`, and the FLPR-GOV enrichment-provider + registries `registries/providers`, `registries/provider-instances`, + `registries/credential-refs`) and refuses to start on any invalid active entry — honest failure, no demo/mock/fallback path. - A pipeline graph is an **`afi.pipeline.v1` manifest** (governed contract home: `afi-config/schemas/pipeline/v1/`) composing **registered strategy nodes** @@ -34,7 +36,12 @@ Implementation lives under: - `afi-reactor/src/pipeline/` — graph executor, plugin registry, registry loader, - the five category nodes and scorer terminal, canonical hashing, execution summaries + the five provider-backed lane bindings, the five-category join and scorer + terminal, canonical hashing, execution summaries +- `afi-reactor/src/providers/` — the sole enrichment-execution seam (FLPR-GOV): + the static adapter registry, provider/instance/credential-ref resolution, the + least-privilege SecretResolver, canonical category-output validation, and the + trusted service clients - `afi-reactor/src/config/runtimeComposition.ts` — the boot-validated composition root --- diff --git a/PRIORITY2_IMPLEMENTATION_PLAN.md b/PRIORITY2_IMPLEMENTATION_PLAN.md deleted file mode 100644 index 513653f..0000000 --- a/PRIORITY2_IMPLEMENTATION_PLAN.md +++ /dev/null @@ -1,593 +0,0 @@ -# Priority 2 Implementation Plan for AGENTS.md - -**Date**: 2025-12-31 -**Status**: Planning Phase -**Scope**: Priority 2 (HIGH) tasks from AGENTS_AUDIT_REPORT.md - ---- - -## Executive Summary - -This plan addresses Priority 2 (HIGH) tasks from the AGENTS_AUDIT_REPORT.md audit report. These tasks build upon the completed Priority 1 (CRITICAL) updates to ensure comprehensive documentation alignment with the current afi-reactor codebase. - -**Priority 2 Tasks**: -1. Update Pipeline Description (Line 34-36) -2. Add afi-gateway Integration Section -3. Add Agent Registry Section - -**Context**: Priority 1 tasks have been completed, including: -- Directory structure corrections -- Flexible DAG architecture documentation -- Node types documentation -- Build and test commands updates - ---- - -## Comprehensive Audit Report Review - -### Current State Analysis - -**Completed Priority 1 Changes**: -- ✅ Directory structure updated (src/dags/ → src/dag/) -- ✅ All documented directories added (state/, aiMl/, adapters/, collectors/, core/, cpj/, enrichment/, indicator/, news/, novelty/, services/, uss/, utils/) -- ✅ Flexible DAG architecture section added (DAGBuilder, DAGExecutor, PluginRegistry, StateManager, MLProviderRegistry) -- ✅ Node types section added (AnalystNode, ExecutionNode, ObserverNode, and plugin nodes) -- ✅ Pipeline description updated to "flexible, plugin-based DAG pipeline" -- ✅ afi-gateway integration section added -- ✅ Build and test commands updated - -**Remaining Priority 2 Tasks**: - -#### Task 1: Update Pipeline Description (Line 34-36) -**Current State**: Already updated in Priority 1 -**Status**: ✅ COMPLETED -**Action**: No additional action needed - this was addressed in Priority 1 - -#### Task 2: Add afi-gateway Integration Section -**Current State**: Already added in Priority 1 -**Status**: ✅ COMPLETED -**Action**: No additional action needed - this was addressed in Priority 1 - -#### Task 3: Add Agent Registry Section -**Current State**: NOT YET IMPLEMENTED -**Status**: ⏳ PENDING -**Action**: This is the primary remaining Priority 2 task - -### Architectural Drift Prevention - -**Risk Assessment**: With Priority 1 changes complete, there is a risk of architectural drift if Priority 2 tasks are not implemented consistently with the same level of detail and accuracy. - -**Mitigation Strategy**: -1. Maintain consistency with Priority 1 documentation style -2. Ensure all new sections reference existing Priority 1 content -3. Cross-reference with actual codebase implementations -4. Validate against audit report requirements before completion - ---- - -## Priority 2 Task Analysis - -### Task 3: Add Agent Registry Section - -**Audit Report Requirement** (Issue 8.1): -```markdown -#### Issue 8.1: No Reference to Agent Registries - -**What's Missing**: -- **agent.registry.json** - Registry of available agents -- **execution-agent.registry.json** - Registry of execution agents -- **agents.codex.json** - Codex metadata for agents - -**Current AGENTS.md Coverage**: None - -**Impact**: MEDIUM - Agent registries are not documented, making it unclear how agents are discovered and registered. - -**Evidence from config directory**: -```json -// From afi-reactor/config/agent.registry.json -{ - "agents": [ - { - "id": "froggy-analyst-node", - "name": "Froggy Analyst", - "type": "analyzer", - "plugin": "froggy.trend_pullback_v1", - "agentReady": true - } - ] -} -``` - -**Action Required**: Add section describing agent registry system and how agents are registered. -``` - -**Codebase Evidence**: - -From [`afi-reactor/config/agent.registry.json`](afi-reactor/config/agent.registry.json): -- Contains agent definitions with fields: agentName, entry, strategy, version, description, enabled, tags -- Currently has 1 agent: "signal-agent" (stub strategy) - -From [`afi-reactor/config/execution-agent.registry.json`](afi-reactor/config/execution-agent.registry.json): -- Contains execution agent configurations -- Three execution agents: binance-local, coinbase-remote, paper-sim -- Each has: type, auth, entry, description, mode, environment - -From [`afi-reactor/config/agents.codex.json`](afi-reactor/config/agents.codex.json): -- Contains comprehensive agent metadata -- 12 agents defined with: agentId, linkedNodes, description, maintainer, agentReady, status, role, capabilities, version -- Agent types include: generators, analyzers, scorers, validators, persisters, executors, observers - -**Key Fields**: -- `agentId`: Unique identifier for the agent -- `linkedNodes`: Array of node IDs this agent connects to -- `description`: Human-readable description of agent's purpose -- `maintainer`: Repository or team responsible for agent -- `agentReady`: Boolean flag indicating if agent is ready for production use -- `status`: Current status (active, deprecated, etc.) -- `role`: Functional role (generator, analyzer, scorer, validator, persister, executor, observer) -- `capabilities`: Array of capabilities the agent provides -- `version`: Semantic version of agent implementation - ---- - -## Implementation Strategy - -### Section Placement - -**Insert Location**: After "afi-gateway Integration" section (approximately line 197) - -**Rationale**: This placement follows the logical flow of the document: -1. Architecture Overview -2. Flexible DAG Architecture -3. Node Types -4. afi-gateway Integration -5. **Agent Registry** ← NEW SECTION HERE -6. Build and Test Commands -7. Security -8. Git Workflows -9. Conventions & Patterns -10. ESM Invariants -11. Scope & Boundaries for Agents - -### Content Structure - -The Agent Registry section should include: - -1. **Overview**: Purpose of agent registry system -2. **Registry Files**: Description of each registry file -3. **Agent Metadata**: Explanation of key fields (agentId, linkedNodes, agentReady, etc.) -4. **Agent Roles**: Description of different agent roles (generator, analyzer, scorer, validator, persister, executor, observer) -5. **Agent Discovery**: How agents are discovered and loaded -6. **Agent Registration**: How new agents are registered -7. **agentReady Flag**: Purpose and usage -8. **Integration with DAG**: How agents connect to DAG nodes -9. **Examples**: Concrete examples from agents.codex.json - -### Dependencies - -**No Code Changes Required**: This is documentation-only task -**Cross-References**: Should reference existing sections (Flexible DAG Architecture, Node Types) for consistency -**Validation**: Must align with actual registry file structures - ---- - -## Detailed Implementation Plan - -### Step 1: Create Agent Registry Section - -**Content to Add**: - -```markdown -## Agent Registry - -afi-reactor uses a registry system to manage agent configurations and their integration with the DAG pipeline. The registry enables dynamic agent discovery, registration, and lifecycle management. - -### Registry Files - -#### agent.registry.json -Located in `config/agent.registry.json`, this registry contains agent definitions for signal generation and analysis. - -**Structure**: -```json -{ - "agents": [ - { - "agentName": "signal-agent", - "entry": "tools/agents/signal-agent.ts", - "strategy": "mean-reversion", - "version": "0.1.0", - "description": "A stub strategy simulating mean-reversion behavior.", - "enabled": true, - "tags": ["stub", "strategy", "demo"] - } - ] -} -``` - -**Purpose**: Defines available signal agents and their entry points. - -#### execution-agent.registry.json -Located in `config/execution-agent.registry.json`, this registry contains execution agent configurations for trade execution. - -**Structure**: -```json -{ - "binance-local": { - "type": "local", - "auth": "env", - "entry": "tools/execution/binance-local.ts", - "description": "Direct Binance API execution using local environment variables.", - "mode": "simulated", - "environment": "dev" - }, - "coinbase-remote": { - "type": "remote", - "auth": "injected", - "entry": "tools/execution/coinbase-remote.ts", - "description": "Remote execution via secure agent, credentials injected at runtime.", - "mode": "simulated", - "environment": "dev" - }, - "paper-sim": { - "type": "simulated", - "auth": "none", - "entry": "tools/execution/paper-sim.ts", - "description": "Simulation agent for testing execution logic without real orders.", - "mode": "simulated", - "environment": "dev" - } -} -``` - -**Purpose**: Defines available execution agents and their authentication methods. - -#### agents.codex.json -Located in `config/agents.codex.json`, this registry contains comprehensive metadata for all agents in the AFI ecosystem. - -**Structure**: -```json -[ - { - "agentId": "MarketDataAgentV1", - "linkedNodes": ["market-data-streamer"], - "description": "Streams real-time market prices, OHLCV, and order books from multiple exchanges", - "maintainer": "augmentcode", - "agentReady": true, - "status": "active", - "role": "generator", - "capabilities": ["price-streaming", "orderbook-analysis", "volume-tracking"], - "version": "1.0.0" - } -] -``` - -**Purpose**: Provides canonical metadata for agents, including their capabilities, roles, and integration points. - -### Agent Metadata Fields - -**Key Fields**: - -- **agentId**: Unique identifier for the agent (e.g., "MarketDataAgentV1", "FroggyAnalystNode") -- **linkedNodes**: Array of DAG node IDs this agent connects to (e.g., ["market-data-streamer"], ["technical-indicators", "pattern-recognition"]) -- **description**: Human-readable description of the agent's purpose and functionality -- **maintainer**: Repository or team responsible for maintaining the agent -- **agentReady**: Boolean flag indicating if the agent is ready for production use -- **status**: Current status of the agent (active, deprecated, experimental) -- **role**: Functional role in the pipeline: - - **generator**: Produces signals or data (e.g., MarketDataAgent, OnchainFeedAgent, SocialSignalAgent, NewsFeedAgent, AIStrategyAgent) - - **analyzer**: Analyzes signals or data (e.g., TechnicalAnalysisAgent, PatternRecognitionAgent, SentimentAnalysisAgent, NewsEventAgent, AIEnsembleAgent) - - **scorer**: Assigns scores to signals (e.g., augmentcode) - - **validator**: Validates signals (e.g., factory.droid) - - **persister**: Persists signals (e.g., scarlet) - - **executor**: Executes trades (e.g., ExchangeExecutionAgent) - - **observer**: Observes and logs results (e.g., TelemetryAgent) -- **capabilities**: Array of capabilities the agent provides (e.g., ["price-streaming", "technical-indicators", "trade-execution"]) -- **version**: Semantic version of the agent implementation - -### Agent Roles - -#### Generator Agents -Produce signals or data for the pipeline: - -- **MarketDataAgentV1**: Streams real-time market prices, OHLCV, and order books -- **OnchainFeedAgentV1**: Ingests blockchain events and DeFi protocol data -- **SocialSignalAgentV1**: Collects Twitter, Discord, and social sentiment signals -- **NewsFeedAgentV1**: Parses financial news and RSS feeds for breaking events -- **AIStrategyAgentV1**: Generates candidate trading signals using AI models - -#### Analyzer Agents -Analyze signals or data: - -- **TechnicalAnalysisAgentV1**: Runs MACD, RSI, Bollinger, and other TA indicators -- **PatternRecognitionAgentV1**: Detects price action setups and chart patterns -- **SentimentAnalysisAgentV1**: Scores market and social sentiment for bias detection -- **NewsEventAgentV1**: Evaluates market impact of news and events -- **AIEnsembleAgentV1**: Aggregates multiple analyses into a final weighted score - -#### Scorer Agents -Assign scores to signals: - -- **augmentcode**: Handles ensemble-based signal scoring using PoI and PoInsight balancing - -#### Validator Agents -Validate signals: - -- **factory.droid**: Handles DAO quorum verification and checkpoint validation - -#### Persister Agents -Persist signals: - -- **scarlet**: Manages MongoDB T.S.S.D. Vault persistence of approved signals - -#### Executor Agents -Execute trades: - -- **ExchangeExecutionAgentV1**: Executes trades via exchanges with risk controls - -#### Observer Agents -Observe and log results: - -- **TelemetryAgentV1**: Logs all signals, scores, and execution results to T.S.S.D. vault - -### Agent Discovery and Registration - -**Discovery Process**: -1. Registry files are loaded at startup from `config/` directory -2. Agent metadata is parsed and validated -3. Agents are indexed by `agentId` for fast lookup -4. Agents with `agentReady: true` are marked as available for production use - -**Registration Process**: -1. New agents are added to registry files -2. Agent metadata is validated against schema -3. `agentReady` flag is set to `false` for new agents until testing is complete -4. Once tested and validated, `agentReady` is set to `true` -5. Registry is reloaded to pick up new agents - -### agentReady Flag - -**Purpose**: The `agentReady` flag indicates whether an agent is ready for production use. - -**Usage**: -- **true**: Agent has been tested, validated, and is ready for production deployment -- **false**: Agent is under development, testing, or not yet validated - -**Lifecycle**: -1. Development: `agentReady: false` -2. Testing: `agentReady: false` (during testing) -3. Validation: `agentReady: false` (during validation) -4. Production: `agentReady: true` (after successful validation) - -### Integration with DAG - -Agents integrate with the DAG pipeline through their `linkedNodes` field: - -1. **Generator Agents**: Connect to ingress nodes (e.g., ScoutNode, SignalIngressNode) -2. **Analyzer Agents**: Connect to enrichment nodes (e.g., TechnicalIndicatorsNode, PatternRecognitionNode, SentimentNode, NewsNode, AiMlNode) -3. **Scorer Agents**: Connect to AnalystNode for final scoring -4. **Validator Agents**: Connect to validation nodes in the DAG -5. **Persister Agents**: Connect to persistence nodes (e.g., TSSD Vault) -6. **Executor Agents**: Connect to ExecutionNode for trade execution -7. **Observer Agents**: Connect to ObserverNode for logging and telemetry - -**Example Integration**: -```json -{ - "agentId": "TechnicalAnalysisAgentV1", - "linkedNodes": ["technical-indicators"], - "description": "Runs MACD, RSI, Bollinger, and other TA indicators", - "maintainer": "augmentcode", - "agentReady": true, - "status": "active", - "role": "analyzer", - "capabilities": ["technical-indicators", "trend-analysis", "support-resistance"], - "version": "1.0.0" -} -``` - -This agent connects to the `TechnicalIndicatorsNode` plugin in the DAG, providing technical indicator enrichment for signals. - -### Examples - -**Example 1: Generator Agent** -```json -{ - "agentId": "MarketDataAgentV1", - "linkedNodes": ["market-data-streamer"], - "description": "Streams real-time market prices, OHLCV, and order books from multiple exchanges", - "maintainer": "augmentcode", - "agentReady": true, - "status": "active", - "role": "generator", - "capabilities": ["price-streaming", "orderbook-analysis", "volume-tracking"], - "version": "1.0.0" -} -``` - -**Example 2: Analyzer Agent** -```json -{ - "agentId": "TechnicalAnalysisAgentV1", - "linkedNodes": ["technical-indicators"], - "description": "Runs MACD, RSI, Bollinger, and other TA indicators", - "maintainer": "augmentcode", - "agentReady": true, - "status": "active", - "role": "analyzer", - "capabilities": ["technical-indicators", "trend-analysis", "support-resistance"], - "version": "1.0.0" -} -``` - -**Example 3: Scorer Agent** -```json -{ - "agentId": "augmentcode", - "linkedNodes": ["afi-ensemble-score"], - "description": "AugmentCode handles ensemble-based signal scoring using PoI and PoInsight balancing", - "maintainer": "augmentcode", - "agentReady": true, - "status": "active", - "role": "scorer", - "capabilities": ["poi-scoring", "insight-balancing", "ensemble-validation"], - "version": "1.0.0" -} -``` - -**Example 4: Validator Agent** -```json -{ - "agentId": "factory.droid", - "linkedNodes": ["dao-mint-checkpoint"], - "description": "Factory Droids handle DAO quorum verification and checkpoint validation", - "maintainer": "factory.droid", - "agentReady": true, - "status": "active", - "role": "validator", - "capabilities": ["dao-consensus", "quorum-verification", "mint-eligibility"], - "version": "1.0.0" -} -``` - -**Example 5: Persister Agent** -```json -{ - "agentId": "scarlet", - "linkedNodes": ["tssd-vault-persist"], - "description": "Scarlet manages MongoDB T.S.S.D. Vault persistence of approved signals", - "maintainer": "Scarlet", - "agentReady": true, - "status": "active", - "role": "persister", - "capabilities": ["vault-storage", "data-persistence", "signal-archival"], - "version": "1.0.0" -} -``` - -**Example 6: Executor Agent** -```json -{ - "agentId": "ExchangeExecutionAgentV1", - "linkedNodes": ["exchange-execution-node"], - "description": "Executes trades via exchanges with risk controls and position management", - "maintainer": "augmentcode", - "agentReady": true, - "status": "active", - "role": "executor", - "capabilities": ["trade-execution", "risk-management", "position-sizing"], - "version": "1.0.0" -} -``` - -**Example 7: Observer Agent** -```json -{ - "agentId": "TelemetryAgentV1", - "linkedNodes": ["telemetry-log-node"], - "description": "Logs all signals, scores, and execution results to T.S.S.D. vault for monitoring", - "maintainer": "Scarlet", - "agentReady": true, - "status": "active", - "role": "observer", - "capabilities": ["telemetry-logging", "performance-monitoring", "data-analytics"], - "version": "1.0.0" -} -``` - -### Best Practices - -**For Contributors**: -1. When adding a new agent, update the appropriate registry file -2. Set `agentReady: false` during development and testing -3. Set `agentReady: true` only after thorough testing and validation -4. Provide clear descriptions and capabilities -5. Specify the correct `linkedNodes` for DAG integration -6. Use semantic versioning for `version` field -7. Tag agents appropriately (e.g., "stub", "strategy", "demo") - -**For Maintainers**: -1. Review agent registry changes in pull requests -2. Validate agent metadata against schema -3. Test agent integration with DAG before setting `agentReady: true` -4. Monitor agent performance and status -5. Update agent status as needed (active, deprecated, etc.) - -### Related Documentation - -- [Flexible DAG Architecture](#flexible-dag-architecture) - How DAG nodes are composed and executed -- [Node Types](#node-types) - Core nodes and plugin nodes in the DAG -- [afi-gateway Integration](#afi-gateway-integration) - ElizaOS agent integration -- [AFI Orchestrator Doctrine](../AFI_ORCHESTRATOR_DOCTRINE.md) - Guidelines for agent behavior -``` - ---- - -## Execution Approach - -### Phase 1: Planning (Current Phase) -- [x] Review audit report Priority 2 requirements -- [x] Analyze agent registry files -- [x] Assess dependencies on existing codebase -- [x] Generate detailed implementation strategy -- [x] Create structured approach for execution - -### Phase 2: Implementation (Next Phase) -- [ ] Add Agent Registry section to AGENTS.md -- [ ] Validate section placement and formatting -- [ ] Cross-reference with existing sections -- [ ] Ensure consistency with Priority 1 documentation style -- [ ] Verify all examples match actual registry files - -### Phase 3: Validation -- [ ] Review completed section against audit report requirements -- [ ] Verify all registry files are accurately documented -- [ ] Check for consistency with codebase -- [ ] Validate markdown formatting and structure - -### Phase 4: Completion -- [ ] Update todo list to mark Priority 2 tasks as complete -- [ ] Provide completion summary - ---- - -## Risk Assessment - -**Low Risk**: This is a documentation-only task with no code changes required. - -**Mitigation**: -- All content is based on existing registry files -- No architectural changes required -- Can be easily validated and corrected if needed - ---- - -## Success Criteria - -The Agent Registry section will be considered complete when: - -1. ✅ Section is added to AGENTS.md at the correct location -2. ✅ All three registry files are documented (agent.registry.json, execution-agent.registry.json, agents.codex.json) -3. ✅ Agent metadata fields are explained (agentId, linkedNodes, agentReady, status, role, capabilities, version) -4. ✅ Agent roles are described (generator, analyzer, scorer, validator, persister, executor, observer) -5. ✅ agentReady flag purpose and lifecycle are documented -6. ✅ Integration with DAG is explained -7. ✅ Concrete examples from agents.codex.json are provided -8. ✅ Best practices for contributors and maintainers are included -9. ✅ Section cross-references existing documentation sections -10. ✅ Content is validated against audit report requirements - ---- - -## Next Steps - -Once this plan is approved, the implementation will proceed in Code mode to: - -1. Add the Agent Registry section to [`afi-reactor/AGENTS.md`](afi-reactor/AGENTS.md) -2. Validate the implementation against this plan -3. Provide completion summary - ---- - -**Plan Created**: 2025-12-31 -**Status**: Ready for Implementation -**Estimated Complexity**: Low (documentation-only task) diff --git a/phase3-template-registry-status.md b/phase3-template-registry-status.md deleted file mode 100644 index d2ae9df..0000000 --- a/phase3-template-registry-status.md +++ /dev/null @@ -1,320 +0,0 @@ -# Phase 3: Template Registry - Status & Resumption Plan - -**Project:** AFI-Reactor pipeline / DAG integration -**Phase:** Phase 3 - Template Registry in afi-factory -**Status:** In Progress - Initial Information Gathering Complete -**Last Updated:** 2025-12-26T16:13:00Z - ---- - -## Executive Summary - -Phase 3 focuses on updating the afi-factory template registry to load and validate analyst configurations, bridging afi-config schemas with afi-reactor orchestration. Initial information gathering has been completed, but no code has been written yet. - ---- - -## Current Progress - -### ✅ Completed (Phase 1 & 2) -- **Phase 1 (Schema Foundation):** JSON schemas created in afi-config - - [`analyst-config.schema.json`](../afi-config/schemas/analyst-config.schema.json) - - [`enrichment-node.schema.json`](../afi-config/schemas/definitions/enrichment-node.schema.json) - - Example configurations provided - -- **Phase 2 (TypeScript Interfaces):** Type definitions created in afi-factory - - [`schemas/index.ts`](../afi-factory/schemas/index.ts) with complete interfaces - - Type guards for runtime validation - - Supporting interfaces (ValidatedAnalystConfig, TemplateRegistryEntry, LoadAnalystConfigOptions) - -### 🔄 In Progress (Phase 3) -- **Information Gathering:** ✅ Complete - - Read existing template_registry.ts (minimal implementation) - - Reviewed all schemas and examples - - Understood TypeScript interfaces from Phase 2 - -- **Implementation:** ⏳ Not Started - - No code written yet for Phase 3 - -### ⏳ Pending (Phase 3) -- Update afi-factory/template_registry.ts -- Create afi-factory/validators/analyst-config-validator.ts -- Create example analyst configurations -- Add unit tests -- Add integration tests - ---- - -## Phase 3 Objectives - -### 1. Update afi-factory/template_registry.ts -**Current State:** Minimal implementation with only `loadTemplate()` function - -**Required Functions:** -- `loadAnalystConfig(analystId, options)` - Load analyst configuration from file -- `loadEnrichmentNodeTemplate(nodeId)` - Load enrichment node template -- `listAnalystConfigs(configDir)` - List all analyst configurations -- `validateAnalystConfig(config)` - Validate analyst configuration -- `checkForCircularDependencies(nodeId, dependencies, allNodes, visited)` - Check for circular dependencies - -**Key Requirements:** -- Maintain backward compatibility with existing `loadTemplate()` function -- Use schemas from afi-config for validation -- Use TypeScript interfaces from afi-factory/schemas/index.ts -- Comprehensive error handling -- JSDoc comments - -### 2. Create afi-factory/validators/analyst-config-validator.ts -**Required Functions:** -- `validateAnalystConfig(config)` - Validate analyst configuration against schema -- `validateEnrichmentNode(node)` - Validate enrichment node -- `isValidISODate(dateString)` - Check if string is valid ISO date - -**Key Requirements:** -- Use JSON schemas from afi-config -- Return validation results with errors/warnings -- Support schema validation using ajv or similar library - -### 3. Create Example Analyst Configurations -**Required Files:** -- `afi-factory/analyst-configs/froggy-trend-pullback-v1.json` -- `afi-factory/analyst-configs/crypto-analyst-v1.json` -- `afi-factory/analyst-configs/templates/analyst-config.template.json` -- `afi-factory/analyst-configs/templates/enrichment-node.template.json` - -**Key Requirements:** -- Demonstrate different use cases -- Validate successfully against schemas -- Include comprehensive metadata - -### 4. Add Unit Tests -**Required Tests:** -- Template registry functions -- Validation functions -- Error handling -- Edge cases - -### 5. Add Integration Tests -**Required Tests:** -- End-to-end configuration loading -- Schema validation integration -- Circular dependency detection - ---- - -## Technical Context - -### Existing Code Structure - -**afi-factory/template_registry.ts** (Current): -```typescript -export const loadTemplate = (templateId: string) => { - switch (templateId) { - case 'validator-v1': - return { type: 'validator', entry: './templates/validator.ts' }; - case 'signal-emitter-basic': - return { type: 'signal', entry: './templates/emitter.ts' }; - default: - throw new Error('Template not found: ' + templateId); - } -}; -``` - -**afi-factory/schemas/index.ts** (Phase 2 - Complete): -- `EnrichmentNodeConfig` interface -- `AnalystConfig` interface -- `ValidatedAnalystConfig` interface -- `TemplateRegistryEntry` interface -- `LoadAnalystConfigOptions` interface -- Type guards: `isEnrichmentNodeConfig()`, `isAnalystConfig()`, `isValidatedAnalystConfig()` - -**afi-config/schemas/** (Phase 1 - Complete): -- `analyst-config.schema.json` - Full schema with validation rules -- `definitions/enrichment-node.schema.json` - Enrichment node schema -- Examples provided for reference - -### Dependencies Analysis - -**afi-factory/package.json** - Current State: -```json -{ - "name": "afi-factory", - "version": "1.0.0", - "description": "AFI agent factory and templates", - "type": "module", - "scripts": { - "build": "tsc", - "test": "echo 'No tests yet' && exit 0", - "typecheck": "tsc --noEmit" - }, - "keywords": ["afi", "factory", "agents", "templates"], - "license": "MIT" -} -``` - -**Dependencies Required:** -- **ajv** (^8.12.0) - JSON schema validation (used in afi-config) -- **ajv-formats** (^3.0.1) - Additional format validators for ajv -- **vitest** (^4.0.14) - Testing framework (used in afi-config) -- **@types/node** (^20.11.0) - Node.js type definitions - -**Note:** afi-config already has these dependencies. afi-factory needs to add them. - ---- - -## Implementation Plan - -### Step 1: Check Dependencies -- Review afi-factory/package.json for existing dependencies -- Add ajv or similar JSON schema validator if not present -- Ensure testing framework is configured - -### Step 2: Create Validator Module -- Create `afi-factory/validators/analyst-config-validator.ts` -- Implement `validateAnalystConfig()` using JSON schemas -- Implement `validateEnrichmentNode()` -- Implement `isValidISODate()` -- Add comprehensive error messages - -### Step 3: Update Template Registry -- Extend `afi-factory/template_registry.ts` -- Add new functions while preserving backward compatibility -- Implement file loading with proper error handling -- Add caching support -- Implement circular dependency detection - -### Step 4: Create Example Configurations -- Create `afi-factory/analyst-configs/` directory -- Create example configurations based on afi-config/examples -- Create template files for reference -- Ensure all examples validate successfully - -### Step 5: Add Unit Tests -- Create `afi-factory/__tests__/template-registry.test.ts` -- Test all new functions -- Test error cases -- Test edge cases - -### Step 6: Add Integration Tests -- Create `afi-factory/__tests__/integration/analyst-config-loading.test.ts` -- Test end-to-end workflows -- Test schema validation integration - -### Step 7: Verify and Document -- Run all tests -- Update README if needed -- Ensure backward compatibility - ---- - -## File Structure After Implementation - -``` -afi-factory/ -├── template_registry.ts # Updated with new functions -├── validators/ -│ └── analyst-config-validator.ts # New validation module -├── analyst-configs/ -│ ├── froggy-trend-pullback-v1.json # Example config -│ ├── crypto-analyst-v1.json # Example config -│ └── templates/ -│ ├── analyst-config.template.json -│ └── enrichment-node.template.json -├── __tests__/ -│ ├── template-registry.test.ts # Unit tests -│ └── integration/ -│ └── analyst-config-loading.test.ts # Integration tests -└── schemas/ - └── index.ts # Phase 2 - already complete -``` - ---- - -## Success Criteria - -- [ ] Template registry loads analyst configurations from files -- [ ] Template registry validates configurations against schemas -- [ ] Example configurations validate successfully -- [ ] All unit tests pass -- [ ] All integration tests pass -- [ ] Backward compatibility maintained with existing `loadTemplate()` function -- [ ] Comprehensive error handling implemented -- [ ] JSDoc comments added to all functions - ---- - -## Resuming This Work - -### Quick Start Instructions - -To resume Phase 3 implementation in a new task: - -1. **Read this status document** (`plans/phase3-template-registry-status.md`) -2. **Review the implementation plan** above (Steps 1-7) -3. **Add dependencies** to afi-factory/package.json: - ```bash - cd afi-factory - npm install --save-dev ajv@^8.12.0 ajv-formats@^3.0.1 vitest@^4.0.14 @types/node@^20.11.0 - ``` -4. **Update package.json scripts** to use vitest: - ```json - "scripts": { - "build": "tsc", - "test": "vitest", - "test:run": "vitest run", - "typecheck": "tsc --noEmit" - } - ``` -5. **Create vitest.config.ts** (if not present) -6. **Start with Step 2** of the implementation plan (Create Validator Module) - -### Key Files to Reference: - -- **Schemas:** [`afi-config/schemas/analyst-config.schema.json`](../afi-config/schemas/analyst-config.schema.json) -- **Definitions:** [`afi-config/schemas/definitions/enrichment-node.schema.json`](../afi-config/schemas/definitions/enrichment-node.schema.json) -- **Examples:** [`afi-config/examples/analyst-config.example.json`](../afi-config/examples/analyst-config.example.json) -- **Types:** [`afi-factory/schemas/index.ts`](../afi-factory/schemas/index.ts) -- **Current Registry:** [`afi-factory/template_registry.ts`](../afi-factory/template_registry.ts) - -### Recommended Mode for Implementation: - -Use **Code mode** for implementing the changes, as this involves writing and modifying code files. - ---- - -## Important Notes - -### Dependencies Status -- **afi-factory currently has NO dependencies** - needs ajv, ajv-formats, vitest, @types/node -- **afi-config already has these dependencies** - can reference their implementation -- **Testing framework**: afi-config uses vitest, afi-factory should follow the same pattern - -### Implementation References -- **Schema validation pattern**: See [`afi-config/tests/schema-validation.test.ts`](../afi-config/tests/schema-validation.test.ts) for ajv usage examples -- **TypeScript interfaces**: Already complete in [`afi-factory/schemas/index.ts`](../afi-factory/schemas/index.ts) -- **JSON schemas**: Complete in [`afi-config/schemas/`](../afi-config/schemas/) - -### Known Issues -- The reactor's implementation lives in `afi-reactor/src/dag/` -- afi-factory currently has no test infrastructure - needs to be set up - -### Success Criteria Verification -- [ ] Template registry loads analyst configurations from files -- [ ] Template registry validates configurations against schemas -- [ ] Example configurations validate successfully -- [ ] All unit tests pass -- [ ] All integration tests pass -- [ ] Backward compatibility maintained with existing `loadTemplate()` function -- [ ] Comprehensive error handling implemented -- [ ] JSDoc comments added to all functions - ---- - -## Next Steps - -1. Review afi-factory/package.json to check dependencies -2. Install ajv or similar JSON schema validator if needed -3. Create the validator module -4. Update the template registry -5. Create example configurations -6. Add tests -7. Verify all success criteria are met diff --git a/specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md b/specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md index d15f6c1..e76e48f 100644 --- a/specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md +++ b/specs/AFI_PROVIDER_BYOK_FOUNDATIONS.v0.1.md @@ -1,6 +1,6 @@ # AFI Provider Adapter and BYOK Foundations v0.1 -**Status:** Current specification of the implemented provider-neutral adapter socket and secure bring-your-own-key (BYOK) credential boundary. Governed by `afi-governance/decisions/provider-byok-foundations-v0.1.md` (PBF-GOV). Documents the Wave-1 foundation delivered across `afi-config`, `afi-factory`, and `afi-reactor` on the existing configurable executor and Evidence V2. +**Status:** v0.1 foundation record of the provider-neutral adapter socket and secure bring-your-own-key (BYOK) credential boundary. Governed by `afi-governance/decisions/provider-byok-foundations-v0.1.md` (PBF-GOV). Documents the Wave-1 foundation delivered across `afi-config`, `afi-factory`, and `afi-reactor` on the existing configurable executor and Evidence V2. The activation of this foundation as the sole live enrichment-execution seam for all five categories is recorded by `afi-governance/decisions/five-lane-provider-runtime-v0.1.md` (FLPR-GOV) and reflected in `AFI_Full_Architecture.md`; this record intentionally describes the v0.1 foundation itself. This foundation establishes the provider **socket** and the credential **boundary**. It does not complete all commercial provider integrations, and it deploys nothing.