@suss/intent-ir 0.33.1 → 0.34.0

package/README.md

@@ -2,24 +2,24 @@
 
 Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
 
-The team-authored side of the loop: what the code was *meant* to do, in a form that pairs against the derived `BehavioralSummary` of what it *does*.
+The team writes this side: what the code was *meant* to do, in a form that pairs against the derived `BehavioralSummary` of what it *does*.
 
 ## What this package is
 
-Two citizens, discriminated by `kind`, both built on `@suss/ir-core` so intent and behaviour describe boundaries the same way:
+It defines two kinds of document, told apart by `kind`. Both build on `@suss/ir-core`, so intent and behaviour describe boundaries the same way:
 
-- **System intent** (`kind: boundary`): what one boundary should do, as named outcomes. The boundary is REST, function-call, message-bus, storage or unit-invocation, and every field of one comes off the `@suss/ir-core` schema for that protocol.
-- **Outcome intent** (`kind: prd`): human `when` / `expect` scenarios, each with an optional `link` to a system-intent outcome (`<intent-name>.<outcome-id>`). A scenario with no `link` is a valid state to be in: it reads fully, and nothing has linked it to an outcome yet.
+- **System intent** (`kind: boundary`) describes what one boundary should do, as named outcomes. The boundary is REST, function-call, message-bus, storage or unit-invocation, and every field of one comes off the `@suss/ir-core` schema for that protocol.
+- **Outcome intent** (`kind: prd`) is a set of human `when` / `expect` scenarios. Each has an optional `link` to a system-intent outcome (`<intent-name>.<outcome-id>`). A scenario with no `link` is valid. It reads fully, and nobody has linked it to an outcome yet.
 
 ## Where it fits in suss
 
-It is a peer of `@suss/behavioral-ir`; both build on `@suss/ir-core`. Readers (e.g. `@suss/contract-intent`) parse files into `IntentDoc` and call `intentDocToSummary`; the checker pairs the result against derived code summaries.
+It is a peer of `@suss/behavioral-ir`, and both build on `@suss/ir-core`. Readers such as `@suss/contract-intent` parse files into `IntentDoc` and call `intentDocToSummary`. The checker then pairs the result against derived code summaries.
 
 ## Status
 
 v0: REST, function-call, message-bus, storage and unit-invocation system intent, effects as outcomes, PRD outcome intent with optional links. GraphQL, runtime-config and metric boundaries have no block yet.
 
-The file format is also published as a [JSON Schema](schema/intent-doc.schema.json), generated from the zod schemas at build time, so an editor can check a document and a tool in another language can read one without depending on this package. [Intent format](../../docs/reference/intent-format.md) goes through both document kinds field by field.
+The file format is also published as a [JSON Schema](schema/intent-doc.schema.json), generated from the zod schemas at build time. An editor can check a document against it, and a tool in another language can read one without depending on this package. [Intent format](../../docs/reference/intent-format.md) goes through both document kinds field by field.
 
 ## More