The scope contract: defining "done"

Why the exit condition is the load-bearing part

A loop is a control structure: while (!done) { learn; analyze; execute; verify; }. The done predicate is evaluated every cycle. If that predicate is not decidable from observable state, the loop has no termination guarantee — it is, formally, a program with no defined halting condition. "Better", "cleaner", "production-ready" are not predicates over state; they are subjective judgments, so the loop can never evaluate them and can never legitimately exit.

SCOPE.md vs. GOAL.md vs. a PRD

SCOPE.md is the lightweight, human-written contract you start any non-trivial loop with — six fields, often under a page. It is the input to the loop, the yardstick the decide step measures against. It is not the same as GOAL.md: GOAL.md is the compiled, autonomous-run contract that the Forge /goal step emits (XML-blocked: goal / context / constraints / verification / done-when) for a long unattended run — you'll meet it in lessons 8 and 10. And a PRD is broader still: market, persona, rollout. Think of it as a zoom scale: PRD (the why & what, many pages) → SCOPE.md (the contract for one loop, one page) → GOAL.md (the machine-checkable run contract the loop executes against).

What "measurable" means precisely

A done-when clause is measurable when it names (1) a metric or observable artifact, (2) a comparison or threshold, and (3) the boundary where it is checked. "Tests pass" is weak (which tests? where?); "npm test exits 0 with 0 failures in CI" is strong. The verify step (lesson 6) runs that check at the real boundary — never a claim, never a mock — and the decide step compares the result to this contract.

The whole contract in one file

# Goal
Cut RHG checkout p95 latency so it stops timing out at peak.

# Context
Checkout lives in services/checkout. Hot path is the cart re-price
call on every keystroke. Prod is us-east, behind a CDN.

# Constraints
- Do NOT change the public /checkout request/response shape.
- No new runtime dependencies.
- Stay on the existing design tokens (no raw hex).

# Done-when
- checkout p95 < 400ms over a 10-minute load test at peak RPS
- 0 responses with status >= 500 during that test
- `npm test` exits 0 with 0 failures in CI
- the /checkout API contract test still passes unchanged

# Editable surface
- services/checkout/**
- services/checkout/__tests__/**

# Agents
- Executor:  agent-A   (tier: execute)
- Validator: agent-B   (tier: analyze)   # never the builder

How to find / open this

It is just a Markdown file you author by hand before the run. Create or open it from the repo root:

# create it next to the work, then open in your editor
$ touch SCOPE.md && $EDITOR SCOPE.md

# confirm a loop run is pointed at it
$ grep -n "Done-when" SCOPE.md

In the Forge front-end (lesson 8) this same six-field thinking is what the /goal step compiles into the autonomous GOAL.md; for a quick interactive loop you often hand-write SCOPE.md and skip straight to running.

How the verdict is computed

The grader is a tiny pure function over the text. It scans for three signals: a metric (a known measurable noun or a number-with-unit), a threshold (a comparison word/operator or a target), and a boundary (a "where" phrase — in CI, in prod, over a test). A clause is measurable only when all three are present (plus the no-feeling-words check in strict mode). Anything less is vague, and the readout spells out the missing piece — exactly what the loop's decide step would be unable to evaluate.

function grade(text, strict) {
  const t = text.toLowerCase();
  const hasMetric    = /\b(p9\d|latency|error rate|uptime|conversion|\d+\s?(ms|s|%))\b/.test(t);
  const hasThreshold = /(under|below|over|above|<|>|>=|<=|at least|exits 0|\d)/.test(t);
  const hasBoundary  = /(in ci|in prod|production|staging|load test|over a)/.test(t);
  const feelings    = /\b(better|faster|fast|good|nice|clean|improv)/.test(t);
  const ok = hasMetric && hasThreshold && hasBoundary && (!strict || !feelings);
  return { ok, hasMetric, hasThreshold, hasBoundary, feelings };
}

The point is not the regex — it's the shape: metric + threshold + boundary is the minimum a verify step can act on. Real loops let an LLM judge this in plain language, but the test is identical: could a machine, looking only at observable state, return true or false?

A constraint is just a done-when that must stay true

Notice every good constraint has the same shape as a good done-when: a metric/observable, a threshold (often "unchanged" or "zero"), and a boundary. "No raw hex in the diff" is metric (count of hex literals) + threshold (= 0) + boundary (the diff). That is why the same grader logic works for both — a constraint is an invariant the loop must hold at every step, while a done-when is the condition that lets it stop. Pinning to a named, fixed artifact (the token set, the contract test, the lockfile) is what makes the check mechanical instead of subjective.

Tiers are a dependency chain, recorded in the contract

Each tier is a boolean the contract grants. A second map records what each tier requires below it; a granted tier whose prerequisite is missing is unsatisfied — it can't take effect, so the editor flags it, exactly as a real runner would refuse to act on an inconsistent grant. The effective authorization the summary reads is the longest satisfied prefix of the chain.

const grant = { analyze:false, execute:false, destructive:false };

const requires = {
  analyze:     [],                 // base tier
  execute:     ['analyze'],        // can't change what you can't read
  destructive: ['execute']         // irreversible needs reversible first
};

function missing(tier) { return requires[tier].filter(t => !grant[t]); }
function effective() {        // what the agent may actually do
  return Object.keys(grant).filter(t => grant[t] && missing(t).length === 0);
}

Why AFK loops stop at execute

An autonomous run (lesson 7, 9) is normally granted analyze + execute and not destructive. The loop can build and prove a change all day; the one irreversible step — ship it to prod — is the genuine user-only fork that triggers a handoff. That is also why the Validator is granted only analyze: it proves, it never changes. computer-use is AX-only and non-blocking, so it never even reaches the execute tier on the real system.

Observability, not operation

Everything in this diagram runs AFK. The human's only role is observability — reading LOOP-LOG.md / status / review.md as the machine works. The human executes nothing, not even the QA. The single exception is the dashed destructive branch: when the only remaining step is irreversible and genuinely user-only, the loop emits a decision-ready handoff and blocks there — never anywhere else. A well-written SCOPE.md is what makes this safe: the constraints keep cycles in-bounds without supervision, and the measurable done-when lets the loop terminate itself instead of waiting to be told.

The banner is an AND over the clauses

One array of clause objects drives both the table and the banner. Each tick re-reads each metric at its boundary and recomputes the clause's status. The overall gate is a logical AND: the run is done only when every clause passes — any fail keeps the banner red and the loop running. This is the decide step made visible. Notice the human does nothing here but read; the loop re-checks itself and converges.

Why "pending" exists

A clause can be pending — its check hasn't completed this cycle (e.g. the 10-minute load test is still running). Pending is not pass; the gate treats only an affirmative pass as satisfied, so a half-finished check can never trip an early exit.

Locate the contract and the log

# the contract you hand-write before a loop
$ $EDITOR SCOPE.md

# the observability artifacts the human reads (never executes)
$ tail -f LOOP-LOG.md          # the loop's running record
$ less review.md               # the AFK QA's observability report

# confirm the gate is wired to your done-when
$ grep -n "Done-when" SCOPE.md

Where this goes next: lesson 3 (LEARN) is how the agent confirms the Context against reality; lesson 6 (VERIFY) is the real-boundary proof gate that evaluates Done-when; lesson 8 (the Forge) shows the /goal step compiling this same thinking into an autonomous GOAL.md; lesson 9 explains why the Validator is never the builder.