rcf-lite 0.18.0 → 0.20.0

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

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

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1404",
+  "prdId": "PRD-001",
+  "reqId": "REQ-014",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Resolution rule prefers applied > registered library > core shelf; two libraries on one role refuse exit 3; validate refuses an unresolvable pin exit 3",
+  "asA": "operator resolving a companion suggestion on a project with a registered library that provides the same role as the shelf",
+  "iWant": "the deterministic tier ladder (applied provider wins, single library candidate wins over shelf, two library candidates refuse with the explicit three-path resolution message, shelf provider is the terminal fallback) and validate to refuse a pin that names no known provider",
+  "soThat": "the operator's opt-in to a library is honoured over the shelf, ambiguity refuses with the explicit remedy paths rather than picking silently, and a stale pin cannot silently drift after a library is removed",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1404-1",
+      "description": "For each role suggested by an applied service blueprint, the resolver walks the tier ladder in order: (1) any applied blueprint whose `providesRoles[]` contains the role wins immediately with origin `already applied`; (2) otherwise, any registered library blueprint (from `rcf/blueprint-libraries.json` + each library's `library.json:blueprints[]`) whose source `providesRoles[]` contains the role wins with origin `registered library '<prefix>'`; (3) otherwise, the single core-shelf blueprint whose `providesRoles[]` contains the role wins with origin `shelf fallback`; (4) otherwise the role is unresolved (origin `unresolved`, provider null). A pin in `rcf/companions.json` overrides steps (2) and (3) with origin `pinned via rcf/companions.json` when the pin names a known provider.",
+      "given": "three fixture projects: (a) core-only; (b) one registered library providing logging + the core provider; (c) an already-applied library-side logging provider",
+      "when": "the resolver runs on the same suggestedCompanions[] from application-api-rest",
+      "then": "(a) resolves logging to observability-logging with `shelf fallback`; (b) resolves logging to the library provider with `registered library '<prefix>'`; (c) resolves logging to the applied library provider with `already applied`",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1404-2",
+      "description": "When two or more registered libraries each carry a `providesRoles[]` containing the same role and no explicit selector or pin is set, the resolver refuses with exit 3 and prints (on `rcf define blueprint add` and on `rcf define blueprint companions <slug>`, both) a message naming the ambiguous role, both library-qualified slugs, and three resolution paths verbatim per spec section 2.4: (1) `rcf define blueprint add <service-slug> --companion <role>=<lib>:<slug>` at apply; (2) `rcf define blueprint companions set <role> <lib>:<slug>` to pin at project level; (3) `rcf define blueprint library remove <prefix>` to remove one library.",
+      "given": "a fixture project with two registered libraries both providing role `logging`, no pin",
+      "when": "the operator runs `rcf define blueprint add <path>/application-api-rest`",
+      "then": "the exit code is 3 and stderr carries the refusal message with both library slugs and the three resolution paths verbatim",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "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 `rcf/companions.json pins role '<role>' to '<slug>' but no such provider is applied, registered or on the shelf.`. The check runs on every validate pass alongside the existing schema and referential-integrity checks; a missing `rcf/companions.json` file is not itself a validation error.",
+      "given": "a fixture project whose companions.json pins `logging` to `nope:nope`",
+      "when": "the operator runs `rcf define validate`",
+      "then": "the exit code is 3 and stderr carries the unresolvable-pin refusal message with the exact quoted role and slug",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

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

