rcf-lite 0.13.0 → 0.15.0

package/blueprints/delivery-ci-workflows/README.md

@@ -0,0 +1,61 @@
+# Delivery-ci-workflows blueprint (v2.0.0)
+
+The `delivery-ci-workflows` blueprint (renamed from `ci-pipeline` at v2.0.0) contributes the full workflow set an rcf-lite project runs on its CI provider: two commit-triggered workflows (pull-request-checks and default-branch-checks), an optional release workflow scaled across four modes, and an optional scheduled-audit workflow. The workflow set is a function of an operator-declared `workflowShape` covering four elicited dimensions plus one optional fifth: branch model (feature or trunk), check set (mandatory tier plus five elicited checks), release mode (none, tagOnly, tagPlusArtefact, or deployHandoff), provider hint (which CI provider's illustrative assets to seed from), and an optional scheduledAudit flag. The v1 RCF-gate suite is preserved verbatim as the mandatory tier inside a broader two-tier check catalogue.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/delivery-ci-workflows
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry; `rcf define blueprint remove delivery-ci-workflows` cleanly removes an unreferenced application.
+
+Projects on the v1 `ci-pipeline` slug follow the migration path in the CHANGELOG: remove `ci-pipeline`, add `delivery-ci-workflows`, populate `.rcf/config/delivery-ci-workflows.json`, re-run the workflow-materialiser.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, and the 62 contributions with scope/topic on the three global ADRs |
+| Doc set | `contributions/` | 23 REQs, 23 USs, 6 TACs, 10 ADRs, all schema-valid and namespaced (`delivery-ci-workflows-REQ-NNN` prefix family; `ADR-70N-delivery-ci-workflows-<tail>` suffix family) |
+| GitHub Actions assets | `assets/ci-provider-examples/github-actions/` | One illustrative workflow file per workflow the matrix materialises (`pull-request-checks.yml`, `default-branch-checks.yml`, `release.yml`, `scheduled-audit.yml`) |
+| Alternate-provider notes | `assets/ci-provider-examples/notes.md` | The four-point mapping (job trigger, Node setup, single-line entry-point invocation, artefact upload) applied per workflow for GitLab CI, CircleCI, Buildkite, and Jenkins |
+| Report-shape samples | `assets/report-samples/per-gate.json`, `assets/report-samples/pipeline.json` | Worked examples of a per-gate report (with the v2 `checkKind` field) and an aggregate report at the ratified schemas |
+| Guide | `guide/delivery-ci-workflows.md` | Operator-facing: workflow-shape declaration, elicited-check catalogue, the four release modes, the deploy handoff contract, the scheduled-audit cadence |
+| Coordination vocabulary | `docs/topics.md` | The three global-topic strings this blueprint contributes and the shared id band registry |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision preserved from v1) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSs are the work of the implementing agent, not the blueprint. The blueprint contributes the WHAT (the workflow-materialiser contract, the gate-runner contract, the release-workflow contract, the scheduled-audit contract, the check-catalogue AC contracts, the report shapes); the implementing agent derives the HOW-tasks in the host project against those contracts.
+
+Deliberately not contributed: a matrix of provider-specific configuration files (v2.0.0 ships GHA only; alternate providers wire the same entry points per the guide's four-point mapping applied per workflow); provider-specific pipeline plugins or actions; the linter, formatter, typechecker, unit-test runner, or security scanner (the elicited checks name the kind; the project picks the tool); a code-formatting style guide or a security-scan severity threshold (project decisions); a release-mechanism (no `standard-version` invocation, no `release-please` config, no `changesets` schema; the workflow reacts to a tag or dispatch, does not create it); a merge-queue integration; a coverage-trend dashboard.
+
+## The three global decisions
+
+ADR-701-delivery-ci-workflows-ci-gates ships `scope: global` on topic `ciGates`. This is the project's required check set: the two mandatory tier gates (`validate` then `coverage-strict`) plus the elicited subset from `workflowShape.checkSet` (default: every catalogued elicited check on). A composing blueprint that ships its own required-check opinion (adherence packs, browser-verify smokes, observability probes) conflicts here by design and expects a project-level ADR that names the extended set.
+
+ADR-702-delivery-ci-workflows-strict-coverage-gate ships `scope: global` on topic `strictCoverageGate`. This is the project's coverage-mode posture: per-AC strict, not shallow-any. Preserved verbatim from v1. A composing blueprint that holds a different coverage posture conflicts here by design.
+
+ADR-709-delivery-ci-workflows-release-artefacts ships `scope: global` on topic `releaseArtefacts` (new at v2). This names the decision area of what the release workflow produces on a release trigger; the delivery-side answer is the four `releaseMode` values. A future `security-release-provenance` or `delivery-release-notes` blueprint that opines on the same decision area conflicts here and expects a project-level ADR that fixes the extended answer.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, the delineation from the application-api-rest blueprint's `logging` topic, and the AC id band allocation (delivery-ci-workflows owns 6101-6899).
+
+## Bootstrap posture (loud)
+
+A fresh apply of this blueprint alongside its usual companions contributes tens to hundreds of ACs and zero TCs. The mandatory tier's `coverage-strict` gate refuses when any AC lacks a resolving TC (ADR-702), so the FIRST commit-triggered workflow the materialiser produces is guaranteed to refuse until the project either authors every TC or ships a project-level ADR demoting the gate. The guide's "Bootstrap posture" section names the two ratified paths and points at the starting-point ADR at `assets/bootstrap/adr-bootstrap-coverage-supersession.template.json`. Choose a path at apply time; discovering the trap at the first PR is a real cost this warning exists to save.
+
+## Quality bar
+
+The workflow-materialiser reads `.rcf/config/delivery-ci-workflows.json` and refuses to run when the three required fields are missing or when any field carries an unrecognised value; the required check set runs on every commit-triggered workflow the branch model defines; the mandatory tier runs first in order (`validate` then `coverage-strict`); the elicited tier runs after the mandatory tier in stable but non-load-bearing order; per-gate JSON reports at stable paths carry the v1 fixed key set plus the v2 `checkKind` field; distinct workflows write to distinct aggregate paths (`.rcf/reports/ci/pipeline.json` for commit-triggered, `.rcf/reports/ci/release.json` for release, `.rcf/reports/ci/scheduled-audit.json` for scheduled); a missing required gate report is recorded as `outcome: missing` and flips the aggregate to `failed`; the release workflow shape scales across four discrete modes with the `none` semantic reached either by explicit value or by absent field; the `deployHandoff:<slug>` mode invokes the named deploy blueprint's `promote` workflow with the `versionId` input and refuses at boot when the deploy blueprint is absent; the applied blueprint's source path carries one illustrative GHA workflow file per workflow in the matrix and a notes file mapping four points to alternate providers. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v2.0.0. Every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the materialised workflow files, the aggregate report files at their stable paths, and the platform's own branch-protection or push-protection surface. The mechanism-reach principle from the authoring standard section 7 is satisfied at ship. The operational responsibility a project must own is the branch-protection or equivalent merge-policy configuration on the default or trunk branch that binds the aggregate exit to the merge criterion (AC-6101-2, AC-6114-3, AC-6115-1, AC-6115-2); that responsibility is stated as an AC observable on the platform's own configuration surface, not a smuggled runtime probe.
+
+## Verification depth
+
+The four illustrative GHA workflow files under `assets/ci-provider-examples/github-actions/` are YAML-shape-valid (parseable, `on:` trigger blocks well-formed, jobs and steps structurally complete) and serve as copy-paste starting points; they are NOT executed as part of this blueprint's ship gate. Every non-mandatory-tier check runner and every workflow behaviour (materialiser boot-check, gate-runner orchestration, release-workflow orchestration, scheduled-audit runner, deploy-handoff dispatch, aggregate-report writing) is project-realised against the TAC contracts (TAC-701..706); end-to-end workflow execution is verified in the consuming project's own CI at apply-time, per the mechanism-reach principle. The v1 mandatory-tier upload+promote path (per the v1 blueprint under the old `ci-pipeline` slug) remains dogfood-proven and is preserved verbatim as the mandatory tier here; the v2 elicited-tier catalogue, the new workflow-materialiser TAC, and the release/scheduled-audit workflows are new AC contracts whose runtime enforcement is the applying project's responsibility.

package/blueprints/delivery-ci-workflows/assets/bootstrap/README.md

@@ -0,0 +1,26 @@
+# Bootstrap assets
+
+Templates the operator copies into their project during the bootstrap window
+of a fresh delivery-ci-workflows apply. Nothing here is imported automatically
+by the blueprint; every file is a starting point the operator adapts and
+registers on the project tree.
+
+## `adr-bootstrap-coverage-supersession.template.json`
+
+Project-level ADR template that demotes the mandatory-tier `coverage-strict`
+gate to advisory-only during the bootstrap window (see the guide's "Bootstrap
+posture" section for the problem statement).
+
+Usage:
+
+1. Copy this file into the project's ADR directory (typically `rcf/adrs/`).
+2. Rename the file and its `adrId` from the `ADR-XXX-...` placeholder to the
+   next free project-level ADR id.
+3. Replace the two `TEMPLATE-*ISO8601` timestamps with the current wall-clock.
+4. Register the ADR on the project as `scope: global` on topic
+   `strictCoverageGate` so it competes with ADR-702 through the resolutions
+   mechanism.
+5. Amend the exit criterion in the `decision` section if `N = 5` consecutive
+   passes is not the right threshold for the project.
+6. When the exit criterion is met, flip `status` to `superseded` and leave
+   the file in place for audit trail.

package/blueprints/delivery-ci-workflows/assets/bootstrap/adr-bootstrap-coverage-supersession.template.json

@@ -0,0 +1,28 @@
+{
+  "adrId": "ADR-XXX-bootstrap-coverage-supersession",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "During bootstrap the coverage-strict gate runs advisory-only until a stated exit criterion is met",
+  "context": "A fresh apply of the delivery-ci-workflows blueprint set (application-*, persistence-*, delivery-ci-workflows) contributes tens to hundreds of REQs and ACs and zero test cases. The mandatory-tier coverage-strict gate runs `rcf audit coverage --strict` which refuses when any AC lacks a resolving TC (ADR-702). On a fresh apply the very first commit-triggered workflow is therefore guaranteed to refuse until the project has authored a TC for every AC the blueprint set contributed. That is a real cost the operator either accepts up-front (author every TC before turning CI green) or defers behind a project-level supersession of ADR-702. This project accepts the deferral posture and states the exit criterion here.",
+  "decision": "During bootstrap the required-gate coverage invocation is demoted to advisory-only: the coverage-strict gate still runs on every commit-triggered workflow, its per-gate report still lands at the stable path, and the aggregate still records its outcome; but a `failed` outcome on coverage-strict does NOT flip the aggregate verdict to `failed` and does NOT block merge. Every other required gate (validate, and the elicited tier the project turned on) retains its merge-blocking semantics. This ADR supersedes ADR-702-delivery-ci-workflows-strict-coverage-gate on the `strictCoverageGate` topic for this project only. The demotion is bounded by a stated exit criterion: this ADR is retired (status flipped to superseded) when the mandatory-tier coverage-strict outcome has been `passed` on the default branch for N consecutive commits (recommended: N = 5) OR when the project's own audit shows every AC in the applied blueprint set has a resolving TC, whichever comes first. On retirement the coverage-strict gate reverts to merge-blocking per ADR-702's default posture, and this ADR's file is left in place with `status: superseded` for audit trail.",
+  "consequences": "The bootstrap window is a knowingly-relaxed CI posture; a reviewer merging during it MUST inspect the aggregate's coverage-strict per-gate report themselves rather than trusting the aggregate verdict alone. Every AC the blueprint set contributed still owes a TC; the exit criterion enforces the debt is repaid rather than allowed to accrue silently. A composing blueprint that ships its own coverage-mode opinion (a hypothetical `delivery-ci-workflows-shallow` or `delivery-ci-workflows-grace-window`) conflicts with this ADR the same way it would with ADR-702; the project-level resolver still picks the winner. Retiring this ADR is a one-line status change; the exit criterion is a checklist the retiring commit records.",
+  "alternativesConsidered": [
+    {
+      "name": "Author every TC before turning CI green",
+      "summary": "Do not demote the gate; author the ~N hundred TCs before the first CI run.",
+      "reasonNotChosen": "The blueprint set is large and TC authoring is a real cost; front-loading it delays every other CI signal the project needs from day one. The demote-with-exit-criterion posture keeps every OTHER gate merge-blocking from day one and pays the coverage debt on a stated schedule."
+    },
+    {
+      "name": "Demote coverage-strict permanently to shallow-any",
+      "summary": "Retire ADR-702 without an exit criterion; run shallow-any as the project's coverage floor forever.",
+      "reasonNotChosen": "ADR-702's own consequences section names the failure mode shallow-any hides (an AC bound but no TC resolves it, REQ reads as covered because a sibling AC's TC resolves). The bootstrap posture is a stated deferral, not a permanent policy change; retiring the deferral is a one-line change the exit criterion drives."
+    }
+  ],
+  "relatedAdrs": [
+    "ADR-702-delivery-ci-workflows-strict-coverage-gate"
+  ],
+  "createdAt": "TEMPLATE-createdAt-ISO8601",
+  "updatedAt": "TEMPLATE-updatedAt-ISO8601"
+}

package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/default-branch-checks.yml

@@ -0,0 +1,61 @@
+# Illustrative default-branch-checks workflow for the delivery-ci-workflows blueprint.
+# Copy this file into the host project as `.github/workflows/default-branch-checks.yml`.
+# The file below is the pnpm+main default the materialiser writes when
+# workflowShape.packageManager, workflowShape.defaultBranch and
+# workflowShape.trunkBranch are absent.
+#
+# The file carries paired RCF substitution markers the materialiser
+# rewrites from workflowShape (see guide/delivery-ci-workflows.md for
+# marker names, replacement blocks, and the substitution table).
+#
+# The workflow runs the same required check set as pull-request-checks and
+# writes to the same aggregate report path `.rcf/reports/ci/pipeline.json`.
+#
+# See `guide/delivery-ci-workflows.md` (four-point mapping) for translating
+# this workflow to GitLab CI, CircleCI, Buildkite, or Jenkins.
+
+name: default-branch-checks
+
+on:
+  push:
+    # @@RCF-SUB-BRANCH-NAME@@
+    branches: [main]
+
+jobs:
+  check-set:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      # @@RCF-SUB-PKG-MGR-SETUP-BEGIN@@
+      - name: setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      # @@RCF-SUB-PKG-MGR-SETUP-END@@
+
+      # @@RCF-SUB-PKG-MGR-INSTALL-BEGIN@@
+      - name: install dependencies
+        run: pnpm install --frozen-lockfile
+      # @@RCF-SUB-PKG-MGR-INSTALL-END@@
+
+      - name: run rcf check set
+        run: node scripts/rcf-ci.js
+
+      - name: upload rcf ci reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: default-branch-checks-reports
+          path: .rcf/reports/ci/
+          if-no-files-found: warn
+          retention-days: 30

package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/pull-request-checks.yml

@@ -0,0 +1,74 @@
+# Illustrative pull-request-checks workflow for the delivery-ci-workflows blueprint.
+# Copy this file into the host project as `.github/workflows/pull-request-checks.yml`.
+# The file below is the pnpm+main default the materialiser writes when
+# workflowShape.packageManager and workflowShape.defaultBranch are absent.
+#
+# The file carries paired RCF substitution markers the materialiser rewrites
+# from workflowShape (see guide/delivery-ci-workflows.md, "Within-provider
+# package-manager substitution" and "Trigger branch-name substitution" for
+# marker names, replacement blocks, and the substitution table). A
+# hand-copier on the default (pnpm + main) keeps the file as-is; a project
+# on npm/yarn/bun or a non-main branch either runs the materialiser or
+# applies the substitution table from the guide by hand.
+#
+# The workflow runs one CI-provider-neutral Node entry point that invokes the
+# required check set (the mandatory tier plus the elicited subset the project
+# turned on in workflowShape.checkSet), writes per-gate and aggregate JSON
+# reports under `.rcf/reports/ci/`, and uploads the report directory as a
+# workflow artefact for downstream readers.
+#
+# See `guide/delivery-ci-workflows.md` (four-point mapping) for translating
+# this workflow to GitLab CI, CircleCI, Buildkite, or Jenkins.
+
+name: pull-request-checks
+
+on:
+  pull_request:
+    # @@RCF-SUB-BRANCH-NAME@@
+    branches: [main]
+
+jobs:
+  check-set:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      # @@RCF-SUB-PKG-MGR-SETUP-BEGIN@@
+      - name: setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      # @@RCF-SUB-PKG-MGR-SETUP-END@@
+
+      # @@RCF-SUB-PKG-MGR-INSTALL-BEGIN@@
+      - name: install dependencies
+        run: pnpm install --frozen-lockfile
+      # @@RCF-SUB-PKG-MGR-INSTALL-END@@
+
+      # Single-line invocation of the project's realised gate runner.
+      # The runner spawns the mandatory tier (`rcf define validate` then
+      # `rcf audit coverage --strict`) and then every elicited check the
+      # project turned on in workflowShape.checkSet, writes
+      # `.rcf/reports/ci/<gate>.json` per gate with the `checkKind` field,
+      # and writes `.rcf/reports/ci/pipeline.json` as the aggregate. Its
+      # exit code is the pipeline's aggregate exit code.
+      - name: run rcf check set
+        run: node scripts/rcf-ci.js
+
+      - name: upload rcf ci reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: pull-request-checks-reports
+          path: .rcf/reports/ci/
+          if-no-files-found: warn
+          retention-days: 30

package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/release.yml

@@ -0,0 +1,75 @@
+# Illustrative release workflow for the delivery-ci-workflows blueprint.
+# Copy this file into the host project as `.github/workflows/release.yml`
+# and adjust the `node-version`, package-manager setup, and release
+# orchestrator path to match the project's realised release runner (TAC-705).
+#
+# This file materialises when workflowShape.releaseMode is `tagOnly`,
+# `tagPlusArtefact`, or `deployHandoff:<slug>`. When releaseMode is `none`
+# or absent, the workflow does not ship at all (Q6-B ratification).
+#
+# The workflow does NOT run the required check set: that already ran on the
+# default-branch-checks workflow at the commit the release points at.
+#
+# See `guide/delivery-ci-workflows.md` for the four release-mode shapes and
+# the deploy handoff invocation contract (AC-6122-1..3).
+
+name: release
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      versionId:
+        description: 'Version identifier to release (optional; omitted defaults to the release event tag)'
+        required: false
+        type: string
+
+jobs:
+  release-flow:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      # @@RCF-SUB-PKG-MGR-SETUP-BEGIN@@
+      - name: setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      # @@RCF-SUB-PKG-MGR-SETUP-END@@
+
+      # @@RCF-SUB-PKG-MGR-INSTALL-BEGIN@@
+      - name: install dependencies
+        run: pnpm install --frozen-lockfile
+      # @@RCF-SUB-PKG-MGR-INSTALL-END@@
+
+      # The release orchestrator reads the releaseMode from its environment
+      # (RCF_RELEASE_MODE) and runs the appropriate step sequence:
+      # tagOnly: create release entity only
+      # tagPlusArtefact: create release entity, run artefact-publish step
+      # deployHandoff:<slug>: create release entity, run artefact-publish
+      #   step, dispatch <slug>'s promote workflow with versionId
+      # It writes .rcf/reports/ci/release.json as the aggregate.
+      - name: run release orchestrator
+        env:
+          RCF_RELEASE_MODE: tagPlusArtefact
+        run: node scripts/rcf-release.js
+
+      - name: upload release reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-reports
+          path: .rcf/reports/ci/
+          if-no-files-found: warn
+          retention-days: 90

package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/scheduled-audit.yml

@@ -0,0 +1,65 @@
+# Illustrative scheduled-audit workflow for the delivery-ci-workflows blueprint.
+# Copy this file into the host project as `.github/workflows/scheduled-audit.yml`
+# and adjust the `node-version`, package-manager setup, and scheduled runner
+# path to match the project's realised scheduled-audit runner (TAC-706).
+#
+# This file materialises when workflowShape.scheduledAudit is `true`. When
+# `false` or absent, the workflow does not ship at all.
+#
+# The workflow runs the same required check set as the commit-triggered
+# workflows and writes to a distinct aggregate report path
+# (.rcf/reports/ci/scheduled-audit.json) so scheduled-run outcomes never
+# overwrite the most recent commit-triggered outcome.
+#
+# See `guide/delivery-ci-workflows.md` for the cron cadence discussion and
+# AC-6123-1/AC-6123-2 for the report-path property.
+
+name: scheduled-audit
+
+on:
+  schedule:
+    # Every day at 06:00 UTC. Adjust to your project's cadence.
+    - cron: '0 6 * * *'
+  workflow_dispatch: {}
+
+jobs:
+  scheduled-check-set:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      # @@RCF-SUB-PKG-MGR-SETUP-BEGIN@@
+      - name: setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      # @@RCF-SUB-PKG-MGR-SETUP-END@@
+
+      # @@RCF-SUB-PKG-MGR-INSTALL-BEGIN@@
+      - name: install dependencies
+        run: pnpm install --frozen-lockfile
+      # @@RCF-SUB-PKG-MGR-INSTALL-END@@
+
+      # The scheduled runner is a thin wrapper around the gate-runner
+      # (TAC-701) that overrides the aggregate report path to the
+      # scheduled-audit path and forwards the elicited check set.
+      - name: run scheduled audit
+        run: node scripts/rcf-scheduled-audit.js --report-path .rcf/reports/ci/scheduled-audit.json
+
+      - name: upload scheduled audit reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: scheduled-audit-reports
+          path: .rcf/reports/ci/
+          if-no-files-found: warn
+          retention-days: 30

package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/notes.md

@@ -0,0 +1,61 @@
+# Wiring the workflow set on alternate CI providers
+
+The blueprint ships one illustrative provider example (GitHub Actions, four workflow files under `github-actions/`). Every mainstream provider hosts the same workflow set by translating four points per workflow and keeping the Node entry-point invocations unchanged. These notes are read alongside `guide/delivery-ci-workflows.md`, not instead of it.
+
+## The workflow set the matrix materialises
+
+Which workflow files exist depends on `workflowShape`:
+
+- Always: `default-branch-checks` (pushes to the default or trunk branch).
+- Feature-branch, or trunk-based with `trunkPullRequests: sometimes`: `pull-request-checks` (pull requests targeting the branch).
+- `releaseMode` not `none` and not absent: `release` (release-trigger events; four shapes per mode).
+- `scheduledAudit: true`: `scheduled-audit` (cron cadence).
+
+## The four mapping points (applied per workflow)
+
+1. Job trigger. Fire the workflow's job on the trigger set defined for that workflow (see the corresponding GHA file's `on:` block for the reference shape).
+2. Node setup. Install Node 24 or later on the runner.
+3. Package-manager setup and install. Install the project's dependencies with the frozen-lockfile discipline of whichever manager the project uses. The manager is a project decision recorded on `workflowShape.packageManager` (default `pnpm`; recognised set `pnpm`, `npm`, `yarn`, `bun`); the per-manager setup and install blocks are named in the guide's "Within-provider package-manager substitution" table. Alternate providers translate the block to the provider's own action/command; the manager choice stays project-controlled.
+4. Node entry-point invocation and artefact upload. Run `node <path>` (or a package-manager script that resolves to the same) for the workflow's entry point (gate-runner for `pull-request-checks` and `default-branch-checks`, release orchestrator for `release`, scheduled-audit runner for `scheduled-audit`); upload the aggregate report directory as a run artefact for downstream readers.
+
+The blueprint does not ship provider-specific configuration files for the providers below at v2.0.0. A project hand-authors the first three points in the provider's own runner language and keeps the fourth unchanged per the workflow's entry point.
+
+## GitLab CI (`.gitlab-ci.yml`)
+
+- Triggers: for `pull-request-checks` use `rules: { if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main" }`; for `default-branch-checks` use `rules: { if: $CI_COMMIT_BRANCH == "main" }`; for `release` use `rules: { if: $CI_COMMIT_TAG }` plus a `workflow_dispatch`-equivalent through GitLab's manual jobs; for `scheduled-audit` use a scheduled pipeline.
+- Node setup: use a `node:24` image or install through the runner's setup hook.
+- Install: the install line from the guide's substitution table for the project's `workflowShape.packageManager` (default `pnpm install --frozen-lockfile`).
+- Invoke: `node scripts/rcf-ci.js` for check-set workflows; `node scripts/rcf-release.js` for release; `node scripts/rcf-scheduled-audit.js --report-path .rcf/reports/ci/scheduled-audit.json` for scheduled-audit.
+- Artefact upload: `artifacts: { when: always, paths: [.rcf/reports/ci/] }`.
+
+## CircleCI (`.circleci/config.yml`)
+
+- Triggers: `workflows:` with branch and PR filters for the two check-set workflows; scheduled workflows for `scheduled-audit`; the release workflow fires from tag-triggered pipelines.
+- Node setup: `cimg/node:24.19` or the `node/install` orb command.
+- Install: the install line from the guide's substitution table for the project's `workflowShape.packageManager`.
+- Invoke: as above.
+- Artefact upload: `store_artifacts: { path: .rcf/reports/ci }`.
+
+## Buildkite (`.buildkite/pipeline.yml`)
+
+- Triggers: pipeline-level branch conditions or per-step `branches: main` for check-set workflows; separate pipelines for release (tag-triggered) and scheduled-audit (Buildkite scheduled builds).
+- Node setup: install Node 24 in the queue's setup hook or use a Docker plugin (`docker#v5.0.0`).
+- Install: the install line from the guide's substitution table for the project's `workflowShape.packageManager`.
+- Invoke: as above.
+- Artefact upload: `artifact_paths: [".rcf/reports/ci/**"]`.
+
+## Jenkins (declarative pipeline)
+
+- Triggers: `triggers { githubPush() }` plus a multibranch pipeline configured to build pull requests against the default branch; a separate tag-triggered pipeline for release; `triggers { cron('H 6 * * *') }` for scheduled-audit.
+- Node setup: install Node 24 via `tools { nodejs '24' }` or provision the agent with Node preinstalled.
+- Install: `sh` invocation of the install line from the guide's substitution table for the project's `workflowShape.packageManager`.
+- Invoke: `sh 'node scripts/rcf-ci.js'` (or the appropriate script per workflow).
+- Artefact upload: `archiveArtifacts artifacts: '.rcf/reports/ci/**', allowEmptyArchive: true`.
+
+## Cross-provider notes
+
+- The Node entry-point paths are the same on every provider. A project that changes providers rewrites its trigger, setup, install, and artefact-upload steps; the entry-point step is unchanged.
+- The report directory (default `.rcf/reports/ci/`) is the same on every provider. Downstream readers do not need per-provider knowledge to pick up the aggregate reports.
+- The tool-version pin (which `rcf` version to run) is the project's decision. The runner records the installed version on every per-gate report's `toolVersion` field; a mismatch across two runs is visible in the reports without re-running the gate.
+- The release workflow's `deployHandoff:<slug>` mode dispatches the named deploy blueprint's `promote` workflow. On GHA that means a `workflow_dispatch` call to the deploy blueprint's workflow file; on other providers, translate to the equivalent workflow-dispatch primitive (GitLab's pipeline API trigger, CircleCI's trigger-pipeline API, Buildkite's Trigger step, Jenkins parameterised build). The `versionId` input contract is unchanged across providers.
+- Sibling asset packs (a v2.1 candidate) that ship per-provider full asset sets from the same `workflowShape` are the natural way to skip this hand-translation work for projects that live on one provider.

