KPI Dictionary · Metric contract template

The metric contract template

A metric definition that lives in a slide deck is a rumour. This is the written form the practice uses instead: twenty-nine fields, one document per production metric, versioned in a repository and read by the semantic layer as well as by people. Every field carries the failure it prevents and a worked example taken from a dashboard that publishes it.

Verified August 2026

The worked examples below are current to the date above — verify against the live contracts on the showcase dashboards before you build.

Why a contract

Most supply chain metrics have no standard definition to inherit. The KPI Dictionary makes that concrete metric by metric: OTIF is a set of switches, not a formula, and no definition of plan attainment was located in the published sources the practice searched — the S&OP reference build names those sources on the face of its own contract. Somebody has to author one. The contract is where that authorship is written down, dated and owned.

It is one document per production metric, agreed with the people who will be held to the number, stored beside the code rather than in a deck, and referenced by the semantic layer that serves it. Nine of the twenty-nine fields are read by machine — the semantic layer, the tests — and the rest are read by people, but all of them are read by someone a year from now who has to defend a figure whose author has left.

What it is not. It is not a standard, and it does not make an authored definition into an inherited one. Two of its fields exist precisely to stop that: definition_status says how hard the definition can be leaned on, and standard_refholds the literal value “authored — no definition located in the published sources the practice searched” where that is the honest answer. On most of the metrics this practice publishes, it is.

The twenty-nine fields

Twenty-nine fields in four groups. Each row names what the field holds, why it is in the template, the failure it prevents when it is filled in honestly, and a worked example — most examples are real values from a live dashboard, and those marked lifted are character-identical copies of that dashboard's own contract, pinned by test so a retune cannot leave a quotation here quietly wrong.

A field marked M is consumed mechanically — it is what the semantic layer's measure definitions and the data-quality tests read, not only what a reviewer reads, and it is the same marker the copyable template carries. A field with an applies to note is conditional rather than mandatory; everything else is filled on every metric, and where it genuinely does not apply the contract says why rather than dropping the line.

Identity

Who the metric is, how hard its definition can be leaned on, and who answers for it. These fields are what let a reader a year from now tell an inherited definition from an authored one — and know which person to ask about each.

Each identity field of the metric contract, what it holds, why it exists and the failure it prevents, and a worked example with the dashboard it comes from
Field	What it holds	Why / failure it prevents	Worked example
metric_id — read by the semantic layer and the tests	A stable house identifier for the metric, never reused for a different definition.	The id is what the semantic layer, the tests and the change log all key on. Names change; the id must not. Prevents: A retired definition and its successor sharing a key, so history silently reports two different metrics as one series.	otifService & Delivery Performance — OTIF contract
display_name	The name as a reader sees it, qualified by the conventions that make it one number rather than several.	The common metric names are not standardized. A bare name is an invitation for two teams to compare numbers that were never the same measurement. Prevents: Two reports both titled OTIF, computed at different grains against different promise dates, presented side by side as though they disagreed about performance.	OTIF — order-line grain, vs original commit date, ship basisService & Delivery Performance — the tile-face convention
plain_definition	What the number means, in a sentence someone outside the analytics team can check.	The formula is not the definition. If the plain sentence and the arithmetic below it disagree, the contract has caught a real defect before anyone shipped it. Prevents: A definition nobody in the business can dispute because nobody in the business can read it.	The share of order lines that arrived on time AND complete. One line, both conditions, counted once — not an on-time number and a fill-rate number multiplied together.Service & Delivery Performance — OTIF, lifted from the live contract
definition_status	One of three values: standardized, narrowed from a standard, or authored house convention.	It tells a reviewer how hard the definition can be leaned on, and it is the field that makes an authored convention honest rather than implied. Prevents: House arithmetic presented with the authority of an industry standard — the quiet over-claim that collapses the first time a client's own reference is opened.	authored house convention — the dictionary entry for OTIF opens by saying there is no standard OTIF, only a set of decisions someone has to makeKPI Dictionary — OTIF
standard_ref	The named public standard, its edition, and the code within it — or the literal value “authored — no definition located in the published sources the practice searched”.	The edition belongs in the key, not in a footnote: codes get reused and renumbered between editions, so a bare code is ambiguous the moment the standard is revised. Prevents: A citation that points at a different metric than it did when it was written, and an authored definition passing as an inherited one because the field was left blank.	authored — no definition located in the published sources the practice searched — the S&OP reference build names the sources it scanned on the face of its own contract, and none of them define plan attainmentS&OP / Demand Review — plan attainment
version_and_change_log	The current version number, and a dated row per change: what moved, who moved it, and why.	A published figure has to be traceable to the version of the definition that produced it, or last year's numbers cannot be defended at all. Prevents: A definition quietly revised mid-year, and a trend line that reads as performance when it is really two metrics stitched together.	1.0.0 — ratified at definition workshopVersioning and change control, below
owner	Two owners by role, never by name: the business owner who decides what the metric means, and the data owner who answers for the pipeline behind it.	The two questions a metric raises — is this the right definition, and is this number right — go to different people, and roles outlast the individuals holding them. Prevents: An alert or a variance with nobody to route it to, which is how a governed metric becomes noise everyone has learned to ignore.	Business owner: customer service lead. Data owner: order-to-cash pipeline owner. Roles, so the contract survives a reorganisation.Service & Delivery Performance

