@webpieces/rules-config 0.4.670 → 0.4.671

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.4.670",
+  "version": "0.4.671",
   "description": "Shared webpieces.config.json loader. Single source of truth for validation rule configuration consumed by @webpieces/ai-hook-rules, @webpieces/code-rules, and @webpieces/nx-webpieces-rules.",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/default-rules.js

@@ -76,12 +76,11 @@ exports.defaultRules = {
     },
     'pr-lifecycle-guard': { mode: 'ON' },
     // NOTE: `whole-repo-build-guard` is deliberately ABSENT from this table, and from RULE_SCHEMAS and
-    // HOOK_GUARD_NAMES with it. It is ON by default and turned off only from the optional machine-local
-    // ~/.webpieces/config.json (`experimental.whole-repo-build-guard: false`). Adding it back here would
-    // make it a rule every consumer must CONFIGURE — which is fault Y, i.e. every Bash call blocked on
-    // upgrade, which is exactly what it did the first time. That fault was the required KEY, not the
-    // default; being on by default from a file nobody has to create cannot reproduce it. See
-    // RETIRED_CONFIG_KEYS.
+    // HOOK_GUARD_NAMES with it. It is EXPERIMENTAL and OFF by default; the ONLY thing that turns it on
+    // is `experimental.whole-repo-build-guard: true` in the optional machine-local
+    // ~/.webpieces/config.json. Adding it back here would make it a rule every consumer must CONFIGURE
+    // — which is fault Y, i.e. every Bash call blocked on upgrade, which is exactly what it did the
+    // first time. See RETIRED_CONFIG_KEYS.
     //
     // branch-state-guard ships ON, INCLUDING its Read-blocking half.
     //

