How Intelligence Works

Vreko’s intelligence layer computes three categories of behavioral signal from observed development sessions: fragility scores, co-change relationships, and AI attribution. These signals are surfaced in agents.workspace.json and translated into agent instructions by AGENTS.md.

This page explains how each signal is computed and what the numbers mean.

Fragility scores

A fragility score is a 0–10 measurement of how risky a given file is to modify, based on observed behavior.

What a score of 9.1 means: This file has high historical churn (it changes frequently), its changes have a meaningful revert rate (modifications are often rolled back), it co-changes with other complex files, and a high fraction of its sessions show AI-assisted editing patterns. Modifying this file carries above-average risk of introducing problems.

What a score of 2.3 means: This file changes rarely, when it does change it stays changed (low revert rate), it changes independently of other fragile files, and most sessions are human-authored. This file is stable.

Score components

Fragility is computed from four inputs weighted by the intelligence model:

Component	What it measures
Historical churn	How often the file has been modified
Revert rate	What fraction of changes were later reverted
Co-change complexity	How many other files are typically modified in the same session, weighted by their fragility
AI attribution ratio	What fraction of sessions involving this file show AI-assisted editing signatures

High values across all four inputs produce high fragility. A file can have high churn but low fragility if its changes are never reverted and it changes alone in human sessions.

Score accuracy by intelligence state

During INSUFFICIENT_DATA, fragility scores are seed-based estimates. The model has not yet observed your workspace’s specific churn patterns. Treat these scores as informed starting points.

During OBSERVING, scores increasingly reflect your actual observed data. The model is weighting your workspace’s patterns against the seed estimates, gradually shifting toward measurement.

During CONFIDENT, scores reflect your real codebase behavior. They are reliable enough to use as governance inputs and as the basis for co-change instructions in AGENTS.md.

Fragility scores are not quality scores. A high fragility score means a file warrants careful agent handling - not that the code is bad. Some files are inherently high-churn because they are actively evolving features. Vreko observes this without judging it.

Co-change relationship detection

Co-change relationships are file pairs (or groups) that are modified together in the same session more often than would be expected from random variation.

How they are detected

Vreko tracks which files appear in the same session. After enough sessions, files that consistently co-change have a high co-occurrence score. The threshold for surfacing a co-change relationship in agents.workspace.json is typically 0.75 co-occurrence across at least 5 observed sessions.

Session 1: billing.ts, stripe.ts, config.ts
Session 2: billing.ts, stripe.ts
Session 3: billing.ts, stripe.ts, auth.ts
Session 4: billing.ts, stripe.ts

Co-occurrence(billing.ts, stripe.ts) = 4/4 = 1.0
Co-occurrence(billing.ts, config.ts) = 1/4 = 0.25 → below threshold

A co-occurrence of 1.0 means every session that touched billing.ts also touched stripe.ts. This is not detected from file contents - it is detected purely from observing which files move together in practice.

Why this matters for agent behavior

AI coding assistants often do not know which files need to move together. They reason from file contents and imports, which captures explicit coupling but misses implicit coordination. Vreko’s co-change data captures the implicit coupling - the convention that “when you touch billing, you also touch stripe” - and surfaces it in AGENTS.md so agents follow the same convention.

Co-change detection accuracy

Co-change relationships require observed sessions to be reliable. During INSUFFICIENT_DATA, there are too few sessions for statistically meaningful relationships. During OBSERVING, early relationships begin to emerge. In CONFIDENT, co-change data reflects stable coupling patterns.

AI attribution

AI attribution measures what fraction of the sessions touching a given file show AI-assisted editing signatures.

How AI sessions are detected

The daemon applies a clustering algorithm (DBSCAN) to the file event stream. Sessions are grouped by temporal density - rapid, high-volume bursts of edits to multiple files match AI-assisted patterns. Human sessions show more irregular timing and narrower file scope.

Each session receives a classification: human, ai-assisted, or mixed. The attribution ratio for a file is the fraction of its sessions that are classified as ai-assisted or mixed.

// agents.workspace.json
{
  "aiAttribution": {
    "apps/web/src/components/Dashboard.tsx": 0.73,
    "apps/api/src/routes/users.ts": 0.41,
    "lib/utils/date.ts": 0.08
  }
}

An attribution of 0.73 means 73% of sessions that touched Dashboard.tsx were AI-assisted. This does not mean 73% of the file was written by AI - it means 73% of the editing sessions on the file happened in an AI-assisted context.

What attribution is used for

AI attribution is one input to fragility scoring. It is also surfaced as a standalone signal in agents.workspace.json and as a note in AGENTS.md for high-attribution files.

High AI attribution does not automatically increase fragility. It is weighted alongside churn and revert rate. A file that has high AI attribution but low revert rate and low churn is not fragile - it just happens to be a file AI tools are comfortable editing accurately.

INSUFFICIENT_DATA and scoring accuracy

The cold-start problem in behavioral intelligence is real: a new workspace has no observations to learn from. Vreko addresses this in two ways:

Seed knowledge: On vr init, the daemon seeds the workspace with a shared knowledge template covering common fragility patterns across many codebases. Scores during INSUFFICIENT_DATA are informed by this seed data, not blank.
Structural signals: The init scan captures structural signals (file count, detected stack, package density) that inform early estimates before behavioral observations accumulate.

These mitigations make INSUFFICIENT_DATA scores useful as starting points, but they are not substitutes for observed behavior. The model transitions to OBSERVING and CONFIDENT as real sessions accumulate.

CONFIDENT and predictive intelligence

In the CONFIDENT state, the intelligence model has enough workspace-specific data to be predictive rather than just descriptive. This enables:

Reliable fragility scores - grounded in observed churn and revert patterns from your codebase
Stable co-change relationships - based on statistically significant session co-occurrence
Calibrated AI attribution - with enough sessions to distinguish your coding patterns from AI-assisted ones accurately
Governance inputs - fragility thresholds have real data to enforce against

CONFIDENT is not a ceiling. The model continues to refine as sessions accumulate. Files that stabilize over time see their fragility scores decrease. New files with rapid early churn see scores increase until they stabilize.

Intelligence States - INSUFFICIENT_DATA, OBSERVING, CONFIDENT explained
agents.workspace.json - where all three signals are surfaced
AGENTS.md - how scores become agent instructions