Computation

The arithmetic, and every switch the arithmetic hides. Most fields here are mandatory; several apply only to a family of metrics and say so. The last field, conventions rejected, is this practice's own extension to the template: a contract that states only what was chosen reads as though nothing else was possible, and the alternatives are exactly what a reviewer will raise.

Each computation field of the metric contract, what it holds, why it exists and the failure it prevents, and a worked example with the dashboard it comes from
Field	What it holds	Why / failure it prevents	Worked example
numerator — read by the semantic layer and the tests	The exact numerator, written over additive component columns rather than over another ratio.	Storing the components and exposing the ratio as a view is what makes a metric correct at every grain without any re-aggregation logic. Prevents: A stored ratio that can only be averaged afterwards — the single most common way a portfolio number ends up wrong and plausible.	Σ order lines shipped on or before their original commit date AND shipped complete.Service & Delivery Performance — OTIF, lifted from the live contract
denominator — read by the semantic layer and the tests	The exact denominator, stated as a population rather than as “the total”.	Almost every disagreement about a rate is a disagreement about its denominator, and the denominator is the half nobody writes down. Prevents: Two teams computing the same numerator over different populations and arguing about the resulting gap for a quarter.	Σ active order lines committed in the selected window.Service & Delivery Performance — OTIF, lifted from the live contract
grain — read by the semantic layer and the tests	The declared grain, written as “one row per … per …”, plus the roll-up rule that follows from it.	Grain is the first thing a fact table declares and the first thing a metric argument turns out to be about. Prevents: A number that moves with average order size rather than with performance, because nobody said whether a line or an order was being counted.	order-line grain · vs original commit date · ship basis — recomputed from summed numerator and denominator at whatever scope you select.Service & Delivery Performance — OTIF, lifted from the live contract
lag_and_level — read by the semantic layer and the testsApplies to: Accuracy and attainment metrics	The vintage the plan or forecast is read at, and the hierarchy level it is scored at — both as parts of the grain, never as attributes.	The same plan restated at a different vintage is a different number, and error at item level is a different number from error at family level. Neither is a filter on one metric; they are two metrics. Prevents: Pooling across vintages, which counts every month once per snapshot age — and scoring the freshest plan, which improves a dashboard by definition rather than by planning better.	Σ\|plan − actual\| ÷ Σ actual, at lag 3, the house scored vintage — recomputed from summed numerator and denominator at whatever scope you select.Plan vs Actual — WMAPE, lifted from the live contract
time_basis	Cohort or completion: whether the period holds the obligations that came due in it, or the work that was finished in it. Named, never mixed.	The two answer different questions and move differently under a backlog. A metric that mixes them can improve because work was finished late. Prevents: A service figure that rises in the month a backlog is cleared, which reads as recovery and is really arithmetic.	Cohort basis: the denominator holds the order lines committed in the selected window, whatever month they eventually shipped in.Service & Delivery Performance — the denominator on every tile
promise_basis	Which date the promise is measured against: what the customer requested, what was first committed back, or what the commit currently says.	An on-time metric is undefined until this is stated. The three are materially different numbers on the same orders. Prevents: Re-dating a late order into being on time — a change nobody has to make dishonestly for the number to become meaningless.	Original commit date is the house basis, with the current-commit figure published beside it rather than instead of it, so the gap between them stays visible.Service & Delivery Performance — Definitions & Official Numbers
plan_version_basis — read by the semantic layer and the testsApplies to: Plan and schedule metrics	Which plan version sits in the denominator, named by its role — the locked commitment, the latest estimate, the released schedule. Two answers means two contracts.	Published constructions compute attainment against an unspecified “the plan”, which silently permits moving the plan and then scoring against the moved one. Prevents: A plan-versus-actual number that measures how recently the plan was edited rather than how well the business planned.	Σ consensus plan (locked) over the closed plan months of the selected cycle.S&OP / Demand Review — plan attainment, lifted from the live contract
overshoot_ruleApplies to: Attainment metrics	What happens above 100%: uncapped, capped per row before summing, or binary. With the reason, because the choice is not obvious.	Incompatible treatments are all in circulation and none is standard, so the rule has to be chosen and defended rather than inherited. Prevents: An overbuild on one item silently paying for a shortfall on another, and a portfolio reading on plan with nothing on plan.	Σ actual ÷ Σ plan, at lag 3, the house scored vintage — uncapped, so overshoot reads above 100%.Plan vs Actual — attainment, lifted from the live contract; it is uncapped, the S&OP demo caps, and both say so
sign_convention	For any signed measure: which way round the subtraction goes, and what a positive number means in words.	Both directions are defensible and neither is standard, so the only defect is leaving it unstated. Prevents: Two reports publishing bias numbers that look comparable, are opposite in sign, and are read as agreement.	Σ(plan − actual) ÷ Σ actual, at lag 3, the house scored vintage. positive = planned above actual.Plan vs Actual — bias, lifted from the live contract
service_definition — read by the semantic layer and the testsApplies to: Service metrics	Which construction the word service names here: cycle service level — the share of replenishment cycles that end without a stockout, an event count per cycle — or fill rate, a quantity ratio over demand, weighted by units or by lines. With the grain the count or the ratio is taken at.	The two share the name in the wild and move differently on the same operation, so an unqualified service percentage names no measurement at all. The dictionary's fill-rate entry sets the two side by side for exactly this reason. Prevents: A safety-stock parameter set against a cycle service level and then reported as the fill rate a customer experiences — two different numbers on the same operation, each quoted as though it were the other.	Line fill and unit fill are published as two separate numbers, each with its own denominator, rather than one blended fill rate.Service & Delivery Performance — Definitions & Official Numbers
exclusions	What is out of the population, and where the reader can see the count of what was removed.	An exclusion is part of the metric. Stated on the face of the number, it is a definition; stated nowhere, it is a discrepancy waiting to be found. Prevents: A number that cannot be reconciled to the source system because a filter nobody documented is standing between them.	Cancelled order lines — a line nobody was still waiting for cannot be late. The cancelled-line count is shown on the Overview so the exclusion is visible rather than silent.Service & Delivery Performance — OTIF, lifted from the live contract
conventions_rejected	The defensible alternatives that were not chosen, each with the reason — including the ones rejected because the data cannot support them.	This field is the practice's extension to the template, and it is what turns a definition into a decision anyone can audit. A contract that lists only what was chosen reads as though nothing else was possible. Prevents: The same argument being re-run every quarter, and a reviewer's first objection landing as a surprise rather than as a paragraph already written.	Re-dating a late order makes it on time. This dataset contains that behaviour deliberately, and the Definitions view shows both numbers side by side — the gap between them is the reason the original commit is the house basis.Service & Delivery Performance — OTIF, lifted from the live contract

