From 55772b50c722233fef40b538be7f70548b7aec3c Mon Sep 17 00:00:00 2001 From: mm Date: Thu, 1 Oct 2026 00:02:33 -0400 Subject: [PATCH] IMP-063: Explain public docs through requirements and composition --- .prose/generate-agent-skills.prose | 2 +- README.md | 16 +- __tests__/agent-skills-manifest.test.ts | 4 +- content/docs/contracts.mdx | 109 +++++---- content/docs/declare-outcomes.mdx | 228 ++++++++---------- content/docs/harness-agnostic.mdx | 72 +++--- content/docs/index.mdx | 37 ++- content/docs/prosescript.mdx | 22 +- content/docs/setup.mdx | 14 +- content/docs/typed-image.mdx | 19 +- package.json | 2 +- public/.well-known/agent-skills/index.json | 8 +- .../openprose-getting-started/SKILL.md | 42 +++- 13 files changed, 310 insertions(+), 265 deletions(-) diff --git a/.prose/generate-agent-skills.prose b/.prose/generate-agent-skills.prose index 580ddbf..475fec5 100644 --- a/.prose/generate-agent-skills.prose +++ b/.prose/generate-agent-skills.prose @@ -28,7 +28,7 @@ production build leaves the repo. - `repo_root`: absolute path to the prose-docs/ checkout - `manifest_path`: `/public/.well-known/agent-skills/index.json` - `skill_glob`: `/public/.well-known/agent-skills/**/SKILL.md` -- `canonical_base_url`: `https://docs.openprose.ai` +- `canonical_base_url`: `https://docs.prose.md` ### Ensures diff --git a/README.md b/README.md index a3ab173..368eb7b 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,35 @@ # @openprose/docs -Documentation site for [OpenProse](https://github.com/openprose/prose), the programming language for AI sessions. +Documentation site for [OpenProse](https://github.com/openprose/prose). Contract authoring expresses intent by composing requirements: state what an agent must accomplish, which conditions it must satisfy, and where it can choose its approach. Live at: https://docs.prose.md ## What is this? -`openprose/docs` runs three prose programs: it compiles its own agent corpus, enforces its own spec coverage, and builds its own changelog. +This site documents the public `open-prose` skill and its Contract Markdown / ProseScript format. The current documentation was checked against skill 0.18.0 (`runtime_contract: 2`) at [source revision `770cebc9`](https://github.com/openprose/prose/tree/770cebc9e03a7150a73bd454b7a6da307595ff9d). The authoring introduction is maintained at [Contract authoring](content/docs/declare-outcomes.mdx); syntax and runtime behavior remain owned by the public language repository. + +The Markdown exports and agent-readable corpus are generated directly from the MDX pages. Vendored examples are retained source specimens. The two `.prose/` files retain legacy manifest and changelog maintenance programs (`kind: program`, `Services`, and `Ensures`). They require a separate format upgrade before use with the current skill and are not part of CI or the Docker build. They were not executed or model-validated for this documentation update. ## Local development ```bash -pnpm install # also initializes external/prose submodule +pnpm install --frozen-lockfile pnpm dev # http://localhost:3000 pnpm check # typecheck + lint + spell -pnpm build # production build +pnpm exec next build # production build, matching CI and Docker ``` ## Layout - `content/docs/**/*.mdx` -- hand-authored documentation -- `external/prose/` -- pinned submodule of `github.com/openprose/prose` (reference content for examples) -- `.prose/` -- three dogfood programs that run during build (`generate-llms`, `changelog-sync`) or from cross-repo CI (`spec-coverage`) +- `vendor/prose-examples/` -- retained example source displayed by documentation pages +- `.prose/` -- retained legacy manifest and changelog maintenance programs; upgrade before execution - `app/` -- Next.js App Router routes (docs pages, `.md` exports, agent-readable surfaces) - `lib/` -- helpers (canonical URLs, preview-mode flag, MDX-to-MD conversion) - `components/` -- React components consumed by MDX pages +`pnpm build` still invokes those legacy programs through an agent in its `prebuild` hook. Use the CI build command above for a deterministic site build without a model call. CI additionally runs unit tests, link and punctuation checks, and standalone HTTP smoke checks in public and preview modes. + ## License MIT diff --git a/__tests__/agent-skills-manifest.test.ts b/__tests__/agent-skills-manifest.test.ts index 8b559a1..f5958e5 100644 --- a/__tests__/agent-skills-manifest.test.ts +++ b/__tests__/agent-skills-manifest.test.ts @@ -39,9 +39,9 @@ describe(".well-known/agent-skills/index.json", () => { expect(manifest.skills.length).toBeGreaterThan(0); }); - it("each skill URL points to docs.openprose.ai", () => { + it("each skill URL points to docs.prose.md", () => { for (const skill of manifest.skills) { - expect(skill.url.startsWith("https://docs.openprose.ai/")).toBe(true); + expect(skill.url.startsWith("https://docs.prose.md/")).toBe(true); } }); }); diff --git a/content/docs/contracts.mdx b/content/docs/contracts.mdx index 7b1d169..737da76 100644 --- a/content/docs/contracts.mdx +++ b/content/docs/contracts.mdx @@ -1,25 +1,24 @@ --- title: Contracts -description: The authored surface of OpenProse, covering Markdown contracts, the five kinds, and the load-bearing sections that turn a declaration into a typed, subscribable node. +description: Write requirements in Contract Markdown. Learn the five contract kinds and the sections that define inputs, maintained state, required steps, and limits. --- # Contracts -A contract is the thing you author. It is a Markdown file (`*.prose.md`) -with a small YAML frontmatter and a handful of `###` sections. The Markdown, -with its durable trail, is the public artifact: it can leave for any -Prose-Complete harness with no lost semantics. The deployment's secrets and -data stay private. +A contract states requirements and the context needed to interpret and apply +them. Authors specify what the agent must accomplish, the conditions it must +satisfy, and the choices it may make. Humans and agents can both author and +reuse contracts. -Authors are co-equal. A human and an agent write contracts the same way, read -the same sections, and fork or compose each other's work without translation. -Every section below is designed for both readers from the start. +This page describes the public skill's **Contract Markdown** format: +`*.prose.md` files with YAML frontmatter and recognized `###` sections. The +five kinds support standing work, one-time calls, external inputs, tests, and +reusable coordination. [Contract authoring](/declare-outcomes) explains how to +use these building blocks to express requirements together. -This page is the authored surface only (what you write). The runtime that -*serves* these contracts (fingerprints, memoization, the continuity clock, -receipts) is the harness's concern; see -[Harness-agnostic](/harness-agnostic) for that seam. Here, intent -lives only in the contract. +The sections declare requirements and interfaces. The selected host supplies +tools and runtime behavior; see [Harness-agnostic](/harness-agnostic) for that +boundary and implementation limits. ## Frontmatter and identity @@ -29,10 +28,11 @@ A contract opens with YAML frontmatter. Two fields carry weight: one field that changes how the file is executed. - `name:` is the human-facing slug. -A third field, `id:`, is a durable identity (a base32 token) minted once by -tooling and preserved across `name:` and filename renames. You do not -hand-write `id:`; tooling manages it. `name:` is what you read; `id:` is what -keys the node's world-model and receipt-ledger state on disk. +An optional `id:` gives a responsibility or gateway a source identity that +survives `name:` and filename renames. Without it, the slug is the identity. +The language repository's `scripts/mint-contract-id.mjs` tool mints the +26-character base32 value. The compiled node key identifies a particular mount; +it is distinct from the optional source `id:`. ## The five kinds @@ -40,7 +40,7 @@ keys the node's world-model and receipt-ledger state on disk. | Kind | Run model | Purpose | | --- | --- | --- | -| `responsibility` | Served (continuously reconciled) | The headline kind: a mounted DAG node maintaining a standing truth over time. | +| `responsibility` | Served (continuously reconciled) | A mounted DAG node with requirements for state maintained over time. | | `function` | Called (one-shot) | A stateless, ephemeral helper. Bind `### Parameters`, run one render, return `### Returns`. No Forme phase, no world-model. | | `gateway` | Mounted as external-driven | Sugar for an external-driven responsibility. Compiles into a trigger registration for the serving host; refuses a direct `run`. | | `test` | Via the test path | Fixtures plus natural-language assertions against a subject responsibility or function. | @@ -52,24 +52,27 @@ subscription between responsibilities; intra-node composition is an imperative `call` inside one render. There is never an internally-autowired graph kind. -The headline kind is `responsibility`. The rest of this page teaches its -load-bearing sections, because those are what make a contract a *typed, -subscribable node* rather than a bare prompt. +The rest of this page focuses on `responsibility`: its declared inputs, +maintained state, and conditions for carrying out the work. Functions use the +separate call interface described below. -## The load-bearing sections + -Most `###` sections mean exactly what their name says. `### Description` is a -human summary preserved for readers, not a contract. `### Goal` is the render's -one-sentence standing intent. These defer to the obvious. +## The recognized sections -Three sections carry the semantic load of a `responsibility`, and the contract -must *state* them rather than defer: `### Requires`, `### Maintains`, and -`### Continuity`. +`### Description` is a summary for readers. `### Goal` states the intended +result. Use the recognized semantic sections for the requirements that guide +execution. + +The following sections describe a responsibility's subscriptions, maintained +state, and wake source: `### Requires`, `### Maintains`, and `### Continuity`. +`### Invariants` states limits that must hold during the work; `### Execution` +can specify required steps. Use the sections applicable to the contract. ### `### Maintains`: the world-model schema (four jobs at once) -`### Maintains` is the schema for the truth this node keeps current. It does +`### Maintains` is the schema for the state this node maintains. It does four jobs in one section: 1. It **types** the maintained truth, the shape of the world-model the node @@ -81,11 +84,12 @@ four jobs in one section: 4. It states **postconditions** that a render must satisfy before it may commit. -There is no separate judge and no `### Criteria` section. Satisfaction folds -into `### Maintains`: checked deterministically where it can be written as a -validator, and self-attested by the render where it is semantic. A render that -cannot satisfy its postconditions commits nothing. The prior truth stands, -and a `failed` receipt records why. +There is no separate judge and no `### Criteria` section in this format. +`### Maintains` states postconditions: deterministic validators can check some, +while semantic conditions rely on render self-attestation. The language +requires a render that cannot satisfy its postconditions to leave prior state +unchanged and report failure. Actual enforcement and receipt detail depend on +the host; see [implementation limits](/harness-agnostic#implementation-status). ### Facets make subscription structural @@ -99,10 +103,9 @@ part of the truth. The facet's name is, at once, three things: `Requires.` ↔ `Maintains.`); - and its **region** of the world-model. -Declaring no parts is the atomic default (one truth, one token) and costs -nothing. This adds no new grammar: it reuses the heading hierarchy and the -Requires↔Maintains join. **Structure is subscription.** The way you shape the -`### Maintains` section *is* the way downstream nodes subscribe to it. +With no named parts, the whole state is one atomic facet. Named facets reuse +the heading hierarchy and the Requires↔Maintains connection. The parts you +define in `### Maintains` determine what downstream nodes can subscribe to. ### `### Requires`: what the node subscribes to @@ -127,9 +130,9 @@ should re-render. It is **not a schedule**. A node is *input-driven* by default - *external-driven*, which marks a `kind: gateway` so an ingress event wakes it. -The author writes these sections. The harness owns the fingerprinting, the -forecast cadence, the receipts, and the subscription wiring. You declare the -truth; the runtime decides, deterministically, when it is worth recomputing. +The author states the requirements in these sections. A serving host provides +fingerprinting, cadence, receipts, and subscription processing. Its supported +wake sources determine when it attempts the work. ## Functions: the call interface @@ -144,7 +147,12 @@ A lone function has no Forme phase: bind parameters, spawn one render, return ## A contract in full -Here is a real, migrated `responsibility`. Read it top to bottom: the `> ` +The following retained source snapshots illustrate how a `responsibility` and +its gateway connect. They predate the current section cleanup and are shown +verbatim; `### Continuity recheck` in the gateway is an older heading. For +current runnable source, use the [skill 0.18.0 basic-unit-suite](https://github.com/openprose/prose/tree/770cebc9e03a7150a73bd454b7a6da307595ff9d/skills/open-prose/examples/basic-unit-suite/src). + +Read the responsibility top to bottom: the `> ` description states intent for a human, `### Requires` names the single facet it subscribes to, `### Maintains` types the `CountSummary` truth and declares one `#### structured` facet with an explicit postcondition, and `### Continuity` @@ -160,11 +168,10 @@ metadata-only event moves `raw_events` (waking the auditor) without moving -A bare prompt is `any`: it tells an agent what to do once and forgets. A -contract is a typed function over the world: a declared truth with a fingerprint, -named facets others can subscribe to, and postconditions it must satisfy before -it commits. That is the whole difference, and it is authored entirely in -Markdown. +These examples combine a gateway's published inputs with a responsibility's +requirements for a summary. The declared interfaces make the composition +inspectable. Evidence and checks still determine whether a particular result +satisfies those requirements. ## Where to go next @@ -172,7 +179,7 @@ Markdown. -OpenProse asks one thing of you that most agent frameworks do not: **declare the -truth you want kept current, and stop there.** Not the steps. Not the order. Not -the prompt that coaxes a model through them. You write down the world as it -should be (an ideal world-model the system is responsible for making real and -keeping real), and the host figures out the work. +# Contract authoring -This is the inversion at the heart of the paradigm, and everything else (the -five contract kinds, fingerprints, the DAG, receipts) is downstream of it. +State what the agent must accomplish, which requirements it must satisfy, and +where it can choose its approach. **Contract authoring is expressing intent by +composing requirements.** A contract states those requirements and the context +needed to interpret and apply them. -## Instructions decay; outcomes endure +Reusable contracts provide the building blocks. Composition determines how +their requirements apply together. For example, a funding-view contract can +use a reusable source-gathering contract while requiring every reported event +to cite a source. Supplying inputs and connecting contracts makes that request +concrete; it does not by itself establish that the result is accurate. -A prompt is a sequence of instructions aimed at one moment. It runs, it produces -something, and then the moment passes. The world moves on: a new filing lands, a -competitor ships, a number drifts. The instructions have nothing to say, because -they were never about the world. They were about a turn. + -An **outcome** is different. "Every tracked competitor has a current, -corroborated funding view" is true or it is not, today and tomorrow and after -the source you scraped changes its layout. It is a standing claim about the -world, not a recipe for one visit to it. Declare the outcome and you have -declared something that can be *re-checked* and *re-established* without you -re-typing the steps. +## Requirements and approaches -That is the whole shift: +A requirement states a condition the work must satisfy. An approach describes +how to satisfy it. A constraint limits permissible actions or results. A +required step is also a requirement, even when other choices remain open. -| You stop writing | You start writing | +| Author's intent | Requirement to express | | --- | --- | -| "First fetch X, then summarize, then compare to Y..." | "This truth, with these fields, kept current and corroborated." | -| a sequence pinned to one run | a standing goal that survives many runs | -| intent spread across a prompt, a config, and a judge | intent in exactly one place | - - -This is the language layer. It says **what** is true and **what** counts as a -material change. It deliberately says nothing about *how often* the host checks, -*how* it decides something moved, or *what* it records along the way. Those are -runtime mechanics, owned by the harness that serves the contract, and left to -it on purpose. - - -## Intent lives only in the contract - -The first OpenProse tenet states it plainly: **intent lives only in the -contract.** The `*.prose.md` you author carries 100% of the semantic weight. -Everything else (the compiled artifacts, the projections, the operational -policy a host applies) is *derived*, and when a derived thing disagrees with -your contract, the contract is right. - -There is no second authored surface for intent. Not a prompt you tune on the -side. Not a YAML config that quietly overrides the Markdown. Not a hidden judge -prompt deciding what you really meant. If you find yourself reaching for one of -those, the meaning has leaked out of the contract, and the system can no longer -guarantee the outcome you declared, because you declared it in two places that -can drift apart. - -One source of meaning is not a stylistic preference. It is what lets the same -contract run identically on any compliant host, what lets an agent fork and -compose your work without archaeology, and what makes the audit trail honest: -there is exactly one thing the trail can be checked against. - -## The world-model: a maintained truth, like the DOM - -When you declare an outcome, the thing the system keeps real on your behalf is -the **world-model**: a node's maintained truth, persisted on disk, standing -between one unit of work and the next. - -If you know React, you already know the shape. The world-model plays the role -of the **DOM**: a current, structured representation that survives between renders, is -read by the next render as its prior state, and is subscribed to by whatever -depends on it. You do not rebuild it from scratch each turn. You declare its -*schema* (its shape, and what about it actually matters), and the system keeps -that truth current against a changing world. - -A render, then, is one bounded step from prior truth to next truth: +| A useful funding view | Include each tracked competitor and cite sources for reported events. | +| Safe research | Stay within the permitted sources, tools, and access limits. | +| Reusable analysis | State the inputs and the result that callers may rely on. | +| A necessary review | Require the review before the specified action. | + +Standing requirements, such as keeping a funding view current, are one use +case. Requirements can also apply to a single deliverable, an action before +publication, or evidence needed at completion. Choose the supported contract +kind and sections for the work rather than treating every request as a +continuous service. + +## Reuse and composition in this format + +These docs cover the public skill's Contract Markdown and ProseScript format. +It provides several concrete ways to reuse and combine contracts: + +- A `function` declares `### Parameters` and `### Returns`; a caller supplies + inputs and invokes it with `call`. +- A `responsibility` subscribes to another contract's published facets through + `### Requires` and `### Maintains`. Forme resolves those connections. +- A `pattern` describes reusable coordination with slots and configuration; + compilation specializes it into nodes. + +These mechanisms combine declared interfaces and behavior. A link to a file +alone does not create a subscription, provide a tool, or grant permission. +Check that connected requirements and interfaces are compatible. The +[Contracts](/contracts) and [ProseScript](/prosescript) references describe the +actual syntax; this introduction adds no new section names or operators. + + + +## Keep requirements in the authored source + +The authored contract is the reference for what the agent is asked to do. +Compiled artifacts and diagrams must preserve its meaning. Keep supplied +inputs, environmental capabilities, and execution records distinguishable from +the requirements themselves. + +Changing a procedure does not remove a requirement it was meant to satisfy. +When requirements change, revise the source explicitly and use the version +selected for the run. A previous result is evidence about that run, not proof +that revised requirements are satisfied. + + + +## Standing work and the world-model + +A `responsibility` maintains a **world-model**: structured state that persists +between renders. Its `### Maintains` section describes the state, material +changes, named facets, and postconditions. The world-model records the agent's +view of the world; its contents still need the evidence required by the contract. + +A render is a bounded attempt to produce the next state: ```text (contract, evidence, prior world-model) -> (new world-model, receipt) ``` -Read it as a sentence. Given **what you declared** (the contract), **what the -world now shows** (evidence), and **what was true last time** (the prior -world-model), one bounded session computes **the truth as it should now be** (the -new world-model) and leaves **a record of the decision** (the receipt). The -outcome you declared is the contract on the left and the world-model on the -right. The instructions you did *not* write are what the session figures out in -the middle. - - -You declare the world-model's schema: its fields, what counts as a material -change, and how its parts divide for subscription. The host owns *how* it decides -a change occurred (fingerprints), *when* it re-checks (the reconciler), and *what* -it records (receipts). Those mechanics belong to the host; this page is only -about the act of declaring the truth. - +The contract states the requirements. Evidence informs the attempt. The new +world-model and receipt record its result. Running a render, producing a +receipt, and satisfying the requirements are distinct outcomes. -## A type system for agent workflows +The host determines how subscriptions, freshness checks, and receipts operate. +Continuous operation requires a serving host; writing a standing requirement +does not start a background service. See [Harness-agnostic](/harness-agnostic) +for capabilities and implementation limits. -Here is the mental model that makes the discipline pay for itself. + -Think of a bare prompt as `any`. It runs, and nothing is checked: no declared -inputs, no declared output, no way for a caller to reason about it or for a -violation to fail loudly. A contract is a **typed function**. Its inputs and -outputs are declared, its callers can reason about composition, and an unmet -obligation fails where you can see it rather than rotting silently downstream. +## Requirements and evidence -You would not write a two-thousand-line TypeScript system in `any`. Multi-step -agent work is the same. Declaring outcomes is how you give an agent workflow a -type: the contract states what must be true, so the system can check that it is. +Declared inputs, outputs, and postconditions help callers understand a contract +and assess its results. Deterministic checks can establish some properties; +semantic claims may rely on an agent's assessment. A self-attestation is not +independent verification. Use the evidence and checks the requirement calls +for, and report unmet requirements or uncertainty explicitly. ## What you actually write -Declaring an outcome is concrete. A standing goal becomes a -`kind: responsibility`, the headline kind, mounted as a node whose truth is -maintained over time. You name the truth it keeps current and what counts as a -material change to it; the host does the rest. +This example states requirements for a funding view. It illustrates a standing +contract in the documented format: ```markdown --- @@ -139,21 +129,16 @@ everywhere: `fetched_at` and source request ids. Postcondition: every funding event cites a source. ``` -There is no `### Execution` here, and that absence is the point. You did not -write the steps. You declared the outcome: the truth, its shape, what matters -about it, and what must hold before it may be committed. A render figures -out the work each time the world moves. `### Maintains` is doing the load-bearing -job: it is the world-model schema, and learning to author it well is the next -page. - - -Declarative is the default, not a cage. Some steps genuinely must happen in a -specific way: a tool that must run, an order that must hold. For those, -OpenProse has an optional imperative layer (ProseScript) for pinning exactly -that, and nothing more. The rule is "declarative by default, explicit when needed," and the -explicit part stays subordinate to the declared outcome. See -[ProseScript](/prosescript). - +The postcondition requires a source for every event. The absence of +`### Execution` leaves the agent to choose its approach within the applicable +requirements. This fragment does not configure data access or an ongoing wake +source; a serving setup must provide the inputs and continuity policy needed +for the requested freshness. + +When specific actions or their order are required, express them in +[ProseScript](/prosescript) under `### Execution`. Required steps remain part of +the contract. Use `### Invariants` for applicable limits, and distinguish +stating a limit from the host's ability to enforce it. ## Where to go next @@ -161,30 +146,25 @@ explicit part stays subordinate to the declared outcome. See These docs are orientation. The canonical execution behavior lives in the -open-source `open-prose` skill in the -[`openprose/prose`](https://github.com/openprose/prose) repo; if the docs and the -skill disagree, trust the skill. - ---- - -_The conversation always ends. The responsibility shouldn't have to._ +public [`open-prose` skill](https://github.com/openprose/prose/tree/main/skills/open-prose). +Follow the syntax and semantics of the version installed for your run. diff --git a/content/docs/harness-agnostic.mdx b/content/docs/harness-agnostic.mdx index 843acd0..68dc93f 100644 --- a/content/docs/harness-agnostic.mdx +++ b/content/docs/harness-agnostic.mdx @@ -1,19 +1,18 @@ --- title: Harness-agnostic -description: OpenProse contracts describe an abstract VM. Any Prose-Complete host can run them, and the SKILL-loaded session embodies that VM. There is no parser. +description: Contracts state requirements; hosts supply tools, state, and execution capabilities. Learn the public skill interface and its implementation limits. --- # Harness-agnostic -A `.prose.md` contract does not name a host. It declares an ideal world-model -and, optionally, a fulfillment plan, in terms of an abstract VM. Anything that -can map that VM's primitives onto real capabilities can run the same contract. -This is the deliberate seam at the center of OpenProse: **the language is one -layer, the host is another**, and you author against the language. +A contract states requirements independently of a particular host. In the +public skill format, an agent follows the OpenProse VM instructions and maps +them to the host's tools. A compatible host must support the needed operations, +inputs, and permissions to carry out the contract. -This is why "harness-agnostic" is a property of the contract, not a promise from -any one runtime. The wisdom of the ancients applies: you write to an interface, -and the interface outlives any single implementation. +Reusing a contract preserves its requirements. It does not provide unavailable +tools or make different models produce identical results. Check the host's +capabilities against the work you are requesting. ## The VM primitives a host must provide @@ -29,11 +28,10 @@ and any host: | `copy_binding` | Publish a declared output through that same durable store; never publish undeclared scratch | | `check_env` | Confirm an environment variable exists without exposing its value | -A host that can do these five things can execute any OpenProse contract. The -contract never reaches past this table. It does not know whether `spawn_session` -becomes a subagent call in Claude Code, a `codex-sdk` activation, or a bounded -session inside some other host. It only knows that a render runs in isolation -with the paths it declared. +These operations define the VM interface. A particular contract can still need +data access, tools, permissions, and serving features beyond the interface +itself. The host maps `spawn_session` to its session mechanism and must honor +the declared paths and isolation requirements. The mapping is the host's job, not yours. Codex-style and Claude Code-style @@ -43,12 +41,14 @@ execute trivial single-render runs inline and must report the limitation rather than pretend. -## The same Markdown runs on any host + -Because the contract speaks only in VM primitives, the **same file** runs -unchanged across hosts. You do not maintain a Claude variant and a Codex -variant. You maintain one `.prose.md`. The host changes; the declared outcome -does not. +## Reuse Markdown across compatible hosts + +A contract can be reused across compatible hosts without rewriting its +requirements. The host changes; the conditions the work must satisfy remain. +Portability requires a compatible skill version and the capabilities used by +the contract. Concretely, a shell line like: @@ -62,14 +62,13 @@ not what the contract asks for. ## The session embodies the VM: there is no parser -This is the load-bearing idea, and it is easy to miss because it inverts the -usual assumption. OpenProse is **never parsed or interpreted**. There is no -`.prose` parser, no bytecode, no interpreter loop that walks the Markdown. +The public skill has no separate parser or bytecode +interpreter. An agent reads and interprets the Markdown instructions. Instead, a SKILL-loaded agent session **is** the VM. When a Prose-Complete host loads the `open-prose` skill and reads a contract, the session itself carries the execution semantics: it resolves the contract, spawns renders, maintains the -world-model, and signs receipts. The intelligence is the runtime. Even a compile +world-model, and records receipts. The intelligence is the runtime. Even a compile step is an agent session. The topology, the canonicalizer, and the validators are all session output, not parser output. @@ -79,9 +78,8 @@ and never parses `.prose` semantics itself. The CLI is plumbing; the SKILL-loaded session is the machine. -This is what makes the language portable without a shared runtime binary. There -is nothing to port. Any host that can host a capable agent session, and can map -the five primitives, already has everything the language needs. +This separates the authored requirements from a particular runtime binary. +The agent and host still need the capabilities required for each run. ## The language/harness seam @@ -103,7 +101,25 @@ with surprise rather than the clock. The contract you author is the same whether or not a host chooses to memoize it. One such host today is **Reactor**, the deterministic harness built alongside the language; its reference lives with the packages in the -[openprose/prose repo](https://github.com/openprose/prose#reactor-the-recommended-harness). +[openprose/prose repo](https://github.com/openprose/prose#harnesses). + +## Implementation status + +Language requirements and implemented enforcement are different. The +[public language specification at revision `770cebc9`](https://github.com/openprose/prose/blob/770cebc9e03a7150a73bd454b7a6da307595ff9d/spec/01-Language.md#part-iii--what-is-next) +records several gaps, including these facts about reference harness 0.3.3: + +- Self-driven freshness uses a fixed poll interval rather than scheduling each + facet at its `valid_until` time. +- Deterministic postcondition validators exist, but the commit gate is not + connected to the live path; commits rely on render self-attestation. +- Durable receipts do not retain all the specified failure detail. + +That specification also identifies enforcement of `### Invariants` and +cryptographic signing as gaps. A declared limit, a receipt, and verified +satisfaction are different things. Check the version and status of the host +you select before relying on those capabilities. These docs do not establish +that a newer host has closed the recorded gaps. ## Where to go next @@ -116,7 +132,7 @@ reference lives with the packages in the diff --git a/content/docs/index.mdx b/content/docs/index.mdx index d77f1e9..a82a03f 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -1,13 +1,28 @@ --- title: OpenProse -description: A declarative language for standing AI work. You declare the outcomes you want kept true, in Markdown contracts, and any Prose-Complete agent harness runs them. +description: State what an agent must accomplish, which requirements it must satisfy, and where it can choose its approach. Reuse and combine Markdown contracts. --- # OpenProse -**OpenProse is a declarative language for standing AI work.** You write Markdown contracts (`*.prose.md`) that declare an ideal world-model: the truths you want kept current. You say what must stay true, and the host session works out the model work it takes to keep it that way. When order, loops, or exact choreography genuinely matter, optional imperative **ProseScript** plans drop in. Declarative by default, imperative where you want the control. +**With OpenProse, you state what an agent must accomplish, which requirements it +must satisfy, and where it can choose its approach.** Contract authoring is +expressing intent by composing requirements. Reusable contracts provide the +building blocks; composition determines how their requirements apply together. -The language ships as a skill. Install it, and any Prose-Complete coding agent (any agent host that can spawn sessions, read and write files, and call tools: Claude Code, Codex CLI, OpenCode, and friends) can author and run contracts: +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. +ProseScript specifies required steps when their order or method matters. + + +The syntax here was checked against [skill 0.18.0, runtime contract 2](https://github.com/openprose/prose/blob/770cebc9e03a7150a73bd454b7a6da307595ff9d/skills/open-prose/SKILL.md). +Use the format supported by your installed skill. Requirements describe what +must happen; tools, permissions, continuous operation, and enforcement depend +on the selected host. See [Harness-agnostic](/harness-agnostic). + + +Install the language skill in a compatible coding agent, then provide the tools and inputs your contract needs: ```bash npx skills add openprose/prose @@ -24,14 +39,14 @@ From there, point your agent at a contract and say `prose run `. The sessi description="Install the skill, author a first contract, and run it where your agent lives." /> `. The sessi ## The shape of a contract -You author **Responsibilities**: standing goals, written as Markdown contracts. A responsibility declares what it subscribes to (`### Requires`) and the truth it keeps current (`### Maintains`): +For ongoing work, author a `responsibility`. It declares the inputs it subscribes to (`### Requires`) and the state it must maintain (`### Maintains`). This fragment assumes a separate telemetry responsibility supplies `usage`: ```markdown --- @@ -66,11 +81,13 @@ account carries a `valid_until`. Postcondition: every flagged account cites a corroborating signal. ``` -`### Maintains` is the load-bearing section: the schema of the truth this contract keeps current. [Contracts](/contracts) teaches it in depth, along with the five kinds and the rest of the authored surface. +`### Maintains` is the section that defines maintained state: the schema for the state this contract maintains. [Contracts](/contracts) teaches it in depth, along with the five kinds and the rest of the authored surface. + +The host serves the contract set using its available runtime capabilities, such as memoization, receipts, and a reconciler. The authored requirements remain the same when you change compatible hosts; successful execution still depends on the host and the required inputs. See [Harness-agnostic](/harness-agnostic) for that boundary. -How a host *serves* that contract set (memoization, receipts, a reconciler) is the host's concern, not the language's. The contract is the public artifact; it runs unchanged on any compliant host. See [Harness-agnostic](/harness-agnostic) for the seam. + -## Where the truth lives +## Source of execution rules The canonical execution behavior lives in the open-source `open-prose` skill in the [`openprose/prose`](https://github.com/openprose/prose) repo. These docs are orientation; if the docs and the skill disagree, trust the skill. diff --git a/content/docs/prosescript.mdx b/content/docs/prosescript.mdx index ae8a4e9..98232f4 100644 --- a/content/docs/prosescript.mdx +++ b/content/docs/prosescript.mdx @@ -1,14 +1,13 @@ --- title: ProseScript -description: The optional imperative pinning layer inside ### Execution. Declarative by default, explicit when needed. Contract Markdown owns the interface; ProseScript only choreographs one render. +description: Specify required steps and their order inside one render. Contract Markdown declares the interface; ProseScript describes the procedure. --- # ProseScript -Contract Markdown is declarative. You write down the world you want to keep -true, and the harness decides the graph. ProseScript is the **pinning layer**: -the optional imperative script you reach for when the *order* of work inside a -single render matters and you do not want a host to choose it for you. +Contract Markdown states requirements and interfaces. ProseScript specifies +required steps inside one render when their order or method matters. This +optional imperative layer leaves the interface in the surrounding contract. The mantra is **declarative by default, explicit when needed**. ProseScript is always secondary to the contract. It never declares what a node depends on or @@ -25,9 +24,10 @@ responsibility's `### Requires` to a producer's `### Maintains`. ## When to pin, and when not to -Use Contract Markdown when the *end state* matters and the host can pick the -graph. Use ProseScript when **order, loops, branching, retries, parallelism, or -exact call choreography** matter and you want them written down, not inferred. +Use Contract Markdown to declare requirements and dependencies. Use ProseScript +when **order, loops, branching, retries, parallelism, or exact call choreography** +are required. Those steps constrain the permitted approach; they do not replace +the requirements for the result. The Prose VM follows pinned choreography exactly. It does not infer new parallelism, reorder calls, or add missing calls. That precision is the whole @@ -364,12 +364,12 @@ pattern and binds its slots before the delegation runs. diff --git a/content/docs/setup.mdx b/content/docs/setup.mdx index f3f1aca..3e5e685 100644 --- a/content/docs/setup.mdx +++ b/content/docs/setup.mdx @@ -13,11 +13,11 @@ OpenProse runs where your agent already lives. The path is short: install the sk npx skills add openprose/prose ``` -That installs the `open-prose` skill into any Prose-Complete coding agent (Claude Code, Codex CLI, OpenCode, and friends). The skill teaches the session the language: the contract grammar, the compile behavior, and the execution semantics. There are no other dependencies. +That installs the `open-prose` skill into any Prose-Complete coding agent (Claude Code, Codex CLI, OpenCode, and friends). The skill teaches the session the language: the contract grammar, the compile behavior, and the execution semantics. The contract may still require tools, credentials, inputs, and permissions from the host. ## 2. Author your first contract -A contract is a Markdown file with `kind:` frontmatter and a handful of `###` sections. This one is complete; save it as `competitor-funding.prose.md`: +Start with what the agent must accomplish and what conditions its work must satisfy. In the public skill format, write those requirements in a Markdown file with `kind:` frontmatter and recognized `###` sections. Save this introductory example as `competitor-funding.prose.md`: ```markdown --- @@ -38,7 +38,9 @@ everywhere: `fetched_at` and source request ids. Postcondition: every funding event cites a source. ``` -A single responsibility with a `### Goal` and a `### Maintains` is a complete program. Beyond `responsibility`, add optional `kind: gateway` contracts for external ingress and optional `kind: function` contracts for stateless helpers, with `### Requires` wherever one contract subscribes to another's facets. [Contracts](/contracts) teaches the full authored surface, and [Declare outcomes](/declare-outcomes) teaches the discipline of writing the truth instead of the steps. +This example states the desired result and source-evidence requirement. Supply the tracked competitors and permitted data access in the running environment; configure a continuity policy and serving host if it must stay current over time. + +Reuse `kind: gateway` contracts for external ingress and `kind: function` contracts for stateless helpers. Use `### Requires` when a responsibility subscribes to another contract's facets. [Contracts](/contracts) teaches the format, and [Contract authoring](/declare-outcomes) explains requirements, discretion, and composition. ## 3. Run it @@ -48,13 +50,15 @@ Point your agent at the file and say: prose run competitor-funding.prose.md ``` -This is an instruction to the session, not a shell binary. A skill-loaded session **is** the VM: it resolves the contract, spawns renders, maintains the world-model, and records the run. See [Harness-agnostic](/harness-agnostic) for why there is no parser and what a host must provide. +This is an instruction to the session, not a shell binary. A skill-loaded session carries out the VM instructions: it resolves the contract, spawns renders, maintains the world-model, and records the run using the available host capabilities. See [Harness-agnostic](/harness-agnostic) for why there is no parser and what a host must provide. ## 4. Learn from the examples The fastest way to pick up the idiom is to read working contracts. The [`skills/open-prose/examples/`](https://github.com/openprose/prose/tree/main/skills/open-prose/examples) directory in the open-source repo is the tour: each example carries its contract source and a README with its standing goal. Copy a shape that resembles your problem and adapt it. Read the contract before you run it. -## Where the truth lives + + +## Source of execution rules The canonical execution behavior is the open-source [`open-prose` skill](https://github.com/openprose/prose/tree/main/skills/open-prose) itself. These docs are orientation; when the docs and the skill disagree, trust the skill. diff --git a/content/docs/typed-image.mdx b/content/docs/typed-image.mdx index 14caa67..906bed0 100644 --- a/content/docs/typed-image.mdx +++ b/content/docs/typed-image.mdx @@ -5,8 +5,8 @@ description: A pixel-only diagram is a visual source one rung above Markdown. An # Typed Image -A contract is Markdown. But Markdown is not the only thing that can carry intent -into the compiler. A **typed image** is an ordinary picture (a `.png` or +Contract authoring expresses intent through requirements. A diagram can help +an author describe those requirements and the connections between contracts. A **typed image** is an ordinary picture (a `.png` or `.svg` of boxes and labelled edges, *pixels only*, no embedded payload) that an intelligent compile step reads and turns into `*.prose.md` contracts. @@ -32,7 +32,7 @@ the exact postcondition, the freshness window. So a typed image lets the **picture own the structural skeleton** and the **text inside the boxes own the intent**. It is a schematic (think circuit -diagram or score) where labels and glyphs are load-bearing, not decoration. +diagram or score) where labels and symbols express required connections and conditions. ## A brief, not a binary @@ -40,9 +40,8 @@ Intent still lives only in the contract (Tenet 1). The resolve does not make the image a second authored surface for meaning. It **emits** `*.prose.md` that a human ratifies, and *that* Markdown carries 100% of the semantic weight, exactly as if it had been typed. The picture is a *brief*; the contract is the spec; the -compiled DAG is the binary. All of the model's interpretive latitude is -quarantined to authoring time, the rarest event in the system, and the -deterministic runtime that follows is unchanged. +compiled DAG is the binary. Review the generated requirements and connections before accepting them. +The diagram does not establish that the resulting contracts will be fulfilled. This is why the typed image is not new syntax. New capability in OpenProse is new *semantics*, never a new overlay: an image resolves down to the same five @@ -69,7 +68,7 @@ The resolve reads the image in three tiers: (subscriptions), the facet each multi-out edge carries, and the overall fan-out / diamond geometry. These must be visually unambiguous. - **Pin-or-interrupt (safety).** Freshness windows (`### Continuity`) and - load-bearing postconditions are safety-critical. A wrong freshness window is + required postconditions are safety-critical. A wrong freshness window is silent staleness or runaway spend. The resolve reads an *explicit* annotation (a clock glyph, a checklist) or **interrupts** with a `failed` receipt naming the gap. It never guesses these. @@ -93,15 +92,15 @@ The typed image is an **authoring-surface** capability of the OpenProse compile, specified in the [`open-prose` skill](https://github.com/openprose/prose/blob/main/skills/open-prose/visual-source.md) (`visual-source.md`). Resolution is an intelligent compile step, so it is generative, not deterministic. That is why its output is reviewable Markdown -you ratify before anything runs. The deterministic harness still runs ordinary -contracts. +you ratify before anything runs. The selected harness still runs ordinary +contracts, with its documented capabilities and limits.