ma-agents 3.8.0 → 3.11.0

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pact-consumer-framework-setup.md

@@ -76,9 +76,9 @@ export default defineConfig({
 
 **Key Points**:
 
-- **`fileParallelism: false` is required** — primary defense against non-deterministic pact generation. Without it, parallel workers race on the shared pact JSON file and corrupt interactions. Symptom: local runs pass, CI randomly fails with `Cannot change pact content for already published pact`. See Example 10 for the determinism gate that enforces byte-stability across re-runs.
+- **`fileParallelism: false` is required** — primary defense against non-deterministic pact generation. Without it, parallel workers race on the shared pact JSON file and corrupt interactions. Symptom: local runs pass, CI randomly fails with `Cannot change pact content for already published pact`. The `publish-pact.sh` `jq` sort (Example 4) provides byte-stability at publish time.
 - **`pool: 'forks'` + `singleFork: true` is required for multi-file consumer suites** — same config the provider side uses (`pactjs-utils-provider-verifier.md` Example 7). Best current understanding: the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; with the default threads pool (Vitest v1) and multiple `.pacttest.ts` files on the same consumer+provider pair, we observed reproducible "request was expected but not received" flakes on Linux CI only. `singleFork: true` serializes every pact file into one forked subprocess and eliminated the flake on two repos (`pactjs-utils`, `seon-mcp-server`). Vitest v2+ defaults to `forks`, but set the pool explicitly so the contract does not drift with Vitest version bumps.
-- **Single-file consumer suites** (one `.pacttest.ts` per consumer+provider pair) have not been observed to flake under default threads pool, because FFI state is not shared across files when there is only one file. Adding `pool: 'forks'` is still recommended — it future-proofs you the moment a second file is added — but a suite passing today with only `fileParallelism: false` is not broken.
+- **One `.pacttest.ts` per consumer+provider pair is the canonical pattern** — not just an observation. Two files for the same pair in one process (which `singleFork: true` guarantees) cause an FFI handle collision: the second file's `new PactV4(...)` call re-enters the FFI handle still holding stale state from the first file → "request was expected but not received" sporadically on Linux CI. The fix is structural — merge the files, not the config. `pool: 'forks'` is still required for pact JSON write safety but does NOT prevent same-pair file splits from colliding. Multiple files for **different** pairs (different consumer or provider name) are correct and safe. See Example 10 for the ✅/❌ pattern.
 - **Interacting settings**: leave `isolate` at its default (`true`). Do NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, or `maxWorkers > 1` in this config — they defeat the serialization this rule relies on. `hookTimeout` may be raised if mock-server startup is slow, but keep `testTimeout` ≥ `hookTimeout`.
 - Do NOT add `setupFiles`, `coverage`, or other settings from the unit test config
 - Keep it minimal — Pact tests run in Node environment with extended timeout
@@ -96,8 +96,7 @@ export default defineConfig({
 ```json
 {
   "scripts": {
-    "test:pact:consumer": "./scripts/check-pact-determinism.sh 'npm run test:pact:consumer:run' 3 ./pacts",
-    "test:pact:consumer:run": "vitest run --config vitest.config.pact.ts",
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
     "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
     "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
     "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
@@ -109,8 +108,6 @@ Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-fronten
 
 **Key Points**:
 
-- **`test:pact:consumer` IS the determinism gate** — it runs the inner command 3× and fails if pact output is not byte-stable. This is the command CI and developers run before pushing. See Example 10 for the `check-pact-determinism.sh` script itself.
-- **`test:pact:consumer:run` is the fast inner command** for TDD loops (a single pass of the suite, no gate). Developers can iterate with this; CI always goes through the outer gated script.
 - Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
 - Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
 - `PACTICIPANT` is set per-script invocation, not globally
@@ -139,7 +136,7 @@ export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
 export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
 ```
 
-#### `scripts/publish-pact.sh` — Publish Pacts to Broker (with defense-in-depth normalization)
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
 
 ```bash
 #!/bin/bash
@@ -147,9 +144,8 @@ export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
 #
 # Before publish, normalize each pact JSON: sort interactions by (description, provider state name,
 # method, path) and sort object keys via `jq -S`. This gives byte-stable output to the broker even
-# if the PactV4 generator produces ordering drift between runs. Paired with scripts/check-pact-determinism.sh
-# as defense-in-depth — the gate catches drift pre-publish; normalization ensures "Cannot change pact
-# content" from PactFlow never fires on ordering-only changes that slip past the gate.
+# if the PactV4 generator produces ordering drift between runs. Ensures "Cannot change pact content"
+# from PactFlow never fires on ordering-only changes.
 #
 # Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH, jq
 # -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
@@ -229,7 +225,7 @@ fi
 - Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
 - `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
 - `record-deployment` has branch guard (only records on main/master)
-- **`publish-pact.sh` normalizes interactions with `jq -S` + `sort_by(...)` before publishing** — defense-in-depth alongside the determinism gate (Example 10). The gate catches drift; normalization ensures byte-stable payload to the broker regardless of generator quirks. Keep both; they protect against different failure modes.
+- **`publish-pact.sh` normalizes interactions with `jq -S` + `sort_by(...)` before publishing** — ensures byte-stable payload to the broker regardless of generator ordering quirks.
 - Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
 
 ---
@@ -276,8 +272,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      # (1) Generate pact files — runs the determinism gate (3 runs + byte-stable check via jq)
-      - name: Consumer pact tests (determinism gate)
+      # (1) Generate pact files
+      - name: Run consumer contract tests
         run: npm run test:pact:consumer
 
       # (2) Publish pacts to broker (publish-pact.sh also normalizes interaction order as defense-in-depth)
@@ -301,8 +297,7 @@ jobs:
 
 **Key Points**:
 
-- **1:1 local/CI parity is a hard rule**: every CI step is `npm run <same-name-a-dev-uses>`. Never let CI invoke `vitest` or `pact-broker` directly — that divergence is how "works on my machine" slips in. The determinism gate, publish, can-i-deploy, and record-deployment are all the same commands a developer runs locally.
-- **The determinism gate is its own visible step, not a side-effect of publish.** A failing gate must be debuggable from the CI log without re-running. Do not fold it into a `prepublish:pact` hook — folding hides the failure inside a publish log and makes attribution harder.
+- **1:1 local/CI parity is a hard rule**: every CI step is `npm run <same-name-a-dev-uses>`. Never let CI invoke `vitest` or `pact-broker` directly — that divergence is how "works on my machine" slips in. Consumer tests, publish, can-i-deploy, and record-deployment are all the same commands a developer runs locally.
 - **Workflow-level `env` block** for broker secrets and git vars — not per-step
 - **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
 - **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
@@ -625,89 +620,42 @@ pact-logs/
 
 ---
 
-### Example 10: Determinism Gate Script (Primary Defense)
+### Example 10: Test File Organization — One File Per Consumer+Provider Pair
 
-**Context**: Even with `fileParallelism: false` (Example 2) and one-interaction-per-`it()` (see `pactjs-utils-consumer-helpers.md`), the PactV4 Rust FFI layer can occasionally produce byte-different pact JSON between runs — interaction ordering drift, nested matcher serialization quirks, or `Date` / random-value matchers that weren't locked down. This causes PactFlow to reject re-publishes of the same consumer SHA with `Cannot change pact content for already published pact`. The determinism gate runs the consumer suite N times locally and in CI, hashes the normalized pact files, and fails fast if drift is detected — before any publish is attempted.
+**Context**: Avoiding Pact Rust FFI handle collisions when structuring consumer test files.
 
-**Implementation**:
-
-#### `scripts/check-pact-determinism.sh`
-
-```bash
-#!/bin/bash
-# Run a pact consumer command N times and fail if the generated pact files are not byte-stable.
-# Primary defense against PactV4 non-deterministic output.
-#
-# Usage:  ./scripts/check-pact-determinism.sh "<cmd>" [runs] [pact-dir]
-# Example: ./scripts/check-pact-determinism.sh 'npm run test:pact:consumer:run' 3 ./pacts
-#
-# Requires: jq installed on the runner (ubuntu-latest has it; macOS users need `brew install jq`).
-set -euo pipefail
-
-CMD="${1:?usage: ./scripts/check-pact-determinism.sh \"<cmd>\" [runs] [pact-dir]}"
-RUNS="${PACT_DETERMINISM_RUNS:-${2:-3}}"
-PACT_DIR="${3:-./pacts}"
+**Rule**: Every consumer+provider pair maps to exactly one `.pacttest.ts` file. Never split interactions for the same pair across multiple files.
 
-TMP_DIR="$(mktemp -d)"
-trap 'rm -rf "$TMP_DIR"' EXIT
+**Root cause**: The Pact Rust FFI maintains one handle per consumer+provider pair per process. With `singleFork: true` (all files run sequentially in one forked process), two files for the same pair access the same FFI handle back-to-back. The second file's `new PactV4({ consumer, provider })` call re-enters the handle still holding stale interaction state from the first file. The first test in the second file starts the mock server in this corrupted state — "request was expected but not received" results, sporadic and Linux-CI-only (execution order differs between environments).
 
-hash_pact_file() {
-  # Sort interactions by (description, first provider state name, method, path), sort keys with -S.
-  # The sorted output is what we hash — so ordering-only drift does NOT count as non-determinism here.
-  # (The gate catches deeper drift; ordering drift is handled by publish-pact.sh normalization.)
-  jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)' "$1" \
-    | shasum -a 256 | awk '{print $1}'
-}
+**Evidence**: In `pactjs-utils`, `movies-read.pacttest.ts` and `movies-write.pacttest.ts` both used `consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI'`. The vitest config and CI workflow were correct throughout. The fix was merging the two files into `movies.pacttest.ts`. The config was not changed.
 
-for run in $(seq 1 "$RUNS"); do
-  echo "→ determinism run $run/$RUNS"
-  rm -f "$PACT_DIR"/*.json 2>/dev/null || true
-  eval "$CMD" >"$TMP_DIR/run-$run.log" 2>&1 || {
-    echo "❌ run $run failed — dumping log:"
-    cat "$TMP_DIR/run-$run.log"
-    exit 1
-  }
-  : > "$TMP_DIR/run-$run.hashes"
-  for f in "$PACT_DIR"/*.json; do
-    [ -f "$f" ] || continue
-    printf '%s  %s\n' "$(hash_pact_file "$f")" "$(basename "$f")" >> "$TMP_DIR/run-$run.hashes"
-  done
-  sort -o "$TMP_DIR/run-$run.hashes" "$TMP_DIR/run-$run.hashes"
-done
-
-# Compare every subsequent run against run 1.
-FAIL=0
-for run in $(seq 2 "$RUNS"); do
-  if ! diff -q "$TMP_DIR/run-1.hashes" "$TMP_DIR/run-$run.hashes" >/dev/null; then
-    FAIL=1
-    echo ""
-    echo "❌ Pact output differs between run 1 and run $run:"
-    diff "$TMP_DIR/run-1.hashes" "$TMP_DIR/run-$run.hashes" || true
-  fi
-done
-
-if [ "$FAIL" -ne 0 ]; then
-  echo ""
-  echo "Pact output is non-deterministic across $RUNS runs. Likely causes:"
-  echo "  • multiple .addInteraction() chained in a single it() block (PactV4 FFI drops one non-deterministically)"
-  echo "  • fileParallelism: true in vitest.config.pact.ts (workers race on shared pact JSON)"
-  echo "  • missing pool: 'forks' + singleFork: true (threads pool shares FFI state across files on Linux CI)"
-  echo "  • Date / random matchers that don't lock a stable example value"
-  echo "  • provider state params mutating between runs (e.g. Date.now())"
-  exit 1
-fi
-
-echo "✅ Pact output is byte-stable across $RUNS runs."
+```typescript
+// ❌ WRONG — same consumer+provider pair split across two files
+// movies-read.pacttest.ts
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Read Operations', () => { /* 4 tests: GET /movies, GET /movies/:id */ })
+
+// movies-write.pacttest.ts  ← second PactV4 for the SAME pair = FFI handle collision
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Write Operations', () => { /* 5 tests: POST, PUT, DELETE */ })
+
+// ✅ RIGHT — one file per consumer+provider pair, describe blocks for organization
+// movies.pacttest.ts
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Movies API', () => {
+  describe('Read Operations', () => { /* 4 tests */ })
+  describe('Write Operations', () => { /* 5 tests */ })
+})
 ```
 
 **Key Points**:
 
-- **Wire this script into `test:pact:consumer`** (see Example 3). The outer script IS the gate; the inner `test:pact:consumer:run` is the single-pass command for TDD loops.
-- **Default 3 runs** is the sweet spot — 2 runs miss intermittent drops, >3 slows CI without catching more. Override with an env var or the positional arg if you're actively debugging a flake.
-- **Treat gate failures as a P0 bug, not a "retry until green" condition.** Find the source of non-determinism (chained `addInteraction`, unsorted interactions, Date-dependent matchers). Do not raise `RUNS` to 10 to mask the symptom.
-- **Requires `jq`** — installed by default on `ubuntu-latest`. For macOS local dev, document `brew install jq` in the project README.
-- **In CI, make this its own visible step** (see Example 5 step (1) naming). Do not fold into a `prepublish:pact` hook — that hides the failure inside a publish log.
-- **Defense-in-depth with `publish-pact.sh` normalization** (Example 4): the gate catches pre-publish drift; the publish-time `jq` sort ensures any ordering-only drift that slipped past the gate still produces a byte-stable payload to PactFlow.
+- **File = contract**: A `.pacttest.ts` file represents one consumer+provider contract. One contract = one file.
+- **Describe blocks, not files**: Organize by operation type (`Read Operations`, `Write Operations`), resource, or feature — always within one file per pair.
+- **Different pairs = different files**: `ServiceA / BackendAPI` and `ServiceA / AuthAPI` are two contracts and correctly use two separate files. This rule only forbids splitting ONE pair.
+- **`singleFork: true` is not a fix for this**: It ensures correct pact JSON write semantics across files, but when two files share a pair it actually guarantees the FFI collision (both land in the same process). Without it you'd get file-write races instead. Neither is safe. The fix is one file per pair.
+- **Naming convention**: `{domain}.pacttest.ts` when one domain maps to one pair. `{consumer-kebab}-{provider-kebab}.pacttest.ts` when the filename must be self-describing about which pair it covers.
 
 ---
 
@@ -715,12 +663,11 @@ echo "✅ Pact output is byte-stable across $RUNS runs."
 
 Before presenting the consumer CDC framework to the user, verify:
 
-- [ ] `vitest.config.pact.ts` is minimal **and sets `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`** (`fileParallelism: false` prevents shared pact JSON corruption from parallel workers; forks + `singleFork: true` eliminates the Linux-CI "request was expected but not received" flake observed once a second `.pacttest.ts` is added — see Example 2 Key Points for evidence, mechanism qualifier, and single-file exception)
+- [ ] `vitest.config.pact.ts` is minimal **and sets `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`** (`fileParallelism: false` prevents shared pact JSON corruption from parallel workers; forks + `singleFork: true` is required for pact JSON write safety across files — see Example 2 Key Points for mechanism and evidence)
+- [ ] Each consumer+provider pair is covered by exactly ONE `.pacttest.ts` file — never split interactions for the same pair across multiple files (two `PactV4` instances for the same pair in one process cause FFI handle collision → "request was expected but not received" on Linux CI; `singleFork: true` does NOT prevent this — it ensures both files share one process, which guarantees the collision; see Example 10)
 - [ ] `vitest.config.pact.ts` does NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, `maxWorkers > 1`, or `isolate: false` — all four defeat the serialization the rule relies on
-- [ ] `package.json` splits `test:pact:consumer` (gated determinism runner) and `test:pact:consumer:run` (inner single-pass command)
-- [ ] `scripts/check-pact-determinism.sh` is present, hashes via `jq -S` + `sort_by`, defaults to 3 runs, and is the body of the `test:pact:consumer` script
-- [ ] `scripts/publish-pact.sh` normalizes interactions with `jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)'` before the `pact-broker publish` call (defense-in-depth alongside the gate)
-- [ ] Script names match pactjs-utils (`test:pact:consumer`, `test:pact:consumer:run`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] `scripts/publish-pact.sh` normalizes interactions with `jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)'` before the `pact-broker publish` call (ensures byte-stable payload to PactFlow regardless of generator ordering)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
 - [ ] Scripts source `env-setup.sh` inline in package.json
 - [ ] Shell scripts use `pact-broker` not `npx pact-broker`
 - [ ] Shell scripts use `PACTICIPANT` env var pattern