package/src/default-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"default-rules.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/default-rules.ts"],"names":[],"mappings":"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","sourcesContent":["// Default holistic exclude list for the validate-ts-in-src\n// rules. Bare names match a directory segment at any depth; globs match the\n// workspace-relative path. `**/*.d.ts` (ambient declarations) and\n// `**/jest.config.ts` legitimately live outside src/ and are exempt here.\nconst DEFAULT_EXCLUDE_PATHS: readonly string[] = [\n    'node_modules', 'dist', '.nx', '.git',\n    '**/*.d.ts', '**/jest.config.ts',\n];\n\n// On/off is driven by `mode` (\"OFF\" disables; an absent mode leaves a rule\n// on). Code-rules entries omit `mode` so each executor keeps its own default\n// scope; structural rules declare `mode: 'RUN_EVERY_TIME'`, bash guards `mode: 'ON'`.\n// webpieces-disable no-any-unknown -- rule options are opaque at framework level\nexport const defaultRules: Record<string, Record<string, unknown>> = {\n    'no-any-unknown': {},\n    'no-implicit-any': {},\n    'max-file-lines': { limit: 900 },\n    'max-method-lines': { limit: 80 },\n    'require-return-type': {},\n    'no-inline-type-literals': {},\n    'no-destructure': { allowTopLevel: true },\n    'catch-error-pattern': {},\n    'no-unmanaged-exceptions': {},\n    'no-file-import-cycles': { mode: 'RUN_EVERY_TIME' },\n    'runtime-architecture': { mode: 'RUN_EVERY_TIME', allowedCycles: [] },\n    'prisma-validate-dtos': {},\n    'prisma-converter': {},\n    'angular-no-direct-api-in-resolver': {},\n    'no-symbol-di-tokens': {},\n    // Ships OFF: a repo opts in per webpieces.config.json once it is ready to migrate any\n    // client-in-a-lib sites (severity defaults to \"warn\" so even when enabled it reports without\n    // failing until a repo flips it to \"error\").\n    'no-client-creation-outside-server-or-client': { mode: 'OFF' },\n    'no-custom-css': { allowGlobs: [] },\n    'no-process-exit-outside-main': {},\n    'inject-annotation-not-needed-for-concrete-class': {},\n    'framework-tag': { mode: 'MODIFIED_PROJECTS', knownTypes: ['browser', 'react', 'angular', 'node', 'express'] },\n    'role-tag': { mode: 'MODIFIED_PROJECTS', knownTypes: ['server', 'app', 'designed-lib', 'lib', 'client', 'api-lib'] },\n    'nx-wiring': { mode: 'RUN_EVERY_TIME' },\n    'di-graph': { mode: 'RUN_EVERY_TIME' },\n    'missing-design-annotation': { mode: 'RUN_EVERY_TIME' },\n    'validate-ts-in-src': {\n        mode: 'NEW_AND_MODIFIED_FILES',\n        allowedRootFiles: ['jest.setup.ts'],\n        excludePaths: [...DEFAULT_EXCLUDE_PATHS],\n    },\n    'no-js-files': { mode: 'OFF' },\n    // The five Nx infrastructure validators. They enforced unconditionally before they were wired to\n    // config, so RUN_EVERY_TIME is the only default that keeps existing repos behaving identically on\n    // upgrade. Set \"mode\": \"OFF\" to disable one; the two graph-baseline rules\n    // (validate-architecture-unchanged / validate-no-architecture-cycles) additionally honor\n    // turnOffRuleUntilEpoch — the other three are all-or-nothing (see rule-configs.ts).\n    'validate-architecture-unchanged': { mode: 'RUN_EVERY_TIME' },\n    'validate-no-architecture-cycles': { mode: 'RUN_EVERY_TIME' },\n    'validate-packagejson': { mode: 'RUN_EVERY_TIME' },\n    'validate-versions-locked': { mode: 'RUN_EVERY_TIME' },\n    'validate-eslint-sync': { mode: 'RUN_EVERY_TIME' },\n    // autoReapMergedBranches ships TRUE, and it is also what a fresh config is seeded with.\n    //\n    // It shipped FALSE on the reasoning that an upgrade must never delete branches unattended before a\n    // human opts in. In practice that produced the opposite of safety: nobody opts in, dead branches\n    // pile up, and the pile is what makes a real branch hard to find. The reap is also NOT destructive\n    // in the way the old comment implied — BranchReaper deletes only provably-dead branches (a merged\n    // PR, a squash-merge backup of one, or no commits of their own), spares everything else for a\n    // human, and logs each deletion to .webpieces/logs/branch-mutations.log with the pre-delete SHA\n    // and a ready-made `recover=` command. So the worst case is one paste to undo, which a human can\n    // resolve; the previous default's worst case was unbounded accumulation nobody ever cleaned.\n    //\n    // Set it false to keep reaping manual; `pnpm wp-cleanup` works either way.\n    'branch-creation-guard': {\n        mode: 'ON',\n        subBranchNaming: 'feature/<ticket>/<short-description>',\n        autoReapMergedBranches: true,\n    },\n    'pr-lifecycle-guard': { mode: 'ON' },\n    // NOTE: `whole-repo-build-guard` is deliberately ABSENT from this table, and from RULE_SCHEMAS and\n    // HOOK_GUARD_NAMES with it. It is ON by default and turned off only from the optional machine-local\n    // ~/.webpieces/config.json (`experimental.whole-repo-build-guard: false`). Adding it back here would\n    // make it a rule every consumer must CONFIGURE — which is fault Y, i.e. every Bash call blocked on\n    // upgrade, which is exactly what it did the first time. That fault was the required KEY, not the\n    // default; being on by default from a file nobody has to create cannot reproduce it. See\n    // RETIRED_CONFIG_KEYS.\n    //\n    // branch-state-guard ships ON, INCLUDING its Read-blocking half.\n    //\n    // Its predecessor `read-stale-guard` shipped OFF as a \"phase 1\" staged rollout, on the reasoning\n    // that Read is the highest-blast-radius tool there is and nobody should be armed before verifying\n    // the fail-open paths against their own git layout. Phase 1 is over: this repo has run it ON in\n    // production for releases, and the fail-open paths (branch undeterminable, cache absent, cache for\n    // another branch, offline, dirty tree on main) are each covered by tests. Keeping it OFF now buys\n    // nothing and costs the exact incident the guard exists for — a session spent reading a tree 18\n    // commits behind while the log read \"handled\".\n    //\n    // Nothing is armed behind anyone's back either way: every built-in requires an explicit entry (the\n    // config-sync check blocks until one exists), so a consumer states this mode themselves on upgrade.\n    'branch-state-guard': { mode: 'ON' },\n};\n\nexport const defaultRulesDir: readonly string[] = [];\n"]}
+{"version":3,"file":"default-rules.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/default-rules.ts"],"names":[],"mappings":"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","sourcesContent":["// Default holistic exclude list for the validate-ts-in-src\n// rules. Bare names match a directory segment at any depth; globs match the\n// workspace-relative path. `**/*.d.ts` (ambient declarations) and\n// `**/jest.config.ts` legitimately live outside src/ and are exempt here.\nconst DEFAULT_EXCLUDE_PATHS: readonly string[] = [\n    'node_modules', 'dist', '.nx', '.git',\n    '**/*.d.ts', '**/jest.config.ts',\n];\n\n// On/off is driven by `mode` (\"OFF\" disables; an absent mode leaves a rule\n// on). Code-rules entries omit `mode` so each executor keeps its own default\n// scope; structural rules declare `mode: 'RUN_EVERY_TIME'`, bash guards `mode: 'ON'`.\n// webpieces-disable no-any-unknown -- rule options are opaque at framework level\nexport const defaultRules: Record<string, Record<string, unknown>> = {\n    'no-any-unknown': {},\n    'no-implicit-any': {},\n    'max-file-lines': { limit: 900 },\n    'max-method-lines': { limit: 80 },\n    'require-return-type': {},\n    'no-inline-type-literals': {},\n    'no-destructure': { allowTopLevel: true },\n    'catch-error-pattern': {},\n    'no-unmanaged-exceptions': {},\n    'no-file-import-cycles': { mode: 'RUN_EVERY_TIME' },\n    'runtime-architecture': { mode: 'RUN_EVERY_TIME', allowedCycles: [] },\n    'prisma-validate-dtos': {},\n    'prisma-converter': {},\n    'angular-no-direct-api-in-resolver': {},\n    'no-symbol-di-tokens': {},\n    // Ships OFF: a repo opts in per webpieces.config.json once it is ready to migrate any\n    // client-in-a-lib sites (severity defaults to \"warn\" so even when enabled it reports without\n    // failing until a repo flips it to \"error\").\n    'no-client-creation-outside-server-or-client': { mode: 'OFF' },\n    'no-custom-css': { allowGlobs: [] },\n    'no-process-exit-outside-main': {},\n    'inject-annotation-not-needed-for-concrete-class': {},\n    'framework-tag': { mode: 'MODIFIED_PROJECTS', knownTypes: ['browser', 'react', 'angular', 'node', 'express'] },\n    'role-tag': { mode: 'MODIFIED_PROJECTS', knownTypes: ['server', 'app', 'designed-lib', 'lib', 'client', 'api-lib'] },\n    'nx-wiring': { mode: 'RUN_EVERY_TIME' },\n    'di-graph': { mode: 'RUN_EVERY_TIME' },\n    'missing-design-annotation': { mode: 'RUN_EVERY_TIME' },\n    'validate-ts-in-src': {\n        mode: 'NEW_AND_MODIFIED_FILES',\n        allowedRootFiles: ['jest.setup.ts'],\n        excludePaths: [...DEFAULT_EXCLUDE_PATHS],\n    },\n    'no-js-files': { mode: 'OFF' },\n    // The five Nx infrastructure validators. They enforced unconditionally before they were wired to\n    // config, so RUN_EVERY_TIME is the only default that keeps existing repos behaving identically on\n    // upgrade. Set \"mode\": \"OFF\" to disable one; the two graph-baseline rules\n    // (validate-architecture-unchanged / validate-no-architecture-cycles) additionally honor\n    // turnOffRuleUntilEpoch — the other three are all-or-nothing (see rule-configs.ts).\n    'validate-architecture-unchanged': { mode: 'RUN_EVERY_TIME' },\n    'validate-no-architecture-cycles': { mode: 'RUN_EVERY_TIME' },\n    'validate-packagejson': { mode: 'RUN_EVERY_TIME' },\n    'validate-versions-locked': { mode: 'RUN_EVERY_TIME' },\n    'validate-eslint-sync': { mode: 'RUN_EVERY_TIME' },\n    // autoReapMergedBranches ships TRUE, and it is also what a fresh config is seeded with.\n    //\n    // It shipped FALSE on the reasoning that an upgrade must never delete branches unattended before a\n    // human opts in. In practice that produced the opposite of safety: nobody opts in, dead branches\n    // pile up, and the pile is what makes a real branch hard to find. The reap is also NOT destructive\n    // in the way the old comment implied — BranchReaper deletes only provably-dead branches (a merged\n    // PR, a squash-merge backup of one, or no commits of their own), spares everything else for a\n    // human, and logs each deletion to .webpieces/logs/branch-mutations.log with the pre-delete SHA\n    // and a ready-made `recover=` command. So the worst case is one paste to undo, which a human can\n    // resolve; the previous default's worst case was unbounded accumulation nobody ever cleaned.\n    //\n    // Set it false to keep reaping manual; `pnpm wp-cleanup` works either way.\n    'branch-creation-guard': {\n        mode: 'ON',\n        subBranchNaming: 'feature/<ticket>/<short-description>',\n        autoReapMergedBranches: true,\n    },\n    'pr-lifecycle-guard': { mode: 'ON' },\n    // NOTE: `whole-repo-build-guard` is deliberately ABSENT from this table, and from RULE_SCHEMAS and\n    // HOOK_GUARD_NAMES with it. It is EXPERIMENTAL and OFF by default; the ONLY thing that turns it on\n    // is `experimental.whole-repo-build-guard: true` in the optional machine-local\n    // ~/.webpieces/config.json. Adding it back here would make it a rule every consumer must CONFIGURE\n    // — which is fault Y, i.e. every Bash call blocked on upgrade, which is exactly what it did the\n    // first time. See RETIRED_CONFIG_KEYS.\n    //\n    // branch-state-guard ships ON, INCLUDING its Read-blocking half.\n    //\n    // Its predecessor `read-stale-guard` shipped OFF as a \"phase 1\" staged rollout, on the reasoning\n    // that Read is the highest-blast-radius tool there is and nobody should be armed before verifying\n    // the fail-open paths against their own git layout. Phase 1 is over: this repo has run it ON in\n    // production for releases, and the fail-open paths (branch undeterminable, cache absent, cache for\n    // another branch, offline, dirty tree on main) are each covered by tests. Keeping it OFF now buys\n    // nothing and costs the exact incident the guard exists for — a session spent reading a tree 18\n    // commits behind while the log read \"handled\".\n    //\n    // Nothing is armed behind anyone's back either way: every built-in requires an explicit entry (the\n    // config-sync check blocks until one exists), so a consumer states this mode themselves on upgrade.\n    'branch-state-guard': { mode: 'ON' },\n};\n\nexport const defaultRulesDir: readonly string[] = [];\n"]}

