@pareto4/pp-core 1.11.1 → 1.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pareto4/pp-core",
-  "version": "1.11.1",
+  "version": "1.12.1",
   "description": "Pareto pp-core — The Pareto Project's AI-assisted engineering framework: meta-prompting, context engineering, and spec-driven development for AI coding agents.",
   "bin": {
     "pp-core": "bin/install.js",
@@ -65,13 +65,22 @@
     "eslint-plugin-no-only-tests": "^3.4.0",
     "fast-check": "^4.8.0",
     "globals": "^16.5.0",
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.2",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0"
   },
   "overrides": {
-    "qs": ">=6.15.2",
-    "@hono/node-server": ">=2.0.5"
+    "qs": ">=6.16.0",
+    "@hono/node-server": ">=2.0.5",
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "fast-uri": "^3.1.8",
+    "hono": "^4.13.7",
+    "ip-address": "^10.7.1",
+    "proxy-addr": "^2.0.8",
+    "brace-expansion@^1.1.0": "^1.1.21",
+    "brace-expansion@^5.0.0": "^5.0.12",
+    "browserslist": "^4.28.7",
+    "baseline-browser-mapping": "^2.11.0"
   },
   "optionalDependencies": {
     "fallow": "^2.70.0"
@@ -79,6 +88,10 @@
   "scripts": {
     "sync:launcher": "node scripts/sync-runtime-launcher.cjs",
     "check:env": "node scripts/check-env.cjs",
+    "setup": "node scripts/dev-env.cjs stable",
+    "dev:setup": "node scripts/dev-env.cjs dev-setup",
+    "dev:install": "node scripts/dev-env.cjs install",
+    "dev:claude": "node scripts/dev-env.cjs claude",
     "check:alias-drift": "node scripts/check-alias-drift.cjs",
     "check:identity-drift": "node scripts/lint-package-identity-drift.cjs",
     "check:integrity": "node scripts/check-npm-integrity.cjs",
@@ -99,7 +112,7 @@
     "pretest:coverage": "npm run build:lib && npm run lint:skill-deps",
     "lint": "eslint . --cache --cache-location node_modules/.cache/eslint/",
     "lint:fix": "eslint . --fix",
-    "lint:ci": "npm run lint && npm run lint:skill-deps && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-windows-test-portability.cjs && node scripts/lint-allow-test-rule-refs.cjs && npm run check:platform-bindings-schema",
+    "lint:ci": "npm run lint && npm run lint:skill-deps && node scripts/lint-test-file-count.cjs && node scripts/lint-command-contract.cjs && node scripts/lint-pr-check-project-dir.cjs && npm run lint:legacy-name && node scripts/lint-regression-test-names.cjs && node scripts/lint-windows-test-portability.cjs && node scripts/lint-allow-test-rule-refs.cjs && npm run check:platform-bindings-schema && node scripts/lint-org-coordinates.cjs && node scripts/lint-neutrality-names.cjs",
     "lint:allow-test-rule-refs": "node scripts/lint-allow-test-rule-refs.cjs",
     "lint:windows-test-portability": "node scripts/lint-windows-test-portability.cjs",
     "lint:regression-names": "node scripts/lint-regression-test-names.cjs",

package/pareto-skills/pp-project-setup/SKILL.md

@@ -19,7 +19,6 @@ This skill bootstraps a new Pareto project and hands it off to `/pp-discovery` t
 
 **What it delivers:**
 - GitHub repository created and configured
-- Prototype folder structure (interactive HTML prototype, created during Discovery after Session 4)
 - Obsidian vault configured for project documentation
 - Requirements templates (functional requirements, user stories, test cases)
 - Project Definition template
@@ -120,7 +119,7 @@ Summarise everything before running any commands:
 >
 > I'll:
 > 1. Create the GitHub repo
-> 2. Scaffold the project structure (requirements + docs + prototype)
+> 2. Scaffold the project structure (requirements + docs)
 > 3. Set up the Project Definition and requirements templates
 > 4. Configure Obsidian vault for project documentation
 > 5. Configure GitHub project board, labels, and milestone
@@ -153,10 +152,6 @@ cd [PROJECT_NAME]
 
 ```bash
 mkdir -p \
-  prototype/src/components \
-  prototype/src/pages \
-  prototype/src/styles \
-  prototype/src/assets \
   requirements \
   Inputs/docs \
   docs/architecture \
@@ -164,7 +159,7 @@ mkdir -p \
   .obsidian
 ```
 
-Discovery Sprint artifacts are not scaffolded here — `/pp-discovery` creates `.planning/discovery/` itself on first run (session files, `_progress.md`, `_context.md`).
+Discovery Sprint artifacts are not scaffolded here — `/pp-discovery` creates `.planning/discovery/` itself on first run (session files, `_progress.md`, `_context.md`). The interactive prototype is built by `/pp-discovery prototype` into `.planning/discovery/prototype/`, on the UI kit the client vault declares when there is one, otherwise on the kit recorded in Session 4.
 
 #### 4c. Scaffold Project Definition & Requirements Templates
 
@@ -486,59 +481,7 @@ _Test cases are added here as user stories are defined during the Discovery Spri
 | | | | | | |
 ```
 
-##### 4c.3 Prototype README
-
-Generate `prototype/README.md`:
-
-```markdown
-# Interactive Prototype — [PROJECT_NAME]
-
-This folder contains the interactive HTML prototype for [PROJECT_NAME].
-The prototype is a core Discovery Sprint deliverable — it makes abstract requirements tangible
-and gives stakeholders something concrete to react to.
-
-## When It Gets Built
-
-The prototype is **created after Discovery Session 4** (UX Design Principles) and
-**iteratively updated** after Sessions 5, 7, and 8. By Session 13, it reflects the full MVP scope.
-
-| Trigger Session | What Happens |
-|----------------|--------------|
-| Session 4 (UX Design) | **Create** — key screens, navigation, user flows based on personas, EPICs, and UX principles |
-| Session 5 (Architecture) | **Update** — reflect architecture decisions (component structure, data flow) |
-| Session 7 (Identity) | **Update** — add role-based views, login flow, permission-gated UI |
-| Session 8 (Integration) | **Update** — add integration touchpoints (document uploads, external system indicators) |
-
-## Structure
-
-```
-prototype/
-├── index.html              # Entry point — links to all screens
-├── src/
-│   ├── components/         # Reusable UI components (header, sidebar, cards, etc.)
-│   ├── pages/              # Individual screen HTML files
-│   ├── styles/
-│   │   ├── tokens.css      # Design tokens (colors, fonts, spacing) from brand
-│   │   ├── global.css      # Base styles, resets, typography
-│   │   └── components.css  # Component-specific styles
-│   └── assets/             # Images, icons, logos
-└── README.md               # This file
-```
-
-## How to View
-
-Open `index.html` in any browser. No build tools or dependencies required.
-
-## Principles
-
-1. **Interactive, not static** — working navigation, hover states, clickable elements
-2. **Realistic content** — domain-specific placeholder data, not Lorem ipsum
-3. **Progressive fidelity** — starts with layout/navigation, gains detail with each session
-4. **Annotated** — subtle references to requirement IDs (FR-xxx, US-xxx) for traceability
-5. **Branded** — uses the customer's brand tokens (colors, typography, logo)
-```
-
-##### 4c.4 Input Documents
+##### 4c.3 Input Documents
 
 Create `Inputs/docs/.gitkeep` (empty file — placeholder for input documents, architecture notes, and reference materials gathered during discovery).
 
@@ -729,14 +672,13 @@ Run `/pp-discovery 1` to begin. `/pp-discovery` facilitates all 13 Discovery Spr
 | [Project Definition]([PROJECT_NAME]-Project-Definition.md) | Consolidated output document |
 | `.planning/discovery/_progress.md` | Session progress tracker (created by `/pp-discovery`) |
 | `.planning/discovery/_context.md` | Cross-session context accumulator (created by `/pp-discovery`) |
-| [prototype/](prototype/) | Interactive HTML prototype (created after Session 4) |
+| `.planning/discovery/prototype/` | Interactive prototype (built by `/pp-discovery prototype` after Session 4) |
 
 ## Project Structure
 ```
 [PROJECT_NAME]/
   .obsidian/              Obsidian vault configuration
-  .planning/discovery/    Discovery Sprint outputs (created by /pp-discovery)
-  prototype/              Interactive HTML prototype (built during Discovery)
+  .planning/discovery/    Discovery Sprint outputs and the prototype (created by /pp-discovery)
   requirements/           Functional requirements, user stories, test cases
   Inputs/docs/            Input documents and reference materials
   docs/                   Architecture decisions and guides

package/pp-core/bin/detect-build-commands.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# detect-build-commands.sh — THE build/test command sniff ladder (D-09-02, D-09-05).
+#
+# SOURCED, never executed. bash 3.2-compatible (macOS ships 3.2.57): no
+# associative arrays, no mapfile, no ${var,,}. Sets no `set -e`/`set -u`,
+# because it is sourced into shells that may or may not use them.
+#
+# ## Contract
+#
+#   pp_detect_build_cmd            -> prints ONE build command on stdout
+#   pp_detect_test_cmd [targets]   -> prints ONE test command on stdout
+#
+# Both ALWAYS exit 0. When no tool is detected they print NOTHING — and the
+# CALLER, not the ladder, decides how to report that. D-09-05: it must be
+# reported as NOT RUN, never as a pass (`true`) and never as a failure
+# (`false`). The four shipped ladders disagreed here — post-merge-gate,
+# execute-phase and audit-fix emitted `true` (a green gate on a project with no
+# runner) while verify-phase emitted `false` and then printed
+# "Test suite failed (exit code 1)" for a project that simply had no tests.
+# Emitting nothing makes the ambiguity impossible to reproduce at the callers.
+#
+# `workflow.build_command` / `workflow.test_command` still win over this
+# ladder; they are read by the caller, which only enters the ladder when the
+# configured value is empty. The ladder itself reads no configuration.
+#
+# ## Why one owner
+#
+# Four ladders shipped and they had already drifted from each other: only
+# post-merge-gate carried the Xcode arm; post-merge-gate's build and test
+# ladders put package.json in different positions; the pytest flags differed at
+# every site (-x at two, plain at one, ${REGRESSION_FILES} at another) and the
+# `uv run` fallback existed at only two. Adding a fifth divergent .NET arm to
+# each copy would repeat the prose-drift pattern this workstream has hit four
+# times, so D-09-02's discretion is exercised as: ONE owner, sourced by every
+# site. Plan 09-02 wires the five call sites:
+#   pp-core/workflows/execute-phase/steps/post-merge-gate.md  (Step A and Step B)
+#   pp-core/workflows/verify-phase.md                          (test suite step)
+#   pp-core/workflows/execute-phase.md                         (regression step)
+#   pp-core/workflows/audit-fix.md                             (per-fix test run)
+#
+# ## Where .NET sits, and why
+#
+# A .NET repository routinely carries a package.json for its front-end assets,
+# so a package.json arm placed first SHADOWS the solution and runs `npm test`
+# on a repo whose tests are MSTest/xUnit. The .NET arm therefore sits
+# IMMEDIATELY BEFORE the package.json arm in both ladders — after Justfile in
+# the test ladder, after the Python arm in the build ladder, matching where
+# package.json already sat in each. The relative order of every pre-existing
+# arm is unchanged. That placement is load-bearing and is proven by an executed
+# mutation rung in tests/gate-shell-owners.test.cjs
+# ("PLACEMENT RUNG"), which swaps the two arms in a scratch copy and asserts
+# the shadowing reappears.
+#
+# ## Convergence choices made where the four sites disagreed
+#
+#   * pytest loses the `-x` that two of the four carried: verify-phase.md
+#     reports total/passed/failed counts, and fail-fast truncates them.
+#   * pytest keeps the `uv run ...` fallback that two of the four carried: it is
+#     strictly more likely to find a runner and costs nothing when uv is absent.
+#   * the Xcode arm, which only post-merge-gate had, now applies everywhere.
+#
+# ## Security note (T-09-01)
+#
+# The emitted string is later run by the caller under `bash -c`. The .NET target
+# is a path `find` produced inside the project and is single-quoted in the
+# emitted command; a filename containing a single quote breaks the quoting
+# rather than escaping it, which is the pre-existing behaviour of every arm that
+# interpolates a discovered path (the Xcode arm does the same with its scheme).
+# The pytest `targets` argument is caller-supplied (execute-phase's
+# REGRESSION_FILES, derived from SUMMARY frontmatter) and is interpolated
+# unquoted exactly as it is today — deliberately, because it is a LIST of paths.
+# No new trust boundary is introduced here.
+
+# Emit one command line. Kept as a function so every arm is a single line and
+# the placement rung has an unambiguous two-line anchor to swap.
+_pp_emit() { printf '%s\n' "$1"; }
+
+# ─── .NET detection ──────────────────────────────────────────────────────────
+
+# Print the best .NET target, or nothing. A solution at the repository root
+# wins; failing that, the first project file.
+#
+# -maxdepth 3 on the csproj probe, and the depth is MEASURED rather than
+# guessed: the canonical .NET layout is src/<Project>/<Project>.csproj, which
+# `find` counts at depth 3 (./src, ./src/App, ./src/App/App.csproj). A
+# -maxdepth 2 probe covers ./App.csproj and ./App/App.csproj but misses the
+# canonical one entirely, which would silently hand a .NET repository back to
+# the package.json arm. All three layouts are pinned as a matrix in
+# tests/gate-shell-owners.test.cjs.
+#
+# The solution probe stays at depth 1: a .sln nested deeper falls through to
+# the project probe, which still yields a correct `dotnet test`, whereas a
+# deeper search risks picking an unrelated solution out of a vendored tree.
+_pp_dotnet_target() {
+  local found
+  found=$(find . -maxdepth 1 -name '*.sln' 2>/dev/null | head -1)
+  if [ -n "$found" ]; then printf '%s\n' "$found"; return 0; fi
+  found=$(find . -maxdepth 3 -name '*.csproj' -not -path '*/node_modules/*' 2>/dev/null | head -1)
+  if [ -n "$found" ]; then printf '%s\n' "$found"; return 0; fi
+  return 0
+}
+
+# True when this looks like a .NET repository. global.json and
+# Directory.Build.props mark one even when no .sln/.csproj sits shallow enough
+# for the probe above to find it.
+_pp_is_dotnet() {
+  if [ -n "$(_pp_dotnet_target)" ]; then return 0; fi
+  if [ -f "global.json" ]; then return 0; fi
+  if [ -f "Directory.Build.props" ]; then return 0; fi
+  return 1
+}
+
+# Emit `dotnet <verb>` against the best target, or bare when there is none —
+# `dotnet` searches the current directory itself in that case.
+_pp_dotnet_cmd() {
+  local verb="$1" target
+  target=$(_pp_dotnet_target)
+  if [ -n "$target" ]; then
+    _pp_emit "dotnet $verb '$target'"
+  else
+    _pp_emit "dotnet $verb"
+  fi
+}
+
+# ─── Xcode detection ─────────────────────────────────────────────────────────
+
+# Emit an xcodebuild command for <build|test>, or nothing when there is no
+# xcodeproj. The scheme probe is best-effort: with no Xcode installed
+# (CI, or a Command Line Tools-only Mac) it fails silently and the bare,
+# scheme-less form is emitted.
+_pp_xcode_cmd() {
+  local verb="$1" proj scheme
+  proj=$(find . -maxdepth 2 -name "*.xcodeproj" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+  if [ -z "$proj" ]; then return 0; fi
+  scheme=$(xcodebuild -list -json -project "$proj" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('project',{}).get('schemes',[None])[0] or '')" 2>/dev/null || true)
+  if [ -n "$scheme" ]; then
+    _pp_emit "xcodebuild $verb -scheme '$scheme' -destination 'platform=iOS Simulator,name=iPhone 16'"
+  else
+    _pp_emit "xcodebuild $verb -destination 'platform=iOS Simulator,name=iPhone 16'"
+  fi
+}
+
+# ─── The build ladder ────────────────────────────────────────────────────────
+
+pp_detect_build_cmd() {
+  local xcode
+  xcode=$(_pp_xcode_cmd build)
+  if [ -n "$xcode" ]; then _pp_emit "$xcode"; return 0; fi
+  if [ -f "Makefile" ] && grep -q "^build:" Makefile; then _pp_emit "make build"; return 0; fi
+  if [ -f "Justfile" ] || [ -f "justfile" ]; then _pp_emit "just build"; return 0; fi
+  if [ -f "Cargo.toml" ]; then _pp_emit "cargo build"; return 0; fi
+  if [ -f "go.mod" ]; then _pp_emit "go build ./..."; return 0; fi
+  if [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+    _pp_emit "python -m py_compile $(find . -name '*.py' -not -path './.planning/*' -not -path './node_modules/*' | head -20 | tr '\n' ' ')"
+    return 0
+  fi
+  if _pp_is_dotnet; then _pp_dotnet_cmd build; return 0; fi
+  if [ -f "package.json" ] && grep -q '"build"' package.json; then _pp_emit "npm run build"; return 0; fi
+  return 0
+}
+
+# ─── The test ladder ─────────────────────────────────────────────────────────
+
+# $1 (optional): a space-separated list of test targets, used only by the
+# Python arm (execute-phase's REGRESSION_FILES). Every other arm ignores it,
+# exactly as the four shipped ladders did.
+pp_detect_test_cmd() {
+  local targets="${1:-}" xcode
+  xcode=$(_pp_xcode_cmd test)
+  if [ -n "$xcode" ]; then _pp_emit "$xcode"; return 0; fi
+  if [ -f "Makefile" ] && grep -q "^test:" Makefile; then _pp_emit "make test"; return 0; fi
+  if [ -f "Justfile" ] || [ -f "justfile" ]; then _pp_emit "just test"; return 0; fi
+  if _pp_is_dotnet; then _pp_dotnet_cmd test; return 0; fi
+  if [ -f "package.json" ]; then _pp_emit "npm test"; return 0; fi
+  if [ -f "Cargo.toml" ]; then _pp_emit "cargo test"; return 0; fi
+  if [ -f "go.mod" ]; then _pp_emit "go test ./..."; return 0; fi
+  if [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
+    _pp_emit "python -m pytest ${targets:+$targets }-q --tb=short 2>&1 || uv run python -m pytest ${targets:+$targets }-q --tb=short"
+    return 0
+  fi
+  return 0
+}

package/pp-core/bin/lib/capability-activation.cjs

@@ -55,6 +55,20 @@ function _readRawConfigKey(filePath, dotKey) {
         return { found: false, value: undefined };
     }
 }
+/**
+ * The raw config files levels 2 and 3 read, in read order: the active
+ * `planningDir(cwd)/config.json`, then the root `planningRoot(cwd)/config.json`
+ * when it is a different file. Exported so `unreadableConfigFiles`
+ * (src/config-loader.cts) parses every file the hook resolver reads — this list
+ * beside `configFilesFor`, the loader's — without restating either. Both levels
+ * skip an unparseable file with a stderr warning and read on, which is the
+ * swallow a gate-governing caller must refuse.
+ */
+function activationConfigFilesFor(cwd) {
+    const wsConfigPath = node_path_1.default.join(planningDir(cwd), 'config.json');
+    const rootConfigPath = node_path_1.default.join(planningRoot(cwd), 'config.json');
+    return wsConfigPath !== rootConfigPath ? [wsConfigPath, rootConfigPath] : [wsConfigPath];
+}
 /**
  * Resolve the raw value for a dotted config key using the four-level precedence
  * walk. Returns { found, value } with the RAW value (not coerced to boolean),
@@ -76,15 +90,10 @@ function resolveConfigKey(dotKey, opts) {
         return { found: true, value: fromConfig.value };
     // Level 2 + 3: raw config.json files (only when cwd is available)
     if (cwd) {
-        const wsConfigPath = node_path_1.default.join(planningDir(cwd), 'config.json');
-        const rootConfigPath = node_path_1.default.join(planningRoot(cwd), 'config.json');
-        const fromWs = _readRawConfigKey(wsConfigPath, dotKey);
-        if (fromWs.found)
-            return { found: true, value: fromWs.value };
-        if (wsConfigPath !== rootConfigPath) {
-            const fromRoot = _readRawConfigKey(rootConfigPath, dotKey);
-            if (fromRoot.found)
-                return { found: true, value: fromRoot.value };
+        for (const filePath of activationConfigFilesFor(cwd)) {
+            const fromFile = _readRawConfigKey(filePath, dotKey);
+            if (fromFile.found)
+                return { found: true, value: fromFile.value };
         }
     }
     // Level 4: registry configSchema default
@@ -110,4 +119,5 @@ module.exports = {
     _readRawConfigKey,
     _resolveActivationValue,
     resolveConfigKey,
+    activationConfigFilesFor,
 };

package/pp-core/bin/lib/capability-registry.cjs

@@ -1931,7 +1931,7 @@ const capabilities = {
     "id": "vault",
     "role": "feature",
     "title": "Client vault load",
-    "description": "Fetches client-specific knowledge (standards, patterns, conventions) from a provider-selected git host vault repo at a pinned ref before plan and execute. Inert unless vault.enabled and .platform-bindings.json + client.vaultRepo are present. Advisory: fetch failure falls back to cached copy and warns; never blocks.",
+    "description": "Fetches client-specific knowledge (standards, patterns, conventions) from a provider-selected git host vault repo at a pinned ref before plan and execute. Inert unless vault.enabled is true. The vault.status gate reports one verdict (loaded / degraded) from a single owner; it confirms a degraded load and blocks only when vault.required is true. Fetch failure falls back to the cached copy and warns.",
     "tier": "full",
     "requires": [],
     "runtimeCompat": {
@@ -1949,6 +1949,11 @@ const capabilities = {
         "default": false,
         "description": "Enable client vault load. When false, all steps and gates are inert."
       },
+      "vault.required": {
+        "type": "boolean",
+        "default": false,
+        "description": "Make the client vault load gate blocking. When true (and vault.enabled is true), plan:pre and execute:pre stop unless the client vault is loaded at its pinned ref. Must be a JSON boolean; any other value is treated as false and named on the gate card."
+      },
       "vault.provider": {
         "type": "string",
         "default": "gitlab",
@@ -2005,6 +2010,18 @@ const capabilities = {
         "consumes": [],
         "when": "vault.enabled",
         "onError": "skip"
+      },
+      {
+        "point": "execute:pre",
+        "ref": {
+          "command": "vault fetch"
+        },
+        "produces": [
+          ".planning/vault/"
+        ],
+        "consumes": [],
+        "when": "vault.enabled",
+        "onError": "skip"
       }
     ],
     "contributions": [
@@ -2036,8 +2053,17 @@ const capabilities = {
           "query": "vault.status"
         },
         "when": "vault.enabled",
-        "blocking": false,
-        "onError": "skip"
+        "blocking": true,
+        "onError": "halt"
+      },
+      {
+        "point": "execute:pre",
+        "check": {
+          "query": "vault.status"
+        },
+        "when": "vault.enabled",
+        "blocking": true,
+        "onError": "halt"
       }
     ]
   },
@@ -2437,8 +2463,8 @@ const byLoopPoint = {
           "query": "vault.status"
         },
         "when": "vault.enabled",
-        "blocking": false,
-        "onError": "skip"
+        "blocking": true,
+        "onError": "halt"
       }
     ]
   },
@@ -2473,9 +2499,34 @@ const byLoopPoint = {
     ]
   },
   "execute:pre": {
-    "steps": [],
+    "steps": [
+      {
+        "capId": "vault",
+        "point": "execute:pre",
+        "ref": {
+          "command": "vault fetch"
+        },
+        "produces": [
+          ".planning/vault/"
+        ],
+        "consumes": [],
+        "when": "vault.enabled",
+        "onError": "skip"
+      }
+    ],
     "contributions": [],
-    "gates": []
+    "gates": [
+      {
+        "capId": "vault",
+        "point": "execute:pre",
+        "check": {
+          "query": "vault.status"
+        },
+        "when": "vault.enabled",
+        "blocking": true,
+        "onError": "halt"
+      }
+    ]
   },
   "execute:wave:pre": {
     "steps": [],
@@ -2764,6 +2815,7 @@ const configKeys = {
   "workflow.ui_review": "ui",
   "workflow.ui_safety_gate": "ui",
   "vault.enabled": "vault",
+  "vault.required": "vault",
   "vault.provider": "vault",
   "vault.cache_ttl_hours": "vault",
   "vault.fallback_repo": "vault",
@@ -3006,6 +3058,12 @@ const configSchema = {
     "default": false,
     "description": "Enable client vault load. When false, all steps and gates are inert."
   },
+  "vault.required": {
+    "owner": "vault",
+    "type": "boolean",
+    "default": false,
+    "description": "Make the client vault load gate blocking. When true (and vault.enabled is true), plan:pre and execute:pre stop unless the client vault is loaded at its pinned ref. Must be a JSON boolean; any other value is treated as false and named on the gate card."
+  },
   "vault.provider": {
     "owner": "vault",
     "type": "string",