Skip to content

Scalar objectives

A scalar objective tracks a number per sector, such as lines of legacy code or any per thousand lines. The number may not get worse, and the objective is met at target.

objectives:
legacy-lines:
measure: { lines: true }
direction: down
target: 0
any-density:
measure:
ratio:
of: { report: { command: node ./campaign/any-sites.mjs, format: regex, pattern: "..." } }
per: { lines: true }
scale: 1000
direction: down
tolerance: 0.5
probes:
fires: [{ path: src/a.ts, source: "let x: any;", report: [{ line: 1 }] }]

A scalar has measure instead of match or sector, and no holdout.

Field Meaning
measure Where the number comes from. See below.
direction Which way is better: down or up. Required.
tolerance How far from the recorded value still counts as unchanged, for a number that wobbles. Default 0.
target The value at which it is met. Required if a phase names the objective. Without one, it only ratchets.

Each measure is counted per file and summed over the sector.

measure Per file
lines: true Non-blank lines, comments included. Reformatting is not progress.
files: true 1, so the value is the sector’s file count.
report: <term> The diagnostics a report term puts on it.
fn: module#export The number a CampaignMeasure function returns.
ratio: { of, per, scale } Two of the above. The sector’s value is scale × Σof / Σper, or 0 when Σper is 0.
command: <shell> Not summed: runs once from the repository root; its output is read whole, or through a pattern with a value group. Only for a campaign with no perimeter.

A function or command returning anything but a finite number ≥ 0 fails check.

The ledger records each sector’s value. If the value moves past tolerance, check fails:

  • Worse: accept it with objectives concede --sector <sector> --reason … (--holdouts is refused).
  • Better: run objectives clear to record it, so the gain can’t be given back.

A phase may name only a scalar with a target; the sector leaves the phase when the value reaches it. A scalar no phase names only ratchets. The editor rule never reports scalars.

A report or fn source requires probes.fires. Each fires file must measure above zero (or exactly its value); each ignores file must measure zero. lines and files need no probes; command takes none.