package/src/home-config.d.ts

@@ -70,12 +70,12 @@
  * used to be a loud rejection; it is now a key nothing reads, so the flag keeps its default and nothing
  * about the machine's behaviour reveals the mistake.
  *
- * That bites HARDEST on a key whose default is ON, which `whole-repo-build-guard` now is
- * (WHOLE_REPO_BUILD_GUARD_DEFAULT). Misspell the OPT-OUT and the guard stays on while the author
- * believes they turned it off — a failure that argues with them rather than one they can shrug at. It is
- * the strongest reason the warning below is not optional decoration, and the reason `nearestKnownKey`
- * had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a transposition, exactly
- * the class of typo an equality test cannot see.
+ * Every key here is an OPT-IN that defaults OFF, so a typo costs the author the feature they meant to
+ * switch on: misspell `whole-repo-build-guard` and the guard stays inert while they believe they armed
+ * it. That is the milder of the two failures — nothing they were doing stops working — but it is still
+ * invisible without a signal, which is why the warning below is not optional decoration, and why
+ * `nearestKnownKey` had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a
+ * transposition, exactly the class of typo an equality test cannot see.
  *
  * That is mitigated, not eliminated, by making the ignore VISIBLE: every unknown key is printed once per
  * load as a `[webpieces]` warning on stderr, and `nearestKnownKey` upgrades that line with a "did you
