Copied to Clipboard
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)T ∇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)T = −J(x), represents lossless energy routing |
| R(x) |
Positive semidefinite dissipation matrix, satisfying R(x) = R(x)T ≽ 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 yTu |
Taking the derivative of H along system trajectories:
dH/dt = (∇H)T ẋ = (∇H)T J ∇H − (∇H)T R ∇H + (∇H)T G u.
Since J is skew-symmetric, for any vector a we have aT J a = 0. Therefore:
dH/dt = − (∇H)T R ∇H + yT 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)) ≤ ∫0t y(τ)T 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:
u1 = −y2, u2 = y1,
then the sum of the two port powers is:
y1T u1 + y2T u2 = y1T (−y2) + y2T y1 = 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 ], ST = −S.
For any 2D vector z, we have zT 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 1⁄2 zT z:
d/dt (1⁄2 zT z) = zT ż = zT (ω S z) = ω zT 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