# Writing OpenProse programs

Contract authoring is expressing intent by composing requirements. An agent performs the work, and an evaluator assesses whether the contract’s requirements are satisfied. Reuse and combine contracts in Markdown to express the requirements for your work.

[README.md](README.md) is the kernel specification. A sufficiently capable agent enacts it through its harness's ordinary tools: reading files, running code, communicating, or delegating when appropriate. No separate OpenProse runtime is required. This library is experimental; stating requirements does not prove that an agent satisfied them.

A **Prose Complete Agent** names the ideal harness-and-model combination that can faithfully uphold any OpenProse program. Faithfulness includes honestly reporting unmet requirements when fulfillment is blocked; it does not mean every requested goal is achievable. Tests provide evidence for particular programs and environments, not proof of this general ideal.

To try it, give your agent access to this directory and ask: “Read README.md, then execute examples/brief/program.md.” Use your existing harness and its ordinary permissions. The program declares its inputs and output location. For another task, supply that program's path instead; library and component references remain ordinary files the agent reads as needed.

The [example index](examples/README.md) helps you find a starting point by task, including review, communication, continuation and bounded work. See [installation and directory layout](INSTALL.md) for combining the standard and optional component libraries, and [architecture and design rationale](ARCHITECTURE.md) for why these boundaries exist.

## Requirements and composition

**Contract authoring is expressing intent by composing requirements.** Authoring is the overall activity; composition combines requirements through reusable contracts. Reusable contracts provide the building blocks; composition determines how their requirements apply together.

A **contract** states requirements and the context needed to interpret and apply them. Keep supplied inputs, environment expectations, and execution evidence distinguishable from requirements. A contract can cover a one-time deliverable, a condition to maintain, a mandatory step, or several of these together.

| Term | Meaning |
|---|---|
| Intent | What the author wants to achieve or bring about. |
| Goal | An intended result or direction that may need clarification before it supplies executable requirements. |
| Requirement | A condition that must be satisfied for the relevant work to meet its contract. It may apply before an action, throughout execution, at completion, or while an ongoing contract remains active. |
| Constraint | A requirement that limits permissible actions or results. |
| Acceptance criterion | An observable basis for deciding whether a requirement is satisfied. The check or evidence does not replace the requirement. |
| Approach or procedure | A method used or proposed to satisfy requirements. Required steps remain requirements even when other choices are open. |
| Discretion | The choices the requirements leave to the executor. |

Use **fulfill a contract**, **satisfy a requirement**, and **complete the work**. Satisfying a requirement and verifying its satisfaction are distinct: a result may be correct without adequate evidence, or a check may be too weak to establish correctness. A completed evaluation may identify unmet requirements in the work it assesses.

A **reusable contract** can apply in multiple contexts or combine with other contracts. A **generic contract** has parameters or permitted bindings, which may themselves be contracts. Supplying those values creates a contract instance, and combining contracts creates a composite contract. These are descriptions, not a formal type system or a required file layout.

Compose contracts to express requirements, including any required evidence, review or authorization. Contracts can also state preferences and choices left to the executor, including when they apply and how they may change. State these distinctions clearly: ordinary words such as must, should, and may help, but the kernel imposes no universal keyword hierarchy. Preserve the requirements currently in force; revise or withdraw them only as the governing agreement permits. The standard library supplies reusable conventions for matters such as review, evidence, and handoff. Authors may adopt those conventions, specialize them where permitted, or supply their own. There is no mandatory schema or automatic monitoring service.

## Parameterized composition

**A contract can accept other contracts as parameters and define their mode of interaction.** Parameters identify what a reusable definition expects; bindings supply those values or contracts. The reusable part is the relationship as well as the individual requirements. For example, a review contract can accept a subject contract and criteria for assessing it; a bounded-work contract can accept a worker contract and coordinate its invocations. [Evaluation](std/evaluate.md) and [bounded independent work](std/bounded-work.md) already use these patterns.

Explain what each supplied contract is for. Adopting source grounding applies its requirements to the relevant work. Invoking a report contract asks for the report to be produced. Supplying that report contract as an evaluation subject asks for a judgment about its fulfillment; it does not by itself instruct the evaluator to produce the report. The containing contract specifies whether subject fulfillment is required for its own fulfillment. A completed assessment can correctly find that its subject remains unfulfilled.