@@ -106,10 +106,16 @@
  * default state. A repo-tracked config key cannot express that — an entry there is something every
  * consumer must add, on a schedule set by whoever bumps the release.
  *
- * Note which half of that was the outage. It was the REQUIRED KEY, not the on-by-default behaviour: the
- * failure was at config LOAD, before any command was judged. `whole-repo-build-guard` defaults ON again
- * today (see WHOLE_REPO_BUILD_GUARD_DEFAULT) and cannot reproduce it, because there is nothing to add
- * anywhere — the only file that could carry it is optional, and absent is a fully supported state.
+ * Note which half of that was the outage. It was the REQUIRED KEY: the failure was at config LOAD,
+ * before any command was judged. That is why every key here stays OPTIONAL and why an absent file
+ * returns all-defaults silently.
+ *
+ * The DEFAULT is settled separately, by a standing policy this file does not get to re-litigate: EVERY
+ * `experimental.*` flag ships OFF and stays OFF for two years. `whole-repo-build-guard` is one of them,
+ * so it is OFF unless a machine writes `{"experimental": {"whole-repo-build-guard": true}}`. A flag that
+ * defaults ON is not an experiment — it is a shipped behaviour that skipped its soak period, and it
+ * changes what every agent on every machine can do the moment they upgrade. Low uptake of an opt-in
+ * experiment is information ABOUT the experiment; it is not a licence to force it on everybody.
  */
 export declare const HOME_CONFIG_DIR = ".webpieces";
 export declare const HOME_CONFIG_FILE = "config.json";
