@stravica-ai/rcf-schemas 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.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.
+
+### Added
+
+- **`fbs.schema.json`**: new optional top-level `journeyStepIds` property. Shape: `array` with items `{ type: "string", minLength: 1 }` and `uniqueItems: true`. Carries discovery journey step ids (shape `JNY-nnn-nnn`, owned by the discovery journey record at `rcf/discovery/journey.json`, minted by the discovery binder as `JNY-nnn-nnn` under their parent `JNY-nnn` journey) that the build unit delivers. Written at Define; read by the build-review surface so a UI-bearing FBS that leaves a journey step unbound, or a discovery step with no FBS binding, raises the new `journeyStub` finding kind. Pre-0.7.0 FBSes stay valid: the field is optional and no existing property changes.
+- **`manifest.schema.json`**: `reviewAudit[].testTheatreFindings[].kind` enum gains `journeyStub` (appended between `uiBaselineDrift` and `otherDeclared`, nothing reordered). The `allOf` conditional that lets `uiBaselineDrift` findings omit `tsId` is widened via `anyOf` so `journeyStub` findings also omit `tsId`: they anchor on an FBS id or a `JNY-nnn-nnn` step id via `anchorId`, same pattern as `uiBaselineDrift`. Every other kind still requires `tsId`; the back-compat allOf arm is unchanged for them.
+- **`manifest.schema.json`**: top-level `description` extended to name the new `journeyStub` kind, following the "From 0.X.Y the manifest additionally carries..." precedent set at 0.4.1, 0.4.4, 0.4.5, 0.5.1 and 0.6.3.
+- **Fixtures (valid)**: `fixtures/valid/fbs/fbs-008-journey-step-ids.json` (FBS-215 carrying three `JNY-nnn-nnn` ids), `fixtures/valid/manifest/manifest-017-review-audit-journey-stub.json` (one `reviewAudit` with two `journeyStub` findings: one anchored on an FBS id, one anchored on a `JNY-nnn-nnn` step id).
+- **Fixtures (invalid)**: `fixtures/invalid/fbs/fbs-014-journey-step-ids-non-string.json` (numeric item), `fixtures/invalid/fbs/fbs-015-journey-step-ids-duplicate.json` (two identical entries, `uniqueItems`), `fixtures/invalid/fbs/fbs-016-journey-step-ids-empty-string.json` (empty-string item, items `minLength` 1).
+- **Tests**: `test/fbs.test.js` gains 9 cases for `journeyStepIds` (back-compat absent, populated, empty array, free-form ids, non-string rejected, empty-string rejected, duplicate rejected, non-array rejected, alongside `contextRequirements.standardIds`). `test/manifest.test.js` gains 5 cases for the `journeyStub` kind (anchor on FBS id, anchor on `JNY-nnn-nnn` step id, finding without `tsId` validates, bad severity rejected, non-exempt kind still requires `tsId`). Total suite grows from 365 to 379.
+
+### Changed
+
+- No `$id` URL roll on this minor bump: the schemas remain keyed to `https://schemas.stravica.io/rcf/v0.6.0/...`. Deviates from the 0.3.0 / 0.4.0 / 0.5.0 / 0.6.0 precedent of rolling the URL on a minor; retained here because the scope is strictly additive and rolling the URL is itself a consumer-visible change that would be larger than the schema delta. Final call on URL rolling at publish time; nothing on this PR precommits it.
+
+### Migration
+
+- **Existing chains on 0.6.3**: bump `@stravica-ai/rcf-schemas` to `0.7.0`. Every existing document keeps validating; both additions are optional and unknown to pre-0.7.0 callers.
+- **To adopt `journeyStepIds` on an FBS**: list the discovery journey step ids the build unit delivers; the discovery record is the source of truth for the ids. The field is optional and may be left absent until the FBS is bound.
+- **To emit a `journeyStub` finding from the review surface**: switch the current `otherDeclared` + `kindDescription: "journeyStub: ..."` path to `kind: "journeyStub"`, anchored on the relevant FBS id or `JNY-nnn-nnn` step id via `anchorId`.
+- **Consumers to bump**: `rcf-lite` (its `packages/rcf-lite/package.json` pins the schemas package exact; the discovery-UX-gate train bumps it to `0.7.0`).
+
+### Notes
+
+- Review-kind enum additive-safety was verified in-tree: `rcf-lite` carries only a JSDoc `TestTheatreFindingKind` typedef and non-exhaustive consumption of the `kind` string. No exhaustive `switch` on the enum surfaced in a repository walk at relay time.
+- The `allOf` widening uses the same `if`/`then` conditional pattern the schema already uses for `uiBaselineDrift` (0.4.2) and `applicable` (0.6.3), with the `if` moved into an `anyOf` so both exempt kinds share one arm. The `else` arm is byte-identical to the pre-0.7.0 clause; every pre-0.7.0 finding keeps hitting the same requiredness.
+- `back-compat-freeze.test.js` continues to pass: the frozen pre-0.4.4 manifest fixture is unaffected by the enum addition or the allOf widening.
+- Scripted back-compat pass at authoring time: every 0.6.3 fixture at main `990875b4` (63 valid + 87 invalid = 150 total) validates to the same outcome against the 0.7.0 schemas with zero drift.
+
 ## 0.6.3 - 2026-09-17
 
 Patch bump for the last two schema-shaped claims on the rcf-lite 0.28.0 referee-guarantees train (docs claims C-33 and C-38). Adds an additive, optional `shipWithoutEval[]` carrier on the manifest (sister of `shipWithoutVerified`, written by `rcf finalise --ship-without-eval`), and an additive, optional `applicable` boolean on `browserVerificationProbePackCheck` (mirrors the pack-level `applicable`, so a check whose own `appliesTo` predicate returned false records `applicable: false` at the check level without a stray verdict or severity). Every change is additive: every 0.6.2-valid manifest keeps validating.

