rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-701-ci-pipeline-ci-gates",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The project's CI runs a fixed ordered required-gate set (validate then coverage-strict at v1.0.0) 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 gate set: which gates run, in which order, and what does 'the pipeline passed' mean. A project that changes its gate set silently loses the property that the pipeline meant the same thing across two runs. The rcf-lite tier this blueprint targets is small greenfield: one tree, one default branch, one merge policy. Naming the gate set as a decision area (not a runtime knob) is what makes the pipeline a stable contract.",
+  "decision": "The project's CI runs a fixed ordered required-gate set. At v1.0.0 the set is exactly two gates in order: `validate` (running `rcf define validate`) followed by `coverage-strict` (running `rcf audit coverage --strict`). The pipeline passes if and only if every required gate's outcome is `passed`; a `failed` or `missing` outcome on any required gate fails the pipeline. Adding a required gate is a project-level or blueprint-level ADR: a project that wants an extra required gate (a linter, a unit-test runner, an adherence pack) supersedes this ADR with a project-level ADR listing the extended set; a future blueprint that ships a new required gate (an observability probe pack) is a blueprint version bump on this ADR's topic. The set is deliberately kept small at v1.0.0: two gates that speak to the RCF chain and its coverage. Every additional gate is a decision the project owes an ADR for.",
+  "consequences": "The pipeline's verdict is stable across runs of the same commit under the same rcf CLI version. Adding a gate is a visible decision, not a diff to a job file. A project that wants a hotter set of gates (adherence packs, browser-verify smokes, style linters) owes a project-level ADR that supersedes this one and lists the extended set; the aggregate report's `gates[]` array then reflects the extended set on every run. Composing blueprints that hold an opinion on the required-gate 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-gate set at v1.0.0 (validate + coverage-strict + adherence packs + browser-verify)",
+      "summary": "The pipeline runs every gate the mechanism offers as required by default.",
+      "reasonNotChosen": "The mechanism-reach principle for blueprints (authoring standard, section 7) says a blueprint should not compel a gate 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. Two gates the mechanism already ships and every project can satisfy is the right v1.0.0 floor."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/adrs/adr-702-ci-pipeline-strict-coverage-gate.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-702-ci-pipeline-strict-coverage-gate",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Coverage runs as per-AC strict; shallow-any is not accepted as a substitute in the required gate set",
+  "context": "The `rcf audit coverage` CLI runs in two modes: the default `shallow-any` (a REQ counts as covered when any AC on any US has any resolving TC) and the opt-in `--strict` (per-AC: every AC on every US must have a resolving TC). Shallow-any is useful for author-time exploration; it is the wrong mode for a merge-blocking gate because it hides the failure mode watchpost run4 caught in categories 5, 6, and 11 (an AC bound but no TC resolves it, and the REQ still reads as covered because some other AC's TC resolved). Choosing which coverage mode the pipeline runs is a policy decision distinct from choosing whether coverage runs at all.",
+  "decision": "The required-gate coverage invocation is `rcf audit coverage --strict`. Every AC on every US must resolve to a TC whose testPointer points at a real test; a `covered-unresolved` or uncovered AC fails the gate. Shallow-any is not accepted as a substitute in the required-gate set. A project that needs an author-time shallow-any view for exploration runs `rcf audit coverage` locally without `--strict`; the pipeline's gate is unaffected. Composing blueprints that ship a coverage gate hold this topic (`strictCoverageGate`) and conflict here by design: a hypothetical `ci-pipeline-shallow` blueprint or a project that wants the shallow-any mode as its floor supersedes this ADR with a project-level ADR stating the reasoning.",
+  "consequences": "Every AC the RCF chain contributes must have a TC bound in the project's own build cycle before the pipeline turns green. That is the mechanism-reach discipline the strict mode enforces: shipping an AC without a TC is caught here, not in production. Composing blueprints (this one and any coverage-shipping blueprint the ecosystem grows) conflict on `strictCoverageGate` for one project-level ADR to fix. A project that thoughtfully accepts a shallow-any floor (small project, exploration phase, no operator-facing surface yet) authors that ADR and the pipeline follows.",
+  "alternativesConsidered": [
+    {
+      "name": "Run shallow-any as the required mode with strict as a warning gate",
+      "summary": "The pipeline runs `rcf audit coverage` in shallow-any mode as required and `rcf audit coverage --strict` as a soft advisory gate whose outcome does not block merge.",
+      "reasonNotChosen": "A warning gate people learn to ignore is a gate that does not exist. The strict-mode failures watchpost run4 caught were exactly the ones a warning-only gate would have surfaced and been dismissed. Strict as required is the shape that makes the mechanism useful in review."
+    },
+    {
+      "name": "Run strict only after a grace period per REQ / US",
+      "summary": "Newly introduced ACs get a configurable grace window during which strict does not enforce coverage; established ACs must have coverage.",
+      "reasonNotChosen": "A grace window is another gate-set knob whose meaning drifts across projects. The current shape (project-level ADR to relax) is the sharper knob; a project that genuinely needs a rolling window authors it as a project-level ADR and lists the reasoning."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/adrs/adr-703-ci-pipeline-node-only-runner.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-703-ci-pipeline-node-only-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The gate runner is a single Node entry point; one illustrative GitHub Actions workflow is shipped; alternate providers wire the same script",
+  "context": "A blueprint that ships CI configuration has two shapes to pick between. Shape one: contribute a provider-specific configuration file (a GitHub Actions workflow YAML, a GitLab CI YAML, a CircleCI config) with every gate spelled in that provider's runner language. Shape two: contribute a Node entry-point script that any provider invokes with one command line, and ship one illustrative provider example as a starting point. Shape one locks the project to the picked provider; shape two lets any provider that can run Node host the pipeline. The rcf-lite tier does not privilege one provider.",
+  "decision": "The blueprint ships shape two. The gate runner is a single Node entry-point script the project realises under its source tree; every gate-specific piece of logic (spawning the child, capturing streams, writing per-gate reports, writing the aggregate report, surfacing failure) lives in Node. The blueprint's package resources include exactly one illustrative provider workflow: `assets/ci-provider-examples/github-actions.yml`, chosen because GitHub Actions is the most widely deployed among rcf-lite candidate projects. The guide names GitLab CI, CircleCI, Buildkite, and Jenkins as equally supported and describes the four-point mapping (job trigger event, Node setup, single-line entry-point invocation, artefact upload) for each. No provider-specific configuration file for those runners is shipped at v1.0.0. A future blueprint that ships one, or a project that hand-authors one, wires the same Node entry point.",
+  "consequences": "A project on any CI provider that can run Node (every mainstream provider) hosts the pipeline with a one-line invocation. Moving between providers is a rewrite of the trigger definition and the artefact-upload step, not a rewrite of the gates. The illustrative GitHub Actions workflow is a starting point, not a blessed choice: an operator moving to another provider translates the four mapping points and keeps the entry-point invocation unchanged. The blueprint does not carry the maintenance cost of a matrix of provider examples; each example would need to track that provider's syntax changes and version pins, which is a per-provider decision the project owns.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship a matrix of provider-specific configuration files (GHA + GitLab CI + CircleCI + Buildkite + Jenkins) at v1.0.0",
+      "summary": "The blueprint contributes one configuration file per supported provider so the operator can copy the one that matches.",
+      "reasonNotChosen": "Every provider file needs its own version pins, its own action or plugin references, and its own syntax bumps. Five files stale at different rates and the blueprint's ship gate would include verifying every one still works on every provider. One worked example plus the mapping paragraph is the sharper contribution."
+    },
+    {
+      "name": "Ship a bash gate runner instead of Node",
+      "summary": "The gate runner is a shell script the CI provider invokes.",
+      "reasonNotChosen": "Bash is not portable across the operator's development host (macOS default bash is 3.2, Windows has no bash without WSL, and cross-platform bash gymnastics are the shape that ships broken). Node runs identically on every host that ships an rcf-lite project, and the same Node runtime that runs the underlying rcf CLI runs the gate runner without a second toolchain."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/adrs/adr-704-ci-pipeline-report-shape.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-704-ci-pipeline-report-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Per-gate and aggregate reports are JSON files at stable paths under a configured report directory; missing reports are never treated as an implicit pass",
+  "context": "A pipeline whose only artefact is the CI provider's own runner-log surface leaves every downstream reader (reviewer, dashboard, audit tool) parsing text or hitting the provider's artefact API. A pipeline whose reports are files at stable paths with stable schemas turns every downstream reader into a JSON reader. The reporting shape is a decision that binds the runner (TAC-701), the per-gate writer (TAC-702), the aggregate writer (TAC-703), and every future consumer.",
+  "decision": "Every gate the suite runs writes a per-gate JSON report at `<reportDir>/<gate>.json` with a fixed key set (gate, command, toolVersion, startedAt, endedAt, durationMs, exitCode, outcome, stdout, stderr). The suite writes one aggregate JSON report at `<reportDir>/pipeline.json` with a fixed key set (verdict, trigger, startedAt, endedAt, durationMs, runner, gates[]). The default report directory is `.rcf/reports/ci/`. Both schemas are stable within a blueprint major version: additive fields are a minor bump, renamed or removed fields are a major bump. Reports are written atomically (temp file plus rename) so a killed writer leaves either the previous file or no file. A required gate whose per-gate report is missing from disk at end-of-suite is recorded in the aggregate as `outcome: missing` with a reason string, and the aggregate verdict is `failed`. A missing report is never treated as an implicit pass.",
+  "consequences": "Downstream readers pick up per-run outcomes without re-running gates and without scraping the CI provider's log surface. Long-lived tools (a coverage-trend dashboard, an audit log, a merge-queue gate) depend on stable paths and stable schemas; the discipline here is what makes those tools cheap to write. The aggregate report is the single record the reviewer opens first; its `gates[]` array in fixed configured order is the ordering contract. A runner crash mid-suite (the failure mode REQ-008 closes) is visible in the aggregate rather than silently omitted. The atomic-write posture costs one extra file-system syscall per report; the truncation cap on stdout/stderr costs the tail of a very verbose gate.",
+  "alternativesConsidered": [
+    {
+      "name": "Use JUnit XML as the per-gate report format",
+      "summary": "The runner emits per-gate JUnit XML files so the CI provider's own JUnit ingestor can parse them.",
+      "reasonNotChosen": "JUnit XML is a test-report format, not a gate-invocation format; the schema does not carry the fields the aggregate report needs (tool version, captured streams, structured exit code, gate ordering). A downstream reader that wants a JUnit view of the pipeline layers a JUnit converter over the JSON reports on the side; the blueprint does not ship it as the primary surface."
+    },
+    {
+      "name": "Rely on the CI provider's artefact system without writing report files",
+      "summary": "The runner writes to stdout only; every downstream reader retrieves outcomes through the provider's artefact or annotation API.",
+      "reasonNotChosen": "That posture couples every downstream reader to the CI provider's API and breaks the local-parity property REQ-010 mandates (the developer running the entry point locally has no report file to inspect). Files at stable paths under a configured directory are equally available in CI (uploaded as artefacts) and locally (read from disk)."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Every push and pull request into the default branch runs the RCF gate suite as a required check",
+  "description": "The project's continuous integration pipeline runs the RCF gate suite on every push to the default branch and on every pull request that targets the default branch. The suite's aggregate exit status is the merge criterion: the branch protection or equivalent policy refuses to merge a pull request whose most recent suite run did not exit zero. No manual override path bypasses the suite; a hotfix that skips the suite requires a documented ADR trail.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "Gates that run sometimes are gates that fail sometimes. Wiring the suite as a required check on every push and pull request into the default branch turns the RCF chain 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.",
+  "tags": [
+    "blueprint:ci-pipeline",
+    "category:01-required-check"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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:ci-pipeline",
+    "category:02-provider-neutral"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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:ci-pipeline",
+    "category:03-validate-gate"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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:ci-pipeline",
+    "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/ci-pipeline/contributions/requirements/ci-pipeline-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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, and the captured stdout and stderr strings. The report file's schema is stable within a blueprint major version.",
+  "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:ci-pipeline",
+    "category:05-per-gate-report"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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:ci-pipeline",
+    "category:06-aggregate-report"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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:ci-pipeline",
+    "category:07-failure-surfacing"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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:ci-pipeline",
+    "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/ci-pipeline/contributions/requirements/ci-pipeline-req-009.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-REQ-009",
+  "prdId": "PRD-001",
+  "title": "The blueprint documents one illustrative GitHub Actions workflow; alternate providers wire the same entry point per their own runner language",
+  "description": "The blueprint's package resources include one illustrative GitHub Actions workflow file (`assets/ci-provider-examples/github-actions.yml`) that names the required repository events (push to default branch, pull_request into default branch), sets up Node and the package manager, installs dependencies, invokes the Node gate entry point, 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 mapping (job trigger, Node setup, single-line entry-point invocation, artefact upload), and states that the blueprint does not ship provider-specific configuration for those runners.",
+  "category": "functional",
+  "domain": "continuous-integration",
+  "priority": "must",
+  "rationale": "One worked example spelled in one runner language is more useful to the reader than a matrix of half-specified examples. GitHub Actions is the illustrative pick because it is the most widely deployed among rcf-lite candidate projects, not because it is privileged. The mapping to other providers is small enough that a paragraph of guide prose plus the one worked example is the right cost.",
+  "tags": [
+    "blueprint:ci-pipeline",
+    "category:09-provider-example"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/requirements/ci-pipeline-req-010.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "ci-pipeline-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:ci-pipeline",
+    "category:10-local-parity"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

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

@@ -0,0 +1,59 @@
+{
+  "tacId": "TAC-701-ci-pipeline-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-ci-pipeline-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-ci-pipeline-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/ci-pipeline/contributions/tacs/tac-702-ci-pipeline-gate-report.json

@@ -0,0 +1,32 @@
+{
+  "tacId": "TAC-702-ci-pipeline-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"
+}

package/blueprints/ci-pipeline/contributions/tacs/tac-703-ci-pipeline-aggregate-report.json

@@ -0,0 +1,41 @@
+{
+  "tacId": "TAC-703-ci-pipeline-aggregate-report",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Aggregate report writer",
+  "purpose": "The module that writes the single aggregate JSON report at `<reportDir>/pipeline.json` at the end of every suite invocation. Owns the aggregate report schema, the fixed-order gate array, the missing-report detection pass, and the verdict rule that maps per-gate outcomes to the aggregate verdict.",
+  "responsibilities": [
+    "Write a JSON file at `<reportDir>/pipeline.json` on every suite completion (AC-6106-1).",
+    "Populate the fixed key set: `verdict`, `trigger`, `startedAt`, `endedAt`, `durationMs`, `runner` (with nested `entryPoint`, optional `environment`), and `gates[]` (each entry naming `gate`, `outcome`, `durationMs`, `reportPath`, optional `reason` on missing) (AC-6106-1, AC-6102-1, AC-6110-2).",
+    "Order the `gates[]` array in the fixed configured order (the runner's gate set), not in completion order (AC-6108-1).",
+    "For each configured gate, check whether the corresponding per-gate report exists on disk; if not, record the entry as `outcome: missing` with a `reason` string derived from the runner's captured failure (killed child, uncaught exception, write failure, permission error) (AC-6108-1).",
+    "Set `verdict: passed` if and only if every gate entry's outcome is `passed`; otherwise set `verdict: failed`. A single `failed` or `missing` outcome flips the aggregate verdict (AC-6106-2, AC-6108-1, AC-6108-2).",
+    "Return the aggregate exit code to the runner: 0 on `passed`, non-zero on `failed`."
+  ],
+  "internalStructure": "One module that exports a `writeAggregateReport({ reportDir, trigger, startedAt, endedAt, runner, gates })` function returning `{ verdict, exitCode, aggregateReportPath }`. Walks the ordered `gates` input, checks each per-gate report file's existence, resolves each `reportPath` to a relative path from `reportDir`. Serialises the fixed key set to JSON with 2-space indent, writes atomically (temp + rename). Never writes `verdict: passed` while any gate outcome is other than `passed`.",
+  "interfaces": [
+    {
+      "name": "writeAggregateReport",
+      "kind": "write-api",
+      "description": "writeAggregateReport({ reportDir, trigger, startedAt, endedAt, runner, gates }) -> Promise<{ verdict, exitCode, aggregateReportPath }>. Writes the aggregate JSON report atomically and resolves with the verdict and the aggregate exit code."
+    },
+    {
+      "name": "aggregate-report-schema",
+      "kind": "schema",
+      "description": "Top-level keys exactly: `verdict` (enum `passed` | `failed`), `trigger` (string; the CI event kind or `local`), `startedAt` (ISO-8601), `endedAt` (ISO-8601), `durationMs` (integer), `runner` (object with `entryPoint` string and optional `environment` object), `gates[]` (array of `{ gate, outcome, durationMs, reportPath, reason? }` in configured order). No other keys at v1.0.0."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Per-gate report writer",
+      "kind": "tac",
+      "tacId": "TAC-702-ci-pipeline-gate-report",
+      "description": "The per-gate reports the aggregate writer reads back to confirm each report's existence and to record its relative path in the aggregate."
+    }
+  ],
+  "tradeoffs": "The verdict rule is deliberately strict: any non-`passed` outcome flips the aggregate. A more nuanced rule (advisory gates, warning outcomes) is a v1.1 minor-bump candidate; v1.0.0 does not ship it because the two required gates are both hard gates. The aggregate schema is fixed within a major version; additive fields are a minor bump.",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6101.json

@@ -0,0 +1,37 @@
+{
+  "usId": "ci-pipeline-US-6101",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every push and pull request into the default branch runs the RCF gate suite as a required check",
+  "asA": "operator merging changes to the default branch of an rcf-lite project",
+  "iWant": "the RCF gate suite to run automatically on every push to the default branch and every pull request into it, and its outcome to be the merge criterion",
+  "soThat": "no change lands on the default branch without the chain and its coverage having been verified against the tree at the head commit",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6101-1",
+      "description": "The CI provider's job for the pipeline is triggered by a push to the default branch and by every pull request opened, synchronised, or reopened against the default branch. The trigger configuration is committed under source control, not set through a provider UI.",
+      "given": "the project's CI configuration and repository state at the head commit",
+      "when": "a push lands on the default branch or a pull request is opened, synchronised, or reopened against the default branch",
+      "then": "the aggregate pipeline report at the configured stable path (default `.rcf/reports/ci/pipeline.json`) is written by the resulting CI job, and its `trigger` field records the event kind",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6101-2",
+      "description": "The pull-request merge policy blocks a merge whose most recent pipeline run did not exit zero. The block is enforced by the repository's branch protection or equivalent policy configured for the default branch.",
+      "given": "a pull request whose most recent pipeline run's aggregate report records `verdict: failed`",
+      "when": "the operator or an automated merge tool attempts to merge the pull request through the standard merge path",
+      "then": "the merge is refused by the platform's branch-protection surface, and the refusal reason references the failed required check that corresponds to the pipeline job",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner",
+    "TAC-703-ci-pipeline-aggregate-report"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6102.json

@@ -0,0 +1,36 @@
+{
+  "usId": "ci-pipeline-US-6102",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The gate suite is invoked as one Node entry point that any CI provider can run",
+  "asA": "operator picking or moving between CI providers on an rcf-lite project",
+  "iWant": "the gate suite to be a plain Node script the CI job invokes with one line",
+  "soThat": "moving from one provider to another is a rewrite of the trigger definition, not a rewrite of the gates",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6102-1",
+      "description": "The gate runner is a single Node entry point on disk under the project's tree (a script or module invocable as `node <path>` with no shell glue). The runner's file path is the same on every host.",
+      "given": "the project tree at the head commit",
+      "when": "the aggregate report is written by any CI run",
+      "then": "the aggregate report's `runner.entryPoint` field records a project-relative path to a `.js` or `.mjs` file that exists at that path in the tree",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6102-2",
+      "description": "The CI provider's job definition invokes the gate runner with a single command line: a `node <path>` invocation (or a package-manager script that resolves to the same). No gate-specific logic sits inside the CI provider's job definition.",
+      "given": "the project's CI configuration file(s) committed under source control",
+      "when": "an operator reads the job step that produces the pipeline report",
+      "then": "the step is a single-line invocation of the Node entry point (or an equivalent package-manager script), and every gate-level branching, timing, and report-writing responsibility lives inside the Node runner rather than the CI configuration",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/ci-pipeline/contributions/user-stories/ci-pipeline-us-6103.json

@@ -0,0 +1,37 @@
+{
+  "usId": "ci-pipeline-US-6103",
+  "prdId": "PRD-001",
+  "reqId": "ci-pipeline-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The suite runs the validate gate and fails the pipeline on any non-zero exit",
+  "asA": "reviewer opening a pull request against the default branch",
+  "iWant": "the pipeline to have already run `rcf define validate` against the head commit's tree and refused the run on any schema or reference issue",
+  "soThat": "I never review a change whose chain is structurally broken",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-6103-1",
+      "description": "The suite invokes `rcf define validate` before any other gate. The gate's exit code, captured stdout, and captured stderr are written to a per-gate report at the configured stable path.",
+      "given": "the pipeline has run against the head commit",
+      "when": "the reviewer opens the per-gate report file at `<reportDir>/validate.json`",
+      "then": "the file exists, its `gate` field is `validate`, its `command` field names the `rcf define validate` invocation, its `exitCode` field records the underlying process exit code, and its `stdout` and `stderr` fields carry the captured streams",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-6103-2",
+      "description": "A non-zero exit from `rcf define validate` marks the aggregate verdict as failed and the aggregate exit code as non-zero. The pipeline does not proceed to declare the run passed on the basis of downstream gates alone.",
+      "given": "an invocation of the suite against a tree that fails `rcf define validate` (a deliberately broken reference)",
+      "when": "the suite completes",
+      "then": "the aggregate report's `verdict` field is `failed`, its `gates[]` entry for `validate` records `outcome: failed`, and the Node entry point's process exit code is non-zero",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-701-ci-pipeline-gate-runner",
+    "TAC-702-ci-pipeline-gate-report"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}