picassodocs
docs/goal-contract-reference.md

Goal Contract Reference

A goal contract (@picasso/goals GoalContract) defines what Picasso should finish, where it may work, how much budget it may spend, and — critically — how completion is judged by machine-verifiable signals rather than the agent's word.

Contracts are validated by validateGoalContract / assertValidGoalContract and persisted to goals.json. Every field below maps directly to the implementation in packages/goals/src/contract.ts.

Shape

id: 123e4567-e89b-42d3-a456-426614174000
objective: Migrate the auth module and keep the repository green.
completionCriteria:
  - type: all-tests-pass
    testCommand: pnpm test
  - type: command-exits-zero
    command: pnpm typecheck
  - type: agent-self-assesses-complete
    rubric: The diff is scoped to the auth migration and verification passes.
budget:
  maxWallTime: 24h
  maxCostUSD: 25
  maxSteps: 1000
  maxSubagentSpawns: 20
scope:
  allowedTools: [read_file, edit_file, exec, spawn_subagent]
  allowedSubagents: [codebase_investigator, test_writer, generalist]
  permissionMode: safe
  workspaceRoot: /workspace/picasso
  rejectUnparseableEdits: true
escalation:
  onRepeatedFailure: escalate
  repeatedFailureThreshold: 3
  onBudgetExhausted: pause
notifications:
  onComplete: [dashboard]
  onStuck: [dashboard, webhook]
  onBudgetMilestone: [50, 80, 95]
audit:
  deliverables:
    - path: packages/auth/src/index.ts
      note: argon2id migration entry point
  failOnDebris: false

Budget fields (budget)

Scope fields (scope)

an edit that leaves a touched file unparseable and feeds the error back (defaults on for every mode except yolo).

Escalation fields (escalation)

Notifications fields (notifications)

Completion criteria (completionCriteria)

Every contract must contain at least one machine-verifiable criterion — agent self-assessment alone is rejected by validation. The machine-verifiable set is: all-tests-pass, specific-tests-pass, file-matches, command-exits-zero, lint-clean, pr-mergeable, custom-script, and score-improves.

all-tests-pass

- type: all-tests-pass
  testCommand: pnpm test

Passes when the test command exits zero.

specific-tests-pass

- type: specific-tests-pass
  testCommand: pnpm --filter @picasso/auth test
  testPaths:
    - packages/auth/test/**/*.test.ts

Passes when the scoped test command exits zero.

file-matches

- type: file-matches
  path: packages/auth/src/index.ts
  pattern: argon2id

Passes when the file exists and its contents match the regular expression.

command-exits-zero

- type: command-exits-zero
  command: pnpm typecheck

Passes when the command exits zero.

lint-clean

- type: lint-clean
  lintCommand: pnpm lint

Passes when the lint command exits zero.

pr-mergeable

- type: pr-mergeable
  prRef: owner/repo#123

Passes when the pull request is mergeable (checks green, not changes-requested).

custom-script

- type: custom-script
  scriptPath: scripts/verify-goal.sh

Passes when the script exists and exits zero.

score-improves

- type: score-improves
  scoreCommand: node bench.js   # prints a single number to stdout
  direction: higher             # or: lower
  baseline: 87.5                # optional; captured at pre-flight when omitted
  minDelta: 0.5                 # optional; default 0 (strictly better)

Runs scoreCommand, parses the trailing number, and passes when it improves on baseline by at least minDelta in direction. When baseline is omitted it is captured during pre-flight and persisted on the goal record.

agent-self-assesses-complete

- type: agent-self-assesses-complete
  rubric: The summary names behavior changes, risk, and verification.

Recorded as trust-prior evidence. It never re-runs in the final audit and never counts toward the coverage numerator — it cannot, on its own, complete a goal.

Audit config (audit, optional)

the full working tree (committed + staged + unstaged + untracked). A missing deliverable fails the audit.

TODO/FIXME, dead imports on added lines) fails the audit instead of just warning.

Verification lifecycle

  1. Pre-flight — before the loop, the deduplicated machine commands run once.

A red baseline aborts the run (override with --skip-preflight). score-improves baselines are captured here.

  1. Loop — plan → act → observe → assess with drift detection and

self-correction; criteria are evaluated each iteration.

  1. Final ship audit — after the loop reports complete, every machine

criterion is independently re-verified, declared deliverables are checked against the full working tree, and a coverage score (re-verified / (re-verified + trusted)) is reported. Coverage under 70% emits an "eyeball before merge" warning. A failed audit downgrades the goal to blocked rather than reporting success.

when all children complete and pass their own audits).

Resume behavior

When a cap is hit, the goal persists a checkpoint and returns a resume token. Resuming reloads the latest safe checkpoint and continues with the remaining scope and updated budget. The oracle gate and final audit also apply on resume.