idkmesh

Repository Evolution Observatory v1

Status: proposed canonical upgrade of the existing IDKMesh Evolution Loop
Date: 2026-08-28

Purpose

IDKMesh needs one repository-level feedback loop that can answer:

Given the current observable state, what bounded intervention is most likely to improve verified useful work without outrunning review, safety, or community capacity?

The Observatory is an observer and recommender, not an autonomous integrator.

It upgrades .github/workflows/evolution-loop.yml; it does not introduce a second write-capable self-evolution controller.

Core rule

The previous loop accumulated soft event evidence in a checkpointed state. That model remains useful as a mathematical/evidence experiment, but cumulative event state can be mistaken for current repository condition.

Repository Observatory v1 therefore evaluates a fresh bounded snapshot:

current GitHub/repository snapshot
 -> deterministic measurements
 -> bounded mathematical response
 -> recommendation artifact

Every live observation recomputes current condition. Historical learning, when added, must be bound to explicit outcomes/lineage rather than hidden runner-local memory.

Compatibility boundary: two models, two scorer modules

The repository deliberately keeps two different mathematical surfaces instead of overloading one CLI:

This separation is intentional. A new repository-control model must not silently break the older mathematical evidence path, and the legacy event scorer must not be mistaken for current-state observation.

Evidence collected

The live collector uses bounded repository/public metadata:

Natural-language bodies/comments are not stored in the artifact and are not executed or sent to an LLM. PR/issue body text is reduced only to deduplicated numeric same-repository references, capped at 32 per item.

The collector is also bounded by page/review caps. Truncation is retained as evidence rather than silently interpreted as completeness.

Algorithm stack

These are inspectable engineering hypotheses, not claims that software repositories literally obey biological or physical laws.

1. Ecological carrying capacity

Reuse the ACE live-open-work-v1 pressure model:

L =
    1.00 * ready_PRs
  + 0.25 * draft_PRs
  + 0.50 * open_Growth_Seeds
  + 0.10 * min(other_open_issues, 20)

Capacity(L) = 1 / (1 + exp((L - K) / tau))

Bootstrap values remain K = 8, tau = 2 until real reviewer-latency/backlog data justifies calibration.

Important property:

open work falls -> L falls -> capacity recovers

2. Shannon work-mix diversity

Open work is mapped to coarse public categories. Normalized Shannon entropy is an inspectable diversity proxy:

H = -sum(p_i * ln(p_i)) / ln(k)

Higher entropy is not automatically better; it is only evidence about concentration of the work surface.

3. Bounded dependency graph

Same-repository #N references between open items create a structural coordination graph:

open item -> referenced open item

Incoming references are a capped unlock/dependency proxy, never correctness evidence. Repetition from one source is deduplicated.

4. Replicator-mutator response

The current strategy set is:

A one-step allocation response uses:

w_i* = w_i * exp(eta * (f_i - mean_fitness))
w_i' = (1 - mu) * normalize(w_i*) + mu / n

mu > 0 preserves a non-zero exploration floor. This is a current-state response, not historical learning.

5. Feedback-control deficit proxy

The observer computes deficits for:

It reports:

V_proxy = sum_j alpha_j * deficit_j^2

Lower is directionally better under configured targets. This is not a Lyapunov stability proof.

6. Multi-objective bounded action priority

Candidate recommendations use an inspectable priority shape:

Priority(a) ~
  value * confidence * unlock * community_leverage * reversibility
  ----------------------------------------------------------------
  1 + review + complexity + coordination + risk

Hard invariants outrank this scalar.

Recommendations include protecting main through #35, obtaining independent review, inspecting reviewed work for integration, pinning floating workflow actions, improving starter-task supply, or converging stale branches. The workflow executes none of them.

Modes

The deterministic repository scorer can emit:

GUARD
CONSOLIDATE
VERIFY
ONBOARD
INTEGRATE
EXPLORE

Examples:

No mode grants write or merge authority.

Anti-Goodhart boundary

These are explicitly excluded from fitness:

They may be discovery/attention context elsewhere, but they do not establish correctness or verified improvement.

Workflow security model

Trusted live observation

Live observation is triggered by bounded issue lifecycle, PR metadata, review, main push, manual dispatch, and daily schedule events. There is deliberately no per-comment trigger: comments may contribute to the bounded 30-day external-participant observation when another observation runs, but comment spam cannot directly amplify API/Actions execution.

