id
Required · stringOther 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.
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.
[{
"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}
}]Adding /users/42 must keep the old link, /users, working. The hold requires a passing test for each URL.
An active goal needs an id, a statement, an owner, and a nextReview trigger.
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" }
});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.
idOther goals and tests refer to this ID. Keep it when you revise the wording so Git records stay under the same name.
routes.optional. Slashes and consecutive dots are invalid.statementState 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.
ownerName 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).
acceptanceGive two behaviors separate entries if one could pass while the other fails. A router can match /users/42 and still reject /users.
routes.optional#without-id. Keep the key when editing its description.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.measureA 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 }
artifact:acceptance.<goal-id>, for example { demonstrated: ["without-id"] }. An empty list counts every entry as missing. Without a report the count is unknown.value(input) returns a number in the declared unit. The same input must give the same result. Bounds and targets use that unit too.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" }.approval(["op:ana"], "approval:release"), Ana must sign the approval:release input for this candidate.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.holdA 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.
["/users", "/teams"].hold: true on an approval measure to require a signature from one of its listed signers.open: true on the bound.targetA 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.
judgeUse 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" }
}
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.criteria.criteriaFor 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.
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.
servesA 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"]
governedByList 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"]
dependsOnA 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"]
contextA 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" }
] }]
}
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.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.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.workspaceWith 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"
stateThe owner marks a goal finished explicitly, even after its checks pass.
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 satisfies another goal’s dependency.nextReviewFor 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: "2027-01-15T09:00:00Z" }. The engine reports the review due when that time arrives.{ on: "routing release" }. The harness recognizes the event and decides when to review.{ evidence: "route compatibility report" }. The engine lists the goal as waiting for that evidence.repairsOn 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.