package/docs/fbs.md

@@ -36,6 +36,7 @@ Structurally, each FBS carries the mandatory `bsId` back-reference plus `buildOr
 | `domain` | string | Free-form domain label. |
 | `notes` | string | FBS-specific gotchas. |
 | `noCodeNodes` | boolean | Declares this build spec produces no traceable code (docs-only or config-only). `rcf build --mark complete` records it via `--no-code-nodes` and the CodeNode gate skips the spec. Added in 0.3.1. |
+| `journeyStepIds` | array of non-empty strings, `uniqueItems: true` | Discovery journey step ids (shape `JNY-nnn-nnn`, owned by the discovery journey record at `rcf/discovery/journey.json`) that this build unit delivers. Written at Define; read by the build-review surface so a UI-bearing FBS that leaves a journey step unbound, or a discovery step with no FBS binding, raises a `journeyStub` review finding. Optional; pre-0.7.0 FBSes keep validating. Added in 0.7.0. |
 
 ## `contextRequirements` shape
 

package/docs/manifest.md

@@ -59,6 +59,20 @@ SSoT discipline. Every parent-child edge is encoded exactly once, on the child,
 
 Enumerating children in the manifest as well would create two sources of truth; pick one. The child owns the reference. The manifest stays small (~8 properties) and a new US / TAC / ADR / FBS / REQ / TS never requires a manifest edit.
 
+## `reviewAudit[].testTheatreFindings[].kind` vocabulary
+
+Review findings on a `reviewAudit` record carry a `kind` from a fixed enum. The vocabulary grows additively; a consumer that switches on the enum should treat an unknown value as "unrecognised" rather than fail-closed.
+
+| Kind | Introduced | Anchor | Notes |
+|---|---|---|---|
+| `mockOnlyIntegrationClaim` | 0.4.0 | `tsId` required | Test suite claims an integration level but the runtime profile is mock. |
+| `testPointerBroken` | 0.4.0 | `tsId` required | The TS/TC pointer resolves to no code node. |
+| `assertionStrengthWeak` | 0.4.0 | `tsId` required | Assertion found too weak for the AC it attests. |
+| `acIdsCoverageDrift` | 0.4.0 | `tsId` required | AC coverage drifted between declared and attested. |
+| `uiBaselineDrift` | 0.4.2 | `anchorId` (FBS id or file path) | UI implementation contradicts a declared uiBaseline default. Exempt from the `tsId` requirement. |
+| `journeyStub` | 0.7.0 | `anchorId` (FBS id or discovery `JNY-nnn-nnn` step id) | Build-review surface flag: a UI-bearing FBS whose `journeyStepIds[]` is empty, or a discovery step with no FBS binding. Exempt from the `tsId` requirement; the sibling pattern of `uiBaselineDrift`. |
+| `otherDeclared` | 0.4.0 | `tsId` required; `kindDescription` required in practice | Catch-all; carries free-text `kindDescription`. |
+
 ## Example
 
 ```json

