@stravica-ai/rcf-schemas 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.4.5 - 2026-08-19
+
+Additive patch bump for the blueprint conflict-resolution mechanism landing in `rcf-lite` Phase 3.5. Adds the schema seam the `rcf blueprint supersede` and `rcf blueprint add --resolve` verbs key to, so a project can record an operator ruling that resolves a cross-blueprint conflict on a scope:global ADR topic. Every change is additive: every 0.4.4-valid document remains valid, and every existing id continues to validate byte-for-byte.
+
+### Added
+
+- **`manifest.schema.json`**: new optional `resolutions[]` at top level, items `$defs.blueprintConflictResolution`. One entry per operator-authored resolution of a cross-blueprint conflict. Fields: `id` (`^res-YYYY-MM-DD-NNN$`), `createdAt`, `kind` (single-valued enum `globalAdrTopic`; the enum is deliberately single-valued so later minor bumps can add further resolution classes additively without breaking existing consumers), `topic` (the topic key the resolution applies to, matching both superseded blueprint ADRs), `resolvedByAdrId` (the project-level ADR id that supersedes the blueprint ADRs), `supersedes[]` (min 2 items, each `{ slug: blueprintSlug, adrId: string }`), and optional `reason` (operator note). Written by `rcf blueprint supersede` and `rcf blueprint add --resolve`; read by the conflict detector so a would-be conflict on a resolved topic is honoured and both blueprint ADRs may co-reside as superseded history.
+- Fixtures (valid): `fixtures/valid/manifest/manifest-012-blueprint-topic-resolution.json` (two applied blueprints whose global auth ADRs collide, resolved by a project-level ADR that supersedes both).
+- Fixtures (invalid): `fixtures/invalid/manifest/manifest-020-resolution-bad-id.json` (resolution id in the wrong shape), `fixtures/invalid/manifest/manifest-021-resolution-single-supersedes.json` (supersedes[] with a single entry, violating minItems 2).
+- Tests: `resolutions[]` cases added to `manifest.test.js` covering the happy path (required fields, with reason, three superseded ADRs, additive composition alongside `blueprints[]` and `standards[]`), the reject-cases (bad id shape, missing required fields, unknown kind, `supersedes[]` minItems 2, uppercase slug in a `supersedes[]` entry, missing `adrId`, and an unrecognised additional property under `additionalProperties: false`), plus a pre-0.4.5 back-compat case that keeps a `blueprints[]`+`standards[]` manifest with no `resolutions[]` valid.
+
+### Notes
+
+- Additive-only: every 0.4.4-valid document remains valid. The prior `blueprints[]` + `standards[]` shape is untouched.
+- `back-compat-freeze.test.js` (added in 0.4.4) continues to assert the frozen pre-0.4.3 chain snapshot validates byte-for-byte; the 0.4.5 additions are new-fields-only and cannot affect existing document bytes.
+- Canonical `$id` URLs stay at `v0.4.0`, following the patch-release precedent set at 0.2.1, 0.3.1, 0.4.1, 0.4.2, 0.4.3, and 0.4.4.
+- Version choice: additive change, no existing document invalidated, no shape widened destructively — per repo precedent this bumps `0.4.4 -> 0.4.5` as a patch.
+
 ## 0.4.4 - 2026-08-18
 
 Additive patch bump for the blueprint-library mechanism landing in `rcf-build-lite`. Unblocks Phase 1 of the blueprint programme (`w-2026-08-18-016`) by adding the schema seams the mechanism keys to. Every change is additive: every 0.4.3-valid document remains valid, and every existing id continues to validate byte-for-byte.

package/fixtures/invalid/manifest/manifest-020-resolution-bad-id.json

@@ -0,0 +1,20 @@
+{
+  "version": "2.0.0",
+  "projectName": "Bad resolution id",
+  "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" },
+  "resolutions": [
+    {
+      "id": "resolution-1",
+      "createdAt": "2026-08-19T10:15:00Z",
+      "kind": "globalAdrTopic",
+      "topic": "auth",
+      "resolvedByAdrId": "ADR-042",
+      "supersedes": [
+        { "slug": "spa",  "adrId": "ADR-005-spa" },
+        { "slug": "rest", "adrId": "ADR-003-rest" }
+      ]
+    }
+  ]
+}

package/fixtures/invalid/manifest/manifest-021-resolution-single-supersedes.json

@@ -0,0 +1,19 @@
+{
+  "version": "2.0.0",
+  "projectName": "Resolution with a single supersedes entry (minItems 2 violation)",
+  "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" },
+  "resolutions": [
+    {
+      "id": "res-2026-08-19-001",
+      "createdAt": "2026-08-19T10:15:00Z",
+      "kind": "globalAdrTopic",
+      "topic": "auth",
+      "resolvedByAdrId": "ADR-042",
+      "supersedes": [
+        { "slug": "spa", "adrId": "ADR-005-spa" }
+      ]
+    }
+  ]
+}

package/fixtures/valid/manifest/manifest-012-blueprint-topic-resolution.json

