rcf-lite 0.12.0 → 0.14.0

package/blueprints/delivery-ci-workflows/contributions/adrs/adr-710-delivery-ci-workflows-scheduled-audit.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-710-delivery-ci-workflows-scheduled-audit",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "2.0.0",
+  "status": "accepted",
+  "title": "scheduledAudit is a top-level optional fifth dimension on workflowShape, defaulting to false",
+  "context": "The scheduled-audit workflow catches drift (dependency updates, secret rotations) that does not coincide with a merge. Whether to ship it is genuinely optional and does not fit cleanly under the four elicited dimensions. Two shapes considered: a fifth top-level field, and a nested cadence flag under `checkSet.securityScan.cadence`.",
+  "decision": "A fifth top-level field `scheduledAudit: boolean` (default `false`) governs whether the `scheduled-audit` workflow ships. When true, the workflow runs the same required check set the commit-triggered workflows run on a cron cadence and writes to a distinct aggregate report path (`.rcf/reports/ci/scheduled-audit.json`). When false or absent, no scheduled workflow ships. If future need arises for scheduled cadence on other checks, the field generalises to `scheduledCadence: string` accepting cron expressions without displacing the fifth dimension.",
+  "consequences": "The scheduled-audit dimension is explicit and independent of any specific check; the aggregate report path is distinct so scheduled-run outcomes never overwrite commit-triggered outcomes. Adopting the scheduled workflow is one boolean flip; opting out is the default. The forward path to a `scheduledCadence` generalisation is clear.",
+  "alternativesConsidered": [
+    {
+      "name": "Fold under `checkSet.securityScan.cadence`",
+      "summary": "A nested cadence flag on the security-scan check governs whether the scan runs on cron.",
+      "reasonNotChosen": "Conflates the check kind with its cadence; a project that wants the linter (not the security scan) on a cron cadence would need a second nested cadence field, blowing up the check-set shape."
+    },
+    {
+      "name": "Ship the scheduled-audit workflow always on",
+      "summary": "Every shape gets a scheduled workflow by default.",
+      "reasonNotChosen": "Small projects with no dependency exposure do not need scheduled scans; running them by default wastes CI minutes and lengthens noise."
+    }
+  ],
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The materialised commit-triggered workflows run the required check set on every trigger event the branch model defines",
+  "description": "The commit-triggered workflows the materialiser produces (per REQ-014 for feature-branch and REQ-015 for trunk-based) run the required check set on every trigger event the elicited branch model defines: for feature-branch, pushes to the default branch and pull requests targeting the default branch; for trunk-based, pushes to the trunk branch (and, in the sub-shape where `trunkPullRequests: sometimes`, pull requests targeting the trunk branch). The workflows' aggregate exit status is the merge criterion: the branch protection or equivalent policy refuses to admit a change whose most recent aggregate run did not exit zero, per the merge-policy AC binding for the branch model in play (AC-6114-3, AC-6115-1, AC-6115-2). No manual override path bypasses the required check set; a hotfix that skips it requires a documented ADR trail.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Gates that run sometimes are gates that fail sometimes. Binding the required check set to every trigger event the branch model defines turns the RCF chain and the elicited checks from a habit into a build property, and removes the class of drift where a chain-authoring seat's fix passes locally but the tree ships already broken. The branch-model dimension controls the trigger set; the merge-policy AC per shape is what wires the aggregate into the platform surface.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:01-required-check"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The gate suite is invoked as one Node entry point that is CI-provider-neutral",
+  "description": "The project realises a single Node entry point script that runs every RCF gate in order. The entry point is a plain Node process invoked by whatever runner the project's CI provider ships (GitHub Actions job step, GitLab job script, CircleCI step, Buildkite command, Jenkins stage). The CI-provider job definition contains one invocation line and the standard Node and package-manager setup steps; every gate-specific piece of logic lives in the Node entry point.",
+  "category": "technical",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A gate suite spelled in one CI provider's runner language locks the project to that provider and makes local reproduction of a CI failure expensive. A Node entry point is portable across every provider that can run Node, local machines included, and keeps the gate logic under one source-controlled file the project's own tests can cover.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:02-provider-neutral"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-003",
+  "prdId": "PRD-001",
+  "title": "The suite runs the schema-and-reference validation gate and refuses on non-zero exit",
+  "description": "The Node entry point invokes `rcf define validate` as a required gate. The gate runs with the project's tree at the pull request's head commit. A non-zero exit code from `rcf define validate` terminates the suite and marks the aggregate result as failed. The failing invocation's stdout and stderr are captured to the gate report file so the reviewer can read the specific schema or reference issue without re-running the gate.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Schema and cross-reference integrity is the floor every other gate stands on: `rcf audit coverage --strict` cannot answer honestly against a tree with broken references. Running `rcf define validate` first, failing fast on non-zero exit, and preserving its output for the reviewer is the shape that makes the mechanism useful in review, not just at author time.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:03-validate-gate"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-004",
+  "prdId": "PRD-001",
+  "title": "The suite runs the per-AC strict coverage gate and refuses on non-zero exit",
+  "description": "The Node entry point invokes `rcf audit coverage --strict` as a required gate. The gate runs against the tree at the pull request's head commit and reports per-AC coverage: every AC on every US must resolve to a TC whose testPointer points at a real test. A non-zero exit code (mechanism exit 4 on gaps) terminates the suite and marks the aggregate result as failed. The strict-flag invocation is the sole coverage mode the suite runs; shallow-any is not accepted as a substitute.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Shallow-any coverage will declare a REQ covered when any AC on any US has any resolving TC, which is exactly the shape the watchpost run4 icon and token gap slipped through. Per-AC strict coverage is what makes the mechanism refuse to declare a shipped floor met while any AC still floats without a resolving TC.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:04-strict-coverage-gate"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Each gate writes a machine-readable JSON report file at a stable path on every invocation",
+  "description": "Every gate the suite invokes writes a JSON report file at a stable relative path under a project-configured report directory (default `.rcf/reports/ci/`). The per-gate report file is written whether the gate passed or failed. The report file carries the gate name, the underlying CLI invocation, the exit code, the start and end ISO-8601 timestamps, the duration in milliseconds, the tool version invoked, the captured stdout and stderr strings, and (v2 addition) a `checkKind` field naming the elicited-check kind (`validate`, `coverage-strict`, `linter`, `formatter`, `typecheck`, `unitTest`, `securityScan`, or `custom:<name>`). The report file's schema is stable within a blueprint major version; v1 additive fields (the `checkKind` addition) are preserved from v1.0.0 to v2.0.0.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A gate that only leaves human-readable text behind forces the reviewer to re-run it to answer any question the log did not surface. A stable JSON report at a stable path turns the gate's outcome into review-time data: what version of the tool ran, how long it took, what did it print. A downstream reader (a coverage-trend dashboard, an audit log) picks up the report by file path without needing to parse the CI provider's own artefact API.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:05-per-gate-report"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-006",
+  "prdId": "PRD-001",
+  "title": "The suite emits an aggregate pipeline report summarising every gate's outcome at a stable path",
+  "description": "The suite writes a single aggregate JSON report at a stable path under the same report directory (default `.rcf/reports/ci/pipeline.json`). The aggregate report carries the suite's own start and end ISO-8601 timestamps, the total duration, an overall pass/fail verdict, the fixed ordered list of gates the suite ran, and for each gate an entry naming the gate, its outcome, its duration, and the relative path to the per-gate report file. The aggregate schema is stable within a blueprint major version.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "The per-gate reports are the detail; the aggregate report is the single record the reviewer reads first. Its stable path and stable schema make the pipeline's verdict pluckable by any downstream reader (a merge-queue tool, a dashboard, an audit trail) without knowing the gate set or its ordering.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:06-aggregate-report"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Gate failures produce operator-readable output naming the failing gate and pointing to the per-gate report",
+  "description": "When any gate in the suite fails, the Node entry point writes an operator-readable failure summary to its own stderr and to the aggregate report's `failure` field. The summary names the failing gate, the failing invocation's exit code, the first few lines of the captured stderr, and the relative path to the per-gate report file the reviewer can open for the full detail. The suite continues past a failing gate to run the remaining required gates and record their outcomes; the aggregate exit is non-zero if any gate failed.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A failed CI job shows the reviewer the tail of the runner's own output. If the failing gate does not surface its name and its report path in that tail, the reviewer clicks around the provider's UI to find the artefact. Naming the gate and its report path in the surface the reviewer already sees is the fix. Continuing past a failing gate matters because a reviewer running two failing gates should see both, not just the first.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:07-failure-surfacing"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-008",
+  "prdId": "PRD-001",
+  "title": "The suite refuses to declare a pipeline pass when any required gate report is missing from the aggregate",
+  "description": "The aggregate report's `gates` array lists every required gate in fixed configured order. If the suite completes without a corresponding per-gate report on disk for any required gate (a runner crash, an unhandled exception in a gate invocation, a report directory that was not writable), the aggregate report records the missing gate as `missing` with an explanatory reason, the aggregate verdict is `failed`, and the suite exits non-zero. A missing report is never treated as an implicit pass.",
+  "category": "nonFunctional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "The failure mode this REQ closes is silent gate skipping: a runner that dies mid-suite, a gate whose Node child process was killed, a report-directory permission error that swallowed the write. Any of those is indistinguishable from 'the gate passed' unless the suite explicitly refuses on missing reports. The aggregate report is the sole ledger of what actually ran.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:08-missing-gate-refusal"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-009.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-009",
+  "prdId": "PRD-001",
+  "title": "The blueprint ships illustrative GitHub Actions workflow files for every workflow the matrix materialises; alternate providers wire the same entry points per the four-point mapping",
+  "description": "The blueprint's package resources include one illustrative GitHub Actions workflow file per workflow the v2 matrix materialises (`pull-request-checks.yml`, `default-branch-checks.yml`, `release.yml`, and `scheduled-audit.yml` under `assets/ci-provider-examples/github-actions/`). Each file names the required trigger set for its workflow, sets up Node and the package manager, installs dependencies, invokes the corresponding Node entry point (gate-runner for the check-set workflows, release orchestrator for the release workflow, scheduled-audit runner for the cron workflow), and uploads the report directory as a workflow artefact. The blueprint's guide names GitLab CI, CircleCI, Buildkite, and Jenkins as equally supported providers, calls out the four-point mapping (job trigger, Node setup, single-line entry-point invocation, artefact upload) applied to each workflow in the matrix, and states that the blueprint does not ship provider-specific configuration for those runners in v2.0.0; sibling asset packs (v2.1 candidate) can ship them without changing the AC contracts.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "One worked example per workflow spelled in one runner language is more useful to the reader than a matrix of half-specified examples across five providers. GitHub Actions is the illustrative pick because it is the most widely deployed among rcf-lite candidate projects, not because it is privileged. The four-point mapping applies uniformly across the workflow set; extending the mapping doc to cover three or four workflows instead of one is a linear amount of writing, not a combinatorial one.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:09-provider-examples"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-010.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-010",
+  "prdId": "PRD-001",
+  "title": "The gate suite entry point is the same code path locally and in CI",
+  "description": "The Node entry point script is invocable on a developer's machine with the same command the CI provider invokes, against the same tree the developer has checked out, and produces the same per-gate reports and aggregate report at the same stable paths. A developer reproducing a CI failure runs the same one line the CI job ran; no CI-only wrapper or environment shim is on the CI code path but not the developer's.",
+  "category": "nonFunctional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A gate that only works inside the CI runner leaves the developer guessing which flag or setup step produced the failure. The Node entry point is the CI's code path and the developer's code path; a CI-only wrapper is the shape that produces 'green locally, red in CI' and slows every review. Same entry point, same reports, same failure mode.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:10-local-parity"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-011.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-011",
+  "prdId": "PRD-001",
+  "title": "The project declares its CI workflow shape in a stable in-repo configuration file the workflow-materialiser reads",
+  "description": "The project ships a `workflowShape` declaration at the stable path `.rcf/config/delivery-ci-workflows.json` on the project tree. The declaration carries three required top-level fields (`branchModel`, `checkSet`, `providerHint`), one optional top-level field (`releaseMode`; absent has the same effect as `releaseMode: none`, per Q6-B ratification), one optional fifth field (`scheduledAudit`, default false), and one optional sub-field (`trunkPullRequests`) that qualifies `branchModel: trunk`. The four-field composed form (`branchModel`, `checkSet`, `releaseMode`, `providerHint`, with `releaseMode` defaulted to `none` when absent) is the authoritative representation the downstream workflow-materialiser (TAC-704) and every AC in this blueprint bind against; the profile-alias convenience surface (REQ-013) expands to the same composed form before any consumer reads it. The declaration is a data file, not code; the workflow-materialiser reads it once at the start of every materialisation run and refuses to proceed when the file is absent or malformed.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A workflow set that scales along size and complexity axes needs a place the project declares its shape once and every workflow materialisation reads. Naming the location (`.rcf/config/delivery-ci-workflows.json`), the file shape (four required fields + optional dimensions), and the authoritative representation (four-field form) turns the elicitation surface into a stable contract the workflow-materialiser and every downstream reader can depend on. A manifest-embedded location was considered and deferred; the in-repo file surface ships with v2.0.0 without waiting on a per-blueprint mechanism-side config surface.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:11-elicitation-surface"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-012.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-012",
+  "prdId": "PRD-001",
+  "title": "A missing or unrecognised workflowShape field is refused at boot with a stable-coded error naming the field",
+  "description": "The workflow-materialiser performs a boot-check on the `workflowShape` declaration before any workflow file is produced. Any of the three required top-level fields (`branchModel`, `checkSet`, `providerHint`) being absent causes the materialiser to exit non-zero with a stable-coded error message that names the missing field. Any field (required or optional) carrying a value not in the recognised enumeration causes the same failure shape, with the message additionally naming the value it received and the allowed set. `releaseMode` being absent is NOT a failure (Q6-B ratification): the materialiser treats it as `releaseMode: none` and ships no release workflow. A `releaseMode: deployHandoff:<slug>` value additionally triggers a manifest boot-check (REQ-022) that names the required deploy blueprint if it is missing from `manifest.blueprints[]`. The boot-check runs before any workflow file is written; a partial workflow set never lands on disk.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Silent defaults on missing configuration lead to workflow sets that materialise wrong-shaped without the operator noticing. Failing fast with a message that names the missing field is what turns the elicitation surface from advisory into contractual. Stable error codes let downstream automation (a project scaffolder, an rcf-lite doctor check) match on the failure without parsing free-form text.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:12-boot-check"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-013.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-013",
+  "prdId": "PRD-001",
+  "title": "Named profile aliases expand to the authoritative four-field workflowShape form before any consumer reads it",
+  "description": "The elicitation surface accepts a named profile alias (`smallLibrary`, `smallService`, `internalPackage`, `trunkLibrary`) in place of the four-field form. On boot the workflow-materialiser detects the alias, expands it to the shipped four-field composition, and treats the expanded form as authoritative for every downstream. Every AC in this blueprint binds to the four-field form only; the alias layer is a convenience surface, not an authoritative representation. An unrecognised alias name is refused at boot with a stable-coded error naming the alias and listing the shipped set. A project that wants a shape the shipped aliases do not name uses the four-field form.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "should",
+  "rationale": "Profile aliases keep the common cases (published library, greenfield service, internal package) short and legible while preserving the four independent axes for shapes the aliases do not cover. Expanding aliases to the four-field form at boot means every downstream reader (workflow-materialiser, deploy handoff, scheduled-audit) sees one representation regardless of how the project declared it; adding an alias is additive; renaming or removing an alias is a minor bump per §2.3.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:13-profile-aliases"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-014.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-014",
+  "prdId": "PRD-001",
+  "title": "The feature-branch shape materialises pull-request-checks and default-branch-checks workflows against the required check set",
+  "description": "When `workflowShape.branchModel` is `feature`, the workflow-materialiser produces two workflows sharing the same required check set: `pull-request-checks` firing on pull requests targeting the default branch, and `default-branch-checks` firing on pushes to the default branch. Both workflows invoke the same Node gate-runner entry point (TAC-701) with the required check set produced by the two-tier catalogue (mandatory tier plus the elicited subset from `checkSet`). Both workflows write their aggregate report to the stable path and preserve the ordering discipline. The blueprint contributes an AC that the project configure default-branch protection to require the `pull-request-checks` aggregate as a merge-blocking check; the configuration itself is a project responsibility on the platform's own surface.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Feature-branch is the good default the operator ruling names and the shape the widely-adopted GitHub-flow convention describes. Naming the two workflows the shape materialises, binding both to the same check set, and stating the merge-policy property as an AC (rather than shipping a branch-protection configuration file) keeps the blueprint provider-neutral while giving the project a stated property it can verify on any platform.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:14-branch-model-feature"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-015.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-015",
+  "prdId": "PRD-001",
+  "title": "The trunk-based shape is a first-class option with a sub-shape for optional pull-request use",
+  "description": "When `workflowShape.branchModel` is `trunk`, the workflow-materialiser produces `default-branch-checks` as the always-on workflow firing on every push to the trunk branch. A nested `trunkPullRequests` field qualifies the shape: `never` (default) ships only `default-branch-checks`; `sometimes` additionally ships `pull-request-checks` against the same check set. The merge-policy AC states the property differently per sub-shape: without PRs, the trunk branch's push protection admits only commits whose `default-branch-checks` aggregate passed; with PRs, the trunk branch's protection admits only PRs whose `pull-request-checks` aggregate passed. Every other contract (check catalogue, report shape, ordering) is shared with the feature-branch shape.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Trunk-based development is a first-class shape the operator ruling named, not an afterthought. The two sub-shapes (with and without PRs) cover the archetypal trunk-based posture and the common hybrid; the nested sub-field keeps the top-level enumeration at the two archetypes. Sharing the check catalogue and report shape across both branch models means a project that migrates between them changes trigger sets, not check contracts.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:15-branch-model-trunk"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-016.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-016",
+  "prdId": "PRD-001",
+  "title": "A linter check the project realises produces a stable-shape lint report and fails non-zero on any lint error",
+  "description": "The elicited `linter` check, when the project enables it in `workflowShape.checkSet.linter`, runs a lint gate that exits non-zero on any lint error the project treats as blocking. The gate writes its per-gate report to `.rcf/reports/ci/lint.json` in the shared per-gate report shape (with `checkKind: \"linter\"`). The blueprint does not pick the linter tool; the project realises the runner over the tool of its choice and satisfies the runner-contract interface the gate-runner TAC binds. Warnings that the project does not treat as blocking are reported in the per-gate report without flipping the exit code.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A lint gate that runs but does not gate is a lint gate that quietly rots; a lint gate whose report shape drifts across projects is a gate downstream readers cannot depend on. Naming the exit-code semantic, the report path, and the report shape as an AC contract turns the linter check into a stable surface without forcing a tool choice.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:16-check-linter"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-017.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-017",
+  "prdId": "PRD-001",
+  "title": "A formatter check the project realises produces a stable-shape formatter report and fails non-zero on any unformatted file",
+  "description": "The elicited `formatter` check, when the project enables it in `workflowShape.checkSet.formatter`, runs a formatter check gate (not a formatter write) that exits non-zero when any tracked file would be rewritten by the formatter. The gate writes its per-gate report to `.rcf/reports/ci/format.json` in the shared per-gate report shape (with `checkKind: \"formatter\"`). The blueprint does not pick the formatter; the project realises the runner and satisfies the runner-contract interface.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A formatter used as a WRITE step masks unformatted commits; a formatter used as a CHECK step fails the pipeline on any unformatted file. Binding the check-mode semantic and the report shape as an AC contract keeps the property stable while leaving the tool choice to the project.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:17-check-formatter"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-018.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-018",
+  "prdId": "PRD-001",
+  "title": "A typecheck the project realises produces a stable-shape typecheck report and fails non-zero on any type error",
+  "description": "The elicited `typecheck` check, when the project enables it in `workflowShape.checkSet.typecheck`, runs a typechecker gate that exits non-zero on any type error. The gate writes its per-gate report to `.rcf/reports/ci/typecheck.json` in the shared per-gate report shape (with `checkKind: \"typecheck\"`). The check is applicable only when the project uses a typed language or a TypeScript-style build; the workflow-materialiser turns the check on by default when the project tree contains a `tsconfig.json` or an equivalent tool marker, off otherwise. The project overrides the auto-detection by setting the check-set flag explicitly.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A typecheck gate belongs on any project with a typechecker; a project without one has no runner to satisfy the contract. Auto-detecting from a stable marker (a `tsconfig.json` or equivalent) keeps the default aligned with project shape while preserving the explicit override.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:18-check-typecheck"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-019.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-019",
+  "prdId": "PRD-001",
+  "title": "A unit-test check the project realises produces a stable-shape test report and fails non-zero on any failing test",
+  "description": "The elicited `unitTest` check, when the project enables it in `workflowShape.checkSet.unitTest`, runs the project unit-test suite as a gate that exits non-zero on any failing test. The gate writes its per-gate report to `.rcf/reports/ci/test.json` in the shared per-gate report shape (with `checkKind: \"unitTest\"`). The blueprint does not pick the test runner; the project realises the runner and satisfies the runner-contract interface. A missing runner (an empty test suite before the project has any tests) is recorded in the per-gate report and does not by itself fail the gate.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A unit-test gate is table stakes for any greenfield project; naming it in the elicited catalogue keeps the default set aligned with what a project engineer expects to find in a CI floor. Preserving the tool choice at the project layer is what keeps the blueprint neutral across test frameworks.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:19-check-unit-test"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-020.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-020",
+  "prdId": "PRD-001",
+  "title": "A security-scan check the project realises produces a stable-shape scan report and fails non-zero on findings above the project threshold",
+  "description": "The elicited `securityScan` check, when the project enables it in `workflowShape.checkSet.securityScan`, runs a dependency-and-secret scan gate that exits non-zero when the scan finds any advisory at or above the project-configured severity threshold. The gate writes its per-gate report to `.rcf/reports/ci/security.json` in the shared per-gate report shape (with `checkKind: \"securityScan\"`). Findings below the threshold are reported in the per-gate report without flipping the exit code. The severity threshold is a project decision; the blueprint does not opine on the threshold.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "A security scan whose severity threshold is a build-in choice punishes projects whose risk posture is different from the blueprint author's; a threshold the project owns keeps the gate applicable across risk postures. Binding the exit-code semantic and the report shape as an AC contract preserves the stable surface downstream readers depend on.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:20-check-security-scan"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-021.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-021",
+  "prdId": "PRD-001",
+  "title": "The release workflow shape scales with the releaseMode dimension across four discrete modes",
+  "description": "When `workflowShape.releaseMode` is `none`, no release workflow ships. When `tagOnly`, a release workflow fires on the project-declared release trigger (a `release` event, a `workflow_dispatch`, or both) and creates a release entity on the CI provider's own release surface (a GitHub Release, a GitLab release, whatever the provider ships). When `tagPlusArtefact`, the release workflow also runs the project-realised artefact-publish step and uploads its output to the release entity; the AC contract requires the artefact-publish step to produce a verified artefact reachable at a stable identifier. When `deployHandoff:<slug>`, the release workflow additionally invokes the named deploy blueprint's promote workflow per REQ-022. The release workflow does not run the required check set; the check set already ran on the default-branch-checks workflow at the commit the release points at.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Release workflow shape scales with project maturity: an internal package has no release path (mode `none`); a documented release stamps a tag (`tagOnly`); a published library adds an artefact (`tagPlusArtefact`); a paired service hands off to deploy (`deployHandoff`). Four discrete modes cover the maturity range without inventing intermediate states the operator has to reason about. Excluding the check set from the release workflow avoids the redundant run-and-lengthen pattern.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:21-release-mode"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-022.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-022",
+  "prdId": "PRD-001",
+  "title": "The deployHandoff release mode invokes the named deploy blueprint's promote workflow and refuses at boot when that blueprint is absent",
+  "description": "When `workflowShape.releaseMode` is `deployHandoff:<slug>`, the release workflow invokes the named deploy blueprint's `promote` workflow via that blueprint's declared invocation contract (a `workflow_dispatch` event carrying the just-published version identifier as the `versionId` input). The release workflow's aggregate outcome is `passed` only when the promote workflow's outcome is `passed`. The workflow-materialiser performs a boot-check that refuses the value when the named deploy blueprint is absent from `manifest.blueprints[]`; the error names the missing blueprint by slug and points at `rcf define blueprint add <deploy-slug>` as the resolution.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Cross-blueprint composition works when the composing blueprint reaches for a stated invocation contract on the composed side, not when it duplicates the composed side's implementation. The `versionId`-optional-input contract on the deploy blueprint's promote workflow is already ratified; the release workflow calls it and inherits the promote workflow's outcome. The manifest boot-check catches the misconfiguration case (a project declaring a handoff to a target it has not applied) before the release workflow lands on disk.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:22-deploy-handoff"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/requirements/delivery-ci-workflows-req-023.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "delivery-ci-workflows-REQ-023",
+  "prdId": "PRD-001",
+  "title": "An optional scheduledAudit dimension materialises a cron-triggered workflow running the required check set on cadence",
+  "description": "When `workflowShape.scheduledAudit` is `true`, the workflow-materialiser produces a `scheduled-audit` workflow that fires on a cron schedule (the provider's own schedule surface) and runs the same required check set the pull-request and default-branch workflows run. When the field is `false` (default), no scheduled workflow ships. The scheduled-audit workflow writes its aggregate report to a distinct stable path (`.rcf/reports/ci/scheduled-audit.json`) so a scheduled-run outcome never overwrites the most recent commit-triggered outcome downstream readers depend on.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Dependency updates and secret rotations do not always coincide with a merge; a scheduled cadence catches drift the commit-triggered workflows would miss. Making the dimension explicit (a top-level fifth field) rather than folding it under a specific check's cadence keeps the axis general: a future need for scheduled cadence on other checks generalises to `scheduledCadence: string` without displacing the fifth dimension.",
+  "tags": [
+    "blueprint:delivery-ci-workflows",
+    "category:23-scheduled-audit"
+  ],
+  "version": "2.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-31T00:00:00Z",
+  "updatedAt": "2026-08-31T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/tacs/tac-701-delivery-ci-workflows-gate-runner.json

