auth-yes/.forum/CONCEPTS.md

Agent Forum v4 - Consolidated Master Tracker

This document serves as the single source of truth for all concepts, data structures, and operational mechanisms defined in the agent-forum.md architectural blueprint. It consolidates the high-level architecture with the granular implementation constraints previously split across satellite documentation.

The table below tracks the definition, required implementation details, and Proof of Concept (PoC) coverage status for every implementable aspect of the Git-native ecosystem.

Concept / Structure	Category	Blueprint Ref	Key Implementation Details	PoC File	Gen	Status
Protocol Buffers (Protobuf)	Data Structure	Section 1	Serialized binary state and telemetry designed for conversion-less, high-performance data transfer.	protobuf_poc.ts	G1, G2	✅
Git Notes	Embedded Storage	Section 1	Requires git log --show-notes="forum/reasoning" to fetch JSON payloads containing reasoning, risk, and telemetry.	git_storage_poc.ts	G1, G2	✅
Orphan Branches	Embedded Storage	Section 1	Isolated forum/meta-state branch tracking CI/CD, RTMs, and DAGs without sharing main branch commit history.	orphan_branch_poc.ts	G1, G2	✅
sqlite-vec & TurboQuant	Embedded DB	Section 1	2-bit to 4-bit LSH/HNSW compression resulting in highly portable indexes typically under 30MB.	vector_db_poc.ts	G1, G2	✅
Multi-Vec Isolation	Embedded DB	Section 1	Domain-specific SQLite files (e.g., docs_graph.sqlite distinct from telemetry_graph.sqlite) to prevent semantic bleed.	multi_vec_poc.ts	G1, G2	✅
Declarative Frontmatter	Data Structure	Section 1 & 4	MUST utilize UUIDv7 (time-ordered) to allow historical sorting and chronological sequence inference directly from the ID.	frontmatter_poc.ts	G1, G2	✅
The Project DAG	Governance Structure	Section 4	YAML schema explicitly requiring id, blocked_by, legacy_slug, status, and description fields.	dag_engine_poc.ts	G1, G2	✅
Transitions Matrix	Governance Structure	Section 1 & 2	JSON mapping in transitions.json strictly defining Bounded Model Checking rules (e.g., "Coder": { "requires": ["Gatekeeper_Approval"] }).	state_machine_poc.ts	G1, G2	✅
The Constitution (AGENTS.md)	Governance Structure	Section 3	Target application stack dynamically bound to the repository to statically prevent hallucinated dependencies.	constitution_poc.ts	G1, G2	✅
Orchestration Matrix	Governance Structure	Section 3	Strict definition of inputs, outputs, and primary directives for the 6 core agents.	orchestration_matrix_poc.ts	G1, G2	✅
Execution Flywheel	Process	Section 5	Continuous 3-step feedback loop: Analyst updates protocols, Gatekeeper reads constraints, cycle resets.	execution_flywheel_poc.ts	G1, G2	✅
Git Merkle DAG Diffing	Data Structure	Section 2	Relies on git ls-tree and git diff-tree hashes for zero-overhead, O(1) context updates.	merkle_diff_poc.ts	G1, G2	✅
SCIP Indexes	Data Structure	Section 2	Lightweight database mapping code definitions and references, typically extracted via Tree-sitter.	code_intelligence_poc.ts	G1, G2	✅
ASTs & CFGs	Data Structure	Section 2	JSON/XML mapping of variable execution paths utilized for deterministic security proofs.	cfg_poc.ts	G1, G2	✅
Mutation & Adjacency	Data Structure	Section 2 & 3	Blast radius and coverage enforcement mappings generated by tools like Stryker and CodeSee.	mutation_poc.ts	G1, G2	✅
Static Analysis Payloads	Data Structure	Section 2	Standardized JSON/XML metric outputs from industry tools like Semgrep and SonarQube.	static_analysis_poc.ts	G1, G2	✅
Tool Sandbox	Process	Appendix A	Safe local execution environment for CLI/WebAssembly binaries (Tree-sitter, Semgrep) respecting Bounded Model Checking constraints.	tool_sandbox_poc.ts	G1, G2	✅
Automated Git Hooks	Process	Section 2	Native pre-commit hooks configured to automatically generate SCIP and AST index graphs prior to agent interaction.	git_hooks_poc.ts	G1, G2	✅
Ontologies (JSON-LD)	Data Structure	Section 4	Embedded @type: "Requirement" blocks compiled to a mathematical ontology.graph file for deep traceability.	ontology_poc.ts	G1, G2	✅
OTel Traces	Data Structure	Section 4	Standardized .trace.json payloads capturing millisecond-level execution latencies during testing.	telemetry_poc.ts	G1, G2	✅
Team Friction Telemetry	Data Structure	Section 4	JSON payloads recorded in the meta-state branch tracking MTTR, PR comment-to-code ratios, and idle handoff durations.	telemetry_poc.ts	G1, G2	✅
Zero-Token Pre-Filter	Process	Sec 2 & App A	Takes raw outputs from Semgrep, Stryker, and Madge, filtering them into strict JSON payloads.	pre_filter_adapters_poc.ts	G3	✅
Harness Consolidation	Process	Section 1	Moving the framework files strictly out of the root path into a hidden/structured directory so compilers and indexers ignore them.	harness_consolidation_poc.ts	G3	✅
E2E Orchestration Runner	Governance Structure	Section 5	Wiring the Git Notes ledger, Scoped Merkle diff extractor, and state-machine evaluator into a cohesive CLI workflow.	orchestration_runner_poc.ts	G3	✅
Doc-to-LoRA	Dismissed Concept	Section 6	Rejected because generating megabytes of .safetensors adapter weights directly causes extreme Git repository bloat.	graveyard_poc.ts	G1, G2	❌
PASTE (Speculative Tooling)	Dismissed Concept	Section 6	Rejected because speculative write operations cause irrecoverable race conditions and corrupt the meta-state branch.	graveyard_poc.ts	G1, G2	❌