@stravica-ai/rcf-schemas 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to `@stravica-ai/rcf-schemas` are documented in this file.
 
 The format roughly follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0 breaking changes are signalled by a minor bump per semver 0.x convention.
 
+## 0.10.0 - 2026-10-25
+
+Minor release for rcf-lite FBS-232, the rcf-schemas slice of rcf-lite's verification flag (rcf-lite ADR-4152). rcf-lite gives every acceptance criterion a verification flag, `external` or `testOnly`, set at DEFINE and read by review, coverage and verify: `external` when an operator can observe the behaviour by running the packed artefact, installed cold, against a fixture project, and `testOnly` when the behaviour lives only in the repository's own tree, CI configuration or chain state. Under 0.9.0 the closed `$defs.acceptanceCriterion` refuses the field, so rcf-lite records the flag as an interim user-story tag until its pin moves. This release gives the flag a validated place on the criterion itself.
+
+Semver: URLs pinned at `v0.6.0`. The change is additive: one optional property on the closed `$defs.acceptanceCriterion`, and every 0.9.0-valid document keeps validating. Under `CONTRIBUTING.md` an additive change is a patch bump; the release-holder set this release at `0.10.0`.
+
+### Added
+
+- **`user-story.schema.json`**: new optional `verification` on `$defs.acceptanceCriterion`, `"enum": ["external", "testOnly"]` with a `description` and no `type` or `default` (the `determinism` shape). Any other value, including another spelling or case, `null`, a boolean, a number, an array or an object, fails on one `enum` error at the criterion's `verification`. `required` stays `["id", "description", "testable"]` and `additionalProperties` stays `false`, so an undeclared property beside the flag is still rejected. As with `disposition` and `scope`, the description leaves to the consumer whether the flag is required and what each value means for a criterion's end state.
+- **Fixtures (valid)**: `fixtures/valid/user-story/us-015-ac-verification.json` (two criteria, one `external` and one `testOnly`).
+- **Fixtures (invalid)**: `fixtures/invalid/user-story/us-026-ac-verification-bad-value.json` (`"verification": "manual"`, one `enum` error). It is also invalid under 0.9.0 (unknown property), so its case pins the new error shape.
+- **Tests**: `test/user-story.test.js` gains 10 cases: each of `external` and `testOnly` validates; a criterion without the field validates (rcf-lite AC-19501-4); thirteen values outside the enum (`External`, `TESTONLY`, `testonly`, `test-only`, `internal`, `manual`, `deployed`, the empty string, `null`, `true`, `1`, `["external"]` and `{}`) are each rejected on `enum` alone; an undeclared `verificationMode` is rejected on `additionalProperties`, alone and beside a valid `verification`; the flag alongside every other optional criterion field, supersession included, validates; the schema file read directly declares the enum as exactly `["external", "testOnly"]`, keeps `required` unchanged and keeps `additionalProperties: false` (rcf-lite AC-19501-6); and one case per new fixture. Total suite grows from 465 to 475.
+- **`docs/user-story.md`**: the AC field table gains the `verification` row.
+
+### Migration
+
+- **Existing chains on 0.9.0**: nothing changes. The field is optional, and no existing document gains or loses validity (see Notes). A criterion may now carry `"verification": "external"` or `"verification": "testOnly"`.
+- **Consumers to bump**: `rcf-lite` (pins the schemas package exact; bump the pin to `0.10.0`). Requiring the flag on new or amended criteria, and what each value means for a criterion's end state, are rcf-lite rules this repo does not touch. Once a criterion carries the field, a consumer still pinned to 0.9.0 rejects the document on `additionalProperties`.
+
+### Notes
+
+- Scripted drift report at authoring time: every fixture at main `906b668` (0.9.0: 73 valid + 107 invalid = 180), in its original bytes, validated against the 0.10.0 schemas keeps its outcome and its exact ajv error list: zero drift.
+- Mutation check at authoring time: the 0.10.0 tests and fixtures run against the 0.9.0 `user-story.schema.json` fail 9 of 475: both value cases, the out-of-enum case (each value fails on `additionalProperties` instead of `enum`), the undeclared property beside a valid `verification` (two `additionalProperties` errors instead of one), the alongside case, the schema-file case, both fixture cases, and the existing `valid fixtures: user-story` runner, which fails only because `us-015` is invalid there. The absent-field case and the undeclared-property case pass on both.
+- `back-compat-freeze.test.js` continues to pass.
+
+## 0.9.0 - 2026-10-19
+
+Minor release for the rcf-lite FBS-220 supersession round and the FBS-218 gate 4 schema findings. It folds in the 0.8.1 draft, which was never published, and adopts decision 1 from that draft. A retired acceptance criterion can now carry a durable, validating record of what replaced it: `supersededBy` (an AC id), `supersededOn` (a date) and `supersessionNote` (why), which travel together. In the FBS-220 round `rcf define update AC-16505-2 --set supersededBy=...` failed validate because the criterion had no such field and `disposition` accepts only `fixed | template`. A probe must now carry at least one response assertion: a probe with only `path` (optionally `method` or `parityEnv`) asserts nothing, rcf-lite already refuses one at runtime (finding BH-1 on FBS-218), and the schema now states the same contract for every consumer. Three further findings were analysed in the same pass and are recorded under Decisions; none of them changes a schema.
+
+Semver: URLs pinned at `v0.6.0`. The supersession fields are additive (three optional properties on the closed `$defs.acceptanceCriterion`, bound to each other by `dependentRequired`) and on their own were drafted as the patch `0.8.1`. The probe rule is a narrowing: a user story whose probe carries no assertion validated under 0.8.0 and is rejected under 0.9.0. Under this repo's rule (`CONTRIBUTING.md` and the `README.md` Versioning section) a narrowing is a minor bump, as 0.8.0 did for the non-whitespace rule and 0.5.0 for the `testPointer` tightening, so the combined release ships as `0.9.0`. No `0.8.1` was tagged or published; its content ships here.
+
+### Breaking
+
+- **`user-story.schema.json`**: `$defs.acProbe` gains an `anyOf` of four arms, `{ "properties": { "<field>": true }, "required": ["<field>"] }` for `expectStatus`, `expectHeader`, `expectBody` and `selector`. A probe with none of the four fails with one `required` error per arm and one `anyOf` error, five errors at the probe's instance path. `path` (the request target), `method` (the verb) and `parityEnv` (the environment scope) are not assertions. Each arm declares its property locally because the test loader runs ajv `strictRequired`. The rule counts presence only: an assertion that is present but malformed (for example `expectBody: {}`) fails on its own constraint, not on `anyOf`.
+- **Fixture and test results that changed.** These are the only changes the scripted drift report finds (see Notes):
+  - `fixtures/valid/user-story/us-007-ac-probe-minimal.json`: its 0.8.0 bytes go from valid to invalid (five errors). It was a path-only probe, exactly the vacuous probe the rule exists to reject, so the flip is the intended effect, not drift to avoid. Rewritten in place as the smallest probe that still asserts (`path` plus `expectStatus: 200`), valid. The path-only shape moves to the new invalid fixture `us-025`.
+  - `fixtures/invalid/user-story/us-009-ac-probe-unknown-property.json`: still invalid, but on six errors instead of one (the five `anyOf` errors plus the original `additionalProperties` on `timeoutMs`), because its probe is also path-only. Bytes unchanged; the 0.7.1 note that each probe fixture fails on exactly one ajv error no longer holds for it, and its six-error list is now pinned by a test.
+  - Test `user-story: AC with a minimal probe (path only) validates` (0.7.1) encoded path-only as valid. It is now `user-story: AC with a path-only probe is rejected on anyOf (a probe requires at least one assertion)`, pinning the five errors, next to a new `user-story: AC with a minimal probe (path and expectStatus) validates`.
+  - Test `user-story: probe accepts every method in the enum` (0.7.1) paired each method with a path-only probe and would now fail. Each case now carries `expectStatus: 200`, so the loop still tests the method enum alone.
+
+### Added
+
+- **`user-story.schema.json`**: new optional `supersededBy` on `$defs.acceptanceCriterion` (`$ref` to the shared `acId`, so `AC-101-1` and `AC-201` both validate and a REQ or lowercase id does not). Presence marks the criterion as retired: it stays in the record as history and consumers stop treating it as live.
+- **`user-story.schema.json`**: new optional `supersededOn` (string, `format: date`, `YYYY-MM-DD`, the `vendorCitation.verifiedOn` shape) and `supersessionNote` (min-length-1 string with `"pattern": "\\S"`, the 0.8.0 non-whitespace rule) on the same def.
+- **`user-story.schema.json`**: `dependentRequired` on `$defs.acceptanceCriterion`: `supersededBy` requires `supersededOn` and `supersessionNote`, and each of those requires `supersededBy`. All three or none; a partial set fails with one `dependentRequired` error per missing field, naming it in `params.missingProperty`.
+- **Fixtures (valid)**: `fixtures/valid/user-story/us-014-ac-superseded.json` (a `fixed`-disposition criterion superseded by its live sibling, which keeps its `disposition`).
+- **Fixtures (invalid)**: `fixtures/invalid/user-story/us-019-ac-superseded-by-missing-note.json`, `us-020-ac-superseded-by-missing-date.json`, `us-021-ac-supersession-note-without-superseded-by.json` (each one `dependentRequired` error), `us-022-ac-superseded-by-not-an-ac-id.json` (`REQ-303`, one `pattern` error), `us-023-ac-superseded-on-bad-date.json` (`17/10/2026`, one `format` error), `us-024-ac-supersession-note-whitespace.json` (two spaces and a newline, one `pattern` error). Each is also invalid under 0.8.0 (unknown property), so the cases pin the new error shape.
+- **Tests**: `test/user-story.test.js` gains 21 cases: back-compat without the fields; the full record; the flat AC id form; the record alongside every other optional AC field; missing note, missing date, and the FBS-220 regression (`supersededBy` alone, both missing fields named); date or note without `supersededBy`; five non-AC ids rejected on `pattern`; four non-dates rejected on `format`; ten whitespace-only notes rejected on `pattern` and an empty note on `minLength`; `disposition: "superseded"` still rejected on `enum`; a `status` field on a criterion still rejected on `additionalProperties`; self-supersession validating at schema level (a consumer rule, pinned so the limit is visible); and one case per new fixture.
+- **`docs/user-story.md`**: the AC field table gains the three fields and a paragraph on why supersession is not a `disposition` value.
+- **Fixtures (invalid)**: `fixtures/invalid/user-story/us-025-ac-probe-path-only.json`, the path-only probe that `us-007` carried from 0.7.1 to 0.8.0, with a `title` naming the rule. It fails on the `anyOf` rule alone (five errors, one reason) and validates under 0.8.0, so it exercises the new constraint alone.
+- **Tests**: `test/user-story.test.js` gains 11 cases for decision 1: a minimal probe (`path` plus `expectStatus`) validates; `path` with each of the four assertion fields alone validates; `path` with `method` and `parityEnv` but no assertion is rejected with the five-error shape; a path-only probe is rejected for every method in the enum; a present but malformed `expectBody` fails on `minProperties`, not on `anyOf`; and one case each for `valid/us-007` (rewritten), `invalid/us-025` and `invalid/us-009` (its six-error list). Total suite grows from 433 to 465: 21 supersession cases and 11 decision 1 cases.
+
+### Changed
+
+- **`user-story.schema.json`**: the `description` of `$defs.acProbe`, `path` and `parityEnv` now says a probe needs an assertion and that `path` and `parityEnv` are not assertions (`path` was described as "The only required field").
+- **Tests hardened, results unchanged**: four 0.7.1 rejection cases used a path-only probe, so under 0.9.0 each would also fail on `anyOf` and no longer prove its own constraint. Each now carries `expectStatus: 200` and pins its single error: lowercase `method` (`enum`), empty `path` (`minLength`), unknown `timeoutMs` (`additionalProperties`) and empty `parityEnv` (`minLength`). They pass against both 0.8.0 and 0.9.0.
+
+### Decisions
+
+1. **Probe requires at least one response assertion: adopted.** The rule is right: a probe with only `path` asserts nothing, and rcf-lite already refuses one at runtime (`PROBE_ASSERTION_FIELDS` in `packages/rcf-lite/src/verify/engine/catalog.js`, gate finding BH-1, which resolves it to a fail with `missing assertion`), so the schema states the same contract for every consumer instead of leaving it to one resolver. The 0.8.1 draft held the rule because it cannot ship with zero fixture drift. The release-holder adopted it on 2026-10-19: the drift is the point, since `us-007` is an example of exactly the vacuous probe the rule rejects and `us-009` is the same shape with an unknown property added. Keeping the runtime check as the only enforcement was rejected. Shape and the named drifts are under Breaking above.
+2. **Match-anything regexes: runtime, not schema.** Nothing is added to the schema. Whether a pattern matches every body is a property of the regex, not of its spelling: a denylist of `.*`, `^.*$`, `[\s\S]*`, `.+`, `^`, `$` and `(?:)` is evaded by `.*?`, `(.*)`, `.{0,}`, `\S*`, `x?`, `a|`, `[^]*` and `.`, so a schema `pattern` or `not.enum` would advertise a guarantee it cannot give. It also could not apply to `expectHeader.match`, which rcf-lite resolves as a substring (`value.includes(match)`), not a regex, so `.*` there is a literal and not vacuous. **Rule for rcf-lite's verify engine:** before resolving `expectBody.matches`, compile the source and test it against two fixed canary strings from disjoint character classes, one of word characters only (for example `qzvxjk0729`) and one of non-word, non-space punctuation only (for example `~!@#%^&*()`). A pattern that matches both asserts nothing about the body: resolve the criterion as a fail with `failedExpectation: "expectBody.matches"` and an expected value naming the vacuity, never a pass; a source that does not compile is also a fail. Every spelling above, named or evasive, matches both canaries; `^\{"notes":\[`, `<h1>\s*Notes\s*</h1>`, `Hello, \w+`, `\w+`, `[0-9a-f]{8}`, `^$` and plain text match neither or one and pass the check. Fixed canaries keep the deterministic mode deterministic. If `expectHeader.match` ever becomes a regex, the same rule applies to it.
+3. **Criterion-level supersession: `supersededBy` plus a required dated note (option a).** Extending `disposition` with `superseded` (option b) was rejected because `disposition` records who owns the criterion (blueprint or applying agent), a separate axis from whether it is live: a `fixed` criterion that is superseded would lose its owner marker. Both (option c) would give two sources of truth that can disagree. `supersededBy` matches the field the FBS-220 round already reached for and the ADR record's own `supersededBy`. A single successor id is carried; a criterion split in two names its primary successor and the note names the other, and widening to a list later is additive.
+4. **Packed-artefact profile on VerifyReport v1: not in this repo.** The VerifyReport v1 shape (`schemaVersion: '1'`, `profile`) is defined in rcf-lite (`packages/rcf-lite/src/verify/report/index.js` and `src/verify/profile/index.js`); rcf-schemas carries no verify-report schema. Nothing is added here; the rcf-lite suite-as-probe DEFINE picks up the `packagedArtefact` profile and the `artefact` object.
+
+### Migration
+
+- **Existing chains on 0.8.0**: bump `@stravica-ai/rcf-schemas` to `0.9.0`. A document is rejected only when a probe carries none of `expectStatus`, `expectHeader`, `expectBody` or `selector`: add the assertion the criterion actually makes (for a health check, `expectStatus: 200`), or remove the probe so the criterion stays critique-only. The three supersession fields are optional and unknown to pre-0.9.0 callers.
+- **To retire a criterion**: set all three in one write, for example `rcf define update AC-16505-2 --set supersededBy=AC-16505-4 --set supersededOn=2026-10-17 --set supersessionNote="..."`. Setting `supersededBy` alone fails validate by design and names both missing fields.
+- **Consumers to bump**: `rcf-lite` (pins the schemas package exact; bump the pin to `0.9.0`). For decision 1, the runtime refusal in `catalog.js` is now duplicated by the schema, so a path-only probe is rejected wherever rcf-lite validates a user story against `$defs.acProbe`; `catalog.js` may keep its check as belt and braces for any probe that reaches verify without passing schema validation. Any rcf-lite fixture or test that carries a path-only probe flips with the pin and needs an assertion. What rcf-lite must also do, none of which this repo touches: (1) `rcf audit coverage --strict` treats a criterion carrying `supersededBy` as retired: it requires no bound test and leaves the coverage denominator, and a test still bound to it is reported, not counted; (2) the cross-record rules the schema cannot express: the successor exists in the same chain and is not the criterion itself, and following `supersededBy` from any retired criterion ends at a live one (no cycle); (3) deterministic verify skips a retired criterion's probe rather than resolving it; (4) the decision 2 canary rule in the verify engine.
+
+### Notes
+
+- Scripted drift report at authoring time: every fixture at main `2341f24` (0.8.0: 72 valid + 100 invalid = 172) and every fixture at the 0.8.1 draft head `973b8fb` (73 valid + 106 invalid = 179), in their original bytes, validated against the 0.9.0 schemas. Exactly two change outcome or error list: `valid/user-story/us-007` (valid to invalid) and `invalid/user-story/us-009` (one error to six). Every other fixture keeps its outcome and its exact ajv error list. The supersession fields alone produced zero drift on the 172.
+- Mutation check at authoring time: the 0.9.0 tests and fixtures run against the 0.8.1 draft schemas (`973b8fb`) fail 6 of 465: the five decision 1 rejection cases (path-only, path-only per method, path with `method` and `parityEnv`, and the `us-025` and `us-009` fixture pins) and the existing `invalid fixtures: user-story` runner, which fails only because the new `us-025` validates there. Run against the 0.8.0 schemas they fail 27 of 465: those 6, the 20 supersession cases that depend on the new fields, and the existing `valid fixtures: user-story` runner on `us-014`. Every acceptance case, every hardened case and every other pre-existing case passes on both.
+- `docs/user-story.md` labels the three supersession rows 0.9.0 and still does not describe `probe` (deferred at 0.7.1).
+- `back-compat-freeze.test.js` continues to pass.
+
 ## 0.8.0 - 2026-10-16
 
 Minor release for rcf-lite FBS-218 (per-AC probe catalog, rcf-lite PR 370), review gate 3. A probe `{ "path": "/", "expectBody": { "contains": " " } }` validated under 0.7.1, because `minLength: 1` counts a single space, and a deterministic verify run resolved it to a vacuous pass. Every assertion string on the probe must now contain at least one non-whitespace character: `"pattern": "\\S"` alongside the existing `minLength: 1`.

