← Guides

Set a goal contract

You'll end up with a goal stated as a contract — accomplish these things, subject to these policies — that ponens resolves against the trace's own evidence into three deterministic verdicts: met, governed, and certified. The full model is in the Goal Contract reference.

1. Declare the goal

Start with the intent (what's changing and why) and the scope (the files/symbols it touches):

ponens trace goal set trace.json \
  --intent "Settlement must never create or destroy money" \
  --scope "settle,refund,fee_tier"

2. State the acceptance criteria — "accomplish these things"

A criterion names the component it's about and the artifact that serves as its evidence — a VerificationResult, a Decomp, a Tests suite, even a plain Diff. That's all it says; whether that artifact is good enough is the policies' job (step 3). Author the whole contract as JSON and load it in one shot:

{
  "id": "session-goal",
  "intent": "Settlement must never create or destroy money",
  "scope": ["settle", "refund", "fee_tier"],
  "acceptance": [
    { "id": "c1", "component": { "function": "settle" },
      "evidence": { "artifact": "VerificationResult" } },
    { "id": "c2", "component": { "function": "fee_tier" },
      "evidence": { "artifact": "Decomp" } },
    { "id": "c3", "component": { "function": "refund" },
      "evidence": { "artifact": "Tests" } }
  ]
}

ponens trace goal set trace.json --json contract.json

Criteria resolve by lineage, not by matching description text: c1 is met once a VerificationResult whose derived_from chain roots in settle exists in the trace. Note what met does not check — a refuted result still counts as met (the artifact exists); whether it had to be proved is a policy on the governed axis. Met = the evidence exists; governed = it's good enough.

3. Attach the policies — "subject to these"

Criteria say what to accomplish; policies set the rigor bar — the governed axis. Scope them to the goal so the bar travels with it. Policies block by default: an error-severity failure fails the goal unless it's explicitly disabled (recorded, never silent) or a failure is waived.

{
  "id": "session-goal",
  "…": "…intent, scope, acceptance as above…",
  "policies": {
    "packs": ["apply_formal_methods"],
    "policies": ["research_before_edit"],
    "disabled": []
  }
}

Who picks the bar. The agent may propose packs and policies, but a human selects and approves them — the party that meets a goal must not be the sole party that sets its rigor bar. Browse the options in the policy gallery; the mechanics of gating are in Govern a repo with policies.

4. Read back the three verdicts

Resolve the criteria against the trace, then enrich to get all three axes at once:

ponens trace goal ls trace.json      # met + faithfulness, per goal
ponens trace resolve trace.json      # each criterion: ✓ done / ◐ doing / ✗ blocked / ○ todo
ponens trace enrich trace.json       # met ∧ governed ∧ certified, with resolved evidence + cone

A goal is met when its criteria resolve from evidence, governed when its policies hold, and certified when a non-doer confirms the criteria were the right ones — three independent checks, never conflated.

5. Certify — the reviewer's sign-off

Met and governed are things the doer can produce. Certified is not: it records that a non-doer agreed the definition of done was the right one.

ponens trace goal certify trace.json --by reviewer --verdict approved

That's the whole contract. Next, put it to work: review an AI-generated PR → (where you own the certified axis), or gate it on every PR → (where governed becomes a required check).