@@ -117,28 +123,6 @@ export declare const HOME_EXPERIMENTAL_SECTION = "experimental";
 export declare const HOME_KEY_BUILD_GATE_LOG_CAPTURE = "buildGateLogCapture";
 export declare const HOME_KEY_WHOLE_REPO_BUILD_GUARD = "whole-repo-build-guard";
 export declare const HOME_KEY_ORPHAN_DIR_SWEEP = "orphan-dir-sweep";
-/**
- * `whole-repo-build-guard`'s value on a machine that does not name the key — including the machine with
- * no such file at all, which is essentially every machine. It is TRUE: the guard is ON by default.
- *
- * ─── Why this one key defaults ON, and why that is not the outage this file warns about ─────────────
- * The outage recorded below was a CONFIG-LOAD failure: the guard once required an entry under
- * `hookGuards` in the repo-tracked `webpieces.config.json`, so every consumer who upgraded without
- * adding it hit fault Y and had EVERY Bash call blocked, for a feature they had never asked for. The
- * shape of that failure is "you must edit a file to get your shell back". Nothing here reproduces it:
- * no file needs to exist, no key needs to be added, and the load path for an absent or silent file is
- * unchanged. What changes is only what the guard DOES once loaded — it refuses a command that would
- * build the whole monorepo, and hands back the scoped command in its place.
- *
- * That is the behaviour the guard was written for, and OFF-by-default is why it never delivered it: a
- * guard nobody opts into never fires. The measured consequence is a sibling repo whose `ci:local`
- * verify chain ran three whole-world passes on every inner loop for months, while the correct command
- * sat unused in `commands.pr-gate.buildCommand`.
- *
- * The escape hatch stays, and it is one line: `{"experimental": {"whole-repo-build-guard": false}}`
- * turns it off for a machine, with no repo config involved.
- */
-export declare const WHOLE_REPO_BUILD_GUARD_DEFAULT = true;
 /**
  * The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than
  * rejected (see the class docblock: this document is machine-global and older releases must survive
@@ -162,16 +146,15 @@ export declare class HomeConfig {
      */
     buildGateLogCapture: boolean;
     /**
-     * NOT experimental, and ON unless this machine says otherwise: `WHOLE_REPO_BUILD_GUARD_DEFAULT`.
-     * When true, `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and
-     * hands back the repo's own scoped build command (`pnpm wp-build`). Setting it false makes the guard
-     * completely inert: no block, no log, no message.
+     * EXPERIMENTAL, and OFF unless this machine opts IN with an explicit `true`. When true,
+     * `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and hands back
+     * the repo's own scoped build command (`pnpm wp-build`). False — and absent, and no file at all —
+     * makes the guard completely inert: no block, no log, no message.
      *
-     * This is the guard's ONLY switch, and it is an OPT-OUT. There is deliberately no
+     * This is the guard's ONLY switch, and it is an OPT-IN. There is deliberately no
      * webpieces.config.json entry for it (see RETIRED_CONFIG_KEYS): a guard that every consumer must
      * ADD A KEY to avoid being blocked by is a guard that ships an outage on upgrade, which is exactly
-     * what happened. Defaulting ON here is the opposite shape — nothing has to be added anywhere, and
-     * see WHOLE_REPO_BUILD_GUARD_DEFAULT for why that distinction is the whole argument.
+     * what happened once. Living here means the default state needs no file, no key and no edit.
      */
     wholeRepoBuildGuard: boolean;
     /**
@@ -256,12 +239,12 @@ export declare class HomeConfigService {
     private parse;
     private validate;
     /**
-     * An absent key falls back to `whenAbsent`, which every caller states OUT LOUD — there is no implicit
-     * "absent means false" any more, because `whole-repo-build-guard` defaults ON and a hidden default
-     * would put the two halves of that fact in different files.
+     * An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing
+     * `GUARD_OFF_WHEN_ABSENT` — an implicit "absent means false" buried in this method would put the
+     * default and the key that carries it in different places, free to drift apart.
      *
-     * A PRESENT key of the wrong type is still an ERROR, and that is the line the unknown-key change
-     * deliberately did not move: `"whole-repo-build-guard": "yes"` is a file somebody wrote wrongly, not
+     * A PRESENT key of the wrong type is still an ERROR, and that is the line neither the unknown-key change
+     * nor this one moved: `"whole-repo-build-guard": "yes"` is a file somebody wrote wrongly, not
      * a file written for a different release. No release of webpieces has ever given this key a string
      * meaning, so there is no forward-compatibility story to protect and nothing is gained by guessing —
      * whereas guessing would turn a typed value into a silent fallback to the default, which is the very

package/src/home-config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HomeConfigService = exports.RETIRED_HOME_CONFIG_KEYS = exports.RetiredHomeConfigKey = exports.HomeConfig = exports.ALLOWED_EXPERIMENTAL = exports.ALLOWED_TOP_LEVEL = exports.WHOLE_REPO_BUILD_GUARD_DEFAULT = exports.HOME_KEY_ORPHAN_DIR_SWEEP = exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD = exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE = exports.HOME_EXPERIMENTAL_SECTION = exports.HOME_CONFIG_FILE = exports.HOME_CONFIG_DIR = void 0;
+exports.HomeConfigService = exports.RETIRED_HOME_CONFIG_KEYS = exports.RetiredHomeConfigKey = exports.HomeConfig = exports.ALLOWED_EXPERIMENTAL = exports.ALLOWED_TOP_LEVEL = exports.HOME_KEY_ORPHAN_DIR_SWEEP = exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD = exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE = exports.HOME_EXPERIMENTAL_SECTION = exports.HOME_CONFIG_FILE = exports.HOME_CONFIG_DIR = void 0;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const os = tslib_1.__importStar(require("os"));
@@ -80,12 +80,12 @@ const to_error_1 = require("./to-error");
  * used to be a loud rejection; it is now a key nothing reads, so the flag keeps its default and nothing
  * about the machine's behaviour reveals the mistake.
  *
- * That bites HARDEST on a key whose default is ON, which `whole-repo-build-guard` now is
- * (WHOLE_REPO_BUILD_GUARD_DEFAULT). Misspell the OPT-OUT and the guard stays on while the author
- * believes they turned it off — a failure that argues with them rather than one they can shrug at. It is
- * the strongest reason the warning below is not optional decoration, and the reason `nearestKnownKey`
- * had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a transposition, exactly
- * the class of typo an equality test cannot see.
+ * Every key here is an OPT-IN that defaults OFF, so a typo costs the author the feature they meant to
+ * switch on: misspell `whole-repo-build-guard` and the guard stays inert while they believe they armed
+ * it. That is the milder of the two failures — nothing they were doing stops working — but it is still
+ * invisible without a signal, which is why the warning below is not optional decoration, and why
+ * `nearestKnownKey` had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a
+ * transposition, exactly the class of typo an equality test cannot see.
  *
  * That is mitigated, not eliminated, by making the ignore VISIBLE: every unknown key is printed once per
  * load as a `[webpieces]` warning on stderr, and `nearestKnownKey` upgrades that line with a "did you
@@ -116,10 +116,16 @@ const to_error_1 = require("./to-error");
  * default state. A repo-tracked config key cannot express that — an entry there is something every
  * consumer must add, on a schedule set by whoever bumps the release.
  *
- * Note which half of that was the outage. It was the REQUIRED KEY, not the on-by-default behaviour: the
- * failure was at config LOAD, before any command was judged. `whole-repo-build-guard` defaults ON again
- * today (see WHOLE_REPO_BUILD_GUARD_DEFAULT) and cannot reproduce it, because there is nothing to add
- * anywhere — the only file that could carry it is optional, and absent is a fully supported state.
+ * Note which half of that was the outage. It was the REQUIRED KEY: the failure was at config LOAD,
+ * before any command was judged. That is why every key here stays OPTIONAL and why an absent file
+ * returns all-defaults silently.
+ *
+ * The DEFAULT is settled separately, by a standing policy this file does not get to re-litigate: EVERY
+ * `experimental.*` flag ships OFF and stays OFF for two years. `whole-repo-build-guard` is one of them,
+ * so it is OFF unless a machine writes `{"experimental": {"whole-repo-build-guard": true}}`. A flag that
+ * defaults ON is not an experiment — it is a shipped behaviour that skipped its soak period, and it
+ * changes what every agent on every machine can do the moment they upgrade. Low uptake of an opt-in
+ * experiment is information ABOUT the experiment; it is not a licence to force it on everybody.
  */
 exports.HOME_CONFIG_DIR = '.webpieces';
 exports.HOME_CONFIG_FILE = 'config.json';
