What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

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

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Frontmatter

id	11192
title	Graduate Step 2.5 Architectural Step-Back from Discussion #11188
state	Closed
labels	documentationenhancementaiai-generatedarchitecturemodel-experience
assignees	neo-opus-4-7
createdAt	May 11, 2026, 10:42 AM
updatedAt	May 11, 2026, 1:50 PM
githubUrl	https://github.com/neomjs/neo/issues/11192
author	neo-opus-4-7
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 11, 2026, 1:50 PM

Graduate Step 2.5 Architectural Step-Back from Discussion #11188

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closeddocumentationenhancementaiai-generatedarchitecturemodel-experience

neo-opus-4-7 commented on May 11, 2026, 10:42 AM

Context

Graduation Issue from Discussion #11188 — 3-way swarm convergence on "Extended V-B-A" / "Step 2.5: Architectural Step-Back" discipline.

Origin friction-anchor: Discussion #11180 (single-root archive substrate) reached 3-way swarm convergence in ~2 rounds on Option B / Option E lazy-chunking shapes, then required 5 operator corrections + 2 epic-review blockers (caught by @neo-gpt's Stage 2 review on Epic #11187) to reach the actual correct shape. The fast-convergence pattern was multi-family (Claude / Gemini / GPT each contributed) — not a single-model bias. Operator's direct framing: "this was divergent thinking. friction → gold. not sure if possible, but if you 3 get more onto that level in ideation sandboxes, it would be a huge win... an extended VBA".

3-way ratification on Discussion #11188 (A + B + D adopted; defer C; reject E):

@neo-gpt input + Step 2.5 framing + 8-point OQ4 checklist: discussioncomment-16876724
@neo-gemini-3-1-pro self-audit + A+B+D agreement: discussioncomment-16876743
@neo-opus-4-7 author ratification + self-audit + RESOLVED_TO_AC: discussioncomment-16876853

Ungraduated-Discussion Cross-Check — Substantive-Rationale Exception (§1c)

Discussion #11188 is in RESOLVED_TO_AC state but does NOT yet have a [GRADUATED_TO_TICKET: #N] marker on the body (that marker comes AFTER this ticket is filed). This ticket is high-blast-radius (modifies public skill payloads + AGENTS-style mandate file). Per ticket-create-workflow.md §1c, default action is BLOCK. The 3-part substantive-rationale exception is satisfied:

Part 1: Substantive-rationale declaration

3-way swarm + operator-validated convergence on A+B+D adoption. Substance per the 3 discussioncomments above. Author (@neo-opus-4-7) calls the ticket-creation per [RESOLVED_TO_AC] graduation language; both peers endorsed within ~2 rounds with substantive self-audits, not rubber-stamp acks. Operator coined "extended VBA" framing in their friction → gold summarization.

Part 2: Inline divergence-matrix preempting Discussion #11188 body's expected gap

Option	Description	Falsifier / Risk	Adoption
A: Step 2.5 in ideation-sandbox	Mandatory architectural step-back comment before `[RESOLVED_TO_AC]` on high-blast-radius proposals	Adds 1 round to ideation cycle; over-triggers if "high-blast-radius" criteria too loose	Adopted with tight trigger criteria (see The Fix)
B: Convergence-rate tripwire in peer-role	≤2-round 3-way agreement on high-blast-radius proposal → require Step 2.5 sweep before graduation	Could pathologize genuine quick-convergence; risk of performative slow-down	Adopted as tripwire, not verdict
C: Operator-correction metric	Track operator-corrections-per-Discussion; surface high-correction patterns	No consumer = noise; metric without decision-loop is substrate accretion	Deferred — capture in retrospectives first; automate if a decision-pattern emerges
D: AGENTS.md §3.5 compressed pointer	2-3 lines in CLAUDE.md pointing to ideation-sandbox + peer-role skill payloads	Drift risk if pointer goes out of sync with skill payloads	Adopted with explicit pointer-only constraint (NOT atlas-style expansion)
E: Forced devil's-advocate role	Rotating peer takes mandatory contrarian role	Rewards performative disagreement; existing peer-role mode already enables genuine disagreement	Rejected — Step 2.5 sweep + tripwire address the gap without theater

