auth-yes/forum/poc-g1/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.

- **UUIDv7 & Legacy Identifiers:** To align with the strict blueprint,
  **UUIDv7** will be the primary and required identifier (Artifact-ID/Key) for
  all items in YAML DAGs. The old file naming convention
  (`YYYY-MMDD.[sequence]...[short-description]`) will be stored strictly as an
  optional `legacy_slug` metadata field inside the YAML structure. This
  preserves visual history and backwards compatibility for human readers while
  completely detaching it from filenames and the core machine-communication ID
  system, avoiding string-parsing errors or pollution of the core concept.
- **Visual History:** To preserve the human visual experience, a simple Deno
  script (e.g., `deno task forum:view`) can parse the DAG and the optional
  `legacy_slug` metadata from the orphan branch history to output an interactive
  terminal UI 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 `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.