Pull-request metadata observation uses pull_request_target so the workflow definition comes from the trusted default branch. The live job explicitly checks out the default branch, never PR-head code.

Job-scoped permissions are only:

contents: read
issues: read
pull-requests: read

Checkout credentials are not persisted. The live collector receives the ephemeral token only for bounded GitHub metadata reads. It has no secrets, contents-write, issue-write, PR-write, Actions-write, approval, branch-mutation, or merge authority.

PR-head verification

A separate ordinary pull_request job runs deterministic compile/unit tests against proposed code with contents: read only. It does not invoke the live API collector.

The observer tests explicitly require that:

Supply chain

The Observatory workflow’s third-party actions are pinned to reviewed immutable SHAs. The live observer also measures pin coverage in the rest of .github/workflows/ and may recommend hardening; it does not silently rewrite other workflows.

Event storms and compute budget

Canonical checkpoint-producing events use one concurrency group with cancel-in-progress: true:

many rapid canonical events -> cancel stale canonical observation -> compute newest snapshot

Advisory pull_request_target observations use a separate group because their artifacts are deliberately ineligible as checkpoint parents. This prevents the PR-close event emitted by a merge from cancelling the authoritative main-push observation. PR-head tests use a third per-PR group, so proposed-code verification cannot cancel either observer class.

A daily scheduled observation provides quiet drift detection.

Output

Each successful live run retains for 30 days:

results/evolution/repository-snapshot.json
results/evolution/evolution-decision.json
results/evolution/EVOLUTION_REPORT.md

The job summary publishes the human-readable report. These outputs are decision-support evidence, not canonical-state mutations.

GitHub API rate-limit exhaustion is an explicit unavailable observation, not a negative repository result or an implementation failure. In that state the job records a blocked summary and publishes no decision, recommendation, or Bayesian checkpoint. Other HTTP and authorization failures remain hard workflow failures.

Hard external gates

The Observatory must remain fail-closed around capabilities it cannot enforce itself:

Relationship to ACE, IDKGraph, and verification

The Observatory is a consumer/recommender, not a replacement controller:

Long-term direction remains a guarded composition of repository, collaboration, and evidence graphs—not parallel competing sources of truth.

Priority uncertainty and unevidenced inputs

The priority score is a ratio of nine inputs. They are not all the same kind of number, and a bare score does not distinguish them, so every recommendation now carries the provenance of each input:

Kind Meaning
snapshot_derived computed from observed repository state
snapshot_conditioned_prior a hand-authored constant selected by an observed boolean — the branch is evidence, the magnitude is not
hand_authored_prior a hand-authored constant with no evidence behind it

Only the first is evidence. Today exactly one input is ever snapshot_derived: unlock, computed from dependency-graph in-degree, and only for pull-request actions. Every other input in every action is authored. The remaining two kinds are the target list for replacing hand-authored evolution priors with derived evidence.

Sensitivity bounds, not confidence intervals

Each recommendation also carries priority_bounds: the score recomputed with every unevidenced constant moved by a declared fraction, once in the direction that helps it and once in the direction that hurts it. Observed inputs are never perturbed.

These are sensitivity bounds over authored inputs, not a posterior over an observed sample, and the perturbation fraction is itself authored. The output says so in a machine-readable field, bounds_are_a_confidence_interval: false, precisely so the number is not mistaken for a calibrated interval. There is no sample here to form a posterior from; presenting one would be the failure mode this section exists to prevent.

What the bounds currently say

separated_from_next reports whether a recommendation’s bounds clear the next one’s. On the observer’s own test fixture, at a 25% perturbation, no adjacent pair is separated: the ranked list is not ordered by evidence, only by authored constants that happen to differ. A consumer that reads recommended_actions[0] as “the most important thing to do next” is reading a preference, not a measurement.

This is not a defect introduced by the bounds; it is a property the scorer always had, now visible. It is pinned as a test, so a future change that makes the ranking genuinely separable will fail that test and have to be updated deliberately.

Falsification and calibration

Treat the model as wrong or incomplete if, for example:

When enough outcome data exists, replace hand-authored pressures with calibrated estimates and retain negative results.

Community impact

A strong repository action should make the project more inspectable, not more mysterious. The Observatory therefore publishes its inputs/proxies, formulas, blockers, strategy weights, recommendations, authority limits, and scientific caveats so contributors can challenge individual assumptions without access to a hidden autonomous agent.

This site is open source. Improve this page.