@@ -137,30 +143,17 @@ exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD = 'whole-repo-build-guard';
 // it switches, exactly as the guard key above is — one name, greppable from either end.
 exports.HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';
 /**
- * `whole-repo-build-guard`'s value on a machine that does not name the key — including the machine with
- * no such file at all, which is essentially every machine. It is TRUE: the guard is ON by default.
- *
- * ─── Why this one key defaults ON, and why that is not the outage this file warns about ─────────────
- * The outage recorded below was a CONFIG-LOAD failure: the guard once required an entry under
- * `hookGuards` in the repo-tracked `webpieces.config.json`, so every consumer who upgraded without
- * adding it hit fault Y and had EVERY Bash call blocked, for a feature they had never asked for. The
- * shape of that failure is "you must edit a file to get your shell back". Nothing here reproduces it:
- * no file needs to exist, no key needs to be added, and the load path for an absent or silent file is
- * unchanged. What changes is only what the guard DOES once loaded — it refuses a command that would
- * build the whole monorepo, and hands back the scoped command in its place.
- *
- * That is the behaviour the guard was written for, and OFF-by-default is why it never delivered it: a
- * guard nobody opts into never fires. The measured consequence is a sibling repo whose `ci:local`
- * verify chain ran three whole-world passes on every inner loop for months, while the correct command
- * sat unused in `commands.pr-gate.buildCommand`.
- *
- * The escape hatch stays, and it is one line: `{"experimental": {"whole-repo-build-guard": false}}`
- * turns it off for a machine, with no repo config involved.
+ * EVERY key's value when it is not named — including on the machine with no such file at all, which is
+ * essentially every machine. False, for all of them, with no exceptions and no per-key table.
+ *
+ * That uniformity is the policy, not a coincidence: every `experimental.*` flag ships OFF and stays OFF
+ * for two years, so "this machine never opted in" is byte-for-byte the behaviour of having no file. ON
+ * requires an explicit `true`; absent, and an explicit `false`, are the same state.
+ *
+ * Named rather than written as a bare `false` at each call site so the reason travels with the value —
+ * and there is deliberately exactly ONE such constant, because a second one would be a second place a
+ * default is stated, free to disagree with this one.
  */