Data & aggregation

How the metric behaves when it is rolled up, where its inputs come from, and what has to be true of them. This block is where a definition meets a pipeline: it is the part a semantic layer and a data-quality test read directly.

Each data & aggregation field of the metric contract, what it holds, why it exists and the failure it prevents, and a worked example with the dashboard it comes from
Field	What it holds	Why / failure it prevents	Worked example
aggregation_class — read by the semantic layer and the tests	Additive; semi-additive, naming the dimension it cannot be summed across; or non-additive, with the rule for recomputing it from its components. Percentiles are never recombined from other percentiles.	It is the one property of a measure that decides whether a total is right, and nothing in a warehouse or a semantic layer declares it for you. Prevents: A stock balance summed across days, an average of ratios sold as a portfolio ratio, and a mean of group percentiles presented as a percentile.	OTIF is non-additive: a ratio of two additive counts, so every scope recomputes it from summed numerator and denominator. The lead-time demo carries the harder case — a percentile is pooled from the raw durations at the displayed scope and never averaged across groups.Lead Time & Reliability — The p95 Trap
capture_pattern	Per source object: snapshot, event, or parameter. Parameters are effective-dated; forecasts and plans are captured as statement-time snapshots.	The pattern decides what history is even recoverable. A ratio needs event grain underneath it, and a plan that was never snapshotted cannot be scored at a vintage afterwards. Prevents: Discovering, a year in, that the plan table is overwritten in place — so there is no lag-3 plan to compare anything against, and never will be for the period already gone.	Event capture: each order line carries its own commit date as of order placement, held on the line rather than read from today's order header.Service & Delivery Performance
source_objects	The named source objects per system that carry the metric — each treated as a hypothesis to verify in the client's own instance, not as a fact.	A table name from a reference is a starting point. Configuration, version and customisation all move what actually holds the field. Prevents: A build plan written against a table that turns out to be empty, renamed, or not the one this business posts to.	The dictionary's OTIF entry names the source tables per ERP — the per-system sections are the hypothesis list a discovery session works through.KPI Dictionary — OTIF, source tables by ERP
tolerance_params	Which tolerance, threshold or policy rows the metric joins to — joined as of the transaction date, never to the current value.	Source systems overwrite tolerances in place. Joining to today's row silently rewrites every historical judgement the metric ever made. Prevents: A restated history in which last year's early deliveries became late because someone edited the tolerance this morning.	An on-time window of ±0 days, held as an effective-dated parameter row and joined as of the order's own date — the silver-layer discipline the layer contracts guide sets out.Medallion Layer Contracts for ERP Data
dq_tests — read by the semantic layer and the tests	The tests that have to pass for the number to be publishable: zero-denominator handling, dense-zero requirements where rows must exist to be counted, and censoring flags where a window truncates the measurement.	These are the conditions under which the arithmetic stops meaning what the definition says, and they are checkable by machine rather than by review. Prevents: A rate published over an empty denominator, a sparse table read as though the missing rows were zeroes, and a censored duration reported as though it had finished.	Stock present before the window opens has no receipt date, so its age is right-censored at ≥365 days and reported as a bound rather than a number.Inventory Health — Excess & Aging

