@stravica-ai/rcf-schemas 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.7.1 - 2026-10-16
+
+Patch bump for rcf-lite issue 349 (per-AC probe catalog resolved by deterministic verify, rcf-lite TAC-4150 and FBS-218). Adds an additive, optional `probe` object on the inline `$defs.acceptanceCriterion` of the user story, so an acceptance criterion can carry a structured, deterministic probe that `rcf verify run --mode deterministic` resolves to pass, fail or skipped with evidence. An AC without a probe stays critique-only. Every change is additive: every 0.7.0-valid document keeps validating.
+
+Patch semver convention: URLs pinned at `v0.6.0`. No breaking change; every 0.7.0-valid document keeps validating. rcf-lite TAC-4150 calls this change "the rcf-schemas minor"; under this repo's rule (`CONTRIBUTING.md` and the `README.md` Versioning section: additive changes are a patch bump, breaking changes a minor) an optional property on a closed object is additive, the same call 0.6.2 made for `ownerRef`, `disposition` and `vendorCitation` on the same record, so the release is `0.7.1`.
+
+### Added
+
+- **`user-story.schema.json`**: new optional `probe` on the inline `$defs.acceptanceCriterion`, `$defs.acProbe`. Object, `additionalProperties: false`, only `path` required. Fields: `method` (string enum `GET | HEAD | POST | PUT | PATCH | DELETE | OPTIONS`; absence means GET, documented in the `description` rather than a JSON Schema `default`, since no schema in this repo uses `default`), `path` (min-length-1 string, a URL path relative to the run's `--url`), `expectStatus` (integer, 100..599), `expectHeader` (`$defs.acProbeExpectHeader`), `expectBody` (`$defs.acProbeExpectBody`), `selector` (min-length-1 string, a DOM selector that must be present), `parityEnv` (min-length-1 string, paired by the resolver with `rcf verify run --parity-env`). Shape follows the Probe record in rcf-lite TAC-4150.
+- **`user-story.schema.json`**: new `$defs.acProbeExpectHeader`. Object with required `name` and `match` (both min-length-1 strings), `additionalProperties: false`. Match semantics belong to the consuming resolver; the schema constrains shape only.
+- **`user-story.schema.json`**: new `$defs.acProbeExpectBody`. Object with optional `contains` (min-length-1 string, literal text) and `matches` (min-length-1 string, a regular expression source), `additionalProperties: false`, `minProperties: 1` and `maxProperties: 1`, so exactly one of the two is present.
+- **Fixtures (valid)**: `fixtures/valid/user-story/us-007-ac-probe-minimal.json` (a probe with only `path`), `fixtures/valid/user-story/us-008-ac-probe-full.json` (a probe carrying every field, `expectBody.matches`).
+- **Fixtures (invalid)**: `fixtures/invalid/user-story/us-009-ac-probe-unknown-property.json` (unknown `timeoutMs` on the probe), `fixtures/invalid/user-story/us-010-ac-probe-expect-body-both.json` (`expectBody` with both `contains` and `matches`), `fixtures/invalid/user-story/us-011-ac-probe-expect-status-600.json` (`expectStatus` 600), `fixtures/invalid/user-story/us-012-ac-probe-expect-header-missing-match.json` (`expectHeader` without `match`), `fixtures/invalid/user-story/us-013-ac-probe-missing-path.json` (probe without the required `path`). Each fails on exactly one ajv error.
+- **Tests**: `test/user-story.test.js` gains 23 cases for `probe` (back-compat absent, minimal path-only, full shape, `expectBody.contains`, every method enum value, lowercase method rejected, missing and empty `path` rejected, unknown probe property rejected, bare-string probe rejected, `expectBody` with both, neither, an unknown property or an empty `contains` rejected, `expectStatus` 600, 99, 200.5 and "200" rejected, bounds 100 and 599 accepted, `expectHeader` missing `match`, missing `name` or carrying an unknown property rejected, empty `selector` and empty `parityEnv` rejected, probe alongside `scope`, `determinism`, `ownerRef`, `disposition` and `provenance`). Total suite grows from 379 to 402.
+
+### Migration
+
+- **Existing chains on 0.7.0**: bump `@stravica-ai/rcf-schemas` to `0.7.1`. Every existing document keeps validating; `probe` is optional and unknown to pre-0.7.1 callers.
+- **To adopt a probe on an AC**: add `probe: { path }` plus whichever expectations the criterion needs (`expectStatus`, `expectHeader`, `expectBody`, `selector`, `parityEnv`). An AC with no probe stays critique-only; the rcf-lite catalog file `rcf/verify-catalog.json` remains an alternative carrier, and an AC-level probe wins over a catalog entry (rcf-lite TAC-4150).
+- **Consumers to bump**: `rcf-lite` (its `packages/rcf-lite/package.json` pins the schemas package exact, at `0.7.0` on `main` at this release). The pin bump to `0.7.1` is FBS-218's job: the build spec cannot merge until the pin lands. This repo does not touch rcf-lite.
+
+### Notes
+
+- `expectBody` uses `minProperties` / `maxProperties` on a closed object rather than a `oneOf` of `required` arms: ajv strict mode (`strictRequired`, which this repo's test loader runs under) refuses a `required` keyword in an arm that does not declare the property locally, and the closed-object count expresses "exactly one of `contains` or `matches`" in one place with a direct error message.
+- Scripted back-compat pass at authoring time: every 0.7.0 fixture at main `e721930` (65 valid + 90 invalid = 155 total) validates to the same outcome against the 0.7.1 schemas with zero drift.
+- `docs/user-story.md` does not yet describe `probe`; this release was scoped to the schema, fixtures, tests, version and changelog, and the doc page catches up in a follow-up.
+- `back-compat-freeze.test.js` continues to pass.
+
 ## 0.7.0 - 2026-10-11
 
 Minor bump for the discovery-UX gate: adds an optional `journeyStepIds[]` carrier on the FBS schema and a new `journeyStub` review-finding kind on `reviewAudit[].testTheatreFindings[].kind`. Both additions are additive at the shape level; every 0.6.3-valid document keeps validating. The bump is a minor (not a patch) because the review-kind enum is a shared vocabulary and the enum extension is a vocabulary change consumers may want to switch on, following the project's pre-1.0 convention. Canonical `$id` URLs are kept at `v0.6.0` on this release: no schema's `$id` or cross-file `$ref` changes, so every validator keyed to the `v0.6.0` URLs picks up the additions by file bytes alone. Rolling the URLs to `v0.7.0` is deferred to HQ at publish time if the convention calls for it.

package/fixtures/invalid/user-story/us-009-ac-probe-unknown-property.json

@@ -0,0 +1,24 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Probe with an unknown property is rejected",
+  "asA": "author",
+  "iWant": "the probe object to stay closed",
+  "soThat": "a typo in a probe field is a validation error, not a silent no-op",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "Probe carries an unknown timeoutMs field.",
+      "testable": true,
+      "probe": {
+        "path": "/healthz",
+        "timeoutMs": 500
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-16T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-010-ac-probe-expect-body-both.json

@@ -0,0 +1,27 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Probe expectBody with both contains and matches is rejected",
+  "asA": "author",
+  "iWant": "expectBody to carry exactly one assertion",
+  "soThat": "the resolver never has to pick between two body checks",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "expectBody carries both contains and matches.",
+      "testable": true,
+      "probe": {
+        "path": "/api/notes",
+        "expectBody": {
+          "contains": "notes",
+          "matches": "^\\{"
+        }
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-16T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-011-ac-probe-expect-status-600.json

@@ -0,0 +1,24 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Probe expectStatus outside 100..599 is rejected",
+  "asA": "author",
+  "iWant": "expectStatus to be a real HTTP status code",
+  "soThat": "a typo in the expected status is caught at authoring time",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "expectStatus is 600.",
+      "testable": true,
+      "probe": {
+        "path": "/healthz",
+        "expectStatus": 600
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-16T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-012-ac-probe-expect-header-missing-match.json

@@ -0,0 +1,26 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Probe expectHeader without match is rejected",
+  "asA": "author",
+  "iWant": "a header assertion to name both the header and the value",
+  "soThat": "a header probe always asserts something",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "expectHeader names the header but omits match.",
+      "testable": true,
+      "probe": {
+        "path": "/healthz",
+        "expectHeader": {
+          "name": "content-type"
+        }
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-16T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-013-ac-probe-missing-path.json

@@ -0,0 +1,24 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Probe without path is rejected",
+  "asA": "author",
+  "iWant": "every probe to name the path it requests",
+  "soThat": "the resolver always knows what to fetch",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "Probe omits the required path.",
+      "testable": true,
+      "probe": {
+        "method": "GET",
+        "expectStatus": 200
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-16T00:00:00Z"
+}

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

@@ -0,0 +1,24 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "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",
+  "soThat": "rcf verify run resolves it without a critique pass",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "The health endpoint answers on the deployed URL.",
+      "testable": true,
+      "scope": "deployed",
+      "probe": {
+        "path": "/healthz"
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-16T00:00:00Z"
+}

package/fixtures/valid/user-story/us-008-ac-probe-full.json

@@ -0,0 +1,39 @@
+{
+  "usId": "US-301",
+  "prdId": "PRD-100",
+  "reqId": "REQ-301",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Notes API returns JSON and the notes list renders",
+  "asA": "operator running deterministic verify",
+  "iWant": "an acceptance criterion to carry a probe exercising every field",
+  "soThat": "rcf verify run resolves status, header, body, selector and environment in one pass",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-301-1",
+      "description": "Listing notes returns a JSON notes array, and the notes page renders its list.",
+      "testable": true,
+      "given": "a deployed notes service",
+      "when": "the client lists notes",
+      "then": "the response is JSON and the list renders",
+      "scope": "deployed",
+      "determinism": "deterministic",
+      "probe": {
+        "method": "GET",
+        "path": "/api/notes?limit=1",
+        "expectStatus": 200,
+        "expectHeader": {
+          "name": "content-type",
+          "match": "application/json"
+        },
+        "expectBody": {
+          "matches": "^\\{\"notes\":\\["
+        },
+        "selector": "[data-testid=\"notes-list\"]",
+        "parityEnv": "preview"
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-10-16T00:00:00Z"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/rcf-schemas",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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

@@ -71,6 +71,7 @@
         "ownerRef": { "$ref": "#/$defs/acOwnerRef" },
         "disposition": { "$ref": "#/$defs/acDisposition" },
         "vendorCitation": { "$ref": "#/$defs/acVendorCitation" },
+        "probe": { "$ref": "#/$defs/acProbe" },
         "provenance": { "$ref": "#/$defs/acProvenance" }
       }
     },
@@ -111,6 +112,79 @@
       },
       "description": "Vendor citation for an acceptance criterion whose truth rests on a third-party platform fact. Optional at schema level; consumer rulesets may require it on any AC that asserts a vendor fact (for example, a platform migration keyword or a rate-limit value)."
     },
+    "acProbe": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+          "description": "HTTP method of the probe request. Optional; absence means GET."
+        },
+        "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."
+        },
+        "expectStatus": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 599,
+          "description": "HTTP status code the response must carry."
+        },
+        "expectHeader": { "$ref": "#/$defs/acProbeExpectHeader" },
+        "expectBody": { "$ref": "#/$defs/acProbeExpectBody" },
+        "selector": {
+          "type": "string",
+          "minLength": 1,
+          "description": "DOM selector that must be present in the rendered response."
+        },
+        "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": "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."
+    },
+    "acProbeExpectHeader": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "match"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Response header name."
+        },
+        "match": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Value the named header must match. Match semantics belong to the consuming resolver."
+        }
+      },
+      "description": "Response header assertion on an acceptance-criterion probe. Both name and match are required."
+    },
+    "acProbeExpectBody": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "contains": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Literal text the response body must contain."
+        },
+        "matches": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Regular expression source the response body must match."
+        }
+      },
+      "minProperties": 1,
+      "maxProperties": 1,
+      "description": "Response body assertion on an acceptance-criterion probe. Exactly one of contains or matches: the object is closed to those two properties and carries exactly one of them."
+    },
     "acProvenance": {
       "type": "object",
       "additionalProperties": false,