@@ -0,0 +1,43 @@
+{
+  "usId": "US-1501",
+  "prdId": "PRD-001",
+  "reqId": "REQ-015",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Loader accepts standardsTrace[], recommendedDefault, elicited and standardsTraceClause; refuses a declared standardsTrace missing a clause reference on any ADR contribution",
+  "asA": "library author writing a standards-derived blueprint (e.g. wsd-logging composing on WSD-001)",
+  "iWant": "the loader to accept a blueprint-level standardsTrace[] and per-ADR-contribution recommendedDefault, elicited and standardsTraceClause fields, and refuse the load when standardsTrace[] is declared but any ADR contribution has no standardsTraceClause",
+  "soThat": "the standards-derived discipline is machine-checkable at load time and a mis-authored library blueprint fails fast, before an apply lands into the tree",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1501-1",
+      "description": "The loader accepts optional top-level `standardsTrace[]` (array of `{id: string, version: string}` objects; `id` is a non-empty string; `version` is a non-empty string), optional ADR-contribution fields `recommendedDefault: true|false`, `elicited: true|false` and `standardsTraceClause: string`. `recommendedDefault` and `elicited` are mutually independent (a SHOULD may be elicited; a MAY need not have a recommended default). The loader does NOT cross-check clause severity against kind (no refusal for a MUST clause mapped to an ADR; the discipline is prose in section 8a, not code, per amendment A2 Baz 2026-09-04T12:20:31Z).",
+      "given": "a blueprint fixture declaring standardsTrace with WSD-001 v2026-05, and one ADR contribution with recommendedDefault: true, elicited: false and standardsTraceClause: 'WSD-001 clause 3.1'",
+      "when": "the loader parses the file",
+      "then": "the LoadedBlueprint object carries the fields verbatim and returns no rcfError",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1501-2",
+      "description": "The loader refuses (rcfError kind `validation`) when `standardsTrace[]` is set but any ADR contribution has no `standardsTraceClause` (or has it set to an empty or whitespace-only string). Refusal message shape: `blueprint '<slug>' declares standardsTrace but ADR contribution '<id>' has no standardsTraceClause; every ADR must reference a standard clause or the sentinel 'generic enterprise practice'.`. At the CLI edge the exit code is 2.",
+      "given": "a fixture blueprint with standardsTrace declared and one ADR contribution missing standardsTraceClause",
+      "when": "the loader parses the file",
+      "then": "the loader returns an rcfError of kind `validation` with the exact refusal message shape",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1501-3",
+      "description": "A blueprint that DOES NOT declare `standardsTrace[]` (every core shelf blueprint today, including the two new core-companion blueprints in REQ-013) loads clean regardless of whether ADR contributions carry `standardsTraceClause` (the discipline lands only when standardsTrace[] is present). The sentinel string `\"generic enterprise practice\"` is accepted as a standardsTraceClause value; the discipline documented in section 8a of blueprint-authoring.md names it explicitly.",
+      "given": "the two new core companion blueprints (observability-logging, application-error-handling) with no standardsTrace declared, and a fixture that declares standardsTrace and uses 'generic enterprise practice' on every ADR",
+      "when": "the loader parses each",
+      "then": "the core blueprints load clean; the fixture with the sentinel on every ADR loads clean",
+      "testable": true,
+      "scope": "library"
+    }
+  ],
+  "tacIds": [],
+  "createdAt": "2026-09-04T12:20:00Z",
+  "updatedAt": "2026-09-04T12:20:00Z"
+}

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

