rcf-lite 0.20.0 → 0.22.0

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

@@ -0,0 +1,69 @@
+{
+  "createdAt": "2026-09-06T16:59:00.000Z",
+  "updatedAt": "2026-09-06T16:59:00.000Z",
+  "usId": "US-4001",
+  "prdId": "PRD-001",
+  "reqId": "REQ-040",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "The persistence-data-postgres blueprint ships on the shelf; six Node-only probes pass against a live postgres:17-alpine container and refuse on each induced failure",
+  "asA": "shelf consumer applying the persistence-data-postgres v1.0.0 blueprint",
+  "iWant": "the shipped blueprint files with 26 contributions and six probes, a sample-app fixture that boots postgres:17-alpine and applies three toy forward-only migrations, and gate-runnable proof that every probe passes on the canonical fixture state and refuses on each induced-failure switch",
+  "soThat": "a rcf-lite project applying this blueprint gets a facade contract over pg with numbered forward-only migrations, prepared-statement discipline, transactional atomicity, a two-path recovery model, and pool posture per deploy target, with runtime-observable ACs proven by probes the HQ gate runs against a real Postgres container rather than a simulated harness",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4001-1",
+      "description": "The shelf carries blueprints/persistence-data-postgres/blueprint.json declaring slug persistence-data-postgres, version 1.0.0, category persistence, 26 contributions in the 7 REQ / 10 US / 4 TAC / 5 ADR groups per infra round 5 spec section 5.1; capabilities is [relationalStore]; suggestedCompanions declares logging and errorHandling with spec section 5.1 reasons; providesRoles is absent; requiresAppliedCapabilities is absent.",
+      "given": "the shelf tree after this blueprint lands",
+      "when": "jq queries against blueprints/persistence-data-postgres/blueprint.json",
+      "then": "jq .slug returns persistence-data-postgres; jq .version returns 1.0.0; jq .contributions | length returns 26; jq .capabilities | index(relationalStore) returns 0; jq .suggestedCompanions | length returns 2",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4001-2",
+      "description": "rcf define blueprint add ./blueprints/persistence-data-postgres applies the 26 contributions cleanly on a fresh init project with no other persistence blueprint applied; rcf define validate reports the tree clean; both rcf audit coverage --strict and rcf audit eval coverage --strict exit 0 on the scratch project.",
+      "given": "a fresh rcf init scratch project with no persistence-* blueprint applied",
+      "when": "rcf define blueprint add ./blueprints/persistence-data-postgres runs, then rcf define validate, then rcf audit coverage --strict, then rcf audit eval coverage --strict",
+      "then": "every command exits 0; the scratch project's rcf tree contains the 26 contributions; no globalAdrTopic conflict is raised",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4001-3",
+      "description": "rcf define blueprint add ./blueprints/persistence-data-postgres on a scratch project with persistence-data-d1 already applied surfaces a DELIBERATE conflict on the persistenceStore and migrationDiscipline global-ADR topics per the round-2 pattern; the tree is untouched by the failed add.",
+      "given": "a fresh rcf init scratch project with persistence-data-d1 v1.0.0 already applied",
+      "when": "rcf define blueprint add ./blueprints/persistence-data-postgres runs against the scratch project",
+      "then": "the add refuses with a globalAdrTopic conflict list containing persistenceStore and migrationDiscipline; the scratch project's rcf tree does not carry persistence-data-postgres contributions after the refusal",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4001-4",
+      "description": "The six probe modules under blueprints/persistence-data-postgres/contributions/probes/ each pass against a running postgres:17-alpine container brought up from the sample-app fixture: facade-round-trip asserts facadeReady fires and the round-trip returns; migration-apply asserts three migrations apply inside individual transactions and schema_version advances to 3; prepared-statement-scan asserts every pg.query first-argument node is a static string literal; transaction-atomicity asserts a rollback fires with the failing statement index; recovery-restore-round-trip asserts row-count and checksum equality between source and restored databases; pool-posture-smoke asserts twenty concurrent queries return with no timeout. Each per-blueprint probe report at .rcf/reports/blueprints/persistence-data-postgres/<probe-name>.json carries aggregateVerdict pass.",
+      "given": "the sample-app fixture at packages/rcf-lite/test/fixtures/infra-postgres/ with docker compose up -d postgres running and the fixture applied",
+      "when": "each of the six run-<probe-name>.mjs shims runs against the fixture in sequence",
+      "then": "every shim exits 0; every per-blueprint report file carries aggregateVerdict pass; every result carries an anchorAcId matching a contributed AC id on the blueprint",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4001-5",
+      "description": "The sample-app fixture's induced-failure switches surface each probe's negative-run behaviour: SIMULATE_MIGRATION_FAILURE=true makes run-migration-apply.mjs exit non-zero with the failing migration filename in its report and the transaction rolled back; SIMULATE_CONSTRAINT_VIOLATION=true names the transaction-atomicity probe's rollback observation. Every negative-run report carries aggregateVerdict fail on the AC anchored to the observation the switch corrupts.",
+      "given": "the sample-app fixture with docker compose up -d postgres running",
+      "when": "the migration-apply probe runs with SIMULATE_MIGRATION_FAILURE=true, and the transaction-atomicity probe runs with SIMULATE_CONSTRAINT_VIOLATION=true",
+      "then": "the migration-apply shim exits non-zero and its report at .rcf/reports/blueprints/persistence-data-postgres/migration-apply.json carries aggregateVerdict fail with the failing migration filename in a detail field; the transaction-atomicity probe records the rollback event with statementIndex 1 as evidence of the constraint-violation semantics",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4001-6",
+      "description": "The blueprint ships a sample-app fixture, a README, a CHANGELOG, a guide, and a docs/topics.md entry; the shelf-wide id-band registry table gains a persistence-data-postgres row at US band 27101-27899 / ADR-TAC suffix block 28xx across every shipped blueprint's docs/topics.md; packages/rcf-lite/docs/blueprint-authoring.md section 6a capability-declaration table gains one row for relationalStore per infra round 5 spec section 5.6.",
+      "given": "the shelf tree after this blueprint lands",
+      "when": "grep queries walk every blueprint's docs/topics.md and the section 6a table",
+      "then": "packages/rcf-lite/docs/blueprint-authoring.md contains a table row beginning | relationalStore |; every shipped blueprint's docs/topics.md carries a row beginning | persistence-data-postgres | with the 27101-27899 band and 28xx suffix; blueprints/persistence-data-postgres/README.md, CHANGELOG.md, guide/persistence-data-postgres.md, docs/topics.md, and packages/rcf-lite/test/fixtures/infra-postgres/ all exist; the fixture README names the docker and podman incantations and the two induced-failure switches",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ]
+}

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

