auth-yes/scratch/agent-forum-experiments/ASSESSMENT.md

Agent Forum v4 Assessment & Research Report

1. Overview & Usefulness

The agent-forum-v4 blueprint outlines a "Git-Native Agent Collaboration Ecosystem." By shifting from flat Markdown files to structured data (YAML DAGs, SCIP indexes, local vector graphs), the protocol addresses a core limitation of modern AI agents: context window collapse and dependency amnesia.

Solving the Pain Points: You noted that agents frequently lose context and struggle to understand if they are fulfilling requirements without constant spoon-feeding. The proposed shift to a Semantic Project Management system directly solves this:

• Dependencies: Instead of relying on an agent to read a folder and "figure out" what to do, the system uses strict YAML Directed Acyclic Graphs (DAGs). An Evaluator script mathematically determines the critical path. An agent is only ever handed an explicitly unblocked task.
• Context: Instead of feeding the agent the entire codebase as raw text, the system uses Git Merkle DAG diffing and embedded SQLite vector search to feed the agent precisely the context it needs in milliseconds.

2. Compatibility with the Repository

The Auth-Yes repository is characterized by a strict, zero-dependency, hermetic environment prioritizing Deno, minimal external SaaS dependencies, and self-contained runtime operations.

• High Alignment: The agent-forum's philosophy of "Local-First / Git-Native" is in perfect harmony with your project's ethos. Eliminating third-party databases in favor of Git Notes and orphan branches ensures the protocol remains portable, cryptographically secure, and isolated.
• Implementation Challenges: The blueprint relies heavily on advanced tooling (Tree-sitter, SCIP, sqlite-vec). Integrating these into a Deno environment without polluting the repository with heavy binary dependencies will require careful execution. We should lean towards WebAssembly (WASM) ports of these tools (e.g., tree-sitter.wasm, or Deno's native FFI for SQLite) to keep the repository lightweight.

3. Isolation Strategy (Preventing Bleed)

To ensure this new protocol does not interfere with the primary intent of Auth-Yes or other target projects, we must implement strict physical and logical boundaries:

1. The .forum/ (or .agents/) Namespace: All protocol-specific files, state machines (transitions.json), schemas, and tooling scripts must be entirely contained within a hidden root directory (e.g., .forum/). The target repository should have zero awareness of these files.
2. Git Meta-State (Orphan Branches): The most powerful isolation technique proposed is the use of an Orphan Branch. Dynamic state (telemetry, task completion status, graphs) will be committed to a branch (e.g., forum/meta-state) that shares no history with main. This ensures the primary branch's git log remains pristine and untouched by agent automation.
3. Git Notes for Meta-Thoughts: By using custom Git Note refs (e.g., refs/notes/forum/reasoning), agents can attach vast amounts of JSON metadata, risk assessments, and historical context to a commit without altering the commit hash or the working directory tree.

4. Adapting the Legacy /tasks Workflow

You mentioned appreciating the file naming conventions (visual history), risk assessments, and meta-thoughts of the old system. The goal is to preserve the value of these features while upgrading their format to be machine-readable.

• Visual History & Filenames: We can retain the descriptive nomenclature (YYYY-MMDD.[sequence]...[short-description]) but use it as the UUID/Key inside the YAML DAGs rather than just a filename. To preserve the human visual experience, we can write a simple Deno script (deno task forum:view) that parses the DAG and orphan branch history to output a beautiful, interactive terminal UI (via Cliffy) or a generated HTML report showing the exact progression of work.
• Risk Assessment & Meta-Thoughts: In the old system, these were markdown headers. In the new system, an "Adversary" agent will generate these risk assessments as structured JSON. We will store this JSON in Git Notes attached to the relevant commits. This ensures the data is tightly coupled to the code changes, never gets lost in a stale markdown file, and can be queried instantly by other agents.
• Human-Readable Projections: If we ever need a standard Markdown view, a "Translator" agent or script can compile the DAGs, Git Notes, and ASTs and generate a static tasks-report.md on demand.

5. Proposed Experimental Path (Proof of Concept)

We will not build the fully automated loop yet. Instead, we will build foundational experiments in scratch/agent-forum-experiments/ to verify the hard concepts:

1. Git Storage PoC (git_storage_poc.ts): Verify that Deno can programmatically read/write to Git Notes and manipulate an orphan branch without disrupting the current working tree. This proves we can store agent state invisibly.
2. DAG Engine PoC (dag_engine_poc.ts): Create a minimal script that parses a YAML task graph, resolves dependencies (blocked_by), and mathematically outputs the exact next task an agent should work on.
3. Local Intelligence PoC (code_intelligence_poc.ts): Experiment with lightweight semantic parsing (e.g., extracting exports or AST structure from a file) to prove we can feed agents structured code intelligence rather than raw strings.