-exports.WHOLE_REPO_BUILD_GUARD_DEFAULT = true;
-// Every OTHER key's value when it is not named. False — "this machine never opted in" — which for those
-// keys is byte-for-byte the behaviour of having no file at all. Named rather than written as a bare
-// `false` at each call site so the asymmetry with the constant above is visible where it is passed.
 const GUARD_OFF_WHEN_ABSENT = false;
 /**
  * The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than
@@ -192,10 +185,8 @@ exports.ALLOWED_EXPERIMENTAL = [
  * reasoning was sound for a single version and wrong for a shared file. It is optional now, along with
  * every other key.
  *
- * Absent then reads as each key's declared default. For every EXPERIMENTAL key that is false, which is
- * byte-for-byte the behaviour of having no file at all. `whole-repo-build-guard` is the one exception
- * and it defaults TRUE — it is no longer experimental — for the reason spelled out at
- * WHOLE_REPO_BUILD_GUARD_DEFAULT.
+ * Absent then reads as the ONE declared default, `GUARD_OFF_WHEN_ABSENT`: false, for every key without
+ * exception, which is byte-for-byte the behaviour of having no file at all.
  *
  * The other half of cross-version safety — an OLD release IGNORING a key a NEW one added, rather than
  * rejecting it — is solved by `warnUnknownKeys` below. The two halves are one invariant: for the set of
@@ -216,16 +207,15 @@ class HomeConfig {
      */
     buildGateLogCapture;
     /**
-     * NOT experimental, and ON unless this machine says otherwise: `WHOLE_REPO_BUILD_GUARD_DEFAULT`.
-     * When true, `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and
-     * hands back the repo's own scoped build command (`pnpm wp-build`). Setting it false makes the guard
-     * completely inert: no block, no log, no message.
+     * EXPERIMENTAL, and OFF unless this machine opts IN with an explicit `true`. When true,
+     * `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and hands back
+     * the repo's own scoped build command (`pnpm wp-build`). False — and absent, and no file at all —
+     * makes the guard completely inert: no block, no log, no message.
      *
-     * This is the guard's ONLY switch, and it is an OPT-OUT. There is deliberately no
+     * This is the guard's ONLY switch, and it is an OPT-IN. There is deliberately no
      * webpieces.config.json entry for it (see RETIRED_CONFIG_KEYS): a guard that every consumer must
      * ADD A KEY to avoid being blocked by is a guard that ships an outage on upgrade, which is exactly
-     * what happened. Defaulting ON here is the opposite shape — nothing has to be added anywhere, and
-     * see WHOLE_REPO_BUILD_GUARD_DEFAULT for why that distinction is the whole argument.
+     * what happened once. Living here means the default state needs no file, no key and no edit.
      */
     wholeRepoBuildGuard;
     /**
@@ -314,13 +304,12 @@ let HomeConfigService = class HomeConfigService {
      */
     load(homeDir = os.homedir()) {
         const raw = this.readIfPresent(this.configPath(homeDir));
-        // THE ABSENT-FILE STATE, and the ONE place it is constructed. Every EXPERIMENTAL flag is off;
-        // `whole-repo-build-guard` is NOT experimental any more and takes WHOLE_REPO_BUILD_GUARD_DEFAULT
-        // (true) — the same value a present file that does not name the key gets, so "no file" and "file
-        // that ignores this key" can never disagree. Spelled out rather than defaulted in the
-        // constructor — see the note there on why a defaulted parameter is a shim.
+        // THE ABSENT-FILE STATE, and the ONE place it is constructed. Every flag is off — the same value
+        // a present file that does not name the key gets, so "no file" and "file that ignores this key"
+        // can never disagree. Spelled out rather than defaulted in the constructor — see the note there
+        // on why a defaulted parameter is a shim.
         if (raw === null) {
-            return new HomeConfig(GUARD_OFF_WHEN_ABSENT, exports.WHOLE_REPO_BUILD_GUARD_DEFAULT, GUARD_OFF_WHEN_ABSENT);
+            return new HomeConfig(GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT);
         }
         return this.validate(this.parse(raw, this.configPath(homeDir)), this.configPath(homeDir));
     }
