npm - @webpieces/rules-config - Versions diffs - 0.4.724 → 0.4.726 - Mend

@webpieces/rules-config 0.4.724 → 0.4.726

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/package.json +1 -1
package/src/home-config.d.ts +1 -1
package/src/home-config.js +2 -2
package/src/home-config.js.map +1 -1
package/templates/webpieces.branch-state-matrix.md +11 -11

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/rules-config",
-  "version": "0.4.724",
+  "version": "0.4.726",
   "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/home-config.d.ts CHANGED Viewed

@@ -206,7 +206,7 @@ export declare class HomeConfig {
      */
     wholeRepoBuildGuard: boolean;
     /**
-     * EXPERIMENTAL. When true, `wp-checkout-clean-main` ARCHIVES the orphan directories it finds — the
+     * EXPERIMENTAL. When true, `wp-sync-main` ARCHIVES the orphan directories it finds — the
      * package directories left behind on every clone by an `nx g move`, which git cannot remove because
      * an ignored `dist/` or `node_modules/` survives the deletion of every tracked file under them.
      *

package/src/home-config.js CHANGED Viewed

@@ -157,7 +157,7 @@ exports.HOME_EXPERIMENTAL_SECTION = 'experimental';
 // gets unconditionally must not have its shell broken for saying yes early. It falls through to the
 // unknown-key WARNING instead, which says the key had no effect and names what is understood.
 exports.HOME_KEY_WHOLE_REPO_BUILD_GUARD = 'whole-repo-build-guard';
-// The on/off switch for the orphan-directory sweep `wp-checkout-clean-main` runs. Named for the thing
+// The on/off switch for the orphan-directory sweep `wp-sync-main` runs. Named for the thing
 // it switches, exactly as the guard key above is — one name, greppable from either end.
 exports.HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';
 /**
@@ -281,7 +281,7 @@ class HomeConfig {
      */
     wholeRepoBuildGuard;
     /**
-     * EXPERIMENTAL. When true, `wp-checkout-clean-main` ARCHIVES the orphan directories it finds — the
+     * EXPERIMENTAL. When true, `wp-sync-main` ARCHIVES the orphan directories it finds — the
      * package directories left behind on every clone by an `nx g move`, which git cannot remove because
      * an ignored `dist/` or `node_modules/` survives the deletion of every tracked file under them.
      *

package/src/home-config.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"home-config.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/home-config.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { InformAiError } from './inform-ai-error';\nimport { toError } from './to-error';\nimport { DOCUMENTATION_KEYS, HOME_KEY_DOC, HOME_KEY_AI_DOC, HomeDocKeys } from './home-config-doc-keys';\nimport {\n RetiredHomeConfigKey, RETIRED_HOME_CONFIG_KEYS, EndedExperiment, ENDED_EXPERIMENTS,\n} from './home-config-retired-keys';\n\nexport { DOCUMENTATION_KEYS, HOME_KEY_DOC, HOME_KEY_AI_DOC, HomeDocKeys };\nexport { RetiredHomeConfigKey, RETIRED_HOME_CONFIG_KEYS, EndedExperiment, ENDED_EXPERIMENTS };\n\n/*\n `~/.webpieces/config.json` — the MACHINE-GLOBAL preference file, and a different thing from the repo's\n * tracked `webpieces.config.json`. It is EXPERIMENTAL and entirely OPTIONAL.\n \n ─── ABSENT IS THE NORMAL STATE, AND IT IS NEVER AN ERROR ─────────────────────────────────────────────\n * Essentially every consumer of these packages has no such file, and for them every `wp-` command must\n behave byte-for-byte as it did before this file was ever read: no error, no warning, no log line, no\n * extra file, nothing. `load()` therefore treats EVERY failure to READ the bytes — the file missing, the\n * `~/.webpieces` directory missing, a permission error, a path component that is not a directory — as\n * \"not opted in\", and returns all-defaults silently. That is not a fallback for a wrong shape; it is the\n * definition of \"the user did not create this file\".\n \n ─── THE STANDING RULE, FOR WHOEVER EDITS THIS FILE NEXT ──────────────────────────────────────────────\n * This file is MACHINE-GLOBAL: ONE document on the disk, read by EVERY repo on the machine, and those\n * repos are pinned to DIFFERENT webpieces releases. Two rules follow, and they are not negotiable:\n \n (a) NO KEY MAY EVER BE REQUIRED. `readOptionalBoolean` and `readOptionalPositiveInteger` are the\n * ONLY readers, and BOTH are optional-by-construction. There is no `readRequiredBoolean`, no\n * `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and were deleted; do not\n * reintroduce them under any name, in any type.\n * (b) AN UNKNOWN KEY IS IGNORED, never rejected. `warnUnknownKeys` warns; nothing throws.\n \n Both halves are needed, and either one alone still leaves a file that some installed release rejects:\n \n (a) covers the OLD FILE on a NEW release — a document written before a key existed, missing it.\n * (b) covers the NEW FILE on an OLD release — a document carrying a key that release never heard of.\n \n Break either one and every repo on the machine that is not on the newest release hard-blocks: a\n * rejection here fails config load, and that denies every tool call in that repo until somebody upgrades\n * all of them in lockstep. That is the outage this design exists to make impossible, and it is not\n * hypothetical — it is the shape of the incident recorded at the bottom of this docblock.\n \n `home-config.spec.ts` pins both halves, and pins them by ENUMERATING `ALLOWED_EXPERIMENTAL` rather\n * than by a hand-written list, so a key added later is covered by the invariant automatically instead of\n * silently escaping it.\n \n ─── PRESENT IS STRICT ABOUT WHAT IT UNDERSTANDS, AND FORWARD-COMPATIBLE ABOUT WHAT IT DOES NOT ───────\n * Once the bytes are readable, someone DELIBERATELY created this file, and three of the four failure\n * modes are REJECTED exactly as webpieces.config.json rejects them (see `retired-config-keys.ts`), with\n * an error naming the exact fix and no `??` fallback anywhere:\n \n UNPARSEABLE not JSON, or not a single JSON object → REJECT\n * RETIRED KEY listed in RETIRED_HOME_CONFIG_KEYS → REJECT, carrying the migration\n * WRONG TYPE a KNOWN key holding a value of the wrong type → REJECT\n * (a non-boolean for a boolean key; anything but a positive whole number for a\n * numeric one — see `readOptionalPositiveInteger`)\n * UNKNOWN KEY a key no version of this validator has heard of → IGNORED, with a warning\n \n ─── WHY THE LAST ROW DIFFERS FROM webpieces.config.json, WHICH STAYS STRICT ──────────────────────────\n * The difference is not a softening of policy; it is that the two files have different CARDINALITY.\n \n webpieces.config.json is REPO-TRACKED. One repo, one file, one pinned @webpieces release, and the\n * file moves through git in lockstep with the code that reads it. \"One version reads this document\" is\n * true by construction, so an unknown key there can only be a typo or a dead key — and rejecting it is\n * right, because it is the delivery mechanism for the migration.\n \n THIS file is MACHINE-GLOBAL. ONE document, read by EVERY repo on the machine, and those repos pin\n * DIFFERENT releases — deliberately, since a repo's pin is tracked and moves when its own PR lands.\n * So \"an unknown key\" here has a second, entirely legitimate cause that cannot occur in the repo file:\n * a key a NEWER release added, being read by an OLDER one. Rejecting it means adding any key to this\n * file hard-blocks every repo on the machine that has not yet been upgraded — an outage produced by\n * opting IN to an experimental flag, which is the same shape of failure that moved these flags out of\n * webpieces.config.json in the first place (see the section below).\n \n This is the exact mirror of the already-settled rule that no key here may be REQUIRED. Both halves fall\n * out of one fact: the set of valid documents must be non-empty for EVERY release on the machine at once.\n * • omit a new key → an old release must not demand it (already true: every key is optional)\n * • add a new key → an old release must not reject it (this change)\n * With only the first half, the set of valid files was still empty the moment a key was added.\n \n ─── WHAT THAT COSTS, AND WHAT PAYS FOR IT ────────────────────────────────────────────────────────────\n * The cost is real and worth stating plainly: a TYPO now silently does nothing. `\"whole-repo-build-gaurd\"`\n * used to be a loud rejection; it is now a key nothing reads, so the flag keeps its default and nothing\n * about the machine's behaviour reveals the mistake.\n \n Every key here is an OPT-IN that defaults OFF, so a typo costs the author the feature they meant to\n * switch on: misspell `whole-repo-build-guard` and the guard stays inert while they believe they armed\n * it. That is the milder of the two failures — nothing they were doing stops working — but it is still\n * invisible without a signal, which is why the warning below is not optional decoration, and why\n * `nearestKnownKey` had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a\n * transposition, exactly the class of typo an equality test cannot see.\n \n That is mitigated, not eliminated, by making the ignore VISIBLE: every unknown key is printed once per\n * load as a `[webpieces]` warning on stderr, and `nearestKnownKey` upgrades that line with a \"did you\n * mean\" whenever the key is within a two-character edit of a known one — which is what a typo is, and\n * what a key from a newer release is not. A warning naming a close match is the strongest signal\n * available that does not also block a colleague on an older pin.\n \n The trade was taken this way round because the two mistakes are not symmetric. A typo costs its author\n * one flag that did not turn on, discoverable the moment they check whether the feature is doing\n * anything, on their own machine. A rejection costs every repo on the machine every tool call, and the\n * person it blocks is usually not the person who edited the file.\n \n An unknown TOP-LEVEL key is ignored on the identical argument, and it is the more important half: a\n * future release adding a second section (`preferences`, say) beside `experimental` would otherwise be\n * unreadable by every older release on the machine, which is precisely the sequencing being deleted here.\n \n ─── REJECTING IS STILL SELF-RECOVERABLE, FOR THE THREE ROWS THAT STILL REJECT ────────────────────────\n * A Write/Edit targeting THIS path is an unconditional PASS in the hook guards (see `isHomeConfigPath`,\n * wired into ai-hook-rules' runner beside the webpieces.config.json pass), so an agent can always repair\n * the file the loader just rejected.\n \n ─── WHY A MACHINE-LOCAL SWITCH LIVES HERE AND NOT IN webpieces.config.json ───────────────────────────\n * `whole-repo-build-guard` first shipped as an ordinary validated guard: `mode: 'ON'` by default AND an\n * entry required under `hookGuards`. The consequence on upgrade was an outage — a consumer repo that had\n * not yet added the entry hit fault Y, which blocks EVERY Bash call, for a feature nobody had opted into.\n \n The rule that buys back: a switch that lives HERE needs no file, no key and no edit to be in its\n * default state. A repo-tracked config key cannot express that — an entry there is something every\n * consumer must add, on a schedule set by whoever bumps the release.\n \n Note which half of that was the outage. It was the REQUIRED KEY: the failure was at config LOAD,\n * before any command was judged. That is why every key here stays OPTIONAL and why an absent file\n * returns all-defaults silently.\n \n The DEFAULT is settled separately, by a standing policy this file does not get to re-litigate: EVERY\n * `experimental.` flag ships OFF and stays OFF for two years. `whole-repo-build-guard` is one of them,\n so it is OFF unless a machine writes `{\"experimental\": {\"whole-repo-build-guard\": true}}`. A flag that\n * defaults ON is not an experiment — it is a shipped behaviour that skipped its soak period, and it\n * changes what every agent on every machine can do the moment they upgrade. Low uptake of an opt-in\n * experiment is information ABOUT the experiment; it is not a licence to force it on everybody.\n /\nexport const HOME_CONFIG_DIR = '.webpieces';\nexport const HOME_CONFIG_FILE = 'config.json';\n\n// The `experimental` section and its keys. Named as constants because both the validator and its error\n// text must spell them identically — a validator whose message names a different key than the one it\n// checks is worse than no message.\nexport const HOME_EXPERIMENTAL_SECTION = 'experimental';\n// The on/off switch for `whole-repo-build-guard`. Spelled with the GUARD's own name, hyphens and all,\n// so `grep -rn whole-repo-build-guard` finds the switch beside the guard — and so nobody has to learn a\n// second name for one thing.\n//\n// `buildGateLogCapture` used to sit beside it and is GONE: capturing the build's output to a file is now\n// what the gate always does (see BuildAffected.runBuildGate), so the flag had nothing left to switch. It\n// is deliberately NOT in RETIRED_HOME_CONFIG_KEYS — a retired key here is a HARD FAILURE on exact match,\n// and this file is machine-global and hand-authored, so a machine that opted INTO a behaviour it now\n// gets unconditionally must not have its shell broken for saying yes early. It falls through to the\n// unknown-key WARNING instead, which says the key had no effect and names what is understood.\nexport const HOME_KEY_WHOLE_REPO_BUILD_GUARD = 'whole-repo-build-guard';\n// The on/off switch for the orphan-directory sweep `wp-checkout-clean-main` runs. Named for the thing\n// it switches, exactly as the guard key above is — one name, greppable from either end.\nexport const HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';\n/\n How many builds may be live on this machine before `pnpm wp-build` refuses to start another. The FIRST\n * NUMERIC key in this file — see `readOptionalPositiveInteger` for why \"known key, wrong type → REJECT\"\n * applies to it exactly as it applies to the booleans.\n /\nexport const HOME_KEY_MAX_CONCURRENT_BUILDS = 'maxConcurrentBuilds';\n\n/\n EVERY key's value when it is not named — including on the machine with no such file at all, which is\n * essentially every machine. False, for all of them, with no exceptions and no per-key table.\n \n That uniformity is the policy, not a coincidence: every `experimental.` flag ships OFF and stays OFF\n for two years, so \"this machine never opted in\" is byte-for-byte the behaviour of having no file. ON\n * requires an explicit `true`; absent, and an explicit `false`, are the same state.\n \n Named rather than written as a bare `false` at each call site so the reason travels with the value —\n * and there is deliberately exactly ONE such constant, because a second one would be a second place a\n * default is stated, free to disagree with this one.\n /\nconst GUARD_OFF_WHEN_ABSENT = false;\n\n/\n The one NON-boolean default, and the one key whose absent value is not `GUARD_OFF_WHEN_ABSENT`.\n \n Three, because contention between agents running full sweeps at once was measured at ~3.2x total test\n * time (CLAUDE.md § \"What actually makes builds slow\"), and a fourth simultaneous build is well past the\n * point where anybody gains anything. It is a NUMBER rather than an on/off flag because the useful\n * machine-to-machine difference here is core count, not opinion — which is also why it is the one key in\n * this file with a non-false default: \"0 builds allowed\" would be a machine that cannot build at all.\n /\nexport const DEFAULT_MAX_CONCURRENT_BUILDS = 3;\n\n/\n The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than\n * rejected (see the class docblock: this document is machine-global and older releases must survive\n * meeting a newer release's key), so adding a key still means adding it here — a key absent from these\n * lists is never read at all, and the flag it was meant to set keeps the default above.\n \n EXPORTED so `home-config.spec.ts` can ENUMERATE them rather than restate them. The cross-version\n * invariant (\"every key is independently omittable\") is only as good as the list the test walks, and a\n * hand-written copy of that list means a NEW key silently escapes the invariant on the day it is added —\n * which is the one failure mode nobody would notice until an older release started rejecting files.\n * Walking the real constant makes the test cover a new key the moment it appears here.\n /\n\n/\n The SETTINGS only. Documentation keys are deliberately NOT here: these lists are walked to build\n * sample documents and to assert cross-version invariants, and every entry is assumed to be a setting\n * with a typed value. `warnUnknownKeys` accepts the documentation keys separately, everywhere.\n /\nexport const ALLOWED_TOP_LEVEL: readonly string[] = [HOME_EXPERIMENTAL_SECTION];\n/\n The understood `experimental.` keys, SPLIT BY VALUE TYPE — because the spec walks these lists to build\n a sample document, and a sample that wrote `false` into a numeric key would be rejected by the very\n * loader it is testing. Splitting them means a key added to either list is covered by the cross-version\n * invariants automatically, with the right sample value, which is the whole reason the lists are exported.\n \n `ALLOWED_EXPERIMENTAL` stays the ONE list the validator warns against — derived from the two, never\n * hand-maintained beside them, so it cannot fall out of step.\n /\n/\n ─── ONLY A HUMAN ENDS AN EXPERIMENT ──────────────────────────────────────────────────────────────\n \n An AI agent may ADD a flag to these lists. It may NEVER DELETE one, and may never make a flagged\n * behaviour unconditional — however settled it looks, however old the flag is, however good the\n * reasoning. Ending an experiment judges evidence that lives on someone else's machine.\n \n From a live incident: PR #711 deleted `buildGateLogCapture` and made capture unconditional. Its\n * owner's config said `true`, and after that release the opt-in silently meant nothing. Note the\n * shape — that file says \"AI: DO NOT EDIT this file!!\", and the agent never touched it; it deleted\n * the key from the CODE, which has the identical effect from the owner's seat. A rule protecting a\n * FILE does not protect the SETTING it selects.\n \n If you believe an experiment should end, SAY SO and leave the flag alone. CLAUDE.md §\"ONLY A HUMAN\n * ENDS AN EXPERIMENT\" carries the full rule and what a human-ended retirement looks like.\n /\nexport const ALLOWED_EXPERIMENTAL_BOOLEANS: readonly string[] = [\n HOME_KEY_WHOLE_REPO_BUILD_GUARD, HOME_KEY_ORPHAN_DIR_SWEEP,\n];\nexport const ALLOWED_EXPERIMENTAL_NUMBERS: readonly string[] = [HOME_KEY_MAX_CONCURRENT_BUILDS];\nexport const ALLOWED_EXPERIMENTAL: readonly string[] = [\n ...ALLOWED_EXPERIMENTAL_BOOLEANS, ...ALLOWED_EXPERIMENTAL_NUMBERS,\n];\n\n/\n ─── EVERY KEY IS OPTIONAL, AND THAT IS A HARD REQUIREMENT OF WHERE THIS FILE LIVES ───────────────────\n * This file is MACHINE-GLOBAL: one document, read by every repo on the machine, and those repos pin\n * DIFFERENT webpieces releases. A REQUIRED key cannot survive that, because it makes the set of valid\n * files EMPTY:\n \n • omit the new key → the NEW release rejects the file (\"REQUIRED and not set\")\n * • add the new key → every OLDER release rejects the file (\"not a known key\")\n \n There is no third option, and both rejections block. `whole-repo-build-guard` was required for the\n * reason recorded in #627 — a flag that decides whether a command RUNS should not be inferred — and that\n * reasoning was sound for a single version and wrong for a shared file. It is optional now, along with\n * every other key.\n \n Absent then reads as the ONE declared default, `GUARD_OFF_WHEN_ABSENT`: false, for every key without\n * exception, which is byte-for-byte the behaviour of having no file at all.\n \n The other half of cross-version safety — an OLD release IGNORING a key a NEW one added, rather than\n * rejecting it — is solved by `warnUnknownKeys` below. The two halves are one invariant: for the set of\n * valid documents to be non-empty across every release installed on the machine, neither omitting a key\n * nor adding one may be an error.\n /\n\n// Read errors that mean \"the file is not there / not reachable\" rather than \"the file is wrong\". Every\n// one of these resolves to the all-defaults config, silently. Widened deliberately past ENOENT: the\n// parent `~/.webpieces` may not exist (ENOENT), may be a file (ENOTDIR), may be unreadable (EACCES /\n// EPERM), and the path itself may be a directory (EISDIR). None of those is a user who opted in.\nconst ABSENT_ERROR_CODES: readonly string[] = ['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM', 'EISDIR', 'ELOOP', 'ENAMETOOLONG'];\n\n/* The parsed `~/.webpieces/config.json`. Data-only (per CLAUDE.md — classes, not interfaces, for data). /\nexport class HomeConfig {\n /\n EXPERIMENTAL, and OFF unless this machine opts IN with an explicit `true`. When true,\n * `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and hands back\n * the repo's own scoped build command (`pnpm wp-build`). False — and absent, and no file at all —\n * makes the guard completely inert: no block, no log, no message.\n \n This is the guard's ONLY switch, and it is an OPT-IN. There is deliberately no\n * webpieces.config.json entry for it (see RETIRED_CONFIG_KEYS): a guard that every consumer must\n * ADD A KEY to avoid being blocked by is a guard that ships an outage on upgrade, which is exactly\n * what happened once. Living here means the default state needs no file, no key and no edit.\n /\n wholeRepoBuildGuard: boolean;\n\n /\n EXPERIMENTAL. When true, `wp-checkout-clean-main` ARCHIVES the orphan directories it finds — the\n * package directories left behind on every clone by an `nx g move`, which git cannot remove because\n * an ignored `dist/` or `node_modules/` survives the deletion of every tracked file under them.\n \n False — and the all-defaults value for a machine with no such file — means the sweep only REPORTS\n * what it found and moves nothing. That asymmetry is the point of shipping this behind the home\n * config at all: the author can run it live across their own clones for a release while every\n * colleague's repo is untouched, and neither state depends on a tracked key anybody must add.\n \n The sweep itself never deletes (see OrphanDirArchiver): directories move under `.webpieces/trash/`\n * with a printed `recover=`, so the worst case for a false positive is a `mv` somebody undoes. The\n * ARCHIVE is reaped after 30 days, which is a real deletion — of the second copy, on a timer long\n * enough that anything still wanted has been noticed.\n /\n orphanDirSweep: boolean;\n\n /\n How many builds may be live on this MACHINE before `pnpm wp-build` refuses to start another. Live\n * is counted from `~/.webpieces/builds.log` — see `builds-log.ts`, and\n * `decisions/0006-the-build-ledger-is-machine-global.md` for why that file lives outside any repo.\n \n `DEFAULT_MAX_CONCURRENT_BUILDS` when absent. The gate stages (`wp-review-upsert-pr`,\n * `wp-finish-upsert-pr`) are NEVER refused whatever this says — blocking the sanctioned path is how\n * you wedge a PR — though their builds do count toward what refuses an ad-hoc `wp-build`.\n /\n maxConcurrentBuilds: number;\n\n // ALL THREE required, no defaults. A defaulted parameter would leave `new HomeConfig(true)` compiling\n // after this class grew a second flag, silently meaning \"guard off\" — an old spelling that still\n // typechecks with a changed meaning is exactly the shim this repo does not ship. The 3-arg arity this\n // class had before `maxConcurrentBuilds` is DELETED rather than overloaded, per CLAUDE.md § \"NO\n // webpieces surface is released backwards-compatible\": the compile errors ARE the migration. The\n // absent-file state is constructed in exactly one place — load()'s absent-file branch.\n constructor(\n wholeRepoBuildGuard: boolean, orphanDirSweep: boolean, maxConcurrentBuilds: number,\n ) {\n this.wholeRepoBuildGuard = wholeRepoBuildGuard;\n this.orphanDirSweep = orphanDirSweep;\n this.maxConcurrentBuilds = maxConcurrentBuilds;\n }\n}\n\n\n/\n Loads and validates `~/.webpieces/config.json`, and resolves whether a path IS that file (for the\n * guard carve-out that keeps a rejection repairable).\n \n Strict about everything it UNDERSTANDS (a retired key, a known key of the wrong type, and a document\n * that is not JSON all throw); forward-compatible about everything it does not (an unknown key is\n * ignored with a warning). The class docblock at the top of this file has the reasoning.\n /\n@injectable(bindingScopeValues.Singleton)\nexport class HomeConfigService {\n constructor(private readonly docKeys: HomeDocKeys = new HomeDocKeys()) {}\n\n /* Absolute path to the preference file. `homeDir` is a parameter so specs never touch a real HOME. /\n configPath(homeDir: string = os.homedir()): string {\n return path.join(homeDir, HOME_CONFIG_DIR, HOME_CONFIG_FILE);\n }\n\n /\n The preferences. Returns all-defaults, silently and without touching anything, when the file is not\n * there. THROWS InformAiError, naming the fix, when a file that IS there is wrong in a way this\n * release can be sure about — unparseable, a RETIRED key, or a KNOWN key of the wrong type. A key it\n * simply does not recognise is ignored with a warning, because it may be a newer release's key and\n * this file is shared by every repo on the machine.\n /\n load(homeDir: string = os.homedir()): HomeConfig {\n const raw = this.readIfPresent(this.configPath(homeDir));\n // THE ABSENT-FILE STATE, and the ONE place it is constructed. Every flag is off — the same value\n // a present file that does not name the key gets, so \"no file\" and \"file that ignores this key\"\n // can never disagree. Spelled out rather than defaulted in the constructor — see the note there\n // on why a defaulted parameter is a shim.\n if (raw === null) {\n return new HomeConfig(\n GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, DEFAULT_MAX_CONCURRENT_BUILDS);\n }\n return this.validate(this.parse(raw, this.configPath(homeDir)), this.configPath(homeDir));\n }\n\n /\n True when `candidate` names `~/.webpieces/config.json`, in any of the forms an agent writes it:\n * an absolute path, a `~/`-prefixed path, or one still spelled `$HOME/…` / `${HOME}/…`.\n \n This is what the hook guards call to grant the file an unconditional Write/Edit PASS. Without it a\n * strict loader could reject the file while the guards blocked the edit that would fix it — the one\n * wedge webpieces.config.json is already immune to, and the reason its own carve-out exists.\n /\n isHomeConfigPath(candidate: string, homeDir: string = os.homedir()): boolean {\n if (candidate.trim() === '') return false;\n return path.resolve(this.expandHome(candidate.trim(), homeDir)) === path.resolve(this.configPath(homeDir));\n }\n\n // `~`, `$HOME` and `${HOME}` at the FRONT only — a home reference anywhere else is not a home path.\n private expandHome(candidate: string, homeDir: string): string {\n if (candidate === '~') return homeDir;\n for (const prefix of ['~/', '$HOME/', '${HOME}/']) {\n if (candidate.startsWith(prefix)) return path.join(homeDir, candidate.slice(prefix.length));\n }\n return candidate;\n }\n\n /\n The file's bytes, or null meaning \"no such file — the user did not opt in\".\n \n EVERY read failure is null. This is the single most important behaviour in the file: the absent\n * path is the path every consumer of these packages is on, and it may never reach an error branch.\n * An error code outside ABSENT_ERROR_CODES is genuinely exceptional (EIO, EBUSY) and is rethrown,\n * because silently disabling on a failing disk would be its own kind of lie.\n /\n private readIfPresent(file: string): string \| null {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: this catch IS the \"you have no such file\"\n // decision, and that decision may never surface as a failure to a user who never created the file\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n return fs.readFileSync(file, 'utf8');\n } catch (err: unknown) {\n const error = toError(err);\n if (this.isAbsent(error)) return null;\n throw error;\n }\n }\n\n private isAbsent(error: Error): boolean {\n // webpieces-disable no-any-unknown -- node attaches `code` to fs errors without typing it on Error\n const code = (error as unknown as Record<string, unknown>)['code'];\n return typeof code === 'string' && ABSENT_ERROR_CODES.includes(code);\n }\n\n // A readable file that is not a JSON object is a WRONG file, not an absent one — hence the throw.\n // webpieces-disable no-any-unknown -- an unvalidated user-authored document; every field is narrowed below\n private parse(raw: string, file: string): Record<string, unknown> {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: JSON.parse's own message is useless to an\n // agent on its own, so it is re-thrown as the InformAiError that names the file and the fix\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n // webpieces-disable no-any-unknown -- opaque parsed JSON, narrowed immediately below\n const parsed: unknown = JSON.parse(raw);\n if (typeof parsed !== 'object' \|\| parsed === null \|\| Array.isArray(parsed)) {\n throw new InformAiError(this.error(file, 'the file must contain a single JSON OBJECT, e.g. {}.'));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return parsed as Record<string, unknown>;\n } catch (err: unknown) {\n const error = toError(err);\n if (error instanceof InformAiError) throw error;\n throw new InformAiError(this.error(file, `the file is not valid JSON (${error.message}).`), { cause: error });\n }\n }\n\n // webpieces-disable no-any-unknown -- see parse(); the document is user-authored and unvalidated\n private validate(raw: Record<string, unknown>, file: string): HomeConfig {\n this.assertNotRetired(raw, file);\n this.docKeys.assertAreStrings(raw, '', (m: string): string => this.error(file, m));\n this.warnUnknownKeys(Object.keys(raw), ALLOWED_TOP_LEVEL, '');\n const section = raw[HOME_EXPERIMENTAL_SECTION];\n if (section !== undefined && (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section))) {\n throw new InformAiError(this.error(file, `\"${HOME_EXPERIMENTAL_SECTION}\" must be a JSON object.`));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n const experimental = (section ?? {}) as Record<string, unknown>;\n this.docKeys.assertAreStrings(experimental, `${HOME_EXPERIMENTAL_SECTION}.`,\n (m: string): string => this.error(file, m));\n this.warnUnknownKeys(Object.keys(experimental), ALLOWED_EXPERIMENTAL, `${HOME_EXPERIMENTAL_SECTION}.`);\n return new HomeConfig(\n this.readOptionalBoolean(experimental, HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalBoolean(experimental, HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalPositiveInteger(\n experimental, HOME_KEY_MAX_CONCURRENT_BUILDS, file, DEFAULT_MAX_CONCURRENT_BUILDS),\n );\n }\n\n /\n The NUMERIC sibling of {@link readOptionalBoolean}, and the same three rules apply unchanged: the\n * key is OPTIONAL (absent → `whenAbsent`, stated out loud by the caller), a PRESENT value of the\n * wrong type is an ERROR, and nothing here ever guesses.\n \n \"Wrong type\" is stricter than `typeof value === 'number'`, because for this key the wrong NUMBERS\n * are as meaningless as the wrong types: `0` is a machine that may never build, `-1` and `2.5` are\n * not counts of anything, and `NaN` compares false against every threshold and would silently\n * disable the check. A positive integer is the only value that means something, so it is the only\n * value accepted — and the rejection names the offending value, exactly as the boolean one does.\n \n This does NOT soften the machine-global forward-compatibility rule: an UNKNOWN key is still\n * ignored with a warning. Only a key THIS release understands is type-checked, and no release of\n * webpieces has ever given `maxConcurrentBuilds` a non-numeric meaning.\n /\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private readOptionalPositiveInteger(\n experimental: Record<string, unknown>, key: string, file: string, whenAbsent: number,\n ): number {\n const value = experimental[key];\n if (value === undefined) return whenAbsent;\n if (typeof value !== 'number' \|\| !Number.isInteger(value) \|\| value < 1) {\n throw new InformAiError(this.error(file,\n `\"${HOME_EXPERIMENTAL_SECTION}.${key}\" must be a POSITIVE WHOLE NUMBER (1 or more), not ` +\n `${JSON.stringify(value)}. Write it as a bare JSON number, e.g. ` +\n `\"${key}\": ${String(whenAbsent)} — or delete the key to use the default of ` +\n `${String(whenAbsent)}.`));\n }\n return value;\n }\n\n /\n An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing\n * `GUARD_OFF_WHEN_ABSENT` — an implicit \"absent means false\" buried in this method would put the\n * default and the key that carries it in different places, free to drift apart.\n \n A PRESENT key of the wrong type is still an ERROR, and that is the line neither the unknown-key change\n * nor this one moved: `\"whole-repo-build-guard\": \"yes\"` is a file somebody wrote wrongly, not\n * a file written for a different release. No release of webpieces has ever given this key a string\n * meaning, so there is no forward-compatibility story to protect and nothing is gained by guessing —\n * whereas guessing would turn a typed value into a silent fallback to the default, which is the very\n * cost the unknown-key warning exists to bound.\n \n This is the ONLY reader; see the every-key-is-optional note above for why there is no required\n * variant.\n /\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private readOptionalBoolean(\n experimental: Record<string, unknown>, key: string, file: string, whenAbsent: boolean,\n ): boolean {\n const value = experimental[key];\n if (value === undefined) return whenAbsent;\n return this.asBoolean(value, key, file, ' Remove the quotes, or delete the key.');\n }\n\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private asBoolean(value: unknown, key: string, file: string, fix: string): boolean {\n if (typeof value !== 'boolean') {\n throw new InformAiError(this.error(file,\n `\"${HOME_EXPERIMENTAL_SECTION}.${key}\" must be the boolean ` +\n `true or false, not ${JSON.stringify(value)}.${fix}`));\n }\n return value;\n }\n\n // Retired keys are checked BEFORE unknown-key reporting: \"unknown key\" would send an agent deleting a\n // key whose value it should be MOVING, which is the whole reason the retirement table exists.\n // webpieces-disable no-any-unknown -- see parse()\n private assertNotRetired(raw: Record<string, unknown>, file: string): void {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (!this.isPresentAt(raw, entry.key)) continue;\n const destination = entry.movedTo === ''\n ? 'It was removed with no replacement.'\n : `It moved to \"${entry.movedTo}\".`;\n throw new InformAiError(this.error(file,\n `\"${entry.key}\" is RETIRED. ${destination} ${entry.instruction}`));\n }\n }\n\n // Is `dotted` (one or two segments — the file is two levels deep by construction) actually present?\n // webpieces-disable no-any-unknown -- see parse()\n private isPresentAt(raw: Record<string, unknown>, dotted: string): boolean {\n const parts = dotted.split('.');\n if (parts.length === 1) return raw[parts[0]] !== undefined;\n const section = raw[parts[0]];\n if (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section)) return false;\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return (section as Record<string, unknown>)[parts[1]] !== undefined;\n }\n\n /\n The understood keys AT ONE LEVEL, rendered from the allow-list rather than hand-listed — and\n * rendered at the level the reader's key was actually found, so a mistyped SECTION is answered with\n * the sections and a mistyped FLAG with the flags. The hand-listed version named two keys and went\n * stale the moment a third arrived, telling an agent its brand-new key was not accepted while the\n * validator right above accepted it.\n /\n private quotedKeys(allowed: readonly string[], prefix: string): string {\n return allowed.map((key: string): string => `\"${prefix}${key}\"`).join(', ');\n }\n\n /\n An unknown key is IGNORED — see the class docblock for why this one file cannot reject it — but it\n * is never SILENT. The warning is the entire mitigation for the cost of ignoring, so it says both\n * things a reader needs: that the key did nothing, and what the understood keys are.\n \n ─── WHY THIS IS NOT THE \"console side channel\" SHAPE ────────────────────────────────────────────\n * That shape is a rule or a library reporting a FAILURE — or a cure for one — by printing it instead\n * of throwing a structured value to the one top-level handler. This is the opposite case, and the\n * distinction is the entire subject of this change: an unknown key here is NOT a failure. The load\n * SUCCEEDS, a valid HomeConfig is returned, every caller proceeds normally, and there is no cure the\n * reader is obliged to apply — a key from a newer release is a CORRECT file being read by an older\n * validator. There is no throw this could be, because throwing is precisely the behaviour being\n * deleted here; and returning it would mean inventing a warnings channel through `load()` that no\n * caller has any reason to render.\n \n stderr, not stdout, for the usual reason: this runs inside hooks whose stdout is a JSON decision\n * and inside `wp-` commands whose stdout is their real output, and neither may be polluted. It is\n the same channel, with the same `[webpieces]` prefix, that `state-dir-migration.announce` already\n * uses in this package for the same category of finding — something a human may want to know about\n * and is not required to act on.\n /\n /\n The sentence for a flag a HUMAN ended, or '' when this key is not one.\n \n Consulted BEFORE the retired-near-miss hint and before the generic \"typo or newer release\" line,\n * because for these keys that generic line is actively misleading: it invites the reader to check\n * their spelling or upgrade, when the truth is that they spelled it correctly, they are on a new\n * enough release, and the thing they asked for now happens anyway.\n /\n private endedExperimentHint(dotted: string): string {\n const ended = ENDED_EXPERIMENTS.find((e: EndedExperiment): boolean => e.key === dotted);\n if (ended === undefined) return '';\n return ` That experiment ENDED in @webpieces ${ended.endedIn}. ${ended.note}`;\n }\n\n private warnUnknownKeys(found: string[], allowed: readonly string[], prefix: string): void {\n // ACCEPTED everywhere, ADVERTISED nowhere. A documentation key is not a setting, so it is\n // skipped here rather than added to the allowed lists: those lists are walked elsewhere to build\n // typed sample documents, and listing `_doc` under \"Understood here\" — or offering it as the\n // nearest match to a misspelled setting — would send someone hunting for what it configures.\n // It configures nothing.\n for (const key of found) {\n if (allowed.includes(key) \|\| this.docKeys.isDocumentationKey(key)) continue;\n const near = this.nearestKnownKey(key, allowed);\n const guess = near !== ''\n ? ` Did you mean \"${prefix}${near}\"?`\n : this.endedExperimentHint(`${prefix}${key}`)\n \|\| this.nearRetiredHint(`${prefix}${key}`)\n \|\| ' If it is a typo, fix the spelling; if it is from a NEWER @webpieces than this repo pins, upgrade this repo to use it.';\n this.warn(\n `\"${prefix}${key}\" is not a key this @webpieces release understands, so it was IGNORED ` +\n `and had NO effect.${guess} Understood here: ${this.quotedKeys(allowed, prefix)}.`);\n }\n }\n\n /\n A near-miss of a RETIRED key, pointed at its migration — or '' when nothing retired is close.\n \n The gap this closes: `assertNotRetired` matches a retired key EXACTLY, so `captureBuildGateLog`\n * throws with its migration instruction while `captureBuildGateLogg` — one stray character away, and\n * a far likelier thing to type — falls through to the generic \"IGNORED, might be from a newer\n * release\" line. That is the least helpful of the three answers offered to the reader whose intent is the\n * clearest, so the retired table is consulted here too, at the same distance-2 threshold.\n \n It only ever produces a WARNING, never a throw: this release cannot know whether the reader meant\n * the retired key or a newer one, and guessing wrong in the throwing direction is what the whole\n * change is about. Known keys are matched first, so a typo of a LIVE key is never answered with a\n * dead one.\n /\n private nearRetiredHint(dottedKey: string): string {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (this.editDistance(dottedKey.toLowerCase(), entry.key.toLowerCase()) > 2) continue;\n const destination = entry.movedTo === ''\n ? 'it was removed with no replacement'\n : `it moved to \"${entry.movedTo}\"`;\n return ` Did you mean the RETIRED key \"${entry.key}\"? If so, ${destination}. ${entry.instruction}`;\n }\n return '';\n }\n\n // One shape for every non-fatal finding, matching state-dir-migration's `[webpieces] <what>:` prefix\n // so a reader can tell at a glance which subsystem is talking.\n private warn(message: string): void {\n process.stderr.write(`[webpieces] ~/.webpieces/config.json: ${message}\\n`);\n }\n\n /\n The closest understood key within two edits, or '' when nothing is close.\n \n This used to be a case-insensitive EQUALITY test, which was adequate while an unknown key was a\n * hard error — the error itself was the signal, and the suggestion only saved a reading. Now the\n * suggestion IS the signal, so it has to catch the typos an equality test misses: a doubled letter,\n * a dropped one, a transposition, a stray trailing character (`orphan-dir-sweeped`). Two is the\n * useful threshold — it covers every one of those and still refuses to guess for a genuinely new\n * key, which is the case that must NOT be dressed up as a typo.\n /\n private nearestKnownKey(key: string, allowed: readonly string[]): string {\n let best = '';\n let bestDistance = 3;\n for (const candidate of allowed) {\n const distance = this.editDistance(key.toLowerCase(), candidate.toLowerCase());\n if (distance >= bestDistance) continue;\n bestDistance = distance;\n best = candidate;\n }\n return best;\n }\n\n /* Ordinary Levenshtein distance, one row at a time — the key names are short and this runs once. */\n private editDistance(a: string, b: string): number {\n let previous: number[] = [];\n for (let j = 0; j <= b.length; j += 1) previous.push(j);\n for (let i = 1; i <= a.length; i += 1) {\n const current: number[] = [i];\n for (let j = 1; j <= b.length; j += 1) {\n const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);\n current.push(Math.min(substitution, previous[j] + 1, current[j - 1] + 1));\n }\n previous = current;\n }\n return previous[b.length];\n }\n\n // One shape for every rejection: what is wrong, in which file, and the fact that deleting the file is\n // always a legal fix — because the file is optional, and \"no file\" is a fully supported state.\n private error(file: string, detail: string): string {\n return `[~/.webpieces/config.json] ${detail}\\n\\n` +\n `File: ${file}\\n` +\n `This machine-local preference file is OPTIONAL and EXPERIMENTAL. Editing it is always ` +\n `permitted, even while it is invalid, and deleting it outright is a valid fix — with no such ` +\n `file every webpieces command behaves exactly as it does by default.`;\n }\n}\n"]}
1	+ {"version":3,"file":"home-config.js","sourceRoot":"","sources":["../../../../../packages/tooling/rules-config/src/home-config.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { injectable, bindingScopeValues } from 'inversify';\n\nimport { InformAiError } from './inform-ai-error';\nimport { toError } from './to-error';\nimport { DOCUMENTATION_KEYS, HOME_KEY_DOC, HOME_KEY_AI_DOC, HomeDocKeys } from './home-config-doc-keys';\nimport {\n RetiredHomeConfigKey, RETIRED_HOME_CONFIG_KEYS, EndedExperiment, ENDED_EXPERIMENTS,\n} from './home-config-retired-keys';\n\nexport { DOCUMENTATION_KEYS, HOME_KEY_DOC, HOME_KEY_AI_DOC, HomeDocKeys };\nexport { RetiredHomeConfigKey, RETIRED_HOME_CONFIG_KEYS, EndedExperiment, ENDED_EXPERIMENTS };\n\n/*\n `~/.webpieces/config.json` — the MACHINE-GLOBAL preference file, and a different thing from the repo's\n * tracked `webpieces.config.json`. It is EXPERIMENTAL and entirely OPTIONAL.\n \n ─── ABSENT IS THE NORMAL STATE, AND IT IS NEVER AN ERROR ─────────────────────────────────────────────\n * Essentially every consumer of these packages has no such file, and for them every `wp-` command must\n behave byte-for-byte as it did before this file was ever read: no error, no warning, no log line, no\n * extra file, nothing. `load()` therefore treats EVERY failure to READ the bytes — the file missing, the\n * `~/.webpieces` directory missing, a permission error, a path component that is not a directory — as\n * \"not opted in\", and returns all-defaults silently. That is not a fallback for a wrong shape; it is the\n * definition of \"the user did not create this file\".\n \n ─── THE STANDING RULE, FOR WHOEVER EDITS THIS FILE NEXT ──────────────────────────────────────────────\n * This file is MACHINE-GLOBAL: ONE document on the disk, read by EVERY repo on the machine, and those\n * repos are pinned to DIFFERENT webpieces releases. Two rules follow, and they are not negotiable:\n \n (a) NO KEY MAY EVER BE REQUIRED. `readOptionalBoolean` and `readOptionalPositiveInteger` are the\n * ONLY readers, and BOTH are optional-by-construction. There is no `readRequiredBoolean`, no\n * `RequiredHomeFlag`, no `REQUIRED_HOME_FLAGS` — those existed once and were deleted; do not\n * reintroduce them under any name, in any type.\n * (b) AN UNKNOWN KEY IS IGNORED, never rejected. `warnUnknownKeys` warns; nothing throws.\n \n Both halves are needed, and either one alone still leaves a file that some installed release rejects:\n \n (a) covers the OLD FILE on a NEW release — a document written before a key existed, missing it.\n * (b) covers the NEW FILE on an OLD release — a document carrying a key that release never heard of.\n \n Break either one and every repo on the machine that is not on the newest release hard-blocks: a\n * rejection here fails config load, and that denies every tool call in that repo until somebody upgrades\n * all of them in lockstep. That is the outage this design exists to make impossible, and it is not\n * hypothetical — it is the shape of the incident recorded at the bottom of this docblock.\n \n `home-config.spec.ts` pins both halves, and pins them by ENUMERATING `ALLOWED_EXPERIMENTAL` rather\n * than by a hand-written list, so a key added later is covered by the invariant automatically instead of\n * silently escaping it.\n \n ─── PRESENT IS STRICT ABOUT WHAT IT UNDERSTANDS, AND FORWARD-COMPATIBLE ABOUT WHAT IT DOES NOT ───────\n * Once the bytes are readable, someone DELIBERATELY created this file, and three of the four failure\n * modes are REJECTED exactly as webpieces.config.json rejects them (see `retired-config-keys.ts`), with\n * an error naming the exact fix and no `??` fallback anywhere:\n \n UNPARSEABLE not JSON, or not a single JSON object → REJECT\n * RETIRED KEY listed in RETIRED_HOME_CONFIG_KEYS → REJECT, carrying the migration\n * WRONG TYPE a KNOWN key holding a value of the wrong type → REJECT\n * (a non-boolean for a boolean key; anything but a positive whole number for a\n * numeric one — see `readOptionalPositiveInteger`)\n * UNKNOWN KEY a key no version of this validator has heard of → IGNORED, with a warning\n \n ─── WHY THE LAST ROW DIFFERS FROM webpieces.config.json, WHICH STAYS STRICT ──────────────────────────\n * The difference is not a softening of policy; it is that the two files have different CARDINALITY.\n \n webpieces.config.json is REPO-TRACKED. One repo, one file, one pinned @webpieces release, and the\n * file moves through git in lockstep with the code that reads it. \"One version reads this document\" is\n * true by construction, so an unknown key there can only be a typo or a dead key — and rejecting it is\n * right, because it is the delivery mechanism for the migration.\n \n THIS file is MACHINE-GLOBAL. ONE document, read by EVERY repo on the machine, and those repos pin\n * DIFFERENT releases — deliberately, since a repo's pin is tracked and moves when its own PR lands.\n * So \"an unknown key\" here has a second, entirely legitimate cause that cannot occur in the repo file:\n * a key a NEWER release added, being read by an OLDER one. Rejecting it means adding any key to this\n * file hard-blocks every repo on the machine that has not yet been upgraded — an outage produced by\n * opting IN to an experimental flag, which is the same shape of failure that moved these flags out of\n * webpieces.config.json in the first place (see the section below).\n \n This is the exact mirror of the already-settled rule that no key here may be REQUIRED. Both halves fall\n * out of one fact: the set of valid documents must be non-empty for EVERY release on the machine at once.\n * • omit a new key → an old release must not demand it (already true: every key is optional)\n * • add a new key → an old release must not reject it (this change)\n * With only the first half, the set of valid files was still empty the moment a key was added.\n \n ─── WHAT THAT COSTS, AND WHAT PAYS FOR IT ────────────────────────────────────────────────────────────\n * The cost is real and worth stating plainly: a TYPO now silently does nothing. `\"whole-repo-build-gaurd\"`\n * used to be a loud rejection; it is now a key nothing reads, so the flag keeps its default and nothing\n * about the machine's behaviour reveals the mistake.\n \n Every key here is an OPT-IN that defaults OFF, so a typo costs the author the feature they meant to\n * switch on: misspell `whole-repo-build-guard` and the guard stays inert while they believe they armed\n * it. That is the milder of the two failures — nothing they were doing stops working — but it is still\n * invisible without a signal, which is why the warning below is not optional decoration, and why\n * `nearestKnownKey` had to get fuzzier than the case-insensitive match it replaced: `gaurd` is a\n * transposition, exactly the class of typo an equality test cannot see.\n \n That is mitigated, not eliminated, by making the ignore VISIBLE: every unknown key is printed once per\n * load as a `[webpieces]` warning on stderr, and `nearestKnownKey` upgrades that line with a \"did you\n * mean\" whenever the key is within a two-character edit of a known one — which is what a typo is, and\n * what a key from a newer release is not. A warning naming a close match is the strongest signal\n * available that does not also block a colleague on an older pin.\n \n The trade was taken this way round because the two mistakes are not symmetric. A typo costs its author\n * one flag that did not turn on, discoverable the moment they check whether the feature is doing\n * anything, on their own machine. A rejection costs every repo on the machine every tool call, and the\n * person it blocks is usually not the person who edited the file.\n \n An unknown TOP-LEVEL key is ignored on the identical argument, and it is the more important half: a\n * future release adding a second section (`preferences`, say) beside `experimental` would otherwise be\n * unreadable by every older release on the machine, which is precisely the sequencing being deleted here.\n \n ─── REJECTING IS STILL SELF-RECOVERABLE, FOR THE THREE ROWS THAT STILL REJECT ────────────────────────\n * A Write/Edit targeting THIS path is an unconditional PASS in the hook guards (see `isHomeConfigPath`,\n * wired into ai-hook-rules' runner beside the webpieces.config.json pass), so an agent can always repair\n * the file the loader just rejected.\n \n ─── WHY A MACHINE-LOCAL SWITCH LIVES HERE AND NOT IN webpieces.config.json ───────────────────────────\n * `whole-repo-build-guard` first shipped as an ordinary validated guard: `mode: 'ON'` by default AND an\n * entry required under `hookGuards`. The consequence on upgrade was an outage — a consumer repo that had\n * not yet added the entry hit fault Y, which blocks EVERY Bash call, for a feature nobody had opted into.\n \n The rule that buys back: a switch that lives HERE needs no file, no key and no edit to be in its\n * default state. A repo-tracked config key cannot express that — an entry there is something every\n * consumer must add, on a schedule set by whoever bumps the release.\n \n Note which half of that was the outage. It was the REQUIRED KEY: the failure was at config LOAD,\n * before any command was judged. That is why every key here stays OPTIONAL and why an absent file\n * returns all-defaults silently.\n \n The DEFAULT is settled separately, by a standing policy this file does not get to re-litigate: EVERY\n * `experimental.` flag ships OFF and stays OFF for two years. `whole-repo-build-guard` is one of them,\n so it is OFF unless a machine writes `{\"experimental\": {\"whole-repo-build-guard\": true}}`. A flag that\n * defaults ON is not an experiment — it is a shipped behaviour that skipped its soak period, and it\n * changes what every agent on every machine can do the moment they upgrade. Low uptake of an opt-in\n * experiment is information ABOUT the experiment; it is not a licence to force it on everybody.\n /\nexport const HOME_CONFIG_DIR = '.webpieces';\nexport const HOME_CONFIG_FILE = 'config.json';\n\n// The `experimental` section and its keys. Named as constants because both the validator and its error\n// text must spell them identically — a validator whose message names a different key than the one it\n// checks is worse than no message.\nexport const HOME_EXPERIMENTAL_SECTION = 'experimental';\n// The on/off switch for `whole-repo-build-guard`. Spelled with the GUARD's own name, hyphens and all,\n// so `grep -rn whole-repo-build-guard` finds the switch beside the guard — and so nobody has to learn a\n// second name for one thing.\n//\n// `buildGateLogCapture` used to sit beside it and is GONE: capturing the build's output to a file is now\n// what the gate always does (see BuildAffected.runBuildGate), so the flag had nothing left to switch. It\n// is deliberately NOT in RETIRED_HOME_CONFIG_KEYS — a retired key here is a HARD FAILURE on exact match,\n// and this file is machine-global and hand-authored, so a machine that opted INTO a behaviour it now\n// gets unconditionally must not have its shell broken for saying yes early. It falls through to the\n// unknown-key WARNING instead, which says the key had no effect and names what is understood.\nexport const HOME_KEY_WHOLE_REPO_BUILD_GUARD = 'whole-repo-build-guard';\n// The on/off switch for the orphan-directory sweep `wp-sync-main` runs. Named for the thing\n// it switches, exactly as the guard key above is — one name, greppable from either end.\nexport const HOME_KEY_ORPHAN_DIR_SWEEP = 'orphan-dir-sweep';\n/\n How many builds may be live on this machine before `pnpm wp-build` refuses to start another. The FIRST\n * NUMERIC key in this file — see `readOptionalPositiveInteger` for why \"known key, wrong type → REJECT\"\n * applies to it exactly as it applies to the booleans.\n /\nexport const HOME_KEY_MAX_CONCURRENT_BUILDS = 'maxConcurrentBuilds';\n\n/\n EVERY key's value when it is not named — including on the machine with no such file at all, which is\n * essentially every machine. False, for all of them, with no exceptions and no per-key table.\n \n That uniformity is the policy, not a coincidence: every `experimental.` flag ships OFF and stays OFF\n for two years, so \"this machine never opted in\" is byte-for-byte the behaviour of having no file. ON\n * requires an explicit `true`; absent, and an explicit `false`, are the same state.\n \n Named rather than written as a bare `false` at each call site so the reason travels with the value —\n * and there is deliberately exactly ONE such constant, because a second one would be a second place a\n * default is stated, free to disagree with this one.\n /\nconst GUARD_OFF_WHEN_ABSENT = false;\n\n/\n The one NON-boolean default, and the one key whose absent value is not `GUARD_OFF_WHEN_ABSENT`.\n \n Three, because contention between agents running full sweeps at once was measured at ~3.2x total test\n * time (CLAUDE.md § \"What actually makes builds slow\"), and a fourth simultaneous build is well past the\n * point where anybody gains anything. It is a NUMBER rather than an on/off flag because the useful\n * machine-to-machine difference here is core count, not opinion — which is also why it is the one key in\n * this file with a non-false default: \"0 builds allowed\" would be a machine that cannot build at all.\n /\nexport const DEFAULT_MAX_CONCURRENT_BUILDS = 3;\n\n/\n The complete UNDERSTOOD shape. A key not on these lists is ignored with a warning rather than\n * rejected (see the class docblock: this document is machine-global and older releases must survive\n * meeting a newer release's key), so adding a key still means adding it here — a key absent from these\n * lists is never read at all, and the flag it was meant to set keeps the default above.\n \n EXPORTED so `home-config.spec.ts` can ENUMERATE them rather than restate them. The cross-version\n * invariant (\"every key is independently omittable\") is only as good as the list the test walks, and a\n * hand-written copy of that list means a NEW key silently escapes the invariant on the day it is added —\n * which is the one failure mode nobody would notice until an older release started rejecting files.\n * Walking the real constant makes the test cover a new key the moment it appears here.\n /\n\n/\n The SETTINGS only. Documentation keys are deliberately NOT here: these lists are walked to build\n * sample documents and to assert cross-version invariants, and every entry is assumed to be a setting\n * with a typed value. `warnUnknownKeys` accepts the documentation keys separately, everywhere.\n /\nexport const ALLOWED_TOP_LEVEL: readonly string[] = [HOME_EXPERIMENTAL_SECTION];\n/\n The understood `experimental.` keys, SPLIT BY VALUE TYPE — because the spec walks these lists to build\n a sample document, and a sample that wrote `false` into a numeric key would be rejected by the very\n * loader it is testing. Splitting them means a key added to either list is covered by the cross-version\n * invariants automatically, with the right sample value, which is the whole reason the lists are exported.\n \n `ALLOWED_EXPERIMENTAL` stays the ONE list the validator warns against — derived from the two, never\n * hand-maintained beside them, so it cannot fall out of step.\n /\n/\n ─── ONLY A HUMAN ENDS AN EXPERIMENT ──────────────────────────────────────────────────────────────\n \n An AI agent may ADD a flag to these lists. It may NEVER DELETE one, and may never make a flagged\n * behaviour unconditional — however settled it looks, however old the flag is, however good the\n * reasoning. Ending an experiment judges evidence that lives on someone else's machine.\n \n From a live incident: PR #711 deleted `buildGateLogCapture` and made capture unconditional. Its\n * owner's config said `true`, and after that release the opt-in silently meant nothing. Note the\n * shape — that file says \"AI: DO NOT EDIT this file!!\", and the agent never touched it; it deleted\n * the key from the CODE, which has the identical effect from the owner's seat. A rule protecting a\n * FILE does not protect the SETTING it selects.\n \n If you believe an experiment should end, SAY SO and leave the flag alone. CLAUDE.md §\"ONLY A HUMAN\n * ENDS AN EXPERIMENT\" carries the full rule and what a human-ended retirement looks like.\n /\nexport const ALLOWED_EXPERIMENTAL_BOOLEANS: readonly string[] = [\n HOME_KEY_WHOLE_REPO_BUILD_GUARD, HOME_KEY_ORPHAN_DIR_SWEEP,\n];\nexport const ALLOWED_EXPERIMENTAL_NUMBERS: readonly string[] = [HOME_KEY_MAX_CONCURRENT_BUILDS];\nexport const ALLOWED_EXPERIMENTAL: readonly string[] = [\n ...ALLOWED_EXPERIMENTAL_BOOLEANS, ...ALLOWED_EXPERIMENTAL_NUMBERS,\n];\n\n/\n ─── EVERY KEY IS OPTIONAL, AND THAT IS A HARD REQUIREMENT OF WHERE THIS FILE LIVES ───────────────────\n * This file is MACHINE-GLOBAL: one document, read by every repo on the machine, and those repos pin\n * DIFFERENT webpieces releases. A REQUIRED key cannot survive that, because it makes the set of valid\n * files EMPTY:\n \n • omit the new key → the NEW release rejects the file (\"REQUIRED and not set\")\n * • add the new key → every OLDER release rejects the file (\"not a known key\")\n \n There is no third option, and both rejections block. `whole-repo-build-guard` was required for the\n * reason recorded in #627 — a flag that decides whether a command RUNS should not be inferred — and that\n * reasoning was sound for a single version and wrong for a shared file. It is optional now, along with\n * every other key.\n \n Absent then reads as the ONE declared default, `GUARD_OFF_WHEN_ABSENT`: false, for every key without\n * exception, which is byte-for-byte the behaviour of having no file at all.\n \n The other half of cross-version safety — an OLD release IGNORING a key a NEW one added, rather than\n * rejecting it — is solved by `warnUnknownKeys` below. The two halves are one invariant: for the set of\n * valid documents to be non-empty across every release installed on the machine, neither omitting a key\n * nor adding one may be an error.\n /\n\n// Read errors that mean \"the file is not there / not reachable\" rather than \"the file is wrong\". Every\n// one of these resolves to the all-defaults config, silently. Widened deliberately past ENOENT: the\n// parent `~/.webpieces` may not exist (ENOENT), may be a file (ENOTDIR), may be unreadable (EACCES /\n// EPERM), and the path itself may be a directory (EISDIR). None of those is a user who opted in.\nconst ABSENT_ERROR_CODES: readonly string[] = ['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM', 'EISDIR', 'ELOOP', 'ENAMETOOLONG'];\n\n/* The parsed `~/.webpieces/config.json`. Data-only (per CLAUDE.md — classes, not interfaces, for data). /\nexport class HomeConfig {\n /\n EXPERIMENTAL, and OFF unless this machine opts IN with an explicit `true`. When true,\n * `whole-repo-build-guard` BLOCKS a Bash command that would build the WHOLE monorepo and hands back\n * the repo's own scoped build command (`pnpm wp-build`). False — and absent, and no file at all —\n * makes the guard completely inert: no block, no log, no message.\n \n This is the guard's ONLY switch, and it is an OPT-IN. There is deliberately no\n * webpieces.config.json entry for it (see RETIRED_CONFIG_KEYS): a guard that every consumer must\n * ADD A KEY to avoid being blocked by is a guard that ships an outage on upgrade, which is exactly\n * what happened once. Living here means the default state needs no file, no key and no edit.\n /\n wholeRepoBuildGuard: boolean;\n\n /\n EXPERIMENTAL. When true, `wp-sync-main` ARCHIVES the orphan directories it finds — the\n * package directories left behind on every clone by an `nx g move`, which git cannot remove because\n * an ignored `dist/` or `node_modules/` survives the deletion of every tracked file under them.\n \n False — and the all-defaults value for a machine with no such file — means the sweep only REPORTS\n * what it found and moves nothing. That asymmetry is the point of shipping this behind the home\n * config at all: the author can run it live across their own clones for a release while every\n * colleague's repo is untouched, and neither state depends on a tracked key anybody must add.\n \n The sweep itself never deletes (see OrphanDirArchiver): directories move under `.webpieces/trash/`\n * with a printed `recover=`, so the worst case for a false positive is a `mv` somebody undoes. The\n * ARCHIVE is reaped after 30 days, which is a real deletion — of the second copy, on a timer long\n * enough that anything still wanted has been noticed.\n /\n orphanDirSweep: boolean;\n\n /\n How many builds may be live on this MACHINE before `pnpm wp-build` refuses to start another. Live\n * is counted from `~/.webpieces/builds.log` — see `builds-log.ts`, and\n * `decisions/0006-the-build-ledger-is-machine-global.md` for why that file lives outside any repo.\n \n `DEFAULT_MAX_CONCURRENT_BUILDS` when absent. The gate stages (`wp-review-upsert-pr`,\n * `wp-finish-upsert-pr`) are NEVER refused whatever this says — blocking the sanctioned path is how\n * you wedge a PR — though their builds do count toward what refuses an ad-hoc `wp-build`.\n /\n maxConcurrentBuilds: number;\n\n // ALL THREE required, no defaults. A defaulted parameter would leave `new HomeConfig(true)` compiling\n // after this class grew a second flag, silently meaning \"guard off\" — an old spelling that still\n // typechecks with a changed meaning is exactly the shim this repo does not ship. The 3-arg arity this\n // class had before `maxConcurrentBuilds` is DELETED rather than overloaded, per CLAUDE.md § \"NO\n // webpieces surface is released backwards-compatible\": the compile errors ARE the migration. The\n // absent-file state is constructed in exactly one place — load()'s absent-file branch.\n constructor(\n wholeRepoBuildGuard: boolean, orphanDirSweep: boolean, maxConcurrentBuilds: number,\n ) {\n this.wholeRepoBuildGuard = wholeRepoBuildGuard;\n this.orphanDirSweep = orphanDirSweep;\n this.maxConcurrentBuilds = maxConcurrentBuilds;\n }\n}\n\n\n/\n Loads and validates `~/.webpieces/config.json`, and resolves whether a path IS that file (for the\n * guard carve-out that keeps a rejection repairable).\n \n Strict about everything it UNDERSTANDS (a retired key, a known key of the wrong type, and a document\n * that is not JSON all throw); forward-compatible about everything it does not (an unknown key is\n * ignored with a warning). The class docblock at the top of this file has the reasoning.\n /\n@injectable(bindingScopeValues.Singleton)\nexport class HomeConfigService {\n constructor(private readonly docKeys: HomeDocKeys = new HomeDocKeys()) {}\n\n /* Absolute path to the preference file. `homeDir` is a parameter so specs never touch a real HOME. /\n configPath(homeDir: string = os.homedir()): string {\n return path.join(homeDir, HOME_CONFIG_DIR, HOME_CONFIG_FILE);\n }\n\n /\n The preferences. Returns all-defaults, silently and without touching anything, when the file is not\n * there. THROWS InformAiError, naming the fix, when a file that IS there is wrong in a way this\n * release can be sure about — unparseable, a RETIRED key, or a KNOWN key of the wrong type. A key it\n * simply does not recognise is ignored with a warning, because it may be a newer release's key and\n * this file is shared by every repo on the machine.\n /\n load(homeDir: string = os.homedir()): HomeConfig {\n const raw = this.readIfPresent(this.configPath(homeDir));\n // THE ABSENT-FILE STATE, and the ONE place it is constructed. Every flag is off — the same value\n // a present file that does not name the key gets, so \"no file\" and \"file that ignores this key\"\n // can never disagree. Spelled out rather than defaulted in the constructor — see the note there\n // on why a defaulted parameter is a shim.\n if (raw === null) {\n return new HomeConfig(\n GUARD_OFF_WHEN_ABSENT, GUARD_OFF_WHEN_ABSENT, DEFAULT_MAX_CONCURRENT_BUILDS);\n }\n return this.validate(this.parse(raw, this.configPath(homeDir)), this.configPath(homeDir));\n }\n\n /\n True when `candidate` names `~/.webpieces/config.json`, in any of the forms an agent writes it:\n * an absolute path, a `~/`-prefixed path, or one still spelled `$HOME/…` / `${HOME}/…`.\n \n This is what the hook guards call to grant the file an unconditional Write/Edit PASS. Without it a\n * strict loader could reject the file while the guards blocked the edit that would fix it — the one\n * wedge webpieces.config.json is already immune to, and the reason its own carve-out exists.\n /\n isHomeConfigPath(candidate: string, homeDir: string = os.homedir()): boolean {\n if (candidate.trim() === '') return false;\n return path.resolve(this.expandHome(candidate.trim(), homeDir)) === path.resolve(this.configPath(homeDir));\n }\n\n // `~`, `$HOME` and `${HOME}` at the FRONT only — a home reference anywhere else is not a home path.\n private expandHome(candidate: string, homeDir: string): string {\n if (candidate === '~') return homeDir;\n for (const prefix of ['~/', '$HOME/', '${HOME}/']) {\n if (candidate.startsWith(prefix)) return path.join(homeDir, candidate.slice(prefix.length));\n }\n return candidate;\n }\n\n /\n The file's bytes, or null meaning \"no such file — the user did not opt in\".\n \n EVERY read failure is null. This is the single most important behaviour in the file: the absent\n * path is the path every consumer of these packages is on, and it may never reach an error branch.\n * An error code outside ABSENT_ERROR_CODES is genuinely exceptional (EIO, EBUSY) and is rethrown,\n * because silently disabling on a failing disk would be its own kind of lie.\n /\n private readIfPresent(file: string): string \| null {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: this catch IS the \"you have no such file\"\n // decision, and that decision may never surface as a failure to a user who never created the file\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n return fs.readFileSync(file, 'utf8');\n } catch (err: unknown) {\n const error = toError(err);\n if (this.isAbsent(error)) return null;\n throw error;\n }\n }\n\n private isAbsent(error: Error): boolean {\n // webpieces-disable no-any-unknown -- node attaches `code` to fs errors without typing it on Error\n const code = (error as unknown as Record<string, unknown>)['code'];\n return typeof code === 'string' && ABSENT_ERROR_CODES.includes(code);\n }\n\n // A readable file that is not a JSON object is a WRONG file, not an absent one — hence the throw.\n // webpieces-disable no-any-unknown -- an unvalidated user-authored document; every field is narrowed below\n private parse(raw: string, file: string): Record<string, unknown> {\n // webpieces-disable no-unmanaged-exceptions -- chokepoint: JSON.parse's own message is useless to an\n // agent on its own, so it is re-thrown as the InformAiError that names the file and the fix\n // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n try {\n // webpieces-disable no-any-unknown -- opaque parsed JSON, narrowed immediately below\n const parsed: unknown = JSON.parse(raw);\n if (typeof parsed !== 'object' \|\| parsed === null \|\| Array.isArray(parsed)) {\n throw new InformAiError(this.error(file, 'the file must contain a single JSON OBJECT, e.g. {}.'));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return parsed as Record<string, unknown>;\n } catch (err: unknown) {\n const error = toError(err);\n if (error instanceof InformAiError) throw error;\n throw new InformAiError(this.error(file, `the file is not valid JSON (${error.message}).`), { cause: error });\n }\n }\n\n // webpieces-disable no-any-unknown -- see parse(); the document is user-authored and unvalidated\n private validate(raw: Record<string, unknown>, file: string): HomeConfig {\n this.assertNotRetired(raw, file);\n this.docKeys.assertAreStrings(raw, '', (m: string): string => this.error(file, m));\n this.warnUnknownKeys(Object.keys(raw), ALLOWED_TOP_LEVEL, '');\n const section = raw[HOME_EXPERIMENTAL_SECTION];\n if (section !== undefined && (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section))) {\n throw new InformAiError(this.error(file, `\"${HOME_EXPERIMENTAL_SECTION}\" must be a JSON object.`));\n }\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n const experimental = (section ?? {}) as Record<string, unknown>;\n this.docKeys.assertAreStrings(experimental, `${HOME_EXPERIMENTAL_SECTION}.`,\n (m: string): string => this.error(file, m));\n this.warnUnknownKeys(Object.keys(experimental), ALLOWED_EXPERIMENTAL, `${HOME_EXPERIMENTAL_SECTION}.`);\n return new HomeConfig(\n this.readOptionalBoolean(experimental, HOME_KEY_WHOLE_REPO_BUILD_GUARD, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalBoolean(experimental, HOME_KEY_ORPHAN_DIR_SWEEP, file, GUARD_OFF_WHEN_ABSENT),\n this.readOptionalPositiveInteger(\n experimental, HOME_KEY_MAX_CONCURRENT_BUILDS, file, DEFAULT_MAX_CONCURRENT_BUILDS),\n );\n }\n\n /\n The NUMERIC sibling of {@link readOptionalBoolean}, and the same three rules apply unchanged: the\n * key is OPTIONAL (absent → `whenAbsent`, stated out loud by the caller), a PRESENT value of the\n * wrong type is an ERROR, and nothing here ever guesses.\n \n \"Wrong type\" is stricter than `typeof value === 'number'`, because for this key the wrong NUMBERS\n * are as meaningless as the wrong types: `0` is a machine that may never build, `-1` and `2.5` are\n * not counts of anything, and `NaN` compares false against every threshold and would silently\n * disable the check. A positive integer is the only value that means something, so it is the only\n * value accepted — and the rejection names the offending value, exactly as the boolean one does.\n \n This does NOT soften the machine-global forward-compatibility rule: an UNKNOWN key is still\n * ignored with a warning. Only a key THIS release understands is type-checked, and no release of\n * webpieces has ever given `maxConcurrentBuilds` a non-numeric meaning.\n /\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private readOptionalPositiveInteger(\n experimental: Record<string, unknown>, key: string, file: string, whenAbsent: number,\n ): number {\n const value = experimental[key];\n if (value === undefined) return whenAbsent;\n if (typeof value !== 'number' \|\| !Number.isInteger(value) \|\| value < 1) {\n throw new InformAiError(this.error(file,\n `\"${HOME_EXPERIMENTAL_SECTION}.${key}\" must be a POSITIVE WHOLE NUMBER (1 or more), not ` +\n `${JSON.stringify(value)}. Write it as a bare JSON number, e.g. ` +\n `\"${key}\": ${String(whenAbsent)} — or delete the key to use the default of ` +\n `${String(whenAbsent)}.`));\n }\n return value;\n }\n\n /\n An absent key falls back to `whenAbsent`, which every caller states OUT LOUD by passing\n * `GUARD_OFF_WHEN_ABSENT` — an implicit \"absent means false\" buried in this method would put the\n * default and the key that carries it in different places, free to drift apart.\n \n A PRESENT key of the wrong type is still an ERROR, and that is the line neither the unknown-key change\n * nor this one moved: `\"whole-repo-build-guard\": \"yes\"` is a file somebody wrote wrongly, not\n * a file written for a different release. No release of webpieces has ever given this key a string\n * meaning, so there is no forward-compatibility story to protect and nothing is gained by guessing —\n * whereas guessing would turn a typed value into a silent fallback to the default, which is the very\n * cost the unknown-key warning exists to bound.\n \n This is the ONLY reader; see the every-key-is-optional note above for why there is no required\n * variant.\n /\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private readOptionalBoolean(\n experimental: Record<string, unknown>, key: string, file: string, whenAbsent: boolean,\n ): boolean {\n const value = experimental[key];\n if (value === undefined) return whenAbsent;\n return this.asBoolean(value, key, file, ' Remove the quotes, or delete the key.');\n }\n\n // webpieces-disable no-any-unknown -- see parse()\n // eslint-disable-next-line @typescript-eslint/max-params\n private asBoolean(value: unknown, key: string, file: string, fix: string): boolean {\n if (typeof value !== 'boolean') {\n throw new InformAiError(this.error(file,\n `\"${HOME_EXPERIMENTAL_SECTION}.${key}\" must be the boolean ` +\n `true or false, not ${JSON.stringify(value)}.${fix}`));\n }\n return value;\n }\n\n // Retired keys are checked BEFORE unknown-key reporting: \"unknown key\" would send an agent deleting a\n // key whose value it should be MOVING, which is the whole reason the retirement table exists.\n // webpieces-disable no-any-unknown -- see parse()\n private assertNotRetired(raw: Record<string, unknown>, file: string): void {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (!this.isPresentAt(raw, entry.key)) continue;\n const destination = entry.movedTo === ''\n ? 'It was removed with no replacement.'\n : `It moved to \"${entry.movedTo}\".`;\n throw new InformAiError(this.error(file,\n `\"${entry.key}\" is RETIRED. ${destination} ${entry.instruction}`));\n }\n }\n\n // Is `dotted` (one or two segments — the file is two levels deep by construction) actually present?\n // webpieces-disable no-any-unknown -- see parse()\n private isPresentAt(raw: Record<string, unknown>, dotted: string): boolean {\n const parts = dotted.split('.');\n if (parts.length === 1) return raw[parts[0]] !== undefined;\n const section = raw[parts[0]];\n if (typeof section !== 'object' \|\| section === null \|\| Array.isArray(section)) return false;\n // webpieces-disable no-any-unknown -- narrowed to a non-null, non-array object one line above\n return (section as Record<string, unknown>)[parts[1]] !== undefined;\n }\n\n /\n The understood keys AT ONE LEVEL, rendered from the allow-list rather than hand-listed — and\n * rendered at the level the reader's key was actually found, so a mistyped SECTION is answered with\n * the sections and a mistyped FLAG with the flags. The hand-listed version named two keys and went\n * stale the moment a third arrived, telling an agent its brand-new key was not accepted while the\n * validator right above accepted it.\n /\n private quotedKeys(allowed: readonly string[], prefix: string): string {\n return allowed.map((key: string): string => `\"${prefix}${key}\"`).join(', ');\n }\n\n /\n An unknown key is IGNORED — see the class docblock for why this one file cannot reject it — but it\n * is never SILENT. The warning is the entire mitigation for the cost of ignoring, so it says both\n * things a reader needs: that the key did nothing, and what the understood keys are.\n \n ─── WHY THIS IS NOT THE \"console side channel\" SHAPE ────────────────────────────────────────────\n * That shape is a rule or a library reporting a FAILURE — or a cure for one — by printing it instead\n * of throwing a structured value to the one top-level handler. This is the opposite case, and the\n * distinction is the entire subject of this change: an unknown key here is NOT a failure. The load\n * SUCCEEDS, a valid HomeConfig is returned, every caller proceeds normally, and there is no cure the\n * reader is obliged to apply — a key from a newer release is a CORRECT file being read by an older\n * validator. There is no throw this could be, because throwing is precisely the behaviour being\n * deleted here; and returning it would mean inventing a warnings channel through `load()` that no\n * caller has any reason to render.\n \n stderr, not stdout, for the usual reason: this runs inside hooks whose stdout is a JSON decision\n * and inside `wp-` commands whose stdout is their real output, and neither may be polluted. It is\n the same channel, with the same `[webpieces]` prefix, that `state-dir-migration.announce` already\n * uses in this package for the same category of finding — something a human may want to know about\n * and is not required to act on.\n /\n /\n The sentence for a flag a HUMAN ended, or '' when this key is not one.\n \n Consulted BEFORE the retired-near-miss hint and before the generic \"typo or newer release\" line,\n * because for these keys that generic line is actively misleading: it invites the reader to check\n * their spelling or upgrade, when the truth is that they spelled it correctly, they are on a new\n * enough release, and the thing they asked for now happens anyway.\n /\n private endedExperimentHint(dotted: string): string {\n const ended = ENDED_EXPERIMENTS.find((e: EndedExperiment): boolean => e.key === dotted);\n if (ended === undefined) return '';\n return ` That experiment ENDED in @webpieces ${ended.endedIn}. ${ended.note}`;\n }\n\n private warnUnknownKeys(found: string[], allowed: readonly string[], prefix: string): void {\n // ACCEPTED everywhere, ADVERTISED nowhere. A documentation key is not a setting, so it is\n // skipped here rather than added to the allowed lists: those lists are walked elsewhere to build\n // typed sample documents, and listing `_doc` under \"Understood here\" — or offering it as the\n // nearest match to a misspelled setting — would send someone hunting for what it configures.\n // It configures nothing.\n for (const key of found) {\n if (allowed.includes(key) \|\| this.docKeys.isDocumentationKey(key)) continue;\n const near = this.nearestKnownKey(key, allowed);\n const guess = near !== ''\n ? ` Did you mean \"${prefix}${near}\"?`\n : this.endedExperimentHint(`${prefix}${key}`)\n \|\| this.nearRetiredHint(`${prefix}${key}`)\n \|\| ' If it is a typo, fix the spelling; if it is from a NEWER @webpieces than this repo pins, upgrade this repo to use it.';\n this.warn(\n `\"${prefix}${key}\" is not a key this @webpieces release understands, so it was IGNORED ` +\n `and had NO effect.${guess} Understood here: ${this.quotedKeys(allowed, prefix)}.`);\n }\n }\n\n /\n A near-miss of a RETIRED key, pointed at its migration — or '' when nothing retired is close.\n \n The gap this closes: `assertNotRetired` matches a retired key EXACTLY, so `captureBuildGateLog`\n * throws with its migration instruction while `captureBuildGateLogg` — one stray character away, and\n * a far likelier thing to type — falls through to the generic \"IGNORED, might be from a newer\n * release\" line. That is the least helpful of the three answers offered to the reader whose intent is the\n * clearest, so the retired table is consulted here too, at the same distance-2 threshold.\n \n It only ever produces a WARNING, never a throw: this release cannot know whether the reader meant\n * the retired key or a newer one, and guessing wrong in the throwing direction is what the whole\n * change is about. Known keys are matched first, so a typo of a LIVE key is never answered with a\n * dead one.\n /\n private nearRetiredHint(dottedKey: string): string {\n for (const entry of RETIRED_HOME_CONFIG_KEYS) {\n if (this.editDistance(dottedKey.toLowerCase(), entry.key.toLowerCase()) > 2) continue;\n const destination = entry.movedTo === ''\n ? 'it was removed with no replacement'\n : `it moved to \"${entry.movedTo}\"`;\n return ` Did you mean the RETIRED key \"${entry.key}\"? If so, ${destination}. ${entry.instruction}`;\n }\n return '';\n }\n\n // One shape for every non-fatal finding, matching state-dir-migration's `[webpieces] <what>:` prefix\n // so a reader can tell at a glance which subsystem is talking.\n private warn(message: string): void {\n process.stderr.write(`[webpieces] ~/.webpieces/config.json: ${message}\\n`);\n }\n\n /\n The closest understood key within two edits, or '' when nothing is close.\n \n This used to be a case-insensitive EQUALITY test, which was adequate while an unknown key was a\n * hard error — the error itself was the signal, and the suggestion only saved a reading. Now the\n * suggestion IS the signal, so it has to catch the typos an equality test misses: a doubled letter,\n * a dropped one, a transposition, a stray trailing character (`orphan-dir-sweeped`). Two is the\n * useful threshold — it covers every one of those and still refuses to guess for a genuinely new\n * key, which is the case that must NOT be dressed up as a typo.\n /\n private nearestKnownKey(key: string, allowed: readonly string[]): string {\n let best = '';\n let bestDistance = 3;\n for (const candidate of allowed) {\n const distance = this.editDistance(key.toLowerCase(), candidate.toLowerCase());\n if (distance >= bestDistance) continue;\n bestDistance = distance;\n best = candidate;\n }\n return best;\n }\n\n /* Ordinary Levenshtein distance, one row at a time — the key names are short and this runs once. */\n private editDistance(a: string, b: string): number {\n let previous: number[] = [];\n for (let j = 0; j <= b.length; j += 1) previous.push(j);\n for (let i = 1; i <= a.length; i += 1) {\n const current: number[] = [i];\n for (let j = 1; j <= b.length; j += 1) {\n const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);\n current.push(Math.min(substitution, previous[j] + 1, current[j - 1] + 1));\n }\n previous = current;\n }\n return previous[b.length];\n }\n\n // One shape for every rejection: what is wrong, in which file, and the fact that deleting the file is\n // always a legal fix — because the file is optional, and \"no file\" is a fully supported state.\n private error(file: string, detail: string): string {\n return `[~/.webpieces/config.json] ${detail}\\n\\n` +\n `File: ${file}\\n` +\n `This machine-local preference file is OPTIONAL and EXPERIMENTAL. Editing it is always ` +\n `permitted, even while it is invalid, and deleting it outright is a valid fix — with no such ` +\n `file every webpieces command behaves exactly as it does by default.`;\n }\n}\n"]}