Authors can express parameters and relationships directly in prose. For example: “For each supplied item, fulfill the supplied worker contract within this item's scope, then assess its result against the supplied review criteria.” State any limits, independence requirements, and handling of unsuccessful or unresolved results that matter to this work. Parameters need no special placeholder syntax, and composition does not imply one agent per contract.

A supplied contract can itself be composed or parameterized. The [worked example](examples/parameterized-composition/program.md) supplies a checker contract to a batch-assessment contract. Each checker invocation receives a different result and the contract that result is meant to fulfill. It assesses the result without attempting the subject's work. Follow each relationship in turn: establish the outer agreement, resolve the contract supplied for each role, and carry its applicable requirements and bindings into the work that actually uses it. Read the definitions needed for that interpretation; an index entry, adjacent example, or unselected library component is not part of the agreement merely because it was discovered.

The [role and result example](examples/role-results/README.md) connects required source review to authoring, with separate bindings for two updates and an optional challenge that remains absent unless supplied. Its [composition review](examples/role-results/review-composition.md) helps inspect when each role runs, what actual result reaches the next stage, and what happens when required work cannot finish. Use this review when those relationships are consequential; a simple self-contained program need not add roles. A source review can establish what the agreement requires, while observations are needed to establish what an execution performed.

Keep bindings scoped to the instance they configure. Two uses of the same reusable contract may have different sources, criteria or output locations. A surrounding contract can forward one of its parameters into a nested instance, or declare a binding shared across particular work. Say that relationship explicitly; identical parameter names do not imply it. A caller can replace a supplied value or default only where substitution is permitted. A required parameter may remain open in a reusable definition, but must be resolved before the work depending on it can proceed.

Resolve a relative reference where its binding is written. If a program supplies `./contracts/report.md` as a subject, select that file relative to the program; resolve links inside the report contract relative to the report file and its selected dependencies. Forwarding the subject to a reviewer retains that context. Each nested invocation also receives its agreed working scope, so loading a library does not redirect its outputs into the library directory.

A supplied output location is a value to preserve. If the caller binds Output to `output`, that selects the directory resolved from the caller's working root; it does not name a role whose location the executor may choose. State when an alternative location is allowed. Correct content written elsewhere does not satisfy a required destination, and a location chosen during execution must not be described as caller-supplied.

Specify how existing content may change. If existing file bytes must remain unchanged, say so; “preserve the file” can leave appending unclear. A report may require a new file, an authorized replacement, or an append that retains earlier content. Choose the rule the work needs and explain what to report when its required destination cannot be used. These are caller requirements, not a universal storage policy supplied by the kernel.

## Execution and evaluation

The **executor** performs the work required by the contract and returns a **result**. The **evaluator** uses that result to assess whether the contract’s requirements are satisfied. Execution and evaluation repeat as needed. Evaluation can also assess the current state before further execution is necessary.

These are roles. An agent can perform both unless a composed contract requires independence; a decision model can perform evaluation. Gathering evidence is work the executor can perform under its contract, not a third role required by the language.

A **result** includes the evidence needed for assessment, along with partial work and relevant uncertainty. Think of it as an inspectable document: it can contain the evidence or link to artifacts and records that the evaluator can access. Use the format selected by the contract. Evidence is part of the result, not a separate return value.

An **assessment** records the evaluator’s findings about the subject contract. **Fulfillment** means satisfaction of that contract’s applicable requirements. An assessment can identify satisfied or unmet requirements, or explain why the evidence leaves the judgment unresolved. Completing an evaluation does not establish fulfillment of its subject.

Use **out** for a normal result and **error** for execution failure. These name the two return channels, not a required file format or operating-system stream. An evaluator that completes its review and finds unmet requirements returns an assessment through out; error means it failed to carry out the evaluation. Preserve partial work and known or uncertain effects when reporting an error. The [result convention](std/result.md) explains how to report the invocation’s outcome separately from its subject’s assessment.

