rcf-lite 0.18.0 → 0.20.0

package/rcf/requirements/req-016.json

@@ -0,0 +1,37 @@
+{
+  "createdAt": "2026-09-04T16:21:15.850Z",
+  "updatedAt": "2026-09-04T16:22:11.909Z",
+  "description": "rcf-schemas 0.6.0 lands the EVAL doc type and the AC-level determinism marker. rcf-lite consumes both: rcf audit eval coverage as a sibling of rcf audit coverage, EVAL-MISSING and EVAL-BELOW-THRESHOLD as per-AC verdicts on the verify report, finalise refusal with a mandatory-reason ship-without-eval opt-out, and a determinism flag on rcf define create ac plus the LLM-as-judge subprocess spawn wired to a runRecord entry on the EVAL doc. The eval-node discipline lives in the schema tier; rcf-lite is the first consumer to make it observable at every stage of the build cycle.",
+  "reqId": "REQ-016",
+  "prdId": "PRD-001",
+  "title": "rcf-schemas 0.6.0 EVAL node: consumer wiring in rcf-lite (audit / verify / finalise / define)",
+  "category": "functional",
+  "domain": "schemas",
+  "priority": "must",
+  "version": "0.1.0",
+  "status": "draft",
+  "shapeClassification": {
+    "shapes": [
+      "persistence"
+    ],
+    "reason": "keyword-scan",
+    "classifiedAt": "2026-09-04T16:21:15.868Z",
+    "signals": [
+      {
+        "source": "title",
+        "shape": "persistence",
+        "match": "schema"
+      },
+      {
+        "source": "description",
+        "shape": "persistence",
+        "match": "schema"
+      },
+      {
+        "source": "description",
+        "shape": "persistence",
+        "match": "schema"
+      }
+    ]
+  }
+}

package/rcf/test-suites/ts-038.json

