@stravica-ai/rcf-schemas 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.6.2 - 2026-09-09
+
+Patch bump for four additive, optional fields that let a blueprint's own layers point at their owning artefacts rather than restating shapes and promises inline. Adds `deliveredBy` on the requirement record (naming the TAC or ADR that delivers the requirement's externally promised property), and `ownerRef`, `disposition`, and `vendorCitation` on the acceptance criterion inline on a user story. Every change is additive: every 0.6.1-valid document remains valid.
+
+Patch semver convention: URLs pinned at `v0.6.0`. No breaking change; every 0.6.1-valid document keeps validating.
+
+### Added
+
+- **`req.schema.json`**: new optional `deliveredBy` on the requirement record, `$defs.deliveredBy`. Object with three optional sub-fields (`tacId` via the shared `common.$defs.tacId` pattern, `adrId` via `common.$defs.adrId`, and a min-length-1 `field` string carrying an optional dotted path into the delivering record). `additionalProperties: false` on the object. All sub-fields are optional at the schema surface so the record composes additively; consumer rulesets that gate the delivery link may require at least one of `tacId` or `adrId`.
+- **`user-story.schema.json`**: new optional `ownerRef` on the inline `$defs.acceptanceCriterion`, `$defs.acOwnerRef`. Same shape as `deliveredBy` (optional `tacId`, optional `adrId`, optional `field`), naming the owning TAC or ADR an acceptance criterion references instead of restating. `additionalProperties: false`.
+- **`user-story.schema.json`**: new optional `disposition` on the inline `$defs.acceptanceCriterion`, `$defs.acDisposition`. Enum `fixed | template`. 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). 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.
+- **`user-story.schema.json`**: new optional `vendorCitation` on the inline `$defs.acceptanceCriterion`, `$defs.acVendorCitation`. Object with two required sub-fields (`url`, JSON Schema `format: uri`, min-length-1; `verifiedOn`, `format: date`, ISO-8601 `YYYY-MM-DD`) for any criterion whose truth rests on a third-party platform fact. `additionalProperties: false`. Consumers may fetch the URL at gate time so a dead link is a finding, and may compare `verifiedOn` against a tolerance window.
+- **Fixtures (valid)**: `fixtures/valid/req/req-004-delivered-by.json` (a REQ with `deliveredBy` pointing at a TAC field), `fixtures/valid/user-story/us-006-ac-ownership-and-disposition.json` (a US with two ACs exercising `ownerRef`, `disposition` at both enum values, and `vendorCitation`).
+- **Fixtures (invalid)**: `fixtures/invalid/req/req-006-delivered-by-not-object.json` (deliveredBy as a bare id string), `fixtures/invalid/user-story/us-006-ac-owner-ref-not-object.json` (ownerRef as a bare id string), `fixtures/invalid/user-story/us-007-ac-disposition-bad-enum.json` (disposition outside the `fixed | template` enum), `fixtures/invalid/user-story/us-008-ac-vendor-citation-missing-verified-on.json` (vendorCitation object missing its required `verifiedOn` date).
+- **Tests**: `test/req.test.js` gains 7 cases for `deliveredBy` (optional back-compat, TAC-pointing, ADR-pointing, empty object, string rejection, unknown-property rejection, bad-tacId-shape rejection). `test/user-story.test.js` gains 13 cases across `ownerRef`, `disposition`, and `vendorCitation` (both enum values, both id targets, missing required sub-fields, bad `verifiedOn` format, unknown property rejections, and a combined-shape case alongside `scope`, `determinism`-adjacent optional fields, and `provenance`). Total suite grows from 330 to 350.
+
+### Migration
+
+- **Existing chains on 0.6.1**: bump `@stravica-ai/rcf-schemas` to `0.6.2`. Every existing document keeps validating; all four fields are optional and unknown to pre-0.6.2 callers.
+- **Consumers that inline the AC record**: pre-0.6.2 code that used `additionalProperties: false` at the AC level via a local extension keeps refusing the new fields until the consumer's own schema pins are bumped. The shared record accepts the fields immediately.
+
+### Notes
+
+- Sub-defs sit alongside the existing `acProvenance` peer on the user story schema, and alongside `reqShapeClassification` on the requirement schema. Both `deliveredBy` and `acOwnerRef` are the same {`tacId?`, `adrId?`, `field?`} shape but defined per file rather than in `common.schema.json`, on the same grounds as `reqShapeClassification` and `acProvenance`: a small, record-local $def keeps the change surface additive on exactly the two files it lives on.
+- The lint mechanics that consume these fields (single-definition ownership, REQ delivery, disposition ledger, vendor-citation freshness) live in the consuming `rcf-lite` build, not in this schema. The schema surface stays validation-only.
+
 ## 0.6.1 - 2026-09-05
 
 Patch bump for the T-0 visual-round Playwright-first ship-gate seam (`projects/blueprint-library/specs/visual-round-spec-2026-09-04.md`, section 3.4). Adds an additive, optional `probePacks[]` carrier on `browserVerificationRecord` so the record shape that rcf-lite's `packages/rcf-lite/src/browser-verify/pack-runner.js` already emits (per pack `packName`, `packVersion`, `blueprintSlug`, `applicable`, `checks[]`, optional `preChecks[]`, optional pack-level `detail` string) can persist without tripping `additionalProperties: false`.