package/docs/user-story.md

@@ -47,6 +47,12 @@ Each AC inside `acceptanceCriteria[]`:
 | `ownerRef` | object: `{tacId?, adrId?, field?}` | no | 0.6.2. Back-reference naming the owning TAC or ADR the criterion observes rather than restating. `tacId` and `adrId` re-use the shared id patterns; `field` is an optional dotted path into the owning record (for example, `interfaces.principal.fields` or `decision.retryPolicy`) pinpointing the surface. All sub-fields optional at schema level so the record composes additively; consumers may require at least one of `tacId` or `adrId` when the criterion references an owning artefact. `additionalProperties: false`. |
 | `disposition` | enum: `fixed`, `template` | no | 0.6.2. Marks whether the criterion is the blueprint's to fix (mechanism-invariant, inherited unchanged by every applying project) or the applying agent's to set (project-parameterised, shape-given and value-open). Optional at schema level; consumer rulesets that gate blueprint contributions may require it on every AC of a shipped blueprint. Absence carries no default: a consumer that requires the marker treats an unmarked AC as a defect, and a consumer that does not require it ignores the absence. |
 | `vendorCitation` | object: `{url, verifiedOn}` | no | 0.6.2. Vendor citation for a criterion whose truth rests on a third-party platform fact. Both sub-fields required when the object is present: `url` is the vendor documentation URL (JSON Schema `format: uri`); `verifiedOn` is the ISO-8601 date (`format: date`, `YYYY-MM-DD`) the fact was verified against that URL. Consumers may fetch the URL at gate time so a dead link is a finding, and may compare `verifiedOn` against a tolerance window. `additionalProperties: false`. |