@@ -0,0 +1,59 @@
+{
+  "tacId": "TAC-701-delivery-ci-workflows-gate-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Gate runner (Node entry point)",
+  "purpose": "The single Node entry-point module the project realises and that any CI provider invokes with one command line. Owns the ordered execution of the configured gate set, the capture of each gate's exit code and streams, the delegation to the per-gate report writer (TAC-702), the delegation to the aggregate report writer (TAC-703), and the shape of the operator-visible failure summary written to stderr on any gate failure.",
+  "responsibilities": [
+    "Expose a Node entry point (a single `.js` or `.mjs` file) invocable as `node <path>` with no shell glue; the entry point path is stable and recorded on the aggregate report's `runner.entryPoint` field (AC-6102-1, AC-6102-2, AC-6110-1).",
+    "Read gate configuration (gate set, gate ordering, report directory) from configuration inputs available equally in CI and on a developer machine; refuse to gate control flow on CI-provider-specific environment variables (AC-6110-2).",
+    "Invoke each configured gate as a Node child process against the project tree; capture the child's exit code, stdout, and stderr; measure start/end wall-clock timestamps and duration (AC-6103-1, AC-6104-1).",
+    "Run `rcf define validate` as the first required gate; run `rcf audit coverage --strict` as the second required gate; continue past a failing gate to run the remaining required gates (AC-6103-2, AC-6104-2, AC-6107-2).",
+    "Delegate per-gate report writing to TAC-702 on every gate completion (pass or fail); delegate aggregate report writing to TAC-703 on suite completion (AC-6105-1, AC-6106-1).",
+    "On any gate failure, write a single-line operator-readable failure summary to the entry point's own stderr naming the failing gate, its exit code, and the relative path to the per-gate report file (AC-6107-1).",
+    "Detect missing per-gate report files (a gate whose child process was killed, exited with an uncaught exception, or whose report write failed) and record the affected gate as `missing` with a reason in the aggregate report; exit non-zero on any missing outcome (AC-6108-1, AC-6108-2).",
+    "Exit non-zero when the aggregate verdict is `failed`; exit zero only when every gate outcome is `passed` (AC-6101-2, AC-6103-2, AC-6104-2)."
+  ],
+  "internalStructure": "One Node module that exports a `runGates({ reportDir, gates, cwd })` function and a shebang entry point that reads its configuration and calls `runGates`. The gate set is a small array of `{ name, command }` descriptors; the runner spawns each command as a child process (Node's `child_process.spawn`), streams stdout/stderr into buffers with size caps, times the child, and hands the recorded fields to the per-gate report writer. A finaliser catches any thrown exception in the gate loop, marks the affected gate `missing` with an exception-derived reason, and continues. The aggregate writer is called once at loop end with the accumulated gate records.",
+  "interfaces": [
+    {
+      "name": "runGates",
+      "kind": "factory",
+      "description": "runGates({ reportDir, gates, cwd }) -> Promise<{ verdict, exitCode, aggregateReportPath }>; the sole callable the entry point invokes. Runs every gate in `gates` order, delegates each report write, resolves with the final verdict."
+    },
+    {
+      "name": "gate-descriptor",
+      "kind": "value",
+      "description": "{ name: string, command: string[] } where `command[0]` is the executable (typically `rcf`) and the rest are argv. The set-of-two required for v1.0.0 is `[{ name: 'validate', command: ['rcf', 'validate'] }, { name: 'coverage-strict', command: ['rcf', 'coverage', '--strict'] }]`."
+    },
+    {
+      "name": "entry-point CLI",
+      "kind": "cli",
+      "description": "`node <entryPointPath>` with no required argv. Optional flag `--report-dir <path>` overrides the default report directory. Exit code is the aggregate exit code."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Per-gate report writer",
+      "kind": "tac",
+      "tacId": "TAC-702-delivery-ci-workflows-gate-report",
+      "description": "Called once per gate with the captured fields; writes the per-gate JSON report and returns the file path the aggregate writer records."
+    },
+    {
+      "name": "Aggregate report writer",
+      "kind": "tac",
+      "tacId": "TAC-703-delivery-ci-workflows-aggregate-report",
+      "description": "Called once at end-of-suite with the ordered gate records; writes the aggregate JSON report and returns the verdict and its exit code."
+    },
+    {
+      "name": "rcf CLI",
+      "kind": "external",
+      "description": "The underlying `rcf` binary the child processes invoke. The runner does not import rcf as a library; every gate is a separate Node process."
+    }
+  ],
+  "tradeoffs": "Running every gate as a separate child process costs Node startup for each; that cost buys a stable exit-code contract and a stable stream capture surface that a library-mode invocation would obscure. Continuing past a failing gate costs a slightly longer pipeline; that cost buys the reviewer seeing every failure on one run instead of chasing them one at a time. The runner does not run gates in parallel: gate ordering is a stable property the aggregate report depends on, and the small gate count at v1.0.0 does not motivate a parallel-and-serialise design.",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/delivery-ci-workflows/contributions/tacs/tac-702-delivery-ci-workflows-gate-report.json

@@ -0,0 +1,32 @@
+{
+  "tacId": "TAC-702-delivery-ci-workflows-gate-report",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Per-gate report writer",
+  "purpose": "The module that writes one JSON report per gate invocation to a stable relative path under the configured report directory. Owns the per-gate report schema (fixed key set, typed values) and the atomic write posture that makes a partially written report distinguishable from a missing one.",
+  "responsibilities": [
+    "Write a JSON file at `<reportDir>/<gate>.json` for every gate the runner invoked, whether the gate passed or failed (AC-6105-1).",
+    "Populate the fixed key set on every report: `gate`, `command`, `toolVersion`, `startedAt`, `endedAt`, `durationMs`, `exitCode`, `outcome`, `stdout`, `stderr`. Value types match the stable schema (ISO-8601 strings, integer durations, integer exit codes, `outcome` is one of `passed` or `failed`) (AC-6105-1).",
+    "Capture the underlying CLI's tool-version string (from `rcf --version`) at the time the gate runs; write it verbatim to the `toolVersion` field (AC-6105-2).",
+    "Ensure the file is created via an atomic write posture (write to a sibling temp file, then rename) so a killed writer leaves either the previous file or no file at all, not a truncated file the aggregate writer would misread as a valid report."
+  ],
+  "internalStructure": "One module that exports a `writeGateReport({ reportDir, gate, command, toolVersion, startedAt, endedAt, exitCode, stdout, stderr })` function returning the written file's absolute path. Serialises the fixed key set to JSON with 2-space indent (human-readable diffs); writes to `<reportDir>/<gate>.json.tmp`; renames to `<reportDir>/<gate>.json` on close. Truncates captured streams past a size cap (default 256KB per stream) with a trailing `[truncated]` marker so a runaway gate does not fill the disk.",
+  "interfaces": [
+    {
+      "name": "writeGateReport",
+      "kind": "write-api",
+      "description": "writeGateReport({ reportDir, gate, command, toolVersion, startedAt, endedAt, exitCode, stdout, stderr }) -> Promise<string>. Writes the per-gate JSON report atomically and resolves with the written file's absolute path."
+    },
+    {
+      "name": "gate-report-schema",
+      "kind": "schema",
+      "description": "Top-level keys exactly: `gate` (string), `command` (string[]), `toolVersion` (string), `startedAt` (ISO-8601 string), `endedAt` (ISO-8601 string), `durationMs` (integer), `exitCode` (integer), `outcome` (enum `passed` | `failed`), `stdout` (string), `stderr` (string). No other keys are written at v1.0.0."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The atomic rename posture costs one extra file-system syscall per report; that cost buys the aggregate writer being able to distinguish a valid report from a partial one. Truncating streams past 256KB costs the tail of a very verbose gate; that cost buys bounded disk usage on runaway gate loops. The report schema is fixed within a major version: adding a new key is a minor bump (additive), removing or renaming a key is a major bump.",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}