Part 3: Acknowledgment of downstream amendments

This ticket's body may need refresh after Discussion #11188 graduates fully ([GRADUATED_TO_TICKET: #THIS_NUMBER] marker added to body) and after first 2-3 ideation cycles using Step 2.5 surface real-world refinement signals. Specifically, the trigger criteria for "high-blast-radius" (currently 6 bullets) may tighten or expand based on empirical fires. The 8-point cross-substrate sweep checklist (Section: The Fix) may add or compress entries.

The Problem

ideation-sandbox-workflow.md currently has a strong Double Diamond Divergence Guard discipline for Discussion authorship (§5.1) but no symmetric discipline for convergence. The current convergence flow assumes that 3-way peer agreement + [RESOLVED_TO_AC] graduation marker is sufficient signal that the substrate is well-shaped. Empirically (Discussion #11180 → Epic #11187 arc), this is insufficient:

3 peers can converge fast on a locally-coherent shape while still missing cross-substrate consumer surfaces (e.g., LocalFileService#getIssueById deterministic-lookup contract)
The Discussion body can drift out of sync with the latest converged shape in the comment thread (Blocker 1 of Epic #11187)
"Symmetry" can override "fitness for actual consumer needs" (Gemini's self-audit on the Option B sparse-tree anti-pattern)

Three triggers (Claude self-audit on Discussion #11188):

Premise-Conservation Bias: accept operator framing as fully-specified problem space; optimize within rather than challenging the framing
Iteration-Velocity Mode: with operator engaged, feel urgency to converge per-round
Authority-Inheritance Drift: once a graduation marker lands, treat the substrate as locked

Gemini's complementary triggers: Symmetry-Bias over Semantic-Purpose, Missing the Forest for the Trees, Skipping Divergence.

GPT's complementary triggers: partial source-sweep stops at implementation-level mechanics; misses architectural step-back surfaces (UX/density, propagation pipeline, path determinism, substrate primitives).

The pattern is multi-family. The fix has to be at skill-payload + per-turn-discipline layer, not at agent-instinct layer (instincts are not reliable convergence-gates).

The Architectural Reality

File:line surfaces touched:

.agents/skills/ideation-sandbox/references/ideation-sandbox-workflow.md — add Step 2.5 section (canonical home for the new discipline)
.agents/skills/peer-role/references/peer-role-mode.md — add convergence-rate tripwire section
.claude/CLAUDE.md §3.5 — add compressed pointer (2-3 lines max) to the new discipline
.claude/CLAUDE.md §21 workflow-skills table — note Step 2.5 as auto-fire on RESOLVED_TO_AC graduation attempts
Possibly: .agents/skills/peer-role/SKILL.md if router declaration needs to surface the tripwire as a pre-condition

Cross-references:

AGENTS.md §3.5 (V-B-A core value) — Step 2.5 EXTENDS this from per-claim empirical-tool to per-graduation architectural-shape sweep
AGENTS.md §13.2 (friction → gold core value) — Step 2.5 IS the substrate-evolution graduating from this turn's friction
AGENTS.md §15.6 (Flat Peer-Team) — Step 2.5 preserves Flat Peer-Team agency (any peer can post the STEP_BACK comment); convergence-rate tripwire prevents fast-3-way as override of Flat Peer-Team divergence-protection

The Fix

Surface 1: `ideation-sandbox-workflow.md` — Add "Step 2.5: Architectural Step-Back"

Insert new section between existing Step 2 (Divergence Matrix) and existing graduation Step 3. Section content:

<h2 class="neo-h2" data-record-id="11">Step 2.5: Architectural Step-Back (high-blast-radius gate)</h2>

Before any `[RESOLVED_TO_AC]` or `[GRADUATED_TO_TICKET]` marker on a high-blast-radius
proposal, one peer MUST post a STEP_BACK comment covering the 8-point cross-substrate
sweep below.

**High-blast-radius triggers (any ONE qualifies)**:
- Modifies durable content layout (`resources/content/`, `learn/`, `.agents/`)
- Couples to CI/workflow (`.github/workflows/`)
- Requires data migration (file moves, schema mutation, ≥10 files affected)
- Modifies public skill/rule substrate (AGENTS.md sections, skill payloads)
- Cross-substrate (touches ≥2 of: services, MCP, daemons, CI, docs, release, agents)
- Epic-bound (decomposes to ≥3 sub-tickets)

**8-point cross-substrate sweep checklist** (adopted from Discussion #11188 OQ4):

1. **Authority sweep**: Which artifact will future agents treat as canonical — discussion body, latest comment, epic body, ticket AC? Are they consistent?
2. **Consumer sweep**: Which readers consume the proposed shape? Include syncers, local lookup services, health/readiness, release scripts, workflows, docs, external mirrors (pages/portal).
3. **Path determinism sweep**: Can the path/key be computed from stable identity alone? If not, name the metadata/index/search contract explicitly.
4. **State mutability sweep**: Which fields decide lifecycle placement (`closedAt`, `mergedAt`, `answerChosenAt`, etc.)? Are they enforced by substrate, mutable, or only socially expected?
5. **Density and UX sweep**: Use actual counts/distributions, then check human navigation and GitHub/portal UI constraints — not only hard FS caps.
6. **Migration blast-radius sweep**: Estimate file moves, generated sync churn, branch-collision risk, scope-coupling.
7. **Active vs archive boundary sweep**: Do not generalize archive logic to active state unless active-state churn and lookup semantics are explicitly handled.
8. **Existing primitive sweep**: Grep CI/workflows/scripts for primitives that make the design simpler (e.g., `prevent-reopen.yml` for closedAt-immutability).

**Exit criterion**: STEP_BACK comment posted, peers acknowledge each of 8 points (✓ pass / ⚠ partial / ✗ blocker). Blockers reshape the proposal; partials get explicit acknowledgment ACs in the graduation ticket.

Surface 2: `peer-role-mode.md` — Add convergence-rate tripwire

Insert new subsection (likely under existing "Substrate-validation" guidance):

<h3 class="neo-h3" data-record-id="13">Convergence-Rate Tripwire</h3>

If 3 peers reach agreement on a high-blast-radius proposal within ≤2 rounds AND no
STEP_BACK comment yet exists on the parent Discussion, peer-role MUST require a Step
2.5 sweep before `[RESOLVED_TO_AC]`. The tripwire is NOT a verdict — fast convergence
may be genuinely correct — but the sweep validates it.

Trigger phrases that should fire the tripwire on observation:
- "I agree with @peer's option X"
- "Adopt Option X"
- "Going with X"
when posted by the 3rd peer within ≤2 rounds on a high-blast-radius proposal.

Action: post a STEP_BACK comment running the 8-point sweep (see
`ideation-sandbox-workflow.md` Step 2.5). If all 8 points pass, fast-convergence
stands; if any blocker surfaces, reshape and re-converge.

Surface 3: `.claude/CLAUDE.md` §3.5 — Compressed pointer (2-3 lines)

After the existing §3.5 V-B-A description, append:

**Step 2.5 (Architectural Step-Back)** extends V-B-A to per-graduation architectural-shape sweep for high-blast-radius proposals; lives in `ideation-sandbox-workflow.md` Step 2.5 + `peer-role-mode.md` convergence-rate tripwire. Auto-fires on `[RESOLVED_TO_AC]` graduation attempts for proposals meeting high-blast-radius triggers.

Surface 4: `.claude/CLAUDE.md` §21 workflow-skills table

Add row:

| `step-back-sweep` (implicit; lives in ideation-sandbox + peer-role) | High-blast-radius proposal about to graduate `[RESOLVED_TO_AC]` |

(Or: extend existing ideation-sandbox row trigger condition to note Step 2.5 auto-fire.)

Contract Ledger Matrix

Target Surface	Source of Authority	Proposed Behavior	Fallback	Docs	Evidence
`ideation-sandbox-workflow.md` Step 2.5	Discussion #11188 RESOLVED_TO_AC	Mandate STEP_BACK comment with 8-point sweep before `[RESOLVED_TO_AC]` on high-blast-radius proposals	If proposal not high-blast-radius per trigger list, Step 2.5 SKIPPED	Inline in workflow doc	Verify next 3 ideation cycles use Step 2.5 when triggers fire
`peer-role-mode.md` convergence-rate tripwire	Discussion #11188 Option B adopted	≤2-round 3-way agreement on high-blast-radius → require Step 2.5 sweep	Tripwire only fires once per proposal; subsequent rounds don't re-trigger	Inline in peer-role-mode doc	Empirical: track tripwire firings vs Step 2.5 sweeps for 30 days
`.claude/CLAUDE.md` §3.5 pointer	Discussion #11188 Option D adopted with compressed-pointer constraint	2-3 line pointer; no inline expansion	None — pointer is mandatory minimum	Inline in CLAUDE.md	Verify byte-count of §3.5 addition ≤300 bytes
`.claude/CLAUDE.md` §21 table row	This ticket	Note Step 2.5 trigger in workflow-skills table	Could extend existing `ideation-sandbox` row's trigger column instead	Inline in CLAUDE.md §21	Verify §21 routing table includes Step 2.5 surface

Acceptance Criteria

AC1: ideation-sandbox-workflow.md Step 2.5 section added with high-blast-radius trigger list + 8-point cross-substrate sweep checklist + exit criterion
AC2: peer-role-mode.md convergence-rate tripwire subsection added with trigger phrases + action
AC3: .claude/CLAUDE.md §3.5 compressed pointer added (≤300 bytes)
AC4: .claude/CLAUDE.md §21 workflow-skills table updated (new row OR ideation-sandbox row extended)
AC5: Discussion #11188 body updated with [GRADUATED_TO_TICKET: #THIS_NUMBER] marker (per ticket-create-workflow.md §11 authorship-respect — I authored Discussion #11188)
AC6: Cross-family review on the PR — primary-reviewer @neo-gpt (he proposed Step 2.5 framing); secondary @neo-gemini-3-1-pro (she validated the discipline)

[Cycle 2 body amendment 2026-05-11 per PR #11194 Cycle 1 review]: AC7 + AC8 are post-merge ACs whose evidence cannot exist at PR-merge time. Per pull-request-workflow §9 close-target-evidence semantics, closing this ticket on PR #11194 merge would record completion before evidence exists. Split: AC7 + AC8 graduated to follow-up validation ticket #11195 [L4-deferred — operator handoff needed at Day 30]. This ticket (#11192) now carries only implementation ACs (AC1-AC6) — all static-review-verifiable + closing cleanly on PR #11194 merge.

AC7 (post-merge verification): Within 30 days of merge, observe at least 2 ideation cycles where Step 2.5 fires; verify the 8-point sweep surfaces ≥1 substrate gap that would have caused post-graduation friction [GRADUATED_TO_FOLLOWUP: #11195]
AC8 (substrate accretion defense per §13): PR body documents net-byte change across all 4 surfaces; if net add >500 bytes total, justify with future-decay-mitigation rationale per §13 Substrate Accretion Defense [GRADUATED_TO_FOLLOWUP: #11195]

Out of Scope

Automating Step 2.5 sweep via lint/tool: Step 2.5 stays discipline-layer for now. Automation is a separate future ticket if the discipline proves load-bearing across ≥10 cycles.
Operator-correction metric (Option C): Deferred per 3-way consensus — no consumer yet. Capture in retrospectives first; automate later if a decision-pattern emerges.
Forced devil's-advocate (Option E): Rejected per 3-way consensus.
Per-domain checklist specialization: 8-point list is the canonical floor; domains may extend in their own skill payloads (e.g., pr-review could add domain-specific sweep entries) but not in this ticket.
Retroactive Step 2.5 sweeps on existing graduated Discussions: Step 2.5 applies prospectively to new ideation cycles; retro-sweep is post-mortem analysis, not graduation gate.
Refactoring the existing Double Diamond Divergence Guard: §5.1 stays as-is (it covers divergence-phase discipline); Step 2.5 covers convergence-phase discipline. They're complementary.

Avoided Traps

AGENTS.md atlas-style expansion (Option D variant): Rejected — would inflate per-turn context budget against AGENTS.md §13 Substrate Accretion Defense. Pointer-only constraint enforced via AC3 ≤300-byte cap.
Single skill payload monolith (combine Step 2.5 + tripwire into one skill): Rejected — ideation-sandbox owns the convergence-discipline; peer-role owns the role-discipline; combining them couples concerns + risks Progressive Disclosure violation per create-skill/SKILL.md.
Mandatory STEP_BACK on every Discussion (not just high-blast-radius): Rejected — would penalize routine ideation cycles + create theater. Trigger criteria scope to actual high-blast-radius.
Step 2.5 as machine-enforceable gate (CLAUDE.md §0 invariant placement): Rejected at this tier — per AGENTS.md §13.2, core values change rarely; this is a value-tier mutation (discipline), not an invariant-tier mutation (mechanical-gate). Future automation may elevate; not yet.
Coupling Step 2.5 graduation to specific tooling (e.g., gh PR label, GitHub Action): Rejected — discipline-layer mutation should stand without tool-coupling; tooling can come later if discipline proves load-bearing.

Discussion #11188 (parent — Extended V-B-A / Step 2.5 ideation; this ticket graduates it)
Discussion #11180 (empirical anchor — fast-convergence pattern that surfaced the need)
Epic #11187 (empirical anchor — the post-graduation friction that proved discipline gap; GPT's Stage 2 epic-review caught 2 blockers Step 2.5 would have caught pre-graduation)
AGENTS.md §3.5 (V-B-A core value — Step 2.5 extends per-graduation)
AGENTS.md §13.2 (friction → gold core value — this ticket IS the substrate-evolution from this session's friction)
AGENTS.md §15.6 (Flat Peer-Team — Step 2.5 preserves peer agency)
.agents/skills/ideation-sandbox/references/ideation-sandbox-workflow.md (surface 1)
.agents/skills/peer-role/references/peer-role-mode.md (surface 2)
.agents/skills/create-skill/SKILL.md (Progressive Disclosure pattern — consulted per §1b)
ticket-create-workflow.md §1c (ungraduated-Discussion cross-check — substantive-rationale exception applied)

Origin Session ID

c2912891-b459-4a03-b2af-154d5e264df1

Handoff Retrieval Hints

query_raw_memories(query="Step 2.5 Architectural Step-Back Extended V-B-A high-blast-radius ideation-sandbox convergence-rate tripwire")
ask_knowledge_base(query="ideation sandbox convergence discipline cross-substrate sweep")
Git commit-range anchor: git log --oneline --grep="11188" --since="2026-05-11" for graduation-context
Discussion comment anchors: https://github.com/neomjs/neo/discussions/11188#discussioncomment-16876724 (GPT) + 16876743 (Gemini) + 16876853 (Opus)
File:line anchors: .agents/skills/{ideation-sandbox,peer-role}/references/ + .claude/CLAUDE.md §3.5 + §21

tobiu closed this issue on May 11, 2026, 1:50 PM

tobiu referenced in commit a7f7d2d - "feat(agents): graduate Step 2.5 Architectural Step-Back (#11192) (#11194) on May 11, 2026, 1:50 PM