+| `supersededBy` | `acId` | no | 0.9.0. Id of the criterion that replaces this one. Presence marks the criterion as retired: it stays in the record as history, and consumers stop treating it as live (a coverage audit does not require a bound test for it). Requires `supersededOn` and `supersessionNote`. That the successor exists in the chain, is not this criterion and forms no cycle are cross-record rules for the consumer. |
+| `supersededOn` | string, `format: date` | with `supersededBy` | 0.9.0. ISO-8601 date (`YYYY-MM-DD`) the criterion was superseded. Valid only alongside `supersededBy`. |
+| `supersessionNote` | string, min 1, at least one non-whitespace character | with `supersededBy` | 0.9.0. Why the criterion was retired and how its successor covers it (for example the decision id that ruled the change). Valid only alongside `supersededBy`. |
+| `verification` | enum: `external`, `testOnly` | no | 0.10.0. How the criterion is verified: `external` when an operator can observe the behaviour by running the packed artefact, installed cold, against a fixture project; `testOnly` when the behaviour lives only in the repository's own tree, CI configuration or chain state. Optional at schema level. Absence carries no default at schema level: whether a consumer requires the flag, and what each value means for a criterion's end state, are the consumer's rules. Written by rcf-lite, which sets it at DEFINE (rcf-lite ADR-4152). |
+
+The three supersession fields travel together (`dependentRequired`): all three or none, and a partial set is rejected. Supersession is deliberately not a `disposition` value, because `disposition` records who owns the criterion (blueprint or applying agent), a separate axis from whether it is still live; a blueprint-fixed criterion can be superseded and keeps its `disposition`.
 
 The Given/When/Then triple is optional at the schema level so non-Gherkin teams aren't forced into it; the `testable` boolean is required to make authors stop and confirm the AC can actually be tested.
 