@@ -730,7 +677,7 @@ Before presenting the consumer CDC framework to the user, verify:
 - [ ] CI workflow named `contract-test-consumer.yml`
 - [ ] CI has workflow-level env block (not per-step)
 - [ ] CI has `detect-breaking-change` step before install
-- [ ] CI step (1) is the determinism gate (calls `npm run test:pact:consumer`) — its own visible step, not folded into publish
+- [ ] CI step (1) generates pact files (calls `npm run test:pact:consumer`) — its own visible step, not folded into publish
 - [ ] CI steps are 1:1 with developer commands — every CI step calls `npm run <same-name>` a dev would run locally (no direct `vitest` or `pact-broker` invocation)
 - [ ] CI step numbering skips (3) — webhook-triggered provider verification
 - [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pactjs-utils-consumer-helpers.md

@@ -260,10 +260,9 @@ it.each([
 
 **Key Points**:
 
-- **This rule stacks with two other MANDATORY vitest settings**: `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`. All three are required and address different failure modes — `fileParallelism: false` prevents parallel workers from racing on the shared pact JSON; `pool: 'forks'` + `singleFork: true` prevents the Pact Rust FFI from leaking state across files (manifests as "request was expected but not received" flakes on Linux CI only); one-interaction-per-`it()` prevents the FFI from dropping interactions within a single test body.
-- Symptom of violating this rule: the pact file is byte-different between otherwise-identical runs; `scripts/check-pact-determinism.sh` flags drift; PactFlow rejects a republish with `Cannot change pact content`.
+- **This rule stacks with two MANDATORY vitest settings and one file-organization rule. All four address different failure modes; none substitutes for the others**: (1) `fileParallelism: false` — prevents parallel workers racing on the shared pact JSON file; (2) `pool: 'forks'` with `singleFork: true` — required for pact JSON write safety across multiple files; (3) **one `.pacttest.ts` per consumer+provider pair** — `singleFork: true` keeps all files in one process, so two files for the same pair produce an FFI handle collision ("request was expected but not received" on Linux CI, sporadic); (4) one-interaction-per-`it()` (this rule) — prevents the FFI from dropping interactions within a single test body. See `pact-consumer-framework-setup.md` Example 10 for the file-organization ✅/❌ pattern.
+- Symptom of violating this rule: the pact file is byte-different between otherwise-identical runs; PactFlow rejects a republish with `Cannot change pact content`.
 - The rule applies to both HTTP consumer pacts (`PactV4`) and message consumer pacts (`MessageConsumerPact`).
-- See `pact-consumer-framework-setup.md` Example 10 for the determinism gate that automatically catches violations of this rule.
 
 ## Key Points
 
@@ -278,13 +277,13 @@ it.each([
 - **Body shorthand**: `setJsonBody` keeps body-only responses concise and readable
 - **Matchers check type, not value**: `string('My movie')` means "any string", `integer(1)` means "any integer". The example values are arbitrary — the provider can return different values and verification still passes as long as the type matches. Use matchers only in `.willRespondWith()` (responses), never in `.withRequest()` (requests) — Postel's Law applies.
 - **Reuse test values across files**: Interactions are uniquely identified by `uponReceiving` + `.given()`, not by placeholder values. Two test files can both use `testId: 100` without conflicting. On the provider side, shared values simplify state handlers — idempotent handlers (check if exists, create if not) only need to ensure one record exists. Use different values only when testing different states of the same entity type (e.g., `movieExists(100)` for happy paths vs. `movieNotFound(999)` for error paths).
-- **One `addInteraction()` per `it()` block (MANDATORY for PactV4)**: Multiple interactions inside one `it()` cause the Rust FFI to non-deterministically drop interactions. Use one `it()` per interaction or `it.each(...)` for parameterized cases. See Example 6 and the determinism gate in `pact-consumer-framework-setup.md` Example 10.
+- **One `addInteraction()` per `it()` block (MANDATORY for PactV4)**: Multiple interactions inside one `it()` cause the Rust FFI to non-deterministically drop interactions. Use one `it()` per interaction or `it.each(...)` for parameterized cases. See Example 6.
 
 ## Related Fragments
 
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
 - `pactjs-utils-provider-verifier.md` — provider-side state handler implementation; same `pool: 'forks'` + `singleFork: true` rule as consumer
-- `pact-consumer-framework-setup.md` — Vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true` config, determinism gate (Example 10), and CI wiring
+- `pact-consumer-framework-setup.md` — Vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true` config and CI wiring
 - `contract-testing.md` — foundational patterns with raw Pact.js
 
 ## Anti-Patterns
@@ -375,6 +374,6 @@ it('returns empty list', async () => {
 });
 ```
 
-See Example 6 above for the full rationale and the determinism gate that enforces this rule.
+See Example 6 above for the full rationale.
 
 _Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pactjs-utils-provider-verifier.md

@@ -296,7 +296,7 @@ export default defineConfig({
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
 - `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation, **one-interaction-per-`it()` rule**
 - `pactjs-utils-request-filter.md` — auth injection for provider verification
-- `pact-consumer-framework-setup.md` — consumer-side framework setup, Vitest `fileParallelism: false`, determinism gate
+- `pact-consumer-framework-setup.md` — consumer-side framework setup, Vitest `fileParallelism: false`, CI wiring
 - `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth/staleness for webhook-triggered provider verification (`contract_requiring_verification_published`)
 - `contract-testing.md` — foundational patterns with raw Pact.js
 

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/tea-index.csv

@@ -38,7 +38,7 @@ pactjs-utils-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderStat
 pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions; vitest pool:forks + singleFork for FFI safety (same rule applies to consumer and provider)","pactjs-utils,provider,consumer,contract-testing,pact,api,backend,ci,vitest,ffi",specialized,knowledge/pactjs-utils-provider-verifier.md
 pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
 pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
-pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config with fileParallelism:false + pool:forks + singleFork:true (FFI safety), determinism gate (check-pact-determinism.sh), jq-normalized publishing, 1:1 local/CI parity, PactV4 patterns","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts,determinism,jq,pactv4,ffi",specialized,knowledge/pact-consumer-framework-setup.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config with fileParallelism:false + pool:forks + singleFork:true (FFI safety), one-file-per-consumer+provider-pair rule (FFI handle collision prevention), jq-normalized publishing, 1:1 local/CI parity, PactV4 patterns","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts,jq,pactv4,ffi,file-organization,one-file-per-pair",specialized,knowledge/pact-consumer-framework-setup.md
 pact-broker-webhooks,Pact Broker Webhooks,"PactFlow → GitHub repository_dispatch auth via dedicated machine user + classic PAT (repo scope, no expiration) + PactFlow secret; staleness monitoring and PAT rotation runbook","pact,pactflow,broker,webhooks,github,auth,pat,ci,operations,security",specialized,knowledge/pact-broker-webhooks.md
 adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
 playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md

package/lib/bmad-cache/tea/src/module-help.csv

@@ -1,11 +1,11 @@
 module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
 Test Architecture Enterprise,_meta,,,,,,,,,false,https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/llms.txt,
-Test Architecture Enterprise,bmad-teach-me-testing,Teach Me Testing,TMT,Teach testing fundamentals through 7 sessions (TEA Academy).,,0-learning,,,false,test_artifacts,"progress file|session notes|certificate"
-Test Architecture Enterprise,bmad-testarch-test-design,Test Design,TD,Risk-based test planning.,,3-solutioning,,bmad-testarch-framework,false,test_artifacts,test design document
-Test Architecture Enterprise,bmad-testarch-framework,Test Framework,TF,Initialize production-ready test framework.,,3-solutioning,bmad-testarch-test-design,bmad-testarch-ci,false,test_artifacts,framework scaffold
-Test Architecture Enterprise,bmad-testarch-ci,CI Setup,CI,Configure CI/CD quality pipeline.,,3-solutioning,bmad-testarch-framework,,false,test_artifacts,ci config
-Test Architecture Enterprise,bmad-testarch-atdd,ATDD,AT,Generate red-phase acceptance test scaffolds before implementation.,,4-implementation,bmad-create-story:create,bmad-dev-story,false,test_artifacts,"atdd-checklist|red-phase acceptance tests"
-Test Architecture Enterprise,bmad-testarch-automate,Test Automation,TA,Expand test coverage.,,4-implementation,bmad-testarch-atdd,,false,test_artifacts,test suite
-Test Architecture Enterprise,bmad-testarch-test-review,Test Review,RV,Quality audit (0-100 scoring).,,4-implementation,bmad-testarch-automate,,false,test_artifacts,review report
-Test Architecture Enterprise,bmad-testarch-nfr,NFR Assessment,NR,Non-functional requirements assessment.,,4-implementation,bmad-testarch-automate,,false,test_artifacts,nfr report
-Test Architecture Enterprise,bmad-testarch-trace,Traceability,TR,Coverage traceability and gate.,,4-implementation,bmad-testarch-test-review,,false,test_artifacts,"traceability matrix|gate decision"
+Test Architecture Enterprise,bmad-teach-me-testing,Teach Me Testing,TMT,Teach testing fundamentals through 7 sessions (TEA Academy).,,,0-learning,,,false,test_artifacts,progress file|session notes|certificate
+Test Architecture Enterprise,bmad-testarch-test-design,Test Design,TD,Risk-based test planning.,,,3-solutioning,,bmad-testarch-framework,false,test_artifacts,test design document
+Test Architecture Enterprise,bmad-testarch-framework,Test Framework,TF,Initialize production-ready test framework.,,,3-solutioning,bmad-testarch-test-design,bmad-testarch-ci,false,test_artifacts,framework scaffold
+Test Architecture Enterprise,bmad-testarch-ci,CI Setup,CI,Configure CI/CD quality pipeline.,,,3-solutioning,bmad-testarch-framework,,false,test_artifacts,ci config
+Test Architecture Enterprise,bmad-testarch-atdd,ATDD,AT,Generate red-phase acceptance test scaffolds before implementation.,,,4-implementation,bmad-create-story:create,bmad-dev-story,false,test_artifacts,atdd-checklist|red-phase acceptance tests
+Test Architecture Enterprise,bmad-testarch-automate,Test Automation,TA,Expand test coverage.,,,4-implementation,bmad-testarch-atdd,,false,test_artifacts,test suite
+Test Architecture Enterprise,bmad-testarch-test-review,Test Review,RV,Quality audit (0-100 scoring).,,,4-implementation,bmad-testarch-automate,,false,test_artifacts,review report
+Test Architecture Enterprise,bmad-testarch-nfr,NFR Assessment,NR,Non-functional requirements assessment.,,,4-implementation,bmad-testarch-automate,,false,test_artifacts,nfr report
+Test Architecture Enterprise,bmad-testarch-trace,Traceability,TR,Coverage traceability and gate.,,,4-implementation,bmad-testarch-test-review,,false,test_artifacts,traceability matrix|gate decision

package/lib/bmad-extension/.claude-plugin/marketplace.json.template

@@ -2,7 +2,7 @@
   "_comment": [
     "BMAD Builder convention: the wrapper directory '.claude-plugin/' is a SHARED convention used by skills-capable platforms — it is NOT a Claude-only binding. BMAD adopted Anthropic's published plugin layout because it was the closest thing to an open standard at the time; multi-tool routing (claude-code, copilot, cline, roo-code, kilocode, cursor) is handled by BMAD's own installer based on the --tools flag. See https://bmad-builder-docs.bmad-method.org/how-to/distribute-your-module/ and https://bmad-builder-docs.bmad-method.org/explanation/.",
     "This is a TEMPLATE file consumed by scripts/build-plugin.js (Story 22.4). Tokens of the form ${var} are replaced at build time; the resolved manifest lands at lib/bmad-extension-plugin/.claude-plugin/marketplace.json. Do NOT hand-edit the generated file.",
-    "Fields follow the v6.5.0 schema read by tools/installer/modules/custom-module-manager.js (top-level: name, owner, description, license, homepage, repository, keywords; per-plugin: name, source, description, version, author, skills[]).",
+    "Fields follow the v6.6.0 schema read by tools/installer/modules/custom-module-manager.js (top-level: name, owner, description, license, homepage, repository, keywords; per-plugin: name, source, description, version, author, skills[]).",
     "plugins[].source interpretation: a value of \"./\" means 'the directory containing .claude-plugin/' — i.e. the plugin output root (lib/bmad-extension-plugin/). Skill paths (\"./skills/<name>\") are resolved relative to that same root. Story 22.4's build script MUST honor this convention.",
     "compatible_tools is an informational, BMAD-wide convention (not read by the installer) used to signal multi-tool parity with downstream consumers. The authoritative list of supported tools is the --tools flag accepted by the BMAD installer.",
     "bmad_min_version forward-compat policy: this floor assumes upstream bmad-method changes remain additive (new fields / new optional schema). Any breaking upstream change requires bumping bmad_min_version in lockstep with the pinned bmad-method dependency in package.json."
@@ -39,7 +39,7 @@
     "roo-code",
     "kilocode"
   ],
-  "bmad_min_version": "6.5.0",
+  "bmad_min_version": "6.6.0",
   "plugins": [
     {
       "name": "ma-skills",

package/lib/bmad-extension/skills/add-sprint/SKILL.md

@@ -11,6 +11,45 @@ triggers:
 
 Guided workflow to create a new sprint entry in the `sprints` section of `sprint-status.yaml` with capacity limits, optional ISO dates, and auto-incremented sprint ID.
 
+## Backend Routing
+
+Before executing any file-system operations, determine and route to the correct backend:
+
+1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and extract the `tracking_system` field.
+   If the field is absent or the file does not exist, read `sprint_backend` from `_bmad/bmm/config.yaml`. Use that value if present, otherwise default to `file-system`.
+
+2. If `tracking_system` is `file-system`:
+   Proceed with the **File-System Backend** instructions below.
+
+3. If `tracking_system` is `jira`:
+   a. Perform the Jira operation: Create a new sprint in the board for project `{jira_project_key}` at `{jira_url}` using the sprint create API. Set the sprint name, goal (if provided), start date, and end date from the provided sprint data. The new sprint starts in "future/planning" state.
+      Use whatever Jira-capable tool is available in your current tool context.
+      Map Jira entities to the canonical schema (Sprint → sprints[], Backlog → backlog[],
+      Epic → epics[], Jira status → canonical vocabulary per Section 6.3 of the routing spec).
+   b. If the Jira operation SUCCEEDS: continue with the Jira data returned. Jira is the source of truth.
+   c. If the Jira operation FAILS for any reason:
+      - If no Jira-capable tool is available in your current context:
+        Pause and present the user with:
+        > "No Jira-capable tool is available. To use Jira tracking, configure a Jira integration
+        > in your agent (an MCP server, plugin, or native integration connected to the Jira
+        > instance at `{jira_url}`). How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again once a Jira tool is configured
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      - If a Jira tool attempted the operation but returned an error:
+        Pause and present the user with:
+        > "The Jira operation failed: {actual Jira error details}. How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      If user chooses (b) in either case: write `tracking_system: file-system` to `sprint-status.yaml`,
+      update `sprint_backend: file-system` in `_bmad/bmm/config.yaml`,
+      then proceed with **File-System Backend** instructions below.
+
+4. **File-System Backend** — execute the workflow steps below.
+
+---
+
 <workflow>
 
 <step n="0" goal="Load configuration and validate file existence">

package/lib/bmad-extension/skills/add-to-sprint/SKILL.md

@@ -13,6 +13,45 @@ Guided workflow to move backlog items to a sprint in the unified `sprint-status.
 
 **Movement semantics:** Each item exists in exactly one location — either the `backlog` array OR a sprint's `items` array, never both. This skill atomically removes items from `backlog` and appends them to the target sprint's `items` array in a single file write.
 
+## Backend Routing
+
+Before executing any file-system operations, determine and route to the correct backend:
+
+1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and extract the `tracking_system` field.
+   If the field is absent or the file does not exist, read `sprint_backend` from `_bmad/bmm/config.yaml`. Use that value if present, otherwise default to `file-system`.
+
+2. If `tracking_system` is `file-system`:
+   Proceed with the **File-System Backend** instructions below.
+
+3. If `tracking_system` is `jira`:
+   a. Perform the Jira operation: Find the Jira issue matching the item ID in project `{jira_project_key}` at `{jira_url}` (search by issue key or summary). Find the active sprint on the board for project `{jira_project_key}`. Move the issue to the active sprint using the "add issue to sprint" operation.
+      Use whatever Jira-capable tool is available in your current tool context.
+      Map Jira entities to the canonical schema (Sprint → sprints[], Backlog → backlog[],
+      Epic → epics[], Jira status → canonical vocabulary per Section 6.3 of the routing spec).
+   b. If the Jira operation SUCCEEDS: continue with the Jira data returned. Jira is the source of truth.
+   c. If the Jira operation FAILS for any reason:
+      - If no Jira-capable tool is available in your current context:
+        Pause and present the user with:
+        > "No Jira-capable tool is available. To use Jira tracking, configure a Jira integration
+        > in your agent (an MCP server, plugin, or native integration connected to the Jira
+        > instance at `{jira_url}`). How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again once a Jira tool is configured
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      - If a Jira tool attempted the operation but returned an error:
+        Pause and present the user with:
+        > "The Jira operation failed: {actual Jira error details}. How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      If user chooses (b) in either case: write `tracking_system: file-system` to `sprint-status.yaml`,
+      update `sprint_backend: file-system` in `_bmad/bmm/config.yaml`,
+      then proceed with **File-System Backend** instructions below.
+
+4. **File-System Backend** — execute the workflow steps below.
+
+---
+
 <workflow>
 
 <step n="0" goal="Load configuration and validate file existence">

package/lib/bmad-extension/skills/bmad-dev-story/workflow.md

@@ -36,6 +36,45 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ---
 
+## Backend Routing
+
+Before executing any status-update operations, determine and route to the correct backend:
+
+1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and extract the `tracking_system` field.
+   If the field is absent or the file does not exist, read `sprint_backend` from `_bmad/bmm/config.yaml`. Use that value if present, otherwise default to `file-system`.
+
+2. If `tracking_system` is `file-system`:
+   Proceed with the **File-System Backend** instructions below.
+
+3. If `tracking_system` is `jira`:
+   a. Perform the Jira operation: Find the Jira issue matching the item ID in project `{jira_project_key}` at `{jira_url}` (search by issue key or summary). Transition the issue to the new status using the Jira issue transition API. Map canonical status to Jira workflow status: backlog → Backlog/Open, ready-for-dev → To Do/Selected for Development, in-progress → In Progress, review → In Review/Code Review, done → Done/Resolved, on-hold → On Hold/Blocked, cancelled → Won't Do/Cancelled.
+      Use whatever Jira-capable tool is available in your current tool context.
+      Map Jira entities to the canonical schema (Sprint → sprints[], Backlog → backlog[],
+      Epic → epics[], Jira status → canonical vocabulary per Section 6.3 of the routing spec).
+   b. If the Jira operation SUCCEEDS: continue with the Jira data returned. Jira is the source of truth.
+   c. If the Jira operation FAILS for any reason:
+      - If no Jira-capable tool is available in your current context:
+        Pause and present the user with:
+        > "No Jira-capable tool is available. To use Jira tracking, configure a Jira integration
+        > in your agent (an MCP server, plugin, or native integration connected to the Jira
+        > instance at `{jira_url}`). How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again once a Jira tool is configured
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      - If a Jira tool attempted the operation but returned an error:
+        Pause and present the user with:
+        > "The Jira operation failed: {actual Jira error details}. How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      If user chooses (b) in either case: write `tracking_system: file-system` to `sprint-status.yaml`,
+      update `sprint_backend: file-system` in `_bmad/bmm/config.yaml`,
+      then proceed with **File-System Backend** instructions below.
+
+4. **File-System Backend** — execute the workflow steps below.
+
+---
+
 ## EXECUTION
 
 <workflow>

package/lib/bmad-extension/skills/bmad-sprint-planning/workflow.md

@@ -42,6 +42,47 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ---
 
+## Backend Routing
+
+Before executing any file-system operations, determine and route to the correct backend:
+
+1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and extract the `tracking_system` field.
+   If the field is absent or the file does not exist, read `sprint_backend` from `_bmad/bmm/config.yaml`. Use that value if present, otherwise default to `file-system`.
+
+2. If `tracking_system` is `file-system`:
+   Proceed with the **File-System Backend** instructions below.
+
+3. If `tracking_system` is `jira`:
+   > "This operation will create/update Jira sprints and items in bulk. If it fails mid-way, Jira may be in partial state. The Jira server URL is `{jira_url}` and project key is `{jira_project_key}` (from `_bmad/bmm/config.yaml`). Proceed?"
+
+   a. Perform the Jira operation: Query all epics, backlog issues, sprint definitions, and sprint items for project `{jira_project_key}` at `{jira_url}` (multiple sequential read calls). For the write phase: create new Jira sprints for each sprint definition not already in Jira (one API call per sprint). Create or update Jira issues for each item in the plan (one API call per item). Map item fields as follows: title → issue summary, type → issue type (story → Story, bug → Bug), status → Jira workflow status (see status mapping below), priority → issue priority/rank. Map sprint fields: name → sprint name, start_date → sprint start date, end_date → sprint end date. Status mapping: backlog → Backlog/Open, ready-for-dev → To Do/Selected for Development, in-progress → In Progress, review → In Review/Code Review, done → Done/Resolved, on-hold → On Hold/Blocked, cancelled → Won't Do/Cancelled.
+      Use whatever Jira-capable tool is available in your current tool context.
+      Map Jira entities to the canonical schema (Sprint → sprints[], Backlog → backlog[],
+      Epic → epics[], Jira status → canonical vocabulary per Section 6.3 of the routing spec).
+   b. If the Jira operation SUCCEEDS: continue with the Jira data returned. Jira is the source of truth.
+   c. If the Jira operation FAILS for any reason:
+      - If no Jira-capable tool is available in your current context:
+        Pause and present the user with:
+        > "No Jira-capable tool is available. To use Jira tracking, configure a Jira integration
+        > in your agent (an MCP server, plugin, or native integration connected to the Jira
+        > instance at `{jira_url}`). How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again once a Jira tool is configured
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      - If a Jira tool attempted the operation but returned an error:
+        Pause and present the user with:
+        > "The Jira operation failed: {actual Jira error details}. How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      If user chooses (b) in either case: write `tracking_system: file-system` to `sprint-status.yaml`,
+      update `sprint_backend: file-system` in `_bmad/bmm/config.yaml`,
+      then proceed with **File-System Backend** instructions below.
+
+4. **File-System Backend** — execute the workflow steps below.
+
+---
+
 ## EXECUTION
 
 <workflow>

package/lib/bmad-extension/skills/bmad-sprint-status/workflow.md

@@ -37,6 +37,45 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 
 ---
 
+## Backend Routing
+
+Before executing any file-system operations, determine and route to the correct backend:
+
+1. Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and extract the `tracking_system` field.
+   If the field is absent or the file does not exist, read `sprint_backend` from `_bmad/bmm/config.yaml`. Use that value if present, otherwise default to `file-system`.
+
+2. If `tracking_system` is `file-system`:
+   Proceed with the **File-System Backend** instructions below.
+
+3. If `tracking_system` is `jira`:
+   a. Perform the Jira operation: Query the active sprint for project `{jira_project_key}` at `{jira_url}` and retrieve all sprint issues with their statuses. Query backlog issue count. Query epic progress (completed stories per epic). Map Jira sprint states and issue statuses to canonical vocabulary per the status mapping below. Use this data for health analysis — no writes. Status mapping: Backlog/Open → backlog, To Do/Selected for Development → ready-for-dev, In Progress → in-progress, In Review/Code Review → review, Done/Resolved → done, On Hold/Blocked → on-hold, Won't Do/Cancelled → cancelled.
+      Use whatever Jira-capable tool is available in your current tool context.
+      Map Jira entities to the canonical schema (Sprint → sprints[], Backlog → backlog[],
+      Epic → epics[], Jira status → canonical vocabulary per Section 6.3 of the routing spec).
+   b. If the Jira operation SUCCEEDS: continue with the Jira data returned. Jira is the source of truth.
+   c. If the Jira operation FAILS for any reason:
+      - If no Jira-capable tool is available in your current context:
+        Pause and present the user with:
+        > "No Jira-capable tool is available. To use Jira tracking, configure a Jira integration
+        > in your agent (an MCP server, plugin, or native integration connected to the Jira
+        > instance at `{jira_url}`). How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again once a Jira tool is configured
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      - If a Jira tool attempted the operation but returned an error:
+        Pause and present the user with:
+        > "The Jira operation failed: {actual Jira error details}. How would you like to proceed?
+        > (a) Retry — attempt the Jira operation again
+        > (b) Switch to file management — update sprint-status.yaml and config to use
+        >     file-system backend, then complete this operation locally. This change is permanent."
+      If user chooses (b) in either case: write `tracking_system: file-system` to `sprint-status.yaml`,
+      update `sprint_backend: file-system` in `_bmad/bmm/config.yaml`,
+      then proceed with **File-System Backend** instructions below.
+
+4. **File-System Backend** — execute the steps below.
+
+---
+
 ## EXECUTION
 
 <workflow>