Documentation / Quality and governance

Measuring against N−1

How Yuli measures quality, always compares it with the previous version and makes the agent improve before testing.

Yuli measures code quality continuously and always compares it with the previous version, N−1. The rule is simple: never backwards, always forwards.

Everything is measured automatically: when you open the project, after every build, test or verification, with every new commit and in the editor as you type.

The Quality panel

Open it from the status bar indicator (for example, A · σ 4.5 ▲) or from the bottom panel.

Tab What it's for
Summary Overall grade, sigma, debt, clean code, the agent's latest measurement, upcoming improvements and comparison with N−1.
Practices The 14 clean code practices, their benefits and where to act first.
Measurement The agent's Measurement phase: verdict, checks, before → after and rounds.
Decision Refactor or evolve? Criteria, matrix and economic criterion.
Maintainability Maintainability index, cognitive complexity, duplication, coupling and debt.
Prevention Security, performance, robustness and accessibility findings.
Architecture The project's architecture rules.
Test health The state of the test suite.
Quality Cyclomatic complexity, defect Pareto, coverage and tests.
Size Lines, languages, components and function points.
Performance Per-method cost from the latest profile and REST client latency.
Statistics Probabilities, distributions and trends.
Six Sigma DMAIC, DPMO, sigma level, FPY/RTY, Cpk and control chart.
History Series for every metric and changes against N−1.
Guide Everything explained in plain words, with search.

Every section has a “?” button that explains it without jargon. “No data” is never a made-up zero: it tells you what is missing to measure.

Toolbar buttons

  • Refresh: measures again.
  • Record version: saves the measurement as the current version. The previous one becomes N−1.
  • Open report: writes docs/quality/reporte-calidad.md and opens it in the editor.

What N−1 is

Yuli keeps only two versions: the current one and the previous one. With Git, every new commit with a clean working tree is a version. A new version is also created when you click Record version and when the agent measures.

Each metric is shown with ▲ (improved), ▼ (got worse) or = (unchanged). A single worse metric is enough for the “Got worse” verdict.

The grade

The overall grade goes from A to E and combines ten ISO/IEC 25010 attributes: functionality, efficiency, reliability, robustness, security, maintainability, understandability, usability, portability and compatibility.

Grade Score Reading
A ≥ 80 Excellent
B ≥ 65 Good
C ≥ 50 Acceptable
D ≥ 35 Poor
E < 35 Critical

A critical vulnerability caps security at 59 (D) and a high one at 79 (B). A serious problem never shows green.

The 14 clean code practices

Each practice is a number with its target, measured in any language.

Practice How it's measured Target
Descriptive Descriptive names and magic numbers per KLOC ≥ 95 %
Small functions Methods of 60 lines or fewer ≥ 95 %
Avoid duplication Lines in repeated blocks of 6 or more ≤ 3 %
Readable code Methods with cognitive complexity ≤ 15 ≥ 95 %
Error handling Robustness findings per KLOC 0
Simple structures Cyclomatic ≤ 10 and nesting ≤ 4 ≥ 95 %
Consistent style Indentation, line length and naming convention ≥ 90
Meaningful names Variables that aren't noise (tmp, aux, data2) ≥ 98 %
Few parameters Methods with 5 parameters or fewer 100 %
Composition over inheritance Inheritance depth ≤ 3 100 %
Small classes ≤ 300 lines and ≤ 20 methods 100 %
No dead code Commented-out, unreachable or unused code 0
Write tests Files with logic and their own test 100 %
Refactor continuously Regressions against N−1 0

The clean code score is the average of the practices that have data. 80 or more is on target.

Six Sigma and defect density

Metric What it is
Defect density Defects per thousand lines (KLOC), with its 95 % confidence interval.
DPMO Defects per million opportunities (each line is an opportunity).
Sigma level (σ) DPMO on the classic scale: 6σ = 3.4 DPMO; 4σ ≈ 6,210. Green from 4.5σ.
Cpk Capability to keep cyclomatic complexity ≤ 10: ≥ 1.33 is capable.
FPY / RTY Builds, tests and verifications that succeed on the first try.

A finding of medium severity or higher counts as a defect.

The agent's Measurement phase

It is the fifth of the 8 phases, between Implementation and Testing. It measures only the code the task touched against the starting version.

The three moments

Phase When What it does
baseline Before changing code Records the task's starting version (N−1).
measure After implementing Compares the touched code against N−1 and gives a verdict.
after With tests green Compares with N−1 and rewrites the report.

When it passes

All of these checks must hold:

  1. Nothing got worse against N−1.
  2. At least one defect fixed (or none present). Density staying the same is not enough.
  3. Clean code improved in files that were below the acceptance level.
  4. New code is clean from the start.
  5. The logic has tests.

A file is accepted if it has 0 defects and a clean code score of 90 or more. An accepted file only has to not get worse.

The verdicts

Verdict What happens
Passed The mission moves to Testing on its own.
Iterate It goes back to Implementation with the exact list of what to fix, with file and line.
Round limit The rounds ran out: it moves on to Testing and anything pending stays in the mission.
No code to measure The task didn't touch code.

Measurement can't be skipped. If the agent tries to move to Testing, Review or Delivery with unmeasured code, Yuli rejects it. The same applies to Claude Code, Kiro, Codex and Antigravity.

Improving never changes what the software does: same use cases, same inputs and outputs.

Where you see the result

Never in the chat. The agent gives a single line with the verdict and the before → after. The details are in the Measurement tab and in the mission bar, with the See in Quality button.

Settings

In the Measurement tab or in .ai/quality.json:

Setting Default Range
The measurement is mandatory before testing Yes —
Maximum implementation ↔ measurement rounds 3 1 to 10
Acceptance level (clean code) 90 50 to 100

If there is a quality contract, its acceptance and rounds values take precedence.

In the editor

  • Above each method: CC · CoG · MI · lines · coverage · cost.
  • On the first line: the file's grade, its clean code score and its change against N−1.
  • Hints: meaningless names, magic numbers or dead code, on the exact line.

The report

A single document, docs/quality/reporte-calidad.md, rewritten with every recorded version. It includes the “Agent measurement” section. Working data lives in .ai/state/quality/ and is never pushed to the repository.

Honest limits

  • Complexity and preventive rules are computed with text patterns. They can produce false positives. Java and JSP also use syntax trees.
  • Estimates (Time-to-Market, costs) use recognized models with editable assumptions. They are meant for decision-making, not as a contractual budget.