From 802f1c00a3ce99e1cfe785852879f4270f133a9f Mon Sep 17 00:00:00 2001 From: mm Date: Thu, 1 Oct 2026 00:06:49 -0400 Subject: [PATCH] IMP-063: align public skill authoring with requirements composition --- .agents/plugins/marketplace.json | 2 +- .claude-plugin/marketplace.json | 4 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 11 ++- .plugin-meta.json | 6 +- CONTRIBUTING.md | 13 ++- README.md | 30 ++++--- assets/README.md | 2 +- packages/co/README.md | 17 ++-- packages/std/README.md | 5 +- .../std/ops/compose/compose.test.prose.md | 8 +- packages/std/ops/compose/tests.prose.md | 2 +- packages/std/ops/prose-author.prose.md | 5 +- skills/README.md | 2 +- skills/open-prose/SKILL.md | 11 ++- skills/open-prose/agent-onboarding.md | 12 ++- skills/open-prose/contract-markdown.md | 4 + skills/open-prose/examples/README.md | 6 ++ skills/open-prose/guidance/README.md | 6 +- skills/open-prose/guidance/authoring.md | 44 +++++++++- skills/open-prose/guidance/system-prompt.md | 88 +++++++++++-------- skills/open-prose/guidance/tenets.md | 6 +- skills/open-prose/help.md | 19 ++-- skills/open-prose/prosescript.md | 4 +- spec/00-Tenets.md | 2 +- spec/01-Language.md | 13 ++- spec/02-Harness.md | 10 +-- spec/03-AuthoringPattern.md | 16 ++-- tests/open-prose/compose/compose.test.ts | 2 +- .../open-prose/stale-docs/stale-docs.test.ts | 40 ++++++++- 30 files changed, 272 insertions(+), 120 deletions(-) diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index a8bd7a18..64ce9d5e 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -6,7 +6,7 @@ "plugins": [ { "name": "open-prose", - "description": "Write a Markdown contract (`.prose.md`). Your agent reads it, wires services, runs subagents, and leaves an auditable trace.", + "description": "State what an agent must accomplish and which requirements it must satisfy. Reuse and combine Markdown contracts.", "source": { "source": "local", "path": "./" diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 277fca33..2ecfee35 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "name": "openprose", "metadata": { - "description": "Stop scripting agents. Declare them." + "description": "Express intent by composing requirements." }, "owner": { "name": "OpenProse", @@ -11,7 +11,7 @@ { "name": "open-prose", "source": "./", - "description": "Write a Markdown contract (`.prose.md`). Your agent reads it, wires services, runs subagents, and leaves an auditable trace." + "description": "State what an agent must accomplish and which requirements it must satisfy. Reuse and combine Markdown contracts." } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b4e83656..95d33316 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "open-prose", - "description": "Write a Markdown contract (`.prose.md`). Your agent reads it, wires services, runs subagents, and leaves an auditable trace.", + "description": "State what an agent must accomplish and which requirements it must satisfy. Reuse and combine Markdown contracts.", "version": "0.18.0", "license": "MIT", "homepage": "https://github.com/openprose/prose", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 020e7d0f..2c6aab6c 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "open-prose", "version": "0.18.0", - "description": "Write a Markdown contract (`.prose.md`). Your agent reads it, wires services, runs subagents, and leaves an auditable trace.", + "description": "State what an agent must accomplish and which requirements it must satisfy. Reuse and combine Markdown contracts.", "license": "MIT", "homepage": "https://github.com/openprose/prose", "repository": "https://github.com/openprose/prose", @@ -22,10 +22,13 @@ "interface": { "displayName": "OpenProse", "developerName": "OpenProse", - "shortDescription": "Write a Markdown contract (`.prose.md`). Your agent reads it, wires services, runs subagents, and leaves an auditable trace.", - "longDescription": "OpenProse is a programming language for AI sessions. Write a Markdown contract: an agent reads it, wires the services, runs the subagents, passes artifacts through the filesystem, and leaves a durable trace under the active OpenProse root. Plain prompts are great for one-off work; they get messy when the same process needs roles, handoffs, retries, memory, or a receipt. The plugin activates on `prose ...`, on `.prose.md` files, and on requests for reusable multi-agent orchestration.", + "shortDescription": "State what an agent must accomplish and which requirements it must satisfy. Reuse and combine Markdown contracts.", + "longDescription": "Contract authoring is expressing intent by composing requirements. State what an agent must accomplish, which conditions it must satisfy, and where it can choose its approach. Reusable Markdown contracts provide the building blocks; composition determines how their requirements apply together. The public OpenProse skill supplies Contract Markdown and ProseScript instructions for a compatible agent host. Tools, permissions, execution evidence, and enforcement depend on that host. The plugin activates on `prose ...`, on `.prose.md` files, and on requests for reusable multi-agent orchestration.", "category": "Productivity", - "capabilities": ["Read", "Write"], + "capabilities": [ + "Read", + "Write" + ], "logo": "./assets/plugin/logo.png", "composerIcon": "./assets/plugin/composer-icon.png", "brandColor": "#8a6b2e", diff --git a/.plugin-meta.json b/.plugin-meta.json index 948f0b31..0795bcc6 100644 --- a/.plugin-meta.json +++ b/.plugin-meta.json @@ -1,7 +1,7 @@ { - "tagline": "Stop scripting agents. Declare them.", - "shortDescription": "Write a Markdown contract (`.prose.md`). Your agent reads it, wires services, runs subagents, and leaves an auditable trace.", - "longDescription": "OpenProse is a programming language for AI sessions. Write a Markdown contract: an agent reads it, wires the services, runs the subagents, passes artifacts through the filesystem, and leaves a durable trace under the active OpenProse root. Plain prompts are great for one-off work; they get messy when the same process needs roles, handoffs, retries, memory, or a receipt. The plugin activates on `prose ...`, on `.prose.md` files, and on requests for reusable multi-agent orchestration.", + "tagline": "Express intent by composing requirements.", + "shortDescription": "State what an agent must accomplish and which requirements it must satisfy. Reuse and combine Markdown contracts.", + "longDescription": "Contract authoring is expressing intent by composing requirements. State what an agent must accomplish, which conditions it must satisfy, and where it can choose its approach. Reusable Markdown contracts provide the building blocks; composition determines how their requirements apply together. The public OpenProse skill supplies Contract Markdown and ProseScript instructions for a compatible agent host. Tools, permissions, execution evidence, and enforcement depend on that host. The plugin activates on `prose ...`, on `.prose.md` files, and on requests for reusable multi-agent orchestration.", "targets": { "tagline": [ { "path": ".claude-plugin/marketplace.json", "pointer": "metadata.description" } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index db4c2691..c602dba6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing to OpenProse -OpenProse is a programming language for AI sessions, expressed as durable -Markdown contracts. Good contributions make agent workflows more readable, +OpenProse supports contract authoring: expressing intent by composing +requirements in Markdown. Good contributions make agent work more readable, reviewable, versioned, reusable, inspectable, and cheaper to trust over time. This repository is the open-source language, skill, standard library, and @@ -33,11 +33,10 @@ A strong OpenProse PR should: Use these when deciding whether a change belongs: -- **Markdown source defines intent.** Authored `*.prose.md` files say what must - be true; runtime and harness code should not smuggle in semantic policy. -- **Outcomes stay decoupled from implementation.** Users declare the result or - desired state; OpenProse can improve models, retries, and program structure - beneath that contract without changing the user's intent. +- **Markdown source defines intent.** Authored `*.prose.md` files state requirements; runtime and harness code should not smuggle in semantic policy. +- **Requirements remain distinct from approaches.** Users state required results, + conditions, and steps. Models, retries, and program structure may change + within those requirements without changing the user's intent. - **The skill and interpreter docs define semantics.** Contract Markdown, Forme, Prose VM, ProseScript, and Responsibility Runtime are the load-bearing language/framework surface. diff --git a/README.md b/README.md index 4337d180..01a5d5ce 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,5 @@

- OpenProse -

- -

- Standing AI jobs, declared in Markdown. + State the requirements. Reuse and combine contracts.

@@ -18,11 +14,23 @@ ## What this is -**OpenProse is a declarative language for standing AI work.** Instead of scripting a sequence of instructions and hoping the run lands where you wanted, you declare the world as it should be: an _ideal world state_, written as familiar structured **Markdown contracts** (`*.prose.md`). You say what must stay true, and the system works out how much 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. -This is the oldest good idea in software, pointed at agents. SQL, Terraform, Kubernetes, React: you declare the desired state, and a reconciler is responsible for making reality match it. A thermostat is the one-sentence version. You set the temperature you want and it holds the room there; you never tell it when to fire. +This public repository supplies the **Contract Markdown and ProseScript** +format, the `open-prose` skill, and reusable libraries. A `responsibility` +expresses requirements for state maintained over time. A `function` performs a +one-time call. ProseScript specifies required steps when their order or method +matters. See [requirements and composition](skills/open-prose/guidance/authoring.md#requirements-and-composition) +for how these fit together. -OpenProse is a language, not a platform. The contracts are plain files that run on **any Prose-Complete agent harness** (any agent host that can spawn sessions, read and write files, and call tools): the language ships as a Skill your coding agent runs directly, and any conforming harness (see [Harnesses](#harnesses)) can compile and serve the same contracts as a standing process. +Contracts are readable `*.prose.md` files. A compatible agent harness runs them +using the skill and its own tools. The requirements remain the reference for +success; execution depends on the host's inputs, capabilities, and permissions. +Serving a standing responsibility requires a host that supports continuous +operation. See [Harnesses](#harnesses) and [Honest status](#honest-status). ## Run it where your agent lives @@ -35,9 +43,9 @@ npx skills add openprose/prose That installs OpenProse into any Prose-Complete coding agent (Claude Code, Codex CLI, OpenCode, and friends). From there, point your agent at a contract and say `prose run `: the session itself embodies the VM; there is no separate binary. The [`examples/`](skills/open-prose/examples/) directory is the tour; start small and read the contract before you run it. For a new program, say `prose init`, then use `prose compose` to shape its -purpose, topology, Contract boundaries, and outside-in semantic tests. Compose +purpose, topology, contract boundaries, and outside-in semantic tests. Compose progressively materializes one directory package; use `prose write` when a -single Contract is already understood and needs focused authoring. +single contract is already understood and needs focused authoring. Your first contract is a Markdown file away: `kind: responsibility` frontmatter, a `### Goal` that states what should stay true, and the sections below. The skill teaches your agent the rest. @@ -64,7 +72,7 @@ The deep truth lives in the skill ([`skills/open-prose/`](skills/open-prose/)) a ## Nothing is held hostage -The contracts in this repo are **harness-agnostic**: OpenProse Markdown runs on any Prose-Complete agent host (a fresh `git clone` is a first-class experience). The contract is the public artifact; the deployment's secrets and data stay private. A contract and its trail can leave for any compliant host with no lost meaning. OpenProse stays free, MIT, and portable, forever. +The contracts in this repo target **compatible Prose-Complete agent hosts**. The same authored requirements can be reused with a different host that supports the required operations. A contract and its trail are portable artifacts; deployment secrets and private data need not be published with them. Portability does not imply identical model results or provide missing tools. OpenProse remains MIT-licensed. ## Harnesses diff --git a/assets/README.md b/assets/README.md index c064651c..db820028 100644 --- a/assets/README.md +++ b/assets/README.md @@ -10,7 +10,7 @@ Static assets for the OpenProse language specification repository. ## Contents -- `readme-header.png`: Header banner shown at the top of the root README. Carries the OpenProse brand hero: the wordmark, the headline, and the install command. +- `readme-header.png`: Retained legacy README banner with the former headline and install command. The root README now introduces the current requirements and composition language in text. ## Plugin assets diff --git a/packages/co/README.md b/packages/co/README.md index 7c0eb95d..40aa16a2 100644 --- a/packages/co/README.md +++ b/packages/co/README.md @@ -6,9 +6,9 @@ OpenProse-native repository. `co` sits next to `std` under `packages/`, not inside it. `std` is the low-level standard library: roles, patterns, output adapters, memory, evals, and ops primitives. `co` is an opinionated starter kit for a specific domain: -a company whose operating system is made of Prose services and systems. +a company whose operating requirements are expressed through reusable contracts. -Reference services and systems in `co` with the `co/` shorthand (analogous to +Reference contracts in `co` with the `co/` shorthand (analogous to `std/`): ```markdown @@ -36,7 +36,7 @@ packages/co/ company-repo-checker.eval.prose.md ``` -## Services and Systems +## Starter contracts - **`agent-readiness`** — narrow intake a founder can run in under a minute: scores how accessible their site is to AI agents (well-known paths, @@ -60,13 +60,12 @@ OpenProse, Inc.'s private business logic: ## std vs co — the split - **std** — use-case-agnostic primitives. Inspector, contract-grader, retry, - fan-out, worker-critic, human-gate. Things that make *Prose services and - systems work*. + fan-out, worker-critic, human-gate. Things that make *reusable Prose contracts work*. - **co** — company-operations-shaped patterns. Starter repo checkers, scheduled intake, windowed analytics, GTM pipelines, fleet monitors. - Things that make *Prose services and systems produce business value*. + Things that make *reusable Prose contracts support company operations*. -## Running Services and Systems +## Running contracts `prose run` is an agent-session command. It is not assumed to be a shell binary. If a host provides a native Prose CLI, use it. Otherwise wrap the command in an @@ -91,8 +90,8 @@ instruction the agent session interprets as the OpenProse VM. - Keep this package generic. Do not include OpenProse, Inc. leads, accounts, GTM logic, release logic, or private operating assumptions. -- Prefer composable services and systems with inline starter services until a - service earns a stable public API. +- Prefer reusable contracts with explicit requirements and interfaces. Keep + helper contracts local until they earn a stable public interface. - Put universal primitives in `std/`; put company-operating-system patterns here. - Keep generated runtime state out of this package. Useful lessons can become diff --git a/packages/std/README.md b/packages/std/README.md index cc045696..0b73588c 100644 --- a/packages/std/README.md +++ b/packages/std/README.md @@ -1,6 +1,9 @@ # OpenProse Standard Library -Reusable OpenProse functions, responsibilities, patterns, roles, delivery adapters, memory contracts, and operational tools. +Reusable contracts provide building blocks for requirements. This library +includes OpenProse functions, responsibilities, patterns, roles, delivery +adapters, memory contracts, and operational tools. Combine them through their +declared interfaces; see [contract authoring](../../skills/open-prose/guidance/authoring.md#requirements-and-composition). ## Usage diff --git a/packages/std/ops/compose/compose.test.prose.md b/packages/std/ops/compose/compose.test.prose.md index 743f9eab..6e7d8850 100644 --- a/packages/std/ops/compose/compose.test.prose.md +++ b/packages/std/ops/compose/compose.test.prose.md @@ -15,17 +15,17 @@ subject: compose - `authority_scope`: openprose-maintainer - `framework_maturity`: experimental - `request`: | - The architect previously selected an obligation-centered directory package, + The architect previously selected a directory package organized by requirements, then explored topology guidance and supplied framework feedback. Continue from the settled package decision without losing the topology findings. ### Expects -- `mental_model_sync`: identifies the obligation-centered package as settled +- `mental_model_sync`: identifies the package organized by requirements as settled - `active_frontier`: resurfaces its pending materialization before opening a new conceptual frontier -- `source_projection`: contains `index.prose.md` plus obligation-owned sibling - Contracts +- `source_projection`: contains `index.prose.md` plus sibling contracts + organized around their requirements - `test_strategy`: begins with the package promise and orders later testing through Contract boundaries, interaction topology, failure behavior, harness portability, and only then performance diff --git a/packages/std/ops/compose/tests.prose.md b/packages/std/ops/compose/tests.prose.md index e83aa3a5..5cab9bb9 100644 --- a/packages/std/ops/compose/tests.prose.md +++ b/packages/std/ops/compose/tests.prose.md @@ -93,7 +93,7 @@ iteration without freezing internal details too early. - Prefer the smallest test that rules out the largest incorrect region of the design space. - A test failure is evidence about the program first. Classify framework - pressure separately and publish it through the feedback obligation. + pressure separately and publish it through the feedback contract. - Do not encode topology as an implementation snapshot when the same promise can be tested through observable behavior. - Do not claim cross-harness portability until the same test sources have run diff --git a/packages/std/ops/prose-author.prose.md b/packages/std/ops/prose-author.prose.md index aa09cb48..b46b50e1 100644 --- a/packages/std/ops/prose-author.prose.md +++ b/packages/std/ops/prose-author.prose.md @@ -354,8 +354,9 @@ Normalize the caller's rough request into an explicit authoring intent. - Treat page, notify, create channel, publish, execute, rollback, feature flag, status update, and issue creation as side-effect signals that require an explicit sub-unit boundary and safety gate. -- Extract obligations before implementation details. Desired outputs and - invariants matter more than proposed step order. +- Extract requirements before implementation details. Desired outputs and + invariants matter more than proposed step order. Preserve any steps or + ordering the caller requires. - When the request says "always", "keep", "monitor", "every", "when event happens", or "before deadline", consider whether a responsibility plus gateway is appropriate. diff --git a/skills/README.md b/skills/README.md index 6ee6d572..95ad9658 100644 --- a/skills/README.md +++ b/skills/README.md @@ -11,4 +11,4 @@ Bundled OpenProse skill definitions shipped with the language specification repo ## Contents -- `open-prose/` — the OpenProse VM skill; defines the `*.prose.md` service/system/test/pattern contract format, Forme wiring, ProseScript, state backends, primitives, package libraries, examples, and VM guidance. This skill is the canonical definition of what the OpenProse VM is; OpenProse Cloud is the hosted execution service that implements this spec. +- `open-prose/` — the OpenProse VM skill; defines the `*.prose.md` responsibility/function/gateway/test/pattern contract format, Forme wiring, ProseScript, state backends, primitives, package libraries, examples, and VM guidance. Start with [contract authoring](open-prose/guidance/authoring.md#requirements-and-composition) to express intent through reusable requirements. The skill defines VM semantics; execution and enforcement depend on the selected host. diff --git a/skills/open-prose/SKILL.md b/skills/open-prose/SKILL.md index cd64f659..48a1af11 100644 --- a/skills/open-prose/SKILL.md +++ b/skills/open-prose/SKILL.md @@ -15,6 +15,11 @@ description: | # OpenProse Skill +Contract authoring is expressing intent by composing requirements. State what +the agent must accomplish, which conditions it must satisfy, and where it can +choose its approach. Reuse and combine contracts through the interfaces in +this skill; see [requirements and composition](guidance/authoring.md#requirements-and-composition). + OpenProse has five load-bearing pieces: | Piece | File | Role | @@ -92,7 +97,11 @@ If the user declines, drop it and don't re-propose on the same task. If they acc ### A cognitive model you can borrow -Think of OpenProse as a type system for agent workflows. A bare prompt is `any` — it runs, but nothing is checked. A contract is a typed function — inputs and outputs are declared, callers can reason about composition, and violations fail loudly. You would not write a 2,000-line TypeScript system in `any`. Multi-step agent workflows are the same. +A contract states requirements and the relevant context for applying them. +Declared inputs, results, and conditions help callers reuse it and combine it +with other contracts. Assess the result against those requirements: a completed +run or a receipt alone does not prove satisfaction. The selected host supplies +tools and enforcement; a declaration does not supply a missing capability. ### When OpenProse is the wrong answer diff --git a/skills/open-prose/agent-onboarding.md b/skills/open-prose/agent-onboarding.md index 1920262a..810dfebb 100644 --- a/skills/open-prose/agent-onboarding.md +++ b/skills/open-prose/agent-onboarding.md @@ -1,6 +1,11 @@ # OpenProse: Agent Onboarding -> Declare outcomes. Not instructions. +> State the requirements. Reuse and combine contracts. + +Contract authoring is expressing intent by composing requirements. Start with +what the agent must accomplish, which conditions it must satisfy, and the +choices it may make. See [requirements and composition](guidance/authoring.md#requirements-and-composition) +for the public skill format. ## Install @@ -16,7 +21,7 @@ CLI, OpenCode, Amp. When a `prose` command fires, you will: - Read a Markdown contract (a `responsibility` or `function` file). -- Spawn subagents to render the truths it declares. +- Spawn subagents to carry out the requirements it declares. - Pass artifacts between them through a `bindings/` boundary. - Persist the run to `/runs/{id}/` so it can be inspected later. @@ -88,7 +93,8 @@ runs only when something material moves. A `function` is the called helper tier prose run research-monitor.prose.md ``` -The contract says _what_. The runtime figures out _how_. In an agent harness, +The contract states requirements and the choices left open. The agent chooses +an approach within those requirements, including any required steps. In an agent harness, `prose run ...` is an instruction inside the agent session. From a shell, pass that instruction to a Prose Complete runner, for example: diff --git a/skills/open-prose/contract-markdown.md b/skills/open-prose/contract-markdown.md index b51594bd..eab75353 100644 --- a/skills/open-prose/contract-markdown.md +++ b/skills/open-prose/contract-markdown.md @@ -15,6 +15,10 @@ see-also: # Contract Markdown +A contract states requirements and the context needed to interpret and apply +them. [Contract authoring](guidance/authoring.md#requirements-and-composition) +explains how reusable contracts express those requirements together. + Contract Markdown is the human-facing `*.prose.md` format for OpenProse responsibilities, functions, gateways, patterns, and tests. It uses tiny YAML frontmatter for file identity, then Markdown sections for the human-facing diff --git a/skills/open-prose/examples/README.md b/skills/open-prose/examples/README.md index 4f2c6a7f..efa5f8ae 100644 --- a/skills/open-prose/examples/README.md +++ b/skills/open-prose/examples/README.md @@ -1,5 +1,11 @@ # OpenProse Examples +These examples show how to express requirements through reusable contracts. +Start with [contract authoring](../guidance/authoring.md#requirements-and-composition) +to distinguish the required result, permitted approach, and evidence of +satisfaction. The examples below exercise the public skill's standing-work +format and its declared harness behavior. + These examples are small OpenProse Native Repositories. Each one models a real standing goal as a mounted `responsibility` (the headline kind) that maintains a world-model, with cross-node helper `function`s it `call`s and a `gateway` diff --git a/skills/open-prose/guidance/README.md b/skills/open-prose/guidance/README.md index 8602d6c9..33551f52 100644 --- a/skills/open-prose/guidance/README.md +++ b/skills/open-prose/guidance/README.md @@ -1,5 +1,5 @@ --- -purpose: VM behavior guidance and canonical authoring advice for OpenProse systems +purpose: VM behavior guidance and canonical contract authoring advice for OpenProse related: - ../SKILL.md - ../examples/README.md @@ -10,10 +10,10 @@ related: # guidance Guidance documents that shape how authors write OpenProse artifacts and how -the VM interprets and executes systems. +the VM interprets and executes contracts. ## Contents - `authoring.md` — canonical guidance for responsibilities, functions, gateways, patterns, tests, the world-model, and security boundaries - `tenets.md` — architectural tenets behind the OpenProse specs (the two-layer / two-phase architecture) -- `system-prompt.md` — system-prompt text injected when the skill is active +- `system-prompt.md` — additional prompt for dedicated OpenProse VM instances; normal skill activation uses `../SKILL.md` diff --git a/skills/open-prose/guidance/authoring.md b/skills/open-prose/guidance/authoring.md index d1e3145d..0f964901 100644 --- a/skills/open-prose/guidance/authoring.md +++ b/skills/open-prose/guidance/authoring.md @@ -14,6 +14,42 @@ Use this file when writing or reviewing OpenProse author-facing artifacts: `kind: responsibility`, `kind: function`, `kind: gateway`, `kind: test`, and `kind: pattern`. +## Requirements and composition + +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 requirements and the context needed +to interpret and apply them. Reusable contracts provide the building blocks; +composition determines how their requirements apply together. + +Requirements can concern a one-time result, state maintained over time, a +required action, a limit on permissible actions, or evidence needed at +completion. An approach is a way to satisfy requirements; required steps remain +requirements when other choices are open. Completing a render, producing a +receipt, and satisfying the contract are distinct results. + +In this format, reuse a `function` by supplying its `### Parameters` and calling +it; combine responsibilities through declared `### Requires` / `### Maintains` +subscriptions; specialize a `pattern` through its slots and configuration. +For example, a report can call reusable research and review functions while +requiring source citations and review before publication. Use the documented +sections and interfaces to express those requirements together. + +Check that the combined requirements and interfaces are compatible. Surface +contradictions for resolution; do not silently discard a requirement or invent +precedence between contracts. + +Keep requirements distinguishable from supplied inputs, host capabilities, and +execution evidence. Declaring a tool or permission does not provide it. A link +alone does not create a subscription or change a contract's requirements. +Revise changed requirements explicitly in the source selected for the run; +past evidence does not establish satisfaction of a revised contract. + +This vocabulary does not add syntax, a generic type system, or new precedence +rules. The following guidance describes the public skill's existing format. +Its [implementation status](../../../spec/01-Language.md#part-iii--what-is-next) +distinguishes specified requirements from implemented harness enforcement. + Every authored file is **one render** — a contract plus the bounded session that runs it. The `kind` field is sugar over that single render atom: each kind is the same render with different or missing sections (the authored kinds in @@ -99,7 +135,7 @@ world-model, no `### Maintains`, and no `### Continuity`. - Use `### Errors` for named failures that should propagate. Do not use a catch-all error for ordinary alternate outcomes. - Use `### Invariants` for properties that remain true on success and failure. -- Use `### Strategies` for judgment guidance, not hidden fallback obligations. +- Use `### Strategies` for judgment guidance, not hidden fallback requirements. - Give functions explicit `### Shape` when boundaries matter: `self`, `delegates`, and `prohibited`. `delegates` names the helper functions this render `call`s (intra-node, ephemeral) — it is not a DAG edge. @@ -268,7 +304,7 @@ subject: summarizer - `### Expects` and `### Expects Not` are semantic assertions over the subject's world-model (responsibility) or returned value (function). Test observable behavior, not exact phrasing. -- Prefer assertions tied to contract obligations: required output existence, +- Prefer assertions tied to contract requirements: required output existence, coverage, evidence, degradation behavior, error signaling, and absence of forbidden behavior. - Assertion reports should name each assertion, pass/fail status, and concise @@ -334,9 +370,9 @@ state is its world-model. - When the task is one competent session, write one function or one responsibility; do not manufacture orchestration. -- When the outcome matters more than choreography, use Contract Markdown only. +- When requirements leave the method open, use Contract Markdown without an execution block. - When exact order, bounded loops, retries, gates, or branch logic matter, use `### Execution`. -- Make every `### Returns` / `### Maintains` item an obligation: named output, evaluable quality bar, and any degradation case. +- Make every `### Returns` / `### Maintains` item a requirement: named output, evaluable quality bar, and any degradation case. - Put caller-supplied values in `### Parameters` / `### Requires`; put runtime-provided secrets/config in `### Environment`. - Use conditional returns for graceful degradation: "if X unavailable: produce Y with caveats." - Use `### Errors` for named failures that should propagate, not for ordinary alternate outcomes. diff --git a/skills/open-prose/guidance/system-prompt.md b/skills/open-prose/guidance/system-prompt.md index 032d0e08..29df61e2 100644 --- a/skills/open-prose/guidance/system-prompt.md +++ b/skills/open-prose/guidance/system-prompt.md @@ -2,7 +2,7 @@ role: system-prompt-enforcement summary: | Strict system prompt addition for dedicated OpenProse VM instances. This - enforces that the agent executes OpenProse services and systems and embodies the VM + requires the agent to execute OpenProse contracts and embody the VM correctly. Append this to system prompts for dedicated OpenProse execution instances. --- @@ -11,14 +11,20 @@ summary: | This file is **not** part of normal skill activation. Load it only when creating or configuring a dedicated OpenProse VM instance whose sole job is to execute -OpenProse service and system files. General-purpose agents should use `SKILL.md` routing instead. +OpenProse contracts. General-purpose agents should use `SKILL.md` routing instead. This agent instance is dedicated to OpenProse execution. Accept `prose` commands -for Contract Markdown services and systems (`*.prose.md`), with ProseScript +for Contract Markdown responsibilities and functions (`*.prose.md`), with ProseScript inside `### Execution` when pinned choreography is needed. Route compile and serve through their own docs. Refuse general-purpose work and redirect it to a general agent. +Contract authoring is expressing intent by composing requirements. Follow the +applicable requirements, including required steps, and use judgment only where +they leave choices open. See [requirements and composition](authoring.md#requirements-and-composition). +Requirements do not supply missing tools or grant permissions; use the host's +available primitives and authorization boundaries. + ## Your Role You are not merely describing a virtual machine. You are the OpenProse VM: @@ -32,19 +38,23 @@ You are not merely describing a virtual machine. You are the OpenProse VM: OpenProse has two authoring surfaces: -- **Contract Markdown** (`*.prose.md`): small identity frontmatter plus `### Services`, - `### Requires`, `### Ensures`, and related sections. Load `forme.md` for - multi-service wiring, then `prose.md` for execution. +- **Contract Markdown** (`*.prose.md`): identity frontmatter and sections such as + `### Requires` / `### Maintains` for responsibilities and + `### Parameters` / `### Returns` for functions. Load `contract-markdown.md` + for the five authored kinds, `forme.md` for responsibility subscriptions, + and `prose.md` for execution. - **ProseScript** (`### Execution`): imperative choreography with `session`, `call`, `let`, `parallel`, `loop`, `try/catch`, `choice`, `block`, and `agent`. ## Core Execution Principles -1. Follow the system structure exactly where the author pinned it. +1. Follow the contract structure exactly where the author pinned it. 2. Use intelligent judgment for contract satisfaction, wiring ambiguity, and discretion conditions. -3. Spawn real subagents for sessions and service calls. +3. Spawn real subagents for sessions and function calls through the host's + `spawn_session` primitive. Follow `SKILL.md`'s Host Primitive Adapter when + that primitive is unavailable; do not silently simulate a multi-agent run. 4. Select a state backend before execution and track state through that backend. Filesystem is the default. 5. Pass large context by reference through files, not by copying whole artifacts @@ -64,8 +74,8 @@ workspace for these specification files. | File | Purpose | |------|---------| | `SKILL.md` | Command dispatcher and load map | -| `contract-markdown.md` | `*.prose.md` service and system format | -| `forme.md` | Phase 1 wiring for multi-service systems | +| `contract-markdown.md` | `*.prose.md` kinds, sections, and interfaces | +| `forme.md` | Wiring for responsibility subscriptions | | `prose.md` | Phase 2 execution semantics | | `responsibility-runtime.md` | Responsibility compile, serve, status, and reconciliation semantics | | `compiler/index.prose.md` | Bundled ProseScript compiler program | @@ -78,12 +88,17 @@ workspace for these specification files. When executing: +- Load `SKILL.md` for the current command router, format detection, and host + primitive adapter. This dedicated prompt uses those same rules. - Load `contract-markdown.md` for `*.prose.md` responsibilities and functions. - Load `forme.md` only when wiring is needed: wiring across responsibilities (matching `### Requires` → `### Maintains`), multi-node files, or patterns. -- Refuse `prose run` on `kind: pattern`; patterns must be instantiated by systems. -- Refuse `prose run` on `kind: responsibility`; responsibilities are compiled - into compiled intent and reconciled by the Responsibility Runtime. +- Run `kind: function` as a called helper using `### Parameters` / `### Returns`. +- Run `kind: responsibility` as a mounted DAG node through the current + `SKILL.md` format-detection and `prose.md` execution rules. A standalone + responsibility render still applies its compiled canonicalizer to its receipt. +- Refuse `prose run` on `kind: pattern`; patterns are instantiated at compile + time and expanded into nodes. - Refuse `prose run` on `kind: gateway`; gateways compile into trigger registrations for `prose serve`. - Route `kind: test` files through `prose test`. @@ -99,26 +114,26 @@ When executing: Do not report success for a durable `prose run` until the run satisfies the selected backend's completion shape. -For the default filesystem backend, the latest `/runs/{id}/` -directory must contain: - -- compiled Forme manifest: generated wiring graph for systems, or minimal - service activation record for one service -- `root.prose.md`: snapshot of the invoked source -- `sources/`: snapshots of referenced service, system, and pattern sources -- `vm.log.md`: append-only execution log with completion or error markers -- `bindings/`: non-empty files for every declared output +Every durable backend must write the compiled intent or minimal function +activation record, `root.prose.md`, and `sources/` required by +`state/README.md`. Use the selected backend's current layout for the ledger, +published world-model, function results, and private scratch. -SQLite and PostgreSQL preserve compiled activation manifests, `root.prose.md`, -and `sources/`, but store events and data-plane bindings in their database backends -instead of filesystem `vm.log.md`, `workspace/`, and `bindings/`. +For the default filesystem backend, `state/filesystem.md` is normative for +paths, ownership, and serialization. Responsibility runs publish the canonical +world-model and append receipts; called functions publish their declared +returns. Do not require every kind to use the same output directory. SQLite +and PostgreSQL use their documented database storage after the shared durable +envelope. A completed receipt does not by itself establish that every contract +requirement was satisfied. ## Runtime Model -Every service call becomes a real subagent invocation. The subagent receives its -own service definition, input file paths, workspace path, output obligations, +Every function call uses the host's `spawn_session` mapping, subject to the +adapter's stated capability limits. The subagent receives its +own function definition, input references, workspace, output requirements, shape constraints, and error signaling rules. It does not receive the whole -manifest or other services' private context. +manifest or other functions' private context. For ProseScript: @@ -142,12 +157,15 @@ declared output. Do: -- Execute OpenProse services and systems strictly and intelligently. -- Spawn subagents for each `session` or service `call`. +- Execute OpenProse contracts strictly and intelligently. +- Spawn subagents for each `session` or function `call` using the host adapter. - Track state through the selected backend rooted at `/runs/{id}/`. -- Publish only declared outputs from workspace to bindings. -- Evaluate `### Ensures`, `### Errors`, `### Invariants`, and tests with model - judgment rather than string matching. +- Publish only declared outputs through the selected backend; keep workspace + scratch private. +- Evaluate `### Maintains`, `### Returns`, `### Errors`, `### Invariants`, and + tests through the validation rules in `prose.md` and the selected backend. + Use model judgment for semantic requirements and documented deterministic + checks where applicable. Do not: @@ -164,11 +182,11 @@ If the user asks for non-OpenProse work in this dedicated instance: ```text This agent instance is dedicated to OpenProse execution. -I can run `prose` commands, Contract Markdown services and systems, and ProseScript scripts. +I can run `prose` commands for Contract Markdown and its embedded ProseScript. For general programming work, please use a general-purpose agent instance. ``` ## Remember -You are the VM. The invoked service or system file is the instruction set. Execute it precisely, +You are the VM. The invoked contract supplies the requirements. Execute it precisely, intelligently, and exclusively. diff --git a/skills/open-prose/guidance/tenets.md b/skills/open-prose/guidance/tenets.md index 04f30166..105841d3 100644 --- a/skills/open-prose/guidance/tenets.md +++ b/skills/open-prose/guidance/tenets.md @@ -53,13 +53,13 @@ The original blueprint proposed a clean break from ProseScript. That was wrong. --- -## 4. Obligation vocabulary, split by node-vs-call: `Maintains` and `Returns` +## 4. Requirements for nodes and calls: `Maintains` and `Returns` -Words are chosen for how *the model* reads them, and the split that matters now is **standing obligation vs. one-shot output**. A `responsibility` (a mounted node) declares `### Maintains`: a model reading "maintains the set of known-exploitable CVEs" treats it as a truth it must keep true *over time*, and the section also doubles as the world-model **schema** (type + canonicalization spec + facets + postconditions). A `function` (a called helper) declares `### Returns`: a model reading "returns the parsed advisories" treats it as the output shape of a single call — no world-model, no standing obligation. +Words are chosen for how *the model* reads them, and the split that matters now is **standing requirements vs. one-shot output**. A `responsibility` (a mounted node) declares `### Maintains`: a model reading "maintains the set of known-exploitable CVEs" treats it as a truth it must keep true *over time*, and the section also doubles as the world-model **schema** (type + canonicalization spec + facets + postconditions). A `function` (a called helper) declares `### Returns`: a model reading "returns the parsed advisories" treats it as the output shape of a single call — no world-model, no standing requirement. This is the split the old single `### Ensures` collapsed. `### Maintains` is *not* a rename of `### Ensures` — it is a richer section doing four jobs, and the folded-in `### Criteria` postconditions live there (no separate judge beat). Reading "Ensures → Maintains" as a pure rename is the false-friend trap. -**How to apply:** A standing truth maintained over time is `### Maintains` on a `responsibility`. A one-shot computed output is `### Returns` on a `function`. Prefer words the model interprets as obligations for the former, and as plain output shape for the latter. Do not put a world-model on a `function`. +**How to apply:** A standing truth maintained over time is `### Maintains` on a `responsibility`. A one-shot computed output is `### Returns` on a `function`. Prefer words the model interprets as requirements for the former, and as plain output shape for the latter. Do not put a world-model on a `function`. --- diff --git a/skills/open-prose/help.md b/skills/open-prose/help.md index 25b322eb..bea67db2 100644 --- a/skills/open-prose/help.md +++ b/skills/open-prose/help.md @@ -6,9 +6,16 @@ Load this file when a user invokes `prose help` or asks about OpenProse. ## Welcome -OpenProse is a programming language for AI sessions. You declare the truths you want kept current as responsibilities (and the helper functions they call), and the VM (this session) executes them by spawning real subagents — running a render only when a node's inputs or its own contract have materially moved. +With OpenProse, 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. Reusable contracts provide the +building blocks; composition determines how their requirements apply together. -**A long-running AI session is a Turing-complete computer. OpenProse is a programming language for it.** +The public skill uses Contract Markdown for requirements and interfaces, and +ProseScript for required steps inside a render. A `responsibility` maintains +state over time; a `function` provides a one-time call. The agent follows the +VM instructions using the selected host's capabilities. See +[requirements and composition](guidance/authoring.md#requirements-and-composition). --- @@ -33,7 +40,7 @@ Options: **After the user responds:** - **Run a contract**: Ask for the file path, then load `prose.md` and execute -- **Build something new**: Start with `prose init` / `prose compose` when the Contract system is not yet clear; use `prose write` when one Contract is already understood +- **Build something new**: Start with `prose init` / `prose compose` when the contract system is not yet clear; use `prose write` when one contract is already understood - **Keep a goal true**: Help author a `kind: responsibility`, then explain `prose compile`, `prose serve`, and `prose status` - **Learn the syntax**: Show examples from `examples/`, explain the VM model - **Improve OpenProse**: Run `std/evals/prose-contributor` on relevant run IDs; require explicit user approval before pushing or opening a PR @@ -46,7 +53,7 @@ Options: | Command | What it does | |---------|--------------| | `prose init [request...]` | Initialize an OpenProse workspace and begin its architecture | -| `prose compose [request...]` | Design and evolve the program's Contracts, relationships, and architecture | +| `prose compose [request...]` | Design and evolve the program's contracts, relationships, and architecture | | `prose compile [path] [--out

]` | Compile source into `/dist/manifest.next.json` | | `prose serve` | Serve the active IR as local cron and HTTP trigger adapters | | `prose run ` | Run a responsibility or function contract | @@ -82,9 +89,9 @@ prose compose prose write ``` -`prose compose` progressively turns the project architecture into full Contract +`prose compose` progressively turns the project architecture into full contract source while keeping unresolved regions explicit. It creates semantic tests in -order from the package promise through Contract boundaries, failure behavior, +order from the package promise through contract boundaries, failure behavior, portability, and performance. It never edits the OpenProse framework during composition; framework feedback is deduplicated and filed as a public issue when authorized, or preserved as an issue draft. diff --git a/skills/open-prose/prosescript.md b/skills/open-prose/prosescript.md index 5487e5a6..923711eb 100644 --- a/skills/open-prose/prosescript.md +++ b/skills/open-prose/prosescript.md @@ -16,7 +16,9 @@ see-also: ProseScript describes exact workflow choreography inside a single render: call this function, pass these bindings, run these branches in parallel, loop until this condition holds, and handle failures this way. Use it when order matters. -Use Contract Markdown when the end state matters and Forme can choose the graph. +Use Contract Markdown to state requirements and dependencies; use ProseScript +when specific steps are required. Pinned steps constrain the approach and remain +part of the contract alongside requirements for the result. ProseScript is the **intra-node** layer: `call` invokes a `function`, and `session`/`agent`/`resume` spawn one-off sub-agents — all ephemeral and internal diff --git a/spec/00-Tenets.md b/spec/00-Tenets.md index b34b4346..1b8a355f 100644 --- a/spec/00-Tenets.md +++ b/spec/00-Tenets.md @@ -16,7 +16,7 @@ evidence); by design it is realized where decisions are frozen — at compile, where the canonicalizer and postcondition validators are fixed, and at the commit gate, whose admissibility check keeps an inadmissible render from corrupting the truth (correctness) and whose fail-closed default makes a render -that cannot satisfy its obligations commit nothing rather than act (safety, +that cannot satisfy its requirements commit nothing rather than act (safety, Tenet 4). Below that floor the stack is the resolution rule for the safety → cost → silence trade-offs — Tenet 4's "safety outranks cost; cost outranks silence": safety is Tenet 4, cost is the spend weighed against safety diff --git a/spec/01-Language.md b/spec/01-Language.md index ba9a0d1e..a957dcdd 100644 --- a/spec/01-Language.md +++ b/spec/01-Language.md @@ -1,6 +1,6 @@ # OpenProse -###### Standing AI jobs, declared as durable Markdown contracts. +###### Requirements expressed through reusable Markdown contracts. This document is the specification of **the OpenProse Language & Framework** — the durable `*.prose.md` contract format, the skill semantics that interpret @@ -8,6 +8,13 @@ it, the model-run compiler that lowers it, and the standard library that packages reusable behavior. It is the spec for what ships **bundled as the SKILL**. +Contract authoring is expressing intent by composing requirements. Authors +state what an agent must accomplish, which conditions it must satisfy, and +where it can choose its approach. Reusable contracts provide the building +blocks; composition determines how their requirements apply together. The +[authoring guide](../skills/open-prose/guidance/authoring.md#requirements-and-composition) +explains this vocabulary for the format specified here. + The OpenProse corpus divides labor exactly, and each document maps to what ships: @@ -76,7 +83,7 @@ Part II is honest about how far the current skill has climbed toward them. - **Intelligence lives in the model, not in deterministic code (Tenet 2).** Compilation is itself model work — intelligent sessions lower a contract into its IR (the Forme topology, the per-node canonicalizer, and the postcondition - validators — deterministic where the obligation is expressible, render-attested + validators — deterministic where the requirement is expressible, render-attested where it is semantic); deterministic code only validates that IR, wires connectors, enforces boundaries, schedules, and signs. The language never grows a config format to encode what the model should decide. @@ -133,7 +140,7 @@ the Ideal must state them rather than defer: `### Requires`, `### Maintains`, current.** It does four jobs at once: it *types* the maintained truth; it carries the *canonicalization spec* (which fields are material, how they normalize) that compiles into the node's fingerprint; it declares *facets* -(below); and it states *postconditions* — the obligations a render must satisfy +(below); and it states *postconditions* — the requirements a render must satisfy before it may commit. There is no separate judge and no `### Criteria`: satisfaction folds into `### Maintains`, checked deterministically where it can be expressed as a validator and self-attested by the render where it is diff --git a/spec/02-Harness.md b/spec/02-Harness.md index b88d1b24..5bb516b9 100644 --- a/spec/02-Harness.md +++ b/spec/02-Harness.md @@ -283,14 +283,14 @@ are design defaults and live in **Architecture**, not here. is a pure predicate over the ledger. 6. **The commit gate is deterministic (`gateCommit`).** A render may commit only if its compiled postconditions pass — deterministic validators where the - obligation can be expressed as one, the render's own self-attestation of its - `### Maintains` obligations where it is semantic. A render that fails commits + requirement can be expressed as one, the render's own self-attestation of its + `### Maintains` requirements where it is semantic. A render that fails commits nothing: the prior truth stands, no downstream wakes, and a `failed` receipt records why. There is no judge and no confidence score in the commit decision. The hard guarantee — an inadmissible render cannot corrupt the truth — is the - **deterministic** validators'; where an obligation is only semantic, the + **deterministic** validators'; where a requirement is only semantic, the render's self-attestation is a *soft* gate (the render attesting its own - `### Maintains` obligations), and how honestly a + `### Maintains` requirements), and how honestly a model attests is a model-choice property measured offline, not a runtime guarantee. Negate the deterministic gate and an inadmissible render can corrupt the maintained truth — the class's correctness guarantee is void. @@ -394,7 +394,7 @@ defense is structural, not a confidence score: - **A render that cannot satisfy its postconditions commits nothing.** `gateCommit` runs the node's compiled validators deterministically; where an - obligation is semantic, the render must self-attest it. Either path failing + requirement is semantic, the render must self-attest it. Either path failing yields a `failed` receipt — the prior truth stands, the world-model is untouched, and no downstream wakes. An inadmissible render can never corrupt the maintained truth or the schedule (Tenet 4; invariant 6). diff --git a/spec/03-AuthoringPattern.md b/spec/03-AuthoringPattern.md index 45627e42..67266cf1 100644 --- a/spec/03-AuthoringPattern.md +++ b/spec/03-AuthoringPattern.md @@ -1,6 +1,12 @@ # OpenProse Authoring Pattern -###### How to write OpenProse for a conforming harness — the language layer beneath evented reconciliation. +###### How to express requirements for standing work in the public skill format. + +Contract authoring expresses intent through requirements. Reusable contracts +provide the building blocks; composition determines how their requirements +apply together. This document focuses on standing responsibilities and the +harness behavior they require. The [authoring guide](../skills/open-prose/guidance/authoring.md#requirements-and-composition) +also covers one-time calls, required steps, and evidence. The OpenProse corpus divides labor exactly, and each document maps to what ships: @@ -40,7 +46,7 @@ in its light: > already exists. What changes is doctrine: the responsibility is the > top-level authored object, the render is where the work happens (there is no > separate fulfillment system), and two contract sections (`### Maintains` and -> `### Continuity`) carry a cost-and-reconciliation obligation they did not +> `### Continuity`) carry requirements for cost and reconciliation they did not > visibly carry before. --- @@ -61,7 +67,7 @@ Forme, the canonicalizer, and the VM are the substrate, never the unit of author ``` The authoring consequence: **you do not start by writing a system. You start by -writing one sentence of durable intent and what makes it true** — a `### Goal` +stating the intended result and the requirements it must satisfy** — a `### Goal` and a `### Maintains`. A responsibility is _served_, not _run_, but that is not a limitation: "not directly runnable" means "continuously reconciled," which is the entire point. The render of a single responsibility still runs standalone @@ -152,7 +158,7 @@ There is no `### Criteria` and no judge. State what "satisfied" means as - **Deterministic where you can express it.** "The release-notes file's last commit is newer than the latest merged PR touching `src/`" compiles into a validator the harness runs at commit. If it fails, the render commits nothing. -- **Self-attested where it is semantic.** Where the obligation cannot be reduced +- **Self-attested where it is semantic.** Where the requirement cannot be reduced to a validator, the render must attest it satisfied its own `### Maintains` before it signs. `gateCommit` fails closed: no attestation, no commit. (Part II: the deterministic gate is built but currently unwired, so the live commit rides @@ -221,7 +227,7 @@ autowired service graph. upstream facet in `### Requires`; Forme matches it to A's `### Maintains` facet and draws the subscription edge. B's render wakes on A's receipt when that facet's fingerprint moves — identical to consuming a webhook. Two authoring -obligations make it safe: +requirements make it safe: - **Reference, don't embed.** B's `### Requires` names A's responsibility id / facet as a declared subscription, not a copied value. diff --git a/tests/open-prose/compose/compose.test.ts b/tests/open-prose/compose/compose.test.ts index b968924b..92a228b1 100644 --- a/tests/open-prose/compose/compose.test.ts +++ b/tests/open-prose/compose/compose.test.ts @@ -31,7 +31,7 @@ describe("prose compose", () => { expect(compose).toMatch(/`prose init` invokes it in `bootstrap`/); }); - it("is an obligation-centered directory package", () => { + it("is a directory package organized by requirements", () => { expect(composePackage).toEqual([ "index.prose.md", "compose.test.prose.md", diff --git a/tests/open-prose/stale-docs/stale-docs.test.ts b/tests/open-prose/stale-docs/stale-docs.test.ts index bdf1b930..be07dbae 100644 --- a/tests/open-prose/stale-docs/stale-docs.test.ts +++ b/tests/open-prose/stale-docs/stale-docs.test.ts @@ -213,7 +213,45 @@ describe("guidance/authoring.md — reshaped to the new kind set", () => { it("drops the legacy ### Ensures-as-obligation framing in favor of Maintains/Returns", () => { // ### Ensures retired (re-purposed, not renamed). expect(doc).not.toContain("### Ensures"); - expect(f).toMatch(/Make every `### Returns` \/ `### Maintains` item an obligation/); + expect(f).toMatch(/Make every `### Returns` \/ `### Maintains` item a requirement/); + }); +}); + +describe("dedicated VM prompt follows the current skill router", () => { + const doc = read("guidance/system-prompt.md"); + const f = flat(doc); + + it("routes responsibilities and functions while refusing direct pattern and gateway runs", () => { + expect(f).toContain("Load `SKILL.md` for the current command router"); + expect(f).toContain("Run `kind: function` as a called helper"); + expect(f).toContain("Run `kind: responsibility` as a mounted DAG node"); + expect(f).not.toContain("Refuse `prose run` on `kind: responsibility`"); + for (const kind of ["pattern", "gateway"]) { + expect(f).toContain(`Refuse \`prose run\` on \`kind: ${kind}\``); + } + expect(f).toContain("Route `kind: test` files through `prose test`"); + }); + + it("uses current interfaces and backend-specific completion rules", () => { + for (const section of ["Requires", "Maintains", "Parameters", "Returns"]) { + expect(doc).toContain(`### ${section}`); + } + expect(doc).not.toContain("### Services"); + expect(doc).not.toContain("### Ensures"); + expect(f).toContain("`state/filesystem.md` is normative for paths, ownership, and serialization"); + expect(f).toContain("Responsibility runs publish the canonical world-model and append receipts"); + expect(f).toContain("called functions publish their declared returns"); + expect(f).not.toContain("`bindings/`: non-empty files for every declared output"); + }); + + it("retains dedicated-instance, capability, pinning, privacy, and secret boundaries", () => { + expect(f).toContain("Refuse general-purpose work"); + expect(f).toContain("do not silently simulate a multi-agent run"); + expect(f).toContain("Requirements do not supply missing tools or grant permissions"); + const prohibitions = doc.slice(doc.indexOf("Do not:"), doc.indexOf("## Standard Refusal")); + expect(prohibitions).toContain("Reorder a pinned `### Execution` block"); + expect(prohibitions).toContain("Share private workspace scratch files unless the contract declares them"); + expect(prohibitions).toContain("Log or reveal environment variable values"); }); });