DEV Community: canonical

Mission Driver: A General Reference Implementation of Loop Engineering

canonical — Fri, 31 Jul 2026 23:26:30 +0000

How a universal AI task-driven engine achieves local fault tolerance and stability guarantees through nested loops.

Part 1: Getting Started

1. The Problem: From Vibe Coding to Autonomous Operation

Current mainstream AI-assisted development is still Vibe Coding: a human prompts, the AI responds, the human corrects, and the AI responds again. This can be called the Human in the Loop model. Every output requires human confirmation and correction; human and AI work in alternation.

This model has two problems.

The first is loss of quality control. AI execution is essentially a probabilistic sampling process. Without an external control structure intervening, the AI can easily veer off course—for example, changing other code halfway through a task, forgetting to run tests after making changes, falling into an infinite loop upon failure, or losing state after a crash and having to start over. Even more dangerous is self-declared completion—claiming something is done without actually implementing it.

The second is capacity limitation. When a human is in the loop, the ultimate bottleneck remains human working time and energy. A person works 8 hours a day; even if AI assistance triples efficiency, the ceiling is only 24 person-hours. To truly unleash AI productivity, we must move toward Human on the Loop: AI runs fully autonomously 7×24, the human steps out of the loop and becomes a control factor that intervenes on demand.

This is not just a shift in operating mode, but a change in cost structure. When AI can run autonomously 7×24, working hours are no longer the constraint. A weaker model may take longer and consume more tokens to complete a job, but it is cheap enough to run at night without occupying human time. Multiple missions can process different roadmap work items in parallel. Cost accounting changes from "output per person-hour" to "intelligent output per dollar."

Mission Driver is a concrete control structure that realizes this transition.

2. What is Mission Driver (One-Minute Version)

Mission Driver is a declarative task-driven engine. You give it a goal (described via a roadmap), and it automatically enters a loop:

Check health status (initial, once) → Review plans → Execute plans → Draft new plans → (back to Review plans) → When no new plans can be drafted → Deep audit → (back to Review plans)...

The loop runs until the goal is achieved or the audit budget is exhausted. Each step is an independent AI subprocess or script function; failure of a single step does not affect the overall loop.

It is a component of Attractor-Guided Engineering (open-source repository links at the end of the article), and it is not limited to software development. By configuring custom flows, prompts, and commands, it can be naturally generalized to scenarios such as data processing and document analysis—a universal mechanism for fully autonomous AI operation.

It is suitable for complex tasks that require long-running execution, clear acceptance criteria, and multi-step iteration.

Loop Engineering is a design methodology rapidly emerging in the AI engineering field—using loop structures instead of linear prompts to let AI systems run autonomously until goals are met. It is not a proprietary feature of any particular tool, but an engineering pattern that can be designed independently of specific tools. Mission Driver is a general reference implementation of Loop Engineering.

3. How It Works: Loop Nesting and Local Fault Tolerance

If we view Vibe Coding as a single infinite loop, the core of Mission Driver is decomposing that single loop into nested multi-layer loops—Mission Driver's main loop (the five-step closed loop) is the outer layer, with embedded inner layers: the Plan Loop (the execute → check → audit → verify cycle in the EXEC_PLANS subflow) and an optional Audit Loop (the multi-dimensional audit cycle in the DEEP_AUDIT subflow). Understanding this nested structure is key to understanding why it can run stably for long periods.

Suppose there are 3 active plans, and the execution of plan-002 encounters a blockage:

EXEC_PLANS:
  ├── plan-001: EXECUTE ✓ → CHECK ✓ → BUILD ✓ → completed ✓
  ├── plan-002: EXECUTE ✗ → retried 3 times still failed → subflow failed
  │              → executing agent finds a prerequisite not met
  │              → moves the blocked item to Deferred But Adjudicated, records trigger conditions
  │              → remaining phases continue → completed (with Follow-up items)
  └── plan-003: EXECUTE ✓ → CHECK ✓ → BUILD ✓ → completed ✓

The execution blockage of plan-002 has no impact on plan-001 and plan-003. The blockage is confined within the subflow and does not propagate to sibling subflows or the parent loop. This is the local fault tolerance brought by loop nesting.

During plan execution, the AI decides based on the actual situation: locally blocked items are moved to Deferred But Adjudicated with successor trigger conditions recorded, while the rest of the scope completes normally; if the entire direction of the plan is falsified, it is marked as superseded or cancelled. The status of the plan's .md file is always managed by the AI agent.

The execution state of each step is persisted to disk (checkboxes in the plan file). After a process crash and restart, the engine scans the checkbox marks on disk and resumes from the breakpoint without replaying history.

Part 2: Starting Out

4. Quick Start

The source project for Mission Driver is in the AGE Template project. Typically, we add a tools/mission-driver.sh script in our own project to proxy calls to Mission Driver, and point to the Mission Driver source directory via the MISSION_DRIVER_HOME environment variable.

Getting started flow:

Download the AGE template, let AI read and adapt it to your project (adjust document structure, configure commands, initialize roadmap)
Ensure test commands are executable (npm test / mvn test / Playwright)
In daily AI conversations, draft plans into the plans directory according to the plan guide, accumulating plans and logs
Start the mission

# Generate mission config + roadmap
./tools/mission-driver.sh draft "your goal description"

# Validate config
node $MISSION_DRIVER_HOME/src/mission-check.mjs missions/<name>.json .

# Dry-run to verify flow orchestration
./tools/mission-driver.sh run <name> --dry-run --no-monitor

# Formal run
./tools/mission-driver.sh run <name>

Monitoring:

Mission Driver has a built-in visual monitoring page.

open http://localhost:9300              # Browser dashboard
cat _tmp/<runDir>/run-state.json        # Read state
tail -f _tmp/<runDir>/<mission>.log     # Follow logs

Interruption and Recovery:

# Ctrl-C safe interrupt (engine catches signal, cleans up child processes)
# Rerunning automatically resumes
./tools/mission-driver.sh run <name>

# Resume from a specific step
./tools/mission-driver.sh run <name> --from-step EXEC_PLANS

# Fast mode (skip DEEP_AUDIT)
./tools/mission-driver.sh run <name> --fast

Postmortem:

./tools/mission-driver.sh analyze           # Analyze most recent run
./tools/mission-driver.sh analyze <runId>   # Analyze a specific run

Postmortem scans all events and logs, runs a postmortem agent, and writes a structured report to the memory directory. Subsequent missions for the same module will automatically load these lessons learned.

5. The Four-Layer Definition System

Mission Driver consists of four layers of definitions, used through configuration rather than programming.

5.1 Mission Config (`missions/<name>.json`)

Pure static configuration, declaring what to do, where to do it, and how to verify:

{
  "name": "medical-qa",
  "description": "Generate QA training dataset from medical papers",
  "roadmapPath": "docs/backlog/medical-qa-roadmap.md",
  "plansDir": "docs/plans/medical-qa",
  "commands": {
    "test": "python scripts/check_quality.py --min-records 500",
    "typecheck": "python -c \"import dataflow\" && echo OK"
  },
  "promptsDir": "missions/prompts/data-processing"
}

commands.test is a required field; CHECK and BUILD_VERIFY both run it. build/lint/typecheck are optional and skipped if missing. Runtime state is in _tmp/<runId>/run-state.json and is not written to mission.json.

5.2 Flow Definition

The engine core is a generic state machine DSL executor (FlowEngine, with zero project-specific logic). Flow definitions declare how steps are orchestrated, how transitions occur, and what to do on errors. The engine advances the state machine according to the flow description, not bound to any fixed steps.

A simplified flow structure:

{
  "name": "my-flow",
  "entry": "CHECK",
  "steps": {
    "CHECK": {
      "type": "agent",
      "promptPath": "prompts/health-check.md",
      "transitions": {
        "pass": { "goto": "NEXT_STEP" },
        "fail": { "done": "failed" }
      }
    },
    "NEXT_STEP": {
      "type": "subflow",
      "flow": "my-subflow",
      "forEach": "activePlans()",
      "transitions": {
        "all_complete": { "done": "completed" }
      }
    }
  }
}

Step types: agent (AI subprocess), script (JS function), subflow (nested subflow), group (grouped steps)
Control flow: transitions define jumps between steps (goto/done/retry); forEach iterates over a collection launching a subflow per element; when/otherwise for conditional skipping
Error handling: each step can configure maxRetries, onMaxRetries, onError, onUnknown; the engine also provides global infinite-loop detection (ping_pong + max_cycles + max_total_steps)

The built-in default flow (flows/mission-driver.json) is the cycle we've been discussing. Its actual structure is: CHECK runs only once at the entry, then enters the loop body REVIEW_PLANS → EXEC_PLANS → DRAFT_PLANS; when DRAFT_PLANS has no new plans to draft, it enters DEEP_AUDIT, then returns to the loop body. It is not hardcoded, just a default configuration. EXEC_PLANS and DEEP_AUDIT themselves are subflows (plan-execution.json / deep-audit-loop.json) that can be replaced independently.

This means entirely new workflows can be designed—for example, a code review workflow that doesn't need Plan orchestration can be written as a four-step flow: FETCH_PR → RUN_LINT → AI_REVIEW → POST_COMMENT. Place custom flow JSON in the missions/flows/ directory and set "flowName": "<custom>" in mission.json; the engine remains unchanged.

5.3 Plan Files

A Plan is the smallest unit of work, automatically generated by AI following a specific format. Its core is not just defining a to-do list, but defining the closure contract for how to judge completion. Its standard structure is as follows:

# 01 Purchase Order Approval Workflow Integration

> Plan Status: draft
> Last Reviewed: 2026-07-25
> Source: roadmap item "Core Business Logic M1"

## Current Baseline
- ErpPurOrder entity modeled, CRUD generated
- No approval logic yet

## Goals
- Purchase orders support submit→approve→reject/approve status transitions
- After approval, trigger inventory posting

## Non-Goals
- No multi-level approval
- No approval delegation

### Phase 1 - Approval State Machine
Status: planned

- [ ] Implement submitForApproval / approve / reject methods
- [ ] Status validation: only DRAFT can be submitted

Exit Criteria:
- [ ] After submit→approve, posted=true
- [ ] Unit tests cover all state transitions

## Closure Gates
- [ ] End-to-end: complete chain submit→approve→posting→reversal verified
- [ ] Independent sub-agent closure audit passed
- [ ] mvn test all green

Top three lines of status markers, Goals + Non-Goals (to prevent scope drift), each Phase has Status + checkboxes + Exit Criteria, and Closure Gates are plan-level final checks. Checkboxes are machine-readable persistent state; the engine resumes from breakpoints by scanning checkboxes. Before marking completed, all checkboxes must be checked.

In AGE practice, humans generally do not need to read Plans; they are created and updated entirely by AI autonomously.

5.4 Roadmap

The Roadmap is a human-readable, controllable macro plan. According to the docs/backlog/00-roadmap-authoring-guide.md specification, work items are grouped by milestones, carrying only three states: todo/ready/done; milestones themselves carry no state:

# Core Business Roadmap

> Prerequisites: All CRUD completed

## Work Item Status

### Milestone M1 — Core Business Cycle

- Purchase requisition approval→convert to order logic: `done`
- Sales quotation approval→convert to order logic: `done`
- Purchase Order BizModel (approval/receiving trigger/posting): `done`
- Sales Order BizModel (approval/shipping trigger/posting): `done`
- Three-way matching logic: `done`

### Milestone M2 — Business-Finance Integration End-to-End

- Procure-to-Pay full chain (PO→Receive→Invoice→Pay): `done`
- Order-to-Cash full chain (SO→Delivery→Invoice→Receipt): `done`
- Period-end closing full process: `todo`
- Return-to-Refund full chain: `todo`

### Milestone M3 — Extended Domain Business Logic

- HR Shift Scheduling Engine: `todo`
- Payroll Calculation: `todo`
- APS Production Scheduling: `todo`

DRAFT_PLANS launches an AI agent: reads the full roadmap + deferred items in historical plans → reads project context and planGuide → selects the next 1–3 work items → drafts plan drafts (Status: draft) → calls an independent sub-agent to review; upon approval, marks them active. When no remaining work can be drafted, it returns nothing, and the engine decides whether to enter an audit round based on this.

6. Configuration and Customization

The Mission Driver engine is completely generic. Customization can be achieved through configuration and prompt overrides, with absolutely no need to modify code. In general, you only need to add a mission-driver.sh script in your own project; it calls the Mission Driver implementation from the AGE template project via paths configured in environment variables.

Customization Layer	Mechanism	Example
Prompt Override	`missions/prompts/<name>.md` overrides built-in	EXECUTE prompt for data processing says "call script" instead of "modify code"
Flow Tuning	Override a same-name flow in `missions/flows/mission-driver.json`, add/remove/modify steps	Insert a compliance audit step after CHECK
Brand New Flow	Write `missions/flows/<custom>.json`, set `flowName: "<custom>"` in mission.json	Code review flow FETCH_PR → RUN_LINT → AI_REVIEW → POST_COMMENT, without Plan orchestration
Subflow Override	Place a same-name subflow JSON (e.g., `plan-execution.json`) in `missions/flows/` to replace built-in subflows	Replace EXEC_PLANS subflow so each active plan calls external scripts before and after execution
Commands	`commands` field in `mission.json`	test = quality check script

Flow loading priority: project missions/flows/<flowName>.json → engine built-in tools/mission-driver/flows/<flowName>.json. Same-name file in project takes precedence. Subflows follow the same chain.

The promptsDir configuration allows different missions to point to different prompt subdirectories, enabling the same engine with different prompt sets:

{
  "promptsDir": "missions/prompts/analysis",
  "flowName": "mission-driver"
}

Engine prompt loading chain: promptsDir (task-type level) → missionsDir/prompts (project level) → built-in default. Behavior is unchanged when promptsDir is not set.

The built-in CHECK→REVIEW→EXEC→DRAFT→AUDIT applies to most software development scenarios. But for tasks like data processing and document analysis, it can be fully adapted with different flows—engine unchanged, just swap the flow file.

The above customization methods fully embody the Delta customization idea from the Reversible Computation Theory, a concrete implementation of non-intrusive customization. For a detailed introduction to Delta customization, see How to Achieve Custom Development Without Modifying Base Product Source Code

Part 3: Practice Methodology

7. Loop as Intelligence

The effectiveness of Mission Driver comes not only from the quality of individual AI calls, but primarily from iterative feedback improvement through loops. Feedback generated in each round of execution (test results, audit findings, human corrections) should be recorded and used to improve the next round.

AGE uses two parallel improvement tracks:

Prompts for doing (DRAFT/EXECUTE): When AI-generated plans or code are corrected by a human, the correction record is analyzed by a sub-agent, extracting general rules and writing them into skills. The AI automatically loads them next time.

Prompts for checking (CLOSURE_AUDIT/DEEP_AUDIT): When an audit misses an issue, supplement the audit prompt with additional checking dimensions.

AI generates first version
  → Human modifies (modification process logged)
  → Independent sub-agent compares original and modified versions
  → Extracts general rules on "why it was changed"
  → Writes into skills or coding standards
  → AI automatically loads next time

The nop-app-erp project has accumulated 19 reusable skills, all originating from this loop-based improvement.

8. AI Auto-Generation of E2E Tests

The manual writing and maintenance cost of E2E tests is very high; previously, few teams could maintain them broadly long-term. Now, AI can generate them automatically. The key is reducing difficulty: encapsulate the PageObject pattern, provide simplified operations like getFieldValue(containerLocator, fieldName), so AI does not need to repeatedly deal with complex DOM selectors for every page.

For example, in the Nop platform's AMIS pages, every field has a stable business identifier defined in view.xml via <cell id="customerName">, which is rendered as the AMIS component's name attribute. AI only needs to look up fields by business name:

# AI focuses on the intent "get customer name", not the DOM path
value = getFieldValue(page, "customerName")
# The encapsulation layer internally locates the input element of the corresponding AMIS component by name attribute

This encapsulation makes AI-generated test scripts more stable—when page layout changes, only the PageObject encapsulation layer needs updating; existing test cases do not need individual modification.

nop-app-erp went from 0 to 260+ specs; frequent human corrections were needed in the early phase, but later it was largely auto-generated or auto-modified.

Part 4: Case Study

9. nop-app-erp: 154 Modules in 22 Days

nop-app-erp provides a publicly auditable case: how multi-layer loop nesting drove AI from an empty skeleton to produce a production-grade ERP. In this project, directories like logs/audits/plans record the execution process and reasons for all key decisions, making it fully analyzable by AI to answer any questions about the project's evolution.
This is an inevitable result of AGE's explicit requirement that the project itself is the single source of truth: no information remains stranded in human brains, chat windows, or temporary conversations; the project's documentation and source code contain the latest project status and its complete evolutionary trajectory.

Scale Metrics (Independently Audited)

Dimension	Value
Development Period	22 days
Business Domains	18 + 1
Maven Modules	154
Own Entities	352 + 110 reference stubs
Java Tests	~2890 (0 failures)
Playwright E2E	260+ specs (0 regressions)
Plan Files	187 (all double-audited)

A Real Cycle (07-10)

08:00 CHECK     — mvn all green
08:05 REVIEW    — 4 drafts → independent review → all active
09:30 EXEC      — 4 plans executed, all green
16:00 DRAFT     — all roadmap work items done
16:05 DEEP_AUDIT — auto-triggered deep audit

One cycle took about 8 hours. The entire roadmap across 22 days was completed through dozens of cycles.

Pre-Coding Defect Interception

On 07-10, a batch of plans had independent draft review intercept 4 P0 defects: code value conflicts, BUDGET contaminating actual financials, an erroneous architectural premise in GlBalance, and dimensional ambiguity. All were intercepted before coding. Without the Plan Loop, these defects would only surface during implementation or even runtime.

Knowledge Transfer Curve

Human intervention was classified into three types: Type A (explicitly specifying platform mechanisms, concentrated early on), Type B (indicating engineering principle directions), Type C (only asking AI to self-check and compare, mainly later on).

The two curves crossed around 06-29 ~ 07-01; thereafter, AI autonomy became the primary working mode.

"Late-stage human intervention dropped to zero not because AI learned to write code, but because the attractor had been defined (the formal definition of attractors is in §12). With the right direction, AI can advance automatically."

Human attention should be spent on defining attractors, not on supervising execution. Mission Driver handles the latter. Over the entire 22 days, there were only 28 human interventions, concentrated in the early project phase. Later, as the attractor stabilized, human intervention dropped to zero, and AI advanced fully autonomously.

Part 5: In-Depth Analysis

10. Loop Engineering Principles

Traditional pipelines assume each step is deterministic, but the nature of AI execution is probabilistic—the same prompt in different sessions can produce different results.

Advantages of loop nesting: failure is expected (loops natively support retry and skip), quality is iterative (audit findings lead to improvement), recovery is natural (checkpoints are checkboxes on disk), isolation is structural (subflow boundaries = fault tolerance boundaries).

The three basic principles of Loop Engineering are: trajectory recoverability (persisted to disk, crash recovery via disk scan), local fault tolerance (subtask failure does not propagate to the parent loop), and independent verification (completion is audited by an independent sub-agent, not self-verified by the executor).

Stability Guarantees

Defense Line	Mechanism	Role
Disk Persistence	All state written to disk	Crash → restart → disk scan → breakpoint recovery
Subflow Isolation	Each plan in its own subflow	Local errors do not spread
Retry Budget	Max 3 fresh sessions per step	Avoid repeated failures in the same context
Infinite-Loop Detection	ping_pong + max_cycles + max_total_steps	Prevent infinite loops
Watchdog	60-minute sub-agent timeout	Prevent hangs
Independent Audit	CLOSURE_AUDIT uses different sub-agent	Prevent executor self-deception

Recovery Mechanism

Recovery is not replay (it does not re-execute historical steps) but disk scan (scanning disk marks). On startup, the engine scans .md files in plansDir, finds plans with Status: active, reads checkboxes ([x] skipped, [ ] resumed). The steps history in run-state.json is only for audit viewing and does not drive recovery.

11. Plan Loop and Verification System

Each plan's execution has its own internal control loop—the Plan Loop.

Core principle: generation and verification must be separated. Both draft review and closure audit are executed by independent sub-agents in fresh sessions; the auditor does not inherit the executor's context, starting from a fresh repository read.

Verification System: Script Checking + AI Auto-Improvement

Audit verification of whether a plan is complete is not simply mechanical checking or pure AI auditing, but a paired collaboration of both. Scripts automatically detect issues; when issues are found, AI automatically diagnoses and fixes them, then re-runs detection.

EXECUTE (agent: AI executes plan)
  ↓
CLOSURE_SCRIPT_CHECK (script: checks checkboxes + evidence)
  ├── pass → BUILD_VERIFY
  └── fail → CLOSURE_AUDIT (independent sub-agent review)
               ├── fixable → back to EXECUTE
               └── not fixable → blocked items moved to Deferred/Follow-up
                              rest of plan continues → completed
BUILD_VERIFY (agent: AI runs test/build/lint)
  ├── failure → AI auto-diagnosis → fix → re-run
  └── pass → plan completed ✓

Checkpoint	Detection Method	Upon Finding Issue
CHECK	Confirm buildable, test-passing baseline	AI auto-repair (max 3 fresh sessions)
CLOSURE_SCRIPT_CHECK	script checks checkboxes + evidence	Enter CLOSURE_AUDIT → back to EXECUTE; unfixable items moved to Deferred/Follow-up
BUILD_VERIFY	AI runs test/build/lint	AI diagnosis → fix → re-run
DEEP_AUDIT	Multi-dimensional audit + adversarial review	Generate remediation plan

The machine acts as referee, AI acts as improver.

12. AGE Theory: Attractors and Dynamical Systems

Mission Driver is the core implementation of AGE (Attractor-Guided Engineering) theory at the tool layer:

State Space = all possible states of the repository/project
Attractor   = docs documentation system (standardized docs like design/architecture)
              Defines "what stable structure the system should converge to in the long term"
Trajectory  = plans + logs + audits recording "how we got to the current state"
Control     = health checks + execution verification + independent audits correcting deviations

Note that the roadmap is not the attractor. The Roadmap is a human-controllable macro plan, a task-oriented projection of the attractor; the true attractor is the documentation system in docs.

Formation of Attractors

Attractors are not clear from the start. They undergo a process from vague to clear:

One-sentence requirement → Grill Me clarification → Attractor prototype (docs draft + roadmap)
  → Roadmap early stage: research competitors, refine attractor
  → Roadmap mid stage: execute items, audit convergence
  → Periodic insertion: audit/refactor/rethink, correct attractor
  → Convergence complete

The entire roadmap is executed fully autonomously, while humans influence it through two channels: before execution (Grill Me clarification + roadmap setting) and during execution (asynchronously injecting plans into the plans directory).

Asynchronous Human-AI Interaction

Mission Driver does not require real-time human interaction during execution. However, humans can asynchronously inject new tasks via the plans directory at any time:

User (or another AI agent) generates a new plan → places it in plans/ directory
  → Next round of REVIEW_PLANS automatically picks it up
  → draft status: independent review → promoted to active
  → active status: directly enters the execution queue

The plans directory can be viewed as a shared queue on the filesystem; multiple contributors can write to it independently: human developers, Code Review agents, remediation plans generated by DEEP_AUDIT all enter the same queue. There is no need to forcibly interrupt the currently executing mission to insert extra work.

13. Comparison with Codex Goal

Here we can compare Mission Driver with the Codex tool's goal mode. Through source code analysis of Codex, we can see that Codex has fairly sophisticated mechanisms (SQLite state database, goal 6-state state machine, pause/resume, token budget), but it differs significantly from Mission Driver in the following dimensions.

Dimension	Codex Goal	Mission Driver
State Persistence	SQLite + rollout JSONL. But runtime metric state is only in-memory Mutex, lost on crash; rollout may not be materialized	Checkbox disk persistence + run-state.json, all state on disk
Independent Verification	Continuation prompt requests self-review, but update_goal(complete) only writes DB without checking objective state	Combination of script checking and AI checking; CLOSURE_AUDIT mandatory by independent sub-agent
Task Granularity	Max 1 goal per thread (single objective + token budget)	Multi-plan coexistence management: plans/ can have multiple active plans simultaneously; engine executes sequentially
Async Interaction	Can pause/resume same thread, but cannot asynchronously inject new tasks	Anytime drop a plan into plans/, automatically picked up next round
Failure Isolation	Single goal failure contaminates context window	Subflow isolation: failure of one plan does not affect others
Termination Guarantee	Token budget + blocked detection (model self-reports requires 3 rounds; after self-report, deferred table prevents continued execution)	Multi-layer defenses (retry budget, infinite-loop detection, watchdog, etc.), all externally enforced
Information Visibility	SQLite + JSONL require tools to parse; runtime state is memory-invisible	All state is files, readable by both humans and AI

Part 6: Vision

14. Goal-Driven Vision and Economic Paradigm

The evolution direction of Mission Driver is a goal-driven AI system—the user states the goal, the system automatically clarifies, plans, executes, and verifies.

User: "Analyze the differences between nop-stream and Flink, improve nop-stream until it becomes a mature distributed stream processing framework"
  → Grill Me (requirement clarification) → clarified spec
  → Auto-Detect (task type → promptsDir)
  → Generate (roadmap + mission.json)
  → Run (automatic loop execution until complete)

Of these, Generate (draft command) and Run (run command) already have an implementation foundation. Grill Me (enhanced deep-interview skill) and Wrapper (entry layer) need to be built.

Shift in Economic Paradigm

§1 already pointed out that in the Human in the Loop model, the efficiency bottleneck is that the human must be inside the loop. The core change of Human on the Loop is not excluding humans, but moving the human's position from an execution node inside the loop to a control factor outside the loop. The frequency and timing of intervention are determined by the clarity of the attractor, not the AI's work rhythm.

The most profound impact of this structural change is the inversion of model selection strategy:

In Human in the Loop mode, every output blocks on human confirmation. The human cannot wait, so the fastest, strongest model must be used, even if it's expensive. Response latency is the primary constraint; model cost is secondary.
In fully autonomous operation mode, no one is waiting. A weaker model may be slower, consume more tokens, and require more iteration rounds to complete work, but it has a low unit cost, can run at night, and multiple missions can process different roadmap work items in parallel. Response latency changes from a constraint to a schedulable variable.

Cost accounting thus shifts from "output per person-hour" to "intelligent output per dollar"—the former optimizes the efficiency of a single human-computer interaction, the latter optimizes the cumulative output per unit of computing power. These two optimization objectives lead to completely different engineering choices: the former pursues single-conversation quality, the latter pursues the stability of the loop structure and the rigor of auditing.

15. Summary

The value of Mission Driver lies in three aspects:

First, it replaces linear pipelines with persistent, locally retryable loop nesting. AI steps are probabilistic, requiring retries, iteration, and local fault tolerance. Subflow isolation ensures the failure of one plan does not affect others.

Second, it achieves customization through configuration, not programming. The engine is a generic Flow DSL executor; the built-in five-step cycle is just the default flow—you can fine-tune steps, replace subflows, or design entirely new workflows. The differences between task types are captured in three layers: flow + prompt + commands.

Third, it puts all state on disk. Checkbox persistence + disk scan recovery means no data loss after a process crash.

It is not limited to code development. Any complex task requiring multi-step iteration, quality auditing, and fault-tolerant recovery can be driven by it. This is exactly the realization of Loop Engineering as an engineering practice.

Attractor Guidance and Trajectory Mining: The Convergence Mechanism of AI Native Engineering

canonical — Fri, 31 Jul 2026 23:22:41 +0000

AGE (Attractor Guided Engineering) is a set of AI-native engineering methodology that I developed during the creation of nop-chaos-flux.

https://github.com/entropy-cloud/nop-chaos-flux is a large-scale frontend framework project developed entirely under AI leadership.

Unlike typical Harness methodologies, the conceptual origin of AGE lies in the controlled convergence picture of dynamical systems in mathematical physics. Consequently, compared to methodology summaries based on accumulated experience, its introduction carries a distinct innovative character. When large AI models directly read documents and practices related to AGE, they often miss the point, frequently falling back into the engineering language they are more familiar with. For example:

Interpreting the attractor as a boundary, guardrail, or stronger constraint;
Understanding skills as the primary carrier for knowledge organization;
Framing the problem of information form as "whether to unify specs";
Understanding the plan as an execution checklist or approval page;
Treating logs, bugs, and history as retrospective archives rather than as part of the system's convergence mechanism.

But the real point is not any of these.

1. AI Is a High-Frequency Random Expansion Force; the System Must Possess Endogenous Convergence Capability

In an engineering system, AI acts more like a high-speed expansion force with inherent randomness. If it is to continuously participate in the system's evolution without causing overall drift, the capacity for convergence cannot be entrusted to the model itself. Instead, it must be endogenous to the entire system composed of the Agent, documentation, code, and verification/audit/memory mechanisms. In other words, what truly keeps the system converging stably is neither any spontaneous sense of direction from the AI, nor the unexternalized architectural judgments residing in a few individuals' minds, but rather the structural landscape provided by this extended cognitive system.

2. Generic Skills Cannot Substitute for a Project-Specific Attractor

Generic skills, at best, grasp the common knowledge of a task type or domain, but they generally lack an understanding of why this particular project is designed this way. In particular, they lack a firm grasp of the project's positioning, architectural trade-offs, design philosophy, overarching principles, historical baggage, and current baseline. Therefore, they are insufficient to form a project-specific attractor. When the system can only access a mass of information lacking clear authority hierarchies, proof relations, and precedence constraints, the increase in information paradoxically amplifies conflicts and heightens system instability. What is truly needed is neither generic architectural boilerplate nor some formulaic directory structure, but rather the project's own specific design ideas, semantic authority chains, and long-term convergence direction.

The substance of attractor guidance is not "writing the architecture down clearly," but organizing the project-specific design ideas, macro principles, authority relations, proof chains, and historical negation space into a systemic structure that can continuously shape subsequent evolutionary trends. That is to say, the attractor is not a document, but a stable convergence topology jointly carried by multiple repository artifacts.

3. Information Itself Is Independent of Form, but Form Affects the Efficiency of Intelligent Computation

Information in itself is independent of form; the same semantics can reside in different carriers such as documents, code, tests, DSLs, and logs. However, form significantly affects the efficiency, stability, and ambiguity rate of intelligent computation. Therefore, the question is not whether a unified spec must be adopted, but whether the mode of information organization fits the domain logic. Rather than flattening knowledge into a planar list of fixed formats, a better approach is often to independently organize it by domain concepts, semantic relations, and authority levels, and to establish a topological structure through links. Domain-specific expression has greater potential to achieve efficient information organization and semantic transfer.

The emphasis is not on "unified form," but on "structure submitting to the domain."

4. The Plan Is a Local Convergence Closed Loop and Must Accept External Auditing

The role of the Plan is not to serve as a temporary draft within a session, but to act as a verification closed loop and convergence mechanism for a given round of local changes: why make the change this time, what the boundaries are, what defines true closure, and what follow-up obligations remain. Precisely because of this, the Plan itself and its execution results must be subjected to mandatory external auditing to avoid the self-verification trap where "the implementer defines completion and then declares completion themselves." As for the specific structure of the Plan, it does not need to be absolutely uniform; it can be dynamically adjusted based on project complexity, task risk, and the current reliability of the AI—for example, whether to introduce a skill selection review or how to set the closure gate intensity.

5. Trajectories Are Core Objects, and Trajectory Mining Is a Generative Mechanism for Future Convergence Capability

From the perspective of dynamical systems, one extremely critical but frequently overlooked object is the trajectory. Most practices remain stuck at the task-driven level: once the task is done, the scaffolding seems useless, and whether the history is preserved is irrelevant. This is precisely the common blind spot.

Merely focusing on whether a single task is completed is not enough; what matters more is continuously recording the system's evolutionary trajectory. The significance of the trajectory is not just to record what happened in the past, but to continuously extract trend signals and periodic signals from the system's history, such as:

Which misunderstandings recur repeatedly;
Which locally correct decisions are accumulating into a directional error;
Which audit false positives are wasting the system's budget;
Which design debts cyclically resurge;
Which temporary patches always grow back into structural problems.

This trajectory information should not be discarded after the task ends; rather, it should be further distilled into tendentious audit prompts, calibration rules, normative document patches, or constraining document increments, thereby forming an ever-strengthening convergence force. Compared to the current practices that still generally remain at the task-driven level, trajectory mining represents an upgrade from "completing tasks" to "shaping long-term controlled evolution."

Conclusion

AI is responsible for expansion; the project-specific attractor is responsible for orientation; the Plan is responsible for local closed loops; trajectory mining is responsible for continuously strengthening the convergence capability. And all of this must be built upon an information organization that conforms to the domain's semantic topology, rather than relying on generic skills or fixed templates.

What attractor guidance addresses is where the system evolves in the long run; what trajectory mining addresses is how the system continuously generates stronger convergence capability from its own history. It is the combination of these two that truly allows AGE to surpass the common narratives of skills, guardrails, workflows, and review-agents.

References:

Task-Level Tools vs. Trajectory-Level Methodology: The Fundamental Divide Between Trellis, OpenSpec, and AGE

canonical — Fri, 31 Jul 2026 23:20:21 +0000

Introduction

Trellis is a third-party open-source template (@mindfoldhq/trellis) that aims to "give AI coding agents a consistent engineering workflow across 14+ platforms."
OpenSpec is a similar third-party open-source framework (@fission-ai/openspec), targeting "spec-driven development" and managing changes through delta specs.
AGE (Attractor-Guided Engineering) is a methodology grown out of the practice of nop-chaos-flux, with the core idea of state space → attractor → trajectory → control.
AGE does not presuppose many fixed tools; it stresses that tools should gradually emerge from where failures repeat: repeated errors → bug note → lesson → skill/prompt → audit script → lint rule → CI guard.
Core finding: The shared limitation of Trellis and OpenSpec is that both use the single change as the organizational unit, lacking repository-wide truth and the supporting capacity to evolve toward full AI automation. This analysis starts from the theoretical framework of AGE and compares the fundamental differences among the three.

