Date: 2026-08-28 Status: architecture hypothesis / implementation plan
../../ITERATION_MODEL.md is the canonical whole-system vocabulary and lifecycle; this document specializes it for repository-structure observation and graph rewrites.
Make IDKMesh progressively better at maintaining and reorganizing itself without creating an uncontrolled self-modifying repository.
“Self-evolving” should mean:
the repository can observe its own structure and outcomes, detect weaknesses, propose bounded graph transformations, test alternative structures, learn which transformations improve project health, and eventually automate a carefully limited subset of low-risk changes.
It must not mean:
an AI agent can rewrite policy, architecture, permissions, tests, and documentation simultaneously and then approve its own change.
The central design is a closed feedback loop over the IDKGraph project representation.
Let repository state at iteration t be
R_t = (G_t, C_t, M_t, P_t, H_t)
where:
G_t = semantic IDKGraph: goals, tasks, evidence, documents, concepts, decisions, artifacts, contributors;C_t = repository contents/code/documentation;M_t = measured health metrics;P_t = current policies and rewrite rules;H_t = provenance/event history.Evolution is a controlled transition
R_(t+1) = F(R_t, a_t, e_t)
where a_t is a proposed action/rewrite and e_t represents external evidence, contributor activity, tests, and new research.
The project should learn policies for selecting a_t, but the allowed action space is constrained by invariants.
A practical baseline is a Monitor–Analyze–Plan–Execute loop around shared Knowledge.
Continuously derive repository observables:
Convert observations into candidate diagnoses:
The analysis must retain confidence and evidence rather than pretending every diagnosis is true.
Generate one or more bounded rewrite plans.
Examples:
Execute only in a sandbox branch/worktree/PR, then run invariant checks, documentation checks, tests, and review.
Record:
This turns repository maintenance into a dataset from which future policy can learn.
Never define “better repository” with a single vanity metric.
Define a health vector
h(R) = (
` correctness,
consistency,
provenance_coverage,
navigation_quality,
modularity,
discoverability,
testability,
newcomer_accessibility,
uncertainty_reduction,
reviewability,
security,
maintainer_leverage
)`.
A diagnostic energy/potential can be used for controllers:
V_repo =
` w_b * BrokenLinks
+ w_o * OrphanNodes
+ w_c * Contradictions
+ w_d * Duplication
+ w_s * Staleness
+ w_p * MissingProvenance
+ w_x * UnresolvedDependencyCycles
+ w_r * ReviewBacklog
+ w_n * NavigationCost
+ w_k * UnsafeCoupling
+ w_u * UnverifiedVolume`.
Lower is generally better, but a rewrite cannot be accepted merely because this scalar decreases. Hard invariants and Pareto trade-offs come first.
Construct G_doc from:
Then derive structural metrics.
O = number_of_unintentionally_orphan_nodes / number_of_document_nodes.
B = broken_internal_links / internal_links.
Let S be newcomer entry points and K important canonical documents.
NavCost = average_(s in S,k in K) shortest_path(s,k)
with unreachable nodes assigned a large penalty.
For canonical concept c, let D_c count incompatible or unnecessarily duplicated definitions. Prefer one canonical definition plus contextual explanations.
For each accepted Decision node, require paths to affected architecture/specification nodes. Missing paths are consistency defects.
Use graph Laplacian algebraic connectivity lambda_2 to detect weakly linked islands. A low value does not automatically justify adding links; links must be semantically meaningful.
Repository structure faces a compression trade-off:
Minimum Description Length suggests an objective of the form
L_total = L(structure) + L(content | structure).
For IDKMesh, an experimental approximation is
MDL_repo = complexity_of_taxonomy_and_crosslinks + residual_duplication + exceptions + repeated_explanations.
Use MDL thinking when deciding whether to:
Do not minimize raw token count. Human comprehension, onboarding, and auditability are part of the cost model.
A repository should be modular but connected.
For a weighted concept/dependency graph, community detection/modularity can suggest candidate modules. Spectral partitioning and graph cuts can identify clusters with dense internal coupling and sparse external interfaces.
For a partition P, a restructuring objective can be
J_partition = InternalCohesion - alpha*CrossBoundaryCoupling - beta*InterfaceComplexity - gamma*MoveCost.
Candidate boundaries should then be checked against semantic ownership and architectural invariants.
This can discover when:
Automated clustering generates proposals, not authoritative architecture.
Represent self-evolution actions as explicit rewrite rules rather than arbitrary edits.
A rule has
r = (Pattern, Preconditions, Transformation, Postconditions, RiskClass).
Candidate rewrite library:
AddMissingLinkPreconditions:
Postcondition:
SplitDocumentPreconditions:
Postconditions:
MergeDuplicateConceptsPreconditions:
Postcondition:
ArchiveSupersededPreconditions:
superseded_by relation;Postcondition:
PromoteRepeatedFindingPreconditions:
Transformation:
TaskDecompositionSplit a WorkUnit when size, uncertainty, reviewability, or actor-capability mismatch exceeds thresholds.
CreateBridgeCreate a boundary artifact/task linking disconnected disciplines/modules when measured cross-cluster dependency exists.
Formal graph-transformation theory such as the double-pushout family is relevant because it provides disciplined conditions for deleting/gluing graph structure. IDKMesh does not need to implement full category-theoretic machinery in P0, but its precondition/transformation/postcondition discipline is valuable.
Some restructuring problems have no obvious locally optimal rewrite.
Maintain candidate repository structures or rewrite sequences:
Population_t = {R_t^1, R_t^2, ..., R_t^m}
and apply
variation -> validation -> evaluation -> selection.
Mutation operators are the typed graph rewrites above.
Candidate fitness dimensions:
Use multi-objective selection such as Pareto ranking rather than one fitness number.
A MAP-Elites / quality-diversity style experiment is also attractive: keep good candidate structures in different niches such as “fewest files,” “best newcomer navigation,” “lowest coupling,” and “lowest migration cost” instead of prematurely choosing one global best.
Only one approved structure enters the canonical repository. Alternative candidates remain experiment artifacts.
Some beneficial restructures temporarily make metrics worse. Moving documents may temporarily increase redirect complexity before duplication is removed.
For sandbox candidates, a simulated-annealing acceptance rule can explore such moves:
P_accept = min(1, exp(-DeltaE/T)).
Use this only inside search/simulation. The main branch still requires explicit acceptance conditions and verification.
High T early in a restructuring experiment preserves alternatives. Lower T later increases convergence.
Let policy i be one approach to maintaining the repository:
Track policy performance f_i. A replicator-style model
dx_i/dt = x_i * (f_i - f_bar)
or a multi-armed bandit can allocate more experiment budget to policies that perform well while retaining exploration.
Fitness should include long-term regressions and reviewer burden, not merely immediate metric improvements.
Biological systems often regulate variables around viable ranges rather than maximize them.
IDKMesh should similarly maintain homeostatic bands:
Example error signal:
e_t = target_review_latency - observed_review_latency.
A PID/adaptive controller could tune task-generation rate or agent fan-out. P0 can use simple threshold/rate-limited controllers before introducing complex control.
Use biological immunity only as a disciplined analogy.
Repository “immune” functions include:
A new autonomous rewrite first enters a quarantine branch, not main.
Previously observed failure patterns become reusable detectors/tests, analogous to memory but implemented concretely as regression tests, policies, or signatures.
Tools compute health metrics and generate reports only.
System opens issues or suggestions for human selection.
System opens bounded pull requests in low/medium-risk areas; humans review/merge.
Only highly constrained operations such as generated indexes, formatting, or dependency metadata may self-merge after deterministic checks and branch-protection rules.
System may generate and compare repository/document/task-graph restructures, but semantic structural changes still require independent approval.
System experiments with coordination/maintenance policies and recommends new policies from measured evidence. Fundamental safety/governance constraints remain constitutionally protected and require explicit governance approval.
The project should earn each level empirically rather than declaring itself autonomous.
repeat every evolution epoch:
G <- build_IDKGraph(repository, issues, decisions, evidence)
H <- measure_health(G, repository, community_metrics)
anomalies <- detect_defects_and_opportunities(G, H)
candidates <- []
for anomaly in highest_value(anomalies):
plans <- apply_allowed_rewrite_rules(G, anomaly)
for plan in plans:
G2 <- simulate(plan, G)
if violates_hard_invariant(G2):
reject(plan)
continue
metrics2 <- estimate_health(G2)
candidates.append(plan, metrics2, uncertainty)
frontier <- pareto_rank(candidates)
selected <- choose_by_risk_information_gain_and_budget(frontier)
for plan in selected:
execute_in_branch(plan)
run_deterministic_validation()
run_independent_critic()
run_tests_and_doc_checks()
if policy_allows_auto_merge(plan.risk) and all_checks_pass:
merge_with_provenance()
else:
request_independent_review()
after_observation_window:
record_actual_effect_of_accepted_changes()
update_rewrite_policy_statistics()
The loop optimizes evidence-backed improvement, not edit frequency.
Build a tool that exports:
Output a machine-readable graph plus Markdown report.
Implement graph/document invariants and fail CI on deterministic violations.
Implement AddMissingLink, GenerateIndex, ArchiveSuperseded, and TaskDecomposition as proposal-only transformations.
Allow a local/open agent to create a branch and PR for approved low-risk rewrite types. Require independent review.
Run multi-objective/evolutionary search in simulation and compare candidate repository structures.
Use outcome history to tune rewrite selection/task decomposition thresholds while maintaining protected invariants.
The Vision of Autonomic Computing, IEEE Computer 36(1), 2003, DOI 10.1109/MC.2003.1160055.Formalising the Double-Pushout Approach to Graph Transformation, arXiv:2312.15641.IDKMesh should pursue guarded semantic self-evolution: observe the repository as a graph, propose typed transformations, test them in isolation, measure their effects, and learn which transformations help.
The repository may become progressively more autonomous, but autonomy is an earned capability constrained by provenance, independent verification, protected invariants, reversibility, and governance.