package/fixtures/invalid/fbs/fbs-014-journey-step-ids-non-string.json

@@ -0,0 +1,14 @@
+{
+  "fbsId": "FBS-215",
+  "prdId": "PRD-001",
+  "bsId": "BS-001",
+  "buildOrder": 15,
+  "executionStatus": "notStarted",
+  "title": "journeyStepIds non-string item",
+  "summary": "journeyStepIds carries a numeric entry; the schema requires string items.",
+  "acIds": ["AC-001"],
+  "dependsOnFbsIds": [],
+  "journeyStepIds": ["JNY-001-001", 2],
+  "createdAt": "2026-10-11T00:00:00Z",
+  "updatedAt": "2026-10-11T00:00:00Z"
+}

package/fixtures/invalid/fbs/fbs-015-journey-step-ids-duplicate.json

@@ -0,0 +1,14 @@
+{
+  "fbsId": "FBS-215",
+  "prdId": "PRD-001",
+  "bsId": "BS-001",
+  "buildOrder": 15,
+  "executionStatus": "notStarted",
+  "title": "journeyStepIds duplicate items",
+  "summary": "journeyStepIds carries two identical entries; uniqueItems is enforced.",
+  "acIds": ["AC-001"],
+  "dependsOnFbsIds": [],
+  "journeyStepIds": ["JNY-001-001", "JNY-001-001"],
+  "createdAt": "2026-10-11T00:00:00Z",
+  "updatedAt": "2026-10-11T00:00:00Z"
+}

package/fixtures/invalid/fbs/fbs-016-journey-step-ids-empty-string.json

@@ -0,0 +1,14 @@
+{
+  "fbsId": "FBS-215",
+  "prdId": "PRD-001",
+  "bsId": "BS-001",
+  "buildOrder": 15,
+  "executionStatus": "notStarted",
+  "title": "journeyStepIds empty-string entry",
+  "summary": "journeyStepIds carries an empty-string entry; items have minLength 1.",
+  "acIds": ["AC-001"],
+  "dependsOnFbsIds": [],
+  "journeyStepIds": ["JNY-001-001", ""],
+  "createdAt": "2026-10-11T00:00:00Z",
+  "updatedAt": "2026-10-11T00:00:00Z"
+}

package/fixtures/valid/fbs/fbs-008-journey-step-ids.json

@@ -0,0 +1,14 @@
+{
+  "fbsId": "FBS-215",
+  "prdId": "PRD-001",
+  "bsId": "BS-001",
+  "buildOrder": 15,
+  "executionStatus": "notStarted",
+  "title": "Discovery UX gate: journeyStub review-kind binding",
+  "summary": "Bind the FBS to the discovery journey steps it delivers so build review can detect unbound steps and unbound UI-bearing specs.",
+  "acIds": ["AC-215-1", "AC-215-2"],
+  "dependsOnFbsIds": ["FBS-210"],
+  "journeyStepIds": ["JNY-001-001", "JNY-001-002", "JNY-002-001"],
+  "createdAt": "2026-10-11T00:00:00Z",
+  "updatedAt": "2026-10-11T00:00:00Z"
+}

package/fixtures/valid/manifest/manifest-017-review-audit-journey-stub.json

@@ -0,0 +1,29 @@
+{
+  "version": "2.0.0",
+  "projectName": "journeyStub review-kind coverage",
+  "prd": { "id": "PRD-001", "path": "rcf/prd.json" },
+  "tad": { "id": "TAD-001", "path": "rcf/tad.json" },
+  "bs":  { "id": "BS-001",  "path": "rcf/build-sequence.json" },
+  "reviewAudit": [
+    {
+      "id": "ra-FBS-215-1",
+      "fbsId": "FBS-215",
+      "createdAt": "2026-10-11T15:30:00Z",
+      "testTheatreFindings": [
+        {
+          "anchorId": "FBS-215",
+          "kind": "journeyStub",
+          "detail": "FBS-215 is UI-bearing (uiBearing: true) but journeyStepIds[] is empty; the discovery journey record binds no step to this build.",
+          "severity": "block"
+        },
+        {
+          "anchorId": "JNY-001-003",
+          "kind": "journeyStub",
+          "detail": "Discovery step JNY-001-003 has no FBS binding; no FBS lists it in journeyStepIds[].",
+          "severity": "warn"
+        }
+      ],
+      "verdict": "block"
+    }
+  ]
+}