Display & target

How the number reaches a reader, and what it is compared against. A contract that stops before display leaves the last mile — the tile, the denominator, the goal line — to whoever builds the dashboard, which is where a defended definition usually goes quiet.

Each display & target field of the metric contract, what it holds, why it exists and the failure it prevents, and a worked example with the dashboard it comes from
Field	What it holds	Why / failure it prevents	Worked example
display_default	The default encoding the metric is published in, and the small-sample rule that governs when a row is judged at all.	Two builds can share a numerator and a denominator exactly and still rank their rows differently, because the encoding and the small-sample rule are choices the arithmetic does not make. Naming them here is what stops the tile from re-deciding the metric. Prevents: A ranked league table whose top and bottom are the smallest samples rather than the best and worst performers.	A league table beside a funnel plot with binomial limits, and nothing under 25 lines judged at all — small samples are drawn hollow and never flagged.Service & Delivery Performance — Customer League Table
denominator_display	How the denominator reaches the reader — a subtitle count, a column, or the axis of the chart itself.	A ratio without its denominator cannot be ranked, weighted or trusted; the reader has no way to tell 2 of 2 from 900 of 1,000. Prevents: A perfect score from three lines sitting at the top of the same list as a strong score from three thousand.	Every published rate carries the denominator it was computed over, on the face of the tile.Service & Delivery Performance — Overview
target_and_provenance	The target, and where it came from: an internal goal, a level derived from the business's own entitlement, or a negotiated commitment — with the derivation in a sentence.	A goal line changes how every figure beside it is read, so its provenance is part of the metric rather than a decoration on the chart. Prevents: A number of unknown origin acquiring the authority of a standard simply by being drawn as a line.	95% at portfolio level · Internal goal — labelled as such on the tile, with no benchmark line drawn anywhere on the dashboard.Service & Delivery Performance — OTIF target
target_licensingApplies to: Benchmark-derived targets only	For a target derived from someone else's published figure: the licence that covers reproducing that number at the tier it appears — a deck is not a dashboard.	Reproduction rights for commercial comparison data are usually narrower than the reading rights, and embedding is the tier most often excluded. Prevents: A licensed figure travelling from a report into a dashboard nobody checked the terms for, and staying there for years.	Not applicable on any showcase demo — every target there is an internal goal, and no benchmark value is published anywhere on the site.Plan vs Actual — where a target's provenance is disclosed rather than implied
provenance_subtitle	The one plain sentence the tile carries under the number: the convention in force, the parameters behind it, and what was excluded.	A sentence works where a legend fails. It is the only part of the contract most readers will ever see, so it has to be the part that stops a misreading. Prevents: A reader taking a number at face value because everything qualifying it lived two clicks away.	order-line grain · vs original commit date · ship basisService & Delivery Performance — the line under every tile