@@ -0,0 +1,69 @@
+{
+  "createdAt": "2026-09-06T17:50:03.129Z",
+  "updatedAt": "2026-09-06T17:50:03.129Z",
+  "asA": "shelf consumer applying the object-storage-s3 v1.0.0 blueprint",
+  "iWant": "the shipped blueprint files with 21 contributions, six probes, and the T-2 side of the shared sample-app fixture that boots MinIO and applies the security-secrets-management shim, plus gate-runnable proof that every probe passes on the canonical fixture state and refuses on each induced-failure switch",
+  "soThat": "a rcf-lite project applying this blueprint gets an S3-shape facade over @aws-sdk/client-s3 or aws4fetch with put/get/delete/list, presigned URLs with bounded TTL, multipart-upload above threshold, a lifecycle-event sink with metadata-only fields, and a compose-time refusal on missing security-secrets-management, with runtime-observable ACs proven by probes the HQ gate runs against a real MinIO container",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4101-1",
+      "description": "The shelf carries blueprints/object-storage-s3/blueprint.json declaring slug object-storage-s3, version 1.0.0, category object-storage, 21 contributions in the 6 REQ / 8 US / 3 TAC / 4 ADR groups per infra round 5 spec section 5.2; capabilities is [objectStorage]; suggestedCompanions declares logging and errorHandling with spec section 5.2 reasons; providesRoles is absent; requiresAppliedCapabilities is absent; every ADR contribution entry carries a non-null standardsTraceClause per section 8a.2.",
+      "given": "the shelf tree after this blueprint lands",
+      "when": "jq queries against blueprints/object-storage-s3/blueprint.json",
+      "then": "jq .slug returns object-storage-s3; jq .version returns 1.0.0; jq .contributions | length returns 21; jq .capabilities returns [objectStorage]; jq .suggestedCompanions | length returns 2; jq .contributions[] | select(.kind==adr) | .standardsTraceClause returns a non-null string for every entry",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-2",
+      "description": "rcf define blueprint add ./blueprints/object-storage-s3 applies the 21 contributions cleanly on a fresh init project with security-secrets-management already applied; rcf define validate reports the tree clean; both rcf audit coverage --strict and rcf audit eval coverage --strict exit 0 on the scratch project.",
+      "given": "a fresh rcf init scratch project with security-secrets-management applied",
+      "when": "rcf define blueprint add ./blueprints/object-storage-s3 runs, then rcf define validate, then rcf audit coverage --strict, then rcf audit eval coverage --strict",
+      "then": "every command exits 0; the scratch project's rcf tree contains the 21 contributions; no globalAdrTopic conflict is raised",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-3",
+      "description": "rcf define blueprint add ./blueprints/object-storage-s3 on a scratch project without security-secrets-management refuses with exit 3 and stable message id object-storage-s3-no-secrets on stderr per REQ-006 and spec section 5.2; the --allow-no-secrets-yet override lands the contributions with a note recorded on source.notes for later reconciliation.",
+      "given": "a fresh rcf init scratch project with no security-secrets-management applied",
+      "when": "rcf define blueprint add ./blueprints/object-storage-s3 runs against the scratch project, then the same command runs with --allow-no-secrets-yet",
+      "then": "the first invocation exits 3 with stderr containing object-storage-s3-no-secrets and naming security-secrets-management and the override flag; the scratch tree does not carry object-storage-s3 contributions after the refusal; the second invocation exits 0 and the applied manifest records a source.notes entry naming the missing predecessor",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-4",
+      "description": "The six probe modules under blueprints/object-storage-s3/contributions/probes/ each pass against a running MinIO container brought up from the shared sample-app fixture: facade-round-trip asserts facadeReady fires with endpointHost and bucketName; put-get-round-trip asserts 1 KiB round-trip byte-equal, list under prefix, and delete round-trip with objectDeleted; presigned-url asserts 200 within TTL, 403 on tampered signature, and floor refusal below 60 s; multipart-upload asserts 10 MiB round-trip byte-equal via multipart with no orphan in-flight uploads; event-secrecy asserts the whitelist and no PII fixture leak; r2-real-account-smoke exits 0 with accountBoundSkipped:true without CI_HAS_CLOUDFLARE_ACCOUNT or runs a real R2 round-trip when the env var is set. Each per-blueprint probe report at .rcf/reports/blueprints/object-storage-s3/<probe-name>.json carries aggregateVerdict pass.",
+      "given": "the shared sample-app fixture at packages/rcf-lite/test/fixtures/infra-s3-and-queue/ with docker compose up -d minio running and the rcf-test bucket created",
+      "when": "each of the six run-<probe-name>.mjs shims runs against the fixture in sequence",
+      "then": "every shim exits 0; every per-blueprint report file carries aggregateVerdict pass; every result carries an anchorAcId matching a contributed AC id on the blueprint",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-5",
+      "description": "The sample-app fixture's induced-failure switches surface each probe's negative-run behaviour: SIMULATE_PART_UPLOAD_FAIL=true drives the multipart-upload probe's AC-28104-2 abort-on-failure path; SIMULATE_PRESIGN_MALFORMED=true drives the presigned-url probe's tampered-signature 403 path; SIMULATE_403_ON_GET=true drives the put-get-round-trip probe's fail on AC-28102-1. Each switched-run report carries aggregateVerdict fail on the AC anchored to the observation the switch corrupts (except SIMULATE_PART_UPLOAD_FAIL which surfaces the pass-on-abort-shape).",
+      "given": "the shared fixture with MinIO running",
+      "when": "each named induced-failure switch is set in turn and the paired probe runs",
+      "then": "SIMULATE_PART_UPLOAD_FAIL true yields multipart-upload report with AC-28104-2 pass and no orphan uploads; SIMULATE_403_ON_GET true yields put-get-round-trip report with aggregateVerdict fail; SIMULATE_PRESIGN_MALFORMED true yields presigned-url first-fetch 403 and aggregateVerdict fail; the fixture README documents each switch and the paired probe",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-6",
+      "description": "The blueprint ships a sample-app fixture entry, a README, a CHANGELOG, a guide, and a docs/topics.md entry; the shelf-wide id-band registry table gains an object-storage-s3 row at US band 28101-28899 / ADR-TAC suffix block 29xx across every shipped blueprint's docs/topics.md; packages/rcf-lite/docs/blueprint-authoring.md section 6a capability-declaration table gains one row for objectStorage per infra round 5 spec section 5.6.",
+      "given": "the shelf tree after this blueprint lands",
+      "when": "grep queries walk every blueprint's docs/topics.md and the section 6a table",
+      "then": "packages/rcf-lite/docs/blueprint-authoring.md contains a table row beginning | objectStorage |; every shipped blueprint's docs/topics.md carries a row beginning | object-storage-s3 | with the 28101-28899 band and 29xx suffix; blueprints/object-storage-s3/README.md, CHANGELOG.md, guide/object-storage-s3.md, docs/topics.md, and packages/rcf-lite/test/fixtures/infra-s3-and-queue/ all exist; the fixture README names docker and podman incantations and four wired induced-failure switches",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "usId": "US-4101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-041",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "The object-storage-s3 blueprint ships on the shelf with five MinIO probes plus one accountBound R2 smoke"
+}