package/templates/webpieces.branch-state-matrix.md CHANGED Viewed

@@ -36,7 +36,7 @@ on its own cure.
 **What is gated is WHEN that polarity applies, not the polarity.** stale-main asks the cache
 whether local `main` is BEHIND (rows 6/7) and default-denies only then; a current `main` — which is
-exactly where `pnpm wp-checkout-clean-main` leaves you — is not this guard's business at all.
+exactly where `pnpm wp-sync-main` leaves you — is not this guard's business at all.
 They remain separate CLASSES because the states they detect are different — one reads the branch
 name, the other the cached merged flag — and because each carries its own message.
@@ -69,14 +69,14 @@ guards, meant at most one of the four values could ever reach a spawn.
 | # | tools | state | act | cure |
 |---|---|---|---|---|
 | 1 | `B R E` | on the **global allowlist** (inert command, or a universal cure such as reading/editing `webpieces.config.json`) | 1 allow | — |
-| 2 | `B` | bare `git checkout main`, with no `git pull` chained into the same command | 4 block | `pnpm wp-checkout-clean-main` |
+| 2 | `B` | bare `git checkout main`, with no `git pull` chained into the same command | 4 block | `pnpm wp-sync-main` |
 | 3 | `B R E` | **merge in progress** — L4 owns this state | 2 exempt | finish the merge: `pnpm wp-finish-upsert-pr` |
 | 4 | `B` | on the **skip list** — it gets you OUT, or tells you where you are | 1 allow | — |
 | 5 | `E` | on `main` | 4 block | `git checkout -b <new> origin/main` |
 | 11 | `B R E` | **the state could not be established** — branch undeterminable, no cache yet, the cache holds another branch, `origin/main` unknown, or the forge unreachable | 1 allow (fail-open) | — (nothing to fix; the refresher populates the cache for the next call) |
 | 12 | `B` | on `main`, behind `origin/main`, and the command STARTS with a refresh-main cure joined to the work by `&&` | 1 allow | — |