The same fields, filled in and live

Every KPI tile on the showcase dashboards carries a Contract button, and the panel behind it is this template in short form — the same authorship, on the face of the number rather than in a repository. Five worth reading side by side, because they disagree with each other on purpose:

Plan attainment, capped — Credit capped per family before summing, against the consensus plan locked at cycle sign-off — with the uncapped figure carried beside it, target-less, never instead of it.
Plan attainment, uncapped — The same metric name, the opposite overshoot rule, and both contracts say so: one instrument scores delivery against a commitment, the other measures error, where the direction of a miss is information rather than credit.
WMAPE — Read at exactly one plan vintage, never summed across vintages, with the goal line's provenance disclosed rather than implied — the level was chosen after the data, and the contract says so.
Schedule attainment — Mix attainment capped per item-week, scored against the schedule as frozen at the planning fence, with the week-end restatement published beside it and structurally unable to read worse.
Forecast accuracy — The whole process chain measured on one identical row set, so the step-to-step deltas are valid — and the row count printed on the card, because that is what makes them valid.

Copy the template

The whole field list as plain text, with the one-line prompt from each row above and the conditional and machine-read fields marked. It is generated from the same registry the tables are, so it cannot drift from them. Paste it into a repository, fill it in with the people who will be held to the number, and the first version is the one they ratified.

Plain text — paste it into a repository as version 0.1.0. It becomes 1.0.0 the day the people who own the number ratify it.

# Metric contract — <metric name>

One document per production metric. Fill every field; where a field does
not apply, write why rather than deleting the line.

## Identity

**metric_id**: A stable house identifier for the metric, never reused for a different definition. (M · wire into the semantic layer / tests)

**display_name**: The name as a reader sees it, qualified by the conventions that make it one number rather than several.

**plain_definition**: What the number means, in a sentence someone outside the analytics team can check.

**definition_status**: One of three values: standardized, narrowed from a standard, or authored house convention.

**standard_ref**: The named public standard, its edition, and the code within it — or the literal value “authored — no definition located in the published sources the practice searched”.

**version_and_change_log**: The current version number, and a dated row per change: what moved, who moved it, and why.

