On this page
Learning objectives
- Translate a request into behavior another person can judge without the author present
- Separate product outcomes from implementation choices and hidden solution hints
- Define permissions, non-goals, stop conditions, and escalation before execution
- Attach each success criterion to a deterministic or end-to-end evidence source
Before you start
- • Module 00 baseline receipt and the exact request-changes feature text
- • Ability to read a test description and explain which visible behavior it proves
Working definition
Executable task contracts
An executable task contract is the versioned boundary between intent and implementation. It states the user-visible outcome, allowed scope, forbidden effects, acceptance cases, evidence, and stop or escalation conditions before the coding agent starts. It remains implementation-light so an agent can choose a sound path while a reviewer can still decide, with evidence, if the result is complete.
A short request leaves gaps that a coding agent fills with plausible assumptions. Those assumptions can produce polished code for the wrong workflow. A detailed implementation recipe creates a different risk: the recipe can encode an untested design and prevent the agent from using simpler repository-native patterns.
The contract holds the middle. It fixes consequences and proof while leaving local implementation open. Review happens when changing intent is cheap. The maker, checker, browser test, and final handoff all point to the same contract, which prevents the definition of done from moving after results appear.
Field situation
Contract review before the second run
The request, actor roles, and failure cases are synthetic Release Desk fixtures created for this course.
- Owner
- A product-minded engineer who owns the feature outcome and a reviewer who owns the acceptance gate.
- Decision
- Which behavior is fixed by product intent, and which implementation detail should remain open to the agent?
- Starting state
- The original issue says add request changes. It does not define required reason length, stale review behavior, duplicate audit events, refresh persistence, or who may trigger the transition.
- Expected outcome
- A reviewed contract that can drive maker work, deterministic tests, browser acceptance, and final sign-off without reinterpretation.
Constraints
- • The contract may name stable repository interfaces but may not prescribe a hidden reference solution
- • Every criterion needs a truth value and an evidence source before the next coding run
- • External writes and real user records remain prohibited throughout the course
Worked example
Replacing make it work with six observable cases
Evidence status: Named synthetic scenarioA first draft required request changes to work correctly and update the audit log. Two reviewers interpreted that sentence differently. One accepted an in-memory state change, while the other expected database persistence and one audit event after refresh. Neither draft covered a stale tab or a reviewer without permission.
The team rewrote the contract around six cases: authorized success, empty reason, stale version, unauthorized actor, retry after unknown outcome, and browser refresh. Each case named starting data, action, expected state, prohibited effect, and evidence. The contract required one audit record but did not prescribe the storage function.
Before coding resumed, the checker found that the public test fixture lacked a stale-version case. Adding it changed the test plan at low cost. The later implementation could use existing repository patterns while remaining accountable to the same visible outcomes.
Limits
A precise contract can still encode the wrong product decision. Named ownership and pre-execution review remain necessary when consequences or user expectations are unsettled.
Method
Build it, with checkpoints
Field situation
Which behavior is fixed by product intent, and which implementation detail should remain open to the agent?
- 01Extract the consequence
- 02Draw scope and authority
- 03Author positive and negative cases
Acceptance checks
The task contract should be shorter than a design document but stronger than an issue description. Its cases become direct inputs to later fixtures, evals, and handoff records.
- 01
Extract the consequence
Write the actor, object, starting state, action, and durable result in plain language. Use the baseline to list assumptions that changed behavior. Keep framework and function choices outside the goal unless an existing public contract requires them.
CHECKPOINT · A reviewer can explain what changes for the Release Desk user without describing the implementation.
- 02
Draw scope and authority
List allowed files or domains, protected surfaces, roles, data classes, network rules, and external-write policy. Add non-goals for adjacent cleanup that the baseline agent attempted but the feature does not need.
CHECKPOINT · Every permitted consequence has an owner, and unrelated formatting or refactoring is explicitly out of scope.
- 03
Author positive and negative cases
Create cases for authorized success, validation, stale state, denied role, unknown retry outcome, and refresh persistence. For each, name a fixture, expected terminal state, prohibited side effect, and the evidence that will settle the result.
CHECKPOINT · Each row can resolve to pass or fail without asking the contract author what they meant.
- 04
Run an ambiguity review
Ask a reviewer to mark soft words, hidden solution hints, missing limits, and evidence that proves only part of a criterion. Revise the contract before any candidate implementation is visible, then lock its version for the next run.
CHECKPOINT · The locked contract has no make it work, appropriate, robust, or similar ungraded completion language.
Operating context
Beyond the demo
Write from observable consequence
Begin with who acts, which object changes, and what a user sees afterward. For request changes, the important consequences are a required reviewer reason, a transition back to in-progress, one durable audit event, and the same state after refresh. A function name, state library, or database method is not part of the product contract unless the repository already exposes it as a required public boundary.
Add negative cases early. Empty reasons, stale review versions, unauthorized actors, repeat submissions, and a failed persistence step reveal more about the contract than five restatements of the happy path. Each prohibited effect should be explicit so the verifier can fail closed.
Freeze evidence before candidates exist
Name the command, fixture, browser path, and receipt field that will prove each criterion. If the evidence method is selected after the agent produces a result, the team can unconsciously choose the easiest test for that implementation and ignore the behavior that remains broken.
Human judgment still has a place. Product language, acceptable interaction tradeoffs, and scope questions may need a named reviewer. The contract should identify those checkpoints and stop. It should not let the coding agent invent a product decision, nor force a human to approve mechanical facts that a test can settle.
Hands-on lab
Convert the baseline issue into an executable contract
Use the baseline receipt to identify every assumption the agent made. Rewrite the request as a compact contract, then have a second person or separate review pass try to find criteria that cannot be judged from the named evidence.
Prepare
- • Open the baseline failure list and the existing domain state definitions without opening the reference solution
- • Choose one named product owner for consequence and one verifier for acceptance evidence
Deliverable
A reviewed `TASK_CONTRACT.md`, acceptance-case table, evidence map, decision owner, and a contract-lint receipt with no soft completion language.
Starter kit: Task contract shell
Markdown# Task contract: request changes
## Goal
## Actor and object
## Starting state
## In scope
## Non-goals
## Permissions
## Acceptance cases
| id | starting fixture | action | expected outcome | prohibited effect | evidence |
|---|---|---|---|---|---|
## Stop and escalate
## Evidence receipt
## Owners and approvalDownloadable artifacts
Task contract
TASK_CONTRACT.md · Markdown
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-01-receipt.json · JSON
A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.
Acceptance command
npm run harness:contract -- --file TASK_CONTRACT.mdExpected receipt
PASS he-01 executable-contract
cases>=6 softCriteria=0 evidenceCoverage=100%
reviewedBeforeExecution=trueExpected result
The task contract should be shorter than a design document but stronger than an issue description. Its cases become direct inputs to later fixtures, evals, and handoff records.
Carry forward
Commit the contract before the next run. Repository guidance, session state, mechanical rules, and verifier outputs will all reference its case IDs.
Acceptance checks
- 01Goal, actor, object, consequence, in-scope work, and non-goals are explicit
- 02Permissions, protected data, stop conditions, escalation, and human decisions are named
- 03At least six cases cover success, invalid input, stale state, denial, retry uncertainty, and browser persistence
- 04Every case has a fixture, truth-valued outcome, prohibited effect, and evidence source
What breaks
Failure clinic
F1The contract is long, but reviewers still disagree on completion.
- Inspect
- Highlight adjectives and criteria without a fixture, terminal state, or evidence field.
- Likely cause
- More prose was added without giving claims a truth value.
- Repair
- Replace each soft criterion with observable behavior and a named check or human owner.
- Prevent next time
- Run contract lint before execution and reject criteria that lack evidence mapping.
F2The agent follows the contract but cannot use a simpler repository-native solution.
- Inspect
- Look for required function names, file layouts, libraries, or step sequences inside product criteria.
- Likely cause
- The author embedded a speculative implementation as if it were user intent.
- Repair
- Move necessary technical constraints into a design note and leave local choices open within invariants.
- Prevent next time
- Review every requirement by asking which user consequence would fail if the detail changed.
F3The acceptance suite passes even though an unauthorized reviewer can change state.
- Inspect
- Check whether negative permission cases exist and assert that no state or audit write occurred.
- Likely cause
- The contract described only successful action and omitted prohibited effects.
- Repair
- Add a denied-role fixture and assert both the error response and unchanged authoritative state.
- Prevent next time
- Require at least one negative authority case for every state-changing action.
Beyond the demo
Production boundary
- 01Contracts are reviewed and versioned before candidate output is available
- 02Observable product behavior stays separate from changeable implementation choices
- 03Every side effect has an authorized actor, protected object, prohibited path, and audit expectation
- 04Negative, stale, retry, and recovery paths have fixtures rather than prose-only warnings
- 05Evidence covers API, persistence, and user-visible behavior at the level each criterion requires
- 06Ambiguous product judgments stop for a named human instead of being filled by the coding agent
Evidence status
Sources and claim limits
Sources support the named claims; they do not guarantee the same result in another system.
- [1]Harness design for long-running application developmentplanner-generator-evaluator · testable contracts · harness simplification · cost tradeoffs
Anthropic · Published research · 2026-08-26
- [2]Building effective agentssimplest viable architecture · workflow patterns · environmental feedback · stop conditions
Anthropic · Official documentation · 2026-08-26
- [3]Harness engineering: leveraging Codex in an agent-first worldrepository knowledge · agent legibility · mechanical enforcement · entropy management
OpenAI · Public case · 2026-08-26
- [4]Andrej Karpathy's AI Engineering PlaybookSoftware 3.0 framing · spec-diff-eval practice · parallel session framing · repository instructions
AI Builder Club · Public case · 2026-08-26
- [5]Learn Harness Engineeringproject-based sequence · five harness subsystems · loop engineering · graph engineering
Walking Labs · Public case · 2026-08-26
Related Tenten resources