-| 13 | `B` | on `main`, behind `origin/main`, and the cure is joined to the work by `;` (or `||`, `&`, a newline) — the work runs even if the cure fails | 4 block | `pnpm wp-checkout-clean-main && <your command>` |
-| 6 | `B R` | on `main`, behind `origin/main` | 4 block | `pnpm wp-checkout-clean-main`, or `git checkout -b <new> origin/main` |
+| 13 | `B` | on `main`, behind `origin/main`, and the cure is joined to the work by `;` (or `||`, `&`, a newline) — the work runs even if the cure fails | 4 block | `pnpm wp-sync-main && <your command>` |
+| 6 | `B R` | on `main`, behind `origin/main` | 4 block | `pnpm wp-sync-main`, or `git checkout -b <new> origin/main` |
 | 7 | `B R` | on `main`, current | 1 allow | — |
 | 8 | `B R E` | on a branch whose PR is **already merged** | 4 block | `git fetch origin main && git checkout -b <new> origin/main` |
 | 9 | `B R E` | no fork point with `origin/main`, or `origin/main` moved and collided with your files | 4 block | `pnpm wp-start-update`, or `pnpm wp-start-upsert-pr` when a PR is open |
@@ -98,7 +98,7 @@ would silently re-point every reference. L1 does the same with its row 8.
 The hazards differ. A WRITE on `main` lands work somewhere unreviewable and unrevertable at ANY
 freshness, so row 5 is `E` only and is judged from the branch alone, above the cache divider. A
 READ or a BUILD on a CURRENT `main` harms nothing, and blocking it strands the agent immediately