package/releases/releases.yaml

@@ -40,8 +40,28 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.20.0"
+latest: "0.22.0"
 releases:
+  - version: "0.22.0"
+    date: "2026-09-07"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.22.0 fills the visual shelf with five application blueprints (empty and error states, file upload with a WCAG keyboard gate, a multi-step forms wizard, a self-service account settings area, and a first-run onboarding tour)."
+      - "Account settings reuses the admin-console capability-gating mechanism, so the five settings surfaces only render when the applied auth blueprint declares the capability."
+      - "The four shipped auth blueprints and the logging blueprint pick up additive capability declarations in the same release."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
+  - version: "0.21.0"
+    date: "2026-09-05"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.21.0 adds five visual-feature blueprints to the shelf (data table, charts, dashboard with packaged design guidance, in-app notifications, admin console) and the mechanism that proves them: a blueprint can now ship a Playwright probe pack that rcf verify runs against your running app in a real browser, and the ship gate refuses while a surface check fails."
+      - "The admin console only offers the surfaces your applied auth blueprint can support. Blueprints can now ask you questions at apply time."
+      - "The schema floor moves to rcf-schemas 0.6.1."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.20.0"
     date: "2026-09-04"
     breaking: true

package/src/blueprint/apply.js

@@ -20,6 +20,7 @@ import { loadBlueprint } from './loader.js';
 import { updateManifest } from './manifest-writer.js';
 import { stampId } from './namespace.js';
 import { nextResolutionId } from './resolutions.js';