@@ -0,0 +1,41 @@
+{
+  "id": "TS-038",
+  "usId": "US-1301",
+  "title": "observability-logging v1.0.0 ships on the core shelf with the ratified anatomy and applies clean",
+  "purpose": "Cover the three ACs on US-1301: shipped anatomy (blueprint.json + contributions + README + guide + docs/topics.md + assets), clean apply into a fresh fixture, and shelf-canonical logging global topic on ADR-1601 with providesRoles logging.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1301-1",
+    "AC-1301-2",
+    "AC-1301-3"
+  ],
+  "testCases": [
+    {
+      "id": "TC-038-blueprint-json-fields",
+      "acId": "AC-1301-1",
+      "description": "blueprints/observability-logging/blueprint.json declares slug, version 1.0.0, category observability, providesRoles [\"logging\"], and includes contributions for REQ-001..005, US-15101..15108, TAC-1601, TAC-1602 and ADR-1601..1604 with ADR-1601 carrying scope global and topic logging.",
+      "testPointer": "test/blueprint/observability-logging-anatomy.test.js::observability-logging: blueprint.json declares the ratified shape (TC-038-blueprint-json-fields)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-038-clean-apply",
+      "acId": "AC-1301-2",
+      "description": "rcf define blueprint add against a fresh fixture applies observability-logging cleanly (exit 0), records manifest.blueprints[] with slug observability-logging at 1.0.0, and writes rcf/adr/adr-1601-observability-logging-line-shape.json.",
+      "testPointer": "test/blueprint/observability-logging-anatomy.test.js::observability-logging: apply into a fresh fixture succeeds and writes the namespaced contributions (TC-038-clean-apply)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-038-anatomy-and-topics",
+      "acId": "AC-1301-3",
+      "description": "The blueprint anatomy is complete: README.md carries the Apply block and Known mechanism-reach gaps section; docs/topics.md names the logging global topic string and records the 15101-15899 band with 16xx suffix block; guide/observability-logging.md exists.",
+      "testPointer": "test/blueprint/observability-logging-anatomy.test.js::observability-logging: anatomy files exist with the required sections (TC-038-anatomy-and-topics)",
+      "status": "pending",
+      "scope": "library"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/test-suites/ts-039.json

@@ -0,0 +1,41 @@
+{
+  "id": "TS-039",
+  "usId": "US-1302",
+  "title": "application-error-handling v1.0.0 ships on the core shelf with providesRoles errorHandling and mints the errorHandling global topic distinct from errorEnvelope",
+  "purpose": "Cover the three ACs on US-1302: shipped anatomy and blueprint.json fields, clean apply into a fresh fixture, and errorHandling vs errorEnvelope topic distinction.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1302-1",
+    "AC-1302-2",
+    "AC-1302-3"
+  ],
+  "testCases": [
+    {
+      "id": "TC-039-blueprint-json-fields",
+      "acId": "AC-1302-1",
+      "description": "blueprints/application-error-handling/blueprint.json declares slug, version 1.0.0, category application, providesRoles [\"errorHandling\"], and includes contributions for REQ-001..004, US-16101..16107, TAC-1701, TAC-1702 and ADR-1701..1703 with ADR-1701 carrying scope global and topic errorHandling.",
+      "testPointer": "test/blueprint/application-error-handling-anatomy.test.js::application-error-handling: blueprint.json declares the ratified shape (TC-039-blueprint-json-fields)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-039-clean-apply",
+      "acId": "AC-1302-2",
+      "description": "rcf define blueprint add applies application-error-handling cleanly into a fresh fixture, records manifest.blueprints[] with the slug at 1.0.0, and writes rcf/adr/adr-1701-application-error-handling-record-shape.json.",
+      "testPointer": "test/blueprint/application-error-handling-anatomy.test.js::application-error-handling: apply into a fresh fixture succeeds and writes the namespaced contributions (TC-039-clean-apply)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-039-topics-distinct",
+      "acId": "AC-1302-3",
+      "description": "docs/topics.md distinguishes errorHandling from errorEnvelope (errorHandling internal record and boundary; errorEnvelope stays with application-api-rest as REST wire shape) and reserves the 16101-16899 band with 17xx suffix block.",
+      "testPointer": "test/blueprint/application-error-handling-anatomy.test.js::application-error-handling: docs/topics.md distinguishes errorHandling from errorEnvelope (TC-039-topics-distinct)",
+      "status": "pending",
+      "scope": "library"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/test-suites/ts-040.json

@@ -0,0 +1,57 @@
+{
+  "id": "TS-040",
+  "usId": "US-1401",
+  "title": "Loader accepts providesRoles and suggestedCompanions with shape validation and paired-ADR gate",
+  "purpose": "Cover the three ACs on US-1401: accepted shape (both fields optional and independent), refusal shapes for camelCase pattern / empty reason / em-dash / emoji, paired-scope-global-ADR gate.",
+  "testLevel": "unit",
+  "acIds": [
+    "AC-1401-1",
+    "AC-1401-2",
+    "AC-1401-3"
+  ],
+  "testCases": [
+    {
+      "id": "TC-040-loader-accepts-both",
+      "acId": "AC-1401-1",
+      "description": "loadBlueprint against a fixture declaring providesRoles: [\"logging\"] and suggestedCompanions: [{role: \"logging\", reason: \"...\"}] returns the fields on the LoadedBlueprint object; a fixture declaring neither also loads clean.",
+      "testPointer": "test/blueprint/loader-companions.test.js::loader accepts and preserves providesRoles and suggestedCompanions (AC-1401-1)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-040-refuse-bad-camelcase",
+      "acId": "AC-1401-2",
+      "description": "loadBlueprint refuses a fixture declaring providesRoles: [\"Logging\"] (upper camel) with rcfError kind validation naming providesRoles[0] and the offending value.",
+      "testPointer": "test/blueprint/loader-companions.test.js::loader refuses providesRoles value that fails the lower camelCase pattern (AC-1401-2)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-040-refuse-empty-reason",
+      "acId": "AC-1401-2",
+      "description": "loadBlueprint refuses a fixture with suggestedCompanions entry whose reason is empty or whitespace-only.",
+      "testPointer": "test/blueprint/loader-companions.test.js::loader refuses suggestedCompanions entry with empty or whitespace-only reason (AC-1401-2)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-040-refuse-em-dash-and-emoji",
+      "acId": "AC-1401-2",
+      "description": "loadBlueprint refuses a fixture with an em-dash (U+2014) or an emoji in the reason string.",
+      "testPointer": "test/blueprint/loader-companions.test.js::loader refuses em-dash in suggestedCompanions reason (AC-1401-2)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-040-paired-adr-required",
+      "acId": "AC-1401-3",
+      "description": "loadBlueprint refuses a fixture declaring providesRoles: [\"logging\"] but no scope:global ADR carrying topic 'logging' with the exact paired-ADR refusal message.",
+      "testPointer": "test/blueprint/loader-companions.test.js::loader refuses providesRoles without a paired scope:global ADR on the topic string (AC-1401-3)",
+      "status": "pending",
+      "scope": "library"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/test-suites/ts-041.json

@@ -0,0 +1,57 @@
+{
+  "id": "TS-041",
+  "usId": "US-1402",
+  "title": "rcf define blueprint add prints resolved companion suggestions and honours --companion / --no-companion-suggestions with persistence to rcf/companions.json",
+  "purpose": "Cover the three ACs on US-1402: apply-time suggestion block and its suppression, --companion selectors and refusal for non-providers, companions.json shape and pin overwrite behaviour.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1402-1",
+    "AC-1402-2",
+    "AC-1402-3"
+  ],
+  "testCases": [
+    {
+      "id": "TC-041-suggestion-block",
+      "acId": "AC-1402-1",
+      "description": "rcf define blueprint add application-api-rest into a fresh fixture prints the header line and one line per suggested role with the origin annotation; the apply does not adopt any companion.",
+      "testPointer": "test/cli/blueprint-companions.test.js::apply prints resolved companion suggestion block after success (TC-041-suggestion-block)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-041-no-suggestions-flag",
+      "acId": "AC-1402-1",
+      "description": "rcf define blueprint add application-api-rest --no-companion-suggestions succeeds and produces no suggestion block on stdout.",
+      "testPointer": "test/cli/blueprint-companions.test.js::--no-companion-suggestions suppresses the block (TC-041-no-suggestions-flag)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-041-companion-flag-writes-pin",
+      "acId": "AC-1402-2",
+      "description": "rcf define blueprint add application-api-rest --companion logging=observability-logging --companion errorHandling=application-error-handling writes rcf/companions.json with both pins carrying pinnedAt.",
+      "testPointer": "test/cli/blueprint-companions.test.js::--companion selectors write rcf/companions.json pins with pinnedAt (TC-041-companion-flag-writes-pin)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-041-companion-flag-non-provider",
+      "acId": "AC-1402-2",
+      "description": "rcf define blueprint add --companion logging=observability-essentials (which does not declare providesRoles containing logging) refuses exit 2 with the specified message shape.",
+      "testPointer": "test/cli/blueprint-companions.test.js::--companion naming a non-provider refuses exit 2 with no side effects (TC-041-companion-flag-non-provider)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-041-pin-file-shape-and-overwrite",
+      "acId": "AC-1402-3",
+      "description": "rcf/companions.json is created lazily with schemaVersion 1 and current-pin-only shape; a re-run with a different --companion value overwrites the pin and prints the pin-transition stderr line.",
+      "testPointer": "test/cli/blueprint-companions.test.js::rcf/companions.json shape and pin overwrite prints transition line (TC-041-pin-file-shape-and-overwrite)",
+      "status": "pending",
+      "scope": "library"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/test-suites/ts-042.json

@@ -0,0 +1,57 @@
+{
+  "id": "TS-042",
+  "usId": "US-1403",
+  "title": "rcf define blueprint companions <slug>|set|unset verb: text output, --json envelope, exit codes",
+  "purpose": "Cover the three ACs on US-1403: <slug> resolution printing with origin annotations, set/unset pin round-trip and refusals, --json envelope on all three sub-verbs.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1403-1",
+    "AC-1403-2",
+    "AC-1403-3"
+  ],
+  "testCases": [
+    {
+      "id": "TC-042-companions-slug-text",
+      "acId": "AC-1403-1",
+      "description": "rcf define blueprint companions application-api-rest with application-api-rest applied prints the header and one line per role with the origin annotations already-applied / shelf-fallback / registered-library.",
+      "testPointer": "test/cli/blueprint-companions.test.js::rcf define blueprint companions <slug> prints resolved companions with origin (TC-042-companions-slug-text)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-042-companions-slug-not-applied",
+      "acId": "AC-1403-1",
+      "description": "rcf define blueprint companions <slug> refuses exit 2 when the named slug is not applied on the project.",
+      "testPointer": "test/cli/blueprint-companions.test.js::rcf define blueprint companions refuses when slug is not applied (TC-042-companions-slug-not-applied)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-042-companions-set-unset-round-trip",
+      "acId": "AC-1403-2",
+      "description": "rcf define blueprint companions set logging observability-logging writes companions.json; rcf define blueprint companions unset logging removes the entry; an unset without a pin refuses exit 2.",
+      "testPointer": "test/cli/blueprint-companions.test.js::companions set writes pin and unset removes it; unset without pin refuses (TC-042-companions-set-unset-round-trip)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-042-companions-set-refuses-non-provider",
+      "acId": "AC-1403-2",
+      "description": "rcf define blueprint companions set logging observability-essentials refuses exit 2 because observability-essentials does not declare providesRoles containing logging.",
+      "testPointer": "test/cli/blueprint-companions.test.js::companions set refuses non-provider slug (TC-042-companions-set-refuses-non-provider)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-042-companions-json-envelope",
+      "acId": "AC-1403-3",
+      "description": "rcf define blueprint companions application-api-rest --json emits {slug, suggestions: [{role, provider, origin, notes}]} preserving the order of suggestedCompanions[].",
+      "testPointer": "test/cli/blueprint-companions.test.js::--json emits machine-readable envelope preserving suggestedCompanions order (TC-042-companions-json-envelope)",
+      "status": "pending",
+      "scope": "library"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/test-suites/ts-043.json

@@ -0,0 +1,49 @@
+{
+  "id": "TS-043",
+  "usId": "US-1404",
+  "title": "Resolution rule tier ladder, two-libraries refusal exit 3, and validate refusal for unresolvable pin",
+  "purpose": "Cover the three ACs on US-1404: deterministic tier ladder (applied > registered library > core shelf) with pin override, two-libraries-one-role refusal message shape on both add and companions verb, validate refusal for a pin naming no known provider.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1404-1",
+    "AC-1404-2",
+    "AC-1404-3"
+  ],
+  "testCases": [
+    {
+      "id": "TC-043-resolver-tier-ladder",
+      "acId": "AC-1404-1",
+      "description": "The resolveCompanions function returns origin already-applied when a provider is applied, registered-library-<prefix> when one library provides it, shelf-fallback when only the core shelf provides it, and pinned when rcf/companions.json overrides.",
+      "testPointer": "test/blueprint/companions-resolver.test.js::resolver returns shelf-fallback when only the core shelf provides the role",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-043-two-libraries-refuse-exit-3",
+      "acId": "AC-1404-2",
+      "description": "With two registered libraries both providing role logging and no pin, rcf define blueprint add on a service blueprint refuses exit 3 with the ambiguous-role message naming both library slugs and the three resolution paths verbatim.",
+      "testPointer": "test/cli/blueprint-companions.test.js::two libraries providing one role refuse exit 3 with three-path resolution message (TC-043-two-libraries-refuse-exit-3)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-043-two-libraries-on-companions-verb",
+      "acId": "AC-1404-2",
+      "description": "The same two-libraries-one-role case on rcf define blueprint companions <slug> refuses exit 3 with the same three-path resolution message.",
+      "testPointer": "test/cli/blueprint-companions.test.js::rcf define blueprint companions refuses exit 3 when two libraries provide same role (TC-043-two-libraries-on-companions-verb)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-043-validate-refuses-unresolvable-pin",
+      "acId": "AC-1404-3",
+      "description": "rcf define validate refuses exit 3 when rcf/companions.json pins a role to a slug that no applied blueprint, no registered library, and no shelf blueprint provides; message shape names the exact role and slug.",
+      "testPointer": "test/cli/validate-companions-pin.test.js::validate refuses exit 3 when a companions.json pin names an unresolvable provider (TC-043-validate-refuses-unresolvable-pin)",
+      "status": "pending",
+      "scope": "library"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/test-suites/ts-044.json

@@ -0,0 +1,41 @@
+{
+  "id": "TS-044",
+  "usId": "US-1501",
+  "title": "Loader validates standardsTrace with the standardsTraceClause discipline; refuses missing clause without cross-checking severity",
+  "purpose": "Cover the three ACs on US-1501: loader acceptance of standardsTrace/recommendedDefault/elicited/standardsTraceClause, refusal message shape when standardsTrace is declared and any ADR lacks a standardsTraceClause, and no-cross-check on MUST-to-kind mapping.",
+  "testLevel": "unit",
+  "acIds": [
+    "AC-1501-1",
+    "AC-1501-2",
+    "AC-1501-3"
+  ],
+  "testCases": [
+    {
+      "id": "TC-044-loader-accepts-standards-fields",
+      "acId": "AC-1501-1",
+      "description": "loadBlueprint on a fixture with standardsTrace [{id: WSD-001, version: 2026-05}] and one ADR contribution carrying recommendedDefault true and standardsTraceClause 'WSD-001 clause 3.1' returns the fields on the LoadedBlueprint object; no rcfError.",
+      "testPointer": "test/blueprint/loader-standards-trace.test.js::loader accepts standardsTrace and recommendedDefault/elicited/standardsTraceClause (AC-1501-1)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-044-loader-refuses-missing-clause",
+      "acId": "AC-1501-2",
+      "description": "loadBlueprint refuses a fixture declaring standardsTrace but with one ADR contribution missing standardsTraceClause; rcfError kind validation with the exact refusal message shape.",
+      "testPointer": "test/blueprint/loader-standards-trace.test.js::loader refuses missing standardsTraceClause when standardsTrace is declared (AC-1501-2)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-044-no-cross-check-and-sentinel",
+      "acId": "AC-1501-3",
+      "description": "The two new core companion blueprints (observability-logging, application-error-handling), which declare NO standardsTrace, load clean regardless of standardsTraceClause presence; a fixture with standardsTrace declared and every ADR carrying 'generic enterprise practice' loads clean; the loader does not refuse a MUST-marked ADR (no cross-check of clause severity to kind, per amendment A2).",
+      "testPointer": "test/blueprint/loader-standards-trace.test.js::no cross-check on severity; sentinel and no-standardsTrace baseline both load clean (AC-1501-3)",
+      "status": "pending",
+      "scope": "library"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/test-suites/ts-045.json

@@ -0,0 +1,46 @@
+{
+  "createdAt": "2026-09-04T16:22:23.766Z",
+  "updatedAt": "2026-09-04T17:21:35.618Z",
+  "purpose": "Cover the four ACs on US-1601 via the unit and integration suites landed in this train. L1 through L3 are deterministic tests over pure or seam-injected code paths; L4 tests the judge invocation shape via a stubbed spawn seam (a real subprocess round-trip is exercised out-of-band as the section 11 real-claude smoke).",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1601-1",
+    "AC-1601-2",
+    "AC-1601-3",
+    "AC-1601-4"
+  ],
+  "id": "TS-045",
+  "usId": "US-1601",
+  "title": "rcf-lite consumer wiring for the rcf-schemas 0.6.0 EVAL node",
+  "testCases": [
+    {
+      "id": "TC-045-computeevalcoverage-across-the-four",
+      "acId": "AC-1601-1",
+      "description": "computeEvalCoverage across the four outcome buckets (covered, covered-optional, missing, not-required) and the classifyEvalDoc pending/superseded/resolving classification",
+      "status": "pending",
+      "testPointer": "test/query/eval-coverage.test.js::nonDeterministic AC without a bound EVAL reports missing and fails the gate"
+    },
+    {
+      "id": "TC-045-per-ac-verdicts-carries-the-two-new-eval",
+      "acId": "AC-1601-2",
+      "description": "PER_AC_VERDICTS carries the two new EVAL classes; evalPerAcVerdict returns null for deterministic ACs; fires EVAL-MISSING when nonDeterministic AC has no resolving EVAL; fires EVAL-BELOW-THRESHOLD on a failing run",
+      "status": "pending",
+      "testPointer": "test/verify/verdict/eval-per-ac.test.js::derivePerAcVerdicts folds EVAL classes alongside the pre-existing per-AC verdicts"
+    },
+    {
+      "id": "TC-045-findevalrefusalacs-and",
+      "acId": "AC-1601-3",
+      "description": "findEvalRefusalAcs and reportHasEvalRefusal read the two EVAL classes off perAcVerdicts[]; composeShipWithoutEvalRecord carries the operator reason and declared per-AC verdicts; nextShipWithoutEvalId increments monotonically",
+      "status": "pending",
+      "testPointer": "test/cli/finalise-eval-refusal.test.js::finalise --ship-without-eval \"harness offline\" exits 0 and appends a monotonic swe-* record on manifest.shipWithoutEval[]"
+    },
+    {
+      "id": "TC-045-runonecase-spawns-the-invoker-claude-or",
+      "acId": "AC-1601-4",
+      "description": "runOneCase spawns the invoker (claude or codex) via the seam, validates response against the declared schema, composeRunRecord verdict resolves to pass on met threshold and fail on critical criterion failure",
+      "status": "pending",
+      "testPointer": "test/eval/judge.test.js::runOneCase returns the parsed graded envelope on a valid response"
+    }
+  ],
+  "status": "draft"
+}

package/rcf/user-stories/us-1301.json

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-013",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Core shelf ships observability-logging v1.0.0 with providesRoles logging and the shelf-canonical logging global topic",
+  "asA": "operator running rcf define blueprint add on a fresh project that needs a general-enterprise-practice logging contract",
+  "iWant": "the shipped core shelf to carry an observability-logging blueprint (v1.0.0) that provides the logging role, mints the logging global topic on ADR-1601, and applies cleanly into a fixture project alongside every other shipped shelf blueprint",
+  "soThat": "a project falls back to a sensible logging contract without registering any library, the mechanism in REQ-014 has a shelf provider to resolve to, and the logging global topic has one owner on the shelf",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1301-1",
+      "description": "`blueprints/observability-logging/blueprint.json` exists with `slug: \"observability-logging\"`, `version: \"1.0.0\"`, `category: \"observability\"`, `providesRoles: [\"logging\"]`, and a contributions list carrying five REQs (`observability-logging-REQ-001` through `-REQ-005`), user stories in the 15101-15899 band (at least `-US-15101` through `-US-15108`), TACs `TAC-1601-observability-logging-logger-factory` and `TAC-1602-observability-logging-redaction-boundary`, and ADRs `ADR-1601` through `ADR-1604` including `ADR-1601-observability-logging-line-shape` with `scope: \"global\", topic: \"logging\"`.",
+      "given": "the shipped core shelf at packages/rcf-lite/blueprints/observability-logging (staged from the top-level blueprints/ directory)",
+      "when": "the loader reads blueprint.json and enumerates contributions[]",
+      "then": "the fields resolve to the values above and jq queries against blueprint.json return them verbatim",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1301-2",
+      "description": "`rcf define blueprint add <path>/blueprints/observability-logging` applied into a fresh fixture project with no prior applied blueprints succeeds (exit 0), writes `manifest.blueprints[]` with slug `observability-logging`, and copies the namespaced contribution files under `rcf/req/`, `rcf/userStory/`, `rcf/tac/` and `rcf/adr/`.",
+      "given": "a fresh fixture project initialised via `rcf init` with no applied blueprints",
+      "when": "the operator runs `rcf define blueprint add <path-to>/blueprints/observability-logging`",
+      "then": "the exit code is 0, `manifest.blueprints[]` lists observability-logging at version 1.0.0, and `rcf/adr/adr-1601-observability-logging-line-shape.json` exists on disk",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1301-3",
+      "description": "The blueprint anatomy is complete: `README.md`, `guide/observability-logging.md`, `docs/topics.md` and `assets/` are present at the blueprint root; the README carries an `Apply` block and a `Known mechanism-reach gaps` section; `docs/topics.md` names the `logging` global topic string with the shelf band 15101-15899 and 16xx suffix block recorded.",
+      "given": "the blueprint source directory on disk",
+      "when": "the reviewer walks the anatomy",
+      "then": "every named file exists, the docs/topics.md table includes the observability-logging row, and the README carries the two required sections",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/user-stories/us-1302.json

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1302",
+  "prdId": "PRD-001",
+  "reqId": "REQ-013",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Core shelf ships application-error-handling v1.0.0 with providesRoles errorHandling and mints the errorHandling global topic",
+  "asA": "operator running rcf define blueprint add on a fresh project that needs a transport-agnostic error-handling contract",
+  "iWant": "the shipped core shelf to carry an application-error-handling blueprint (v1.0.0) that provides the errorHandling role, mints the errorHandling global topic on ADR-1701 (distinct from errorEnvelope), and applies cleanly into a fixture project",
+  "soThat": "a project falls back to a sensible error-handling contract without registering any library, and the internal error record shape sits one project decision above any transport-specific error-envelope decision",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1302-1",
+      "description": "`blueprints/application-error-handling/blueprint.json` exists with `slug: \"application-error-handling\"`, `version: \"1.0.0\"`, `category: \"application\"`, `providesRoles: [\"errorHandling\"]`, and a contributions list carrying four REQs (`application-error-handling-REQ-001` through `-REQ-004`), user stories in the 16101-16899 band (at least `-US-16101` through `-US-16107`), TACs `TAC-1701-application-error-handling-boundary` and `TAC-1702-application-error-handling-record-factory`, and ADRs `ADR-1701` through `ADR-1703` including `ADR-1701-application-error-handling-record-shape` with `scope: \"global\", topic: \"errorHandling\"`.",
+      "given": "the shipped core shelf at packages/rcf-lite/blueprints/application-error-handling (staged from the top-level blueprints/ directory)",
+      "when": "the loader reads blueprint.json and enumerates contributions[]",
+      "then": "the fields resolve to the values above and jq queries return them verbatim",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1302-2",
+      "description": "`rcf define blueprint add <path>/blueprints/application-error-handling` applied into a fresh fixture project with no prior applied blueprints succeeds (exit 0), writes `manifest.blueprints[]` with slug `application-error-handling`, and copies the namespaced contribution files.",
+      "given": "a fresh fixture project initialised via `rcf init` with no applied blueprints",
+      "when": "the operator runs `rcf define blueprint add <path-to>/blueprints/application-error-handling`",
+      "then": "the exit code is 0, `manifest.blueprints[]` lists application-error-handling at version 1.0.0, and `rcf/adr/adr-1701-application-error-handling-record-shape.json` exists on disk",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1302-3",
+      "description": "The `errorHandling` topic is DISTINCT from `errorEnvelope`; the blueprint's docs/topics.md names both, distinguishes them (errorHandling is the internal record shape and uncaught-exception boundary; errorEnvelope stays with application-api-rest as the REST wire shape), and reserves the 16101-16899 band and 17xx suffix block for the shelf-wide registry.",
+      "given": "the blueprint's docs/topics.md file",
+      "when": "the reviewer reads the topic table",
+      "then": "the errorHandling and errorEnvelope rows are both present, distinct, and the band registry row is recorded",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/user-stories/us-1401.json

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1401",
+  "prdId": "PRD-001",
+  "reqId": "REQ-014",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Loader accepts and validates providesRoles[] and suggestedCompanions[] on blueprint.json (shape + camelCase + paired-ADR + reason-string)",
+  "asA": "blueprint author declaring a companion suggestion or a role provided on a shipped blueprint",
+  "iWant": "the loader to accept two additive top-level fields on blueprint.json, validate their shape at load time, and refuse a mis-authored file before the tree is touched",
+  "soThat": "a service blueprint can name the roles it recommends and a provider blueprint can name the roles it provides, and mis-shaped or unpaired declarations never reach apply",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1401-1",
+      "description": "The loader accepts optional top-level `providesRoles` (non-empty array of lower camelCase strings on the pattern `^[a-z][a-zA-Z0-9]*$`) and optional top-level `suggestedCompanions` (non-empty array of `{role, reason}` objects; `role` is a lower camelCase string; `reason` is a non-empty string with no em-dashes and no emojis). Both fields are independent (a blueprint may provide a role AND suggest another; a blueprint may declare neither). Existing shelf blueprints (application-spa v1.4.0 baseline, observability-essentials v2.0.0, etc.) that declare neither still load clean.",
+      "given": "a blueprint.json declaring `providesRoles: [\"logging\"]` and `suggestedCompanions: [{role: \"logging\", reason: \"...\"}]`",
+      "when": "the loader parses the file",
+      "then": "the LoadedBlueprint object carries both fields verbatim and returns no rcfError; a blueprint declaring neither loads clean",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1401-2",
+      "description": "The loader refuses (rcfError kind `validation`, exit 2 at the CLI edge) each of: a `providesRoles` value that fails the lower camelCase pattern (message names the offending index and value); a `suggestedCompanions` entry with a non-string or empty `role`; a `suggestedCompanions` entry with a missing, empty, or whitespace-only `reason`; a `suggestedCompanions` entry whose `reason` contains an em-dash (U+2014) or an emoji.",
+      "given": "four separate mis-authored blueprint.json fixtures, one per refusal shape",
+      "when": "the loader parses each",
+      "then": "each returns an rcfError of kind `validation` with a message naming the offending field and (for arrays) the index",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1401-3",
+      "description": "A blueprint that declares a role in `providesRoles[]` MUST also carry a `scope: \"global\"` ADR contribution whose `topic` string equals the role name; the loader refuses otherwise with `providesRoles[] names '<role>' but no scope:global ADR carries topic '<role>'.` and exits 2 at the CLI edge.",
+      "given": "a fixture blueprint with `providesRoles: [\"logging\"]` and no ADR contribution carrying `scope: \"global\", topic: \"logging\"`",
+      "when": "the loader parses the file",
+      "then": "the loader returns an rcfError of kind `validation` with the paired-ADR message exactly as specified",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

package/rcf/user-stories/us-1402.json

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1402",
+  "prdId": "PRD-001",
+  "reqId": "REQ-014",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "`rcf define blueprint add` prints resolved companion suggestions and accepts --companion selectors that persist to rcf/companions.json",
+  "asA": "operator running rcf define blueprint add on a service blueprint that declares suggestedCompanions[]",
+  "iWant": "the apply to print the resolved companion set as a suggestion block after a successful apply, and to accept `--companion <role>=<slug>` selectors that record my choice to rcf/companions.json for future runs",
+  "soThat": "the mechanism surfaces the suggestion at the moment of the apply, my explicit selection at apply time survives to future re-runs without repeating the flag, and the apply itself never adopts a companion on my behalf",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1402-1",
+      "description": "After `rcf define blueprint add <service-slug>` succeeds and the service blueprint declares `suggestedCompanions[]`, stdout carries a block: a header line `Suggested companions this blueprint recommends alongside it:` followed by one line per suggested role in the shape `  <role>          -> <resolved-provider> (<origin>)`, where origin reads `registered library '<prefix>'` or `shelf fallback` or `already applied`, and a footer line `Apply either with: rcf define blueprint add <slug>`. The apply itself does not adopt any companion (`manifest.blueprints[]` contains only the service blueprint and any prior applies). `--no-companion-suggestions` suppresses the block entirely and every other apply behaviour is unchanged.",
+      "given": "a fixture project with application-api-rest v2.1.0 (or later) applied cleanly and no core companions applied",
+      "when": "the operator runs `rcf define blueprint add <path-to>/blueprints/application-api-rest`",
+      "then": "the suggestion block prints for `logging` and `errorHandling` roles, manifest.blueprints[] carries only application-api-rest, and passing `--no-companion-suggestions` on the same command produces no suggestion block",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1402-2",
+      "description": "`rcf define blueprint add <service-slug> --companion <role>=<slug>` (repeatable) accepts `<libraryPrefix>:<slug>` for a library provider or a bare kebab slug for a shelf provider, validates that the named provider blueprint's `providesRoles[]` contains the role, refuses with exit 2 (`--companion <role>=<slug>: blueprint '<slug>' does not declare providesRoles containing '<role>'.`) when it does not, and writes the accepted choices to `rcf/companions.json` under `roles.<role>.provider` with a `pinnedAt` ISO-8601 timestamp.",
+      "given": "a fixture project with application-api-rest applying and the shelf observability-logging blueprint available",
+      "when": "the operator runs `rcf define blueprint add <path-to>/blueprints/application-api-rest --companion logging=observability-logging --companion errorHandling=application-error-handling`",
+      "then": "the exit code is 0, `rcf/companions.json` exists with `roles.logging.provider = \"observability-logging\"` and `roles.errorHandling.provider = \"application-error-handling\"`, and `--companion logging=observability-essentials` (a non-provider) refuses exit 2 with the specified message",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1402-3",
+      "description": "`rcf/companions.json` is created lazily on the first pin (no file when no pins exist), rides git, is human-readable JSON with `schemaVersion: 1`, and carries only the current pin per role (no per-apply history per amendment A1). A re-run of the same `rcf define blueprint add ... --companion ...` command overwrites the pin's `pinnedAt` timestamp but keeps the same provider; a `--companion` naming a different provider than the current pin overwrites the pin and prints one stderr line `[blueprint] companion pin for role '<role>' updated: '<old>' -> '<new>'`.",
+      "given": "a fixture project with an existing companions.json pin",
+      "when": "the operator re-runs the apply with the same or a different --companion selector",
+      "then": "the pin file schema stays valid, the shape matches the spec section 2.4 example (schemaVersion + roles + pinnedAt), and the pin overwrite prints the transition line",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}