**owner**: Two owners by role, never by name: the business owner who decides what the metric means, and the data owner who answers for the pipeline behind it.

## Computation

**numerator**: The exact numerator, written over additive component columns rather than over another ratio. (M · wire into the semantic layer / tests)

**denominator**: The exact denominator, stated as a population rather than as “the total”. (M · wire into the semantic layer / tests)

**grain**: The declared grain, written as “one row per … per …”, plus the roll-up rule that follows from it. (M · wire into the semantic layer / tests)

**lag_and_level**: The vintage the plan or forecast is read at, and the hierarchy level it is scored at — both as parts of the grain, never as attributes. (applies to: Accuracy and attainment metrics · M · wire into the semantic layer / tests)

**time_basis**: Cohort or completion: whether the period holds the obligations that came due in it, or the work that was finished in it. Named, never mixed.

**promise_basis**: Which date the promise is measured against: what the customer requested, what was first committed back, or what the commit currently says.

**plan_version_basis**: Which plan version sits in the denominator, named by its role — the locked commitment, the latest estimate, the released schedule. Two answers means two contracts. (applies to: Plan and schedule metrics · M · wire into the semantic layer / tests)

**overshoot_rule**: What happens above 100%: uncapped, capped per row before summing, or binary. With the reason, because the choice is not obvious. (applies to: Attainment metrics)

**sign_convention**: For any signed measure: which way round the subtraction goes, and what a positive number means in words.

**service_definition**: Which construction the word service names here: cycle service level — the share of replenishment cycles that end without a stockout, an event count per cycle — or fill rate, a quantity ratio over demand, weighted by units or by lines. With the grain the count or the ratio is taken at. (applies to: Service metrics · M · wire into the semantic layer / tests)

**exclusions**: What is out of the population, and where the reader can see the count of what was removed.

**conventions_rejected**: The defensible alternatives that were not chosen, each with the reason — including the ones rejected because the data cannot support them.

## Data & aggregation

**aggregation_class**: Additive; semi-additive, naming the dimension it cannot be summed across; or non-additive, with the rule for recomputing it from its components. Percentiles are never recombined from other percentiles. (M · wire into the semantic layer / tests)

**capture_pattern**: Per source object: snapshot, event, or parameter. Parameters are effective-dated; forecasts and plans are captured as statement-time snapshots.

**source_objects**: The named source objects per system that carry the metric — each treated as a hypothesis to verify in the client's own instance, not as a fact.

**tolerance_params**: Which tolerance, threshold or policy rows the metric joins to — joined as of the transaction date, never to the current value.

**dq_tests**: The tests that have to pass for the number to be publishable: zero-denominator handling, dense-zero requirements where rows must exist to be counted, and censoring flags where a window truncates the measurement. (M · wire into the semantic layer / tests)

## Display & target

**display_default**: The default encoding the metric is published in, and the small-sample rule that governs when a row is judged at all.

**denominator_display**: How the denominator reaches the reader — a subtitle count, a column, or the axis of the chart itself.

**target_and_provenance**: The target, and where it came from: an internal goal, a level derived from the business's own entitlement, or a negotiated commitment — with the derivation in a sentence.

**target_licensing**: For a target derived from someone else's published figure: the licence that covers reproducing that number at the tier it appears — a deck is not a dashboard. (applies to: Benchmark-derived targets only)

**provenance_subtitle**: The one plain sentence the tile carries under the number: the convention in force, the parameters behind it, and what was excluded.

## Change log

| Date | Author | Field | Old → new | Reason |
|---|---|---|---|---|
| | | | | |

Restatement decision for this version: restate history / freeze the series (choose one, and say which).

Two pre-drafted contracts

Two drafts, both for metrics with no definition located in the published sources the practice searched. Each arrives with the settled fields filled and the contested ones opened as a decision with its options named and a house default stated — so a working session chooses between written positions rather than inventing from a blank page. Neither is a definition until the people who own the number have agreed it; that agreement is what converts an authored house convention from a proposal into a contract.

Schedule adherence

Draft — decisions open