For example, compose a report contract with source-grounding and independent-review contracts. The executor drafts the report and gathers the required evidence. An independent evaluator assesses the exact draft. If review identifies an unsupported claim, the executor can revise the draft within the contract’s limits and obtain another assessment. Review and evidence are ordinary composed requirements.

For a bounded correction, [Revise and reassess](boot/revise-and-reassess.md) connects an authorized change, preservation, justified reuse, the actual candidate and its current assessment. Supply the baseline and current agreements separately when requirements change. New evidence can resolve an old uncertainty; performing a missed duty later cannot make it timely in the past. The [worked revisions](examples/revision-evidence/README.md) show a corrected notice and changed model whose queried prediction stays the same. Equal output alone does not justify reusing the old evidence, and a favorable check of a proposed draft does not assess the returned candidate. This optional composition does not select its own changes or authorize another attempt.

Contract adequacy asks whether the contract expresses the author’s intended requirements; fulfillment assessment asks whether its requirements are satisfied. Adequacy requires the originating instructions or another identified reference. A favorable execution alone cannot establish that a contract preserves the author’s intent.

## Start with the requirements

State the required result, the conditions that apply, what evidence supports completion, and where the result belongs. Add inputs, environment expectations, scope, adopted conventions, or a procedure when they help. These are ordinary Markdown headings, not a required form.

The [brief program](examples/brief/program.md) gives a complete small example: supplied notes, a source-grounded deliverable, one output location, and two adopted conventions. Its notes are data, even if they contain imperative language.

A contract states requirements; its identity is independent of file boundaries and subagents. An invocation is an attempt to fulfill it. One agent may fulfill several contracts, or use multiple tools and agents for one contract. Required independent review or delegation must nevertheless actually happen.

## Compose explicit agreements