package/package.json

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schemas.stravica.io/rcf/v0.6.0/fbs.schema.json",
   "title": "RCF Functional Build Spec",
-  "description": "Functional Build Specification. One per build session. Carries the mandatory bsId parent reference plus buildOrder and executionStatus. Owns its acIds[] scope (Acceptance Criteria delivered by this FBS) and its dependsOnFbsIds[] graph edge (other FBSs this one depends on). From 0.4.4 the contextRequirements block carries an optional standardIds[] array. It is the host for the bundle assembler's selective-retrieval step: the assembler analyses the FBS work text against the manifest.standards[] tag vocabulary and populates standardIds for that bundle only, or honours an operator override authored on the FBS. Every added field is optional; pre-0.4.4 FBSes remain valid.",
+  "description": "Functional Build Specification. One per build session. Carries the mandatory bsId parent reference plus buildOrder and executionStatus. Owns its acIds[] scope (Acceptance Criteria delivered by this FBS) and its dependsOnFbsIds[] graph edge (other FBSs this one depends on). From 0.4.4 the contextRequirements block carries an optional standardIds[] array. It is the host for the bundle assembler's selective-retrieval step: the assembler analyses the FBS work text against the manifest.standards[] tag vocabulary and populates standardIds for that bundle only, or honours an operator override authored on the FBS. From 0.7.0 the FBS additionally carries an optional journeyStepIds[] array: discovery journey step ids (JNY-nnn-nnn) owned by the discovery journey record that this build unit delivers, so the build-review surface can detect unbound discovery steps and unbound UI-bearing build specs. Every added field is optional; pre-0.4.4 FBSes remain valid.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -37,6 +37,12 @@
       "minItems": 0,
       "items": { "$ref": "https://schemas.stravica.io/rcf/v0.6.0/common.schema.json#/$defs/fbsId" }
     },
