mnmx

Goal definitions

A goal states what you want the software to do or keep doing as it changes. For example, when a router adds support for user links that include an ID, links without an ID should still work.

You can give the builder concrete examples as acceptance entries. Here, one entry covers /users and another covers /users/42. The harness tests each case independently. An optional hold tells the engine what evidence to require before a change lands. In this example, both cases must pass.

Browse all 17 fields
Identity
Evidence
Judgment
Relationships
Lifecycle
[{
  "id": "routes.optional",
  "statement": "The router accepts a user URL with or without an ID.",
  "owner": "team:routing",
  "nextReview": {"on": "routing release"},
  "acceptance": {
    "without-id": "The route /users/:id? matches /users.",
    "with-id": "The route /users/:id? matches /users/42."
  },
  "measure": {"demonstrated": true},
  "hold": {"max": 0}
}]

Matching an optional user ID

Adding /users/42 must keep the old link, /users, working. The hold requires a passing test for each URL.

Runner’s report

fail

The runner supplied no passing result for /users/42.

{"demonstrated":["without-id"]}
Entries missing
1
Maximum allowed
0

pass

{"demonstrated":["without-id","with-id"]}
Entries missing
0
Maximum allowed
0

unknown

The missing report blocks submission because the engine cannot verify either test.

Entries missing
Unknown
Maximum allowed
0

Goal files

An active goal needs an id, a statement, an owner, and a nextReview trigger.

TypeScript
import { goal } from "@mnmx/engine";

export default goal({
  id: "routes.optional",
  statement: "The router accepts a user URL with or without an ID.",
  owner: "team:routing",
  nextReview: { on: "routing release" }
});
Harness bundle

The bundle directory contains a README.md and a goals.json array with at least one goal. In the case registry, link each test ID to its acceptance entry.

{
  "id": "matches-short-link",
  "goalId": "routes.optional",
  "entryId": "without-id"
}

If three visible cases cite without-id, all three must pass for the visible checks to demonstrate that entry. The harness applies the same rule separately to the held-out cases.

Identity

id

Required · string

Other goals and tests refer to this ID. Keep it when you revise the wording so Git records stay under the same name.

Syntax
Use a unique Git ref component such as routes.optional. Slashes and consecutive dots are invalid.

statement

Required · string

State the behavior in a sentence or two. “The router accepts a user URL with or without an ID” leaves the team free to replace the router.

owner

Required · actor ID

Name whoever can decide whether to keep supporting the shorter URL. Valid owners include a person (op:ana), a team (team:routing), or a role (role:release).

Evidence

acceptance

Optional · entry ID → text

Give two behaviors separate entries if one could pass while the other fails. A router can match /users/42 and still reject /users.

Entry ID
Use lowercase letters and digits, with hyphens between words. Tests refer to an entry by goal ID and entry ID, as in routes.optional#without-id. Keep the key when editing its description.
Entry text
Give each entry a distinct, nonempty description of the input and expected result.
Evidence
The engine allows an empty acceptance map. To require a passing test for every entry, use measure: { demonstrated: true } and hold: { max: 0 }. In a harness bundle, each non-guidance goal needs entries. The visible checks and any configured held-out checks must each cover every entry.

measure

Optional · one per goal

A custom quantity’s value function receives the contents of the runner’s signed report for the proposed change.

measure: {
  from: "artifact:routes.failures", version: 1, unit: "failures",
  value: (report: { failures: number }) => report.failures
},
hold: { max: 0 }
demonstrated
Counts missing entries for a goal with at least one acceptance entry. The runner lists the IDs it demonstrated in artifact:acceptance.<goal-id>, for example { demonstrated: ["without-id"] }. An empty list counts every entry as missing. Without a report the count is unknown.
from
The engine looks up the report by this exact input name and the candidate under review.
version
Increment this number when a calculation changes meaning. For example, give counts of failed suites a new version to keep them separate from earlier counts of failed cases.
unit · value
For a quantity, value(input) returns a number in the declared unit. The same input must give the same result. Bounds and targets use that unit too.
noise
Optional estimate of how much the quantity varies across runs on the same change. The engine uses this until it has repeat measurements. A noisy result still has to meet the exact hold.
check
Given the report and hold.choice, return a boolean or an object with pass and an optional reason. A route-prefix check could return { pass: false, reason: "/admin is outside the allowed prefixes" }.
by
One verified signature from a listed signer satisfies the approval. For approval(["op:ana"], "approval:release"), Ana must sign the approval:release input for this candidate.
kind
If you omit kind, the engine infers quantity from value, check from a check function, and approval from by. Callbacks require executable code. The demonstrated measure works in JSON.

hold

Optional · requires a measure

A failed or unknown hold on this goal or an adopted policy blocks an ordinary submission. An authorized override creates a repair goal. Holds protected by organizational context still apply.