Analysis

1. Positioning: What the Three Are

Trellis:

A productized engineering framework, installed via npm install -g @mindfoldhq/trellis && trellis init.
Provides a 3-phase workflow (Plan → Execute → Finish), task management scripts, a spec system, sub-agent dispatch, and multi-platform hooks.
The toolchain is determined at design time: 12 skills such as trellis-brainstorm, trellis-check, trellis-update-spec, trellis-break-loop, and so on.
5 core principles: Plan before code, Specs injected not remembered, Persist everything, Incremental development, Capture learnings.

OpenSpec:

A productized spec-driven framework, installed via npm install -g @fission-ai/openspec && openspec init.
The core model is the spec + delta + archive cycle: specs/ (source of truth) ← merge ← changes/ (delta specs).
Each change contains four artifacts — proposal → specs → design → tasks — generated according to a schema dependency graph.
Delta specs use ADDED/MODIFIED/REMOVED to describe incremental modifications and are merged back into the main specs upon archive.
4 philosophies: fluid not rigid, iterative not waterfall, easy not complex, brownfield-first.
Supports slash command integration for 25+ AI tools.

AGE:

A methodology, not a product. No npm package, no install command.
The AGE Template is a copy-and-use document skeleton (https://github.com/entropy-cloud/attractor-guided-engineering-template) that defines document responsibilities and processes, accompanied by generic tools (check-doc-links, check-oversized-files, etc.). Domain-specific tools need to be extracted from practice.
The AGE author has open-sourced several large-scale example projects demonstrating complete AGE practices in different domains:
- nop-chaos-flux (https://github.com/entropy-cloud/nop-chaos-flux): a frontend low-code framework with 15 audit files (including 11 scanners), 22 prompts, 66 bug notes, and 72 logs.
- nop-entropy (https://github.com/entropy-cloud/nop-entropy): a backend full-stack framework with docs-for-ai/ normative docs + ai-dev/ development memory tracks.
- nop-chaos-next (https://gitee.com/canonical-entropy/nop-chaos-next): an application-layer project, lightweight practice with design/, input/, logs/, skills/.
Theoretical framework: state space → attractor → trajectory → control; all practice elements can be deduced from this.

2. Tool Origin: Preset vs. Gradually Emerged

Trellis has 12 built-in skills; AGE’s domain tools need to be accumulated by oneself, or borrowed from other projects.

Trellis: Tools Determined at Design Time

Trellis’s 12 skills exist at project creation:

Skill	Origin	Responsibility
`trellis-brainstorm`	framework preset	requirement discovery process
`trellis-check`	framework preset	code quality checks
`trellis-update-spec`	framework preset	spec write-back
`trellis-break-loop`	framework preset	deep bug analysis (5-dimension framework)
`trellis-before-dev`	framework preset	pre-development context loading
`trellis-finish-work`	framework preset	task wrap-up
`trellis-start`	framework preset	task initiation
`trellis-continue`	framework preset	task resumption
`trellis-meta`	framework preset	framework self-operation
`first-principles-thinking`	framework preset	thinking method
`python-design`	framework preset	Python design guide
`contribute`	framework preset	contribution guide (docs, marketplace)

These skills are generic and unrelated to any specific project. Users get these tools without needing a bug history or audit findings. Among them, trellis-break-loop and trellis-update-spec form a mechanism to extract knowledge from failures (see Section 3 for details).

AGE: Tools Extracted Gradually from Practice

The tool growth chain in nop-chaos-flux is clearly visible:

Chain 1: hardcoded type dispatch → audit script

Bug found: hardcoded type switch in the renderer
  → audit finding: violates the architectural contract "renderers should dispatch via registry"
  → Plan 430: eliminate-hardcoded-type-dispatch-plan
  → extracted as script: scripts/audit/find-hardcoded-type-dispatch.mjs
  → rules encoded in: scripts/audit/rules.mjs

Chain 2: missing renderer markers → audit script

Bug found: renderer did not output marker class as per contract
  → appeared multiple times in deep audit dimension 09
  → extracted as script: scripts/audit/find-missing-renderer-markers.mjs

Chains 3–5: imprecise reactive subscriptions, async without failure path, React 19 legacy APIs → each with a corresponding audit script.

nop-entropy follows the same pattern:

Bug found: bare RuntimeException used in Java code
  → convention: NopException subclasses should be used
  → extracted as ast-grep rule: ai-dev/tools/rules/java-lint-bare-runtimeexception.yml

Out-of-the-Box vs. Gradual Accumulation

A new Trellis project instantly gets the complete 12 skills + workflow state machine + cross-platform hooks. A new AGE project starting from the Template has only generic tools, but can refer to open-source exemplars such as nop-chaos-flux, nop-entropy, and nop-chaos-next to quickly establish domain-specific tools. Trellis suits "starting today"; AGE suits "long-term evolution".

3. Extracting Knowledge from Failures: Two Mechanisms of Different Depth

Both Trellis and AGE extract knowledge from failures, but the artifact form and degree of automation differ.

Trellis: Extract to Prose Spec

trellis-break-loop provides a structured 5-dimension bug analysis framework:

Root Cause Category: 5 categories (Missing Spec / Cross-Layer Contract / Change Propagation Failure / Test Coverage Gap / Implicit Assumption)
Why Fixes Failed: 4 failure modes (Surface Fix / Incomplete Scope / Tool Limitation / Mental Model)
Prevention Mechanisms: 6 mechanisms (Documentation / Architecture / Compile-time / Runtime / Test Coverage / Code Review)
Systematic Expansion: similar issues / design flaws / process flaws
Knowledge Capture: mandatory update of spec files ("The analysis is worthless if it stays in chat. The value is in the updated specs.")

After analysis, the knowledge is written into .trellis/spec/ via trellis-update-spec, precipitated as prose in forms like Design Decision, Common Mistake, Case Study, etc.

AGE: Extract to Gradually Automated Tools

AGE’s promotion ladder (AGE Template AGENTS.md Rule 15):

Level 0: discover repeated issues
  ↓
Level 1: bug note (docs/bugs/) — record non-obvious root causes
  ↓
Level 2: lesson (docs/lessons/) — extract reusable judgment rules
  ↓
Level 3: skill/prompt (docs/skills/) — reusable audit/diagnostic methods
  ↓
Level 4: audit script (scripts/audit/) — semi-automated scanning
  ↓
Level 5: lint rule / CI guard — fully automated interception

nop-chaos-flux’s docs/skills/ directory (22 prompt files):

Skill/Prompt	Promotion Source
`bug-diagnosis-prompt.md` (242 lines)	diagnostic methodology extracted from 66+ bug fix histories
`open-ended-adversarial-review-prompt.md` (116 lines)	open-ended discovery method extracted from multiple rounds of adversarial review
`deep-audit-prompts.md` (2141 lines, 20 dimensions)	structured review framework extracted from multiple rounds of deep audits
`implementation-contract-review-prompt.md`	contract review method extracted from plan closure audits

Core Differences

Both extract knowledge from failures, but the form and automation level of the artifacts differ:

Dimension	Trellis	AGE
analysis framework	5 dimensions (break-loop)	promotion ladder (5 levels)
knowledge artifact	prose spec (coding conventions, cases)	prompt → script → lint rule (gradual automation)
deposit location	`.trellis/spec/`	`docs/skills/` → `scripts/audit/` → CI
automation level	prose only (human-readable)	prose → semi-automated scanning → fully automated interception
escalation mechanism	none (break-loop output goes directly into spec)	yes (same pattern recurring promotes to higher level)

The reason AGE can escalate is that it has dedicated time-sensitive document categories (bugs/, lessons/, skills/) to track whether a pattern repeats. Trellis precipitates knowledge into the spec once; when the same mistake is made again there is no upgrade path.

4. Document Organization: Domain-Adapted vs. Framework-Adapted + Normative/Historical Separation

These are two closely intertwined dimensions: who determines the document structure, and whether normative and historical information are separated.

Trellis: Framework-Preset Fixed Structure, Normative and Historical Mixed

.trellis/                  # top-level directory mandated by Trellis
├── spec/                  # coding conventions organized by package/layer + accumulated learnings
│   ├── cli/backend/
│   ├── cli/unit-test/
│   └── guides/
├── tasks/                 # task directories named by date (archived after completion)
│   └── MM-DD-name/
│       ├── prd.md / implement.jsonl / check.jsonl / task.json
└── workspace/             # session memory isolated by developer name (rotates at 2000 lines)

This structure serves Trellis’s own operation: the layering of spec/ serves the discovery mechanism of get_context.py, the format of tasks/ serves the lifecycle management of task.py, and the developer isolation of workspace/ serves multi-user scenarios. The 5 core principles (Plan before code, Persist everything, etc.) are cross-project constraints.

Normative and historical are not separated. The template types of trellis-update-spec (Design Decision, Common Mistake, Case Study, Gotcha) naturally encourage writing historical information into the spec. trellis-break-loop also requires "update spec/guides" after the 5-dimension analysis. Trellis has no separate bugs/, logs/, or lessons/ directories — tasks/ are archived upon completion, and workspace/journal rotates at 2000 lines. Learnings have nowhere to go but into the spec.

A real example — historical content in quality-guidelines.md (982 lines):

"Case Study (2026-04-22): current_phase / next_action drift across 4 writers + type declaration" — a complete bug evolution history including "what the first audit missed," "four drift patterns," and "final integration result"
"Cautionary tale — 0.6.0-beta.3 → 0.6.0-beta.4 emergency revert" — account of a version rollback incident
"Case Study (2026-04-30): issue #204 --yes + bootstrap recovery" — includes commit hash, discovery process, and fix process

In workflow-state-contract.md (299 lines): "Two production bugs (Phase 1.3 jsonl curation skip, Phase 3.4 commit skip) hit exactly this failure mode."

Case Studies mixed into the spec provide immediate causal context ("why does this rule exist"), whereas AGE requires cross-file references to obtain the same context. The cost is spec file bloat and the AI’s inability to distinguish "current specification" from "historical lesson" when reading.

AGE: Organized by Domain Needs, Strict Normative-Historical Separation

AGE document organization has only two constraints:

Progressive disclosure: unfold from a minimal entry point (index / start-here) gradually to detailed content.
Separation of normative and time-sensitive history: stable files use stable names; time-sensitive records carry dates.

Within these constraints, each project organizes its document structure according to its domain needs.

nop-chaos-flux (frontend low-code framework): docs/architecture/ organized by 4-layer priority (programme → conventions → baseline → subsystems), docs/components/ has 100 component design docs, docs/references/ compresses the most-used types into a single file. This is the domain need of a frontend framework.

nop-entropy (backend full-stack framework): docs-for-ai/ organized by numbered prefix reading order (00→04), separated from ai-dev/ (development process memory). Because users and developers are completely different audiences.

AGE Template (application-layer projects): has input/ (raw PM input) separated from requirements/ (implementation-ready requirements), and backlog/ (priority queue). This is the domain need of application development.

AGE’s normative/historical separation is explicitly stipulated by nop-chaos-flux plan guide Rule 14:

Documents under docs/architecture/ only describe the latest current design state. Do not write historical changes, do not write "Proposed vs Current" comparisons, do not write evolution narratives.

Only three types of historically related content are allowed in normative documents: the reason for a choice (why A over B), rejected alternatives with reasons (negative space), and exception records ("intentionally retained legacy behavior"). Evolution narratives must stay in logs/, bugs/, plans/.

Core Differences

Dimension	Trellis	AGE
document structure decider	framework (`.trellis/` three-piece suite)	domain (each project differs)
cross-cutting constraints	5 core principles + framework structural mandates	progressive disclosure + normative/historical separation
history in spec	allowed and encouraged (Case Study, Cautionary Tale)	strictly excluded (only reason for choice and negative space retained)
carrier for history	no dedicated carrier (journal rotates, tasks archived)	`bugs/`, `logs/`, `plans/`, `lessons/`
spec bloat risk	exists (knowledge only enters, never leaves)	low (owner doc retains only current state)
spec readability	high (causal context available in place)	requires cross-file references for context

5. Plans: Closure Contracts, Not Task Lists

An AGE plan is not "get this thing done," but establishing verifiable closure conditions for fully autonomous AI execution.

The Full Lifecycle of a Plan

An AGE plan has three key gates, all completed by independent AI sub-agents:

Draft review: an independent sub-agent audits whether the scope is honest, closure gates are real, and hidden dependencies exist.
Execution: the AI executes around the plan, recording focused proof at each step, owner doc synchronization, and verification results.
Closure audit: another independent sub-agent returns to the live repository and re-checks — independently verifying code, documentation, tests, and whether the closure conditions are truly satisfied.

The nop-chaos-flux plan guide (403 lines, 24 minimal rules) explicitly requires:

Rule 8: "completed must come from a separate closure audit"
Rule 12: "Before marking completed, a closure audit performed by an independent reviewer or independent sub-agent must be completed"
Rule 11: "When closing a plan, one must distinguish 'contract surface has appeared' from 'contract semantics have landed'"

Gradually Advancing Toward Full Automation

AGE’s overall goal is to gradually reduce human intervention nodes. In current practice, humans still control a few key nodes (defining attractors, arbitrating conflicts, calibrating direction), but the draft review and closure audit of plans are already fully completed by independent AI sub-agents. The future direction: humans control only input and final output, with sampling-based monitoring of intermediate processes.

first-principles-of-agent-engineering.md defines the essence of an Agent: "An Agent is a system that, under goal constraints, maintains, verifies, corrects, and reuses actionable cognitive structures across time." A plan is a local carrier for verification and correction — it defines "what it truly means for this round of expansion to be complete," and then an independent sub-agent verifies it.

Comparison with Trellis

Trellis’s plan/execution system has two layers:

First layer: PRD (design document + requirements document). Trellis’s prd.md is closer to a design document than pure requirements — containing Goal, Assumptions, Requirements, Acceptance Criteria, Out of Scope, Decisions (ADR-lite), and Technical Notes. It is co-created with the user through collaborative brainstorming in Phase 1.

Second layer: generic execution flow. workflow.md defines a universal 3-phase execution list for each task: Phase 1 (1.0–1.5: create task → explore requirements → research → configure context → activate) → Phase 2 (2.1–2.3: implement → quality check → rollback) → Phase 3 (3.1–3.5: quality verification → debug post-mortem → spec update → commit → wrap-up). Phase 2 implementation and checks are done autonomously by sub-agents; the Phase 3.4 commit requires a one-shot user confirmation.

Comparison of AGE’s plan vs. Trellis’s PRD + execution flow:

Dimension	Trellis PRD + 3-phase flow	AGE Plan
plan content	PRD: design + requirements + technical approach + acceptance criteria	Goals/Non-Goals/Closure Gates/execution items
execution list	generic (workflow.md 3 phases, shared by all tasks)	custom (each plan has its own Fix/Decision/Proof execution items)
Current Baseline	none	mandatory: check live repository before execution
Non-Goals	present (Out of Scope section)	mandatory: prevent scope drift
Closure Gates	present (Acceptance Criteria, self-checked by implementer)	mandatory: closure conditions, verified by independent sub-agent
Draft review	none	independent sub-agent audit
Closure audit	none (implementer self-checks against Acceptance Criteria)	independent sub-agent returns to live repository to verify
completion decision	self-check before Phase 3.4 commit	evidence from independent closure audit
human role	participates in PRD collaboration and commit confirmation	does not review intermediate plans, controls only input and final output
automation target	human always in the loop	gradually advancing toward full automation

Logs: Automatically Recorded Trajectory

AGE’s AGENTS.md mandates: "After completing any significant code change, you MUST update the daily dev log."

nop-chaos-flux’s docs/logs/2026/ directory contains 72 daily log files, each recording: specifically which workstream of which plan was closed, which code paths were modified (precise to file:line), which focused proofs passed, which owner docs were synchronously updated, repository-wide verification status, and the subagent task ID of the independent closure audit.

Trellis’s equivalent is workspace/journal-N.md — personal session memory, rotating after 2000 lines. It does not record precise code paths and verification baselines, and has no connection to plans.

6. Audit System: Shared Executive Checks + AGE’s Unique Directional Audit

Both AGE and Trellis have code quality gates. The difference is that AGE adds a layer of directional audit.

Common Ground: lint/test/typecheck as Commit Gates

Trellis’s Phase 2.2 (Quality check) and Phase 3.1 (Quality verification) require running pnpm lint && pnpm typecheck && pnpm test, encapsulated by the trellis-check skill.

AGE also has mandatory gates. nop-chaos-flux’s plan guide requires pnpm typecheck/build/lint/test all green to close a plan; nop-entropy’s AGENTS.md requires ./mvnw test -pl <affected-module> -am passes, and Rule 13 explicitly states, "fixed rules that have entered lint, static check scripts, or CI fail-fast are non-negotiable hard constraints." nop-entropy’s pre-commit hook also enforces code formatting checks. The two are equivalent at this level.

Trellis Unique: 5-Dimension Post-Mortem

trellis-break-loop provides structured bug post-mortems (Root Cause Category / Why Fixes Failed / Prevention / Systematic Expansion / Knowledge Capture), updating the spec after analysis.

AGE Unique: Overall Document-Code Consistency Audit

Deep Audit (deep-audit-prompts.md, 2141 lines, 20 dimensions) covers 6 categories:

Category	Dimensions	Audit Object
A. Architecture & Module Boundaries	01–03	dependency graph, module responsibilities, API surface area
B. Runtime & State	04–08	state ownership, reactive precision, async safety, lifecycle, validation consistency
C. Renderer & UI	09–12	renderer contract, style compliance, component usage, field modeling
D. Engineering Quality	13–15	type safety, test coverage, security & performance
E. Documentation & Consistency	16–18	document-code consistency, naming consistency, cross-package pattern consistency
F. Runtime Robustness	19–20	error propagation fidelity, accessibility

Dimensions 16–18 specifically audit consistency between documentation and code. Audit execution model: Phase 1 iterative deep dig (up to 10 rounds per dimension, independent sub-agent each round), Phase 2 independent re-verification (independent sub-agent returns to live code to re-confirm every finding).

Open-ended Adversarial Review (open-ended-adversarial-review-prompt.md) does not preset check dimensions, encouraging leapfrog exploration and self-negation, looping until no new findings emerge.

AGE adds directional audit: whether the owner doc matches the code, whether naming matches the glossary, whether the same concept is implemented consistently across packages. Deep-audit execution costs are extremely high (multiple rounds of independent sub-agents) — a trade-off that must be weighed.

7. Summary of Tool Comparison Between the Two

Dimension	Trellis	AGE (nop-chaos-flux / nop-entropy)
tool origin	framework preset, available on install	reverse-extracted from historical trajectory
new project startup cost	`trellis init` gives full toolset	AGE Template has only generic tools, but can reference open exemplars (nop-chaos-flux, nop-entropy) to quickly build domain-specific tools
tool evolution mechanism	`trellis update` (framework upgrade)	promotion ladder (bug → lesson → prompt → script → lint)
knowledge extraction from failures	yes (break-loop 5-dimension analysis → spec prose)	yes (promotion ladder → gradually automated tools)
knowledge artifact automation	prose only	prose → semi-automated scanning → fully automated interception
multi-platform adaptation	core capability (14+ platforms)	not a focus; depends on the host project’s CI
process automation	core capability (state machine, hooks, sub-agents)	limited (plan closure check scripts, pre-commit hook)
tool maintenance cost	low (framework maintains uniformly)	high (each tool needs whitelist and rule updates as the project evolves)
normative/historical separation	not separated (history precipitated into spec)	strictly separated (owner doc contains only current state)
plan system	PRD requirement description	closure contract (draft review + closure audit)
code quality gates	yes (Phase 2.2/3.1: lint+typecheck+test)	yes (plan guide Rule 13: hard gates non-negotiable)
post-mortem analysis	yes (break-loop 5-dimension bug post-mortem)	yes (bug note → lesson → skill promotion)
directional audit	none	yes (deep-audit 20 dimensions including document-code consistency)

8. Common Limitations: Trellis and OpenSpec Are Both Task-Level Tools

Trellis and OpenSpec have three structural deficiencies.

Deficiency One: No Repository-Wide Truth

The core organizational unit for Trellis and OpenSpec is the single change (a task / a change), not the repository as a whole.

Trellis: each task has its own prd.md; spec/ is a stack of coding conventions. There is no maintenance point for "what the system as a whole currently is and what it should converge to."
OpenSpec: specs/ claims to be source of truth, but it is an accumulation of requirements (each archive merges deltas, only adding, never removing), not a direction definition. The accumulated specs are a requirements list, not an architectural attractor.

AGE’s owner doc maintains the overall direction: which modules must be separated, the single direction that dependencies may flow, what concepts must not be mixed together.

AGE’s first-principles-of-agent-engineering.md distinguishes two sources of truth: four-dimensional truth (facts, causal source, confidence state, negative space) answers "what is and what was," while the attractor answers "what it should converge to." Trellis and OpenSpec do not distinguish these two sources — they only have "current specifications" (specs/spec), not "direction definition" (attractor).

Deficiency Two: No Trajectory Between Single Changes

Trellis: tasks are archived upon completion; journal rotates after 2000 lines. The next task cannot see what the previous task did, why those decisions were made, or what was rejected.
OpenSpec: changes are archived and kept in archive/, but they are only historical folders. There are no structured trajectory records (code paths, verification baselines, owner doc sync status). The next change does not learn from the execution process of the previous one.

AGE’s logs/ are mandatory trajectory: precise to code paths, focused proofs, owner doc sync, and verification baselines. bugs/ records negative space (which paths are excluded, which assumptions were falsified). Future sessions can recover from the trajectory "what happened up to yesterday."

This difference stems from the organizational unit: task-level tools care about "is this change correct," while a repository-level methodology cares about "after multiple consecutive AI changes, is the repository still heading in the right direction."

Deficiency Three: No Support Point for Evolving Toward Full AI Automation

Trellis: humans participate in PRD collaboration and commit confirmation; the 3-phase flow is designed for humans. There is no independent closure audit; humans do the final check.
OpenSpec: /opsx:propose and /opsx:verify both assume a human is in the loop. verify is optional, with no independent verification. tasks.md is a human-readable checklist.

AGE’s plan has draft review and closure audit completed by independent AI sub-agents; humans gradually withdraw. The plan is a closure contract, not a task list for humans. The attractor defines "converge to where," and the audit checks "are we converging" — neither requires human intervention.

AGE’s age-from-state-engineering-to-trajectory-engineering.md puts it directly: the basic structure of traditional software engineering is "state checks + human implicit direction sense." After deep AI participation, the human brain no longer holds the complete blueprint; the "direction sense" must be externalized into the repository structure. Trellis and OpenSpec both still rely on human implicit direction sense — they make single AI-human collaborations more reliable, but they do not replace human judgment of direction.

The Relative Progress of Trellis and OpenSpec

Each has progressed relative to the other, but both still circle within the task-level framework.

Trellis’s progress over OpenSpec:

Knowledge write-back from failure to spec: trellis-break-loop (5-dimension bug analysis) → trellis-update-spec (mandatory spec file update). OpenSpec’s /opsx:archive only merges delta specs (requirement changes), and does not write back failure lessons — learned lessons stay in the archive folder and do not flow back into the specs.
Complete execution pipeline: sub-agent dispatch (trellis-implement/trellis-check), jsonl context injection, rollback. OpenSpec only has an artifact dependency graph (proposal → specs → design → tasks), with no execution flow management — /opsx:apply relies on the AI to find and read specs on its own.
Structured bug analysis: the 5-dimension analysis framework of trellis-break-loop (Root Cause Category / Why Fixes Failed / Prevention / Systematic Expansion / Knowledge Capture). OpenSpec has no equivalent.

OpenSpec’s progress over Trellis:

Enforced spec validation: openspec validate parses Markdown with a Zod schema, mandating a Purpose section, Requirements section, at least one Scenario per Requirement, ADDED/MODIFIED must contain SHALL/MUST, and no cross-section conflicts. Trellis’s spec files are completely free Markdown with no structural validation.
Delta mechanism: ADDED/MODIFIED/REMOVED incremental descriptions + merge on archive. More structured than Trellis’s "stuff all knowledge into spec files."
Spec/Change separation: specs/ (source of truth) and changes/ (incremental modification) are kept separate. A step beyond Trellis’s non-distinction between specifications and proposals.

The spec format of OpenSpec has a fundamental limitation: the Given/When/Then Scenario is a format meant for machine verification (can be automatically converted into test cases), not a direction definition for humans to read. AGE’s owner doc is an architectural direction for humans to read ("modules must be separated," "dependencies can only flow in one direction"); the audiences of the two are different.

Three-Way Comparison Table

AGE Dimension	AGE	OpenSpec	Trellis
organizational unit	repository as a whole (attractor + trajectory)	single change (change)	single change (task)
nature of spec	direction definition ("what it should converge to")	behavioral description ("current behavior")	coding conventions ("how to write code")
between changes	trajectory records (logs + bugs + plans)	archive folder (archive/)	archive + rotating journal
negative space	bugs/ (excluded paths)	none	none
closure verification	independent AI sub-agent closure audit	optional /opsx:verify (self-check)	Acceptance Criteria (self-check)
full AI automation	conceptually supported (plan = contract, not designed for humans)	not considered (flow assumes human in the loop)	not considered (3-phase flow designed for humans)
spec validation	none (owner doc freely organized by domain)	enforced (Zod schema + `openspec validate`)	none (free Markdown)
knowledge promotion	bug → lesson → skill → script → lint	none (no progression after archive)	none (break-loop output goes into spec and stops there)

9. The Co-Evolution of Theory and Practice

The thought of dynamical systems (state space → attractor → trajectory → control) was the earliest conceptual framework established by AGE. But the specific implementation — what structure the owner doc uses, how closure audits are done, how the promotion ladder is designed — has been continuously adjusted in practice.

The evolutionary history of nop-chaos-flux:

Attractor carrier evolved from flat architecture documents to a 4-layer priority system — solidified only after multiple audits revealed priority conflicts.
Closure audit evolved from manual checking to mandatory independent sub-agent verification — established after Plan 143’s closure hypothesis was repeatedly overturned.
The promotion ladder was not designed at the beginning; it gradually formed after discovering that "prose-only lessons cannot prevent the same error from recurring."
Open-ended adversarial review emerged because the fixed dimensions of deep-audit sometimes missed problems outside those dimensions.

What specific document structures carry attractors, what mechanisms check deviation — guided by the dynamical systems thought, they are continuously calibrated and refined through practice.

Trellis comes from practical observations ("what practices work in AI engineering"); the 5 core principles are empirical summaries. There is no derivation chain from theory to practice; expansion relies on stacking experiences.

Conclusion

Core finding: Trellis and OpenSpec both use the single change as the organizational unit, while AGE uses the overall repository trajectory as the organizational unit. The former cares about "is this change correct"; the latter cares about "after multiple consecutive AI changes, is the repository still heading in the right direction."

Specifically, the three diverge fundamentally in eight dimensions:

Organizational unit: Trellis and OpenSpec are task-level tools (a task / a change); AGE is a trajectory-level methodology (repository as a whole). This is the most fundamental difference, and all the following divergences derive from it.
Where tools come from: Trellis’s 12 skills and OpenSpec’s slash commands are preset at framework design time, available out-of-the-box for new projects; AGE’s tools are reverse-extracted from historical trajectories, new projects start from the Template’s generic tools, but can accelerate by referencing open-source exemplars such as nop-chaos-flux, nop-entropy, and nop-chaos-next. They cater to different stage needs.
Depth of knowledge extraction from failures: All three learn from failures. Trellis’s trellis-break-loop offers 5-dimension analysis; OpenSpec has an archive to retain change history; knowledge is precipitated as prose. AGE’s promotion ladder elevates the same pattern step by step into automated tools. The difference lies in the automation level of the artifacts.
Nature of spec: OpenSpec’s specs are structured behavioral contracts (Requirement + Scenario), closer to "executable contracts" than Trellis’s coding conventions. But neither distinguishes "current behavior" from "what it should converge to." AGE’s owner doc is a direction definition, not a requirements description.
Continuity between single changes: Trellis (task archive + journal rotation) and OpenSpec (archive folder) both lack structured trajectory records. AGE’s logs are precise to code paths and verification baselines; bugs record negative space.
Support for evolving toward full AI automation: Trellis and OpenSpec’s processes both assume a human in the loop. AGE’s plan is a closure contract; draft review and closure audit are completed by independent AI sub-agents, and humans gradually withdraw.
Audit layers: All three have code quality gates. AGE adds directional audit (deep-audit 20 dimensions including document-code consistency), checking "whether the system is converging in the right direction," but at an extremely high execution cost.
Theory generation vs. experience stacking: AGE starts from dynamical systems thinking; practical elements can be deduced from the theory. Trellis and OpenSpec come from practical observations; expansion relies on experience stacking.

References

AGE Methodology:

AGE Template: https://github.com/entropy-cloud/attractor-guided-engineering-template
~/app/attractor-guided-engineering-template/AGENTS.md — Rule 15: Tool promotion rules
~/app/attractor-guided-engineering-template/docs/articles/attractor-before-harness-ai-large-scale-development-methodology.md — Attractor Before Harness

nop-chaos-flux (AGE instance):

GitHub: https://github.com/entropy-cloud/nop-chaos-flux
Gitee: https://gitee.com/canonical-entropy/nop-chaos-flux
docs/skills/README.md — index of 22 skills/prompts
docs/skills/deep-audit-prompts.md — 2141 lines, 20-dimension deep audit framework
docs/skills/open-ended-adversarial-review-prompt.md — open-ended adversarial review
docs/skills/bug-diagnosis-prompt.md — diagnostic methodology extracted from 66+ bugs
docs/plans/00-plan-authoring-and-execution-guide.md — 403 lines, 24 minimal rules
scripts/audit/ — 15 files (including 11 scanners + rules/shared modules)
docs/bugs/ — 66 bug fix histories
docs/articles/first-principles-of-agent-engineering.md — 276 lines, fundamental principles of agent engineering
docs/articles/age-from-state-engineering-to-trajectory-engineering.md — From State Engineering to Trajectory Engineering

nop-entropy (AGE instance):

GitHub: https://github.com/entropy-cloud/nop-entropy
Gitee: https://gitee.com/canonical-entropy/nop-entropy
ai-dev/tools/rules/ — 3 ast-grep Java lint rules
docs-for-ai/INDEX.md — index of normative usage documentation

nop-chaos-next (AGE instance):

Gitee: https://gitee.com/canonical-entropy/nop-chaos-next
Application-layer AGE practice: design/, input/, logs/, bugs, skills/ lightweight pattern

Completion Semantics vs. Context Preservation: The Design Divergence Between AGE Plan and Planning-with-Files

canonical — Fri, 31 Jul 2026 23:15:56 +0000

Planning-with-Files is a popular Claude Code plugin that supplements Claude Code with a more powerful planning system. This article compares its approach with the Plan concept in the AGE (Attractor-Guided Engineering) system at two levels.

Specification Layer (Plan System)

AGE Plan — The plan governance system of Attractor-Guided Engineering, defined by the 24 Minimum Rules in docs/plans/00-plan-authoring-and-execution-guide.md. A pure text specification with no dependency on a specific toolchain.
Planning-with-Files (PwF) — OthmanAdi/planning-with-files, a universal AI agent skill plugin originating from Manus's context engineering philosophy. Three-file structure + state model + hooks.

Automation Layer (Execution Engine)

AGE Goal Driver — An independent process state machine in nop-entropy/ai-dev/tools/opencode-goal-driver/ that engineers the textual rules of the AGE Plan into executable code. The AGE Goal Driver is an optional execution mechanism for the AGE Plan.

AGE Plan governs whether completion is genuine; PwF governs whether context is still present. One prevents the false completion of plans, the other prevents the agent from losing its goals. This divergence determines all subsequent mechanism differences.

1. Design Orientation

Specification Layer: AGE Plan vs PwF

Dimension	AGE Plan	PwF
Core Concern	Whether completion is genuine	Whether context is still present
Attitude toward agent	Distrusts completion judgment; requires independent audit review	Not worried about completion judgment; worried about forgetting
Trust Boundary	Trusts agent not to maliciously alter files; does not trust agent not to self-deceive	Does not trust that plan files won't be tampered with; locks with SHA-256
Completion Judgment	Closure Gates + Exit Criteria + independent closure audit	`check-complete.sh` counts phase status occurrences
Plan States	9 states: `proposed \	planned \
Governance Tools	Anti-Slacking Rule, Non-Degradable Items, Failure Paths, Test Strategy tiering	2-Action Rule, 3-Strike Error Protocol, 5-Question Reboot Test
Security Model	None (trusts agent and file system)	Two-layer defense: delimiter framing + hash attestation
Parallel Tasks	Multiple plan files coexist in {% raw %}`docs/plans/`, no isolation	`.planning/<slug>/` directory isolation + `PLAN_ID` env var
Scope of Application	Complex, long-maintenance projects	Any project, 17+ IDEs/platforms

Automation Layer: AGE Goal Driver vs PwF hooks/loop

2. Unique Features of AGE Plan (Specification Layer)

All 24 Minimum Rules of the AGE Plan originate from seven categories of errors encountered in execution history. Each rule is a patch added because an agent had at some point self-deceptively marked something as "completed." This section only describes the requirements at the AGE Plan specification layer — these rules do not depend on the AGE Goal Driver and are equally effective when followed manually. The automation implementation of AGE Goal Driver is left to Section 4.

2.1 Closure Gates — A Final Inspection Layer Independent of Phase Exit Criteria

Closure Gates are a plan-level final inspection checklist, forming a separate verification layer from the Exit Criteria within each Phase. Their items are not a task list, but anti-self-deception judgments:

"No in-scope live defect has been silently downgraded to deferred / follow-up"
"Independent sub-agent closure audit completed and evidence recorded"
"All in-scope confirmed contract drifts have been converged"
pnpm typecheck && pnpm build && pnpm lint && pnpm test

PwF's check-complete.sh performs syntactic checks: it counts whether the occurrences of **Status:** complete (and the [complete] fallback format) equal the occurrences of ### Phase. PwF deliberately chooses not to perform semantic audits — its goal is cross-platform universality across 17+ platforms, and semantic auditing requires understanding project-specific completion criteria, which is difficult to templatize. The cost, however, is that it cannot differentiate between "the phase status was written as complete" and "the defect was truly fixed, the contract truly aligned." Closure Gates handle the latter.

AGE Goal Driver Automation: check-plan-checklist.mjs automates the Closure Gates check — scanning all plan files, checking whether completed-status plans have unchecked checklists, whether Closure Evidence exists, and whether all Closure Gates are checked. It distinguishes between a hard fail (completed but has unchecked items) and a warning (non-completed but has unchecked items).

2.2 Independent Closure Audit — Implementers Cannot Self-Audit

A necessary condition for marking a plan as completed: an independent reviewer or an independently launched fresh sub-agent session must perform a closure audit. Implementers cannot close their own plans.

Verification requires not just checking that interfaces exist, but that behavioral semantics are realized: newly added components are invoked at runtime (not just imports present), no empty method bodies/silent skipping.

PwF's Stop hook only checks phase status counts, without distinguishing "who performed the audit."

2.3 Anti-Slacking Rule — No Vague Words to Substitute Status Adjudication

Every in-scope item must fall into, and only into, one of four definitive states before plan closure: landed, adjudicated as residual-risk-only, moved to explicit successor ownership, removed from scope through a recorded scope change.

Using optional, if time permits, consider, maybe, nice to have to substitute status adjudication is prohibited.

Each deferred item in ## Deferred But Adjudicated must carry three fields: Classification (only watch-only residual | optimization candidate | out-of-scope improvement), Why Not Blocking Closure (explicit reason), Successor Required (yes/no). Deferred items without a reason are treated as incomplete.

PwF states are only pending → in_progress → complete, with no intermediate state for "deferred but adjudicated."

2.4 Non-Degradable Items + Test Strategy + Failure Paths

These three rules together form the "non-degradable" boundary of the AGE Plan:

Non-Degradable Items. Five categories of items cannot be placed into deferred / non-blocking: lint rules, live defects, public-contract drift, owner-doc drift, necessary focused verification. Each execution item must be tagged as one of Fix | Decision | Proof | Follow-up. Confirmed live defects can only be Fix, not downgraded to Follow-up.

Test Strategy Tiering. Every plan must declare a risk-matched test investment strategy: Auth and external API contracts must be automated (Proof items before Fix); general features are recommended to have tests; pure documentation with no behavioral changes may declare not applicable with justification.

Failure Paths. The template provides a ## Failure Paths table — recommended for plans involving error handling, API contracts, authentication, or external integration. Each row contains trigger conditions, expected behavior (including status codes), retryability, and user-visible performance. This forces plan authors to consider unhappy paths alongside happy paths.

PwF's error handling is limited to the 3-Strike Error Protocol (retry escalation) and the Errors Encountered table (post-hoc recording), without an upfront specification of exception paths.

2.5 Current Baseline + Documentation Adjudication Embedded in Phases

Before writing a plan, one must first verify the current state of the live repo, listing item by item "established facts", "facts that have been completed but old documentation hasn't synchronized", and "the real remaining gaps." The Goal is not the Baseline — Goal is where you are going, Baseline is where you currently are.

Each Phase's Exit Criteria includes: "If this Phase changes the live baseline, the relevant docs/architecture/ has been updated; otherwise, explicitly state No owner-doc update required." Documentation synchronization is work within the Phase, not wrap-up work.

AGE Goal Driver Automation: detectStartPhase automatically determines where to continue at startup — running check-plan-status.mjs to check for incomplete plans, checking if an audit directory exists; if there are incomplete plans, jump to execution; if an audit directory exists, jump to planning; if neither, start from auditing. Pure script logic, no LLM calls.

2.6 Historical Plan Protection + Anti-Excessive Splitting

Rule 20 (Historical Protection): Historical plans already marked completed are by default treated as historical records and are not actively rewritten due to specification evolution, template changes, or code evolution.
Rules 21-24 (Anti-Excessive Splitting): Do not split a plan just because there are many findings or the file is nearing 30 KB. Multiple findings that fall within the same component, the same module, or the same owner-doc should preferably be merged into one owner plan. Splitting is triggered only when closure semantics diverge.

3. Unique Features of PwF (Specification + Automation Layer)

PwF's core concern is singular: preventing the agent from losing context during long tasks.

3.1 Three-File Separation + Security Isolation

task_plan.md (roadmap) + findings.md (knowledge base) + progress.md (session log). The three files have clear responsibilities and update frequencies:

File	Nature	Read/Write Frequency
`task_plan.md`	Roadmap and decision record	At each phase completion
`findings.md`	Research findings and external content	Every 2 search operations
`progress.md`	Timeline log and test results	Continuously updated, data source for session catchup

The existence of findings.md is more than just a notebook — its design carries security considerations. task_plan.md is automatically injected into the agent's context by hooks at every tool call. If external web search results were written into task_plan.md, adversarial instructions within them would be amplified into every tool call. The SKILL.md Security Boundary explicitly mandates: external content can only be written to findings.md, not to task_plan.md.

The AGE Plan does not manage research findings and external content within the plan system — these materials generated during execution are stored by the agent in appropriate locations based on actual circumstances and are not included within plan files.

3.2 Hook Auto-Injection System

Five types of hooks execute automatically during the IDE lifecycle, eliminating the need for the agent to consciously follow rules:

Hook	Triggered When	Action
UserPromptSubmit	Each time the user sends a message	Injects plan content into context
PreToolUse	Before each Write/Edit/Bash/Read/Glob/Grep	Re-reads plan to refresh attention
PostToolUse	After each Write/Edit	Reminds to update progress
Stop	When agent attempts to stop	Checks whether all phases are complete
PreCompact	Before context compaction	Reminds to flush progress + prints Plan-SHA256 (if attestation exists)

The AGE Plan's rule layer has no automatic injection mechanism and relies on the agent following AGENTS.md. The AGE Goal Driver also does not inject plan content but uses an XML tag protocol for programmatic output parsing. PwF represents a third path: using hooks to automatically stuff the plan into the context without the agent's knowledge.

3.3 Two-Layer Security Defense

First layer (enabled by default): delimiter framing. Hook-injected plan content is wrapped in ===BEGIN PLAN DATA=== / ===END PLAN DATA===, marked as structured data, with the agent instructed not to execute imperative text within.

Second layer (opt-in): SHA-256 attestation. /plan-attest computes and stores the hash of task_plan.md. All hooks compare the hash before injection; if mismatched, they refuse injection and output [PLAN TAMPERED]. The PreCompact hook also prints Plan-SHA256, ensuring the agent can still verify that the plan hasn't been tampered with after compaction.

The AGE Plan has no equivalent security mechanism because it trusts the agent and the file system.

3.4 Session Catchup — Automatic Session Recovery

session-catchup.py automatically extracts the conversation that occurred after the last planning file update from the IDE's session store after /clear or context reset and generates a catchup report.

The AGE Plan manually reconstructs context via docs/logs/ and has no automatic session recovery mechanism. The AGE Goal Driver's detectStartPhase determines where to continue by checking the repo state — it does not restore conversation history, only the execution position.

3.5 Parallel Task Isolation

PwF supports parallel multi-tasking: init-session.sh "task name" creates an isolated directory under .planning/YYYY-MM-DD-slug/, each with its own set of three files. set-active-plan.sh switches the active plan, and the PLAN_ID environment variable pins the terminal to a specific plan. Hooks automatically locate the correct plan via resolve-plan-dir.sh.

The AGE Plan has multiple plan files coexisting in docs/plans/ with no directory isolation or automatic switching mechanism.

3.6 Operational-Level Constraints

2-Action Rule: After every 2 search/browse operations, findings must be written to findings.md. Targeted at the volatility of multimodal content — images and browser results do not persist in context.

3-Strike Error Protocol: Attempt 1 diagnose and fix → Attempt 2 change approach (prohibiting repeating the same operation) → Attempt 3 rethink → after 3 failures, escalate to the user.

5-Question Reboot Test: If the agent can answer "Where am I, where am I going, what is the goal, what have I learned, what have I done," it indicates context integrity.

The AGE Plan has structured checks via Baseline and Exit Criteria, but no operation frequency constraints or quick self-tests.

3.7 Turn-Loop Integration

Integration with Claude Code's /loop and /goal combination: /plan-loop 10m auto-ticks every 10 minutes (re-reads plan, runs check-complete, writes progress); /plan-goal derives termination conditions from the plan. This is the looping mechanism of PwF's automation layer. The dual-loop state machine of the AGE Goal Driver is another automation approach, detailed in Section 4.

3.8 17+ IDE/Platform Support

One plan format adapts simultaneously to platforms including Claude Code, Cursor, Copilot, Gemini CLI, Kiro, Codex, Hermes, CodeBuddy, FactoryAI, Pi Agent, OpenCode, Continue, Mastra, OpenClaw, Antigravity, Kilocode, AdaL CLI, etc. The AGE Plan is used only in internal projects.

4. Relationship Between the Two (Specification Layer)

The AGE Plan and PwF are not in a composable relationship; they are two independent plan systems, each answering different questions.

The AGE Plan's plan system only governs the structure, execution, audit, and closure of the plan itself. Research findings and external content generated during execution do not belong to the plan system — the agent chooses a temporary directory to store them based on actual circumstances, organizing file links as needed. The AGE Plan does not prescribe the storage location for these materials, nor does it include them in plan files.

PwF's three-file structure (task_plan + findings + progress) is an integrated design, and the security isolation rationale for findings.md directly serves the hook injection mechanism — isolating external content from the injection surface. This design cannot be dismantled and partially grafted onto the AGE Plan.

The true intersection between the two is this: if the AGE Plan were to deeply integrate with some agent runtime in the future, it could emulate PwF's hook mechanism to strengthen enforcement at execution moments — for instance, automatically re-reading the plan before critical tool calls, or automatically reminding to update logs after phase completion. But this would not be "combining with PwF," but rather borrowing the hook mechanism concept to provide automatic enforcement guarantees for the AGE Plan's governance rules.

5. Automation Layer Comparison: AGE Goal Driver vs PwF hooks/loop

The AGE Goal Driver is not the AGE Plan itself but an optional automated implementation of the AGE Plan. It sits at the same level as PwF's hooks/loop — both are mechanisms that turn plan specifications into executable systems.

5.1 The Dual-Loop State Machine of AGE Goal Driver

Outer Loop (Audit-Driven):
  Health Check → Deep Audit + Adversarial Review → Issues?
    ├─ No → DONE
    └─ Yes → Draft Plan
        ↓
      Inner Loop (Execution-Driven):
        Execute Plan → Independent Closure Audit (independent process)
          ├─ complete → break
          └─ incomplete → Extract REMAINING XML → Continue Execution
        ↓
      Build Verification → Return to Outer (re-audit)

The outer loop ensures that even if all checkboxes of the current plan are checked, an independent audit must still confirm that no new issues have been introduced. The inner loop ensures that after execution, independent verification must be passed; the executor cannot self-declare completion.

Each step's prompt requires the AI to output XML tags like <AUDIT_RESULT>clean|issues</AUDIT_RESULT>, and the extractTag function parses these tags to drive the state machine. When the AI does not output a tag, extractTagOrAsk spawns an additional AI call to infer the missing tag — a self-healing parsing layer. The entire state machine does not rely on humans reading markdown to make judgments; instead, it parses tags programmatically for automatic state transitions.

5.2 Process Isolation

Each step spawns an independent opencode process — deep-audit, adversarial-review, plan, execute, closure-audit are each isolated. The execution agent and the audit agent are inherently different processes, physically isolated rather than constrained by rules.

The closure audit is performed by a completely independent opencode process with no information from the execution phase in its context; it must re-examine each Exit Criteria from the live repo. If the verification result is incomplete, it extracts the specific incomplete items from the <REMAINING> XML block and injects them into the prompt for the next round of execution.

When a subprocess log exceeds a configurable stall threshold without updates, an independent watchdog agent is spawned, allowing it to diagnose the process state itself, read the tail of logs, and decide whether to kill the stuck process. The main driver does not make the kill decision.

5.3 Comparison with PwF Automation Layer

Dimension	AGE Goal Driver	PwF hooks/loop
Operation Mode	Node.js independent process, no IDE primitive dependency	Depends on IDE hook system (5 hook types)
Loop Model	Dual-loop (Outer Audit + Inner Execution)	Single-layer tick-driven (`/plan-loop`)
Process Isolation	Independent process per step, physical isolation of audit and execution	Hook calls within a single process, no process isolation
Output Protocol	XML tags (`extractTag` programmatic parsing)	No structured output protocol, relies on markdown status markers
Resume from Breakpoint	`detectStartPhase` checks repo state	`session-catchup.py` restores conversation history
Platform Dependency	Requires Node.js runtime	17+ IDEs/platforms, plug-and-play

6. Which Direction is More Enduring

The core problem PwF solves is insufficient agent context. The 2-Action Rule, session catchup, and hook auto-injection all exist because models cannot remember or read everything. This problem will gradually diminish as context windows expand and model long-context capabilities strengthen. Most of PwF's mechanisms will sediment into agent runtime infrastructure capabilities, without users needing to explicitly install a skill to solve them. PwF's security model (delimiter framing, attestation, findings isolation), however, is independent of model capabilities — no matter how strong the model, the vector of injection attacks will always exist. But that is security engineering, not a plan system.

The problem the AGE Plan solves will not disappear as models become stronger. "Was the defect truly fixed?" is not a memory problem but a problem of completion semantics judgment. "This live defect was secretly downgraded to follow-up" is not that the agent forgot, but that the agent is self-deceiving. These are structural difficulties of complex engineering — scope management, contract alignment, consistency of documentation and code. The stronger the model, the faster and more changes occur, the more likely these problems become: a powerful agent can complete a complex refactoring within 50 tool calls, while quietly hiding a contract drift into follow-up on the 37th call. The 24 Minimum Rules govern not the agent's capability boundary, but the honesty of engineering judgment.

The true direction of evolution is the path represented by the AGE Goal Driver — turning governance rules from "hoping the agent complies" into "system-enforced mandates." The Plan Guide defines semantics, and the AGE Goal Driver ensures semantics land. If further deeply integrated with an agent runtime — automatically re-reading the plan before key tool calls, automatically triggering exit criteria checks after phase completion — it becomes a complete solution: rule semantics from the AGE Plan, enforcement from the AGE Goal Driver, and triggering timing from a hook mechanism. All three layers revolve around the governance semantics of the AGE Plan.

The Divide Between Control Layer and Direction Layer: OpenProse, Natural-Language Agent Harnesses, and Attractor-Guided Engineering

canonical — Fri, 31 Jul 2026 23:12:36 +0000

Related projects: OpenProse (@openprose/reactor), NLAHs (Natural-Language Agent Harnesses), AGE Template, nop-chaos-flux (a production-grade implementation of AGE)
AGE methodology series: Attractor Before Harness: A Methodology for Large-Scale AI Development, From Spec-Driven Development to AGE

Starting Point

OpenProse, Natural-Language Agent Harnesses (NLAHs), and Attractor-Guided Engineering (AGE) all try to solve the same problem: what do you do when the output of an AI agent is unreliable?

The first two provide answers at the control layer—OpenProse uses a deterministic runtime so that goals can be precisely maintained, and NLAHs use natural-language documents so that harness policies can be reviewed. AGE asks a question that precedes the control layer: what structure should the control maintain in the first place?

If the direction layer does not exist, better runtimes and clearer harnesses will only cause the overall structure to drift.

OpenProse starts from runtime abstraction—designing a contract language and execution engine that allows AI agents to maintain goals that “remain true” over time.

NLAHs start from the representation medium—externalizing agent harness policies from tangled controller code into editable natural-language documents, interpreted and executed by a shared runtime, the IHR.

AGE starts from the engineering process—designing a document-and-workflow system that causes a human–AI collaboration to converge continuously toward a stable structure.

OpenProse asks: how do you keep a goal invariant? NLAHs ask: how do you make a single agent run follow auditable policies? AGE asks: after the system has been pushed off course, why does it still return to the right direction?

Convention: In this article, “NLAHs” refers to the overall framework proposed in the paper (Natural-Language Agent Harnesses), “NLAH” refers to a single policy document, and “IHR” refers to the shared runtime (Intelligent Harness Runtime).

Fixed Point ≠ Attractor

The core abstractions of OpenProse and AGE correspond to two distinct mathematical objects.

Fixed Point: f(x) = x. When the system is placed at this point, it does not move. The judgment criterion is a strict equality. A fixed point can be stable (nearby points converge to it) or unstable (nearby points move away). The concept of a fixed point does not imply the existence of a basin of attraction.

Attractor: A set (a point, a limit cycle, a strange attractor) such that all initial states in a surrounding region (the basin of attraction) evolve toward it over time. The key property is not “put it there and it stays,” but “start near it and you will be pulled back.” An attractor need not be a single point; it can be a manifold. The system does not need to reach it exactly—as long as the trajectory is within the basin and converging, that is enough.

OpenProse’s fingerprint comparison fingerprint == fingerprint is a fixed-point check: is the output the same as before? If so, it stands still.

AGE’s “system converges toward a stable structure” can be understood in terms of attractor criteria: the system need not reach an ideal state exactly; it is enough that the control mechanism continuously pulls it back toward the vicinity of a stable structure.

One is a state judgment—“has it arrived?” The other is a process judgment—“is the direction right?”

Control Target ≠ Attractor: An Ontological Distinction

Beyond the distinction in convergence mechanisms (fixed point vs. attractor), there is a deeper ontological difference: control target vs. attractor.

Control Target

Once a control framework has been established, a control target defines “where control should aim.” It assumes:

The control framework itself already exists.
The executor will act according to the instructions.
Deviations are corrected by re-executing the instructions.

A control target is an externally imposed specification that drives the executor to conform to it.

Mathematical Attractor

An attractor is generated by the system’s own dynamics—all initial states in the surrounding region converge toward it over time. The key properties:

It is emergent—defined by the system’s dynamics, not by externally imposed commands.
Perturb-and-recover—push it away, and the dynamics will pull it back.
The system does not need to “know” about it—water follows the Lorenz attractor without needing to know it exists.
It is a manifold defined by equations—it does not enumerate every correct state, only the constraint relationships.

An attractor provides a final cause for control. It exists prior to control, not within it.

Note: AGE’s attractor is only an analogy; it is not a naturally emergent mathematical object but an engineered semantic field: humans define structural constraints, and the workflow converts these constraints into a recovery dynamic that spans sessions. Its criterion is not “absence of external design,” but “whether the recovery after perturbation is driven by a persistent structural field rather than by one-off instructions.”

An Analogy

An operations manual tells workers how to assemble parts. The workers follow the manual, and when they deviate they correct by referring back to the manual. The manual is a control target—it requires the workers to “know” it and to actively execute it.

A gravity well is an attractor—no matter how you push an object, the object’s dynamics naturally pull it back. The object does not need to “know” the gravity well exists.

The Invariants of OpenProse and NLAHs Are Both Control Targets

OpenProse’s Responsibility (Goal/Maintains/Continuity) is an externally defined specification. The runtime detects deviations via fingerprint comparison and re-renders when a deviation occurs. This is a control target plus deterministic execution. Convergence relies on the runtime forcibly re-executing the specification.

NLAHs’ harness pattern (contract + stages + state / validation / recovery / stopping rules) tells the IHR how to organize a single task run. The IHR is not a hard-coded controller but uses runtime policies to interpret the NLAH, translating the clauses into child-agent calls, state updates, validation gates, and artifact contracts. If an agent deviates, what acts are control targets such as validation / recovery / stopping rules, not a natural convergence of system dynamics. “Behavior is flexible but still policy-guided” is not attractor semantics; it is flexible execution under runtime semantic constraints.

AGE’s Owner-Doc System Possesses Attractor-Like Properties by Analogy

Perturb-and-recover dynamics: AI changes code (perturbation) → test/audit discovers a deviation → correction → the system returns to the vicinity of the structure. The cross-session perturbation–detection–correction cycle constitutes a convergence dynamic.
Implicitly defined manifold: docs/architecture/ does not enumerate every correct state; it defines constraint equations. The states that satisfy the constraints form a manifold—local implementations can vary, but the whole is pulled toward the same class of structure.
Cross-session emergence: The long-term convergence produced by hundreds of commits, dozens of plans, and multiple audits is a “system behavior,” not the behavior of a single execution.

AGE’s recovery likewise depends on documents as a source of truth. The difference is not merely granularity and time scale but what is being constrained: control-layer instructions constrain how a single execution is completed; the direction layer constrains the structural region into which the results of all future executions are allowed to fall.

Structural Parallels at the Mechanism Layer

The three systems exhibit structural parallels at the mechanism layer:

	OpenProse	NLAHs	AGE
Source of truth	Responsibility (Goal/Maintains)	NLAH (contract + run rules)	Owner docs (`docs/architecture/`)
Interpreter	OpenProse reactor	IHR runtime	AI agent reads documents
Execution unit	render	task run	plan (for major changes)
Detection	fingerprint comparison	validation gates	CI + audit
Closure condition	postcondition + receipt	completion gates + artifacts	Closure Gates + independent closure audit
Correction	re-render	retry / recovery / honest stop	fix code, re-read documents

The mechanism slots are similar, but the semantics differ. This table only illustrates that all three are control systems, not that they control the same kind of object. OpenProse and NLAHs make a single execution more controllable; AGE judges whether the accumulation of those executions still points toward the same long-term structure.

The difference lies not at the mechanism layer but in whether a direction layer exists above it. OpenProse’s Responsibility and NLAHs’ NLAH are both self-contained specifications—they define their own completion conditions (fingerprint equality / contract satisfaction) without requiring external reference to “what structure the system should converge toward.” AGE also has completion conditions (CI gates, audit passing), but the irreplaceable role of owner docs is: when a local completion condition conflicts with the long-term structural direction, they provide the adjudication basis. CI can determine whether a particular import passes; owner-doc determines why flux-react must not have a reverse dependency on the renderer package. The former is a control gate; the latter is the direction layer.

This is precisely the distinction between the direction layer and the control layer: it is not a difference of mechanism, but whether there exists above the control an independent, persistent target structure that provides the final cause for all control.

The Ontological Positions of the Three

The relationship among the three is not a hierarchical one (project-level attractor ⊃ run-level attractor), but an ontological difference:

Direction layer (Attractor) — AGE: the long-term convergence structure defined by owner-doc
  ↑ provides final cause for control
  │
Control layer (Control Target) — NLAHs/OpenProse: specification + runtime execution
  ↑ implements the control mechanism
  │
Mechanism layer (Mechanism) — IHR / reactor / CI: concrete detection, execution, recovery

The core thesis of the AGE article is precisely this: the direction layer precedes the control layer. Without defining “where to converge,” control mechanisms have no unified meaning. Both NLAHs and OpenProse innovate at the control layer—NLAHs use NL to improve the auditability and portability of policies, while OpenProse uses a deterministic runtime to improve the precision and cost efficiency of execution. But neither can answer the direction-layer question: Toward what structure should the system converge over the long term? A falsifiable formulation would be: if, after removing AGE’s owner-doc priority chain, logs, and bug distillation, the system can still maintain the same architectural direction during long-term refactoring, then AGE’s direction-layer claim is superfluous.

The Underlying Assumptions of the Three Systems

OpenProse: Sessions Will Eventually End, Responsibilities Should Not Disappear with Them

OpenProse’s core metaphor comes from React. It models every execution of an AI agent as a render.

Three key assumptions:

The value of AI lies in bounded render—finite, auditable, single-shot reasoning.
The source of continuity is not the session, but the persistent state of the world-model and the receipt chain.
Cost is proportional to “surprise,” not to time—if nothing changes, the render does not execute.

This is a runtime-first worldview: first define “what remains true at runtime,” then consider the engineering process.

NLAHs: Policies Should Not Be Buried in Code

The core metaphor of NLAHs (Natural-Language Agent Harnesses) comes from editable policy documents. The NLAH+IHR system splits the agent harness into a four-layer stack.

Three key assumptions:

Harness policies can be separated from tangled controller code and expressed in editable natural language.
NL carries the policy, code carries the mechanism—precise operations stay in code, auditable policies stay in NL.
A shared runtime (IHR) can provide a unified execution substrate for different NLAHs.

This is a representation-first worldview: the representation medium of a policy determines its auditability, portability, and analyzability.

AGE: First Define Where the System Should Return, Then Discuss How to Get Back

AGE’s core metaphor comes from dynamical systems theory.

Three key assumptions:

AI is a perturbation source structurally different from humans—high frequency, high amplitude, and lacking a sustained sense of direction.
The attractor must exist before the harness—"where to correct toward" precedes "how to correct."
Documents are the carrier of the attractor, code is an instantaneous projection of the attractor—neither is the attractor itself.

This is a process-first worldview: first define “toward what structure the system should converge,” then design the runtime behavior.

Summary of Divergences

Dimension	OpenProse	NLAHs	AGE
Core question	How to make AI continuously maintain a goal that is true?	How to externalize harness policies as auditable NL?	How to make the system continuously converge toward a stable structure under high-frequency AI perturbations?
Problem domain	The lifecycle of a single responsibility	The harness policy of a single task run	The evolutionary trajectory of an entire repository
Time scale	Single render (minutes) to continuous serve (days)	Single task run (minutes to hours)	Single commit (minutes) to project evolution (months/years)
Nature of invariant	Control target (specification + fixed point)	Control target (specification + soft constraints)	Engineered direction field (engineered attractor-like structure)
Stability concept	Fixed point—fingerprint equality means no change	Policy conformance—conforming to the policy is correct	Attractor—within the basin means converging
Meaning of "correct"	Output matches expectation precisely (binary)	Execution path follows the policy specified by NLAH	The system is moving in the direction of convergence (directional)
Control mechanism	Deterministic fingerprint comparison (zero LLM)	IHR interprets NL policy (relies on LLM)	Perturb-recover dynamics (test → audit → fix)
Policy enforcement	Enforced by runtime	Runtime + NL guidance	Induced by institutionalized process, not enforced by runtime

Core Abstraction Comparison

Smallest Primitives

OpenProse’s Responsibility is a self-contained computational unit with explicit input boundaries (Requires), output boundaries (Maintains), a goal (Goal), and a continuity constraint (Continuity). Execution produces a receipt—a content-addressed, chain-verifiable proof of decision.

NLAHs’ NLAH document is an editable policy description that defines the lifecycle policy of a task run: contract, stages, roles, state rules, verification rules, recovery rules, and stopping conditions. A NLAH does not “tell the model how to answer”; it “tells the runtime how to organize a multi-step execution.”

The IHR’s execution semantics do not compile the NLAH into code, nor does it let an agent act freely after reading the document. It uses a fixed runtime-policy prompt to turn the base agent into a parent orchestrator: the parent reads the NLAH and translates the contract, stages, state rules, validation rules, recovery rules, and stopping conditions into child-agent task packets, handoffs, state files, artifact gates, and completion checks. The stages themselves are still executed intelligently by child agents; precise operations such as tests, parsers, validators, and benchmark adapters are handled by scripts/adapters.

AGE’s Attractor is not an object, but a structural property composed of three layers:

Structure layer: a small set of high-level invariants (e.g., the package dependency direction flux-core → ... → flux-renderers, the closure of seven primitives, the compile-first pipeline).
Carrier layer: auditable documents that carry these invariants (docs/architecture/).
Implementation layer: the parts of the current code that embody these invariants.

Both Responsibility and NLAH are instances—you can count “this project has 23 responsibilities” or “this benchmark has 1 NLAH.” An Attractor is a property—you cannot count “this project has 5 attractors”; it is more like “the attractor of this system is a low-dimensional manifold.”

All three systems have mechanisms for closing an AI action into a completable unit: OpenProse’s render, NLAHs’ task run, AGE’s plan. The closure of a render is determined by the input fingerprint, postcondition, and receipt; the closure of a task run is determined by the NLAH’s task contract, validation rules, artifact contracts, and stopping conditions; the closure of a plan is determined by Plan Status, Current Baseline, Goals, Non-Goals, the execution/proof checklist, Closure Gates, and an independent closure audit.

A plan is not a to-do list; it is an evidence structure for whether a major change can be closed: first verify the current baseline, constrain the goals and non-goals, prove each item during execution, and finally have an independent audit confirm that the in-scope items have been completed or honestly deferred. The relationship between a plan and the owner-doc is not “update the document every time.” Instead, the owner-doc is used to judge the boundaries and closure conditions of the current change; only when the change alters the live baseline, public contract, or owner behavior does closure require synchronizing the document.

NLAH and AGE plan are similar in mechanism: both use natural language to define the contract, stages, evidence, and stopping conditions, and both oppose relying solely on the agent’s self-reported completion. However, they close different things: NLAH closes a single run, proving that the execution trajectory satisfies the harness policy; plan closes a single change, proving that the results, evidence, and textual state of the current scope are sufficient to be accepted by an independent audit.

	NLAH	AGE plan
Target	The harness policy of a single agent run	The closure contract of a single major change
Execution structure	IHR parent orchestrator + child agents	Implementing agent / human executing according to the plan; independent reviewer or fresh subagent performs the closure audit
Evidence carrier	STATE_ROOT, artifacts, run logs	Plan checklist, proof, verification output, daily log
Stopping condition	Task contract, artifact contract, stopping conditions	Closure Gates, in-scope checklist, deferred adjudication, closure audit
Handling after failure	In-run retry / recovery / honest stop	Not closing, supplementing proof, changing status, extracting a non-blocking follow-up or new plan

State Model

	OpenProse	NLAHs	AGE
State representation	Content-addressed world-model (formal)	Filesystem state (STATE_ROOT + artifacts)	Code + docs + logs (informal)
Judgment mechanism	Deterministic fingerprint function (canonicalizer)	Validation gates + artifact contracts	CI commands + human review
History	Receipt ledger (chain-verifiable)	Artifact files + logs (within a single run)	Logs + Bug Notes + Git history
Stability semantics	Fixed-point detection (`hash == hash`)	Policy conformance (conforms to policy)	Attractor convergence (within the basin and direction correct)
Cross-session memory	Receipt chain (chain-verifiable)	None (filesystem state within a single run)	Present (logs, bugs, discussions, plans)

Technical Implementation Comparison

OpenProse is a strict two-phase architecture: at compile time it uses an LLM to produce deterministic artifacts (Forme DAG, canonicalizer, postcondition validators); at runtime it never calls an LLM—all decisions are deterministic. AGE has no “compile once then run” separation; verification is continuously embedded in every change—typecheck → build → lint → test → audit → logs, always verifying the direction. NLAHs sit in between: NL policy is separated from deterministic hooks, but the IHR runtime relies on an LLM to interpret the policy.

AGE explicitly identifies the self-verification trap: when an AI generates both the code and all the evaluation materials (types, tests, docs, completion summary) from the same context, if the understanding is biased, all the “verification evidence” will drift in the same direction. The countermeasure is to force a separation between generation and evaluation—a closure audit must be performed by a fresh context. OpenProse bypasses the same problem by freezing deterministic functions at compile time. NLAHs avoid it in the paper’s evaluation scenarios by relying on a benchmark autograder, but in production deployment they would likewise require an external verification mechanism to avoid the self-verification trap.

Understanding "Consistency"—Three Semantics

This is the deepest point of divergence among the three systems.

OpenProse’s fixed-point consistency: Each responsibility’s render produces a world-model; a canonicalizer derives a fingerprint. If the fingerprint is the same as before, the system is “consistent.” The judgment is binary: equal or not equal, there is no “roughly consistent.” At the composition level, if every responsibility is at its own fixed point and the DAG topology is correct, the entire system is consistent. Bottom-up, each local fixed point composes into a global fixed point.

NLAHs’ policy-conformance consistency: whether the agent’s execution path follows the policy specified by the NLAH. The paper defines metrics such as pattern-preservation, stage-coverage, and artifact-contract compliance to measure this. It is not binary—the NLAH allows flexible execution but requires that the policy structure (stages, roles, validation gates, state rules) be preserved. The paper’s RQ2 found that NLAH preserves recognizable workflow structure (workflow preservation 0.63–0.67, stage coverage 0.57–0.82), but information passing is a primary weakness (handoff recall as low as 0.32).

AGE’s attractor consistency: Not binary. A system can be “mostly near the attractor, but one subsystem has deviated”—this is not “inconsistent” but “within the basin yet off-center.” The judgment criterion is directional: is the system converging toward the attractor or moving away? A single commit can pass all tests (within the basin), but if it introduces an architectural drift (e.g., reversing the package dependency direction), the system’s trajectory is no longer converging toward the attractor. Top-down—even if every module’s tests pass (every local part is at a fixed point), the whole can still drift away from the attractor.

AGE’s original assertion: “All state-level checks can pass, yet the system as a whole is drifting.” Plan 76 of nop-chaos-flux is an example: an attempt to remove the local state mirror of array-editor produced 11 test failures—not because of a single bug, but because the tests themselves had drifted into a temporally coupled state with the old implementation. Every accumulated change had passed review and CI, but from the attractor’s perspective, the test suite had drifted away from a position capable of supporting structural evolution. This is precisely why the attractor concept exists.

This distinction is not a terminological preference:

Fixed-point methods can only detect “has it arrived exactly?”—they are very weak at distinguishing between “on the way toward convergence but not there yet” and “already deviated.”
Attractor methods naturally focus on the trajectory’s direction—the system does not need to arrive exactly; it only needs to be converging, and convergence itself is sustainable.
Fixed points work well in discrete state spaces (like the fingerprint of a world-model); attractors are more expressive in continuous state spaces (like the evolution of an architecture).
This directly explains why OpenProse uses hash == hash (discrete equality) and AGE uses “CI passes + docs consistency + architectural boundaries intact” (multi-dimensional convergence signals).

Three Dimensions

Positioning of AI. OpenProse models AI as a bounded render function; its role is executor. NLAHs model AI as an execution system organized by a harness policy: the parent orchestrator interprets the NLAH according to runtime policies, child agents execute concrete tasks—roles are differentiated into orchestrator + executor. AGE models AI as a high-frequency, high-amplitude perturbation lacking a sustained sense of direction; its role is perturbation source + executor—simultaneously constrained and utilized.

Understanding of Documents. OpenProse: *.prose.md is the program; if anything disagrees with the Markdown, the Markdown is correct. NLAHs: an NLAH document is a policy—it specifies “how to do” without directly “executing”; the most auditable parts are separated from implementation details. AGE: documents are the carrier layer of the attractor; code is an instantaneous projection of the attractor; the carrier layer defines where it should return.

Failure Handling. OpenProse: failure produces a failed receipt, immediate, individual, each render recorded independently. NLAHs: NLAH defines Recovery Rules (retry, rollback, evidence); failed artifacts are preserved for analysis but are not distilled across runs. AGE: failure produces a structured Bug Note; recurring failure patterns are distilled into guardrails and escalated along a progressive automation ladder (notes → checklists → heuristic scripts → lint rules → CI gates).

Empirical Evidence of Progressive Automation: The nop-chaos-flux Toolchain

A core thesis of the AGE methodology is: what can be turned into a deterministic check will gradually be extracted from trajectory data into deterministic scripts.

The toolchain of nop-chaos-flux provides complete empirical evidence for this claim. The observed 5-tier progressive automation ladder:

Tier 1: Trajectory capture (Bug Notes + Logs)
  62+ bug fix notes, 72 daily dev logs

Tier 2: Pattern distillation (Architecture Guardrails + Audit Rules)
  8 guardrails distilled from bugs, 19 dedicated audit rules

Tier 3: Codified review patterns (Skills/Prompts)
  24 reusable audit/review prompt templates

Tier 4: Heuristic suspicion scanners (Heuristic Scanners, exit 0)
  12 focused audit scanners, informational output

Tier 5: Hard-gate automation (Hard Gates, CI-blocking, exit 1 on failure)
  14 hard gate scripts, 30+ ESLint rules, dependency-cruiser, Semgrep, Husky pre-commit

Example A: Build Artifacts Polluting Source Directories

Tier 1 — Bug #23: Residual .js files in packages/*/src/ were silently overriding .ts source files during Vitest runs, causing test failures whose root cause was not in the test code. A total of 102 stale files were found.

Tier 2 — Guardrail #6 “No Build Artifacts In Source Directories” was distilled into docs/references/architecture-guardrails-from-bugs.md, with links to bug evidence.

Tier 5 — scripts/verify-no-src-artifacts.mjs became a hard gate (CI-blocking), while scripts/clean-src-artifacts.mjs provided cleanup capability. The pnpm lint chain runs clean + verify before ESLint.

From bug to CI gate, the full 5-tier ladder was traversed.

A Thought Experiment: Managing nop-chaos-flux with OpenProse or NLAHs

If the architectural invariants of nop-chaos-flux were modeled as OpenProse responsibilities, you would obtain precise runtime change detection, but you would not be able to answer why these invariants should be organized that way or how they should evolve. If plan execution were modeled as NLAHs, you would obtain structured execution workflows, but you could not answer whether, after 100 plans, the system is still converging. Both are control-layer tools; neither covers the direction layer.

AGE’s owner-doc system handles these questions. OpenProse’s responsibility contracts do not cover the direction layer. NLAHs’ policy documents do not cover the cross-session trajectory evolution. Both are excellent control-layer tools, but the attractor (direction layer) falls outside their problem domain.

Conclusion

OpenProse answers: “Given a goal that must continuously remain true, how can we use AI to maintain it efficiently, safely, and auditably?”—a micro-runtime problem.

NLAHs answer: “Given tangled controller code, how can we externalize reusable harness policies into NL documents that are auditable, portable, and amenable to ablation analysis?”—a representation-medium problem.

AGE answers: “Given a system that continuously evolves under AI perturbation, how can we ensure it does not drift away from a stable structure?”—a macro-process problem.

The three safeguard different formal/engineered stability semantics, and even different ontological layers. OpenProse trusts algorithms (deterministic functions, content addressing, chain verification) to maintain a fixed point; NLAHs trust auditable NL policies (IHR interpreting and executing, modules amenable to ablation) to maintain policy conformance; AGE trusts not a generic process but a process that is auditable, cumulative, adversarial-reviewable, and capable of sedimenting failure into future constraints. OpenProse and NLAHs innovate at the control layer; AGE contributes at the direction layer.

The real divergence lies in where failure accumulates: OpenProse localizes failure to a responsibility, NLAHs localize failure to a task run, AGE treats failure as a signal in a cross-session trajectory.

In the practice of nop-chaos-flux, AGE’s progressive automation ladder has already been validated: 62+ bug notes → 8 guardrails → 14 hard gates + 12 heuristic scanners + 30+ ESLint rules. Bug #23 (build artifact pollution) fully traversed the 5-tier distillation from bug note to CI-blocking hard gate. 72 log files record the system’s trajectory, 46 execution plans serve as local convergence mechanisms, and the priority chain of 58 architectural documents is the carrier layer of the attractor.

OpenProse can turn the local invariants that AGE has already made explicit into precise change detection. NLAHs can turn harnesses into objects amenable to ablation. Both are excellent control-layer tools; but the attractor (the direction layer) falls outside their problem domain. They can serve as control-layer executors; they cannot replace a direction-layer judge.

One could put it this way: if a project continuously passes CI, review, and harness contracts, yet after 50 AI-assisted changes exhibits package boundary reversals, semantic test coupling, and owner-doc conflicts, then the control layers of OpenProse/NLAHs have succeeded—and the problem that AGE is designed to address has only just become visible. That is the dividing line among the three: not who is more comprehensive, but who can see the long-term drift.

The control layer can tell AI how to correct an error; the direction layer determines what counts as an error in the first place.

Two Scales of Self-Evolution: Deep Structural Correspondence between RMSP Agent and AGE Methodology

canonical — Wed, 03 Jun 2026 06:23:46 +0000

Abstract: RMSP (Reward-Modulated Structural Plasticity) proposes a new paradigm in which an agent's behavioral topology self-evolves through use. AGE (Attractor-Guided Engineering) proposes a methodology that enables a software repository to continuously converge under high-frequency AI perturbations. These two are not competing approaches—RMSP adjusts an agent's internal structure (on the order of seconds), while AGE stabilizes repository-level invariant contracts (on the order of days). nop-chaos-flux is a complete implementation of AGE at the framework level. Its owner-doc system has undergone structural evolution in four directions—responsibility splitting (split), high-level abstraction (lift), removal of obsolete structures (prune), and cross-referencing (connect)—which correspond exactly to the structural self-organization driven by RMSP's six rewrite rules. This paper analyzes this cross-scale structural correspondence and discusses the complementary boundaries of the two.

Sources:

RMSP Paper — Self-Evolving LLM Agents as LLM + MAN: A New Agent Paradigm via Reward-Modulated Structural Plasticity, full text at mp.weixin.qq.com/s/HYCq2mKlIaSCRAJIp92NGQ

AGE Template — attractor-guided-engineering-template, github.com/entropy-cloud/attractor-guided-engineering-template

nop-chaos-flux Practice — github.com/entropy-cloud/nop-chaos-flux

1. Core Proposition Comparison

Dimension	RMSP Agent Paradigm	AGE Methodology	nop-chaos-flux Practice
Core Diagnosis	Current agent = authoring artifact, structure is static	Current AI development relies on external tools to constrain behavior (harness-first), rather than letting the repository structure itself converge	Under high-frequency AI perturbations, the repository must become a verifiable source of truth
Core Proposition	Agent structure should self-evolve through use	The system should converge to stable attractors through iteration	The `docs/architecture/` owner-doc system is the engineering carrier of attractors
Structural Object	MAN aspect graph	Owner-doc system	Architecture document tree with precedence
Evolution Rules	RMSP: reweight/connect/prune/split/merge/lift	AGE workflow: input → req → design → plan → implement → verify → close	Strengthened: plan closure gate + independent audit + deep-audit
Evaluation Function	`F = Surprise + β·Complexity`	Attractor fidelity + trajectory convergence	Live repo baseline consistency (owner doc vs code vs test)

All three paradigms originate from the same observation: static structure cannot adaptively evolve through interaction; some form of plasticity mechanism must be introduced.

2. Structural Plasticity at Three Scales

Structural plasticity occurs at three distinct time scales.

Scale 1: Agent Runtime — RMSP/MAN

RMSP models the agent's behavior topology as an aspect graph. Each aspect (a responsibility concern, containing pointcut matching conditions and advice processing logic) carries its own sliding window that tracks recent performance.

After each interaction, the reward is distributed to the aspects that participated in the decision, accumulating as contribution values. When the credit variance of an aspect exceeds a threshold, one of six rewrite rules is triggered. split divides a high-variance aspect into two specialized ones (top-down differentiation); lift abstracts a cluster of co-activated aspects into a higher-level coordinator (bottom-up abstraction); connect/prune manage edge evolution and elimination. The LLM can propose new structures, but they can only be committed after passing dual gating—κ estimation (evaluating expected benefit) and F-score (Surprise + β·Complexity)—generation and verification must be separated.

MAN explicitly divides the agent into two systems: the LLM is System 1, responsible for fast reasoning and generation in the current round; the aspect network is System 2, responsible for structural governance, scheduling, and self-evolution. The fast pathway (⇓_fast) completes a single inference under a fixed topology; the slow pathway (⇓_slow) only changes the graph structure after accumulating sufficient signal. The LLM is the effector, MAN is the nervous system—the two specialize at different time scales.

Scale 2: AI Development Session — AGE Plan/Closure/Audit

AGE organizes each development task as a convergence cycle: input/ → discussions/ → requirements/ → design/ + architecture/ → plans/ → implement → verify → close.

What grows here is not an aspect graph, but plan documents, closure gate judgments, and audit records. The cycle triggered by each task pushes requirements from ambiguity to implementation readiness, while simultaneously depositing stable design intentions into design/ and architecture/ (i.e., attractors). After each plan execution, an independent session must perform a closure audit—the implementer cannot self-report completion.

In nop-chaos-flux, this cycle is strengthened to 24 plan rules, 3 status levels, and deep-audit. Plan 143 is a typical example: closure assumptions were successively overturned by independent audits on 2026-04-26 and 2026-04-27, and were only allowed to close after the live repo truly passed the threshold.

Scale 3: Long-Term Project Evolution — AGE Attractor / Owner-Doc System

The slowest layer is the change of the docs/architecture/ document tree itself. New architecture docs are promoted from analysis/ or plans/ to stable architecture docs; old structures are excluded (e.g., CompiledSchemaNode removal); architectural layers deepen (from fewer package layers to three layers—flux-compiler, flux-action-core, flux-runtime—forming a five-layer pipeline: flux-core → flux-compiler → flux-action-core → flux-runtime → flux-react).

Changes at this layer are not driven by session-level tasks, but by the accumulation of cross-session design decisions + discoveries from deep-audits. Each deep-audit that finds a discrepancy between owner-docs and the live repo triggers a round of structural correction. After correction, the project returns to the vicinity of a more precise attractor.

	Agent Internal (RMSP)	Session Control (AGE Plan)	Project Evolution (AGE Attractor)
Time Scale	Per interaction	Per task (hours ~ days)	Weekly ~ monthly
Structural Unit	aspect	plan + closure gate	owner-doc
Learning Signal	reward → credit assignment	audit finding → baseline drift	deep-audit → doc/code discrepancy
Drift Detection	sliding window variance	exit criteria not met	owner-doc vs live repo inconsistency
Adoption Gating	κ estimation + F-score	independent closure audit	deep-audit + decision record
Persistence Assumption	Continuous existence (single instance, single session)	Intermittent existence (multi-session)	Time-translation invariant (multi-instance, unaffected by instance lifecycle)

3. Conceptual Mapping

Aspect ↔ Owner-Doc

RMSP's aspect is the minimum behavioral unit inside an agent (pointcut + advice + sliding window). AGE's owner-doc is the minimum stable unit of project knowledge (design intent + contract + precedence).

Both are the minimal structural units, both can be split/merged/lifted, and both have their own "pointcut" (when to trigger, docs/index.md routing) and "advice" (behavior after triggering).

Key difference: aspects are automatically grown driven by reward, and are proprietary to a single agent instance; owner-docs are collaboratively authored by humans and AI, versioned, and shared by the team.

Rewrite Rules ↔ Document Evolution

RMSP Rule	AGE/nop-chaos-flux Correspondence	Real Examples in the Repository
split	One architecture doc split into multiple narrow-scope docs	Responsibility differentiation from `flux-core.md` into `frontend-programming-model.md` (top-level spec), `form-validation.md`, `renderer-runtime.md`
merge	Merging docs with similar functions	Two docs expressing the same constraint merged into one
lift	Abstracting higher-level principle docs from concrete docs	`docs/architecture/README.md` as the reading order and hierarchy for the whole set of architecture docs
connect	Establishing cross-references and new dependencies	`renderer-runtime.md` referencing `form-validation.md`, `field-binding-and-renderer-contract.md` referencing `renderer-runtime.md`
prune	Deprecating/archiving docs that no longer apply	Code and docs related to `CompiledSchemaNode` completely removed
reweight	Adjusting owner-doc precedence	`frontend-programming-model.md` established as a top-level spec, overriding part of `flux-core.md`'s responsibilities

Reward Modulation ↔ Audit Signal

RMSP uses reward → credit assignment → contribution accumulation → structural rewrite. AGE uses audit finding → baseline drift detection → closure gate adjustment → structural update.

The signal must not come from the generator itself—this is a shared discipline of both. In RMSP, the LLM is the structure proposer, reward is the verifier; in AGE, the implementer cannot make the completion judgment—an independent session must perform the closure audit.

Soft Advice ↔ Hard Control Flow

Both RMSP and AGE transform soft signals into hard control flow. In RMSP, new structures proposed by the LLM must pass the hard gates of κ estimation and F-score before being written into the aspect graph—this is not a suggestion, but an unavoidable verdict. In AGE, the closure audit result is likewise not a "recommendation to close," but the actual decision on whether a plan can be marked completed. Both do the same thing: whether the structure changes is not decided by the proposer's soft opinion, but by a hard mechanism independent of the proposer.

From an engineering direction perspective, the long-term trends on both sides are also consistent: turning more soft constraints into enforceable control-flow nodes. The RMSP paper explicitly distinguishes "soft advice" (prompt injection, unreliable) from "hard advice" (intercepting tool calls, rejecting actions, rewriting parameters, reliable), and points out that improving agent reliability depends on the latter. AGE's closure gate, deep-audit, and 24 plan rules similarly solidify the soft intention of "should converge" into executable hard barriers.

Slow Pathway ↔ Closure Audit

RMSP's slow pathway does not participate in each fast inference; it only triggers structural rewriting after credit accumulates to a threshold. AGE's closure audit likewise does not participate in daily implementation; it performs an independent convergence judgment only after plan execution is complete.

4. Core Differences

Degree of Automation

RMSP's aspect growth is fully automatic—reward drives all rewrite rules with no human intervention required. AGE's attractor evolution is semi-automatic—human/AI collaboration proposes new structures, adopted after audit gating.

RMSP is more suitable for online learning of a single agent—small scale, dense feedback. AGE is more suitable for repository-level knowledge management—large scale, feedback sparse but each structural change has major impact.

Structural Carrier

RMSP's structural carrier is the runtime aspect graph (in memory, independent per agent instance). AGE's structural carrier is the owner-doc in the repository file system (on disk, versioned, team-shared).

RMSP can migrate aspect graphs across agent instances (export → import); AGE naturally supports multiple humans and multiple agents sharing the same attractor (version control + diff review).

Evaluation Metric

RMSP uses F = Surprise + β·Complexity to uniformly judge whether a structural change is accepted. The intuitive meaning of this formula is "structure must pay rent": new structure must reduce error (Surprise) to justify its complexity (Complexity). AGE does not have a unified numerical metric; it uses multiple practical signals to evaluate convergence: whether typecheck/build/test pass, whether owner-docs match the live repo, whether the closure audit verifies completion.

The state space at agent runtime (aspect graph × memory × tool calls) is far smaller than the state space of a software repository (files × dependencies × behaviors × tests × docs × configuration). In a small state space, a unified numerical evaluation function is feasible; in a large state space, evaluation must decompose into a combination of multiple orthogonal signals.

Adaptation vs. Convergence

RMSP's goal is adaptation—the agent better adapts to the current user, allowing the aspect graph to drift continuously (as long as F decreases). AGE's goal is convergence—the system converges toward predefined attractors; structures that deviate are pulled back by the harness.

nop-chaos-flux manages this by strictly distinguishing "scope-in changes" from "attractor updates." Design changes must go through both owner-doc update and closure audit; silent baseline shifts are not allowed.

Time-Translation Invariance

RMSP assumes the agent exists continuously—at least running throughout one session, the aspect graph in memory, reward signals continuously accumulating, structural rewriting occurring naturally between interactions.

AGE faces different constraints: AI sessions disappear when the user closes the window. Today Agent A modifies the same repository, tomorrow Agent B audits it, the day after Agent C continues development—all three must see the same repository, read the same owner-docs, and judge closure against the same live repo. All of AGE's state input and output pass through the file system; this is not a design preference, but a direct consequence of time-translation invariance: because sessions cannot persist, cross-session consistency can only be guaranteed by the file system as the sole persistent layer. ("Time-translation invariance" is borrowed from Noether's theorem in physics; here it means that the system's behavior does not change due to the agent operating it or the point in time.)

RMSP and AGE fundamentally do not face the same time structure.

RMSP solves an adaptation problem for a single instance, continuously existing—an agent works better and better from the beginning to the end of a session.
AGE solves a convergence problem for multiple instances, intermittently existing—no matter which agent, no matter when the repository is opened, they all see and maintain the same set of attractors.

When integrating RMSP and AGE, the data-flow problem that truly needs to be solved is not compatibility at the architectural abstraction level, but: After an agent instance is destroyed, which information from its aspect graph needs to be written into the repository? The RMSP paper does not define this step (it does not assume multiple instances), but this must be resolved in practical integration—for example, degrading stably converged aspect rules into operational rules in AGENTS.md, or exporting them as project-shareable skill packages. Conversely, after AGE's owner-docs are read into agent runtime, a mechanism is also needed to determine which constraints should be solidified into the aspect graph and which only need to be referenced during the current session.

Can an RMSP Agent encode AGE's owner-doc rules as pointcuts/advice in the aspect graph, thereby internalizing AGE's functionality? No. The reason is not technical difficulty—AI can certainly learn to read files—but that the time structures do not match. RMSP assumes the agent exists continuously; the aspect graph lives and dies with the instance. AGE requires time-translation invariance: the owner-doc written by Agent A today must be independently auditable by Agent B tomorrow, unaffected by whether A is still running. As long as repository users do not share the same persistent agent instance, internalization is a dead end. The file system is the only shared layer unaffected by instance lifecycles.

When the two conflict, attractor takes priority—cross-session project consistency has higher weight than the local optimum of a single agent's adaptation. If an agent's aspect graph drifts in a direction that conflicts with the owner-doc, AGE's harness (closure audit, deep-audit) will pull it back, not RMSP's reward signal. Coexistence of both requires a clear arbitration rule: the project baseline is defined by AGE; the agent can only self-adapt without breaking the baseline.

Integrate RMSP into agent runtime so that agents evolve skill preferences adapted to the current project through use; layer the AGE methodology on top so that the project repository maintains structure under high-speed agent iteration. Each handles its own convergence problem.

5. Implicit Confirmation in nop-chaos-flux

nop-chaos-flux does not implement RMSP, but its practices have deep correspondence with RMSP's ideas:

Separation of Generation and Verification: RMSP's core design—LLM proposes structure, reward decides whether the structure is committed. nop-chaos-flux's core discipline—the implementer cannot make the completion judgment; closure audit must be done by an independent session.

Explicit Externalization of Structure: RMSP designs the aspect graph as an inspectable, editable, exportable data structure. nop-chaos-flux uses the docs/architecture/ owner-doc as the stable carrier of where the system should converge. Both approaches believe structural information should be explicitly externalized, not relying on implicit internalization.

Structural Rewriting Predicated on Baseline Alignment: Before RMSP rewrites, the current MAN graph must be known (κ estimation requires a baseline). The first rule of nop-chaos-flux's plan guide: verify the live repo before writing a plan.

Deep Correspondence in Audit Algorithms: nop-chaos-flux's deep-audit has a whole set of drift classifications—doc-behavior drift, proof insufficiency, duplicate coverage, orphan contract. These are the repository-scale expressions of the Surprise signal in RMSP: when owner-doc description ≠ live repo behavior, Surprise increases, requiring structural correction.

6. AGE Template: The Middle Adhesive Layer

attractor-guided-engineering-template (GitHub) is a complete templating of AGE for application-layer projects. Its relationship with nop-chaos-flux is:

Dimension	AGE Template	nop-chaos-flux
Positioning	Application-layer project scaffold	Framework-level low-code runtime
Document Count	~20-30 files (core ~10)	Dozens of architecture docs + component design docs + plan + audit
Plan Complexity	Lightweight plans (~5-section template)	Full plan system (24 rules + 3 status levels)
Audit Requirements	Pre-plan audit + closure audit	Same as left + deep-audit + adversarial review
Project Scale	Small-to-medium applications	Large framework (~20 workspace packages)

The AGE template serves as a bridge between RMSP and nop-chaos-flux: it does not require every layer to be in place from the start, but provides a scaffold that can be progressively strengthened. The RMSP paper calls the initial state of the agent the "zygote" (a single cortical aspect + a set of conserved reflex cores + zero synapses), corresponding to the AGE template's "minimal core" (AGENTS.md + docs/index.md + docs/context/ + verification commands); RMSP's "growth through interaction" corresponds to AGE template's "trigger on demand" (plans/, bugs/, logs/ appear only when actually needed, not pre-created in full).

7. A Unified Evolutionary Landscape

Scale              Time Structure                   Structural Example          Evolution Mechanism        Evaluation Method
────               ──────                          ──────                     ──────                     ──────
Agent Runtime      Continuous existence            aspect graph               RMSP                       F = Surprise + β·Complexity
                   (single instance)               (6 rewrite rules)
                                                        ↑
Development        Intermittent existence          plan + closure             plan audit                 Independent closure audit
Session            (multi-session)                 gate + audit               + exit criteria
                                                        ↑
Long-Term          Time-translation invariant      owner-doc tree             deep-audit +               owner-doc vs live repo
Project            (multi-instance, unaffected     architecture attractor     decision record            consistency check
                   by instance lifecycle)
                                                        ↑
Methodology        Time-translation invariant      AGE template +             copy → fill →             project-context authenticity
Template           (templatized)                   START-HERE                 progressive enhancement    verification commands non-placeholder

Each layer solves a different convergence problem, and each layer has a different time structure. RMSP assumes continuous agent existence, converging an instance to a behavioral topology adapted to the current task; the Plan layer faces intermittently existing multi-sessions, converging a single development change to a predetermined scope and closure gate; the Owner-doc layer requires time-translation invariance, converging the project's long-term evolution toward a stable architecture attractor—no matter which agent reads it when, the attractor seen is consistent; the template layer also requires time-translation invariance, but targets new projects starting from scratch.

8. Conclusion

Shared Diagnosis: All three consider the static authoring artifact to be the core limitation of current practice and argue that structural plasticity must be introduced.
Scale Division of Labor: RMSP solves the structural self-evolution of the agent at runtime; AGE/nop-chaos-flux solves the structural convergence of project repositories under high-frequency AI iteration. The two are not substitutes, but complement each other at different scales.
Shared Gating Principle: Generation (LLM proposal / agent implementation) and verification (reward / audit) must be separated. In RMSP, this manifests as κ estimation + F-score; in AGE/nop-chaos-flux, as independent closure audit.
nop-chaos-flux is a complete implementation of AGE at the framework level, and also an early validation of RMSP concepts at the repository management level—owner-doc's split/merge/lift/prune/connect/reweight achieves self-organizing evolution of document structures.
The AGE Template is the middle adhesive layer: attractor-guided-engineering-template connects the theoretical paradigm (RMSP) and framework-level practice (nop-chaos-flux), providing a path for application-layer projects to grow progressively from a zygote.
A Verifiable Prediction: If RMSP is engineered and verified in the future, its most natural integration method is not to replace AGE, but to combine with AGE at the agent runtime layer—RMSP drives the adaptation of the agent's own structure, AGE drives the convergence of repository attractors. Together they form a complete "self-evolving development" closed loop.

Why Attractor Guided Engineering Cannot Be Demoted to an AI Agent Skill

canonical — Mon, 01 Jun 2026 07:05:49 +0000

Agent Skill is already one of the most widely accepted practices in AI Agent engineering: encapsulating repeatable tasks into capability packages that are discoverable, callable, and injectable into context.

This is certainly valuable. Diagnosing bugs can be a skill. Reviewing code can be a skill. Generating slides can be a skill. Converting files can be a skill. Skills let an Agent enter a proven way of working faster, and they allow teams to distill experience into reusable work specifications.

But as the saying goes: “If all you have is a hammer, everything looks like a nail.” The same is true for skills: as soon as people find a useful practice, their first instinct is often “wrap it into a reusable skill.”

Attractor Guided Engineering (AGE) points out that if every AI engineering practice is turned into a skill, we lose sight of the most critical question in AI-dominated software engineering: how does the system remain controlled and convergent under continuous perturbation?

Skills solve the problem of capability invocation. AGE solves the problem of how domain structure is preserved during the long-term evolution of a repository, and how trajectory drift is suppressed.

This also explains why AGE cannot be demoted to a skill: making skills the primary vehicle for AGE practices would collapse repository-level convergence mechanisms into one-shot invocation capabilities, defeating the purpose of AGE.

1. The Essence of a Skill is a Semantic-Level Hash Map

When many people think of skills, they first see the file form: SKILL.md, description, trigger words, supporting files, scripts, templates.

But these are just the shell. Where a skill really works is that the Agent runtime organizes them into a semantic-level lookup table:

task intent -> matched skill -> procedure bundle

In other words, the Agent does not gain capability simply because a file is named SKILL.md; it gains capability because the current task intent can be matched in the skill description space to a loadable work specification.

The hash here is not a string hash. The key is not a fixed string but a combination of task intent, contextual clues, trigger words, and descriptions; the value is not a single file but a collection of instructions, scripts, templates, and examples that can be injected into the context.

This structure is ideally suited to answering one question:

I need to do this kind of task — which set of practices should I load?

Therefore, skills are very suitable for encapsulating local capabilities: diagnosing bugs, reviewing diffs, calling tools, generating reports, executing checklists. Their organizing axis is invocation intent, mapping “what to do” to “which capability package to load.”

2. The Information Format Is Not the Key

Since the real mechanism of a skill is semantic matching, we must not fetishize the file format of a skill.

For an intelligent agent, the format in which information is written is not essential. AI can read Markdown, and it can also read XML and other formats. Database models, API models, and the like can be fully expressed in DSLs (domain-specific languages).

AGENTS.md and docs/index.md can perfectly serve as information routers and can even do better: through file links, we can provide hierarchical routing by domain structure. The AI can first read a compact entry point and then, as the task requires, progressively open more specific owner docs, model files, tests, and source code.

Therefore, the question is not “has this piece of knowledge been written as a skill?”

The question is: after the information changes form, does the original structure still exist?

A key capability of intelligence is the ability to freely transform information across forms. If the structure remains, knowledge written as Markdown, XML, tests, DSL/schema, or source code anchors can all be used by the AI. If the structure is lost, wrapping it in the most exquisite skill only makes the fragments—after the structure is lost—easier to invoke.

3. Why Dynamical Systems Care About Preserving Structure

Dynamical systems in mathematics and physics provide a useful intuition: the variables describing a system can change, but the key structures governing the system’s evolution must not be casually discarded.

Imagine a pendulum clock. You can describe it with angle and angular velocity, or with position and velocity, or with energy and phase. The form of expression can change, but the key structure of the pendulum cannot be lost: how position and velocity are coupled, how energy changes, how damping dissipates energy, where external forces enter.

If an algorithm only pursues “the next position looks roughly right” without preserving these structures, it might make only small errors at each step, yet over the long term it makes the pendulum swing higher and higher for no reason, or stop suddenly. The local output looks similar, but the long-term system is no longer the original system.

Consider an electrical circuit. You can describe it with node voltages, or with branch currents, or treat the energy stored in capacitors and inductors as state variables. The variable form can change, but some structures must not be lost: charge conservation, the coupling relationships between voltage and current, energy storage and dissipation in components, where the external power source injects energy.

If an algorithm only pursues voltage values at a few sampling points that look close, without preserving these structures, the long-term simulation may spontaneously generate energy, or turn a system that should dissipate into one that oscillates endlessly. The local curve resembles the truth, but the physical meaning of the system is already wrong.

This is what it means to preserve structure:

The form of expression can change, but key constraints, coupling relationships, and conservation/dissipation structures must not be lost.

A controlled system converges over the long term not because each step seems reasonable, but because these structures are preserved through repeated transformations and perturbations.

4. The State Space Is Not the Source Code Space

If we observe software engineering through the lens of dynamical systems, a repository is no longer a static folder but a system that is repeatedly perturbed. Every requirements clarification, plan generation, code modification, test addition, review, and log update pushes the repository to a new state.

Traditional software engineering rests on an implicit assumption: the human brain can serve as the long-term implicit integrator of system truth. Source code, requirements, architectural trade-offs, historical bugs, and unwritten context can ultimately be fully understood by a few core engineers who decide the direction of evolution.

After deep participation of AI, this underlying assumption is shaken. AI can generate at high frequency, modify at large amplitude, and spread across modules, while each session lacks a sustained sense of direction. The expansive force that AI introduces into the state space far exceeds the information processing capacity of a few humans. At this point, unless we forcibly slow AI down to a rhythm that humans can continuously integrate, the source of truth in the system's evolution can no longer be the memory inside someone's head. What the next session can re-read is not the complete intent in the author’s mind, but the code, diffs, logs, tests, docs, models, and audit evidence in the repository.

The history of nop-chaos-flux has already recorded this kind of drift multiple times. Workstream 8 of docs/plans/436-deep-audit-2026-05-24-full-remediation-plan.md fixed an active-doc drift: the documentation described component:open/close/toggle, component:refresh, the old package split, old source anchors, and an outdated component inventory as current facts, while the live repo was no longer like that. docs/logs/2026/05-26.md recorded a proof drift: the E2E tests still asserted that the spreadsheet's 30 row headers were mounted simultaneously, while the live spreadsheet shell had already been virtualized, so the correct proof could only assert that visible row headers were mounted. Code, documentation, and tests might each be locally reasonable, but the owner/proof/precedence relationships among them had already drifted.

Thus, the basic premise of AGE is:

Repository = Source of Truth
Chat = Transient work surface

Under this premise, the core question is not:

Did the Agent invoke the right skill this time?

but:

After many Agent perturbations, does the repository still converge in a controlled manner along the domain structure?

The basic picture of AGE is:

State space -> Attractor -> Trajectory -> Control

The state space here is not the “source code state space.” Source code answers what the current implementation is, but it cannot alone answer where the system should converge, why a certain design is valid, which behavior has been proven, why a certain deviation was accepted, and from where the AI should recover context next time.

AGE is concerned with the state of the entire repository engineering reality: source code, tests, owner docs, requirements, plans, logs, bug notes, schemas, XML models, database models, XDSL, AGENTS.md, docs/index.md, CI configuration, and audit evidence together constitute a state.

These are not several separable materials, but the distribution of the same set of semantic commitments across different carriers. Code has authority over implementation facts; owner docs have authority over convergence direction; tests have authority over proven behavior; logs/bug notes have authority over the evolution trajectory; plans/audits have authority over whether the current cycle of changes is closed. What AGE must maintain is the relationships among these authorities, not the sanctification of any single file format.

A Skill occupies a different position. AGE organizes the repository itself; skills are external capabilities or control inputs that act upon the repository.

External capabilities can change the system, but they cannot replace the internal structure of the system. A bug-diagnosis skill can be used in many repositories, many domains, many bug types. Its organizing logic is general task capability, not the topology of domain concepts inside a specific repository.

What truly needs to be preserved inside the repository are the relationships among source code, documentation, tests, models, plans, logs, and audit evidence — relationships such as owner, proof, precedence, and freshness. Skills can help modify these things, but they cannot replace the relationships themselves.

At this point, we realize that the skill’s semantic hash is insufficient to solve the problem. What a skill stores is:

task intent -> capability package

What AGE needs to preserve is:

domain concept -> semantic commitment -> implementation location -> proof evidence -> audit/memory -> subsequent obligations

These two structures are not the same. A skill can tell an Agent how to review, but it cannot automatically know which owner doc holds the current semantic fact. A skill can tell an Agent how to write tests, but it cannot automatically know which domain commitment this test protects. A skill can tell an Agent how to update documentation, but it cannot automatically determine whether a piece of information should go into an owner doc, a bug note, a log, a lesson, a reference, or a skill.

These judgments are not invocation capabilities; they are the semantic authority structure of the repository.

5. Why `age-skill` Is a Wrong Abstraction

Turning AGE into an age-skill is superficially tempting: take AGE’s rules, procedures, checklists, and document templates and write them into a callable capability package. When the Agent needs AGE, it loads this skill.

But this places AGE at exactly the wrong level. A skill is a capability package that is matched and loaded after a task occurs; AGE should be the repository structure that already exists before the task begins. It determines how the task is understood, where information is read from, whose voice prevails in a conflict, and how closure is proved after completion.

AGE cannot wait to appear only after a certain skill is selected. It should already be embodied in:

The operational boundary of AGENTS.md
The routing structure of docs/index.md
The fact ownership of owner docs
The conflict rules of source-of-truth precedence
The obligation declarations of plans
The proof relations of tests
The closure gates of audits
The trajectory memory of logs, bug notes, and lessons
The action constraints of freshness/autonomy

If these relationships exist only inside an age-skill, they are not repository structure but merely the content of a procedure bundle. Whenever the Agent does not match this skill, or the skill conflicts with the live repo, AGE becomes ineffective.

Making age-skill an always-on or global skill does not solve this problem either. At best, it can prescribe “read these owner docs first, check precedence this way, do a closure audit like that.” But the real owner, proof, precedence, and freshness relationships must still exist among the repository’s files, tests, logs, plans, and audit evidence.

So the problem is not whether age-skill is loaded every time; the problem is that a skill is still a capability package imposed on the repository from the outside. AGE must become the underlying topology of the repository itself. As long as owner, proof, precedence, and freshness are not internalized as repository state, AGE is demoted to an external operating method rather than an intrinsic convergence structure.

6. The Missing Concepts That AGE Supplies

Under the image of controlled convergence and structure preservation, what AGE supplies is not a new checklist, but a set of first-class system concepts that skill-ification practices lack.

1. Attractor

To what structure should the system return in the long run? This cannot be decided by any single skill. It needs to be carried by owner docs, architectural baselines, domain design, and source-of-truth precedence. Without an attractor, a skill can only tell the Agent how to do things; it cannot tell the repository where it should converge.

2. Trajectory

Completing a single task does not mean the system direction is correct. Logs, bug notes, lessons, plans, and audit records record how the repository arrived at its current state step by step. Without trajectory memory, the AI starts anew from a local cross-section each time, making it hard to judge whether the system is converging or drifting.

3. Semantic Authority

When a skill, plan, code, test, and documentation disagree, whose voice prevails? AGE requires owner, routing, and precedence, rather than letting the currently invoked skill adjudicate on the fly. Semantic authority is not part of the execution steps; it is the internal order of the repository’s state space.

4. Proof Relation

It is not enough for tests to “have coverage.” Tests must declare which semantic commitment they protect. Audit is not a checklist, either, but an examination of whether commitments have disappeared, weakened, or migrated to non-authoritative carriers. Proof relation makes verification not just about passing commands, but about returning to domain commitments.

5. Freshness / Autonomy

Documentation is not eternally trustworthy just because it was written. Whether a document is fresh affects whether the AI can act on it, how far it can go autonomously, and when it must stop and ask a human. Freshness/autonomy turns “can we trust this, can we do this automatically” into a visible state of the repository, rather than an ad-hoc judgment inside a single session.

6. Structure-Preserving Document Routing

AGENTS.md can provide the AI with a compact operational entry point, and docs/index.md can provide complete routing. The purpose of both is not to cram all knowledge into a single file, but to let the AI progressively open the right information according to the task’s needs. Information disclosure can be layered, but the domain structure must not be fragmented.

These concepts together form the semantic authority topology of AGE.

7. AGE Can Use Skills, But Cannot Become a Skill

AGE is not opposed to skills. Skills are excellent execution scaffolds.

But within AGE, skills can only be method nodes; they cannot be the source of truth, nor can they be AGE itself.

The correct order is:

First, find the route via AGENTS.md / docs/index.md
Then, read the domain or architectural owner doc
Then, read the active requirement / plan / audit evidence
Finally, select the appropriate skill as the execution method

Not:

First, select a skill, then let the skill decide fact ownership

For example, a bug diagnosis skill can tell the Agent how to reproduce and locate a problem. But which domain concept the root cause belongs to, which owner doc needs updating, which test proves the fix, and which category of regression the bug note will constrain in the future — all of these must be decided by returning to the semantic topology of AGE.

A good skill accelerates execution. Bad skill-ification replaces domain structure with execution methods.

8. Judgment Criteria

To judge whether a set of AI engineering practices is over-skill-ified, ask:

Does it organize knowledge primarily by operational verbs, or by domain concepts and architectural ownership?
Are its links mainly execution resource references, or owner / invariant / proof / precedence / freshness relationships?
After information is transformed between skills, plans, code, tests, docs, and logs, can the domain structure still be recovered?
If all skills are deleted, does the repository still know what is correct, who owns it, and how to prove it?

If the answers are negative, skills have already taken on attractor responsibilities they should not bear.

The ultimate distinction can be compressed into a single sentence:

Skill packages capabilities by invocation.
AGE preserves domain structure across transformations.

Skills make the Agent better at doing things. AGE ensures that after the Agent does things repeatedly, the repository still converges in a controlled manner along the domain structure.

AGE Application Development Template

Beyond Harness Engineering: Understanding Attractor-Guided Engineering through Nonlinear Dynamical System Control

canonical — Fri, 29 May 2026 15:17:19 +0000

This article is aimed at readers who are already familiar with Harness Engineering but not yet familiar with Attractor-Guided Engineering (AGE).

Harness Engineering focuses on how to constrain, verify, and audit AI-generated outputs; AGE asks further: what long-term structure should these control mechanisms eventually pull the repository trajectories back to?

For a detailed introduction to AGE, see my previous article: Attractor Before Harness: A Methodology for AI-Scale Development. This article focuses on a methodological analogy: using the language of nonlinear dynamical system control—in particular the structure-preserving terminology of port-Hamiltonian systems (PHS) and the target-manifold image of Immersion and Invariance—to explain some structures that already exist in AGE but have not yet been fully named: how semantic commitments are conserved, how change obligations are transformed, how document topology preserves structure, and how AI sessions recover the same system reality in a repository across time.

1. Why This Analogy Is Needed

AGE already has a core language:

State space → attractor → trajectory → control

This basic AGE vocabulary precisely captures a core problem in AI-scale development: when AI perturbs the repository at high frequency and amplitude with no persistent memory, how do we describe whether the system is still converging to a stable structure over the long term?

More precisely, AGE examines AI-driven software engineering through the mental image of a dynamical system. A single AI task can be seen as one perturbation and correction on the repository trajectory; a single input-output is only a local cross-section of that trajectory. The repository is a state space that evolves over time; AI, humans, CI, audits, and documentation updates all change the trajectory; owner docs define the attractor the system should repeatedly return to; plans, tests, audits, and logs provide local calibration mechanisms.

Nonlinear dynamical system control is the theoretical branch that systematically studies “states, trajectories, stability, manifolds, feedback, observation, and structure preservation.” PHS (port-Hamiltonian systems) is a representative example of the structure-preserving approach. It decomposes a complex system into four structural classes: the Hamiltonian records how much energy is stored in the system; the interconnection matrix records how energy is transferred losslessly among internal variables; damping records irreversible losses such as resistance or friction; ports record the boundaries where the system exchanges energy with the external world. The key role of PHS modeling is to classify the coupling terms in the equations by function: some coupling terms only move energy internally, some represent true dissipation, and some come from external ports. Once these structures are distinguished, control design knows which terms should be preserved and which should be compensated or suppressed.

This article does not try to equate AGE with PHS, but rather borrows the representative vocabulary of PHS to further identify conserved quantities, phase variables, interconnection topology, dissipation mechanisms, and port boundaries in AGE.

Terminology conventions used in this article:

AGE: Attractor-Guided Engineering. The core hierarchy is “state space → attractor → trajectory → control.”
Harness Engineering: the engineering practice of building execution scaffolding around AI generation, such as guardrails, verification, review, audit, and diagnostics.
PHS: port-Hamiltonian systems, the representative language of the structure-preserving approach in nonlinear dynamical system control, describing complex systems using an energy function, interconnection, dissipation, and ports.
Hamiltonian: the system’s stored energy function, describing how much energy the system currently holds.
Immersion and Invariance: a method that handles nonlinear control, observation, and adaptation problems by constructing a target invariant manifold.
owner docs: long-term documents that hold the ultimate interpretive authority for certain categories of facts in the repository, such as architecture baselines, feature designs, or component contracts.
closure audit: an audit that re-checks the closure evidence along requirements, owner docs, code, tests, and logs before a task is considered complete.

Compared with PHS, the basic language of AGE still has an underexplored layer:

Between repeated inputs, plans, implementations, verifications, audits, and logs, what exactly is being preserved, transformed, routed, and dissipated?

If we answer in ordinary process language, it is easy to fall back into a linear pipeline:

input → requirement → design → plan → code → test → log

This image misleads the reader. Real development does not simply read the output of the previous stage and generate the next artifact. When writing and reviewing code, the AI typically needs to reference simultaneously: the current requirement, owner docs, live code, tests, a known-good baseline, bugs, logs, the plan, audit results, external contracts, and the reading routes given by the document index and architecture hierarchy.

In other words, AGE is more like a multi-port coupled system; the unidirectional cascade pipeline only describes a local projection of it.

The inspiration from nonlinear control lies exactly here: complex coupling terms are not necessarily noise; many coupling terms are themselves the way the system preserves structure. In motor control, the d-q coordinates—direct-axis and quadrature-axis coordinates that rotate with the rotor—are commonly used; under these coordinates, certain speed-dependent, skew-symmetric cross-coupling terms can represent lossless flow of energy between different coordinates. Similarly, in AGE the cross-references among requirements, architecture, plans, code, tests, and logs bear the topological function of keeping semantic commitments recoverable across different carriers—not just document redundancy.

2. The Structure-Preserving Language of PHS

The basic starting point of PHS is to view a physical system as a combination of “energy storage, interconnection, dissipation, and port exchange.” A common finite-dimensional form can be written as:

dx/dt = (J(x) − R(x)) ∇H(x) + G(x) u
y = G(x)ᵀ ∇H(x)

This formula shows how several core symbols are organized:

H measures the energy currently stored in the system;
J only moves energy; it neither creates nor destroys energy;
R dissipates the system’s internal energy;
u is the port input, y is the port output; the pair forms the port power yᵀu;
G describes how the ports couple to the internal state.

We can borrow this vocabulary to express three methodological principles from nonlinear control:

First find quantities that tend to be conserved, then judge which errors need to be eliminated.
Distinguish lossless routing from true dissipation; do not mistake “information moved” for “the system converged.”
View “transport, dissipation, and external injection/extraction” separately, and avoid flattening all coupling into a linear task chain.

3. The Feedback-Linearization–Style Software Engineering Fallacy

In control theory, exact feedback linearization attempts to cancel nonlinear terms using coordinate transformations and feedback so that the system behaves as a linear object. This works in some systems, but it can also be highly dependent on exact parameters and destroy the system’s original energy structure.

There is a similar impulse in software engineering: to make things easier for the AI, flatten all knowledge into a single unified artifact—a spec, a change request, a task list, an issue, a pull request description, or some master plan document.

This practice appears to reduce complexity, but it is actually performing an engineering version of “linearization”:

Context in raw input is flattened into requirement entries;
The long-term structure of owner docs is flattened into this iteration’s task description;
Architecture precedence is flattened into a checklist;
Historical judgments in logs, bugs, and analysis are flattened into “known items”;
Tests and audits are flattened into “completed proof.”

Locally, this makes it easier for the AI to execute. Over the long term, it destroys the semantic topology of the repository. After different types of facts are squeezed into the same coordinate system, the AI no longer knows which material answers “what is,” which material answers “where we should converge,” and which material is only “why we did it that way at the time.”

AGE can use specs and checklists, but it should not forcibly compress all knowledge into the same execution form. docs/architecture/, docs/components/, docs/plans/, docs/logs/, docs/bugs/, docs/analysis/ need to retain distinct responsibilities, because they are different energy ports and different state coordinates within the same repository system.

4. Semantic Commitment as the Energy Storage Function of AGE

In PHS, the Hamiltonian is the system’s stored energy function, answering “how much energy does the system currently hold.” When applied to AGE, we can regard the semantic commitments that must be recovered, preserved, and used to constrain future evolution across sessions as the repository system’s “stored energy”:

H_repo = total amount of semantic commitment in the repository that remains valid
         and must be recoverable across sessions to constrain future evolution.

Here “semantic commitment” means facts, contracts, and judgments that the system has accepted and that should not be casually lost; file word count or number of document entries is not equivalent to semantic commitment. For example:

A certain user-visible behavior must exist;
A certain schema field has a definite meaning;
A certain package dependency direction must not be reversed;
A certain renderer contract needs to be stable;
The root cause of a certain historical bug must not be reintroduced;
A certain audit finding has been falsified and should no longer drive corrective action;
A certain owner doc defines the current specification baseline, not a future aspiration.

These commitments can be roughly decomposed as:

H_repo = H_intent + H_requirement + H_owner + H_contract + H_behavior + H_proof + H_memory

These components correspond to:

Component	Meaning	Typical carriers
Hintent	Genuine intent brought by external input	User requests, PM explanations, external material
Hrequirement	Requirement commitments that the current slice must fulfill	requirement, plan goals
Howner	Long-term stable structural commitments	architecture docs, component design docs
Hcontract	Contracts that can be relied upon externally or downstream	schema, API, public types, renderer contracts
Hbehavior	Actual running behavior in the live repo	code, examples, playground
Hproof	Re-examinable proof	tests, verification, audit evidence
Hmemory	Trajectory judgments that should not be forgotten in the future	logs, bugs, retrospectives, analysis

An implementation changes the carrier shape of a commitment: the same semantic commitment transforms from “a change obligation not yet fulfilled” into “a stable, recoverable fact in code, tests, owner docs, and logs.”

Hrepo describes only the commitments that have been accepted by the system and need to be retained and recovered. It excludes free uncertainty that has not yet been clarified, assigned, or verified. The latter is recorded separately as:

F_repo = free semantic uncertainty in the repository not yet bound
         to a stable commitment, owner, or proof.

Therefore, Frepo is not a component of Hrepo. It is more like unbound energy floating around the semantic commitments: when requirements are not yet clear, owners not yet determined, tests not yet proven, audits not yet closed—the commitment has emerged but has not yet settled into a stable repository structure.

5. Energy Redistribution Is About Authority Weight, Not File Count

Each folder should not be naively viewed as a separate energy bin. After a requirement is turned into code, the requirement file does not disappear; after an owner doc is updated, the input file still exists. What truly changes is the active authority of the same semantic commitment across different carriers—the redistribution of interpretive power, constraining power, and proving power.

For example, a commitment initially appears in raw input:

"Hidden form fields should not participate in submission."

After it enters the requirement, the raw input is still retained, but the direct interpretive authority for the current implementation transfers to the requirement. After it enters an architecture owner doc, long-term baseline interpretive authority transfers to the owner doc. After it enters code and tests, behavioral execution and proving authority transfer to implementation and verification. After it enters a bug note or log, historical judgment becomes a recoverable memory for future sessions.

Therefore, a more accurate statement is:

Files are not conserved.
The effective weight of semantic commitments is redistributed among multiple carriers.

Within a closed slice, unless an explicit human decision changes the scope, Hrepo should not increase or decrease out of nowhere. What truly should decrease is Frepo—the free semantic uncertainty that has not yet been bound, assigned, or verified.

The goal of AGE can be written as:

preserve H_repo while reducing F_repo.

Requirement clarification, owner-doc alignment, tests, verification, and closure audits bind commitments from a free, vague, driftable state into a stable, recoverable, provable form.

In PHS, R dissipates physical energy H; in AGE, Hrepo represents the total semantic commitment that should be preserved as much as possible, and should not be treated as an object of dissipation. Later, the term R-flow will refer to reducing Frepo—that is, reducing the free uncertainty generated when the same semantic commitment is not yet bound, assigned, or verified.

6. q and p: Stable State Representation and Change Obligation Representation

If we view Hrepo as a scalar defined on some phase space, that phase space requires at least two classes of conjugate variables.

It can be written as:

H_repo(q, p).

Here I borrow the notation q and p to represent two complementary semantic dimensions in AGE, not to treat them as physical position and momentum.

q is the stable state representation:

q_i = the current form in which a certain semantic commitment exists
      within the stable structure of the repository.

It answers: what the system is now.

p is the change obligation representation:

p_i = the directional pressure that a certain semantic commitment exerts
      on future evolution.

It answers: why the system needs to move next, and in which direction.

A simple example explains why the q/p duality is still needed even in one-dimensional cases. Suppose the semantic commitment is:

c = "administrators can export CSV (comma-separated value) files."

When the code currently has no CSV export, two completely different situations can exist:

Situation	qc	pc	AI's expected action
CSV explicitly out of scope	currently unsupported	no change obligation	should not implement
CSV is the top-priority active requirement	currently unsupported	strong change obligation	should implement per plan

Looking only at q, both are “currently unsupported.” But p is completely different.

Conversely, if the current code supports CSV but an owner doc decides to remove it, qc remains “currently supported” while pc becomes a reverse change obligation. Without p, the AI cannot distinguish “stable existence” from “should be deleted but not yet deleted.”

In the AGE documentation system, q is primarily carried by these materials:

Current baselines in docs/architecture/;
Component contracts in docs/components/*/design.md;
Live code and exported types;
Passing tests and examples;
Schema, public contracts, runtime behavior.

p is primarily carried by these materials:

Active plan;
Backlog or audit findings;
Failing test;
Bug report;
Open question;
Stale-doc conflict;
Closure gate;
Human decision pending.

This is only a tendency of responsibility, not a fixed directory mapping. The same file may simultaneously carry both q and p. A requirement describes both the target state and the implementation obligation; a plan records both the current baseline and the closure pressure; a bug note records both historical facts and imposes constraints on future changes.

7. Development Is Converting Legitimate p into Stable q

A correct implementation in AGE converts legitimate change obligations into stable state commitments. “Completing the task” is only the surface narrative; what really matters is whether this change has entered a recoverable, provable repository structure.

Again take CSV export as an example.

In the table below, T(p) denotes the total tension or pressure of change obligations—not a new physical energy, but a marker for “why the system still needs to evolve.”

Before implementation:

Component	State
Hrequirement	high, requirement carries "CSV support needed"
Howner	low or needs update, owner doc hasn't absorbed the capability
Hbehavior	low, code not yet implemented
Hproof	low, no tests or verification
T(p)	high, plan/backlog holds change pressure

After implementation:

Component	State
Hrequirement	still present, but unclosed obligation decreases
Howner	increases if it becomes a stable capability
Hbehavior	increases, code carries behavior
Hproof	increases, tests and verification carry evidence
Hmemory	increases, log/audit records closure
T(p)	decreases, change obligation released

In engineering language, this is:

active requirement / plan pressure
→ owner baseline / code behavior / proof / memory

The commitment did not disappear; it only transformed from “an obligation to be fulfilled in the future” into “a stable fact the current system already supports.”

This also explains why a closure audit should not merely look at checkboxes. - [x] only indicates that the executor claims something is done. The real question is: has this p been transformed into stable q, or has it merely been moved from plan to summary, from summary to log, from log to the next round of follow-ups?

8. J-flow and R-flow: Routing Is Not Dissipation

In PHS, J represents the lossless interconnection structure, and R represents dissipation. AGE likewise needs to distinguish two completely different classes of actions.

J-flow and R-flow here are engineering labels created in this article by borrowing cybernetic language; they are not standard control-theory terms.

J-flow is the transport and transformation of semantic commitments along the correct topology.

Examples:

Raw input is recorded in docs/input/;
Requirements are synthesized into a requirement;
Stable rules enter an owner doc;
A plan references owner docs and the live baseline;
Traceable links are established among code/test/log/audit.

These actions themselves do not necessarily reduce uncertainty. They mainly let commitments flow along the correct topology and avoid being stuffed into wrong positions.

R-flow is what truly reduces Frepo:

A human explicitly cuts scope;
A requirement writes testable acceptance criteria;
An owner doc absorbs a stable baseline;
Automated tests prove behavior;
Focused verification exercises real paths;
An independent closure audit overthrows or confirms a completion narrative;
A bug note records a non-obvious root cause, reducing the risk of future drift.

This distinction is critical. A great deal of seemingly diligent documentation work is actually only J-flow:

Moving ambiguity from input to discussion;
Writing an undecided design into a plan;
Writing a plan summary into a log;
Turning preliminary audit findings directly into a backlog;
Writing “should test” as a closure gate, but never truly executing it.

These may be necessary steps, but they mainly change the location of free semantic energy without truly eliminating it. The real danger is mistaking J-flow for R-flow—mistaking “information moved” for “the system converged.”

9. Park Transformation: From Chat Coordinates to Repo Coordinates

From the nonlinear control perspective, the significance of the Park transformation is that it converts the rotational couplings hidden in time-varying three-phase coordinates into d-q coordinates, where power relationships and interconnection structure are easier to identify.

A similar move exists in AGE. The raw chat, PM materials, and discussions in a long context constitute a time-varying, strongly coupled, implicit coordinate system. Requirements, architecture, execution, proof, history, and assumptions are all mixed together. In this coordinate system, the AI can easily mistake exploration for baseline, plans for facts, and historical judgments for current contracts.

The docs/ system performs the function of transforming this mixed semantic field into more stable repo coordinates:

Coordinate	Responsibility
`docs/architecture/`	Current canonical architecture and owner precedence
`docs/components/`	Component-level contracts and schema semantics
`docs/plans/`	How this round of work will close
`docs/logs/`	What happened and short-term context
`docs/bugs/`	Non-obvious defects and regression risks
`docs/analysis/`	Exploration, comparison, rejected directions
`docs/testing/`	Manual or exploratory proof
live code/tests	Current implementation facts and executable evidence

This step is more like a coordinate transformation: it turns a hidden semantic interconnection structure into a routable, auditable, recoverable topology. Document classification is only the external form of this coordinate transformation.

One could say:

AGE's document system resembles a Park-style re-coordinatization:
it expresses the time-varying, implicit, strongly coupled semantic quantities
in chat into more stable, routable, auditable responsibility coordinates
in the repository. This process is not lossless transformation; it is a
structured transcription that includes interpretation, assignment, and
evidence binding.

10. Space, Time, and Conservation

If we continue unfolding the energy-function language, “space” and “time” in AGE can also receive a clearer explanation.

Here space refers to the semantic responsibility space, not the filesystem path itself:

space = the set of positions where a commitment can be placed,
        interpreted, constrained, and proven.

It can also be called:

space ≃ semantic ownership topology.

For example, the same commitment “should hidden form fields participate in submission” might simultaneously reside in:

docs/architecture/form-validation.md;
docs/architecture/data-domain-owner.md;
runtime code;
validation tests;
a historical bug note;
plan closure evidence.

These positions are more like coordinate axes; together they define the spatial distribution of this commitment in the repository, rather than forming a before-and-after sequence of stages.

Here time refers to the discrete evolution sequence of the repository state, not the natural calendar:

time = sequence of repository state transitions across sessions.

A plan closure, an audit overturn, a commit, a full-green baseline, an owner-doc update—these are all events in AGE time.

AI does not have human continuous memory. Therefore, AGE time is not psychological time but externalized, recoverable repository time. If a decision exists only in chat and never enters the repository, it barely existed in AGE time at all.

From this, we can define two important homogeneities.

Temporal homogeneity: When the same repository state is re-read on different dates, in different AI sessions, and in different context windows, the same set of effective commitments and execution rules should be recovered.

This is the deep meaning of file-in/file-out:

temporal homogeneity = session translation invariance.

If the AI knows today that a feature is out of scope, but tomorrow in a different session does not know it because it was only written in chat, then temporal homogeneity is broken and Hrepo suffers a semantic leak.

Spatial homogeneity: The same type of semantic commitment, no matter in which local feature it appears, should follow the same ownership, routing, and proof rules.

For example, a permission commitment should not bypass the permission owner doc just because it appears inside a CSV export button; schema authoring semantics should not bypass compiler/runtime contracts just because they appear in an example; a complex host capability should not leak directly into the core scope just because the current implementation makes it convenient.

AGE space is not a uniform Euclidean space but a responsibility space with topology and curvature:

Protected areas are high-curvature zones; entering them requires a change in trajectory;
Owner docs are centers of a potential field; nearby changes will be pulled back toward the baseline;
Stale docs are coordinate singularities and should not be taken at face value;
External integrations are open ports that may inject or extract commitments;
Audits are observation surfaces, not sources of fact.

Therefore, AGE does not require all spatial points to be homogeneous. It requires homogeneity within the same type of responsibility region, and that cross-region transitions obey clear topology.

11. Immersion and Invariance: From Attractor to Target Manifold

The core idea of Immersion and Invariance is to first construct a target manifold, rather than estimating all unknown parameters accurately. Immersion means embedding the desired low-dimensional target dynamics into the original system’s state space so that the target behavior becomes a set of state relationships the system can reach. Invariance means that once the trajectory lands on this set of relationships, the system evolution will not take it off the manifold. The task of the controller or observer is to make the trajectory converge to this manifold and maintain self-consistent evolution on it.

The relationship to the attractor concept can be understood this way: the attractor answers “what structure the system should converge to in the long term,” while Immersion and Invariance answers “when unknown parameters and local unobservability exist, how to construct a convergent, maintainable target manifold.” The former defines the long-term structure; the latter gives a control-design image for making the trajectory enter and stay near that structure.

In AI development there are also massive “parameters” that can never be fully known:

The product manager’s complete true intent;
Future user behavior;
The full boundaries of external systems;
All the historical reasons in legacy code;
What the next AI session will misunderstand;
The real evolutionary pressure on a certain abstraction six months later.

Traditional approaches easily fall into two extremes: either try to clarify all unknowns before acting, or swallow all unknowns and code directly.

AGE is closer to the Immersion and Invariance compromise:

Do not require knowing all parameters; only require that the current slice
be embedded into, and converge to, a closable invariant manifold.

Corresponding to AGE, owner docs define the long-term attractor; the current plan’s goals, non-goals, accepted assumptions, verification gates, and closure audit define the local target manifold for this slice. A slice does not have to resolve all unknowns, but it needs to state which local manifold it is embedded into, and why it will not escape this manifold after completion.

This manifold is jointly defined by the following materials:

goals;
non-goals;
owner-doc invariants;
accepted assumptions;
blocking assumptions;
verification gates;
closure audit;
live code baseline.

What a plan should really spell out is:

This slice is permitted to ignore X because X is orthogonal to this closure.
This slice needs to resolve Y because Y changes current contracts or
user-visible behavior.

This does not give a green light to vague requirements. On the contrary, it demands the classification of uncertainty: which unknowns can remain unknown, and which must be eliminated first through human decisions or owner-doc alignment.

12. Structure-Preserving Observer: Audit Is Not Another Narrative Source

The key inspiration from structure-preserving PHS observer design is: an observer can preserve the system’s original structure rather than constructing a separate estimator disconnected from the system topology.

AGE’s audit should be the same. A good closure audit re-observes the system state along the same set of owner-doc precedence, live code, tests, logs, and plan gates; the implementer’s completion narrative is merely material to be verified.

This is also why a closure audit in AGE should not merely ask “is the task done,” but should ask:

Has the live behavior truly landed;
Does the owner doc still describe the current baseline;
Do the tests protect the commitment rather than an accidental implementation;
Are the plan’s Goals/Non-Goals still honest;
Does the closure evidence exist in the repository, not just in a summary;
Have in-scope defects been downgraded to vague follow-ups;
Has J-flow been misreported as R-flow.

If an audit does not preserve structure, it becomes another high-density narrative source. It may create new findings, new backlogs, a new sense of completion, without actually reducing Frepo.

Thus, the audit in AGE should resemble a structure-preserving observer: it re-estimates the system state according to the existing fact topology, and calibrates its estimation with live repo evidence; it does not create a separate fact topology.

13. Implications for AGE Practice

The value of this nonlinear control analogy for AGE practice lies in pointing out several directly improvable methodological points. New terminology is meaningful only when it helps distinguish real engineering actions.

1. Plans Should Explicitly Write the Reference Set

Writing and reviewing code both require materials beyond the previous-stage file. A plan can more explicitly require listing the reference constellation for this slice:

## Reference Set

- Context / routing:
- Active owner docs:
- Live code routes:
- Tests / verification baseline:
- Logs / bugs / known regressions:
- External contracts:
- Plan / audit evidence:

This can prevent the AI from treating the plan as the sole source of truth.

2. Plans Should Explicitly Write the Commitment Phase State

Current plans already emphasize baseline, goals, non-goals, and closure gates. The nonlinear control perspective further asks to spell out q/p:

## Commitment Phase State

- Stable state now (`q`):
- Active change pressure (`p`):
- Target stable state after closure:
- Proof that `p` was converted into stable `q`:
- Remaining pressure and why it is non-blocking:

This can distinguish “the behavior currently does not exist because it is stably unnecessary” from “the behavior currently does not exist but needs to be implemented.”

3. Closure Audit Should Check Semantic Conservation

One more question can be added:

Did any in-scope commitment disappear, weaken, or move to a non-authoritative artifact?

This is more accurate than “were the documents updated.” What we truly need to avoid is commitments leaking during transformation.

4. Owner Docs Should Write Stable Commitments

For important owner docs, structures like the following can be gradually added:

## Stable Commitments

## Allowed Variation

## Drift / Leakage Signals

## Correction Path

This makes owner docs more like structural equations than instruction manuals.

5. Audit Prompts Should Distinguish J-flow and R-flow

During an audit, one should ask:

Which changes merely routed commitments between artifacts?
Which changes actually reduced free semantic uncertainty through
decision, proof, or owner-doc alignment?

This avoids mistaking “more documents were written” for “the system has become more convergent.”

14. Conclusion: The Nonlinear Dynamical System Control Image of AGE

If AGE is reinterpreted under the lens of nonlinear dynamical system control, it can be seen as a structure-preserving AI engineering control system. PHS provides the representative vocabulary of energy, interconnection, dissipation, and ports; Immersion and Invariance supplements the image of a target manifold, unknown parameters, and trajectory convergence.

This image can be summarized as:

Hrepo is the total semantic commitment that should be conserved across sessions;
q is the stable state representation of commitment;
p is the change obligation representation of commitment;
Development is the conversion of legitimate p into stable q;
J-flow is responsible for routing commitments along the correct ownership topology;
R-flow is responsible for reducing free semantic energy that is unbound, unverified, and unassigned;
The docs system is a Park transformation from chat coordinates to repo coordinates;
File-in/file-out maintains temporal homogeneity, i.e., session translation invariance;
Owner docs, plans, tests, audits, and logs together form a multi-port coupled convergence mechanism.

The core judgment is:

The disorder in AI development is not just noise; it is often semantic energy that has not yet been correctly coordinatized. The next step for AGE is to more clearly model how these semantic commitments are injected, routed, stored, transformed, proven, and conserved, rather than simply piling on more processes.

Therefore, AGE can be understood as:

A nonlinear dynamical system control image for software engineering under high-speed AI perturbation: use owner docs to define the attractor, use plans to embed the current slice into a local target manifold, use routing to preserve structure, use verification/audit to reduce free semantic energy, and use logs/bugs to preserve the trajectory memory across time.

Appendix: PHS Mathematical Background

PHS is a structured modeling framework developed by van der Schaft, Maschke, and others around the 1990s around nonlinear systems, generalized bond graphs, and port interconnections, and is closely intertwined with the passivity-based control and energy shaping work of Ortega and others. Its difference from ordinary state-space models lies in putting the energy function and interconnection topology first. Mechanical systems, electrical circuits, motors, power networks, and fluid networks can all be viewed under this perspective as combinations of energy-storage elements, dissipative elements, and port interconnections.

Interconnection and Damping Assignment Passivity-Based Control further applies this approach to control design: the controller does not simply cancel nonlinearities, but reconfigures the closed-loop system’s interconnection structure and damping distribution so that the closed-loop energy function has the desired shape. Structure-preserving observers, PHS network stability, and passive interconnection of microgrids all inherit the same judgment: preserving structure is often more robust than flattening it.

A common form of finite-dimensional PHS is:

dx/dt = (J(x) − R(x)) ∇H(x) + G(x) u
y = G(x)ᵀ ∇H(x)

where:

Symbol	Meaning
x	System state, e.g., mechanical position/momentum, circuit flux linkage/charge
H(x)	Total energy function of the system
∇H(x)	Gradient of energy with respect to state, also often called co-energy variables; under specific port choices can correspond to conjugate quantities like force, voltage, current
J(x)	Skew-symmetric interconnection matrix, satisfying J(x)ᵀ = −J(x), represents lossless energy routing
R(x)	Positive semidefinite dissipation matrix, satisfying R(x) = R(x)ᵀ ≽ 0, represents dissipation such as resistance, friction
G(x)	How external ports couple into the system
u	Port input, e.g., applied voltage, external force
y	Port output, usually paired with u to form input power yᵀu

Taking the derivative of H along system trajectories:

dH/dt = (∇H)ᵀ ẋ = (∇H)ᵀ J ∇H − (∇H)ᵀ R ∇H + (∇H)ᵀ G u.

Since J is skew-symmetric, for any vector a we have aᵀ J a = 0. Therefore:

dH/dt = − (∇H)ᵀ R ∇H + yᵀ u.

If there is no dissipation and no external input, i.e., R = 0 and u = 0, then dH/dt = 0—energy is conserved. If u = 0 but R ≽ 0, then dH/dt ≤ 0—the system energy is non-increasing. This is the fundamental reason why passivity-based control and energy shaping can work.

Integrating the above from 0 to t gives the passivity inequality:

H(x(t)) − H(x(0)) ≤ ∫₀ᵗ y(τ)ᵀ u(τ) dτ.

It expresses that the increase in stored energy will not exceed the total energy injected through the external ports. The system can store energy, release energy, and dissipate energy, but cannot create energy out of nothing.

This inequality explains why PHS is particularly suitable for network systems. If two passive systems are interconnected in a power-conserving way, for example:

u₁ = −y₂, u₂ = y₁,

then the sum of the two port powers is:

y₁ᵀ u₁ + y₂ᵀ u₂ = y₁ᵀ (−y₂) + y₂ᵀ y₁ = 0.

The interconnection itself neither injects nor dissipates energy; it only moves energy between the two subsystems. Therefore, lossless interconnection of passive systems remains passive. This property is key to extending PHS from single motors, robot arms, and circuits to microgrids, networked systems, and large-scale physical systems modeling.

The minimal canonical Hamiltonian system can be written as:

x = (q, p),

[ dq/dt ]   [ 0  I ] [ ∂H/∂q ]
[ dp/dt ] = [ −I 0 ] [ ∂H/∂p ].

Here q is a position-like variable, p is a momentum-like variable, and the matrix in the middle is the most basic symplectic structure. Its role is not to dissipate energy, but to let energy reciprocally convert between “positional potential energy” and “momentum kinetic energy.”

If dissipation and ports are added, we obtain a more general form:

[ dq/dt ]   [ 0  I ] [ ∂H/∂q ]
[ dp/dt ] = [ −I 0 ] [ ∂H/∂p ] − damping terms + port input terms.

The reason the Park transformation is important in electric motors is that it converts the time-varying rotational relationships in stationary three-phase coordinates into d-q coordinates, making speed-dependent cross-couplings easier to identify as part of the interconnection structure. From the energy perspective, such a cross-term is not an ordinary disturbance, but a structural channel through which energy flows among the d-axis, q-axis, and mechanical momentum.

This fact can be seen from a two-dimensional skew-symmetric matrix:

S = [ 0  −1 ]
    [ 1   0 ],  Sᵀ = −S.

For any 2D vector z, we have zᵀ S z = 0. If a local dynamic contains a term ω S z, it will cause the two components of z to rotate mutually and exchange energy forms, but it will not change the quadratic energy ½ zᵀ z:

d/dt (½ zᵀ z) = zᵀ ż = zᵀ (ω S z) = ω zᵀ S z = 0.

This is why the PHS perspective cautions against the intuition to “cancel all cross-coupling terms.” Some cross-terms are not errors, but the manifestation of system topology in local coordinates.

AGE Application Development Template

Attractor Before Harness: A Methodology for Large-Scale AI Development

canonical — Thu, 21 May 2026 12:08:33 +0000

In systems where AI deeply participates in development, the first-principles question is not "how to constrain AI's behavior," but "what long-term structure the system should converge to."

Only after this direction is clearly defined can mechanisms like harness, guardrail, verification, audit, and closure truly have meaning. Otherwise, they are merely efficiently solidifying a wrong baseline.

This claim is inevitable because AI collaboration pushes "trajectory convergence"—a problem long treated as an add-on in software engineering methodology—to a position where it must be explicitly modeled.

1. Why Harness Is the First Thing People Think of When Discussing AI Engineering

In current discussions about AI-assisted development, the most common terms are:

guardrail
verification
review
feedback loop
agent harness

This set of intuitions assumes a single premise by default:

The correct direction of the system is already known.

Given that premise, the problems naturally become:

How to limit deviations
How to expose failures as early as possible
How to make reviews stricter
How to prevent agents from going rogue

This language suffices for small tasks. For a script, a CRUD page, or a local bug fix, you usually already know "what a correct result looks like"; the remaining work is mainly about execution and verification.

But what truly makes large systems difficult is often not "how to prevent crossing the line," but "which path is the right long-term structure in the first place."

To answer this question, we must first recognize one thing: all current harness-type mechanisms rest on an implicit premise—the evaluation unit is primarily state, and trajectory convergence relies on the developer's tacit sense of direction as a backstop. AI collaboration removes precisely this backstop.

2. The Backstop That Has Been Removed

Open any mainstream engineering methodology—TDD, DDD, Clean Architecture, Agile, Code Review culture—and their first-class evaluation targets are almost always state:

Evaluate "whether this PR is correct," not "whether the cumulative direction of the last 100 PRs is correct."
Evaluate "whether the current architecture is clean," not "whether the architecture is being continuously pushed toward a stable form during evolution."
Evaluate "whether tests cover the current behavior," not "whether the test suite itself has been corroded by implementation details."

Traditional methodologies are not entirely without trajectory awareness—refactoring, technical debt, code smells, evolutionary architecture, and Lehman's laws of software evolution all touch on trajectory. But these concepts exist in the methodology as corrective mechanisms and diagnostic vocabulary, not as fundamental objects. When a theory must continuously introduce negative concepts like "debt," "fragility," and "corrosion" to retroactively acknowledge trajectory problems, it reveals that its foundational category set lacks a positive trajectory object.

This state-centric paradigm has worked for so long because human engineers themselves act as a perturbation source with low frequency and stable directional sense. A person writes a few hundred lines of code per day; each perturbation is small in magnitude, and a continuous sense of direction is maintained in the mind. State-level quality assurance combined with the programmer's implicit directional sense ensures that the trajectory does not drift.

AI collaboration removes this backstop. AI is not a faster programmer; it is a structurally different perturbation source:

High frequency: A single session can generate hundreds of lines of code spanning multiple modules in minutes.
High magnitude: Each generation can introduce cross-boundary structural changes.
No persistent directional sense: Each session is independent, with no implicit architectural judgment carried across sessions.
Highly reasonable locally: Interfaces, types, tests, and documentation can be produced simultaneously, and each piece passes inspection when viewed in isolation.

The last point is crucial. In AI collaboration, all state-level checks can pass while the system as a whole drifts continuously.

Plan 76 of nop-chaos-flux is a typical example. An attempt to remove the local state mirror in array-editor / key-value immediately caused 11 test failures. But what was exposed was not a specific bug, but a deeper fact: the tests themselves had become tightly coupled to the timing of the old implementation. From a state perspective, every incremental change had passed review and CI; from a trajectory perspective, the test suite had unconsciously drifted into a position where it could no longer support structural evolution.

Traditional theory has a symptom name for this—"test fragility"—but a symptom name is a cross-sectional diagnosis. It does not name the process by which 100 legitimate commits accumulate into fragility. Trajectory problems are process problems, and process problems require a process language.

Thus, the issue is not that AI makes old problems worse, but that AI pushes trajectory problems from an occasional repair target to a high-frequency, first-class citizen. For these problems to enter the methodology's field of view, engineering methodology must adopt "trajectory" as a fundamental category.

3. Dynamical Systems Language: Making Trajectory Problems Explicit

In mathematics and physics, a dynamical system refers to a system whose state evolves continuously over time, with each next state depending on the current state. What we care about is not just whether it is correct at a single moment, but what kind of trajectory it traces out over time.

Translated to large-scale AI development, this language corresponds to four mutually defining fundamental objects:

State Space: All possible implementation states the system can evolve into under current constraints.
Attractor: The stable structure to which the system is repeatedly pulled back during long-term evolution.
Trajectory: The actual evolutionary path left behind after each round of generation, verification, and correction.
Control: The various mechanisms that continuously influence the trajectory through local signals.

The repository, under existing constraints, has a set of all possible combinations of code, documentation, and tests it could evolve into—this constitutes the state space. The continuous actions of humans, AI, review, CI, and documentation updates constitute the evolution rules. The interaction of these two forms the live repo history, which is the trajectory. The attractor is the stable structure to which the system is repeatedly pulled back during long-term iteration.

One point must be made clear: this language is not a "more elegant way of saying things," but the foundational language of a new ontology. The four concepts—state space, attractor, trajectory, control—define one another; if one is missing, the other three cannot be rigorously expressed. Attempting to translate these concepts into the language of the old ontology (architecture, constraints, goals, process) inevitably incurs information loss—this is the root of misreadings like "Isn't Attractor Guided Engineering just Harness?"

The relationship among the four objects is:

State Space → Attractor → Trajectory → Control

This is not a rhetorical ordering; it is a logical dependency. Without defining the state space, there is no talk of an attractor; without defining the attractor, one cannot judge whether the trajectory is drifting; without trajectory judgment, control has no target.

The "before" here refers to logical priority: in execution, attractor and harness co-evolve in a closed loop, but the attractor can be conceptually defined independently of the harness, while the harness cannot be conceptually defined independently of the attractor (to correct deviation, toward what?). This asymmetry corresponds to the relationship between final cause and efficient cause in dynamical systems—acknowledging co-evolution does not weaken the "before" claim. Final cause and efficient cause act together in physical systems as well, but the final cause remains the logical prerequisite for the efficient cause.

4. What Exactly Is an Attractor

Take the well-known Lorenz attractor as an example. It is implicitly defined by differential equations. It is not a checklist that enumerates all correct trajectories in advance, nor is it a simple boundary. Within the attractor, local trajectories are highly complex and appear nearly chaotic in the short term, yet the whole does not fly apart randomly; it is always pulled back into the same type of geometric shape.

Lorenz attractor: Local trajectories are highly complex, yet the whole is still constrained by a stable structure. Chaos does not equal randomness; local unpredictability does not mean the whole is out of control.

An engineering attractor works the same way. It is more like an "equation-defined manifold" than "a list of all legal points enumerated one by one." The equation does not write out every point on the manifold in advance; it only stipulates which relations must hold. Points satisfying these relations naturally fall within the same structure.

Key difference from traditional architecture concepts: DDD and Clean Architecture also emphasize long-term structure, but they treat that long-term structure as a target state—the methodology's job is to "reach X." A trajectory ontology treats the long-term structure as an attractor—the methodology's job is to "return to the vicinity of X no matter how far you are pushed away." The second perspective addresses stability under perturbation. This is exactly the core problem in AI collaboration scenarios, and exactly the problem for which traditional methodologies lack first-class conceptual tools.

To prevent conceptual drift, an attractor in engineering can be strictly divided into three layers:

Structural layer (the attractor itself): A small number of high-order invariants, such as how responsibilities are divided, how boundaries are established, and which structural relationships cannot be violated.
Carrier layer (the engineering carrier of the attractor): Externalizing these invariants into versionable, auditable documents.
Implementation layer (the instantaneous projection of the attractor): The parts of the current code that actually embody these invariants.

The attractor is not the document; the document is the carrier of the attractor. The attractor is not the code; the code is an instantaneous projection of the attractor.

This layering is important because it resolves a common confusion: "When architecture docs and code conflict, which one do we follow?" The answer is not "which one is more authoritative," but "what question are you asking?" If you are asking about current implementation behavior, the code is authoritative. If you are asking where the system should converge, the docs are authoritative. If you are asking why a certain path was abandoned, logs/bugs/analysis are authoritative. Each layer is authoritative only for its corresponding question.

5. The Repository Begins to Bear the System's Truth, Making Harness Infrastructure

Once AI deeply participates, the repository is no longer merely an external projection of human cognition; it begins to become the sole carrier of the system's truth. No one person fully grasps all the design details in the system, and no one can answer questions about the system's design without consulting the project source code. What the next session can re-read is not the full intent in the author's mind, but the code, diffs, logs, tests, and documentation.

This has a direct engineering consequence:

Generation and acceptance must be genuinely separated.

Generation actions can be completed at high speed by AI within the same context, but acceptance can no longer rely on that generative context itself. You must return to the external evidence in the repository and re-evaluate:

Whether the behavior was truly implemented.
What the current baseline actually is.
Which materials are authoritative.
Whether this "completion" is just a feeling of completion.

It is precisely because the repository begins to bear the system's truth that generation and evaluation must be separated; and it is precisely because generation and evaluation are separated that the harness is upgraded from a "safer engineering habit" to necessary infrastructure.

In traditional collaboration, harness is optional discipline; in AI collaboration, harness is the necessary condition for making trajectory judgment possible. The reason is this: while AI generates code, it also generates all the materials for judging whether that code is correct—types, tests, documentation, completion summaries are all produced together by the same context based on the same understanding. If that understanding is skewed, all "verification evidence" will be skewed consistently in the same direction, not contradicting each other, yet entirely wrong as a whole. This self-verification trap is naturally weakened in human collaboration—CI rules, reviewers, spec documents are all independent external standards maintained by different cognitive subjects. AI collaboration breaks this independence, so we must use engineering means—fresh sessions, independent audits, returning to live repo forensics—to artificially reconstruct the separation of generation and acceptance.

Under repo-truth conditions:

test / lint / audit functions more like measurement.
owner doc / plan / closure functions more like constraints.
logs / bugs / discussions functions more like trajectory records and externalized memory.

6. Three Most Common Ontological Confusions

First, mistaking the attractor for a boundary.

Boundaries answer "what cannot be done," and violating them causes an error immediately. Attractors answer "where the system should converge in the long run." A single violation may not cause an error, but persistent deviation causes structural decay. Boundaries define forbidden zones; attractors define stability zones. Confusing the two downgrades the attractor to a stricter guardrail, missing its core capability of handling "stability under perturbation."

Second, mistaking the attractor for a stronger guardrail.

Guardrails operate at the execution layer (checked for each action), while attractors operate at the direction layer (whether the accumulation of multiple actions trends toward it). Understanding it as stricter governance, denser constraints, or stronger auditing still reduces the primary problem to the control layer. The root of this reduction is the failure to recognize that the two belong to different levels.

Third, mistaking the attractor for another way of saying "control target."

The phrase control target seems very close, but it assumes that a control framework is already in place. Under a trajectory ontology, the attractor's role is to provide the final cause for control—it is prior to control, not within it. If the attractor is not defined first, so-called control has no target, and mechanisms like harness, guardrail, verification, and audit have no unified meaning.

7. In the nop-chaos-flux Repository, the Attractor Is First and Foremost `docs/architecture/`

If the attractor remains only at an abstract level, it has no real engineering significance. For nop-chaos-flux, what first bears the attractor is the owner-doc system with precedence within docs/architecture/.

In this repository, the engineering landing point is clear: the specification definitions under docs/architecture/ come first, followed by convergence mechanisms like plan, verification, audit, and logs.

Within docs/architecture/, this "equation layer" also has a clear precedence:

docs/architecture/README.md is responsible for explaining the architecture hierarchy and reading order.
flux-design-principles.md handles the direction layer, explaining design intent and stable principles.
frontend-programming-model.md handles the top-level specification layer, defining primitive identity, macro boundaries, and hard invariants.
flux-core.md handles the current codebase-wide baseline.
Narrower architecture docs define local contracts within their respective topics.

In nop-chaos-flux, the structural layer of the attractor is not an abstract "correct architecture," but is defined by a small number of high-value invariants: the closed set of seven primitives, the compile-first pipeline, the Template/Instance separation, Data/Capability orthogonality, the unified renderer/hook contract, and the dependency direction flux-core → flux-formula → flux-compiler → flux-action-core → flux-runtime → flux-react.

These are not parallel pieces of governance material; they are structural equations fixed by owner docs. The value of architecture lies not in describing everything, but in making wrong structures unable to continue existing legitimately.

It is precisely for this reason that many truly important convergence actions in this repository end up manifesting as "a certain old structure being excluded from the legitimate state space."

The final removal of CompiledSchemaNode is a typical example. It was not merely a refactoring cleanup; it demonstrated that once the new baseline of template/instance separation was established, the old intermediate structure, though still functional, no longer belonged to the correct structure and was thus excluded.

Similarly, the three-way split of flux-compiler / flux-action-core / flux-runtime is not simply a matter of "extracting two more packages," but a case where the attractor became more precise: the system was not just "able to run," but was further converged into a more stable responsibility structure.

8. What Is Harness

If the attractor solves "what is the direction," then harness solves:

How to continuously measure, correct, and update the system's trajectory through local signals.

The term "harness" here does not mean the narrow testing harness, but a broader execution scaffold. It typically includes: context routing, separation of implementation and acceptance, planning and closure conditions, verification mechanisms, audit mechanisms, diagnostic tools, and externalized memory.

In this repository, at least five layers of harness can be seen:

1. Routing Harness

docs/index.md and docs/architecture/README.md determine: what to read first for a given problem, what is the current baseline, and what is merely analysis, plan, or history.

2. Plan Harness

docs/plans/ addresses "how this round of expansion closes," not "what the system is."

Fields like current baseline, goals / non-goals, exit criteria, validation checklist, and closure audit evidence define how a local trajectory can be effectively closed.

After Plan 145's closure/audit, the newly confirmed follow-ups were broken out into Plan 146. Plan 143's closure assumptions were repeatedly overturned by fresh audits until the live repo truly crossed the line and closure was allowed. Plans here are not a to-do list, but a local convergence mechanism—they don't just list "what needs to be done now," but stipulate where this round of expansion must close, what exit criteria must be met, and what independent evidence closure requires.

3. Verification Harness

lint, check, typecheck, build, test push high-frequency, clear, automatable deviation detection to the machine layer ahead of time.

4. Audit Harness

Not all deviations can be caught by automated rules. Higher-level semantic drift, structural bias, false completion, and problems that are locally self-consistent but globally distorted still require independent auditing.

Auditing itself is also a closed loop: discover deviation points, filter out conflicts and false problems, and return to the live repo for confirmation. The focus of high-quality auditing is not to pile up more problems, but to eliminate invalid problems as quickly as possible.

In this repository, one of the most critical harness rules is: never let the same context serve as both implementer and completion judge. Completion must be re-evaluated against the live repo by a fresh session or independent audit. The reason the closures of Plan 143 and Plan 145 carry weight is precisely because "completion" is not self-reported by the implementer, but comes from an independent convergence judgment.

5. Memory Harness

docs/logs/, docs/bugs/, docs/discussions/ constitute cross-session externalized memory.

This layer is especially important because for AI, "why that understanding is invalid" is itself part of the system's memory. It is often insufficient to retain only the final conclusion; you must also retain:

Which premise has been falsified
Which path has been proven to diverge
Which terminological translation degrades the problem
Which "completed" judgment was later overturned by the live repo

Without this memory harness, the system loses a portion of its historical trajectory information each time.

True closed-loop is not "define the attractor once, then execute harness forever," but "define attractor → expand → correct → update attractor → expand again." The three-way split of flux-compiler / flux-action-core / flux-runtime is an example of the attractor being refined by practice before continuing expansion.

9. Why a New Attractor Is Usually Not Evolved by AI on Its Own

Even with harness in place, you cannot expect AI to slowly evolve a new attractor on its own through high-speed iteration.

At least under the training distribution and biases of current mainstream models, this generally cannot be expected to happen naturally.

To be more specific:

Current mainstream AI excels at high-speed expansion and convergence around an existing attractor.
However, it typically falls back to the average solution it has seen.
Truly novel conceptual decompositions, boundary redefinitions, and architectural languages still require a human to propose first.

The responsibility for defining a new attractor cannot be silently outsourced to AI.

In large-scale framework development, the division of labor between humans and AI cannot be simplified to "AI writes code, humans do review." The more realistic division is:

Humans define new attractors.
AI performs high-speed expansion around the defined attractor.
Harness continuously pulls the trajectory back on track.

Concepts like the separation of ActionScope and Data Scope, or lexical scoping—concepts that genuinely change the system's structural language—cannot grow by letting AI freely sample average solutions. They are new attractors that must be proposed first; only then can AI perform large-scale expansion on the new baseline.

A limitation must be acknowledged: this means the effectiveness of this methodology depends on the presence of people within the team capable of defining attractors. This is not a weakness of the methodology, but a fact it correctly identifies—architectural judgment is a scarce resource. In traditional collaboration, this judgment could partially reside in the architect's mind, transmitted through oral tradition and code review. AI has no cross-session memory; any architectural judgment not explicitly externalized does not exist for AI. The engineering contribution of this methodology is precisely to externalize this scarce resource into a versionable, auditable, inheritable repository structure so that it does not have to leave with the individual. However, if no one on the team can make such judgments at all, the methodology cannot generate them out of thin air.

10. Conclusion

The truly difficult part of large-scale AI development is not getting AI to write more code, but ensuring the system continues to converge toward the correct structure during high-speed expansion.

This convergence problem has no positive object in traditional methodologies where state is the first-class citizen—it can only be indirectly acknowledged through negative terms like "debt," "fragility," and "corrosion." For the convergence problem to become a first-class citizen object that can be expressed, discussed, and engineered, the methodology must incorporate trajectory into its foundational categories.

Whoever proposes a new attractor defines the structural baseline for the system's subsequent evolution.

Compressing this methodology to its core, only one line remains:

State Space → Attractor → Trajectory → Control.

This is not a more complex engineering process; it is a more fundamental engineering conceptual structure. Only with a structure defining where the system should converge in the long run can there be a judgment of whether the trajectory has deviated; only with a judgment of trajectory deviation can the subsequent harness, guardrail, verification, audit, and closure have a unified meaning.

In the age of AI, what is truly scarce is not more agents that can write code, but people who can first answer the question, "Where should the system converge?"

nop-chaos-flux is open source:

From Spec-Driven Development to Attractor-Guided Engineering

canonical — Thu, 21 May 2026 11:52:48 +0000

nop-chaos-flux is a low-code runtime framework built on React 19, Zustand 5, and Vite 8. It is inspired by Baidu AMIS but independently implemented from scratch based on innovative design principles. It includes a JSON Schema compiler and runtime, as well as design tools such as a report designer and Flow Designer.

The initial version of this project was completed by a single programmer in two months, developed entirely through AI automation. Unlike typical AI-assisted development, as features were continuously added, the project did not suffer from quality degradation. Instead, module boundaries became clearer, document categorization more stable, testing and auditing increasingly captured real issues, and code quality continuously improved.

I recently gave some internal sharing sessions and named this practice Attractor-Guided Engineering (AGE). Later, during code reviews, I found that many people did not truly understand it. Some operated in a way close to casual vibe coding, while others adopted a spec-driven development style similar to OpenSpec, leaning overall toward task-driven, feature-by-feature development. As the workload accumulated, inconsistencies in the code steadily built up, and deviations from the architectural design became the norm.

This article analyzes the differences between AGE and spec-driven development, and what ordinary business projects can learn from the large-scale AI engineering practices of nop-chaos-flux.

Core Hierarchy

At the heart of AGE lies the following conceptual hierarchy:

State Space → Attractor → Trajectory → Control

State Space: All possible implementation states the system can evolve into under current constraints.
Attractor: The stable structure to which the system is repeatedly pulled back during long-term evolution.
Trajectory: The actual evolutionary path preserved after each round of generation, verification, and correction.
Control: Various mechanisms that continuously influence the trajectory through local signals.

All possible combinations of code, documentation, and tests that the repository could evolve into under existing constraints constitute the state space. The continuous actions of humans, AI, review, CI, and document updates form the evolutionary rules. The live repo history created by the superposition of the two is the trajectory. The attractor is the stable structure to which the system is repeatedly pulled back over long-term iteration.

Large-scale AI development is essentially a controlled convergence problem for a dynamical system. AI expands the state space extremely fast. The key is not to add guardrails everywhere, but to first figure out: what structure should the system be pulled back to over the long term?

An attractor is not a fully written-out end point, not a roadmap, and not a "scope of permitted activity." It is a structure implicitly defined by a small set of high-order constraints: local implementations can vary, but the whole will be pulled back to the same type of form by these relationships.

In nop-chaos-flux, what first defines the attractor is not the plan, lint, test, audit, or any single spec file, but the architecture docs with precedence under docs/architecture/. In the following text, these architecture docs with owner and precedence are referred to as owner docs.

docs/architecture/README.md explicitly states: docs/architecture/ is the current final-state architecture baseline, flux-design-principles.md is the governing-principles anchor, frontend-programming-model.md holds the top-level primitives and core-boundary precedence, and other normative docs hold local precedence within their respective topics.

These documents do not enumerate all correct implementations. They define a stable structure like an equation: what primitives exist, which dependency directions are legal, which owner boundaries must not be broken, and which old patterns no longer belong to the correct state space. They first define the cluster of states that can sustainably exist, so that subsequent implementation, testing, planning, and auditing have a reference.

Plan, verification, audit, logs, bugs, testing all come later. They are not the attractor itself, but the harness that keeps the system trajectory continuously close to the attractor.

Flux/AGE is not centered on spec evolution, but on attractor definition and trajectory convergence.

Real Development History

"Architecture docs define the attractor" might sound like ordinary document governance at first, but the difference becomes clear if you carefully examine the actual development records in docs/logs/.

For example, docs/plans/371-deep-audit-2026-05-19-owner-routing-plan.md is a typical entry point. It does not directly change the code, but converges the 64 retained findings from the 2026-05-19 deep audit into an owner-routing baseline. Each finding has a unique owner bucket, priority, successor plan, and owner-doc obligation. No ownerless items, no multiply-owned items, no silent downgrade to vague follow-ups.

Its role is to first freeze how a round of deviations should be resolved, after which the subsequent execution plans close the local trajectory to concrete outcomes. docs/plans/382-deep-audit-2026-05-19-table-and-crud-owner-state-and-event-contract-plan.md resolves the table/CRUD owner state and event payload: Current Baseline declares the live status of explicit empty-array owner state and event payload, execution items fix the empty-array fallback, focused tests prove the result, docs/components/table/design.md and docs/components/crud/design.md synchronize the owner contract, and finally repo-wide pnpm typecheck, pnpm build, pnpm lint, pnpm test all pass, with the independent closure audit ses_1bd9ed593ffeVpkho4lb4wPR6p recording Verdict: acceptable.

docs/plans/388-deep-audit-2026-05-19-form-tree-widget-accessibility-plan.md demonstrates another type of closure: visible node roving focus, ArrowUp/ArrowDown/Home/End navigation, loading aria-busy/aria-describedby for input-tree and tree-select all have focused proof, but the plan explicitly rules No owner-doc update required. This shows that a plan is not just a to-do list; it is also responsible for judging whether this change modifies the owner-doc baseline.

docs/plans/400-deep-audit-2026-05-19-test-harness-reliability-plan.md and docs/bugs/62-e2e-shared-websocket-error-suppression-fix.md demonstrate the role of memory harness. The problem was not a business function failure, but that the E2E shared fixture's filter scope was too broad, filtering out real transport/runtime failures as well. The fix not only changes the code, but also adds tests/e2e/fixtures-hard-gate.spec.ts to prove it now fails, and records a rule in the bug note: if future tests genuinely expect a WebSocket failure, a per-test allowance must be used, and fixture-wide suppression must not be restored.

docs/logs/2026/05-19.md and docs/logs/2026/05-20.md are not mere daily logs. They record the focused proof of each closure slice, owner-doc rulings, repo-wide gates, independent audits, and full-green baselines.

These materials form a real chain: owner docs define the long-term structure, audits discover deviations, plans route and freeze ownership, focused proof demonstrates local results, owner-doc rulings decide whether to update, logs/bugs/testing preserve cross-session memory, and closure audits re-judge completion status from the live repo.

This is the harness in AGE. The goal is not to make each task appear more complete, but to make the system trajectory continuously return to the vicinity of the attractor.

Where OpenSpec's Structure Excels

OpenSpec is a representative spec-driven development framework that structures a category of work well:

openspec/specs/ stores the behavioral specifications of current capabilities.
openspec/changes/ stores proposed changes, including proposal.md (why change, what changes, impact), design.md (technical design when necessary), and tasks.md (implementation checklist).
changes/<name>/specs/ records spec deltas using ADDED/MODIFIED/REMOVED/RENAMED.
Archive applies the deltas back to the main specs through fixed rules.

This mechanism lowers the cost of updating specifications. OpenSpec does not require the AI to freely understand the entire requirement and then arbitrarily modify documents each time. Instead, it uses fixed sections, requirement header matching, and delta application to merge structured changes back into the main specs. This approach is well-suited for scenarios where behavioral specifications are clear and need to be parseable, archivable, and re-writable.

Where OpenSpec Is Limited

OpenSpec's spec format (Requirement, Scenario, SHALL/MUST, delta sections) is tool-parseable friendly, but is not flexible enough as a way to organize general project knowledge.

A lot of repository knowledge does not naturally grow into requirement/scenario form:

Architecture hierarchy and precedence.
History of terminology misunderstandings.
External research materials (PPT, discussion records).
Analysis conclusions from a source code audit.
Phenomena discovered through manual testing.
The elimination path of a complex bug.
Why a plan cannot be closed.

If everything must first be translated into a spec/change to gain an official place, the conversion cost is high, and the original context is also lost. External documents, discussion records, analysis reports, and bug retrospectives could directly become repository memory. Forcing them into requirement/scenario format tends to flatten the information.

In terms of execution verification, the two reflect different tool philosophies. OpenSpec's tasks.md is a checklist; /opsx:verify is an optional agent verification skill (requires manually enabling expanded workflows). archive checks task status and prompts about risks, but can still proceed after user confirmation—strict closure is left to the team's own conventions.

Flux plan, on the other hand, bakes independent closure audit in as a required step: you must start from the current baseline, write clear Goals, Non-Goals, execution items (each annotated with Fix/Decision/Proof), and Closure Gates; before marking completed, an independent sub-agent or independent reviewer must go back to the live repo and perform a closure audit. docs/plans/361-slot-contract-host-manifest-and-owner-doc-closure-plan.md puts together the current baseline, the finding ownership matrix, execution phases, closure gates, the deferred items that have been ruled on, and independent review evidence. This is not a checklist, but an execution contract that strictly defines closure conditions and requires independent audit. It emphasizes not what was done, but to what standard something counts as truly landed.

Why Spec-Driven Easily Becomes Task-Oriented

The default structure of spec-driven development easily pulls the attention of both humans and AI back to "how to complete this change."

A change typically has a proposal, design, tasks, and delta specs. This is much better than verbal requirements, but it is naturally organized around one change: why change, what to change, how to do it, which checklist items are done. Over time, spec-driven development can easily become a more formal task dispatch system.

This task orientation has a hidden risk: specs are updated, tasks are checked, archive is done, and both AI and humans get a strong sense of completion. But whether the system is truly closer to the long-term structure is not proven by the change itself. It must be verified by looking back at the architecture docs, the live repo, tests, logs, and independent audits.

If one tries to long-term maintain specs to the level of precision in Flux, the cost is usually higher. What Flux maintains is not a single specification tree, but a set of repository memories with different responsibilities: architecture docs define the attractor, plans define local trajectory closure, logs record evolution, bugs preserve complex defect diagnosis, testing preserves manual findings, analysis preserves research judgments, and audit is responsible for looking back at the live repo. Cramming all of this into a spec/change structure incurs continuous conversion cost.

Spec-driven can serve as a local harness within AGE to manage behavioral spec evolution. But it should not replace architecture docs, nor should it replace the separate repository memories of plan closure, logs, bugs, testing, and audit.

What If You Just Need to Look Up an Owner Doc?

This reveals a fundamental difference between the two approaches.

If, in Flux, you simply want to check the current owner contract of the renderer runtime, you can directly route from docs/index.md to docs/architecture/renderer-runtime.md and the relevant references. You do not need to create a change, do not need a proposal, do not need tasks, and do not need to rewrite the question into a spec delta.

If it's just research, it might go into docs/analysis/. If it's just a discovery from manual testing, it goes into docs/testing/ first. If it's a complex bug, it goes into docs/bugs/. If it's an execution closure, then a plan is written. A stable baseline change then goes back to the owner doc.

Flux's document organization is free but not arbitrary. Free means: it does not force all knowledge to first enter the same artifact workflow. Constraint means: each type of material has a clear responsibility and cannot arbitrarily compete for factual status.

OpenSpec's organization is more structured. It is good at putting proposed behavioral changes into a change package and then writing spec deltas back to main specs. But general repository knowledge routing is not the main problem it aims to solve by default.

Tasks Are Not Plans

OpenSpec's tasks.md does not correspond to Flux's plans.

tasks.md at most corresponds to the execution checklist fragment inside a Flux plan, or the todo list of the current session. It can help AI avoid missing steps, but it does not answer these questions:

What is the current live repo baseline?
What is explicitly not being done this time?
What evidence can prove it is truly complete?
Which defects cannot be downgraded to follow-ups?
Who independently verifies the completion status?

The value of a Flux plan is not in "having more tasks," but in it being a closure contract for a local trajectory.

So tasks are necessary for AI, but tasks are not the source of truth. - [x] only indicates that the executor claims an item is complete. The real proof must return to the current code, tests, owner docs, and independent review.

Sources of Change Go Beyond Spec Changes

OpenSpec's path is very clear: organize behavioral spec evolution around specs and changes.

Flux's sources of change are broader:

New requirements raised by users.
Architectural drift discovered by reading source code.
Owner boundary problems discovered by audits.
Interaction problems exposed by testing issues.
Historical regression risks recorded in bug notes.
Design judgments derived from external research or analysis.
A plan closure audit overturning a previous judgment of "completed."

These sources should not all be transformed into spec deltas first. They can first land in analysis, testing, bugs, logs, plans, or directly update architecture docs. Whether they ultimately need to become a behavioral contract depends on whether they are part of the long-term baseline.

This is the significance of Flux's organizational freedom in documentation. Information from different sources first stops at different positions, rather than being shoved entirely into a single spec evolution channel.

Why Files-In, Files-Out Matters

I have emphasized many times in sharing sessions that a best practice for AI-driven development is files-in, files-out. This is not just documentation fastidiousness—the attractor and the harness need a physical carrier.

Files-in: do not leave input only in the chat window. Even if the content is messy, first write it to a requirements file, analysis file, or plan file, and then @ this file in OpenCode.

Files-out: do not end with output just printed in the window. Important conclusions, analyses, plans, test records, bug diagnoses, and architectural constraints are all written into docs/, categorized by responsibility:

Architecture rules → docs/architecture/
Change closures → docs/plans/
Execution trajectory → docs/logs/
Manual testing findings → docs/testing/
Complex defect diagnosis → docs/bugs/
Research judgments → docs/analysis/

The point is not "write more documents." Once output is categorized and persisted, it enters the repository memory. The chat window is temporary context; files are the repository memory.

Code Is the Current Implementation Fact, Not the Only Fact

Code is the source of truth for the current implementation. Types and tests protect the current behavior. The architecture owner docs with precedence define the attractor—the structure the system should converge to over the long term. Logs, bugs, analysis, and testing record the trajectory and externalize memory.

These do not conflict. Conflicts arise in two situations:

When documents start regurgitating implementation details that easily rot.
When the completed state of a document is taken as proof that the code is already correct.

OpenSpec's behavior-first boundary actually avoids the first problem to some extent: behavioral specs should write verifiable behavior, not internal implementation details. Flux further emphasizes the second problem: even if the document describes the correct behavior, it cannot replace the verification of the current repository. True closure must return to code, tests, owner docs, logs, and audit evidence.

The Real Difference

What OpenSpec solves: how to use structured specs/changes/delta/archive to organize the update of behavioral specifications, focusing on the evolution flow of specs.

What AGE solves: when AI rapidly expands the state space, how the system first defines an attractor, and then uses harnesses such as plan, verification, audit, logs, bugs, analysis, and testing to make the trajectory continuously converge.

The two tools solve problems at different levels. OpenSpec's strength is the structured specification workflow. Flux/AGE's strength is using architecture owner docs with precedence to define the attractor, and then using free but responsibility-bounded document routing and a strict closure harness to make the repository converge over the long term.

Moving from spec-driven development to Attractor-Guided Engineering is not moving from "writing specs" back to "not writing specs," but moving from "organizing changes into spec updates" toward "defining where the system should converge over the long term, and making every round of AI generation continuously pulled back by this structure."

What Ordinary Projects Can Directly Adopt

There is no need to copy the full governance of Flux.

First, files-in, files-out. Write input into a file first before @-ing it to AI; output goes into docs/, not left only in the chat window. This step takes just a few minutes, but it gives AI traceable repository memory instead of relying on conversational context.

Second, write an architecture document for the core business that defines the business attractor. Do not write a code guide. Instead, write down the sources of truth, state transitions, ownership boundaries, and common misunderstandings.

Third, write lightweight plans for complex changes. Include the current baseline, goals, what is not being done, an execution checklist, proof items, and closure conditions. Before completion, have an independent session or independent reviewer re-verify.

Fourth, turn recurring problems into repository memory. Manual issues go into testing, complex bugs go into bugs, research conclusions go into analysis, and high-frequency errors go into audit scripts.

Specification updates are a necessary layer. System convergence still needs an attractor.

nop-chaos-flux is open source:

NOP Chaos Flux Architecture Evolution: Rewriting from AMIS to a Modern Low-Code Runtime

canonical — Tue, 19 May 2026 12:57:52 +0000

This article is based on the development logs under docs/logs/2026/ (2026-03-20 to 2026-05-03), sorting out the architectural decisions, module splits, performance optimizations, and platform evolution of the entire framework from zero to maturity. Each phase includes key code paths and document links for traceability.

This article is a collation of historical evolution and implementation trajectory, not a current normative owner doc. For judgments involving current primitive boundaries, action execution model, resource publishing contracts, template instantiation, or package boundaries, the current owner docs and live code pointed to by docs/architecture/README.md shall prevail.

The "key path" filenames appearing in the text are recorded according to the repository state at that time; some paths may have been moved, split, or deleted today and should not be used as current entry indexes.

Preface: Source of Design Ideas

The core design ideas of Flux were not discovered gradually during implementation, but were established as early as the AMIS theory research phase. The two articles under nop-entropy/docs/theory/amis/ — Why Baidu AMIS Framework is an Excellent Design and Revisiting Baidu AMIS Framework and Declarative Programming — laid the theoretical foundation for the entire project:

Env environment abstraction: AMIS's env object virtualizes all I/O operations, making output = AmisPage(Input) possible. Flux's RendererEnv is a modern implementation of this idea.
Api and value/function duality: The Api object is a Ref encapsulation of remote async calls, essentially an asynchronous upgrade of computed. Flux's Resource (data-source) primitive directly inherits this idea.
Data chain = lexical scope: AMIS's data chain is essentially lexical scope lookup at the DSL level. Flux's ScopeRef chain structure is a compile-time enhancement of this model.
xui:import action modularization: The xui:import attribute introduced by the Nop platform for AMIS injects external function libraries into the action system by lexical scope. Flux's xui:imports + ActionScope is a complete compile-time implementation of this mechanism.
Declarative first: From imperative DOM manipulation to reactive data binding to compiled artifact execution — each step increases the proportion of declarativeness. Flux's compile-first principle is the endpoint of this evolution.

Therefore, the architectural evolution of Flux is not "discovering principles during design" but "systematically implementing established principles on a modern technology stack (React 19, Zustand, TypeScript 6.0)". The evolution history records split decisions, performance breakthrough bottlenecks, and contract refinements on the implementation path, not swings in design direction.

The Most Fundamental Shift: From Runtime Interpretation to Compile-Time Execution

The above principles answer "what to design"; the most fundamental implementation shift throughout the evolution is "how to execute":

AMIS is essentially a runtime interpreter — takes a JSON schema, reads and executes it on the fly. Data chain is looked up at runtime, actions are dispatched at runtime, validation is triggered at runtime, field visibility is judged at runtime. All design principles operate at the runtime level.

Flux inserts a compilation phase between DSL and runtime, moving forward various categories of AMIS runtime behavior into compiled artifacts:

AMIS Runtime Behavior	Flux Compiled Artifact
Runtime type judgment of values	`CompiledValueNode` five static node types
Runtime traversal of schema structure	`TemplateNode` immutable graph (compile once, instantiate multiple times)
Runtime resolution of actions	`CompiledActionProgram` / `CompiledActionNode` IR
Runtime wiring of host contracts	`CapabilityProjectionManifest` compile-time visible and verifiable
Runtime exposure of schema problems	Compile-time diagnostics (unknown attributes, contract shape validation)

This shift was not completed at once but runs through the entire evolution process as the main thread: from value compilation (03-25) to template instantiation (04-07) to action pre-compilation (04-20) to compiler package extraction (04-21) — each step is a milestone on the same path of "moving runtime judgment forward to compile time". The final three-layer split of flux-compiler / flux-action-core / flux-runtime is the physical form of this shift: the compiler is responsible for producing immutable artifacts, and the runtime only consumes and instantiates them.

Phase 1: Core Concept Establishment and Package Structure Setup
Phase 2: Flow Designer from Proof of Concept to Production-Grade
Phase 3: Renaming, Styling System, and Component Migration
Phase 4: Complex Renderers and Architecture Audit
Phase 5: Code Audit and Quality Convergence
Phase 6: Runtime Architecture Convergence and Performance Optimization
Phase 7: Frontend Programming Model Finalization and In-depth Design
Phase 8: Template Instantiation and Node Identity System
Phase 9: Deep Audit, Performance Optimization, and Architecture Convergence
Phase 10: Compiler Independence and Package Boundary Hardening
Phase 11: Comprehensive Quality Convergence and Host Maturity
Key Principles of Architectural Evolution
Appendix: Timeline Overview

1. Phase 1: Core Concept Establishment and Package Structure Setup

Time: 2026-03-20 ~ 2026-03-23

On 03-20, systematic bug analysis and first-round fixes of the early Flux runtime were completed (dual-state desynchronization, concurrent submit race, validation coverage, etc.). On the same day, @nop-chaos/amis-debugger (later renamed nop-debugger) was created, positioned from the start as an AI-first structured diagnostic tool.

1.1 Action Scope and Import Semantics

docs/architecture/action-scope-and-imports.md established one of the most core conceptual layers of Flux:

ScopeRef is a pure data scope, only carrying data reads/writes.
ActionScope is a capability scope, carrying namespaced actions and imported library capabilities.
xui:import is declarative import semantics (order-independent, repeatable, deduplicated by normalized key), not execution order semantics.

The dispatch path is fixed as: built-in → component:<method> → namespaced action.

1.2 Flow Designer Package Creation

The two packages @nop-chaos/flow-designer-core and @nop-chaos/flow-designer-renderers were created in this phase. Core contains the pure graph runtime (GraphDocument, GraphNode, GraphEdge, DesignerConfig), and Renderers contains renderer definitions for designer-page, designer-field, designer-canvas, designer-palette.

1.3 Collaborative Documentation System

The complexity of Flow Designer gave birth to a layered documentation system:

docs/architecture/flow-designer/design.md — target architecture
docs/architecture/flow-designer/runtime-snapshot.md — current implementation snapshot
docs/architecture/flow-designer/collaboration.md — runtime collaboration boundaries
docs/architecture/flow-designer/canvas-adapters.md — canvas adapter boundaries

Key decision: Split documentation into "target state" and "snapshot state" to avoid confusion between target architecture and current implementation.

Key paths: packages/flux-runtime/src/action-runtime.ts, packages/flow-designer-core/src/core.ts, docs/architecture/action-scope-and-imports.md

2. Phase 2: Flow Designer from Proof of Concept to Production-Grade

Time: 2026-03-23 ~ 2026-03-27

2.1 Canvas Bridge Pattern

Introduced the DesignerCardCanvasBridge contract, abstracting canvas interactions (select, delete, move, connect, reconnect, viewport sync) as bridge callbacks, allowing the card canvas and XYFlow canvas to share the same command adapter.

Renderer UI Events → Bridge Callbacks → Command Adapter → Core Mutations

Key decision: Replacing the canvas renderer does not require reintroducing direct graph mutation paths. All mutations go through the shared command adapter.

2.2 Command Adapter

designer-command-adapter.ts introduced a target-side command normalization layer, providing a unified result shape of ok/snapshot/data/error/reason. Both Provider and canvas bridge dispatch commands through this surface, avoiding fragmented semantic rejection logic.

2.3 Schema-Driven Designer

Flow Designer completed the migration from hardcoded React components to JSON configuration-driven. Node/edge rendering is defined through the body: SchemaInput field, allowing complex node appearances to be composed using AMIS schemas such as flex, container, tpl, icon. classAliases and themeStyles enable theme customizability.

2.4 Production-Grade Visual Alignment

Completed visual alignment with the flow-editor-static.html prototype, unifying node two-line semantics, selection states, palette icon chips, quick action buttons, edge/label tokens, minimap anchor positions, etc.

Key paths: packages/flow-designer-renderers/src/canvas-bridge.tsx, packages/flow-designer-renderers/src/designer-command-adapter.ts, apps/playground/src/schemas/workflow-designer-schema.json

3. Phase 3: Renaming, Styling System, and Component Migration

Time: 2026-03-25 ~ 2026-03-29

3.1 AMIS → Flux Renaming

Comprehensively migrated package references and documentation from the AMIS namespace to the Flux namespace:

amis-schema → flux-core
amis-runtime → flux-runtime
amis-react → flux-react
amis-debugger → nop-debugger
Window global variables renamed from __NOP_AMIS_* to __NOP_FLUX_*

3.2 flux-core Modular Split

packages/flux-core/src/index.ts (1183 lines) was split into a modular structure:

types.ts (687 lines) — all type definitions
validation-model.ts (174 lines) — validation model functions
utils/object.ts — object utilities
utils/path.ts — path utilities
utils/schema.ts — schema utilities
constants.ts — constants

3.3 Styling System Established

docs/architecture/styling-system.md established a TailwindCSS-first styling solution:

Semantic attributes (direction, gap, align) as syntactic sugar for Tailwind classes
classAliases mechanism for reusable Tailwind class definitions, supporting nested alias expansion and scope inheritance
Layout renderers only emit marker classes (nop-container, nop-flex), marker classes carry no visual styling
Spacing explicitly declared in schema via stack-*/hstack-* aliases

3.4 shadcn/ui Migration

Created @nop-chaos/ui package, based on the shadcn/ui component library pattern (class-variance-authority + tailwind-merge + lucide-react), migrating the underlying layer from radix-ui to base-ui:

Button, Input as first migrated components
Gradually covering the full component set: Textarea, Checkbox, Switch, RadioGroup, Select, Dialog, Tabs, Table, Card, etc.
First batch of renderers (Button, Input, Form) migrated to @nop-chaos/ui, subsequent renderers follow in batches

3.5 RendererComponentProps Contract

Established the RendererComponentProps pattern that all renderers must follow:

Data Source	Provides	Purpose
`props.props`	Compiled runtime values	Schema-driven values
`props.meta`	Compiled metadata	Control state
`props.regions`	Pre-compiled child render handles	Render child fragments
`props.events`	Runtime event handlers	Event binding
`props.helpers`	Stable runtime helpers	dispatch, evaluate

3.6 FieldFrame and Renderer Wrapping Contract

The FieldFrame component was introduced into the flux-react layer to uniformly handle form label/error/hint wrapping. The RendererDefinition.wrap flag lets NodeRenderer automatically add labels and error displays for renderers that need field wrapping.

3.7 Report Designer and Spreadsheet Migration

Migrated four packages from nop-chaos-next into the workspace (completed 03-25):

@nop-chaos/spreadsheet-core / spreadsheet-renderers
@nop-chaos/report-designer-core / report-designer-renderers

Integrated workspace configuration (tsconfig references, path aliases, Vite aliases), fixed runtime/test issues, ensured all tests pass.

3.8 testid and Architecture Consistency

On 03-29, added the testid field to BaseSchema, propagated through the compilation→parsing pipeline, all production renderers apply data-testid to the root element. On the same day, completed an architecture consistency audit, discovering issues such as implicit layout injection by renderers, validation trigger semantic drift, theme token naming drift, etc., and established a two-phase fix strategy.

Key paths: packages/ui/src/, docs/architecture/styling-system.md, packages/flux-react/src/field-frame.tsx, packages/spreadsheet-renderers/src/, packages/report-designer-renderers/src/

4. Phase 4: Complex Renderers and Architecture Audit

Time: 2026-03-28 ~ 2026-03-31

4.1 Full shadcn/ui Migration

On 03-28, completed the full migration of the shadcn/ui component library. The @nop-chaos/ui package expanded to cover the full suite of components including Inputs/fields, Overlay, Layout/feedback, etc. Flow Designer, form renderers, code editor, etc., fully switched to shadcn/ui components.

4.2 Code Editor Package

On 03-30, @nop-chaos/flux-code-editor was created based on CodeMirror 6, unifying the expression editor and SQL editor. Features include: support for 8 languages, expression/SQL completion, expression validation, friendly name tagging, template mode, fullscreen toggle, light/dark themes. Subsequently on 03-31, SQL enhancements (formatting, snippet templates, variable panel, SQL execution result preview) were completed.

4.3 Condition Builder

On 03-30, a complete condition-builder renderer was implemented in flux-renderers-form, supporting embedded/selector mode, AND/OR/NOT logic, field search, grouping, unique fields, nested groups, custom operators.

4.4 Word Editor Package

On 03-31, @nop-chaos/word-editor-core (framework-agnostic bridge layer with zero React dependencies + Store) and @nop-chaos/word-editor-renderers (EditorCanvas, RibbonToolbar, FontControls, WordEditorPage) were created. Integrated @hufe921/canvas-editor as the canvas rendering engine, with template expressions stored as hyperlinks. On the same day, completed Phase 1 basic editor integration and Phase 1~4 toolbar controls.

4.5 Architecture Audit

On 03-31, conducted a comprehensive audit of core packages (flux-core, flux-runtime, flux-react, flux-formula, 3 renderer packages), analyzing approximately 32,000 lines of non-test source code. Findings: flux-core's design is correct (it is a base package containing shared pure utilities, not a pure types package), form-runtime has been decomposed into 10 sub-modules, and the dependency flow is clean.

Key paths: packages/ui/src/, packages/flux-code-editor/src/, packages/word-editor-core/src/

5. Phase 5: Code Audit and Quality Convergence

Time: 2026-04-01 ~ 2026-04-03

5.1 Code Audit Fix Plan (Plan #25)

Executed 14 fixes covering 8 packages:

Build hygiene: Removed stale tsconfig include paths, created scripts/verify-no-src-artifacts.mjs CI guard
Logical correctness: Fixed Flow Designer allowMultiEdge logic error, unified executeApiObject() request pipeline
Defensive fixes: Wrapped NodeRenderer with React.memo, added boundary protection for evaluateArray/evaluateObject
Performance optimizations: API cache LRU eviction, Proxy cache WeakMap

5.2 Comprehensive Code Overhaul (Plan #27)

Executed comprehensive code overhaul including:

Render phase remains side-effect free
Form path state relatedPaths fix
Extracted shared hook for form field controller
Dynamic renderer API payload validation
Changed root component registry from module-level mutable state to instance-level state
Added change detection to ScopeRef.merge() method

5.3 Data Source Redesign

DataSourceSchema removed the body region, instead injecting data into the current scope. If dataPath is set, the response is written to scope[dataPath]; otherwise, the response is merged as a plain object into the current scope.

5.4 useOwnScopeSelector Dual Hooks and Full Adoption of @nop-chaos/ui

On 04-03, flux-react exposed useOwnScopeSelector() in parallel with the lexical useScopeSelector(). Report Designer shell renderers migrated to the own-scope hook, consuming only fragment host data. On the same day, completed adoption migration of word-editor-renderers, report-designer-renderers, spreadsheet-renderers to @nop-chaos/ui.

5.5 Dependency and Lint Upgrades

From 04-02 to 04-03, the workspace upgraded to eslint-plugin-react-hooks recommended-latest strict rule set (later deepened on 04-16 to React 19 strict lint baseline), completed Lucide React patch fixes, and cleaned up all build artifact leaks in src/ directories.

Key paths: packages/flux-runtime/src/request-runtime.ts, packages/flux-renderers-data/src/data-source-renderer.tsx, scripts/verify-no-src-artifacts.mjs

6. Phase 6: Runtime Architecture Convergence and Performance Optimization

Time: 2026-04-04 ~ 2026-04-06

6.1 Formily Comparative Analysis and Performance Direction

Completed a detailed comparison with 10+ low-code platforms (AMIS, Formily, LowCode Engine, Appsmith, ToolJet, Retool, etc.). Core findings:

The reactivity model is the most critical shortcoming: The current Pull Model triggers evaluation of O(number of nodes × number of expressions) on parent scope changes, whereas Formily's Push Model is O(number of dependents)
Flux's AOT compilation, orthogonal scope design, and field metadata-driven compilation are unique architectural advantages
Decision: Maintain Flux's compile-first general-purpose platform baseline, allowing only thin local capability extensions in the form subdomain

6.2 Dependency Tracking and Change Path Notification

Implemented ScopeChange dependency tracking baseline:

ScopeStore carries ScopeChange (set of changed paths)
Formula leaf evaluation refreshes dependency set after each successful run
NodeRenderer subscriptions gate metadata/property recomputation through dependency path intersection
Later evolved into lexical root binding model: dependency tracking converges to lexical roots like user, row, record

6.3 Source Registry and Reaction Runtime

Source Registry (source-registry.ts): RendererRuntime exposes registerDataSource(...), sources are bucketed by ScopeRef.id, the data-source renderer is only responsible for registration/release lifecycle
Reaction Runtime (reaction-runtime.ts): ReactionSchema supports watch, when, immediate, debounce, once, reaction execution async scheduling occurs after writes stabilize
Self-cascade protection: Queued reaction triggers merge change paths by pending turn, self-cascading reactions hard-stop after a limited number of times

6.4 Action Control Flow Extensions

The action system added when/parallel/timeout/retry:

when: Precondition check, returns structured skip result if false
parallel: Promise.all parallel execution
timeout: Structured timeout result, cancelable request-like actions participate in actual cancellation
retry: Retry strategy with fixed attempts/fixed delay

6.5 Complex Renderer State Ownership

On 04-05, the Table renderer introduced a local/controlled two-level state ownership model, extended to three levels on 04-06 with the addition of scope mode:

local (default) — internal renderer state
controlled — external schema/runtime driven
scope (added 04-06) — reads/writes reactive state directly from the current rendering scope

6.6 Frontend Programming Model Documentation

docs/architecture/frontend-programming-model.md was established as the top-level architecture baseline document, defining Flux's seven core primitives (at that time the first primitive was still called Base Tree, officially renamed to Template on 04-21). The seven primitives are: Template (formerly Base Tree), ScopeRef, Value, Resource, Reaction, Capability, Host Projection.

6.7 WorkbenchShell Extraction

On 04-04, extracted the shared WorkbenchShell React component from various designers into packages/flux-react/src/workbench/. The page renderers of Flow Designer and Report Designer migrated from handwritten three-column layouts to the unified WorkbenchShell. Shell is purely presentational, carrying no Flux scope or domain knowledge.

Key paths: packages/flux-runtime/src/source-registry.ts, packages/flux-runtime/src/reaction-runtime.ts, packages/flux-runtime/src/action-runtime.ts, packages/flux-react/src/workbench/workbench-shell.tsx, docs/architecture/frontend-programming-model.md

7. Phase 7: Frontend Programming Model Finalization and In-depth Design

Time: 2026-04-06 ~ 2026-04-11

Note: This phase had parallel work with Phase 8 (Template Instantiation), with overlapping dates.

7.1 Programming Model Evolution Discussions

After multiple rounds of in-depth discussions (8 rounds of discussion recorded in docs/discussions/2026-04-06-programming-model-optimality-critique.md), finally established:

Keep the seven primitives closed, do not introduce an alternative primitive system
Understand data-source as "registering a named dynamic value into scope"
name as the sole normalized publication path, mergeToScope: true as the only special publication mode
Action semantics (when + then + onError + parallel) already form a DAG at execution time
Distinguish between "progressive authoring surface" and "DAG execution semantics"

7.2 Action/API Convergence Construction

Renamed declarative request from ApiObject to ApiSchema
type: 'source' as an action-based anonymous value consumption form
data-source as the named/dispatch extension of source
Standardized built-in action naming to camelCase (openDialog, showToast)

7.3 Validation System In-depth Design

On 04-11, completed a unified validation design (docs/analysis/2026-04-11-flux-validation-unified-design.md), covering:

modelGeneration counter to track validation model replacements
Async run identity quintuple (ownerId, modelGeneration, path, ruleId, runGeneration)
Two lifecycle paths: owner-compatible model refresh vs. owner boundary change
State retention rules: always reset materialized caches and async runs

7.4 Form Linkage and Hidden Field Policy

On 04-11, fully implemented the HiddenFieldPolicy contract (Plan 67): clearValueWhenHidden, validatePath skipping, notifyFieldHidden, 21 new tests.
Constraint-based declarative linkage (xui:linkage) compiled into existing node metadata/properties and validation flow.
Field presentation snapshot (effectiveDisabled/effectiveRequired).

7.5 Owner Status Model

On 04-09, unified loading/pending/status as owner-specific read-only summaries:

Internal form expressions standardized to $form binding
Cross-form observers standardized to explicit statusPath
Surface owners (dialog/drawer) expose external read-only status via statusPath

7.6 Component Documentation System and xui:imports Expression Projection

On 04-07, established the docs/components/ component documentation system, each component directory carries design.md + example.json, distinguishing registered renderers from planned renderers. Component naming standardized to Flux native vocabulary rather than AMIS legacy names.

On the same day, completed xui:imports expression projection; import aliases can now be used in expressions as $alias.method(...), sharing the same import namespace provider mapping as the existing namespace:method action dispatch.

Key paths: docs/architecture/frontend-programming-model.md, docs/architecture/api-data-source.md, docs/architecture/action-scope-and-imports.md

8. Phase 8: Template Instantiation and Node Identity System

Time: 2026-04-07 ~ 2026-04-08

8.1 Template Instantiation Architecture

docs/architecture/template-instantiation-and-node-identity.md established the architecture of "compile the template once, instantiate it multiple times at runtime":

cid is strictly a mount-time active node bridge ID
Structure resolution belongs to the runtime-owned resolver
Canonical runtime address as NodeLocator = runtimeId + templateGraphId + templateNodeId + instancePath

8.2 Repeated Instance Identity Propagation

Table row child rendering (cell, buttons, expanded) passes in [{ repeatedTemplateId: 'table.row', instanceKey: rowKey }], row child debug locator data can now see the real instancePath.

8.3 NodeRenderer Compatibility Migration

Through Plan 40, gradually migrated CompiledSchemaNode dependencies to NodeInstance/templateNode:

NodeFrameWrapper consumes templateNode + explicit renderer wrap metadata
RendererComponentProps and useCurrentNodeMeta() mirror templateNode + optional locator
Fragment/dialog ownership seams migrated to active-node-first fallback

8.4 Compiler-Integrated Diagnostics

Plan 41 implemented compiler-integrated schema diagnostics:

flux-core exposes a formal schema diagnostic contract
CompileSchemaOptions carries diagnostic/validation policy
RendererDefinition can contribute schemaValidator
Form and table renderers contributed renderer-owned schema validator checks

8.5 BEM Migration Completed

All internal __ markers cleaned up, field framework, code editor, spreadsheet/report designer, workbench areas migrated to data-slot/data-*.

Key paths: docs/architecture/template-instantiation-and-node-identity.md, packages/flux-react/src/node-instance.ts, packages/flux-runtime/src/node-resolver.ts

9. Phase 9: Deep Audit, Performance Optimization, and Architecture Convergence

Time: 2026-04-12 ~ 2026-04-20

Note: This phase was the highest-density convergence period of the entire project, with code changes, document audits, performance optimizations, and architectural decisions densely interwoven.

9.1 Architecture Document Consistency Audit and Governance System Maturation

On 04-12, completed the first full-scope architecture document consistency audit, checking all files under docs/architecture/ for consistency with code and with each other. Discovered cross-document conflicts (Final Execution Schema wording, node identity model, xui:imports boundaries, style contract drift, etc.), established a repair strategy sharded by document family.

This phase also marked the formal maturation of Flux's unique development governance method:

First write owner doc (target state architecture document)
Then write execution plan
Write daily log after execution
Finally use an independent sub-audit to confirm closure

Many subsequent Plans (73~121) followed this method.

9.2 Plan 82: Architecture Contract Implementation Convergence

Plan 82 was the core convergence plan from 04-12 to 04-14, covering multiple parallel contract alignment threads:

xui:imports node lifecycle tightening (Phase 5): The creation of ActionScope for import declaration nodes and namespace registration began to separate from renderer policies; module loading deduplication and scope namespace lifecycle initially became independent. The final import-owned boundary was finalized in Plan 133 on 04-23 (see Phase 10, 10.3)
Surface family extraction (Phase 5): dialog/drawer state extracted from page.store into independent SurfaceStore, SurfaceRuntime became the unified owner for dialog/drawer/surface
Value adaptation contract convergence (Phase 6): detail-field, detail-view, object-field, array-field, variant-field gradually aligned to shared value-adaptation helper and unified scope model
Architecture narrowing decision: After multiple rounds of implementation attempts, the architecture documentation clearly positioned object-field, array-field, variant-field as inline live-edit controls (editing directly writes to parent form), only detail-field/detail-view retain staged owner semantics (confirm/cancel boundaries)

9.3 ScopeRef Read-Write Separation and Per-Path Subscription

From 04-14 to 04-15, performed a major refactoring of ScopeRef's core APIs:

read() → readVisible() + materializeVisible() (Plan 89): readVisible() uses the prototype chain to provide a lazy lexical view; materializeVisible() is called only at explicit flattening boundaries (formula broad-access, debugger dump, request includeScope: '*')
Per-path fine-grained subscription (Plan 90): FormStore added a subscribeToPath(path) mechanism; keystrokes on field A no longer wake subscribers of field B, achieving O(1) field-level invalidation
Host Projection scope base (Plan 87): RendererRuntime.createHostProjectionScope(...) moved the read-only/write-protection boundary of host projection from React hooks into a shared runtime contract

9.4 Performance Optimization Series (Plans 100~110)

On 04-16, executed an entire performance optimization plan series, from audit to per-package implementation:

Playground loading and bundle boundaries (Plan 102)
Flux React hot path fixes (Plan 103): NodeRenderer useSyncExternalStore selector stabilization, ClassAliasesContext broadcast debouncing
Formula runtime hot path (Plan 104)
Spreadsheet performance and virtualization (Plan 105): setCells() batch operations, grid virtualization (binary search for visible range), requestAnimationFrame batch selection/fill/zoom
Runtime and form invalidation performance (Plan 106): parallel field validation, computeScopeState caching, publishStatus skip unchanged updates
Collection renderer scalability (Plan 107): table viewport-driven virtualization (threshold 50 rows, overscan 10), row scope cache changed from full clone to in-place mutation + generation counter
Form field consumer performance (Plan 108): useBoundFieldValue() uses UNUSED_VALUE sentinel selector to avoid inactive subscriptions
Flow Designer performance hygiene (Plan 109): node synchronization reduced from O(n²) to O(n)
API request and cache hygiene (Plan 110): source refresh O(1) name indexing, polling changed from setInterval to setTimeout chain

9.5 @nop-chaos/flux-renderers-form-advanced Split

On 04-16, split 11 advanced renderers from flux-renderers-form (~15,800 lines) into the new @nop-chaos/flux-renderers-form-advanced package: condition-builder, variant-field, detail-view, detail-field, object-field, array-field, array-editor, tag-list, key-value, etc. flux-renderers-form was reduced to ~3,000 lines. Dependency direction confirmed as form-advanced → form → basic (no cycles).

9.6 Capability Projection Manifest

On 04-16, introduced the Capability Projection Manifest architecture (Plan 112), upgrading host protocols from runtime wiring conventions to compile-time visible and verifiable static contracts:

HostCapabilityProjectionManifest declares host projection fields and namespaced capability methods
RendererDefinition.hostContract lets renderer definitions carry host contract metadata
Flow Designer as the first pilot, declaring 30 designer:* methods
Compiler-integrated diagnostics: validateActionShape() can now validate host action parameter shapes

9.7 @nop-chaos/flux-i18n Internationalization Package

On 04-17, created the @nop-chaos/flux-i18n package, based on i18next and react-i18next, supporting zh-CN (default) and en-US. All translation keys use the flux. prefix. Subsequently migrated hardcoded strings from packages like condition-builder, report-designer, code-editor, form-advanced to t() calls, upgrading the ESLint i18next/no-literal-string rule from warn to error, ensuring that new hardcoded strings cause build failures.

9.8 ValueAdapter Unified Protocol

On 04-20, docs/architecture/value-adaptation-and-detail-field.md established ValueAdapter as the canonical shared protocol (Plan 121):

Simple fields use declarative adapters: stringAdapter(), booleanStringAdapter(), array adapters
Composite owners (object-field, variant-field) uniformly connect to actionAdapter() for transformInAction / transformOutAction
Staged helpers of detail-field/detail-view internally delegate to actionAdapter(), keeping the public API unchanged
ValueAdapter becomes the standard access method for new value-oriented fields, replacing JSX local type conversions

9.9 CompiledSchemaNode Complete Elimination

On 04-16, the compilation pipeline no longer passes through the CompiledSchemaNode intermediate layer, directly generating TemplateNode from SchemaInput. CompiledSchemaMeta and CompiledNodeRuntimeState were demoted to type aliases. This cleanup simplified the compilation pipeline and eliminated an indirection layer that no longer held value after the template/instance separation landed.

9.10 Renderers Contract Unified Static Metadata

On 04-20 (Plan 117), added unified static contract fields to RendererDefinition: rendererClass, rendererTraits, propContracts, eventContracts, componentCapabilityContracts, scopeExportContracts. propContracts immediately participates in compiler unknown attribute checking; the remaining fields are reserved for tooling (Inspector, online editor). button, form, crud, designer-page served as the first pilots.

9.11 Action Pre-compilation and Async Governance

On 04-20 (Plans 119~120), pushed the action system into the compile phase:

CompiledActionProgram IR: compileAction() compiles ActionSchema to CompiledActionProgram/CompiledActionNode; the runtime executor no longer mixes raw schema execution paths internally
Async governance convergence: Shared async-governance.ts base unified the run identity, stale publish gating, and debug diagnostics for three categories of async runtime owners: data-source, reaction, and async validation

9.12 Documentation Governance and Deep Audits

From 04-12 to 04-19, multiple rounds of deep audits were produced (12 audit dimensions covering API surface, state ownership, reactivity precision, async safety, validation consistency, renderer contracts, style compliance, field slot modeling, lifecycle, etc.). After each audit, only true defects still reproducible in the current code were fixed, avoiding over-fixing.

Key paths: packages/flux-core/src/value-adapter.ts, packages/flux-runtime/src/async-governance.ts, packages/flux-runtime/src/action-compiler.ts, packages/flux-i18n/src/, packages/flux-renderers-form-advanced/

10. Phase 10: Compiler Independence and Package Boundary Hardening

Time: 2026-04-21 ~ 2026-04-25

10.1 Compiler Package Extraction

Extracted the @nop-chaos/flux-compiler package from flux-runtime:

Schema compilation/validation
Action pre-compilation
Compilation symbol table
Diagnostics and validation lowering
flux-runtime briefly retained a compatibility re-export layer (removed in Plan 124 on 04-22; runtime side no longer holds any compiler code)

10.2 Action Core Package Extraction

On 04-22, further extracted the @nop-chaos/flux-action-core package from flux-runtime, with ActionRuntimeAdapter becoming the unified action invocation boundary. By this step, Flux completed a three-layer split:

flux-compiler responsible for "turning schema into executable artifacts"
flux-action-core responsible for "action dispatching, control flow, and unified invocation exit"
flux-runtime responsible for "connecting compiled artifacts with the host environment and holding lifecycle"

10.3 Import Boundary Semantic Convergence

On 04-23, the creation of ActionScope for xui:imports was separated from renderer policy into import-owned boundary semantics (Plan 133). Module loading deduplication and scope namespace registration operate independently; import lifecycle and compile-time diagnostics participate in the compilation pipeline, completing the second phase of the ActionScope / xui:imports model proposed in late March.

On the same day, Plan 132 eliminated runtime fallback reads of raw Schema objects — DataSource and Reaction fully migrated to compiled data; the runtime no longer holds uncompiled schemas. This is a direct manifestation of the compile-forward mainline.

10.4 Base Tree → Template Renaming

On 04-21, the first primitive of the programming model was renamed from Base Tree to Template, emphasizing its nature as a compile-time immutable program definition. SchemaCompiler produces an immutable TemplateNode graph; the runtime only consumes and instantiates.

10.5 Data Domain Owner Architecture

On 04-22, the Data Domain Owner concept was formally elevated to an architecture baseline document (docs/architecture/data-domain-owner.md). object-field, array-field, variant-field aligned to the Data Domain Owner baseline — composite fields become explicit data domain owners, with clear value adaptation, validation coordination, and sub-scope lifecycle. This complements the staged owner semantics of detail-field/detail-view: two ownership models (inline live-edit vs. staged confirm/cancel boundaries) cover all composite field paradigms.

10.6 DingFlow Tree Mode

Introduced a structured process tree contract: nodes can have branch groups, branches implicitly merge, continuation flow enters the downstream child of the owner node. In tree mode, free connections, free reconnections, and manual node dragging are disabled.

10.7 CRUD Contract Finalization and Shared Context Menu

The design and implementation of CRUD spanned multiple phases: component contract document completed on 04-12 (docs/components/crud/design.md), entered implementation around 04-17, and completed interaction and contract finalization on 04-24 ~ 04-25:

CRUD selection summary and refresh behavior stabilized
Spreadsheet shared context menu baseline (copy, cut, paste, clear, insert/delete rows/columns)
Double-click fill handle uses adjacent data region for auto-fill down

On 04-25, Plan 139 removed the DataSourceSchema.api field; all remote calls are uniformly dispatched via { action: 'ajax', args: ... }. ApiSchema is explicitly defined as a transport contract used internally by the ajax action; author side no longer directly touches independent API definitions — the convergence from independent execution paths to unified action dispatch is completed here.

Key paths: packages/flux-compiler/src/, packages/flux-action-core/src/, docs/architecture/flux-runtime-module-boundaries.md, docs/architecture/capability-projection-manifest.md

11. Phase 11: Comprehensive Quality Convergence and Host Maturity

Time: 2026-04-25 ~ 2026-05-03

Note: This phase was the second high-density convergence period after Phase 9 (04-12~04-20), but the focus shifted from "architecture contract alignment" to "comprehensive quality convergence" — performance audit, test institutionalization, adversarial security review, validation owner boundary precision, host tooling engineering. If Phase 9 answered "is the architecture right?", Phase 11 answered "is the implementation robust enough".

11a. Performance Audit and Hot Path Optimization (04-26)

Conducted in-depth performance audits on four hot paths: runtime, form, spreadsheet, report-designer:

Eliminated JSON.stringify full-value comparisons: Form valuesPath publication used JSON.stringify for change detection, incurring significant serialization overhead in high-field-count forms. Replaced with path-aware structural comparison.
Spreadsheet batch writes: Batch operations like paste/cut changed from per-cell full Map cloning to setCells() batch interface, eliminating O(n) immutable clone overhead.
Condition-builder recursive structural equality: Condition builder used JSON.stringify for value comparison; replaced with recursive structural equality function, avoiding stringification overhead and key-order sensitivity.
Path-aware form value subscription: useCurrentFormState added an optional { path: name } parameter; field-level subscribers are woken only when the specified path changes, eliminating cascading re-renders of unrelated fields.
Full adoption in advanced form renderers: Path-aware subscription extended to all advanced form renderers including object-field, array-field, detail-field, variant-field, array-editor, key-value, etc.

11b. Test Coverage Institutionalization and Deep Audit (04-26 ~ 04-27)

Plan 143: Coverage threshold institutionalization

Enforced 80% Vitest coverage thresholds in all core package configurations. Systematically closed coverage gaps in the following packages:

flux-runtime, flux-react, flux-renderers-data
flux-renderers-form, flux-renderers-form-advanced, flux-renderers-basic
flux-formula

First 18-dimensional deep audit (04-27)

Full-dimensional audit covering 24 packages, discovering 1 P0, 16 P1, 28 P2, 36 P3 issues. Audit dimensions included:

Architecture consistency, state ownership, async safety, reactivity precision
Host contracts, test quality, accessibility, security
Performance, boundary clarity, dependency direction, API surface stability
Documentation synchronization, type safety, error handling, internationalization, observability, extensibility

11c. Renderer Contract and Host Projection Convergence (04-26 ~ 04-30)

Plan 145: runtime/react/renderer hot spot boundary convergence

Extracted shared helper functions, established projected-owner scope base, CRUD owner bridging, Flow Designer page-shell/adapter split. Cross-package dependencies in renderer hot paths converged to explicit contracts.

Plan 146: Domain-host projection and lexical convergence

Word Editor real-time save vs. auto-save timing semantics clarified
Report Designer standardized selection vocabulary
Host projection interfaces of various domain designers aligned to a unified baseline

Plan 144: Execution boundary diagnostics and host contract tooling

Diagnostic information carries source location, supporting precise jumping from runtime errors to schema definition locations
Host contract manifest tooling, supporting automated contract checking

Plan 150: xui:actions — Schema-local named action chains

Introduced the xui:actions attribute, allowing declaration of named action chains on schema nodes:

__xui_actions__ synthetic namespace carries schema-local action definitions
Lexical inheritance: child nodes inherit xui:actions from the parent scope, sharing the same namespace resolution mechanism as xui:imports
Action chains support when/then/onError control flow

11d. Adversarial Review and Security Hardening (05-01 ~ 05-02)

Conducted an adversarial review of the entire codebase (24 packages), covering compiler-runtime contract consistency, reaction cascade depth, scope dangerous key filtering, formula parser/evaluator depth limits, form validation resilience, accessibility.

Key fixes:

$Date symbol table fix: Completed from 7 methods to 14 methods, covering all date operations
booleanStringAdapter("false") fix: Boolean("false") pitfall — the string "false" is truthy in JavaScript; adapter must explicitly parse
Action compilation depth limit: MAX_ACTION_COMPILE_DEPTH=128 to prevent malicious nested action chains from causing compile stack overflow
Scope snapshot sanitization: sanitizeSnapshot() blocks prototype pollution keys like __proto__, constructor, prototype
Formula parser depth limit: MAX_PARSER_DEPTH=256, MAX_EVAL_DEPTH=256 to prevent deeply nested expression attacks

11e. Validation Owner Boundary Convergence (04-30 ~ 05-03)

The validation owner boundary underwent three stages of precision refinement, finally forming a clear ownership hierarchy:

Plan 157: validation owner boundary

formId becomes a true targeting carrier, no longer just an identifier
submitWhenHidden semantics removed — submission behavior of hidden fields is uniformly controlled by the owner
Registration identity maintains path-singleton: registrations on the same path are automatically replaced, no duplication

Plan 163: core boundary

flux-core completely removes React type dependencies, becoming a pure TypeScript package
flux-react owns the reactComponent convenience path
Surface runtime creates an independent validation owner for each surface, achieving validation isolation

Plan 168: validation owner convergence

formId resolution path unified
validateOn: 'change' no longer gates on touched — validation on change, orthogonal to touched state
Summary-gate enforcement during submission: collect all validation summaries on submit, block until all pass

Plan 174: Strict Validation Mode

Schema authors can enable strict compilation mode, causing the compiler to report unknown attributes. This mechanism fills the last piece of schema validation: from "compiler ignores unknown attributes" to "unknown attributes are compile errors in strict mode".

Final Validation Owner Hierarchy:

Owner Level	Coverage	Typical Scenario
form	All fields within the form	Main form submission
page-root	Page-level validation	Page-level linkage constraints
surface	Independent validation domain within dialog/drawer	Popup form independent submission
detail-child	Sub-validation domain within staged owner	Detail row edit confirm/cancel boundary

11f. Host Tooling and Engineering (04-30)

Turborepo introduction

Turborepo as the workspace task runner, enabling parallel execution of build/typecheck/test/lint. The task dependency graph is automatically topologically sorted by Turborepo, eliminating manual orchestration scripts.

Repository-level audit toolchain

dependency-cruiser: Dependency direction validation, preventing circular dependencies and illegal cross-layer references
knip: Dead code detection, identifying unused exports, types, and dependencies
Stryker: Mutation testing pilot, validating the effectiveness of test suites
Semgrep: Static security scanning, detecting known unsafe patterns

Bundle analysis

Support for pnpm analyze via rollup-plugin-visualizer, visualizing bundle composition of each package, helping identify size regressions and unexpected dependencies.

Key paths: packages/flux-runtime/src/form-runtime.ts, packages/spreadsheet-core/src/, packages/flux-formula/src/, packages/flux-core/src/, docs/plans/143-*, docs/plans/145-*, docs/plans/157-*, docs/plans/163-*, docs/plans/168-*

12. Key Principles of Architectural Evolution

Looking across the evolution history from 2026-03-20 to 2026-05-03, the following principles repeatedly appear in key decisions:

12.1 Compile First

Flux always does as much work as possible at compile time: value classification, expression compilation, action pre-compilation, schema diagnostics. The runtime only executes compiled artifacts and makes no additional judgments. This principle runs from the five node types of CompiledValueNode through the TemplateNode/NodeInstance separation.

12.2 Data and Capability Separation

ScopeRef purely carries data, ActionScope purely carries capabilities; they are orthogonally separated. This decision avoids turning ScopeRef into a general-purpose method registry, keeping the scope model simple.

12.3 Renderer Contract Consistency

All renderers follow the unified RendererComponentProps pattern, with data coming from props.props/props.meta/props.regions/props.events/props.helpers, and do not directly access stores. This ensures renderer replaceability and testability.

12.4 Marker Classes Carry No Styling

Layout renderers only emit semantic marker classes (nop-container, nop-flex); marker classes carry no visual styling. All spacing/direction/padding is explicitly declared via classAliases or semantic attributes in the schema. This avoids implicit layout and style drift.

12.5 Domain Bridge Pattern

Complex designers (Flow Designer, Report Designer, Spreadsheet) are integrated via the DomainBridge pattern: core packages provide pure logic runtime, renderer packages provide React integration, and the canvas is decoupled via bridge callbacks. This allows canvas implementations to be replaced without affecting core logic.

12.6 Documentation as Architecture

From the layered documentation system of Flow Designer to multiple rounds of discussion on the frontend programming model, the Flux project always uses documentation as the carrier of architectural decisions. The separation of target state and snapshot state, and the separation of discussion records from normative documents, ensure the sustainable maintenance of architectural knowledge.

12.7 AI-First Observability

The debugger was designed as AI-first from the start: structured automation APIs, diagnostic reports, session export, interaction tracing. Subsequent dependency tracking change paths, source/reaction registry snapshots, and node locator identity all follow the "machine-readable over human-readable" observability design.

12.8 Design First, Implementation Approximates

Flux's core design ideas (Env environment abstraction, Api/Resource as asynchronous reactive values, lexical scope data chain, xui:imports action modularization, declarative first) were established as early as the AMIS theory research phase. The architectural evolution records not the discovery of design directions, but the gradual approximation of implementation precision to design principles — from runtime interpretation to compile-time staticization, from implicit conventions to explicit contracts, from monolithic to layered package boundaries.

12.9 Host Boundary Testing Ground

Flow Designer is the first testing ground for Flux to validate host protocols. What Flux learned from Flow Designer is not "how to make a flowchart editor", but that complex controls must access the runtime via host boundaries, namespaced actions, bridge snapshots, and configuration-driven approaches. The same unified runtime later successfully accommodated two vastly different complex host paradigms: structured process tree (DingFlow) and Excel-native workbench (Spreadsheet/Report Designer).

12.10 Implementation-Driven Convergence

Although design ideas were established early, the implementation path was not achieved overnight. Flux's architecture gradually became precise through continuous implementation, failure, regression, splitting, renaming, rewriting documentation, and then being forced to converge by sub-audits. Each step of implementation advancement was accompanied by clear documentation and regression test coverage, ensuring traceability of implementation decisions.

12.11 Audit Rule Extraction Forms Long-Term Governance Loop

From the deep audits of Phase 9 to the 18-dimensional audit of Phase 11, the Flux project continuously distilled audit findings into reusable governance rules: coverage thresholds (Plan 143), compilation depth limits, scope snapshot sanitization, strict validation mode. The output of each audit is not just fixes, but the extraction of new rules. These rules are written into code (threshold configs, compiler checks) rather than documentation, forming an automated governance loop.

12.12 Adversarial Review Complements Deep Audit

Deep audits discover problems from architectural dimensions (state ownership, dependency direction, contract consistency); adversarial reviews expose vulnerabilities from an attacker's perspective (prototype pollution, deep nesting, truthy traps). The two complement each other: deep audits ensure "architecture is correct", adversarial reviews ensure "attacks do not succeed". Phase 11 institutionalized both as standard processes before release.

12.13 Reactive Subscription Precision is an Architectural Concern

From per-path subscription (Plan 90) in Phase 9 to path-aware useCurrentFormState in Phase 11, subscription precision has always been an architectural concern, not a local optimization. The wake-up scope of React re-renders directly determines the responsiveness performance of forms, tables, and designers. Flux's answer is progressive precision from full-value comparison → dependency path intersection → path-aware precise subscription; each step is an architectural decision, not an implementation detail.

12.14 Validation Owner Hierarchy

The ownership of the validation system is not a binary "has/has not", but a hierarchical model: form (form domain) → page-root (page domain) → surface (popup domain) → detail-child (staged sub-domain). Each layer has an independent lifecycle, submission gating, and validation summary. This hierarchy was the result of three Plans (157 → 163 → 168) gradually converging in Phase 11, evolving from implicit "form owns all validation" to an explicit four-layer ownership model.

13. Appendix: Timeline Overview

Phase	Date	Key Events
Phase 1	03-20 ~ 03-23	Bug #1~#5 analysis and fixes, debugger birth, ActionScope/Import semantics established, Flow Designer packages created, canvas bridge initial implementation
Phase 2	03-23 ~ 03-27	Canvas bridge, command adapter, schema-driven designer, production-grade visual alignment
Phase 3	03-25 ~ 03-29	AMIS→Flux renaming, flux-core split, styling system, shadcn/ui migration, FieldFrame, Report/Spreadsheet migration, testid
Phase 4	03-28 ~ 03-31	Full shadcn/ui migration, Code Editor, Condition Builder, Word Editor, architecture audit
Phase 5	04-01 ~ 04-03	Code audit fixes, comprehensive overhaul, data source redesign, dual-hook design, full @nop-chaos/ui adoption
Phase 6	04-04 ~ 04-06	Formily comparison, dependency tracking, source registry, reaction runtime, action control flow, WorkbenchShell, table state ownership, programming model doc
Phase 7	04-06 ~ 04-11	Programming model finalization, Action/API convergence, Owner Status, component documentation system, imports expression projection, validation design, HiddenFieldPolicy
Phase 8	04-07 ~ 04-08	Template instantiation, repeated instance identity, NodeRenderer migration, compiler diagnostics, BEM cleanup
Phase 9	04-12 ~ 04-20	Deep audit, architecture doc consistency, Plan 82 contract convergence, ScopeRef read-write separation, per-path subscription, performance optimization series (Plans 100~110), form-advanced split, Capability Projection Manifest, flux-i18n, ValueAdapter unified protocol, CompiledSchemaNode elimination, action pre-compilation IR, async governance convergence
Phase 10	04-21 ~ 04-25	Compiler package extraction, action core package extraction, Import Boundary convergence, Base Tree→Template, DingFlow tree mode, CRUD, shared context menu
Phase 11	04-25 ~ 05-03	Performance audit and hot path optimization, test coverage institutionalization (Plan 143), 18-dimensional deep audit, renderer contract convergence (Plans 145/146/144), xui:actions (Plan 150), adversarial security review and hardening, validation owner four-layer boundary convergence (Plans 157/163/168), Strict Validation Mode (Plan 174), Turborepo engineering

Conclusion

The architectural evolution of NOP Chaos Flux is a process of systematically implementing established design ideas on a modern technology stack. The core designs — Env environment abstraction, Api/Resource as asynchronous reactive values, lexical scope data chain, xui:imports action modularization, declarative first — were established as early as the AMIS theory research phase (see c:/can/nop/nop-entropy/docs/theory/amis/). What Flux did was not to invent these principles, but to solve the structural limitations of AMIS at the schema layer (parallel field explosion) and runtime layer (MST tight coupling), and to implement these principles in a compile-first, type-safe, package-boundary-clear manner.

The strongest mainline throughout the evolution is from runtime interpretation to compile-time execution: value classification, template instantiation, action pre-compilation, host contract staticization, compiler package extraction — each step is a milestone on the same path of moving runtime judgment forward to compile time. But this mainline is not the only one. Running in parallel and equally important are two others: the ownership convergence of owner / validation / surface (from implicit dual-state to explicit staged owner, finally converging to the four-layer validation owner of form / page-root / surface / detail-child), and the boundary explicitization of host contract / import boundary / capability manifest (from runtime wiring conventions to compile-time visible contracts). The final three-layer split of flux-compiler / flux-action-core / flux-runtime is the physical form of the compile-forward mainline. Phase 11 built on the three-layer split to complete comprehensive quality convergence: performance hot path optimization, 80% coverage institutionalization, adversarial security review, validation owner boundary precision, host tooling engineering — a leap from "architecture correct" to "implementation robust".

The resulting architecture — DSL-first + compilation/execution separation + orthogonal scopes + template instantiation + domain bridging + compile-time host contracts + layered validation owner + automated quality governance — provides a clear modern runtime reference for declarative frontend low-code DSLs.

nop-chaos-flux is open source:

Design Principles of nop-chaos-flux, a Next-Generation Low-Code Rendering Framework

canonical — Tue, 19 May 2026 12:38:06 +0000

Introduction

nop-chaos-flux is the rendering layer of the Nop platform—a low‑code runtime driven by declarative DSLs, designed to render and execute application pages described by Schema in the browser. Its DSL surface syntax resembles that of Baidu AMIS, but achieves conceptual unification (e.g., eliminating the xxxOn suffix family). Its internal compilation model, runtime architecture, and expression engine have all been redesigned.

Most low‑code platforms treat the Schema as the runtime input configuration. The runtime then simultaneously carries authoring‑time structures, domain semantics, and scheduling logic. Every new capability adds another set of primitives, a new global provider, another authoritative Schema channel, and the core keeps bloating.

Flux starts from a different path: elevating the DSL from a runtime input format to an independent, first‑class structural layer.

1. DSL First

The DSL is not an input format fed to the runtime; it is a first‑class artifact of the platform: an independent, operable structural layer. Before ever entering the runtime, it already possesses its own lifecycle, transformation space, and organization rules.

Many systems have a DSL, but it is only used as a runtime input format—there is no independent structural manipulation. Flux does not see it that way. Flux’s DSL is a structural layer that can be edited, composed, trimmed, and transformed even outside the runtime:

Operation	Meaning
Edit	Source location retention, aliases, editor metadata, round‑trip fidelity
Merge / Inherit	`x:extends` inheritance, override expansion, fragment composition
Trim	Permission trimming, feature flag trimming, profile assembly
Transform	i18n string replacement, static default expansion
Meta‑programming	Express variations through structural conventions (not by growing runtime interfaces)

DSL transformations are layered: permission trimming, i18n replacement, and default expansion each operate independently. Removing authoring‑time metadata must not change runtime behavior.

2. Authoring–Execution Separation

Even when adopting a DSL‑first approach, many systems still maintain only one model, forcing the runtime to directly carry authoring‑time structures. Flux deliberately does not do this. Instead, it places the Authoring Model and the Execution Model on opposite sides of a pre‑compilation boundary.

The point of this principle is not “having two models” per se, but acknowledging that the two sides have different optimisation goals: authoring time serves understanding, editing, composition, and fidelity; execution time serves conceptual simplification, reduced runtime overhead, and stable execution semantics.

Two‑sided optimisation goals

Aspect	Authoring Model	Execution Model
Optimisation goal	Understandability, domain expressiveness, editing fidelity	Performance, unified internal concepts, minimal runtime overhead
Structural form	Retains source location, aliases, editor metadata, domain‑specific edit structures	Final assembled Execution Schema, no redundancy
Correctness	Round‑trip fidelity, author intent never lost	Behavioural equivalence, deterministic execution
Replaceability	Many editors/designers/collaborative engines can produce the same DSL	The same Final Execution Schema can execute on different runtime hosts

Significance of the boundary

The pre‑compilation boundary means more than “do some optimisation early”. It ensures that structural problems that should never land on the runtime surface are resolved at the structural layer:

Compile‑time structural decisions — type resolution, renderer binding, default expansion are done during the loading phase; runtime overhead is zero.
Compile‑time policy trimming — permission nodes, feature flag branches are removed before entering the runtime; the runtime never sees them.
Compile‑time action DAG assembly — then / onError / parallel are assembled at compile time into a cycle‑free execution graph; no graph discovery or cycle detection at runtime.
Unified Value IR — All forms of Value (literal/expression/template/array/object) are compiled into a unified IR; evaluation is unified at runtime.

If a problem can be solved at the structural transformation layer, it must never be dragged onto the runtime surface.

3. Reactive Data‑Driven

Flux’s core execution model is reactive and declarative. The author does not need to explicitly build imperative linkage logic: whenever a dynamic value reads a path from the scope via a field path, name, or ${expr}, it automatically falls into the dependency graph and will be re‑evaluated when the dependency changes.

Basic rhythm: evaluate → collect dependencies → propagate changes → targeted re‑evaluation / invalidation → republish.

Dependency tracking is a built‑in design semantic of the Value primitive. Dependencies are automatically collected during evaluation, not declared statically beforehand. Value, Resource, and Reaction all use this mechanism, but with different consequences: Value is re‑evaluated, Resource is marked dirty and refreshed, a Reaction may trigger a Capability.

The current implementation uses React and useSyncExternalStore to interface with the rendering host, but the principle itself is not tied to any UI framework.

Read/Write and Effect Separation

Read: Value / Resource published values / Host Projection snapshots are all read‑only via ScopeRef.
Write: User edits, FormRuntime.setValue, ScopeRef.update, Resource publication—these modify owner‑owned data and belong to the data owner side; they will publish store/scope changes, but that is not equivalent to triggering an action.
Command / Effect: Schema‑authored commands (API calls, setValue action, submission, navigation, host commands, etc.) are dispatched only through Capability.
Change → Effect: Data changes do not directly trigger actions; they must pass through a Reaction or a Semantic Lifecycle Entry.

Rendering Host Interfacing

The Store layer runs the reactive logic self‑consistently; React is merely a rendering host that subscribes to Store snapshots.

Settled Update Turn is a runtime‑store concept, not a React useEffect ordering concept.
React concurrent mode can interrupt, replay, and discard renders; Flux does not constrain such scheduling behaviour—it only defines when the store settles an update turn and when a stable snapshot is published.
The rendering host consumes the published results; it does not directly hold reactive protocol objects.

4. Gradual Evolution

Complex capabilities in Flux should not be obtained by continually inventing new primitives; they should grow naturally from simpler existing forms. This principle constrains two things at the same time:

The author‑visible DSL naturally extends from simple forms to complex forms without frequent mental model switches.
Complex capabilities inside the runtime should be composed from existing primitives (derived system) as much as possible, instead of expanding the primitive set under pressure.

DSL‑level evolution: natural growth from simple forms

Concept	Simple form	→	Complex form
Value	literal → expression → anonymous source	→	named `data-source` (Resource)
Action	single‑step dispatch	→	`when` guard → `then`/`onError` branches → `parallel` fan‑out → compilable to DAG execution graph
Structure	`visible` (display level)	→	`when` (lifecycle activation) → `loop` (collection expansion) → `dynamic-renderer` (remote assembly)
Host write	semantic command	→	generic patch‑style `applyPatch`

Value evolution

The same property chooses the appropriate form based on complexity. How the consumer reads the value stays the same: ${countries} remains uniform from literal to data‑source.

// literal
{ "options": ["draft", "published", "archived"] }

// expression
{ "options": "${role === 'admin' ? adminOptions : userOptions}" }

// source: field‑level anonymous request, not published to scope
{ "options": {
  "type": "source",
  "action": "ajax",
  "args": { "url": "/api/countries", "params": { "region": "${form.region}" } }
}}

// data-source: named Resource with producer lifecycle & scheduling policy
{ "type": "data-source", "name": "countries",
  "action": "ajax",
  "args": { "url": "/api/countries" },
  "interval": 3000,
  "stopWhen": "${countries.complete}" }

Action evolution

The compiler recursively assembles nested schemas into a CompiledActionNode DAG (flux-compiler/action-compiler.ts). The runtime simply traverses edges to execute; no graph discovery or cycle detection is needed.

// single-step dispatch
{ "action": "setValue", "args": { "path": "name", "value": "test" } }

// when guard: skip if condition not met, result marked skipped
{ "action": "setValue", "when": "${isEnabled}",
  "args": { "path": "name", "value": "test" } }

// then/onError branches: different paths based on ActionResult triage
{ "action": "ajax", "args": { "url": "/api/users" },
  "then":     { "action": "showToast", "args": { "message": "Save successful" } },
  "onError":  { "action": "showToast", "args": { "message": "${error.message}" } } }

// parallel fan-out + onSettled aggregation
{ "action": "parallel",
  "parallel": [
    { "action": "ajax", "args": { "url": "/api/notify/email" } },
    { "action": "ajax", "args": { "url": "/api/notify/sms" } }
  ],
  "onSettled": { "action": "showToast", "args": { "message": "Notifications complete" } } }

// form submission: submitAction owned by the form node; button is only a thin component:submit trigger
{ "type": "form", "id": "profile-form",
  "submitAction": {
    "action": "ajax", "args": { "url": "/api/profile", "method": "post" } },
  "onSubmitSuccess": { "action": "closeSurface" },
  "onSubmitError":   { "action": "showToast", "args": { "message": "${error.message}" } } }

Branch contexts (result / error / prevResult) are automatically injected into the evaluation environment during dispatching (flux-action-core/action-core.ts createBranchEvaluationBindings).

Structure evolution

visible and when are not synonyms: fields hidden by visible still participate in validation; subtrees with when=false are entirely inactive and do not participate in the lifecycle.

// visible: display‑level toggle, node still exists
{ "type": "input-text", "name": "adminCode", "visible": "${role === 'admin'}" }

// when: lifecycle activation, affects existence and subtree validation
{ "type": "fragment", "when": "${showSummary}",
  "body": [{ "type": "text", "text": "Summary content" }] }

// loop: collection expansion, each iteration gets its own repeated‑item scope
{ "type": "loop", "items": "${users}", "itemName": "user", "indexName": "idx",
  "body": [{ "type": "text", "text": "${idx + 1}. ${user.name}" }],
  "empty": [{ "type": "text", "text": "No data" }] }

// dynamic-renderer: runtime remote assembly, decides which fragment to render
// Note: it is not a second Resource facet — data‑source produces named values, dynamic‑renderer assembles fragments
{ "type": "dynamic-renderer",
  "loadAction": { "action": "ajax", "args": { "url": "/api/schema/${componentType}" } },
  "body": { "type": "text", "text": "Loading..." } }

5. Lexical Ownership

This principle is an organisational constraint for Principle 3. Data, capabilities, resources, reactions, and runtime sidecars belong to the lexical scope or subtree boundary; they are not held by a global runtime mega‑object.

Three resolution mechanisms

Data lookup (ScopeRef), action lookup (ActionScope), and instance location (ComponentHandleRegistry) are architecturally separate resolution mechanisms, each with its own scoping rules.

Lexical shadowing

Child scopes override parent publications through natural lexical shadowing, not global overrides. Bindings with the same name can independently exist in different lexical scopes:

// page scope has items
{
  "type": "page",
  "data": { "items": ["a", "b"] },
  "body": [
    // dialog child scope also has items, shadows parent
    {
      "type": "dialog",
      "data": { "items": ["x", "y"] },
      "body": [{ "type": "text", "text": "${items}" }],
    }, // → ["x", "y"]
  ],
}

Resource publication ownership

Within the same owning scope, the same binding target should not be long‑term co‑occupied by two simultaneously active publishing producers. This constraint applies to authoritative publication (continuous publication by a Resource), not ordinary writes:

// compliant: two forms write to the same path at different times
{ "type": "dialog", "body": [
  { "type": "form", "id": "createForm",
    "onSubmitSuccess": { "action": "setValue", "args": { "path": "result", "value": "${result}" } } },
  { "type": "form", "id": "editForm",
    "onSubmitSuccess": { "action": "setValue", "args": { "path": "result", "value": "${result}" } } }
]}

// violation: two data‑sources simultaneously claim to publish "status"
{ "type": "page", "body": [
  { "type": "data-source", "name": "status", "action": "ajax", "args": { "url": "/api/a" } },
  { "type": "data-source", "name": "status", "action": "ajax", "args": { "url": "/api/b" } }
]}

Runtime sidecars (Resource state, Reaction state, caches, diagnostics) follow lexical ownership, but they must not become methods or mutable protocol objects attached to a ScopeRef. The Scope hosts the data environment; it does not carry bridges, controllers, handles, or other command‑like objects.

6. Domain Isolation & Abstraction

The Flux core maintains a small, stable abstraction layer. Its goal is not to absorb all frontend domain semantics, but to provide a sufficiently stable execution kernel that allows different domains to grow outside the core.

The litmus test for this principle is not “can the core directly describe all complex systems?” but “can the core provide a stable embedding surface for complex systems without pushing domain complexity back into the core vocabulary?”

Isolation contract

Interactions between domain systems (Flow Designer, Report Designer, Spreadsheet Editor, collaborative engines, CRDT/OT, etc.) and the Flux core are narrowed down to:

Direction	Mechanism	Meaning
Core → Domain (read)	Host Projection	Read‑only snapshot projection, host‑driven refresh
Domain → Core (write)	Capability	Namespaced command dispatch (e.g., `designer:*`)
Instance location	ComponentHandleRegistry	Explicit target component instance method invocation
Host‑private	DomainBridge	`getSnapshot/subscribe/dispatch`, does NOT enter Schema‑visible Scope

Why the core stays stable

Graph algorithms, layout, collision detection, collaboration protocols, CRDT/OT, local‑first sync, gesture loops—these are all important, but they are domain systems and should not become core primitives. From Flux’s perspective, they are just production strategies behind a Resource, host snapshots behind a Host Projection, or command systems behind a Capability.
New domains plug in by declaring a host type + projection fields + capability namespace, without needing to introduce new global provider families, environment registries, or new authoritative Schema channels.
Cross‑domain generic write pattern for editable hosts: read Host Projection → write Capability (structured patch DTO) → DomainBridge host‑private.

Business semantics ownership

Business pipelines (form submission, dialog confirmation, page entry) belong to the node that owns that lifecycle boundary, not to the UI trigger. Concrete examples are given in Section 4 (Semantic Lifecycle Entry). This is a concrete manifestation of lexical ownership and domain isolation.

Summary

#	Principle	One‑liner
1	DSL First	The DSL is a first‑class structural layer independent of the runtime: editable, composable, and transformable before execution.
2	Authoring–Execution Separation	Authoring and execution serve different optimisation goals; they should be separated by a pre‑compilation boundary, not mixed in the runtime.
3	Reactive Data‑Driven	The Value primitive has built‑in dependency tracking, read/write separation, and side effects are funnelled through Capability.
4	Gradual Evolution	Complexity should grow naturally from simple DSL forms and existing primitives, not by expanding the primitive set under pressure.
5	Lexical Ownership	Data, capabilities, resources, reactions, and their sidecars belong to lexical/subtree boundaries, not to a global runtime mega‑object.
6	Domain Isolation & Abstraction	The core provides a small, stable execution kernel; domain complexity stays outside the core and embeds through a narrow contract.

nop-chaos-flux is open source:

DEV Community: canonical

Mission Driver: A General Reference Implementation of Loop Engineering

Part 1: Getting Started

1. The Problem: From Vibe Coding to Autonomous Operation

2. What is Mission Driver (One-Minute Version)

3. How It Works: Loop Nesting and Local Fault Tolerance

Part 2: Starting Out

4. Quick Start

5. The Four-Layer Definition System

5.1 Mission Config (missions/<name>.json)

5.2 Flow Definition

5.3 Plan Files

5.4 Roadmap

6. Configuration and Customization

Part 3: Practice Methodology

7. Loop as Intelligence

8. AI Auto-Generation of E2E Tests

Part 4: Case Study

9. nop-app-erp: 154 Modules in 22 Days

Scale Metrics (Independently Audited)

A Real Cycle (07-10)

Pre-Coding Defect Interception

Knowledge Transfer Curve

Part 5: In-Depth Analysis

10. Loop Engineering Principles

Stability Guarantees

Recovery Mechanism

11. Plan Loop and Verification System

Verification System: Script Checking + AI Auto-Improvement

12. AGE Theory: Attractors and Dynamical Systems

Formation of Attractors

Asynchronous Human-AI Interaction

13. Comparison with Codex Goal

Part 6: Vision

14. Goal-Driven Vision and Economic Paradigm

Shift in Economic Paradigm

15. Summary

Further Reading

Attractor Guidance and Trajectory Mining: The Convergence Mechanism of AI Native Engineering

1. AI Is a High-Frequency Random Expansion Force; the System Must Possess Endogenous Convergence Capability

2. Generic Skills Cannot Substitute for a Project-Specific Attractor

3. Information Itself Is Independent of Form, but Form Affects the Efficiency of Intelligent Computation

4. The Plan Is a Local Convergence Closed Loop and Must Accept External Auditing

5. Trajectories Are Core Objects, and Trajectory Mining Is a Generative Mechanism for Future Convergence Capability

Conclusion

Task-Level Tools vs. Trajectory-Level Methodology: The Fundamental Divide Between Trellis, OpenSpec, and AGE

Introduction

Analysis

1. Positioning: What the Three Are

2. Tool Origin: Preset vs. Gradually Emerged

Trellis: Tools Determined at Design Time

AGE: Tools Extracted Gradually from Practice

Out-of-the-Box vs. Gradual Accumulation

3. Extracting Knowledge from Failures: Two Mechanisms of Different Depth

Trellis: Extract to Prose Spec

AGE: Extract to Gradually Automated Tools

Core Differences

4. Document Organization: Domain-Adapted vs. Framework-Adapted + Normative/Historical Separation

Trellis: Framework-Preset Fixed Structure, Normative and Historical Mixed

AGE: Organized by Domain Needs, Strict Normative-Historical Separation

Core Differences

5. Plans: Closure Contracts, Not Task Lists

The Full Lifecycle of a Plan

Gradually Advancing Toward Full Automation

Comparison with Trellis

Logs: Automatically Recorded Trajectory

6. Audit System: Shared Executive Checks + AGE’s Unique Directional Audit

Common Ground: lint/test/typecheck as Commit Gates

Trellis Unique: 5-Dimension Post-Mortem

AGE Unique: Overall Document-Code Consistency Audit

7. Summary of Tool Comparison Between the Two

8. Common Limitations: Trellis and OpenSpec Are Both Task-Level Tools

Deficiency One: No Repository-Wide Truth

Deficiency Two: No Trajectory Between Single Changes

Deficiency Three: No Support Point for Evolving Toward Full AI Automation

The Relative Progress of Trellis and OpenSpec

Three-Way Comparison Table

9. The Co-Evolution of Theory and Practice

Conclusion

References

5.1 Mission Config (`missions/<name>.json`)