+    "journeyStepIds": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Discovery journey step ids (shape JNY-nnn-nnn, owned by the discovery journey record at rcf/discovery/journey.json) that this build unit delivers. Written at Define by the author or the discovery binder; read by the build-review surface so a UI-bearing FBS that leaves a journey step unbound, or a discovery step with no FBS binding, raises a journeyStub review finding. Optional; pre-0.7.0 FBSes keep validating with no journeyStepIds field present."
+    },
     "contextRequirements": {
       "type": "object",
       "additionalProperties": false,

package/schemas/manifest.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schemas.stravica.io/rcf/v0.6.0/manifest.schema.json",
   "title": "RCF Project Manifest",
-  "description": "Project manifest. Roots-only shape: declares prd, tad, bs. Children are owned by their parents and discovered by walking from the roots. From 0.4.0 the manifest also carries optional records for pre-flight configuration, review audits, UI baselines, browser verification, baseline-AC opt-outs, intake classification, register-regression canaries, and the review-surface state. From 0.4.1 the manifest additionally carries optional shipWithoutVerified acknowledgements written by rcf finalise --ship-without-verified. From 0.4.2 the testTheatreFinding shape carries an optional anchorId and drops tsId from its required list when kind is uiBaselineDrift (the drift finding is not anchored on a test suite); every other kind still requires tsId, and any 0.4.0- or 0.4.1-valid record remains valid. From 0.4.4 the manifest carries two optional additive sections that host the blueprint-library mechanism: blueprints[] (applied-blueprints registry written by rcf blueprint add / remove / upgrade) and standards[] (standards-pack registry written at rcf init and rcf standards add). From 0.4.5 the manifest additionally carries an optional resolutions[] section: one entry per operator-authored resolution of a cross-blueprint conflict, keyed at first by the globalAdrTopic conflict class (two applied blueprints each contributing a scope:global ADR on the same topic, resolved by a project-level ADR that supersedes both). Written by rcf blueprint supersede and by rcf blueprint add --resolve; read by the conflict detector so the resolved conflict is honoured and both blueprint ADRs may co-reside as superseded history. From 0.5.1 the appliedBlueprintRecord carries an optional libraryPrefix (blueprintSlug), stamped when an apply resolves through a registered external blueprint library so the library-registered ownership is durable on the record itself rather than derived by string-matching source; absent for shelf or path applies. From 0.6.3 the manifest additionally carries an optional shipWithoutEval[] section written by rcf finalise --ship-without-eval (sister of shipWithoutVerified; acknowledges EVAL-MISSING or EVAL-BELOW-THRESHOLD per-AC verdicts on the verify report and carries the operator's reason string); and the browserVerificationProbePackCheck item accepts an optional applicable:boolean flag, letting a check-level appliesTo predicate record applicable:false without a verdict or severity (aggregate verdict treats such a check as neither pass nor fail). Every added field is optional; pre-0.4.0 manifests remain valid.",
+  "description": "Project manifest. Roots-only shape: declares prd, tad, bs. Children are owned by their parents and discovered by walking from the roots. From 0.4.0 the manifest also carries optional records for pre-flight configuration, review audits, UI baselines, browser verification, baseline-AC opt-outs, intake classification, register-regression canaries, and the review-surface state. From 0.4.1 the manifest additionally carries optional shipWithoutVerified acknowledgements written by rcf finalise --ship-without-verified. From 0.4.2 the testTheatreFinding shape carries an optional anchorId and drops tsId from its required list when kind is uiBaselineDrift (the drift finding is not anchored on a test suite); every other kind still requires tsId, and any 0.4.0- or 0.4.1-valid record remains valid. From 0.4.4 the manifest carries two optional additive sections that host the blueprint-library mechanism: blueprints[] (applied-blueprints registry written by rcf blueprint add / remove / upgrade) and standards[] (standards-pack registry written at rcf init and rcf standards add). From 0.4.5 the manifest additionally carries an optional resolutions[] section: one entry per operator-authored resolution of a cross-blueprint conflict, keyed at first by the globalAdrTopic conflict class (two applied blueprints each contributing a scope:global ADR on the same topic, resolved by a project-level ADR that supersedes both). Written by rcf blueprint supersede and by rcf blueprint add --resolve; read by the conflict detector so the resolved conflict is honoured and both blueprint ADRs may co-reside as superseded history. From 0.5.1 the appliedBlueprintRecord carries an optional libraryPrefix (blueprintSlug), stamped when an apply resolves through a registered external blueprint library so the library-registered ownership is durable on the record itself rather than derived by string-matching source; absent for shelf or path applies. From 0.6.3 the manifest additionally carries an optional shipWithoutEval[] section written by rcf finalise --ship-without-eval (sister of shipWithoutVerified; acknowledges EVAL-MISSING or EVAL-BELOW-THRESHOLD per-AC verdicts on the verify report and carries the operator's reason string); and the browserVerificationProbePackCheck item accepts an optional applicable:boolean flag, letting a check-level appliesTo predicate record applicable:false without a verdict or severity (aggregate verdict treats such a check as neither pass nor fail). From 0.7.0 the testTheatreFinding kind enum additionally accepts journeyStub (sibling of uiBaselineDrift), carried by the build-review surface when the FBS-to-discovery-journey binding is incomplete; the enum extension is additive, every 0.6.3-valid finding keeps validating. Every added field is optional; pre-0.4.0 manifests remain valid.",
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "projectName", "prd", "tad", "bs"],
@@ -214,9 +214,10 @@
             "assertionStrengthWeak",
             "acIdsCoverageDrift",
             "uiBaselineDrift",
+            "journeyStub",
             "otherDeclared"
           ],
-          "description": "Category of the finding. uiBaselineDrift is added by the UI-design-gate track for FBS implementations that contradict a uiBaseline default. otherDeclared requires a kindDescription."
+          "description": "Category of the finding. uiBaselineDrift is added by the UI-design-gate track for FBS implementations that contradict a uiBaseline default. journeyStub (added 0.7.0) is raised by the build-review surface when the FBS-to-journey binding (fbs.journeyStepIds[] against the discovery journey record) is incomplete: a discovery step with no FBS binding, or a UI-bearing FBS whose journeyStepIds[] is empty. Previously these cases went out as otherDeclared with a `journeyStub:` detail prefix; the dedicated kind lets consumers key on it without parsing the detail string. otherDeclared requires a kindDescription."
         },
         "kindDescription": {
           "type": "string",
@@ -235,7 +236,12 @@
       },
       "allOf": [
         {
-          "if": { "properties": { "kind": { "const": "uiBaselineDrift" } }, "required": ["kind"] },
+          "if": {
+            "anyOf": [
+              { "properties": { "kind": { "const": "uiBaselineDrift" } }, "required": ["kind"] },
+              { "properties": { "kind": { "const": "journeyStub" } }, "required": ["kind"] }
+            ]
+          },
           "then": {},
           "else": {
             "properties": {