-after `pnpm wp-checkout-clean-main` — the command this repo prescribes — put it there. So `B` joins
+after `pnpm wp-sync-main` — the command this repo prescribes — put it there. So `B` joins
 `R` on the freshness-gated pair: row 6 (behind) blocks, row 7 (current) allows, and "cannot tell"
 fails open at row 11 by construction.
@@ -142,7 +142,7 @@ valve in the code either** — both were closed, and "Not done" is empty as a re
 ### Rows 12 and 13 — the cure may be COMPOSED with the work, but only with `&&`
-`pnpm wp-checkout-clean-main && cat src/app.ts` is ALLOWED. `pnpm wp-checkout-clean-main ; cat
+`pnpm wp-sync-main && cat src/app.ts` is ALLOWED. `pnpm wp-sync-main ; cat
 src/app.ts` is REFUSED, and the refusal names the operator you typed.
 The difference belongs to the shell, not to this guard. `&&` short-circuits: the work cannot run
@@ -173,7 +173,7 @@ under. So a case whose row is wrong fails the build rather than misinforming a r
 |---|---|---|---|---|
 | 1 | You are blocked by some other L2 row, and need to turn the policy off to get anything done | any state — this row is ahead of every block | ALLOW: reading and editing `webpieces.config.json` is never blocked, so the mode-OFF cure is always reachable | Edit `webpieces.config.json` → `hookGuards` → `branch-state-guard` → `"mode": "OFF"` |
 | 2 | A Write to `webpieces.config.json` while on `main`, which row 5 would otherwise block | on `main`, editing the one file that can disable the guard | ALLOW: the hook adapter bypasses feature-branch-guard for this path before any guard runs | None needed — the edit proceeds |
-| 3 | `git checkout main` after a merge, to start the next piece of work | about to land on whatever local `main` you last had — 157 commits behind, in the incident | BLOCK: decided from command TEXT alone, before the checkout, because the only `main` this could measure is the one it is about to leave | `pnpm wp-checkout-clean-main` — checkout, pull, reap dead branches/worktrees, sweep orphan directories, in one command (hand-rolled, the pull must be in the SAME command as the checkout) |
+| 3 | `git checkout main` after a merge, to start the next piece of work | about to land on whatever local `main` you last had — 157 commits behind, in the incident | BLOCK: decided from command TEXT alone, before the checkout, because the only `main` this could measure is the one it is about to leave | `pnpm wp-sync-main` — checkout, pull, reap dead branches/worktrees, sweep orphan directories, in one command (hand-rolled, the pull must be in the SAME command as the checkout) |
 | 4 | The same command inside a linked worktree, where `git checkout main` fatals anyway | linked worktree — `main` is already checked out in the primary clone | BLOCK, and the message prints the worktree form rather than a cure git would refuse | `git fetch origin main`, then work off `origin/main` |
 | 5 | Reading and editing conflicted files during a 3-point merge, on a branch row 9 would block | merge markers on disk — `pnpm wp-start-update` has run and not finished | EXEMPT: everything is permitted, which is exactly what lets row 9 be strict | Resolve the conflicts, then `pnpm wp-finish-upsert-pr` |
 | 6 | `git status` / `gh pr view` while blocked, to work out where you are | any state — orientation is never "working here" | ALLOW: metadata tells you where you are without putting stale file CONTENT in context | None needed |
@@ -187,13 +187,13 @@ under. So a case whose row is wrong fails the build rather than misinforming a r
 | 27 | A build, a `cat` or a `curl` on `main`, on the first Bash call of a session | on `main`, cache absent — so whether `main` is behind is UNKNOWN | ALLOW (fail-open), logged `ALLOW_FAIL_OPEN`. `B` on `main` is judged by rows 6/7 and therefore lands here when the cache cannot answer; the WRITE half is not, which is why row 5 sits above this divider | None — the second call is judged normally |
 | 14 | Mid-rebase, every guard abstains | detached HEAD — there is no branch name to judge | ALLOW (fail-open), logged LOUDLY when the branch is unresolvable rather than merely detached | None — finish or abort the rebase |
 | 29 | `git fetch --prune origin main -q && git pull --ff-only origin main 2>&1 | tail -1 && sed -n '30,75p' src/app.ts` — the agent cures and reads in one call | on `main`, behind `origin/main`, cure first, `&&` between | ALLOW: `&&` short-circuits, so the `sed` never runs if the pull fails — the guard was refusing a safety property the shell already enforces. Measured fleet-wide as `cure_bundled_and`, and filed as a TOOLING defect, not an agent one | None needed |
-| 30 | `pnpm wp-checkout-clean-main >/dev/null 2>&1; git log --oneline -1; sed -n '598,612p' eslint.config.mjs` — and the agent then quotes an eslint rule out of a file 15 commits stale | on `main`, behind `origin/main`, cure first, `;` between | BLOCK: `;` discards the cure's exit code, so a conflict, a dirty tree or no network leaves the `sed` reading still-stale content — and 7 of the 9 observed cases also silenced the cure with `>/dev/null 2>&1`, so the failure was invisible too. The two-step is safer because the NEXT tool call re-computes `localMain` against `originMain`, so a failed pull re-blocks; an allowed `;` compound never gets that second look | Swap the `;` for `&&` — `pnpm wp-checkout-clean-main && <your command>` — or run the cure alone and re-issue the command in the next call |
+| 30 | `pnpm wp-sync-main >/dev/null 2>&1; git log --oneline -1; sed -n '598,612p' eslint.config.mjs` — and the agent then quotes an eslint rule out of a file 15 commits stale | on `main`, behind `origin/main`, cure first, `;` between | BLOCK: `;` discards the cure's exit code, so a conflict, a dirty tree or no network leaves the `sed` reading still-stale content — and 7 of the 9 observed cases also silenced the cure with `>/dev/null 2>&1`, so the failure was invisible too. The two-step is safer because the NEXT tool call re-computes `localMain` against `originMain`, so a failed pull re-blocks; an allowed `;` compound never gets that second look | Swap the `;` for `&&` — `pnpm wp-sync-main && <your command>` — or run the cure alone and re-issue the command in the next call |
 | 13 | The Read tool refuses a file on a stale `main` while you have UNCOMMITTED edits | on `main`, behind `origin/main`, dirty tree | BLOCK. This used to fail open, on the argument that the prescribed `git pull` is not a clean fast-forward when the tree is dirty. That was true of the MESSAGE, not the row: the cure cell always offered a second form, and it works dirty | `git checkout -b <new> origin/main` — uncommitted changes come with you onto the new branch. If git refuses because `origin/main` touched the same files, `git stash` first (never blocked), then retry, then `git stash pop` |
-| 15 | The Read tool refuses a file that exists, on a `main` 18 commits behind | on `main`, behind `origin/main`, clean tree | BLOCK: judged by live ancestry (`git merge-base --is-ancestor`), not hash equality, so a pull takes effect instantly | `pnpm wp-checkout-clean-main`, or `git checkout -b <new> origin/main` |
+| 15 | The Read tool refuses a file that exists, on a `main` 18 commits behind | on `main`, behind `origin/main`, clean tree | BLOCK: judged by live ancestry (`git merge-base --is-ancestor`), not hash equality, so a pull takes effect instantly | `pnpm wp-sync-main`, or `git checkout -b <new> origin/main` |
 | 16 | Read is blocked, so the session reaches for `cat`, `grep` and `ls` instead — and describes a CI workflow set missing a whole workflow that existed upstream | the SIDE DOOR: same tree, same staleness, different tool | BLOCK: `B` is judged here beside `R`, so closing the Read tool no longer opens a shell-shaped hole. The log used to read "read-stale-guard handled", which is worse than no guard — it looks covered | `git checkout -b <new> origin/main` |
 | 10 | A Bash command that WRITES tracked files as a side effect — `npx expo install`, a formatter, codegen, `sed -i`, a `>` redirect | on a `main` known to be BEHIND, and the write is incidental to a command whose stated purpose is something else | BLOCK: inside this row `B` is default-DENY plus row 4's skip list, never a blocklist of readers — a command nobody thought to enumerate is caught by not being on the list, which is the only shape that could have caught this one | `git checkout -b <new> origin/main` BEFORE running anything that may write |
 | 17 | Reading files on a `main` you just pulled | on `main`, and `origin/main` is an ancestor of HEAD | ALLOW: ancestry, not hash equality, so the allow arrives the instant the pull lands rather than when the detached refresher next runs | None needed |
-| 24 | `curl`, `gh pr close` or a test run, immediately after `pnpm wp-checkout-clean-main` landed you on a perfectly current `main` | on `main`, current — no staleness anywhere | ALLOW. This used to BLOCK, from the branch alone: the tool the repo prescribes put the agent here, and the guard whose name says STALE then refused everything off a narrow allowlist for a reason that had nothing to do with staleness. WRITES here are still blocked, by row 5 — that hazard is real at any freshness | None needed |
+| 24 | `curl`, `gh pr close` or a test run, immediately after `pnpm wp-sync-main` landed you on a perfectly current `main` | on `main`, current — no staleness anywhere | ALLOW. This used to BLOCK, from the branch alone: the tool the repo prescribes put the agent here, and the guard whose name says STALE then refused everything off a narrow allowlist for a reason that had nothing to do with staleness. WRITES here are still blocked, by row 5 — that hazard is real at any freshness | None needed |
 | 18 | You keep working on the branch after its PR merged, and the next PR reopens code review already landed | branch whose PR is merged — `merged` is monotonic, so the cached flag is trusted with no TTL | BLOCK across all three tools | `git fetch origin main && git checkout -b <new> origin/main` |
 | 26 | You have uncommitted edits on a branch whose PR just merged | merged branch, dirty tree | BLOCK. This used to fail open too, and that valve never had an argument behind it — row 8's cure carries uncommitted work onto the fresh branch, so nothing was ever trapped. It was drift from the documented design, which `read-stale-guard`'s own class comment still described correctly | `git fetch origin main && git checkout -b <new> origin/main` — your edits come with you |
 | 19 | A shell-only session sails through on a merged branch | merged branch, Bash only — both FILE guards are file-scoped, so Bash reached neither | BLOCK: `merged-branch-bash-guard` exists because `branchAlreadyMerged` was being computed and logged on that very path, then thrown away | `git fetch origin main && git checkout -b <new> origin/main` |
@@ -228,7 +228,7 @@ Principle: **these get you OUT or tell you where you are.** They are not "workin
 | group | commands |
 |---|---|
 | get out | `git checkout -b <new> origin/main` · `git switch -c <new> origin/main` · `git switch <other>` · `git worktree add … -b <new> origin/main` |
-| make `main` current | `pnpm wp-checkout-clean-main` *(the prescribed form — also reaps dead branches/worktrees and sweeps orphan directories)* · `git pull` · `git fetch` · `git checkout main && git pull origin main` *(paired only; still allowed, and still the L0 recovery cure, where no `pnpm` bin can be trusted)* |
+| make `main` current | `pnpm wp-sync-main` *(the prescribed form — also reaps dead branches/worktrees and sweeps orphan directories)* · `git pull` · `git fetch` · `git checkout main && git pull origin main` *(paired only; still allowed, and still the L0 recovery cure, where no `pnpm` bin can be trusted)* |
 | orient | `git status\|log\|diff\|branch` · `gh` generally (`pr view`, `pr close`, `pr comment`, `api`, `run watch` — it talks to GitHub, not to this tree) |
 | talk to the network | `curl` · `wget` — a URL is not this repo. NOT the forms that write a local file: `curl -o`, `wget -O`, `gh repo clone`, `gh pr checkout`, `gh run download`, or any `> file` redirect |
 | park work | `git stash` |