rcf-lite 0.17.0 → 0.19.0

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/user-stories/us-1201.json

@@ -0,0 +1,34 @@
+{
+  "usId": "US-1201",
+  "prdId": "PRD-001",
+  "reqId": "REQ-012",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "observability-essentials + observability-probe-endpoints + application-api-rest compose cleanly in every ordering with no globalAdrTopic conflict on healthProbes or readinessSemantics",
+  "asA": "operator applying the three post-alignment observability + api-rest blueprints on one project in any order",
+  "iWant": "the three amended blueprints (essentials v2.0.0, probe-endpoints v1.1.0, api-rest v2.0.0) to apply cleanly in every ordering, with observability-probe-endpoints as the sole scope:global claimant of healthProbes and readinessSemantics in the resulting manifest",
+  "soThat": "a project that reaches for all three shipped blueprints inherits a single-owner probe-path surface without an operator-side supersede ADR or a manifest-editing follow-up",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1201-1",
+      "description": "Applying the three blueprints in every ordering (six permutations) into a freshly initialised project tree succeeds with no `globalAdrTopic` conflict on `healthProbes` or `readinessSemantics`; the resulting `rcf/manifest.json` carries all three blueprint records.",
+      "given": "a freshly initialised rcf-lite project tree and the three shipped blueprints at essentials v2.0.0, probe-endpoints v1.1.0, api-rest v2.0.0",
+      "when": "for each of the six permutations of the three blueprints, applyBlueprint runs three times in that order against a fresh project tree",
+      "then": "no ordering returns a `globalAdrTopic` conflict on healthProbes or readinessSemantics, and every ordering ends with manifest.blueprints containing observability-essentials, observability-probe-endpoints, and application-api-rest",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1201-2",
+      "description": "In the applied manifest, exactly one blueprint declares `scope: global` with `topic: healthProbes` (observability-probe-endpoints ADR-1501) and exactly one declares `scope: global` with `topic: readinessSemantics` (observability-probe-endpoints ADR-1502); zero from essentials, zero from api-rest.",
+      "given": "a project with all three amended blueprints applied",
+      "when": "manifest.blueprints[].contributions[] is walked for scope:global ADRs on the two topics",
+      "then": "the claimant list for healthProbes equals [\"observability-probe-endpoints\"] and the claimant list for readinessSemantics equals [\"observability-probe-endpoints\"]",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T00:00:00Z",
+  "updatedAt": "2026-09-04T00:00:00Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "US-1202",
+  "prdId": "PRD-001",
+  "reqId": "REQ-012",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "The applied tree carries no literal probe path (/healthz, /readyz, /healthz/*) outside observability-probe-endpoints prose",
+  "asA": "operator or reviewer grepping an applied project tree for literal probe paths after re-applying the three amended blueprints",
+  "iWant": "zero matches for /healthz, /readyz, /healthz/live, /healthz/ready or /healthz/startup in the applied `rcf/` tree, so the shelf ships one probe-path opinion (the resolved one) and no rogue literals",
+  "soThat": "a project that composes the three shipped blueprints never inherits a stale literal path binding that disagrees with the resolved probe path set",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1202-1",
+      "description": "Grepping the applied `rcf/` tree of a project that has re-applied observability-essentials v2.0.0 + observability-probe-endpoints v1.1.0 + application-api-rest v2.0.0 for the strings `/healthz/live`, `/healthz/ready`, `/healthz/startup`, `/healthz`, and `/readyz` returns zero matches across all contribution JSON files.",
+      "given": "a project with all three amended blueprints applied",
+      "when": "the applied `rcf/` tree is grepped for the five literal probe-path strings above",
+      "then": "the match count is zero (matches remain only in the source blueprint READMEs and guides for observability-probe-endpoints, never in the applied contribution JSON)",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T00:00:00Z",
+  "updatedAt": "2026-09-04T00:00:00Z"
+}

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

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1203",
+  "prdId": "PRD-001",
+  "reqId": "REQ-012",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Each amended blueprint carries the ratified alignment facts: probe-endpoints optional startup + composing section; essentials path-neutral REQs/TACs and PROBE_INTERFACE_PATHS_MISSING; api-rest defers all probe paths",
+  "asA": "reviewer walking the three amended blueprint source directories after the alignment lands",
+  "iWant": "each blueprint to carry the shape the spec ratified: observability-probe-endpoints v1.1.0 adds the optional startup path and a composing section; observability-essentials v2.0.0 restates REQ-001/002 and TAC-801/802 path-neutral and names the PROBE_INTERFACE_PATHS_MISSING boot refusal; application-api-rest v2.0.0 defers probe paths to the resolved set with a matching AC on the auth-exempt list and a startup AC that consumes the optional path",
+  "soThat": "a downstream project (or a gate reviewer walking the shelf) reads the ratified alignment off the source blueprints directly, without needing to reconstruct the intent from the spec",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1203-1",
+      "description": "observability-probe-endpoints/blueprint.json declares version 1.1.0. US-14102 carries a new AC-14102-4 naming the three-path resolution (/live, /ready, /startup) and the startup handler when `probeInterface.options.kubernetes.startup.enabled: true`. US-14107 carries a new AC-14107-4 naming the three-entry auth-exempt list when startup is enabled. ADR-1503 decision text names the startup.enabled flag, the same body shape, and the fused topology by default. `guide/observability-probe-endpoints.md` carries a \"Composing with observability-essentials and application-api-rest\" section naming the deferral pattern and the compose test at `packages/rcf-lite/test/blueprint/probe-path-alignment.test.js` as the ratified truth.",
+      "given": "the shipped observability-probe-endpoints blueprint source directory at HEAD",
+      "when": "blueprint.json, US-14102, US-14107, ADR-1503, and the guide are read",
+      "then": "blueprint.json version equals 1.1.0; AC-14102-4 and AC-14107-4 exist and name the startup path; ADR-1503 decision names startup.enabled; the guide carries the composing section naming the compose test path",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1203-2",
+      "description": "observability-essentials/blueprint.json declares version 2.0.0; the ADR-801 and ADR-802 contribution entries no longer carry `scope: \"global\"` or `topic`. REQ-001 and REQ-002 restate path-neutral and name `probeInterface.paths.liveness` / `probeInterface.paths.readiness` as the required configuration key. TAC-801 and TAC-802 mark the path as REQUIRED with no shipped default and name the `PROBE_INTERFACE_PATHS_MISSING` stable-coded boot refusal on the responsibilities list. US-7101 gains AC-7101-4 and US-7102 gains AC-7102-4 covering the boot-refusal-on-missing-config semantics. `docs/topics.md` shrinks the global-topics table to `statusPageContract` alone and records `healthProbes` and `readinessSemantics` in a \"Historical global topics (dropped in v2.0.0)\" section.",
+      "given": "the shipped observability-essentials blueprint source directory at HEAD",
+      "when": "blueprint.json, ADR-801, ADR-802, REQ-001, REQ-002, TAC-801, TAC-802, US-7101, US-7102, and docs/topics.md are read",
+      "then": "blueprint.json version equals 2.0.0; ADR-801/802 contribution entries carry no scope or topic field; REQ-001/002 name probeInterface.paths and refuses-boot; TAC-801/802 mark path as REQUIRED and name PROBE_INTERFACE_PATHS_MISSING; AC-7101-4 and AC-7102-4 exist; topics.md carries the Historical global topics section",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1203-3",
+      "description": "application-api-rest/blueprint.json declares version 2.0.0. REQ-006 restates path-neutral naming observability-probe-endpoints as the probe-path owner and probeInterface.paths as the essentials-alone fallback. US-2108 all eight ACs bind to \"the resolved liveness path\", \"the resolved readiness path\", or \"the resolved startup path\"; AC-2108-5 binds the auth-exempt assertion to the resolved probe path set (naming `getExemptPathSet` from TAC-1501). TAC-306 responsibilities restate the three probe surfaces at their resolved paths, drop the literal path strings, and name the auth-exempt consumption of the resolved set. US-2103 versioning-exemption AC no longer carries the literal `/healthz/*` and names the resolved probe paths instead.",
+      "given": "the shipped application-api-rest blueprint source directory at HEAD",
+      "when": "blueprint.json, REQ-006, US-2108 (all eight ACs), TAC-306, and US-2103 are read",
+      "then": "blueprint.json version equals 2.0.0; REQ-006 names probe-endpoints and probeInterface.paths as the two path-resolution sources; every US-2108 AC contains \"resolved\" and none contains a literal /healthz/* prefix; TAC-306 responsibilities name the resolved probe path set and getExemptPathSet or probeInterface.paths; US-2103 no longer contains /healthz/*",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T00:00:00Z",
+  "updatedAt": "2026-09-04T00:00:00Z"
+}

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