+import { buildRefusalMessage, discoverAppliedCapabilities, runCustomAuthCapabilityElicits, runElicitationPhase, writeSidecar } from './capabilities.js';
 
 /**
  * @typedef {object} ApplyResult
@@ -79,7 +80,7 @@ import { nextResolutionId } from './resolutions.js';
  *        prove the rollback runs. Never used in production.
  * @returns {Promise<ApplyResult | import('../core/errors/index.js').RcfError>}
  */
-export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, effectiveSlug, libraryPrefix, libraryBands, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
+export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, effectiveSlug, libraryPrefix, libraryBands, resolveDeclarations, allowNoAuthYet = false, elicitAnswers = null, customAuthReadLine = null, now = new Date(), dryRun = false, _copyFileForTest }) {
   const hintSource = typeof displaySource === 'string' && displaySource.length > 0 ? displaySource : source;
   const blueprint = await loadBlueprint(source);
   if (blueprint.kind) return blueprint; // RcfError
@@ -105,6 +106,69 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     if (bandErr) return bandErr;
   }
 
+  // Capability-declaration mechanism (visual round T-5 spec 5.5).
+  // Discover the union of applied capabilities across every applied
+  // blueprint via source read-back; the applied-blueprint-record
+  // schema is closed (rcf-schemas 0.6.0) and does not carry a
+  // capabilities field, so the source blueprint.json is the ground
+  // truth for what each applied blueprint declares.
+  const discovery = await discoverAppliedCapabilities(applied, projectRoot);
+  const discoveredCapabilities = discovery.union;
+
+  // Custom-auth capability elicitation (visual round T-5 spec 5.5
+  // "Risks": custom auth elicits per capability). Fires BEFORE the
+  // requiresAppliedCapabilities refusal gate: providesCapability
+  // elicits let a project with no shelf auth blueprint declare which
+  // capabilities its own custom auth carries. Truthy answers fold
+  // into the effective applied set; that set is what the refusal gate
+  // and the standard elicitation phase see.
+  const customAuth = await runCustomAuthCapabilityElicits({
+    elicits: blueprint.elicits,
+    answers: elicitAnswers ?? {},
+    readLine: customAuthReadLine ?? undefined,
+  });
+  if (customAuth.kind) return customAuth; // RcfError
+  const appliedCapabilities = [...new Set([...discoveredCapabilities, ...customAuth.capsProvided])].sort();
+  const customAuthElicitations = customAuth.answered;
+
+  // Refusal gate for consumer blueprints that require at least one
+  // applied capability. When the effective set has no overlap AND
+  // the CLI did not pass the allow-skip flag AND no custom-auth
+  // capability answers were supplied that satisfy the gate, refuse
+  // with the templated message (spec 5.5.1 verbatim for admin-console).
+  if (blueprint.requiresAppliedCapabilities && !allowNoAuthYet) {
+    const required = blueprint.requiresAppliedCapabilities.capabilities;
+    const overlap = required.some((c) => appliedCapabilities.includes(c));
+    if (!overlap) {
+      const message = buildRefusalMessage({
+        slug: appliedSlug,
+        refusalMessageId: blueprint.requiresAppliedCapabilities.refusalMessageId,
+        requiredCapabilities: required,
+        appliedRecords: applied,
+        allowSkipFlag: blueprint.requiresAppliedCapabilities.allowSkipFlag,
+      });
+      return rcfError({ kind: 'requiresAppliedCapabilities', message });
+    }
+  }
+
+  // Elicitation phase (visual round T-5 spec section 5.5, T-2 gate).
+  // Evaluate each declared elicit against the effective capability set
+  // (union of applied blueprints and custom-auth answers). Skip
+  // providesCapability entries: those were resolved above and their
+  // answers already landed in customAuthElicitations. Coerce operator
+  // answers per kind. A missing required answer refuses before any
+  // write.
+  const regularElicits = Array.isArray(blueprint.elicits)
+    ? blueprint.elicits.filter((e) => typeof e.providesCapability !== 'string')
+    : [];
+  const elicitResult = runElicitationPhase({
+    elicits: regularElicits,
+    appliedCapabilities,
+    answers: elicitAnswers ?? {},
+  });
+  if (elicitResult.kind) return elicitResult; // RcfError
+  const appliedElicitations = { ...customAuthElicitations, ...elicitResult.value };
+
   // Pre-detection: fold operator-supplied --resolve declarations into a
   // WORKING COPY of the manifest so the detector honours them on this
   // run. The final manifest write later composes the same resolution
