What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Neo.mjs - Self-Evolving Software Organism

Frontmatter

title	docs(agent): Enforce Retrospective 9492 Guardrails & Self-Evolving Systems
author	tobiu
state	Merged
createdAt	Apr 10, 2026, 6:22 PM
updatedAt	Apr 11, 2026, 6:11 PM
closedAt	Apr 10, 2026, 6:30 PM
mergedAt	Apr 10, 2026, 6:30 PM
branches	`dev` ← `agent/9866-retrospective-guardrails`
url	https://github.com/neomjs/neo/pull/9867

Merged

tobiu commented on Apr 10, 2026, 6:22 PM

Resolves #9866

Scope & Architectural Reality

This Pull Request modifies the core agent operational files (AGENTS.md and AGENTS_STARTUP.md) to enforce findings derived from Epic #9492:

Whitebox E2E Neural Link: Mandating the use of direct agent Neural Link tool introspection over brute-force Playwright test suite execution to verify VDOM structures dynamically.
Self-Evolving Systems (Meta-Level Enhancements): A new mandate forcing the swarm to synthesize workflow and collaboration improvements dynamically when encountering systemic friction.
Guardrails: Establishes the 3-5x Productive Failure Loop and the 25-turn global hard stop to prevent agent hallucination cycles, prioritizing localized artifact tracking over remote Github issue pollution.

PR Requirements Check

Issue #9866 acts as the A2A graph node proxy.
Contextual completeness (Gate 2) is met; these operational files don't require JSDoc/Anchor-Echo syntax.

tobiu commented on Apr 10, 2026, 6:28 PM

Input from Gemini 3.1 Pro (Antigravity):

✦ # PR Review Summary

Status: Approved

Great job implementing the operational fixes from our retrospective. These changes immediately resolve the "Whack-A-Mole" debugging friction we saw and establish a much higher standard for self-evolving agent loops. Let's get this merged so the new Guardrails immediately apply to all upcoming Swarm sessions!

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 100 - Perfectly aligns the swarm protocols with the Neo.mjs "Whitebox E2E" testing paradigm and mandates the targeted use of Neural Link Agent tools.

[CONTENT_COMPLETENESS]: 100 - The PR description strictly follows the Fat Ticket protocol ensuring A2A nodes retain the origin story (Epic #9492 dependencies and Retrospective insights).

[EXECUTION_QUALITY]: 100 - The exact semantic changes are accurate. Replaces the incorrect "black-box" phrase with "Whitebox E2E" to respect the internal testing architectures.

[PRODUCTIVITY]: 100 - Solves the exact issues specified in the retrospective immediately.

[IMPACT]: 90 - Critical framework architecture for future agent resilience, hard-capping runaway turns and enforcing targeted introspection.

[COMPLEXITY]: 20 - Direct markdown modifications to the global agent startup scripts without touching core framework source code.

[EFFORT_PROFILE]: Quick Win - Exceptionally high ROI with very low codebase stability risk.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #9866

Related Graph Nodes: Epic #9492 (originating context)

🧠 Graph Ingestion Notes

[KB_GAP]: N/A

[TOOLING_GAP]: N/A

[RETROSPECTIVE]: The swarm successfully synthesized repeated VDOM-testing failures from Epic #9492 into a permanent procedural guardrail. Neural Link VDOM verification is now formally prioritized over Playwright test sweeps for tactical UI debugging, bringing an end to blind "shotgun debugging" attempts by agents on the UI.

📋 Required Actions

To proceed with merging, please address the following:

All agent constraints look solid.

Maintainer manually Squash Merges to baseline dev (since gh pr merge is reserved for maintainer accounts).

Looks perfect to me! Ready for squash merge.