The execution twin of plan attainment. Attainment scores delivery against the commitment the business signed; adherence scores it against the schedule the plant was last released to run. Collapsing the two into one number is what makes attainment arguments unresolvable — one side is arguing about accountability and the other about execution, using the same figure. The formula core is shared with attainment; the plan version in the denominator is what separates them, which is why the draft splits them into two contracts rather than one metric with a toggle.

Filled fields

display_name: Schedule adherence — item × week, capped per row, vs the latest released schedule
definition_status: authored house convention — proposed here, ratified in the working session
standard_ref: authored — no definition located in the published sources the practice searched
numerator: Σ min(completed quantity, released schedule quantity) per item and week, summed after capping.
denominator: Σ released schedule quantity over the same item-weeks in the window.
grain: One row per item per plant per week. Work line travels as an item attribute, not as an axis of the measure.
plan_version_basis: The latest released schedule — the version the plant was actually told to run. Plan attainment's contract takes the locked commitment instead; the two are separate metrics with separate owners.
overshoot_rule: Capped per row before summing, as the house default: an overbuild on one item cannot pay for a shortfall on another. Shortfall and overbuild are carried beside it as separate additive measures that never net.
aggregation_class: Non-additive — a ratio of two additive quantities, recomputed from summed numerator and denominator at every scope. The mean of weekly percentages is a named wrong answer, not a roll-up.
denominator_display: Scheduled quantity is shown beside every adherence figure, so a small week cannot look like a good one.
target_and_provenance: To be set in the session as an internal goal. No benchmark value is available and none should be implied.

Open decisions

Which schedule version is the denominatorOptions: Latest released schedule · the schedule as frozen at the planning fence · the schedule as it stood at week endHouse default: Latest released schedule for adherence; the frozen-at-fence version belongs to the attainment contract, published beside it. Adherence asks whether the floor ran what the floor was told to run, so its denominator has to be the instruction the floor actually held: the schedule as last released before execution began, which is the frozen commitment plus any change the planners published and the plant acknowledged. That is not the week-end restatement — a schedule re-cut after the fact moves toward what was built and converges on 100% by construction, which is why the live production-schedule contract rejects it as a basis and publishes it only beside the frozen figure. Nor is it the frozen-at-fence version, which is the right denominator for a different question: attainment scores delivery against the commitment the business signed, and accountability belongs to the version that was signed. Two questions with two owners, so two contracts rather than one metric with a toggle — a toggle lets either answer be reported as the other, and a released schedule that keeps moving would quietly turn the accountability number into the execution one.
Overshoot treatmentOptions: Uncapped · capped per row before summing · binary hit/missHouse default: Capped per row before summing. It is the only position that argues for itself rather than asserting a formula: nobody asked for the surplus, and the shortfall is still a shortfall.
Which axis adherence is measured onOptions: Mix — did we build the right things · timing — did we build them in the right week · a composite of bothHouse default: Mix, with timing kept as its own separate metric if it is wanted. A multiplicative composite moves without anyone being able to say which part moved it, so it cannot be acted on. Keep the parts separate and publish them separately.
Naming, for a regulated audienceOptions: Adherence · attainment · conformanceHouse default: Adherence, and never conformance. Conformance vocabulary carries a quality-system meaning in a regulated plant, and a metric name that collides with it will be read as a compliance claim.

Time-phased plan grid

Draft — decisions open

The supply, demand and inventory grid a site reviews week by week: what we expect to make, what we expect to sell, and what we expect to be holding at the end of each bucket. It is a structure rather than a single metric, and the reason it needs a contract is that its rows do not share aggregation rules — treating the whole grid as one measure is the defect it exists to prevent.

Filled fields

