feat(forum): add Generation 2 agent forum PoCs with production tools (#67)

- Renamed `forum/experiments` to `forum/poc-g1` to designate generation 1.
- Created `forum/poc-g2` and a new `lab.ts` runner.
- Non-destructively migrated `dag_engine_poc.ts`, `git_storage_poc.ts`, `merkle_diff_poc.ts`, and `frontmatter_poc.ts` to `poc-g2`.
- Upgraded migrated PoCs to utilize actual production-ready tools (e.g. `std/yaml` parsing and isolated `Deno.Command` Git repos) per blueprint constraints.

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: mrteye <1945243+mrteye@users.noreply.github.com>

forum/poc-g2/dag_engine_poc.ts

@@ -0,0 +1,120 @@
+import { assertEquals } from "https://deno.land/std@0.224.0/testing/asserts.ts";
+import { parse } from "https://deno.land/std@0.224.0/yaml/mod.ts";
+import { join } from "https://deno.land/std@0.224.0/path/mod.ts";
+
+/**
+ * Generation 2 Proof of Concept: Semantic Task DAG Engine
+ *
+ * This module demonstrates parsing strict YAML Directed Acyclic Graphs (DAG)
+ * from ACTUAL YAML files on disk to calculate the critical path,
+ * proving we can use real production tooling for task orchestration.
+ */
+
+export interface TaskNode {
+  id: string;
+  title: string;
+  blocked_by: string[];
+  status: "pending" | "in-progress" | "complete";
+}
+
+export class TaskDAG {
+  private nodes: Map<string, TaskNode> = new Map();
+
+  constructor(yamlContent: string) {
+    const rawNodes = parse(yamlContent) as TaskNode[];
+    for (const node of rawNodes) {
+      this.nodes.set(node.id, {
+        ...node,
+        blocked_by: node.blocked_by || [],
+        status: node.status || "pending",
+      });
+    }
+  }
+
+  /**
+   * Returns a list of tasks that are fully unblocked and ready to be worked on.
+   */
+  getUnblockedTasks(): TaskNode[] {
+    const unblocked: TaskNode[] = [];
+    for (const node of this.nodes.values()) {
+      if (node.status === "complete") continue;
+
+      const isBlocked = node.blocked_by.some(
+        (depId) => this.nodes.get(depId)?.status !== "complete",
+      );
+
+      if (!isBlocked) {
+        unblocked.push(node);
+      }
+    }
+    return unblocked;
+  }
+
+  markComplete(taskId: string) {
+    const node = this.nodes.get(taskId);
+    if (node) {
+      node.status = "complete";
+    }
+  }
+}
+
+if (import.meta.main) {
+  console.log("Running Gen 2 DAG Engine PoC tests...");
+
+  // We write the YAML out to a temporary real file, then read it.
+  const tempYamlPath = await Deno.makeTempFile({ suffix: ".yaml" });
+
+  const yamlInput = `
+- id: task_1
+  title: Setup Git Notes PoC
+  status: complete
+- id: task_2
+  title: Setup DAG Engine PoC
+  blocked_by: [task_1]
+  status: pending
+- id: task_3
+  title: Setup Local Intelligence PoC
+  blocked_by: [task_1, task_2]
+  status: pending
+- id: task_4
+  title: Write Assessment Report
+  blocked_by: [task_1]
+  status: pending
+`;
+
+  try {
+    // Prove we can write and read a real file
+    await Deno.writeTextFile(tempYamlPath, yamlInput);
+    console.log(`Wrote YAML file to ${tempYamlPath}`);
+
+    const fileContent = await Deno.readTextFile(tempYamlPath);
+    console.log("Read YAML from disk.");
+
+    const dag = new TaskDAG(fileContent);
+
+    // Initially, task_2 and task_4 should be unblocked because task_1 is complete.
+    let unblocked = dag.getUnblockedTasks();
+    assertEquals(unblocked.length, 2);
+    assertEquals(unblocked[0].id, "task_2");
+    assertEquals(unblocked[1].id, "task_4");
+
+    // Mark task_2 as complete. Now task_3 should still be blocked because task_4 has no effect,
+    // wait, task_3 is blocked by task_1 and task_2. Since both will be complete, task_3 should unlock.
+    dag.markComplete("task_2");
+    unblocked = dag.getUnblockedTasks();
+
+    // Unblocked should now be task_3 and task_4
+    assertEquals(unblocked.length, 2);
+    assertEquals(unblocked.find((t) => t.id === "task_3")?.id, "task_3");
+    assertEquals(unblocked.find((t) => t.id === "task_4")?.id, "task_4");
+
+    console.log(
+      "✅ Gen 2 DAG Engine PoC successful: Correctly processed YAML from real files.",
+    );
+  } catch (err) {
+    console.error("❌ DAG Engine PoC failed:", err);
+    Deno.exit(1);
+  } finally {
+    await Deno.remove(tempYamlPath);
+  }
+}

forum/poc-g2/frontmatter_poc.ts

@@ -0,0 +1,88 @@
+import { assertEquals } from "https://deno.land/std@0.224.0/testing/asserts.ts";
+import { parse as yamlParse } from "https://deno.land/std@0.224.0/yaml/mod.ts";
+
+/**
+ * Generation 2 Proof of Concept: Declarative Frontmatter (YAML UUIDs)
+ *
+ * This module demonstrates extracting strict UUIDv7 identifiers from
+ * Markdown YAML frontmatter using production-ready YAML parsing,
+ * ensuring precise artifact identification.
+ */
+
+// A helper to test if a string matches UUIDv7 structure
+// (8-4-4-4-12, where the 13th hex char is '7')
+function isUUIDv7(uuid: string): boolean {
+  const uuidV7Regex =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidV7Regex.test(uuid);
+}
+
+export function extractArtifactId(markdownContent: string): string {
+  // Extract YAML block strictly
+  const match = markdownContent.match(/^---\n([\s\S]*?)\n---/);
+  if (!match || !match[1]) {
+     throw new Error("No YAML frontmatter found");
+  }
+
+  // Parse YAML block with std/yaml
+  const metadata = yamlParse(match[1]) as Record<string, unknown>;
+
+  const id = metadata["Artifact-ID"];
+  if (!id || typeof id !== "string") {
+    throw new Error("Missing or invalid Artifact-ID in frontmatter");
+  }
+
+  if (!isUUIDv7(id)) {
+    throw new Error(`Artifact-ID ${id} is not a valid UUIDv7`);
+  }
+
+  return id;
+}
+
+if (import.meta.main) {
+  console.log("Running Gen 2 Declarative Frontmatter PoC tests...");
+
+  // Mock UUIDv7: 018fa031-6e3e-7a2e-8c4d-91b5a6c7d8e9
+  const validMarkdown = `---
+Artifact-ID: 018fa031-6e3e-7a2e-8c4d-91b5a6c7d8e9
+Title: Authentication Architecture
+Status: Draft
+---
+
+# Authentication Architecture
+This document details the auth system...
+`;
+
+  const invalidMarkdown = `---
+Artifact-ID: task-123
+Title: Legacy Task
+---
+
+# Legacy System
+`;
+
+  try {
+    const id = extractArtifactId(validMarkdown);
+    assertEquals(id, "018fa031-6e3e-7a2e-8c4d-91b5a6c7d8e9");
+    console.log(
+      "✅ Gen 2 Frontmatter PoC successful: Correctly extracted UUIDv7 using std/yaml.",
+    );
+
+    // Test rejection of non-UUIDv7
+    let failedAsExpected = false;
+    try {
+      extractArtifactId(invalidMarkdown);
+    } catch (e: any) {
+      if (e.message.includes("not a valid UUIDv7")) {
+        failedAsExpected = true;
+      }
+    }
+    assertEquals(failedAsExpected, true, "Should have rejected invalid UUID");
+
+    console.log("✅ Gen 2 Frontmatter PoC successful: Successfully rejected non-UUIDv7 artifact.");
+
+  } catch (err) {
+    console.error("❌ Gen 2 Frontmatter PoC failed:", err);
+    Deno.exit(1);
+  }
+}

forum/poc-g2/git_storage_poc.ts

@@ -0,0 +1,103 @@
+import { assertEquals } from "https://deno.land/std@0.224.0/testing/asserts.ts";
+
+/**
+ * Generation 2 Proof of Concept: Git Storage (Notes)
+ *
+ * This module demonstrates interacting with Git Notes in a completely
+ * isolated, real Git environment using Deno.Command. It sets up a local
+ * Git repository on the fly to avoid polluting the main project repo,
+ * thereby proving production-readiness of the local-first storage mechanism.
+ */
+
+async function runGitCmd(args: string[], cwd?: string): Promise<string> {
+  const cmd = new Deno.Command("git", {
+    args,
+    cwd,
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const output = await cmd.output();
+  const stdout = new TextDecoder().decode(output.stdout).trim();
+  const stderr = new TextDecoder().decode(output.stderr).trim();
+
+  if (!output.success) {
+    throw new Error(`Git command failed: git ${args.join(" ")}\n${stderr}`);
+  }
+  return stdout;
+}
+
+export async function addGitNote(
+  cwd: string,
+  ref: string,
+  message: string,
+  targetRef: string = "HEAD",
+) {
+  await runGitCmd([
+    "notes",
+    "--ref",
+    ref,
+    "add",
+    "-f",
+    "-m",
+    message,
+    targetRef,
+  ], cwd);
+}
+
+export async function readGitNote(
+  cwd: string,
+  ref: string,
+  targetRef: string = "HEAD",
+): Promise<string> {
+  try {
+    return await runGitCmd(["notes", "--ref", ref, "show", targetRef], cwd);
+  } catch (error: any) {
+    if (error.message.includes("No note found") || error.message.includes("does not exist")) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+if (import.meta.main) {
+  console.log("Running Gen 2 Git Storage PoC tests...");
+
+  // Setup an isolated Git repository
+  const tempDir = await Deno.makeTempDir({ prefix: "agent-forum-git-poc-" });
+  console.log(`Created isolated Git repo at ${tempDir}`);
+
+  try {
+    await runGitCmd(["init"], tempDir);
+    await runGitCmd(["config", "user.email", "poc@example.com"], tempDir);
+    await runGitCmd(["config", "user.name", "PoC Tester"], tempDir);
+
+    // Create an initial commit so we have a HEAD
+    const dummyFile = `${tempDir}/README.md`;
+    await Deno.writeTextFile(dummyFile, "# Dummy");
+    await runGitCmd(["add", "README.md"], tempDir);
+    await runGitCmd(["commit", "-m", "Initial commit"], tempDir);
+
+    const customRef = "forum/test-reasoning";
+    const testMessage = JSON.stringify({
+      agent: "poc-g2-agent",
+      risk: "low",
+      thought: "This is a hidden thought stored in an isolated git note.",
+    });
+
+    console.log(`Adding note to current HEAD under ref ${customRef}...`);
+    await addGitNote(tempDir, customRef, testMessage);
+
+    console.log(`Reading note back...`);
+    const readMessage = await readGitNote(tempDir, customRef);
+
+    assertEquals(readMessage, testMessage);
+    console.log("✅ Gen 2 Git Storage PoC successful: Read/Write worked securely in an isolated Git environment.");
+
+  } catch (err) {
+    console.error("❌ Gen 2 Git Storage PoC failed:", err);
+    Deno.exit(1);
+  } finally {
+    console.log(`Cleaning up isolated Git repo...`);
+    await Deno.remove(tempDir, { recursive: true });
+  }
+}

forum/poc-g2/lab.ts

@@ -0,0 +1,105 @@
+import {
+  dirname,
+  fromFileUrl,
+  join,
+} from "https://deno.land/std@0.224.0/path/mod.ts";
+import {
+  blue,
+  bold,
+  green,
+  red,
+  yellow,
+} from "https://deno.land/std@0.224.0/fmt/colors.ts";
+
+// Define the experiments to run
+const EXPERIMENTS = [
+  {
+    name: "DAG Engine PoC (Gen 2)",
+    file: "dag_engine_poc.ts",
+    description: "Verifies dependency resolution parsing real YAML task graphs.",
+  },
+  {
+    name: "Git Storage PoC (Gen 2)",
+    file: "git_storage_poc.ts",
+    description: "Verifies ability to read/write Git Notes in an isolated environment.",
+  },
+  {
+    name: "Git Merkle DAG Diffing PoC (Gen 2)",
+    file: "merkle_diff_poc.ts",
+    description: "Verifies O(1) diffing using native Git tree hashes on an isolated history.",
+  },
+  {
+    name: "Declarative Frontmatter PoC (Gen 2)",
+    file: "frontmatter_poc.ts",
+    description: "Verifies extraction of UUIDv7 from Markdown using real YAML parsing.",
+  },
+];
+
+async function runExperiment(
+  file: string,
+): Promise<{ success: boolean; output: string }> {
+  const currentDir = dirname(fromFileUrl(import.meta.url));
+  const filePath = join(currentDir, file);
+
+  try {
+    const command = new Deno.Command("deno", {
+      args: ["run", "-A", filePath],
+      stdout: "piped",
+      stderr: "piped",
+    });
+
+    const { code, stdout, stderr } = await command.output();
+    const decoder = new TextDecoder();
+
+    const outputString = decoder.decode(stdout) + decoder.decode(stderr);
+
+    return {
+      success: code === 0,
+      output: outputString.trim(),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      output: `Failed to execute ${file}: ${error}`,
+    };
+  }
+}
+
+async function runLab() {
+  console.log(bold(blue("=== Agent Forum v4 - Experimental Laboratory (Generation 2) ===")));
+  console.log("Running advanced foundational proofs of concept with real production tools...\n");
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const exp of EXPERIMENTS) {
+    console.log(bold(`[Running] ${exp.name}`));
+    console.log(`> ${exp.description}`);
+
+    const { success, output } = await runExperiment(exp.file);
+
+    if (success) {
+      console.log(green("✅ PASS\n"));
+      console.log(output);
+      passed++;
+    } else {
+      console.log(red("❌ FAIL\n"));
+      console.log(output);
+      failed++;
+    }
+    console.log(yellow("--------------------------------------------------\n"));
+  }
+
+  console.log(bold(blue("=== Laboratory Results ===")));
+  console.log(`Total Experiments: ${EXPERIMENTS.length}`);
+  console.log(green(`Passed: ${passed}`));
+  console.log(red(`Failed: ${failed}`));
+
+  if (failed > 0) {
+    Deno.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  runLab().catch(console.error);
+}

forum/poc-g2/merkle_diff_poc.ts

@@ -0,0 +1,93 @@
+import { assertNotEquals, assertEquals } from "https://deno.land/std@0.224.0/testing/asserts.ts";
+
+/**
+ * Generation 2 Proof of Concept: Git Merkle DAG Diffing
+ *
+ * This module demonstrates using Git's Merkle Tree structure to perform
+ * O(1) diffing (`git diff-tree` and `git ls-tree`). To prove production readiness
+ * and avoid failures from shallow clones or dirty states, we instantiate
+ * a clean, isolated Git repository with a deterministic commit history.
+ */
+
+async function runGitCmd(args: string[], cwd?: string): Promise<string> {
+  const cmd = new Deno.Command("git", {
+    args,
+    cwd,
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const output = await cmd.output();
+  const stdout = new TextDecoder().decode(output.stdout).trim();
+  const stderr = new TextDecoder().decode(output.stderr).trim();
+
+  if (!output.success) {
+    throw new Error(`Git command failed: git ${args.join(" ")}\n${stderr}`);
+  }
+  return stdout;
+}
+
+if (import.meta.main) {
+  console.log("Running Gen 2 Git Merkle DAG Diffing PoC tests...");
+
+  const tempDir = await Deno.makeTempDir({ prefix: "agent-forum-merkle-poc-" });
+  console.log(`Created isolated Git repo at ${tempDir}`);
+
+  try {
+    // 0. Setup an isolated Git repo with two commits
+    await runGitCmd(["init"], tempDir);
+    await runGitCmd(["config", "user.email", "poc@example.com"], tempDir);
+    await runGitCmd(["config", "user.name", "PoC Tester"], tempDir);
+
+    const fileA = `${tempDir}/fileA.txt`;
+    const fileB = `${tempDir}/fileB.txt`;
+
+    // Commit 1
+    await Deno.writeTextFile(fileA, "Hello World A");
+    await Deno.writeTextFile(fileB, "Hello World B");
+    await runGitCmd(["add", "."], tempDir);
+    await runGitCmd(["commit", "-m", "Commit 1"], tempDir);
+
+    // Commit 2: Modify fileA only
+    await Deno.writeTextFile(fileA, "Hello World A - Modified");
+    await runGitCmd(["add", "."], tempDir);
+    await runGitCmd(["commit", "-m", "Commit 2"], tempDir);
+
+    // 1. Get the current HEAD commit hash
+    const headHash = await runGitCmd(["rev-parse", "HEAD"], tempDir);
+    console.log(`Current HEAD: ${headHash}`);
+
+    // 2. Get the tree hash of HEAD
+    const treeHash = await runGitCmd(["rev-parse", "HEAD^{tree}"], tempDir);
+    console.log(`Tree Hash of HEAD: ${treeHash}`);
+
+    // 3. Diff HEAD against HEAD~1
+    const diffTreeOutput = await runGitCmd([
+      "diff-tree",
+      "--no-commit-id",
+      "--name-only",
+      "-r",
+      "HEAD~1",
+      "HEAD",
+    ], tempDir);
+
+    console.log(`\nChanged files between HEAD~1 and HEAD (O(1) diffing):\n${diffTreeOutput}`);
+
+    // Assert that only fileA.txt changed
+    assertEquals(diffTreeOutput, "fileA.txt");
+    assertNotEquals(treeHash, "");
+
+    // 4. Also use ls-tree to read the structure
+    const lsTreeOutput = await runGitCmd(["ls-tree", "HEAD"], tempDir);
+    console.log(`\nls-tree of HEAD:\n${lsTreeOutput}`);
+
+    console.log(
+      "\n✅ Gen 2 Git Merkle DAG Diffing PoC successful: Deterministic isolated diffing achieved.",
+    );
+  } catch (err) {
+    console.error("❌ Gen 2 Git Merkle DAG Diffing PoC failed:", err);
+    Deno.exit(1);
+  } finally {
+    console.log(`Cleaning up isolated Git repo...`);
+    await Deno.remove(tempDir, { recursive: true });
+  }
+}