@@ -0,0 +1,25 @@
+{
+  "usId": "US-1204",
+  "prdId": "PRD-001",
+  "reqId": "REQ-012",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Operator running `rcf define blueprint remove-resolution <adr-id>` drops a redundant historical resolutions[] entry cleanly (spec section 9 remedy)",
+  "asA": "operator running `rcf doctor --check probe-path-owner` on a project that upgraded to observability-essentials v2.0.0 + observability-probe-endpoints v1.1.0 and now sees a redundant-<topic>-resolution drift line",
+  "iWant": "the `rcf define blueprint remove-resolution <adr-id>` verb the drift line and section 9 name to actually exist, drop the named manifest.resolutions[] entry (and nothing else), refuse exit 2 when the id is not a resolution entry, and be idempotent on a second run",
+  "soThat": "the section 9 migration remedy printed by the doctor is executable verbatim, and re-running the same command after a successful pass is a no-op rather than a refusal",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1204-1",
+      "description": "The `rcf define blueprint remove-resolution <adr-id>` verb exists on the blueprint CLI (advertised in `rcf help define blueprint`), matches the `<adr-id>` argument against `manifest.resolutions[].resolvedByAdrId`, and exhibits three ratified behaviours: (a) when an entry matches, drop that entry and only that entry from `manifest.resolutions[]` (every other manifest section byte-identical, and the project-level ADR file at `rcf/adrs/<adr-id>.json` untouched), print one result line naming the id, the topic, and the dropped resolution id, and exit 0; (b) when the `<adr-id>` is a well-formed ADR id that still names an ADR present on the project tree but is no longer on any `resolutions[]` entry, print `[blueprint] nothing to remove: '<adr-id>' is not on manifest.resolutions[]` and exit 0 (idempotent on re-run of the same operation); (c) when the `<adr-id>` is malformed against the ADR id grammar, or is well-formed but names no ADR on the tree and no resolutions[] entry, print `[error] blueprint remove-resolution: ...` on stderr and exit 2.",
+      "given": "a project whose manifest.resolutions[] carries one globalAdrTopic entry on healthProbes with resolvedByAdrId = 'ADR-011-health-probes' and the ADR file present at rcf/adrs/adr-011-health-probes.json",
+      "when": "the operator runs `rcf define blueprint remove-resolution ADR-011-health-probes` once, then a second time, then with 'not-an-adr' and with 'ADR-999-nowhere'",
+      "then": "the first run exits 0 with the removal line and drops the single resolutions[] entry (project-ADR file untouched, every other manifest section byte-identical); the second run exits 0 with the 'nothing to remove' line and does not write; 'not-an-adr' exits 2 with 'is not a well-formed ADR id'; 'ADR-999-nowhere' exits 2 with 'is not a resolution entry on this manifest'; and `rcf help define blueprint` output contains the `remove-resolution <adr-id>` verb block",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T00:00:00Z",
+  "updatedAt": "2026-09-04T00:00:00Z"
+}

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"
+}

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

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1403",
+  "prdId": "PRD-001",
+  "reqId": "REQ-014",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "`rcf define blueprint companions` verb: three sub-verbs (print resolution, set pin, unset pin) with --json on all three",
+  "asA": "operator inspecting or pinning companion suggestions on an applied service blueprint outside the apply flow",
+  "iWant": "a `rcf define blueprint companions <slug>` sub-verb that prints the resolved companion set for one applied service blueprint, `rcf define blueprint companions set <role> <slug>` that writes a project-level pin to rcf/companions.json, and `rcf define blueprint companions unset <role>` that removes a pin",
+  "soThat": "I can read the current resolution without re-applying, pin a decision the operator makes outside the apply, and lift a pin cleanly",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1403-1",
+      "description": "`rcf define blueprint companions <slug>` (three positionals: `blueprint`, `companions`, `<slug>`) with `<slug>` naming an applied service blueprint that declares `suggestedCompanions[]` prints on stdout: header `<slug> suggests companions:` and one line per role in the shape `  <role>          -> <resolved-provider> (<origin-note>)`, where the origin note reads `already applied` / `pinned via rcf/companions.json` / `registered library '<prefix>' (overrides shelf provider <shelf-slug>)` / `shelf fallback (no registered library provides this role)`. Exit 0. Refuses with exit 2 when `<slug>` names no applied blueprint or the applied blueprint declares no `suggestedCompanions[]`.",
+      "given": "a fixture project with application-api-rest v2.1.0 applied and observability-logging applied",
+      "when": "the operator runs `rcf define blueprint companions application-api-rest`",
+      "then": "stdout carries the header and one line per role with `already applied` on `logging` and `shelf fallback` (or similar) on `errorHandling`; a slug that is not applied refuses exit 2",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1403-2",
+      "description": "`rcf define blueprint companions set <role> <slug>` writes `rcf/companions.json` under `roles.<role>.provider` with `pinnedAt` ISO-8601 (or updates it if present); refuses exit 2 when `<slug>` names no blueprint or the named blueprint does not declare `providesRoles` containing `<role>`. `rcf define blueprint companions unset <role>` removes the `roles.<role>` entry (leaves the rest of the file intact); refuses exit 2 when no pin exists for `<role>`. Both sub-verbs honour `--json` (emit `{ok: true, role, provider, pinnedAt}` on success; `{ok: false, error: {...}}` on refusal).",
+      "given": "a fixture project with no existing pin",
+      "when": "the operator runs `rcf define blueprint companions set logging observability-logging`, then `rcf define blueprint companions unset logging`",
+      "then": "the first run writes companions.json with the pin (exit 0); the second run removes the pin and prints `[blueprint] companion pin for role 'logging' removed` on stdout (exit 0); an unset on a role without a pin refuses exit 2",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1403-3",
+      "description": "`--json` on `rcf define blueprint companions <slug>` emits a machine-readable object: `{slug, suggestions: [{role, provider, origin, notes}]}`, exit 0. The suggestions array preserves the order of the applied blueprint's `suggestedCompanions[]`.",
+      "given": "a fixture project with application-api-rest applied and both companions applied",
+      "when": "the operator runs `rcf define blueprint companions application-api-rest --json`",
+      "then": "stdout carries a JSON object of the shape above and jq queries against it return the resolved provider per role",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}