From 8e3c168252d98efd2a3ec05df1476cb65c1076f9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 17:47:55 +0000 Subject: [PATCH] Position the documentation around AI Design by Contract The README now opens with the AI workflow: rules in plain language, the contracts an agent writes from them, and the violation that names the broken rule. New sections explain why contracts matter for AI-written code, how the skill works (specification, rules, contracts, code, checker, tests, report), a quick start that installs the skill, what the agent delivers and the contract checker. The existing reference follows as "The contract language", and the old "AI coding agents" section is folded into the top. The Composer description and keywords, AGENTS.md and the CHANGELOG intro follow the same positioning. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FxhC1FD8xw9sMh2etSB3ir --- AGENTS.md | 5 +- CHANGELOG.md | 3 +- README.md | 264 +++++++++++++++++++++++++++++++++++++------------- composer.json | 10 +- 4 files changed, 213 insertions(+), 69 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6c0ea8e..0facbe5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,8 @@ Guidance for AI coding agents working on this repository. Human contributors: se ## Project -`php-deal/framework` is a Design by Contract library for PHP. Contracts are native attributes +`php-deal/framework` is an AI Design by Contract library for PHP: AI agents turn business specifications into +contracted code with the bundled Agent Skill, and the library enforces the contracts. Contracts are native attributes (`#[Verify]`, `#[Ensure]`, `#[Invariant]`, `#[Inherit]`) whose string arguments are PHP expressions. Aspects of [Go! AOP 4](https://github.com/goaop/framework) weave the annotated classes and evaluate the expressions on every call. @@ -88,6 +89,8 @@ lowest-dependencies job and `composer audit`. Global functions in expressions are written `\is_numeric(...)`, and class names fully qualified, because `use` imports do not apply inside expressions. - Keep comments short and useful. Public API classes need a class docblock that explains their purpose. +- The README leads with the AI workflow (specification โ†’ rules โ†’ contracts โ†’ code โ†’ tests). Present new features + from that angle first, then in the contract language reference. ## Testing tips diff --git a/CHANGELOG.md b/CHANGELOG.md index f74a376..41ab559 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,8 @@ All notable changes to this project are documented in this file. The format is b 2.0.0 - unreleased ------------------ -A rewrite for modern PHP. See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the migration steps. +A rewrite for modern PHP and for AI-driven development: an Agent Skill lets AI coding agents turn business +specifications into contracted code and tests. See [UPGRADE-2.0.md](UPGRADE-2.0.md) for the migration steps. ### Added diff --git a/README.md b/README.md index 36314c5..956986b 100644 --- a/README.md +++ b/README.md @@ -2,37 +2,50 @@ # PhpDeal -**Design by Contract for modern PHP** +**AI Design by Contract for PHP** -Declare preconditions, postconditions and invariants with native attributes.
-PhpDeal checks them on every call, powered by [Go! AOP](https://github.com/goaop/framework). +Your AI agent turns business specifications into code that checks its own rules.
+PhpDeal enforces those rules on every call, as native PHP attributes powered by [Go! AOP](https://github.com/goaop/framework). [![CI](https://github.com/php-deal/framework/actions/workflows/ci.yml/badge.svg)](https://github.com/php-deal/framework/actions/workflows/ci.yml) [![Latest Version](https://img.shields.io/packagist/v/php-deal/framework.svg?label=release)](https://packagist.org/packages/php-deal/framework) [![Total Downloads](https://img.shields.io/packagist/dt/php-deal/framework.svg)](https://packagist.org/packages/php-deal/framework) [![PHP Version](https://img.shields.io/badge/php-%E2%89%A5%208.4-777BB4.svg?logo=php&logoColor=white)](https://www.php.net/releases/8.4/) +[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-design--by--contract-d97757.svg)](skills/design-by-contract/SKILL.md) [![Go! AOP](https://img.shields.io/badge/Go!%20AOP-4.x-1f6feb.svg)](https://github.com/goaop/framework) [![PHPStan](https://img.shields.io/badge/PHPStan-level%2010-2a5ea7.svg)](https://phpstan.org/user-guide/rule-levels) [![License](https://img.shields.io/packagist/l/php-deal/framework.svg)](LICENSE) +You write the rules in plain language: + +> **R1.** A deposit is a positive amount.
+> **R2.** A deposit adds the amount to the balance.
+> **R3.** The balance is never negative. + +Your agent turns them into contracts, the code and the tests: + ```php use PhpDeal\Attribute\{Ensure, Invariant, Verify}; -#[Invariant('$this->balance >= 0')] +#[Invariant('$this->balance >= 0')] // R3 class Account { private float $balance = 0.0; - #[Verify('$amount > 0')] - #[Ensure('$this->balance === $__old->balance + $amount')] + #[Verify('$amount > 0')] // R1 + #[Ensure('$this->balance === $__old->balance + $amount')] // R2 public function deposit(float $amount): void { $this->balance += $amount; } } +``` + +When the code or its caller breaks a rule, PhpDeal stops the call and names the rule: +```php new Account()->deposit(-10); // PhpDeal\Exception\PreconditionViolation: // Precondition "$amount > 0" violated in Account->deposit(-10.0) @@ -40,45 +53,193 @@ new Account()->deposit(-10); ## Contents -- [Why Design by Contract?](#why-design-by-contract) +- [Why AI Design by Contract?](#why-ai-design-by-contract) +- [How it works](#how-it-works) +- [Quick start](#quick-start) +- [What the agent delivers](#what-the-agent-delivers) +- [The contract checker](#the-contract-checker) - [Features](#features) -- [Installation](#installation) -- [Setup](#setup) -- [Contracts](#contracts) - - [Preconditions: `#[Verify]`](#preconditions-verify) - - [Postconditions: `#[Ensure]`](#postconditions-ensure) - - [Invariants: `#[Invariant]`](#invariants-invariant) - - [Inheritance: `#[Inherit]`](#inheritance-inherit) -- [Writing expressions](#writing-expressions) -- [Handling violations](#handling-violations) -- [PHPStan integration](#phpstan-integration) -- [AI coding agents](#ai-coding-agents) -- [Production](#production) +- **The contract language** + - [Setup](#setup) + - [Contracts](#contracts): [`#[Verify]`](#preconditions-verify), [`#[Ensure]`](#postconditions-ensure), + [`#[Invariant]`](#invariants-invariant), [`#[Inherit]`](#inheritance-inherit) + - [Writing expressions](#writing-expressions) + - [Handling violations](#handling-violations) + - [PHPStan integration](#phpstan-integration) + - [Production](#production) - [Upgrading from 1.x](#upgrading-from-1x) - [Contributing](#contributing) -## Why Design by Contract? +## Why AI Design by Contract? + +An AI agent writes code faster than anyone can review it. The hard question is no longer *how* to implement a +feature but *whether the code does what the business asked*. The usual answers fall short: + +- **Review** does not scale to every line an agent writes. +- **Tests written by the same agent** share its reading of the requirements. When the agent misreads a rule, the + code and the tests agree with each other, and both are wrong. +- **Requirements in a ticket** are forgotten by the next change, whether a person or an agent makes it. + +[Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract) closes that gap. Every business rule becomes +an executable contract that lives next to the code it constrains: + +- **Preconditions** (`#[Verify]`) are what the caller must guarantee before a call. +- **Postconditions** (`#[Ensure]`) are what the method promises after it returns. +- **Invariants** (`#[Invariant]`) are what is always true of an object between calls. + +PhpDeal checks them on every call. That gives each party something it lacked: + +| For... | Contracts give you | +|------------------|------------------------------------------------------------------------------------------------------------| +| **You** | A one-line, reviewable statement of each rule, traced to the specification, instead of hundreds of lines of code | +| **The agent** | An immediate, exact signal: which rule broke, in which method, with which arguments. It fixes the code instead of guessing | +| **The tests** | An oracle on every call. Any test that drives the object through valid calls also checks every postcondition and invariant | +| **The next change** | Rules that stay enforced. A later edit, by a person or an agent, can not quietly break one | + +A broken contract is a bug, reported at the exact place where it happens, before a corrupt state travels through +the application. + +## How it works + +PhpDeal ships an [Agent Skill](https://agentskills.io), [`design-by-contract`](skills/design-by-contract/SKILL.md), +that teaches your coding agent the whole workflow: + +```mermaid +flowchart LR + spec[Business
specification] --> rules[Numbered
rules] + rules --> contracts[Contracts:
Verify, Ensure,
Invariant] + contracts --> code[Code] + code --> checker[Contract
checker] + checker --> tests[Tests derived
from contracts] + tests --> report[Rule table,
assumptions,
open questions] + tests -- violation --> code +``` + +1. **Extract the rules.** The agent reads the specification, numbers every rule (`R1`, `R2`, ...), and writes down + ambiguities as open questions instead of guessing. +2. **Classify them.** Each rule becomes a precondition, a postcondition or an invariant. A business error that users + see, such as *"this room is already booked"*, stays as explicit code, because contracts are usually off in + production. +3. **Write the code** with the contracts on the classes and interfaces, each one tagged with its rule ID. +4. **Check the contracts.** A bundled checker finds mistakes inside the contract strings, which neither PHP nor + PHPStan see. +5. **Derive the tests.** These cover the examples of the specification, the boundaries of every precondition, + the business errors, and random sequences of valid calls sampled from the preconditions. The contracts judge + every step. +6. **Report.** The agent ends with a table that maps each rule to its contract, its code and its test, plus the + assumptions it made and the questions for the business. + +## Quick start + +**1. Install the library** (PHP 8.4+): -[Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract) treats the public API of a class as a formal -agreement between the class and its callers: +```bash +composer require php-deal/framework +``` -- **Preconditions** are the requirements upon the caller: what must be true before a method is called. -- **Postconditions** are the promises of the method: what is true after it returns. -- **Invariants** are the properties of an object that always hold between calls. +**2. Start the contract kernel** in your test bootstrap (and in development), before your classes are loaded. See +[Setup](#setup) for all options: + +```php +use PhpDeal\ContractApplication; -If the caller meets the requirements, the class delivers the promised service. A broken contract is a bug, and -PhpDeal reports it at the exact place where it happens instead of letting a corrupt state travel through the -application. The contracts live next to the code they describe, so they double as precise, executable -documentation. +require __DIR__ . '/../vendor/autoload.php'; + +ContractApplication::getInstance()->init([ + 'debug' => true, + 'appDir' => __DIR__ . '/..', + 'cacheDir' => __DIR__ . '/../var/cache/contracts', + 'includePaths' => [__DIR__ . '/../src'], +]); +``` + +**3. Give your agent the skill.** In [Claude Code](https://claude.com/claude-code), install the plugin from this +repository: + +``` +/plugin marketplace add php-deal/framework +/plugin install php-deal@php-deal +``` + +Other agents that read the [Agent Skills](https://agentskills.io) format can load the folder +[`skills/design-by-contract`](skills/design-by-contract) directly. Composer installs it too, at +`vendor/php-deal/framework/skills/design-by-contract`, in the version that matches your library. + +**4. Hand over the specification:** + +> Implement docs/booking-spec.md with Design by Contract, and write the tests. + +In Claude Code you can also call the skill explicitly with `/php-deal:design-by-contract`. + +## What the agent delivers + +The [worked example](skills/design-by-contract/examples/inventory) shows a complete run. Our CI weaves and runs it on +every change: + +- [`SPEC.md`](skills/design-by-contract/examples/inventory/SPEC.md): nine stock-keeping rules, written for people; +- [`StockItem.php`](skills/design-by-contract/examples/inventory/StockItem.php): the class, with each contract + tagged by its rule; +- [`StockItemTest.php`](skills/design-by-contract/examples/inventory/StockItemTest.php): the tests derived from the + rules and the contracts; +- a rule table: + +| Rule | Contract or code | Where | Test | +|------|----------------------------------------------------------------------------|----------------------------|-------------------------------------------| +| R3 | `#[Invariant('$this->reserved >= 0 && $this->reserved <= $this->onHand')]` | `StockItem` | random sequences | +| R6 | `#[Verify('$quantity <= $this->available()')]` | `StockItem::reserve()` | precondition boundaries | +| R8 | `#[Ensure('$this->onHand === $__old->onHand - $quantity')]` | `StockItem::ship()` | specification example, random sequences | +| R9 | code: throws `CountBelowReserved`, a business error | `StockItem::recordCount()` | `testCountBelowTheReservationsIsRejected` | + +The random sequences are contract-based testing with no extra library. The agent samples valid arguments from the +preconditions, and every postcondition and invariant checks every step: + +```php +$random = new Randomizer(new Mt19937($seed)); +for ($step = 0; $step < 200; ++$step) { + if ($item->available() > 0) { + $item->reserve($random->getInt(1, $item->available())); // sampled from #[Verify] + } + $item->receive($random->getInt(1, 50)); +} +``` + +**Does it catch bugs?** We gave an agent with no other context a new specification (meeting-room booking) and only +the skill. It wrote 46 contracts and 46 tests. Then it planted five bugs, one at a time: an off-by-one error, a wrong +overlap check, a cancel that deleted every booking, reused ids and a broken free-slot check. Contracts caught all +five. + +## The contract checker + +Contracts are PHP expressions in strings, so neither PHP nor PHPStan see their mistakes until the method runs. The +skill bundles a checker that agents run after every edit. You can run it too, in CI or by hand: + +```bash +php vendor/php-deal/framework/skills/design-by-contract/scripts/lint-contracts.php --strict src +``` + +It reports syntax errors, misspelled variables, `$__old` or `$__result` in the wrong contract, `$this` in static +methods, class names that `use` imports do not resolve, double-quoted strings, assignments, reads of the clock or +random values, and `\in_array()` without strict comparison. ## Features +**For AI-driven development** + +- ๐Ÿค– **Agent Skill** with the full workflow from specification to tested code, installable as a Claude Code plugin + and portable to any agent that reads the Agent Skills format. +- ๐Ÿงญ **Traceable rules**: every contract carries the ID of the business rule it enforces. +- ๐Ÿงช **Tests derived from contracts**: specification examples, precondition boundaries, business errors and seeded + random sequences. +- ๐Ÿ”Ž **Contract checker** that catches mistakes in expressions before they run. +- ๐ŸŽฏ **Exact feedback**: a violation names the contract, the class, the method and the arguments, and points to the + declaring line, so the agent fixes the right place. + +**The contract engine** + - โœ… **Native PHP attributes**: `#[Verify]`, `#[Ensure]`, `#[Invariant]` and `#[Inherit]`, repeatable where it makes sense. - ๐Ÿงฌ **Contract inheritance** from parent classes and interfaces, with clear and predictable rules. - ๐Ÿ”’ **Full access to the object**: expressions run in the scope of the class and can read private state. - ๐Ÿ•ฐ๏ธ **`$__old` and `$__result`** to compare the state before and after a call, and to check return values. -- ๐ŸŽฏ **Precise exceptions**: `PreconditionViolation`, `PostconditionViolation` and `InvariantViolation`, pointing to - the method that declares the contract. - โšก **Fast**: each expression is compiled once, contracts are read once per class, and the object is cloned only when a contract uses `$__old`. - ๐Ÿ” **Recursion-safe**: an invariant may call public methods of its own class. @@ -86,16 +247,18 @@ documentation. - ๐Ÿ” **PHPStan extension** included: properties and methods used only by contracts are not reported as unused. - ๐Ÿงช **Thoroughly tested**, analysed with PHPStan at level 10 with strict rules. -## Installation +--- -```bash -composer require php-deal/framework -``` +# The contract language -PhpDeal 2 requires **PHP 8.4** or newer and is built on **Go! AOP 4**. +The rest of this document is the reference for the contracts themselves: what your agent writes and what you +review. Everything in it works without an AI as well, and contracts can be written by hand. ## Setup +PhpDeal 2 requires **PHP 8.4** or newer and is built on **Go! AOP 4**. Contracts are checked only in classes +that Go! AOP weaves, so the kernel must start before they are loaded. + Initialize the contract kernel once, as early as possible in your front controller or test bootstrap, before the classes with contracts are loaded: @@ -367,35 +530,6 @@ includes: - vendor/php-deal/framework/extension.neon ``` -## AI coding agents - -PhpDeal ships an [Agent Skill](https://agentskills.io) that teaches AI coding agents to turn a business -specification into self-checking code: it extracts the rules, maps each one to a `#[Verify]`, `#[Ensure]` or -`#[Invariant]` (or to plain code for business errors), writes the classes, checks the contract expressions and -derives PHPUnit tests from the contracts. The tests cover the examples of the specification, the boundaries of the -preconditions and random sequences of valid calls. - -In Claude Code, install it as a plugin from this repository: - -``` -/plugin marketplace add php-deal/framework -/plugin install php-deal@php-deal -``` - -Then ask for it, e.g. *"Implement docs/booking-spec.md with Design by Contract"*, or run -`/php-deal:design-by-contract`. Other agents that read the Agent Skills format can use the folder -[`skills/design-by-contract`](skills/design-by-contract) directly. It is also installed with the package, at -`vendor/php-deal/framework/skills/design-by-contract`. - -The skill bundles a checker for contract expressions, which works without an AI as well. Contracts are strings, so -neither PHP nor PHPStan see their mistakes. The checker reports syntax errors, misspelled variables, `$__old` or -`$__result` in the wrong kind of contract, `$this` in static methods, names that `use` imports do not resolve, and -more: - -```bash -php vendor/php-deal/framework/skills/design-by-contract/scripts/lint-contracts.php src -``` - ## Production Contracts are a development and testing tool: every checked call costs an expression evaluation. The usual setup is diff --git a/composer.json b/composer.json index a1278f9..4a98301 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "php-deal/framework", - "description": "Design by Contract framework for PHP: preconditions, postconditions and invariants declared with native attributes", + "description": "AI Design by Contract for PHP: AI agents turn business specifications into code with preconditions, postconditions and invariants, checked on every call", "type": "library", "keywords": [ "dbc", @@ -11,7 +11,13 @@ "invariant", "attributes", "aop", - "goaop" + "goaop", + "ai", + "ai-agents", + "agent-skills", + "claude-code", + "specification", + "contract-based-testing" ], "license": "MIT", "authors": [