package/blueprints/{ci-pipeline → delivery-ci-workflows}/assets/report-samples/per-gate.json

@@ -1,6 +1,6 @@
 {
   "gate": "validate",
-  "command": ["rcf", "validate"],
+  "command": ["rcf", "define", "validate"],
   "toolVersion": "0.7.4",
   "startedAt": "2026-08-24T10:15:03.221Z",
   "endedAt": "2026-08-24T10:15:04.891Z",
@@ -8,5 +8,6 @@
   "exitCode": 0,
   "outcome": "passed",
   "stdout": "[rcf] validate: 0 issue(s) across 47 document(s)\n",
-  "stderr": ""
+  "stderr": "",
+  "checkKind": "validate"
 }

package/blueprints/delivery-ci-workflows/blueprint.json

@@ -0,0 +1,87 @@
+{
+  "slug": "delivery-ci-workflows",
+  "version": "2.1.0",
+  "category": "delivery",
+  "contributions": [
+    { "id": "delivery-ci-workflows-REQ-001", "kind": "req", "path": "requirements/delivery-ci-workflows-req-001.json" },
+    { "id": "delivery-ci-workflows-REQ-002", "kind": "req", "path": "requirements/delivery-ci-workflows-req-002.json" },
+    { "id": "delivery-ci-workflows-REQ-003", "kind": "req", "path": "requirements/delivery-ci-workflows-req-003.json" },
+    { "id": "delivery-ci-workflows-REQ-004", "kind": "req", "path": "requirements/delivery-ci-workflows-req-004.json" },
+    { "id": "delivery-ci-workflows-REQ-005", "kind": "req", "path": "requirements/delivery-ci-workflows-req-005.json" },
+    { "id": "delivery-ci-workflows-REQ-006", "kind": "req", "path": "requirements/delivery-ci-workflows-req-006.json" },
+    { "id": "delivery-ci-workflows-REQ-007", "kind": "req", "path": "requirements/delivery-ci-workflows-req-007.json" },
+    { "id": "delivery-ci-workflows-REQ-008", "kind": "req", "path": "requirements/delivery-ci-workflows-req-008.json" },
+    { "id": "delivery-ci-workflows-REQ-009", "kind": "req", "path": "requirements/delivery-ci-workflows-req-009.json" },
+    { "id": "delivery-ci-workflows-REQ-010", "kind": "req", "path": "requirements/delivery-ci-workflows-req-010.json" },
+    { "id": "delivery-ci-workflows-REQ-011", "kind": "req", "path": "requirements/delivery-ci-workflows-req-011.json" },
+    { "id": "delivery-ci-workflows-REQ-012", "kind": "req", "path": "requirements/delivery-ci-workflows-req-012.json" },
+    { "id": "delivery-ci-workflows-REQ-013", "kind": "req", "path": "requirements/delivery-ci-workflows-req-013.json" },
+    { "id": "delivery-ci-workflows-REQ-014", "kind": "req", "path": "requirements/delivery-ci-workflows-req-014.json" },
+    { "id": "delivery-ci-workflows-REQ-015", "kind": "req", "path": "requirements/delivery-ci-workflows-req-015.json" },
+    { "id": "delivery-ci-workflows-REQ-016", "kind": "req", "path": "requirements/delivery-ci-workflows-req-016.json" },
+    { "id": "delivery-ci-workflows-REQ-017", "kind": "req", "path": "requirements/delivery-ci-workflows-req-017.json" },
+    { "id": "delivery-ci-workflows-REQ-018", "kind": "req", "path": "requirements/delivery-ci-workflows-req-018.json" },
+    { "id": "delivery-ci-workflows-REQ-019", "kind": "req", "path": "requirements/delivery-ci-workflows-req-019.json" },
+    { "id": "delivery-ci-workflows-REQ-020", "kind": "req", "path": "requirements/delivery-ci-workflows-req-020.json" },
+    { "id": "delivery-ci-workflows-REQ-021", "kind": "req", "path": "requirements/delivery-ci-workflows-req-021.json" },
+    { "id": "delivery-ci-workflows-REQ-022", "kind": "req", "path": "requirements/delivery-ci-workflows-req-022.json" },
+    { "id": "delivery-ci-workflows-REQ-023", "kind": "req", "path": "requirements/delivery-ci-workflows-req-023.json" },
+    { "id": "delivery-ci-workflows-US-6101", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6101.json" },
+    { "id": "delivery-ci-workflows-US-6102", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6102.json" },
+    { "id": "delivery-ci-workflows-US-6103", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6103.json" },
+    { "id": "delivery-ci-workflows-US-6104", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6104.json" },
+    { "id": "delivery-ci-workflows-US-6105", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6105.json" },
+    { "id": "delivery-ci-workflows-US-6106", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6106.json" },
+    { "id": "delivery-ci-workflows-US-6107", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6107.json" },
+    { "id": "delivery-ci-workflows-US-6108", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6108.json" },
+    { "id": "delivery-ci-workflows-US-6109", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6109.json" },
+    { "id": "delivery-ci-workflows-US-6110", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6110.json" },
+    { "id": "delivery-ci-workflows-US-6111", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6111.json" },
+    { "id": "delivery-ci-workflows-US-6112", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6112.json" },
+    { "id": "delivery-ci-workflows-US-6113", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6113.json" },
+    { "id": "delivery-ci-workflows-US-6114", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6114.json" },
+    { "id": "delivery-ci-workflows-US-6115", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6115.json" },
+    { "id": "delivery-ci-workflows-US-6116", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6116.json" },
+    { "id": "delivery-ci-workflows-US-6117", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6117.json" },
+    { "id": "delivery-ci-workflows-US-6118", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6118.json" },
+    { "id": "delivery-ci-workflows-US-6119", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6119.json" },
+    { "id": "delivery-ci-workflows-US-6120", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6120.json" },
+    { "id": "delivery-ci-workflows-US-6121", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6121.json" },
+    { "id": "delivery-ci-workflows-US-6122", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6122.json" },
+    { "id": "delivery-ci-workflows-US-6123", "kind": "us", "path": "user-stories/delivery-ci-workflows-us-6123.json" },
+    { "id": "TAC-701-delivery-ci-workflows-gate-runner", "kind": "tac", "path": "tacs/tac-701-delivery-ci-workflows-gate-runner.json" },
+    { "id": "TAC-702-delivery-ci-workflows-gate-report", "kind": "tac", "path": "tacs/tac-702-delivery-ci-workflows-gate-report.json" },
+    { "id": "TAC-703-delivery-ci-workflows-aggregate-report", "kind": "tac", "path": "tacs/tac-703-delivery-ci-workflows-aggregate-report.json" },
+    { "id": "TAC-704-delivery-ci-workflows-workflow-materialiser", "kind": "tac", "path": "tacs/tac-704-delivery-ci-workflows-workflow-materialiser.json" },
+    { "id": "TAC-705-delivery-ci-workflows-release-workflow", "kind": "tac", "path": "tacs/tac-705-delivery-ci-workflows-release-workflow.json" },
+    { "id": "TAC-706-delivery-ci-workflows-scheduled-audit", "kind": "tac", "path": "tacs/tac-706-delivery-ci-workflows-scheduled-audit.json" },
+    {
+      "id": "ADR-701-delivery-ci-workflows-ci-gates",
+      "kind": "adr",
+      "path": "adrs/adr-701-delivery-ci-workflows-ci-gates.json",
+      "scope": "global",
+      "topic": "ciGates"
+    },
+    {
+      "id": "ADR-702-delivery-ci-workflows-strict-coverage-gate",
+      "kind": "adr",
+      "path": "adrs/adr-702-delivery-ci-workflows-strict-coverage-gate.json",
+      "scope": "global",
+      "topic": "strictCoverageGate"
+    },
+    { "id": "ADR-703-delivery-ci-workflows-node-only-runner", "kind": "adr", "path": "adrs/adr-703-delivery-ci-workflows-node-only-runner.json" },
+    { "id": "ADR-704-delivery-ci-workflows-report-shape", "kind": "adr", "path": "adrs/adr-704-delivery-ci-workflows-report-shape.json" },
+    { "id": "ADR-705-delivery-ci-workflows-elicitation-surface", "kind": "adr", "path": "adrs/adr-705-delivery-ci-workflows-elicitation-surface.json" },
+    { "id": "ADR-706-delivery-ci-workflows-branch-model-defaults", "kind": "adr", "path": "adrs/adr-706-delivery-ci-workflows-branch-model-defaults.json" },
+    { "id": "ADR-707-delivery-ci-workflows-release-workflow-shape", "kind": "adr", "path": "adrs/adr-707-delivery-ci-workflows-release-workflow-shape.json" },
+    { "id": "ADR-708-delivery-ci-workflows-provider-hint-shape", "kind": "adr", "path": "adrs/adr-708-delivery-ci-workflows-provider-hint-shape.json" },
+    {
+      "id": "ADR-709-delivery-ci-workflows-release-artefacts",
+      "kind": "adr",
+      "path": "adrs/adr-709-delivery-ci-workflows-release-artefacts.json",
+      "scope": "global",
+      "topic": "releaseArtefacts"
+    },
+    { "id": "ADR-710-delivery-ci-workflows-scheduled-audit", "kind": "adr", "path": "adrs/adr-710-delivery-ci-workflows-scheduled-audit.json" }
+  ]
+}

package/blueprints/delivery-ci-workflows/contributions/adrs/adr-701-delivery-ci-workflows-ci-gates.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-701-delivery-ci-workflows-ci-gates",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "2.0.0",
+  "status": "accepted",
+  "title": "The project's CI runs a fixed ordered required check set (mandatory tier plus the elicited subset from workflowShape.checkSet) whose completeness is the merge criterion",
+  "context": "Continuous integration surfaces are a matrix of trigger events, runner definitions, and gates. The interesting decision area is not the runner or the trigger (a small dial with obvious answers) but the check set: which checks run, in which order, and what does 'the pipeline passed' mean. A project that changes its check set silently loses the property that the pipeline meant the same thing across two runs. Naming the check set as a decision area (not a runtime knob) is what makes the pipeline a stable contract. v2 broadens the answer surface from the fixed v1.0.0 two-gate set to a two-tier catalogue: a mandatory tier (the two v1 gates, preserved verbatim) plus an elicited tier (linter, formatter, typecheck, unitTest, securityScan) the project turns on and off through `workflowShape.checkSet`.",
+  "decision": "The project's CI runs a fixed ordered required check set at every workflow that carries one. The mandatory tier runs first, in order, on every check-set workflow: `validate` (running `rcf define validate`) followed by `coverage-strict` (running `rcf audit coverage --strict`). The elicited tier runs after the mandatory tier: the checks the project turned on in `workflowShape.checkSet` (default: every catalogued check on) run in a stable but non-load-bearing order documented in the guide. The pipeline passes if and only if every required check's outcome is `passed`; a `failed` or `missing` outcome on any required check fails the pipeline. Adding a check kind the catalogue does not name (mutation-testing, contract-test, accessibility scan) is a project-level or blueprint-level ADR: a project that wants an extra required check supersedes this ADR with a project-level ADR listing the extended catalogue; a future blueprint that ships a new required check (a browser-verify pack, an observability probe pack) contributes its own scope:global ADR on the `ciGates` topic and lets composition surface the pairing.",
+  "consequences": "The pipeline's verdict is stable across runs of the same commit under the same rcf CLI version and the same `workflowShape`. Adding a check is a visible decision (either a `workflowShape.checkSet` flag flip or a project-level ADR); changing the check catalogue itself is a v2.x major bump. A project that wants a check the catalogue does not name owes a project-level ADR that supersedes this one and names the extended catalogue; the aggregate report's `gates[]` array then reflects the extended catalogue on every run. Composing blueprints that hold an opinion on the required-check set conflict on the `ciGates` topic: an observability-essentials blueprint that ships health-probe gates as required conflicts here by design and expects a project-level ADR to resolve the pairing (or the operator adopts one of the two blueprints).",
+  "alternativesConsidered": [
+    {
+      "name": "Ship the gate set as a runtime configuration knob rather than as an ADR",
+      "summary": "The runner reads the gate set from a config file or environment variable, and any project reconfigures without a decision record.",
+      "reasonNotChosen": "A gate set that can silently change is one whose meaning drifts. The value of the aggregate report as a stable contract collapses if two runs of the same commit can have different gate sets. Making the gate set an ADR forces the reasoning to be recorded and forces a composing blueprint to conflict explicitly."
+    },
+    {
+      "name": "Ship a maximal required-check set at v2.0.0 (mandatory tier plus every plausible elicited check plus adherence packs plus browser-verify)",
+      "summary": "The pipeline runs every check the mechanism offers as required by default, with no elicitation surface.",
+      "reasonNotChosen": "The mechanism-reach principle for blueprints (authoring standard, section 7) says a blueprint should not compel a check the project has no reasonable path to satisfy. Adherence packs and browser-verify probes belong in future blueprints that ship the surface they enforce; requiring them here would leave every fresh project failing its pipeline until it realises those surfaces. The mandatory tier plus the five elicited checks the project turns on and off is the right v2.0.0 floor."
+    },
+    {
+      "name": "Keep the v1.0.0 fixed two-gate set at v2",
+      "summary": "The check set stays at `validate` + `coverage-strict`; the elicited tier does not ship.",
+      "reasonNotChosen": "Lint, formatter, typecheck, unit-test, and security-scan are checks a project engineer expects to find in a general-purpose CI floor; leaving v2 at the v1 two-gate set does not close that gap and leaves every consuming project reinventing the elicited tier as a project-level ADR."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}