From 245b1e904601fa45e09279478d831cecbb17a1f4 Mon Sep 17 00:00:00 2001 From: mm Date: Thu, 1 Oct 2026 14:12:58 -0400 Subject: [PATCH] IMP-076: Explain contract execution, evaluation and returned results --- content/docs/declare-outcomes.mdx | 30 ++++++++++++++++++++++++++++-- content/docs/index.mdx | 7 ++++--- 2 files changed, 32 insertions(+), 5 deletions(-) diff --git a/content/docs/declare-outcomes.mdx b/content/docs/declare-outcomes.mdx index dc2fcac..bf64460 100644 --- a/content/docs/declare-outcomes.mdx +++ b/content/docs/declare-outcomes.mdx @@ -7,8 +7,7 @@ description: Express intent through requirements. Reuse and combine contracts wh # Contract authoring -State what the agent must accomplish, which requirements it must satisfy, and -where it can choose its approach. **Contract authoring is expressing intent by +**Contract authoring is expressing intent by composing requirements.** A contract states those requirements and the context needed to interpret and apply them. @@ -20,6 +19,33 @@ concrete; it does not by itself establish that the result is accurate. +## Execution and evaluation + +An agent performs the work, and an evaluator assesses whether the contract's +requirements are satisfied. The **executor** performs the work and returns a +**result** that includes the evidence needed for assessment. The **evaluator** +returns an **assessment**: its findings about the contract and the evidence. +Execution and evaluation repeat as needed. Evaluation can also assess the +current state before further execution. + +These are roles. The same agent can perform both unless a composed contract +requires independence. A decision model can perform evaluation. Authors +compose contracts for evidence, review and authorization just as they compose +contracts for the rest of the work. + +A result can be a long document containing or referencing artifacts and +records. Keep its references accessible to the evaluator. Evidence belongs in +the result, not in a separate return value. Fulfillment means satisfaction of +the contract's applicable requirements; returning a result does not establish +fulfillment by itself. + +Use **out** for the normal result channel and **error** for execution failure. +An evaluator can return a normal assessment that finds unmet requirements or +insufficient evidence in its subject. Preserve partial work and effects when +execution fails. These concepts map to the selected runtime's existing +interfaces: function returns, responsibility state and receipts, and declared +errors. They do not add syntax or prescribe operating-system streams. + ## Requirements and approaches A requirement states a condition the work must satisfy. An approach describes diff --git a/content/docs/index.mdx b/content/docs/index.mdx index a82a03f..6e3d52a 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -1,15 +1,16 @@ --- title: OpenProse -description: State what an agent must accomplish, which requirements it must satisfy, and where it can choose its approach. Reuse and combine Markdown contracts. +description: Express intent by composing requirements. Execute contracts and evaluate results. --- # OpenProse -**With OpenProse, you state what an agent must accomplish, which requirements it -must satisfy, and where it can choose its approach.** Contract authoring is +Contract authoring is expressing intent by composing requirements. Reusable contracts provide the building blocks; composition determines how their requirements apply together. +An agent performs the work, and an evaluator assesses whether the contract's requirements are satisfied. The executor returns a result that includes evidence for the assessment. Execution and evaluation repeat as needed. + These docs cover the public `open-prose` skill's **Contract Markdown and ProseScript** format. A `responsibility` expresses requirements for information or conditions maintained over time. A `function` provides a one-time call.