@@ -0,0 +1,37 @@
+{
+  "createdAt": "2026-09-04T16:21:28.205Z",
+  "updatedAt": "2026-09-04T16:22:01.527Z",
+  "description": "As a project owner shipping non-deterministic behaviour, I want rcf-lite to speak the eval-node surface at every stage of the build cycle so that a non-deterministic AC is graded, audited, verdict-annotated and merge-gated without me holding four disconnected mental models. The surface is one train: audit reports coverage, verify annotates per-AC verdicts, finalise refuses on missing / failing evals with an opt-out, and define authors the determinism flag.",
+  "usId": "US-1601",
+  "prdId": "PRD-001",
+  "reqId": "REQ-016",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "The four-track eval-node surface (audit / verdict / finalise / define) reads a single spec across four independent consumers",
+  "asA": "project owner shipping non-deterministic behaviour on an rcf-lite project",
+  "iWant": "rcf-lite to speak the eval-node surface at every stage of the build cycle",
+  "soThat": "a non-deterministic AC is graded, audited, verdict-annotated and merge-gated without me holding four disconnected mental models",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1601-1",
+      "description": "`rcf audit eval coverage --strict` exits 0 on a chain with zero nonDeterministic ACs and exits 4 on any nonDeterministic AC without a resolving EVAL (a non-superseded EVAL whose most recent runRecord entry is not pending). Non-strict runs always exit 0; the mermaid format colours the AC glyph green (deterministic), amber (covered) or red (missing).",
+      "testable": true
+    },
+    {
+      "id": "AC-1601-2",
+      "description": "The verify verdict layer emits EVAL-MISSING on any nonDeterministic AC without a resolving EVAL and EVAL-BELOW-THRESHOLD on any nonDeterministic AC whose bound EVAL last ran with verdict fail. Deterministic ACs never emit either verdict. Both entries ride report.perAcVerdicts[] without expanding the top-level VERDICTS set (backward compatibility on validateReportShape). runStats.evalCoverage rolls up the counts and the CLI prints the preflight line on stderr.",
+      "testable": true
+    },
+    {
+      "id": "AC-1601-3",
+      "description": "rcf finalise refuses (exit 4) with the spec-verbatim message when the verify report carries EVAL-MISSING or EVAL-BELOW-THRESHOLD, and accepts --ship-without-eval <reason> (mandatory reason string; exit 2 without one, refused when the value looks like a flag). The acknowledgement lands on the manifest under shipWithoutEval[] with a monotonic id, the reason, the declared per-AC verdicts and the report path.",
+      "testable": true
+    },
+    {
+      "id": "AC-1601-4",
+      "description": "The LLM-as-judge run path spawns claude (or codex) on PATH, passes the per-case payload on stdin, captures stdout, validates against the declared response schema and composes a runRecord[] entry (aggregateScore, criticalFailures, verdict). No API keys or HTTP APIs enter rcf-lite; the estate subscription-only rule holds. The grader's aggregate verdict is a non-deterministic judgement over graded output, which is the correct home for an EVAL contract on the dogfood tree.",
+      "testable": true,
+      "determinism": "nonDeterministic"
+    }
+  ]
+}

package/releases/releases.yaml

@@ -40,8 +40,27 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.18.0"
+latest: "0.20.0"
 releases:
+  - version: "0.20.0"
+    date: "2026-09-04"
+    breaking: true
+    headlines:
+      - "rcf-lite 0.20.0 adds an optional evaluation step to the chain for the acceptance criteria whose outcome cannot be checked deterministically. You mark such a criterion when you define it, attach an evaluation with its own pass threshold, and the audit, verify and finalise steps refuse to ship while it is missing, with an explicit opt-out that records its reason."
+      - "The schema floor moves to rcf-schemas 0.6.0."
+    minAgentAction: "rerun-init"
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.19.0"
+    date: "2026-09-04"
+    breaking: false
+    headlines:
+      - "The rcf-lite core shelf gains two new blueprints, observability-logging and application-error-handling, that carry the widely followed rules for structured logging and internal error handling so a service can compose them alongside its own blueprint."
+      - "Service blueprints can now name the roles they want alongside them and rcf define blueprint suggests the most specific provider for each at apply time, preferring an applied provider first, then a project-level pin, then a registered library, then the shipped shelf; the operator still applies each companion by hand."
+      - "The authoring standard grows a written discipline for blueprints that derive from an outside standard, so a must-clause that binds a testable behaviour becomes a test and a choice-shaped clause becomes a recommended default. Rerun rcf init to refresh the agent-instructions block."
+    minAgentAction: "rerun-init"
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.18.0"
     date: "2026-09-04"
     breaking: true

package/src/blueprint/apply.js

@@ -307,6 +307,14 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     slug: appliedSlug,
     version: blueprint.version,
     contributions: writtenContributions,
+    // Companion-suggestion mechanism (spec 2.6). Bubble the source
+    // blueprint's `suggestedCompanions[]` up on the result so the CLI
+    // can render the resolved-suggestion block after a successful
+    // apply. Unresolved here (the CLI holds the tree + libraries to
+    // run the resolver); apply owns only the raw copy.
+    ...(Array.isArray(blueprint.suggestedCompanions) && blueprint.suggestedCompanions.length > 0
+      ? { suggestedCompanions: blueprint.suggestedCompanions }
+      : {}),
     ...(duplicateResolveTopics.length > 0 ? { warnings: [{ kind: 'duplicateResolveTopic', topics: duplicateResolveTopics }] } : {}),
   };
 }