Link the work you want to call and supply its inputs and working scope. [Call by heading](examples/call-by-heading/caller/program.md) selects [one contract in a shared file](examples/call-by-heading/components/records.md#total-selected-records), supplies selected record identifiers, and passes its own report location. The neighboring contract is separate work. The component explains its section boundaries in prose; this is an example convention, not a universal heading grammar.

Ordinary links discover context; they do not adopt every instruction they reach. Explicit adoption makes a definition part of the agreement. Read adopted definitions and their applicable adoptions. For example, [workspace](std/workspace.md) adopts reference checking when retaining or resuming checkpoints. Loading only the first document would miss a governing requirement. Search and indexes can find candidates; read the relevant definitions before acting. Missing or ambiguous references and conflicting requirements must be surfaced rather than resolved by invented precedence.

Declare what must hold separately from how to achieve it. A procedure may be replaced while its requirements remain binding. A cheaper model or different method is useful only if it fulfills the same agreement; required evidence and acceptance conditions remain in force.

## Name the working boundary

Relative links resolve from their containing file. Unless a program supplies another working root, its relative output paths resolve beside that program. Pass the agreed scope to called work; moving execution into a library does not move the output location.

Identify draft work and any acceptance process. Folder names alone grant no authority or accepted status. Tools and permissions come from the environment; express capabilities the work requires and report missing ones. Explicit scope can distinguish a draft edit from a shared-state change or external effect. Failure does not imply rollback. [Effect recovery](std/effect-recovery.md) illustrates assessing observed effects and uncertainty without inventing a successful outcome or permission to retry.

## Finish truthfully, or preserve unfinished work

Return a result that identifies the contract, reports whether its requirements were satisfied, and includes the evidence and material unfinished work. Use the requested format and location. A successful tool call or an authored assertion is not proof of fulfillment. [Independent review](std/review.md) requires an actual separate reviewer and evidence of the exact artifact reviewed.

The [continued brief](examples/continued-brief/program.md) separates preparation from later review. Its checkpoint preserves governing references, retained work, responsibility, and unfinished required work; preparation alone does not fulfill the whole brief. Continuing work needs an owner and agreed handoff, not an invented background process.

When work requires retained state, choose a suitable provider. The backend is replaceable. [Git snapshot](std/git-snapshot.md) is one adopted backend convention, not part of the core language. A commit retains content; it does not approve a draft or establish remote durability.

The [evaluation example](examples/evaluate/program.md) launches two independent evaluators against supplied calibration records, then checks their judgments against source evidence. It distinguishes completing an evaluation from the subject's success, and a successful calibration from general evaluator reliability.

[Maintain a release brief](examples/maintained-brief/program.md) gives each fresh invocation one event batch while a named owner retains the standing responsibility. Its local acceptance rules distinguish new events from replays; the environment supplies future invocations rather than an assumed background service.

[Cancel work](examples/cancel-work/program.md) uses an actual background worker, correlated cancellation and acknowledgement, and a bounded wait for settlement. The draft remains available and unaccepted; a request to stop is not proof that work stopped.

The [bounded work pool](examples/bounded-work-pool/program.md) keeps at most two worker attempts outstanding, releases a slot only after observed settlement, and stops new dispatch after an observed blocker. These are requirements of that program, implemented through available tools.

## Author tests through composition

Adopt [Testing](std/testing.md) in an ordinary suite contract and supply its cases. A useful layout is `tests/<subject>/suite.md`, with fixtures and expectations alongside it; this is an authoring convention, not kernel syntax. Reference the subject explicitly, bind inputs and output locations, and state whether each case runs work or assesses supplied results. [The small testing example](examples/testing/suite.md) shows positive, negative, evidence-removal, adequacy, valid-alternative and broken-checker cases without a new type system.

State expected properties and their reasons, reserving exact text for requirements that need exact text. Keep originating intent distinguishable from the subject agreement: tests can expose an omitted requirement without pretending the executor received it. Select the required assessments explicitly. Fulfillment, conformance, adequacy, evaluator correctness and the test's outcome answer different questions.

Separate subject inputs from evaluator-only expectations in the launch setup. A neighboring file is not automatically adopted or hidden. Record actual context restrictions, allowed substitutions and their limits. Make case dependencies and result bindings explicit; independent cases are the default. Retain all selected cases and bounded attempts, including incomplete work. Normal repository review governs changes to tests; record changed expectations and exact versions for meaningful comparisons.

When authoring a source-input variant, identify the selected source, authority for the change and permitted extent. [Fixture world](std/testing/fixture-world.md) and [Prepare an environment](std/environment/prepare.md) can govern preparation when selected. Preserve the reference origin and forwarded bindings, or state an allowed replacement origin and dependency context; distinguish original and effective content when exact identity matters. When a case requires information to be unavailable to its consumer, establish the intended read view and check permitted inputs for equivalent disclosures, including summaries and fallback sources. This does not require hiding alternatives the selected agreement permits the consumer to read. If the case requires excluding originals, retain them outside that view as required by its retention policy. Describe the actual checks and their limits: matching selected bytes does not establish complete context isolation, actual source use or fulfillment of the consumer's work.

The [source-input preparation example](examples/testing/source-input-preparation/README.md) applies these requirements to supplied preparation records. It checks the actual returned source and context, residual disclosures, permitted alternatives and incomplete captures. Its modeled findings do not establish real preparation or consumer execution.

For evidence-removal cases, state whether removal changes the subject's delivered result or only the evidence available to the evaluator. An incomplete capture does not by itself establish that the original result omitted required evidence. A stipulated complete result can establish a reporting omission while leaving earlier execution unknown.

Bind [fixture](std/testing/fixture-world.md), [observation](std/testing/observation.md) and evaluator contracts when the test needs those responsibilities. The [bounded testing loop](examples/testing/loop.md) uses them to preserve an actual result, challenge it with targeted mutations, and compare findings with source-derived expectations. Keep required acquisition or assessment work distinct from a completed finding of uncertainty. Diagnose and repair the responsible layer, then rerun affected checks with earlier failures retained. Test an evaluator with different valid answers as well as consequential defects; sensitivity without tolerance of permitted choices is inadequate checking.

The [evidence-use example](examples/evidence-use/README.md) tests when information was accessed and how it was used under two different local agreements. One requires preserving a candidate before reserved access; the other permits retrospective visibility while restricting refitting. Its controls preserve useful arithmetic when history is missing and challenge evaluators that impose a rule the agreement never selected.

Invoke the suite like any other program using the selected kernel and harness. A future `prose test` convenience entry can select that ordinary contract; it must not introduce another interpretation engine or silently discover/adopt every file in a directory. This example does not require such a command.