# Agent Forum v4 - Concepts & PoC Coverage Tracker

This document tracks all concepts, data structures, and operational mechanisms
defined in the `agent-forum-v4` blueprint and `DATA_STRUCTURES.md`, along with
their Proof of Concept (PoC) coverage status.

## 1. Storage Layers (Git-Native Storage)

| Concept                                  | Status | PoC File               | Description                                                              |
| :--------------------------------------- | :----: | :--------------------- | :----------------------------------------------------------------------- |
| **1.0 Protocol Buffers (Protobuf)**      |   ✅   | `protobuf_poc.ts`      | High-performance binary serialization for agent state transfer.          |
| **1.1 Git Notes**                        |   ✅   | `git_storage_poc.ts`   | Attaching metadata/JSON to Git commits without altering file content.    |
| **1.2 Orphan Branches (Meta-State)**     |   ✅   | `orphan_branch_poc.ts` | Tracking project state separately from source code in isolated branches. |
| **1.3 Embedded Vector DBs (sqlite-vec)** |   ✅   | `vector_db_poc.ts`     | Associative fuzzy memory retrieval of semantic data.                     |
| **1.4 TurboQuant**                       |   ✅   | `vector_db_poc.ts`     | Compressing vectors to binary hashes. Mocked alongside Vector DB PoC.    |
| **1.5 Multi-Vec Isolation**              |   ✅   | `multi_vec_poc.ts`     | Isolated sqlite-vec files preventing semantic bleed (e.g., docs vs telemetry). |

## 2. Process & Governance Structures

| Concept                                      | Status | PoC File               | Description                                                        |
| :------------------------------------------- | :----: | :--------------------- | :----------------------------------------------------------------- |
| **2.0 Declarative Frontmatter (YAML UUIDs)** |   ✅   | `frontmatter_poc.ts`   | Unique identification of artifacts via UUIDv7 in YAML frontmatter. |
| **2.1 The Project DAG (YAML)**               |   ✅   | `dag_engine_poc.ts`    | Execution order driven by mathematical DAG resolution.             |
| **2.2 Bounded Model Checking (Transitions)** |   ✅   | `state_machine_poc.ts` | Strict state machine rules (transitions.json) for agent roles.     |
| **2.3 The Constitution (AGENTS.md)**         |   ✅   | `constitution_poc.ts`  | Strict adherence to the machine-readable ruleset/stack boundaries. |
| **2.4 Orchestration Matrix**                 |   ✅   | `orchestration_matrix_poc.ts` | Definition and interactions of the 6 core agent roles (Gatekeeper, Historian, etc.). |

## 3. Code Intelligence Structures

| Concept                                          | Status | PoC File                   | Description                                                        |
| :----------------------------------------------- | :----: | :------------------------- | :----------------------------------------------------------------- |
| **3.0 Git Merkle DAG Diffing**                   |   ✅   | `merkle_diff_poc.ts`       | O(1) context updates using native git tree diffing.                |
| **3.1 SCIP Indexes (Semantic Code Protocol)**    |   ✅   | `code_intelligence_poc.ts` | Code symbol mapping (mocked via AST exports extraction).           |
| **3.2 ASTs & Control Flow Graphs (CFGs)**        |   ✅   | `cfg_poc.ts`               | Structured paths for security analysis (e.g., unsanitized inputs). |
| **3.3 Mutation Testing Scores**                  |   ✅   | `mutation_poc.ts`          | Blast radius / coverage enforcement by injecting bugs (Adversary). |
| **3.4 Dependency Graphing (Adjacency Matrices)** |   ✅   | `dependency_graph_poc.ts`  | Blast radius mapping via dependency matrices.                      |
| **3.5 Static Analysis Payloads**                 |   ✅   | `static_analysis_poc.ts`   | Ingestion of JSON outputs from tools like Semgrep/SonarQube.       |

## 4. Semantic & Telemetry Structures

| Concept                                    | Status | PoC File           | Description                                                           |
| :----------------------------------------- | :----: | :----------------- | :-------------------------------------------------------------------- |
| **4.1 Ontologies (JSON-LD)**               |   ✅   | `ontology_poc.ts`  | Deep traceability linking code/tasks to business requirements.        |
| **4.2 OpenTelemetry Traces (.trace.json)** |   ✅   | `telemetry_poc.ts` | Millisecond-level execution latency capture for bottleneck detection. |
| **4.3 Team Friction Telemetry**            |   ✅   | `telemetry_poc.ts` | Human-to-agent collaboration metrics (MTTR, Comment Ratios).          |

## 5. Architectural Graveyard (Dismissed Concepts)

These concepts were explored but ultimately dismissed to respect strict repo-native constraints. See `GRAVEYARD.md` for details and rationales.

| Concept                                    | Status | Anti-PoC File      | Description                                                           |
| :----------------------------------------- | :----: | :----------------- | :-------------------------------------------------------------------- |
| **5.1 Doc-to-LoRA Hypernetworks**          |   ❌   | `graveyard_poc.ts` | Dismissed due to extreme Git repository bloat from adapter weights.   |
| **5.2 PASTE (Speculative Execution)**      |   ❌   | `graveyard_poc.ts` | Dismissed due to high risk of Bounded Model Checking violations.      |