package/docs/req.md

@@ -27,6 +27,7 @@ Individual Requirement within a PRD. One file per REQ. Recommended path: `rcf/re
 |---|---|---|
 | `rationale` | string | Why this REQ exists. |
 | `tags` | array of strings | Free-form tags for grouping or filtering. |
+| `deliveredBy` | object: `{tacId?, adrId?, field?}` | 0.6.2. Back-reference naming the TAC or ADR that delivers the requirement's externally promised property (a global staleness ceiling, an anti-enumeration guarantee, a forward-only migration invariant, a boot-event contract). `tacId` and `adrId` re-use the shared id patterns; `field` is an optional dotted path into the delivering record (for example, `responsibilities.replicationCeiling` or `decision.retryPolicy`). All sub-fields optional at schema level so the record composes additively; consumer rulesets may require at least one of `tacId` or `adrId` on a REQ that promises an externally observable property. `additionalProperties: false`. |
 
 ## Why REQ is its own file
 

package/docs/user-story.md

@@ -44,6 +44,9 @@ Each AC inside `acceptanceCriteria[]`:
 | `testable` | boolean | yes | Author declares the AC is testable. |
 | `scope` | `scopeTag` enum | no | `library`, `runtime`, `deployed`, `unclassified`. Optional at schema level (0.4.3). Names the scope at which the AC is observable; governs which test scopes count as coverage. |
 | `determinism` | enum: `deterministic`, `nonDeterministic` | no | 0.6.0. Author's declaration of whether the AC's observable output is deterministic or non-deterministic (LLM-generated text, ranked results, generated code, judgement calls). Optional at schema level; absence is treated as `deterministic` by every consumer. Governs whether an EVAL is required by `rcf audit eval coverage --strict` and whether the merge gate emits `EVAL-MISSING` / `EVAL-BELOW-THRESHOLD` per-AC verdicts. |
+| `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`. |
 
 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/req/req-006-delivered-by-not-object.json

@@ -0,0 +1,14 @@
+{
+  "reqId": "REQ-201",
+  "prdId": "PRD-100",
+  "title": "Delivered-by must be an object, not a string",
+  "description": "Rejects a REQ whose deliveredBy is a bare id string instead of the {tacId?, adrId?, field?} object.",
+  "category": "functional",
+  "domain": "cache",
+  "priority": "must",
+  "version": "1.0.0",
+  "status": "draft",
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": "TAC-401"
+}

package/fixtures/invalid/user-story/us-006-ac-owner-ref-not-object.json

@@ -0,0 +1,21 @@
+{
+  "usId": "US-201",
+  "prdId": "PRD-100",
+  "reqId": "REQ-201",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Owner-ref must be an object, not a string",
+  "asA": "author",
+  "iWant": "the AC's ownerRef to be the {tacId?, adrId?, field?} object shape",
+  "soThat": "the reference is machine-checkable rather than free text",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-201-1",
+      "description": "Owner ref is a string instead of an object.",
+      "testable": true,
+      "ownerRef": "TAC-401"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-007-ac-disposition-bad-enum.json

@@ -0,0 +1,21 @@
+{
+  "usId": "US-201",
+  "prdId": "PRD-100",
+  "reqId": "REQ-201",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Disposition outside the enum is rejected",
+  "asA": "author",
+  "iWant": "disposition to be one of fixed or template",
+  "soThat": "the marker is unambiguous for a consumer that gates on it",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-201-1",
+      "description": "Disposition is neither fixed nor template.",
+      "testable": true,
+      "disposition": "invariant"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z"
+}

package/fixtures/invalid/user-story/us-008-ac-vendor-citation-missing-verified-on.json

@@ -0,0 +1,23 @@
+{
+  "usId": "US-201",
+  "prdId": "PRD-100",
+  "reqId": "REQ-201",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Vendor citation without verifiedOn is rejected",
+  "asA": "author",
+  "iWant": "a vendor citation to carry both url and the ISO-8601 verified-on date",
+  "soThat": "a consumer can tell a fresh fact from a stale one",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-201-1",
+      "description": "Vendor citation without the required verifiedOn date.",
+      "testable": true,
+      "vendorCitation": {
+        "url": "https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/"
+      }
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z"
+}

package/fixtures/valid/req/req-004-delivered-by.json

@@ -0,0 +1,19 @@
+{
+  "reqId": "REQ-201",
+  "prdId": "PRD-100",
+  "title": "Application cache stays fresh within a stated ceiling",
+  "description": "The application cache surfaces stale reads no older than the ceiling stated in the delivering TAC's replication guarantee.",
+  "category": "nonFunctional",
+  "domain": "cache",
+  "priority": "must",
+  "rationale": "Stale reads beyond the ceiling break invalidation-sensitive views.",
+  "tags": ["cache", "freshness"],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z",
+  "deliveredBy": {
+    "tacId": "TAC-401-cache-aside-store",
+    "field": "responsibilities.replicationCeiling"
+  }
+}

package/fixtures/valid/user-story/us-006-ac-ownership-and-disposition.json

@@ -0,0 +1,47 @@
+{
+  "usId": "US-201",
+  "prdId": "PRD-100",
+  "reqId": "REQ-201",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Deploy a Durable Object namespace with a migration record",
+  "asA": "operator deploying a Worker that mints a Durable Object namespace",
+  "iWant": "the wrangler configuration and migration record to be consistent with the platform's minting rules",
+  "soThat": "the deploy succeeds and the namespace mints on the current backend",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-201-1",
+      "description": "The migration record carries the new_sqlite_classes keyword against every minted class name.",
+      "given": "a Worker configuration with a Durable Object binding block",
+      "when": "the deploy runs",
+      "then": "the migration record uses the vendor-current keyword and the deploy succeeds",
+      "testable": true,
+      "scope": "deployed",
+      "ownerRef": {
+        "tacId": "TAC-401-durable-objects-namespace",
+        "field": "interfaces.migration.keyword"
+      },
+      "disposition": "fixed",
+      "vendorCitation": {
+        "url": "https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/",
+        "verifiedOn": "2026-09-08"
+      }
+    },
+    {
+      "id": "AC-201-2",
+      "description": "The wrangler binding names commit to the project's chosen class names on both binding blocks.",
+      "given": "a Worker configuration with a Durable Object binding block",
+      "when": "the applying agent has substituted the project's chosen class names",
+      "then": "each binding's class_name appears once in the migration record",
+      "testable": true,
+      "scope": "runtime",
+      "ownerRef": {
+        "tacId": "TAC-401-durable-objects-namespace",
+        "field": "interfaces.wrangler.bindings"
+      },
+      "disposition": "template"
+    }
+  ],
+  "createdAt": "2026-01-01T00:00:00Z",
+  "updatedAt": "2026-09-09T00:00:00Z"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/rcf-schemas",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "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/req.schema.json

@@ -35,9 +35,24 @@
     "status": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/authoringStatus" },
     "createdAt": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/timestamp" },
     "updatedAt": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/timestamp" },
-    "shapeClassification": { "$ref": "#/$defs/reqShapeClassification" }
+    "shapeClassification": { "$ref": "#/$defs/reqShapeClassification" },
+    "deliveredBy": { "$ref": "#/$defs/deliveredBy" }
   },
   "$defs": {
+    "deliveredBy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tacId": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/tacId" },
+        "adrId": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/adrId" },
+        "field": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional dotted path into the owning TAC or ADR record (for example, 'principal.fields' or 'decision.retryPolicy') that pinpoints the delivering surface. Optional; presence is not enforced."
+        }
+      },
+      "description": "Optional back-reference on a REQ naming the TAC or ADR that delivers the requirement's externally promised property. All sub-fields are optional at schema level so the record composes additively; ruleset-enforcing consumers may require at least one of tacId or adrId when the REQ carries a delivery promise."
+    },
     "reqShapeClassification": {
       "type": "object",
       "additionalProperties": false,

package/schemas/user-story.schema.json

@@ -68,9 +68,49 @@
           "enum": ["deterministic", "nonDeterministic"],
           "description": "Whether the AC's observable output is deterministic (same inputs, same outputs) or non-deterministic (LLM-generated text, ranked results, generated code, judgement calls). Optional at schema level; absence is treated as 'deterministic' by every consumer. Governs whether an EVAL is required by rcf audit eval coverage --strict and whether the merge gate emits EVAL-MISSING or EVAL-BELOW-THRESHOLD per-AC verdicts."
         },
+        "ownerRef": { "$ref": "#/$defs/acOwnerRef" },
+        "disposition": { "$ref": "#/$defs/acDisposition" },
+        "vendorCitation": { "$ref": "#/$defs/acVendorCitation" },
         "provenance": { "$ref": "#/$defs/acProvenance" }
       }
     },
+    "acOwnerRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tacId": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/tacId" },
+        "adrId": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/adrId" },
+        "field": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional dotted path into the owning TAC or ADR record (for example, 'interfaces.principal.fields' or 'decision.retryPolicy') that pinpoints the referenced surface. Optional; presence is not enforced."
+        }
+      },
+      "description": "Optional back-reference on an acceptance criterion naming the owning TAC or ADR the criterion observes rather than restating. All sub-fields are optional at schema level so the record composes additively; ruleset-enforcing consumers may require at least one of tacId or adrId when the criterion references an owning artefact."
+    },
+    "acDisposition": {
+      "enum": ["fixed", "template"],
+      "description": "Marks whether an acceptance 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."
+    },
+    "acVendorCitation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url", "verifiedOn"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "minLength": 1,
+          "description": "Vendor documentation URL the third-party fact rests on. Consumers may fetch it at gate time so a dead link is a finding."
+        },
+        "verifiedOn": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO-8601 date (YYYY-MM-DD) the vendor fact was verified against the cited URL. Consumers compare against their own tolerance window and refuse or warn when the citation is beyond it."
+        }
+      },
+      "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)."
+    },
     "acProvenance": {
       "type": "object",
       "additionalProperties": false,