@@ -407,15 +396,15 @@ let HomeConfigService = class HomeConfigService {
         // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above
         const experimental = (section ?? {});
         this.warnUnknownKeys(Object.keys(experimental), exports.ALLOWED_EXPERIMENTAL, `${exports.HOME_EXPERIMENTAL_SECTION}.`);
-        return new HomeConfig(this.readOptionalBoolean(experimental, exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalBoolean(experimental, exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, exports.WHOLE_REPO_BUILD_GUARD_DEFAULT), this.readOptionalBoolean(experimental, exports.HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT));
+        return new HomeConfig(this.readOptionalBoolean(experimental, exports.HOME_KEY_BUILD_GATE_LOG_CAPTURE, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalBoolean(experimental, exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, GUARD_OFF_WHEN_ABSENT), this.readOptionalBoolean(experimental, exports.HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT));
     }
     /**
-     * An absent key falls back to `whenAbsent`, which every caller states OUT LOUD — there is no implicit
-     * "absent means false" any more, because `whole-repo-build-guard` defaults ON and a hidden default
-     * would put the two halves of that fact in different files.
+     * An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing
+     * `GUARD_OFF_WHEN_ABSENT` — an implicit "absent means false" buried in this method would put the
+     * default and the key that carries it in different places, free to drift apart.
      *
-     * A PRESENT key of the wrong type is still an ERROR, and that is the line the unknown-key change
-     * deliberately did not move: `"whole-repo-build-guard": "yes"` is a file somebody wrote wrongly, not
+     * A PRESENT key of the wrong type is still an ERROR, and that is the line neither the unknown-key change
+     * nor this one moved: `"whole-repo-build-guard": "yes"` is a file somebody wrote wrongly, not
      * a file written for a different release. No release of webpieces has ever given this key a string
      * meaning, so there is no forward-compatibility story to protect and nothing is gained by guessing —
      * whereas guessing would turn a typed value into a silent fallback to the default, which is the very