min · max
Supply a finite lower bound, upper bound, or both. The endpoints count as passing. The engine rejects a range whose minimum exceeds its maximum.
choice
The engine passes this value as the check function’s second argument. For a route-prefix check it could be ["/users", "/teams"].
true
Use hold: true on an approval measure to require a signature from one of its listed signers.
open
A goal that adopts a policy can tighten its threshold. The policy owner can also allow a looser threshold or a different choice by setting open: true on the bound.

target

Optional · finite number

A target tracks progress on a quantity without blocking submission. At 93% coverage, the change passes a 90% minimum and falls five percentage points short of a 98% target. A demonstrated count can have a target of zero missing entries.

Judgment

judge

Optional · requires criteria

Use a judge for questions such as whether an error message explains how to fix the route. The harness runs the reviewer and the engine records its score. A hold cannot use evidence from judge: or judgment:.

judge: agent({
  id: "route-reviewer", model: "review-model",
  prompt: "./judges/reviewer.md"
}),
criteria: {
  prompt: "./rubrics/route-errors.md",
  scale: { 1: "Cause unclear", 3: "Cause named", 5: "Cause and fix explained" }
}
id · kind
agent(...) sets kind to "agent". Give the reviewer a stable ID without @ or the reserved op: prefix. The engine uses id@revision to distinguish scores from different versions of the reviewer.
model · prompt
Name the model and the shared review instructions. Put requirements specific to this goal in criteria.

criteria

Required with judge · rubric and scale

For the route-error rubric, ask the reviewer to quote the suggested fix. A message that names the cause but gives the caller no next step earns a 3.

prompt
Path to the rubric the harness gives the judge for this goal.
scale
Give each allowed score a nonempty label. List at least one score. Every score must be finite, and the engine rejects scores between the listed values.

Relationships

Reference goals by their existing IDs. Within each of serves, governedBy, and dependsOn, list each ID once. The graph rejects cycles within any one relationship type.

serves

Optional · goal ID array · default []

A failing check on routes.optional can appear in feedback for the goal it serves, links.stable. To inherit the parent’s holds, add it to governedBy.

serves: ["links.stable"]

governedBy

Optional · goal ID array · default []

List the policies whose holds this goal must pass. Adopting build.tests also brings in any holds the test policy inherits. The engine reports a conflict if two bounds on the same measure cannot both hold.

governedBy: ["build.tests"]

dependsOn

Optional · goal ID array · default []

A new claim or landing requires every listed goal to have state "finished". A migration marked "stopped" still blocks work, even if its tests pass.

dependsOn: ["route-table-migration"]

context

Optional · organizational context

A release team can give routing the authority to reorder its priorities while requiring every routing change to preserve existing links.

context: {
  parent: "release",
  groups: [{ id: "routing", priorities: [
    { goal: "links.stable", scope: "routes.optional" }
  ] }]
}
parent
The goal whose context this one inherits.
obligations
Policy goal IDs. Their holds apply here and to child contexts, even if a child changes its priorities.
groups
Each group has a local id and a nonempty list of priorities. A priority’s goal names the objective. Its scope must be the defining goal’s ID when you create the group.
grants
To authorize a direct child to adjust a group, supply a grant id, the group: { goal, id }, the child and its owner in to: { goal, owner }, and a reason in because. Set redelegate: true to let the recipient pass that permission to a child of its own.
adjustments
A child names the inherited group and cites its grant in using: { goal, id }. It lists the new priorities and gives a reason in because. Each replacement must support an inherited objective and stay within the permitted scope.

Lifecycle

workspace

Required for a submission target · string

With GitStore, workspace: "main" lands changes on refs/heads/main. Goals checked or submitted together must share a workspace. A policy used only through governedBy can omit it.

workspace: "main"

state

Optional · default "active"

The owner marks a goal finished explicitly, even after its checks pass.

active
Accepts new claims once its prerequisites are finished.
waiting · blocked
Use waiting for an expected event and blocked for a problem someone needs to resolve. Both need a next review and neither accepts new claims.
finished · stopped
Both close the goal to new submissions and make the next review optional. Only finished satisfies another goal’s dependency.

nextReview

Required for active, waiting, and blocked goals

For several goals on one review schedule, set nextReview with goal.with(...). This helper also accepts owner and state. Values on an individual goal override the defaults.

at
A timestamp, such as { at: "2027-01-15T09:00:00Z" }. The engine reports the review due when that time arrives.
on
An event, such as { on: "routing release" }. The harness recognizes the event and decides when to review.
evidence
A report or other input, such as { evidence: "route compatibility report" }. The engine lists the goal as waiting for that evidence.

repairs

Engine-generated · override request ID

On a repair goal, repairs identifies the override request, serves names the bypassed holds, and nextReview gives the override’s expiration time. The engine sets all three when the override lands.