@@ -0,0 +1,41 @@
+{
+  "version": "2.0.0",
+  "projectName": "Composed SPA + REST project with a resolved auth conflict",
+  "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" },
+  "blueprints": [
+    {
+      "slug": "spa",
+      "version": "1.0.0",
+      "appliedAt": "2026-08-19T10:00:00Z",
+      "source": "@stravica-ai/rcf-blueprint-spa@1.0.0",
+      "contributions": [
+        { "id": "ADR-005-spa", "path": "rcf/adrs/adr-005-spa.json", "kind": "adr", "scope": "global", "topic": "auth" }
+      ]
+    },
+    {
+      "slug": "rest",
+      "version": "1.0.0",
+      "appliedAt": "2026-08-19T10:00:05Z",
+      "source": "@stravica-ai/rcf-blueprint-rest@1.0.0",
+      "contributions": [
+        { "id": "ADR-003-rest", "path": "rcf/adrs/adr-003-rest.json", "kind": "adr", "scope": "global", "topic": "auth" }
+      ]
+    }
+  ],
+  "resolutions": [
+    {
+      "id": "res-2026-08-19-001",
+      "createdAt": "2026-08-19T10:15:00Z",
+      "kind": "globalAdrTopic",
+      "topic": "auth",
+      "resolvedByAdrId": "ADR-042",
+      "supersedes": [
+        { "slug": "spa",  "adrId": "ADR-005-spa" },
+        { "slug": "rest", "adrId": "ADR-003-rest" }
+      ],
+      "reason": "Project auth model is documented in ADR-042; both blueprint auth ADRs remain on disk as superseded history."
+    }
+  ]
+}

package/package.json

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schemas.stravica.io/rcf/v0.4.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). 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. Every added field is optional; pre-0.4.0 manifests remain valid.",
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "projectName", "prd", "tad", "bs"],
@@ -65,6 +65,11 @@
       "type": "array",
       "items": { "$ref": "#/$defs/standardsPackRecord" },
       "description": "Standards-pack registry. One entry per standards folder registered at rcf init (or later via rcf standards add). Records the pack's id, slug, source path, optional copy path (present only when the source lived outside the project root and was copied into rcf/standards/<slug>/ for portability), tag vocabulary, testsProvidedBy classification, and provenance. Read by the bundle assembler's selective-retrieval step when populating fbs.contextRequirements.standardIds. Optional; projects that register no standards have no entries."
+    },
+    "resolutions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/blueprintConflictResolution" },
+      "description": "Operator-authored resolutions of cross-blueprint conflicts. One entry per resolved conflict. Written by rcf blueprint supersede (which also scaffolds the project-level ADR that supersedes both blueprint ADRs) and by rcf blueprint add --resolve (which records the resolution declaratively on the add itself). Read by the conflict detector at rcf blueprint add: a resolution whose kind and key match a would-be conflict causes the detector to honour the resolution and let both blueprint ADRs co-reside as superseded history. Optional; projects with no cross-blueprint conflicts have no entries."
     }
   },
   "$defs": {
@@ -870,6 +875,59 @@
         }
       },
       "description": "One standards-pack registration. Written by rcf init (during standards prompting) and rcf standards add; read by the bundle assembler's selective-retrieval step."
+    },
+    "blueprintConflictResolution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "createdAt", "kind", "topic", "resolvedByAdrId", "supersedes"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^res-\\d{4}-\\d{2}-\\d{2}-\\d{3}$",
+          "description": "Blueprint-conflict-resolution record id. Format: res-YYYY-MM-DD-NNN. Monotonic per project."
+        },
+        "createdAt": { "$ref": "https://schemas.stravica.io/rcf/v0.4.0/common.schema.json#/$defs/timestamp" },
+        "kind": {
+          "enum": ["globalAdrTopic"],
+          "description": "Which conflict class this record resolves. Currently the only kind is globalAdrTopic (two applied blueprints each contributing a scope:global ADR on the same topic). The enum is single-valued so a later minor bump can add further resolution classes additively without breaking existing consumers."
+        },
+        "topic": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The topic key the resolution applies to (for example, 'auth', 'versioning', 'errorEnvelope'). Matches the topic on both superseded blueprint ADRs. Required for kind=globalAdrTopic; the conflict detector reads this to know which would-be conflict the record honours."
+        },
+        "resolvedByAdrId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The project-level ADR id that supersedes the blueprint ADRs (for example, ADR-042). Its file lives outside any applied blueprint's namespace and is authored at rcf blueprint supersede time. Provenance for the resolution; the conflict detector does not currently re-read the referenced ADR."
+        },
+        "supersedes": {
+          "type": "array",
+          "minItems": 2,
+          "items": { "$ref": "#/$defs/blueprintConflictResolutionSupersededAdr" },
+          "description": "The blueprint ADRs this resolution supersedes. Two entries at minimum: the two applied blueprints whose global ADRs collided on topic. Both blueprint ADRs co-reside on disk as superseded history; the resolvedByAdrId is the live decision."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional operator note recording why this resolution was chosen. Free text; the schema does not enforce a minimum floor here so the operator can record a terse one-liner when the resolvedByAdrId itself carries the reasoning."
+        }
+      },
+      "description": "One blueprint-conflict resolution. Written by rcf blueprint supersede (scaffolds the resolvedByAdrId and appends the record) and by rcf blueprint add --resolve (appends the record without scaffolding a new ADR). Read by the conflict detector to skip a would-be conflict when a resolution matches."
+    },
+    "blueprintConflictResolutionSupersededAdr": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "adrId"],
+      "properties": {
+        "slug": { "$ref": "https://schemas.stravica.io/rcf/v0.4.0/common.schema.json#/$defs/blueprintSlug" },
+        "adrId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The blueprint-owned ADR id that is superseded (for example, spa-ADR-005 or ADR-005-spa). Kept as a free-string minLength: 1 so the shape does not have to encode the mixed prefix/suffix namespacing grammar."
+        }
+      },
+      "description": "One superseded blueprint ADR: the applied blueprint's slug plus the ADR id inside that blueprint's contribution set."
     }
   }
 }