package/fixtures/invalid/user-story/us-019-ac-superseded-by-missing-note.json

@@ -0,0 +1,29 @@
+{
+  "usId": "US-303",
+  "prdId": "PRD-100",
+  "reqId": "REQ-303",
+  "version": "1.1.0",
+  "status": "draft",
+  "title": "Supersession without a note is rejected",
+  "asA": "author retiring a criterion",
+  "iWant": "a supersession record that validates",
+  "soThat": "a retired criterion cannot lose its successor, date or reason",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-303-1",
+      "description": "supersededBy and supersededOn without supersessionNote.",
+      "testable": true,
+      "scope": "deployed",
+      "supersededBy": "AC-303-2",
+      "supersededOn": "2026-10-17"
+    },
+    {
+      "id": "AC-303-2",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-020-ac-superseded-by-missing-date.json

@@ -0,0 +1,29 @@
+{
+  "usId": "US-303",
+  "prdId": "PRD-100",
+  "reqId": "REQ-303",
+  "version": "1.1.0",
+  "status": "draft",
+  "title": "Supersession without a date is rejected",
+  "asA": "author retiring a criterion",
+  "iWant": "a supersession record that validates",
+  "soThat": "a retired criterion cannot lose its successor, date or reason",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-303-1",
+      "description": "supersededBy and supersessionNote without supersededOn.",
+      "testable": true,
+      "scope": "deployed",
+      "supersededBy": "AC-303-2",
+      "supersessionNote": "A pagination ruling caps the list at 25; AC-303-2 carries the bound."
+    },
+    {
+      "id": "AC-303-2",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-021-ac-supersession-note-without-superseded-by.json

@@ -0,0 +1,28 @@
+{
+  "usId": "US-303",
+  "prdId": "PRD-100",
+  "reqId": "REQ-303",
+  "version": "1.1.0",
+  "status": "draft",
+  "title": "A supersession note without a successor is rejected",
+  "asA": "author retiring a criterion",
+  "iWant": "a supersession record that validates",
+  "soThat": "a retired criterion cannot lose its successor, date or reason",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-303-1",
+      "description": "supersessionNote without supersededBy.",
+      "testable": true,
+      "scope": "deployed",
+      "supersessionNote": "A pagination ruling caps the list at 25; AC-303-2 carries the bound."
+    },
+    {
+      "id": "AC-303-2",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-022-ac-superseded-by-not-an-ac-id.json

@@ -0,0 +1,30 @@
+{
+  "usId": "US-303",
+  "prdId": "PRD-100",
+  "reqId": "REQ-303",
+  "version": "1.1.0",
+  "status": "draft",
+  "title": "Supersession pointing at a non-AC id is rejected",
+  "asA": "author retiring a criterion",
+  "iWant": "a supersession record that validates",
+  "soThat": "a retired criterion cannot lose its successor, date or reason",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-303-1",
+      "description": "supersededBy names a requirement, not a criterion.",
+      "testable": true,
+      "scope": "deployed",
+      "supersededBy": "REQ-303",
+      "supersededOn": "2026-10-17",
+      "supersessionNote": "A pagination ruling caps the list at 25; AC-303-2 carries the bound."
+    },
+    {
+      "id": "AC-303-2",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-023-ac-superseded-on-bad-date.json

@@ -0,0 +1,30 @@
+{
+  "usId": "US-303",
+  "prdId": "PRD-100",
+  "reqId": "REQ-303",
+  "version": "1.1.0",
+  "status": "draft",
+  "title": "Supersession with a malformed date is rejected",
+  "asA": "author retiring a criterion",
+  "iWant": "a supersession record that validates",
+  "soThat": "a retired criterion cannot lose its successor, date or reason",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-303-1",
+      "description": "supersededOn is not an ISO-8601 date.",
+      "testable": true,
+      "scope": "deployed",
+      "supersededBy": "AC-303-2",
+      "supersededOn": "17/10/2026",
+      "supersessionNote": "A pagination ruling caps the list at 25; AC-303-2 carries the bound."
+    },
+    {
+      "id": "AC-303-2",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-024-ac-supersession-note-whitespace.json

@@ -0,0 +1,30 @@
+{
+  "usId": "US-303",
+  "prdId": "PRD-100",
+  "reqId": "REQ-303",
+  "version": "1.1.0",
+  "status": "draft",
+  "title": "Supersession with a whitespace-only note is rejected",
+  "asA": "author retiring a criterion",
+  "iWant": "a supersession record that validates",
+  "soThat": "a retired criterion cannot lose its successor, date or reason",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-303-1",
+      "description": "supersessionNote is two spaces and a newline.",
+      "testable": true,
+      "scope": "deployed",
+      "supersededBy": "AC-303-2",
+      "supersededOn": "2026-10-17",
+      "supersessionNote": "  \n"
+    },
+    {
+      "id": "AC-303-2",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-025-ac-probe-path-only.json

@@ -0,0 +1,24 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Path-only probe is rejected: a probe requires at least one assertion (acProbe anyOf, 0.9.0)",
+  "asA": "operator running deterministic verify",
+  "iWant": "a probe to carry at least one of expectStatus, expectHeader, expectBody or selector",
+  "soThat": "a probe that only names a path cannot resolve to a vacuous pass",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "Probe names a path and asserts nothing about the response (the 0.7.1 to 0.8.0 us-007 shape, rcf-lite FBS-218 finding BH-1).",
+      "testable": true,
+      "scope": "deployed",
+      "probe": {
+        "path": "/healthz"
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-026-ac-verification-bad-value.json

@@ -0,0 +1,21 @@
+{
+  "usId": "US-202",
+  "prdId": "PRD-100",
+  "reqId": "REQ-202",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Verification outside the enum is rejected",
+  "asA": "author",
+  "iWant": "verification to be one of external or testOnly",
+  "soThat": "the flag is unambiguous for a consumer that gates on it",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-202-1",
+      "description": "Verification is neither external nor testOnly.",
+      "testable": true,
+      "verification": "manual"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-25T00:00:00Z"
+}

package/fixtures/valid/user-story/us-007-ac-probe-minimal.json

@@ -6,19 +6,20 @@
   "status": "approved",
   "title": "Health endpoint answers on the deployed URL",
   "asA": "operator running deterministic verify",
-  "iWant": "an acceptance criterion to carry the smallest possible probe",
+  "iWant": "an acceptance criterion to carry the smallest probe that still asserts something",
   "soThat": "rcf verify run resolves it without a critique pass",
   "acceptanceCriteria": [
     {
       "id": "AC-301-1",
-      "description": "The health endpoint answers on the deployed URL.",
+      "description": "The health endpoint answers 200 on the deployed URL.",
       "testable": true,
       "scope": "deployed",
       "probe": {
-        "path": "/healthz"
+        "path": "/healthz",
+        "expectStatus": 200
       }
     }
   ],
   "createdAt": "2026-01-01T00:00:00Z",
-  "updatedAt": "2026-10-16T00:00:00Z"
+  "updatedAt": "2026-10-19T00:00:00Z"
 }

package/fixtures/valid/user-story/us-014-ac-superseded.json

@@ -0,0 +1,31 @@
+{
+  "usId": "US-303",
+  "prdId": "PRD-100",
+  "reqId": "REQ-303",
+  "version": "1.1.0",
+  "status": "approved",
+  "title": "Notes list paginates",
+  "asA": "author retiring a criterion",
+  "iWant": "a retired criterion to keep a durable record of its successor",
+  "soThat": "coverage stops asking for a test on it and the history stays auditable",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-303-1",
+      "description": "The notes list renders every note.",
+      "testable": true,
+      "scope": "deployed",
+      "disposition": "fixed",
+      "supersededBy": "AC-303-2",
+      "supersededOn": "2026-10-17",
+      "supersessionNote": "A pagination ruling caps the list at 25; AC-303-2 carries the bound."
+    },
+    {
+      "id": "AC-303-2",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-19T00:00:00Z"
+}

package/fixtures/valid/user-story/us-015-ac-verification.json

@@ -0,0 +1,28 @@
+{
+  "usId": "US-304",
+  "prdId": "PRD-100",
+  "reqId": "REQ-304",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Criteria carry their verification flag",
+  "asA": "test-author writing criteria at DEFINE",
+  "iWant": "each criterion to say whether it is verified from the packed artefact or by the repository's own tests",
+  "soThat": "review, coverage and verify read a validated field, not a convention in prose",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-304-1",
+      "description": "The notes list renders the 25 most recent notes.",
+      "testable": true,
+      "scope": "deployed",
+      "verification": "external"
+    },
+    {
+      "id": "AC-304-2",
+      "description": "The notes repository's CI runs the full suite on every pull request.",
+      "testable": true,
+      "verification": "testOnly"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-25T00:00:00Z"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/rcf-schemas",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "JSON Schemas for the Requirements Confidence Framework (RCF). Language-neutral. The contract every RCF tool keys to.",
   "license": "Apache-2.0",

package/schemas/user-story.schema.json

@@ -72,7 +72,31 @@
         "disposition": { "$ref": "#/$defs/acDisposition" },
         "vendorCitation": { "$ref": "#/$defs/acVendorCitation" },
         "probe": { "$ref": "#/$defs/acProbe" },
-        "provenance": { "$ref": "#/$defs/acProvenance" }
+        "provenance": { "$ref": "#/$defs/acProvenance" },
+        "supersededBy": {
+          "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/acId",
+          "description": "Id of the acceptance criterion that replaces this one. Presence marks the criterion as retired: it stays in the record as history and consumers stop treating it as live (a coverage audit does not require a bound test for it). Requires supersededOn and supersessionNote. Optional at schema level; that the successor exists, is not this criterion, and forms no cycle are cross-record rules for the consumer."
+        },
+        "supersededOn": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO-8601 date (YYYY-MM-DD) the criterion was superseded. Required with supersededBy, and valid only alongside it."
+        },
+        "supersessionNote": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S",
+          "description": "Why the criterion was retired and how its successor covers it (for example the decision id that ruled the change). Required with supersededBy, and valid only alongside it. At least one non-whitespace character is required."
+        },
+        "verification": {
+          "enum": ["external", "testOnly"],
+          "description": "How the acceptance criterion is verified. external: an operator can observe the behaviour by running the packed artefact, installed cold, against a fixture project. testOnly: the behaviour lives only in the repository's own tree, CI configuration or chain state. Optional at schema level. Absence carries no default at schema level: whether a consumer requires the flag, and what each value means for a criterion's end state, are the consumer's rules. Written by rcf-lite, which sets it at DEFINE (rcf-lite ADR-4152)."
+        }
+      },
+      "dependentRequired": {
+        "supersededBy": ["supersededOn", "supersessionNote"],
+        "supersededOn": ["supersededBy"],
+        "supersessionNote": ["supersededBy"]
       }
     },
     "acOwnerRef": {
@@ -125,7 +149,7 @@
         "path": {
           "type": "string",
           "minLength": 1,
-          "description": "URL path the probe requests, relative to the run's --url (for example /healthz or /api/notes?limit=1). The only required field."
+          "description": "URL path the probe requests, relative to the run's --url (for example /healthz or /api/notes?limit=1). Required. The request target, not an assertion: a probe also needs at least one of expectStatus, expectHeader, expectBody or selector."
         },
         "expectStatus": {
           "type": "integer",
@@ -144,10 +168,16 @@
         "parityEnv": {
           "type": "string",
           "minLength": 1,
-          "description": "Target environment the probe is scoped to; the consuming resolver pairs it with rcf verify run --parity-env."
+          "description": "Target environment the probe is scoped to; the consuming resolver pairs it with rcf verify run --parity-env. Scopes the probe and is not an assertion."
         }
       },
-      "description": "Deterministic per-AC probe resolved by rcf verify run (rcf-lite issue 349). Absent means the criterion stays critique-only. Shape follows the Probe record in rcf-lite TAC-4150; the schema constrains shape only and the resolution semantics belong to the consumer."
+      "anyOf": [
+        { "properties": { "expectStatus": true }, "required": ["expectStatus"] },
+        { "properties": { "expectHeader": true }, "required": ["expectHeader"] },
+        { "properties": { "expectBody": true }, "required": ["expectBody"] },
+        { "properties": { "selector": true }, "required": ["selector"] }
+      ],
+      "description": "Deterministic per-AC probe resolved by rcf verify run (rcf-lite issue 349). Absent means the criterion stays critique-only. Shape follows the Probe record in rcf-lite TAC-4150; the schema constrains shape only and the resolution semantics belong to the consumer. From 0.9.0 a probe carries at least one response assertion (anyOf: expectStatus, expectHeader, expectBody or selector): a probe with only path, method or parityEnv asserts nothing and is rejected. Each anyOf arm declares its property locally so ajv strictRequired accepts it."
     },
     "acProbeExpectHeader": {
       "type": "object",