@@ -302,11 +366,53 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
   });
   if (manifestResult.kind) return manifestResult; // RcfError
 
+  // Sidecar write for the capability-declaration mechanism (visual
+  // round T-5 spec 5.5.1). Per-project apply-state that the applied-
+  // blueprint-record schema cannot carry today: the discovered
+  // appliedCapabilities snapshot, the elicit answers, and (when the
+  // gate was skipped) an allowNoAuthYet flag plus a notes string that
+  // rcf define validate later reads to flag ungated surfaces. The
+  // sidecar is written on ANY apply that carries capabilities-related
+  // data (declared capabilities, requiresAppliedCapabilities gate,
+  // elicits, or an override) so probe packs and audit tooling have
+  // one deterministic file to read. dryRun skips the write.
+  const wroteSidecar = !dryRun && (
+    blueprint.requiresAppliedCapabilities !== undefined ||
+    (Array.isArray(blueprint.elicits) && blueprint.elicits.length > 0) ||
+    Array.isArray(blueprint.capabilities) ||
+    allowNoAuthYet === true
+  );
+  let sidecarPath = null;
+  if (wroteSidecar) {
+    sidecarPath = await writeSidecar({
+      projectRoot,
+      slug: appliedSlug,
+      version: blueprint.version,
+      appliedAt: now.toISOString(),
+      appliedCapabilities,
+      appliedElicitations,
+      allowNoAuthYet: allowNoAuthYet === true ? true : undefined,
+      notes: allowNoAuthYet === true
+        ? (function buildOverrideNote() {
+            const flag = blueprint.requiresAppliedCapabilities?.allowSkipFlag ?? 'allow-no-auth-yet';
+            const caps = (blueprint.requiresAppliedCapabilities?.capabilities ?? []).join(', ');
+            // Predecessor-family prose is derived from the flag name so
+            // the note reads sensibly for both the auth override ("auth
+            // blueprint") and the secrets override ("secrets-management
+            // blueprint") without the runner learning the family list.
+            const family = flag.includes('secrets') ? 'secrets-management' : 'auth';
+            return `no ${family} yet: applied under --${flag}; surfaces gated on ${caps} will refuse at runtime until a ${family} blueprint is applied.`;
+          })()
+        : undefined,
+    });
+  }
+
   return {
     applied: true,
     slug: appliedSlug,
     version: blueprint.version,
     contributions: writtenContributions,
+    ...(wroteSidecar ? { sidecarPath, appliedCapabilities, appliedElicitations } : {}),
     // 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