display_name: Time-phased plan grid — site, weekly buckets
definition_status: authored house convention — proposed here, ratified in the working session
standard_ref: authored — no definition located in the published sources the practice searched
grain: One row per item per site per bucket, per row type. Bucket boundaries are declared, not inferred from whatever the source system happened to store.
plan_version_basis: Future buckets are drawn from one named plan version; past buckets are actuals. The seam between them is drawn on the visual, not left for the reader to infer from where the line stops being smooth.
aggregation_class: Split by row type, and this is the whole point of the contract. Supply and demand rows are fully additive flows. The inventory row is semi-additive — a closing balance, summed across items and sites but never across buckets. The two families are modelled separately and never share a roll-up rule.
capture_pattern: Plan rows are statement-time snapshots, so a bucket can be re-read at the vintage it was stated at. Policy bands are effective-dated parameters, not observations.
tolerance_params: The projected-inventory band edges are policy rows — safety stock and the reorder point — joined as of the bucket's own date. A threshold is drawn against the quantity it is a threshold on: safety stock against on-hand, the reorder point against inventory position.
display_default: A grid with the buckets across and the row types down, and a projection chart beneath it drawn with period-end semantics — a step line, never a smoothed one.
provenance_subtitle: The bucket grain, the plan version feeding the future side, and the date of the seam, on the face of the grid.

Open decisions

Bucket grainOptions: Weekly · monthly · weekly near-in and monthly beyond the fenceHouse default: Weekly, if the review cadence is weekly. The bucket should match the meeting that consumes it. A mixed grain is defensible but has to be declared, because a chart with two bucket widths reads as one series and is not.
Which plan version feeds the future sideOptions: The locked consensus plan · the latest estimate · the released supply planHouse default: The locked consensus plan, with the latest estimate available as a second, labelled line. The grid is a review instrument. Reviewing against a plan that is edited continuously measures how recently it was edited.
Demand basis for any days-of-supply conversionOptions: Trailing actual demand · forward plan demand · a blendHouse default: State it explicitly, whichever is chosen, and show it beside the converted figure. The conversion turns an additive quantity into a non-additive ratio, so the converted row can no longer be summed across anything. That is worth saying out loud on the grid rather than discovering in a roll-up.
Whether the grid carries value as well as quantityOptions: Quantity only · quantity and value · value onlyHouse default: Both, each computed from its own pair of sums. Where items span orders of magnitude in unit price, a mix shift moves the value view and the quantity view in different directions. Scaling a quantity by an average price erases exactly that effect.

Versioning and change control

A contract that can be edited without a trace is a slide deck with extra steps. Five rules, each one existing because the convenient alternative makes a past figure indefensible.

Anything that moves a number is a major version. Change the numerator, the denominator, the grain, the vintage, the plan version, the exclusions or any field the semantic layer reads, and the definition is no longer the one that produced last quarter's figure. That is a major bump, not a correction. The numbering: a contract is 0.1.0 while it is still a draft nobody has ratified, 1.0.0 the day the working session ratifies it, then major for a change that moves a number or alters a machine-consumed field, minor for a target moving — a version event in its own right, because a figure is read against its goal and the pair is what a reader actually saw — and patch for wording.
Wording-only changes are logged patches. Rewriting a plain definition for clarity, tightening a rejected-convention paragraph, correcting a typo: none of these move a number, and all of them still get a row. The log is what lets a reviewer tell a clarification from a change, which is the distinction the whole register exists to preserve.
A change-log row carries five columns. Date, author, the field that changed, its old value alongside its new one, and the reason — the five columns of the change-log table in the copyable form above. The old value is the column most often dropped and the one most often needed: without it the log records that something changed and not what it changed from.
The restatement decision travels with the bump. When a definition changes, history is either restated under the new definition or frozen under the old one with the series broken at the change date. Both are defensible; neither is a default. The contract records which was chosen, so a trend line spanning the change can be read correctly instead of being read as performance.
Versions are never deleted, and every published figure names its version. A retired definition stays in the register with its dates, because the figures it produced are still in circulation — in board packs, in commitments, in other people's spreadsheets. A number that cannot be traced to the version of the definition that produced it cannot be defended, and definition and target are snapshotted together for exactly that reason.

The copyable template above ends with the change-log table and the restatement line, so a contract cannot be started without a place to record the first change.

The metric contract template

Why a contract

The twenty-nine fields

Identity

Computation

Data & aggregation

Display & target

The same fields, filled in and live

Copy the template

Two pre-drafted contracts

Versioning and change control

Where this connects