@pareto4/pp-core 1.12.1 → 1.17.1

package/pp-core/bin/lib/org-profile.cjs

@@ -11,9 +11,11 @@
  * profile" — that carries a small set of vault/platform coordinates for a
  * single operator's projects. The package name lives entirely in the
  * consuming project's own `.planning/config.json`; pp-core's own source
- * never names one (ORG-01, SC1). An install that configures no such
- * pointer resolves nothing, warns about nothing, and probes no filesystem
- * beyond the one config read every project already pays for (ORG-02).
+ * never names one (ORG-01, SC1). Upstream, an install that configures no
+ * such pointer resolves nothing (ORG-02). This fork reverses ORG-02 on
+ * purpose: with no usable pointer it resolves the embedded profile
+ * (`EMBEDDED_ORG_PROFILE_NAME`, PBI 74316), and `org.profile: "none"` is the
+ * explicit opt-out.
  *
  * It imports ONLY node builtins (`node:fs`, `node:path`) at the top level —
  * no `./vault.cjs`, `./vault-coordinates.cjs`, `./vault-write-back.cjs`,
@@ -39,6 +41,13 @@
  * than writing a second regex; the lazy seam is how a zero-import leaf can
  * still do that.
  *
+ * The second exception (Vault Assurance 13-03, D-23) is a top-level import
+ * of `./vault-mode.cjs`, the mode vocabulary leaf. That module imports
+ * nothing at all, so it can never require this module back and cannot close
+ * a cycle; it is imported so `resolveVaultMode` and the `vault.mode`
+ * disposition quote the key and the two literals from their one owner rather
+ * than spelling them here.
+ *
  * This file's own prose and code deliberately never name a concrete org
  * profile package or any client — the pointer is described only as "the
  * npm package name an operator configures". `tests/org-profile.test.cjs`
@@ -48,12 +57,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOST_FORBIDDEN_CHARS = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = exports.ORG_PROFILE_SEED_KEYS = exports.ORG_PROFILE_SEED_SECTION = exports.ORG_PROFILE_ALLOWLIST = exports.ORG_PROFILE_DATA_FILE = exports.ORG_PROFILE_CONFIG_KEY = void 0;
+exports.HOST_FORBIDDEN_CHARS = exports.PROFILE_REJECTED_CLONE_TARGET_PATTERNS = exports.ORG_PROFILE_SEED_KEYS = exports.ORG_PROFILE_INIT_SECTION = exports.ORG_PROFILE_SEED_SECTION = exports.ORG_PROFILE_ALLOWLIST = exports.VAULT_REQUIRED_CONFIG_KEY = exports.EMBEDDED_ORG_PROFILE_ENV = exports.EMBEDDED_ORG_PROFILE_NAME = exports.ORG_PROFILE_NONE = exports.ORG_PROFILE_DATA_FILE = exports.ORG_PROFILE_CONFIG_KEY = void 0;
+exports.embeddedOrgProfilePath = embeddedOrgProfilePath;
+exports.effectiveEmbeddedOrgProfilePath = effectiveEmbeddedOrgProfilePath;
+exports.resolveGlobalPackageRootCandidates = resolveGlobalPackageRootCandidates;
+exports.globalRootCandidatesFor = globalRootCandidatesFor;
+exports.probeOrgProfilePackage = probeOrgProfilePackage;
 exports.resolveOrgProfileDocument = resolveOrgProfileDocument;
 exports.resolveOrgProfile = resolveOrgProfile;
 exports.readProfileValue = readProfileValue;
+exports.booleanPolicyValue = booleanPolicyValue;
+exports.resolveVaultRequired = resolveVaultRequired;
+exports.resolveVaultMode = resolveVaultMode;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultMode = require("./vault-mode.cjs");
+const { VAULT_MODE_CONFIG_KEY, DEFAULT_VAULT_MODE, VAULT_MODE_REASON, isVaultMode } = vaultMode;
 // ─── Constants ───────────────────────────────────────────────────────────────
 /** The dotted `.planning/config.json` key naming the profile package. Deliberately
  * top-level, NOT nested under `vault.`, because the profile also supplies
@@ -63,9 +83,112 @@ exports.ORG_PROFILE_CONFIG_KEY = 'org.profile';
  * package's `main`/`exports` entry, and never loaded via `require` (D-08). */
 exports.ORG_PROFILE_DATA_FILE = 'org-profile.json';
 /**
- * D-06's fixed allowlist: a profile may contribute exactly these five dotted
- * config keys. Entry order is not contractual; membership is. Anything else
+ * The `org.profile` value that opts a project out of every org profile, the
+ * embedded one included. Compared case-insensitively after trimming — the
+ * same spelling `pp-tools init` already accepts as a skip (UAT-13-F3).
+ */
+exports.ORG_PROFILE_NONE = 'none';
+/**
+ * The name `resolveOrgProfileDocument` reports as `packageName` for this
+ * fork's embedded profile. Not a valid npm package name shape for a scoped
+ * org profile, so it can never collide with a pointer that resolves.
+ *
+ * FORK-ONLY (PBI 74316). This fork serves a single organisation, so the
+ * profile ships inside pp-core as `pp-core/org-profile.json` instead of as a
+ * separate package. It carries coordinates only — never a vault ref: the
+ * vault version a project builds on is committed per project in its
+ * `.platform-bindings.json` (`client.vaultRef`), so no pp-core release can
+ * move it. Never offered upstream — see docs/PORT-BACK-DELTA.md.
+ */
+exports.EMBEDDED_ORG_PROFILE_NAME = 'embedded';
+/**
+ * Absolute path of the embedded profile document. Resolved against this
+ * module's own directory: the compiled file sits at `pp-core/bin/lib/`, and
+ * both this repo and every installed tree keep `pp-core/org-profile.json`
+ * two levels up.
+ */
+function embeddedOrgProfilePath() {
+    return node_path_1.default.join(__dirname, '..', '..', exports.ORG_PROFILE_DATA_FILE);
+}
+/**
+ * Environment override for the embedded profile, for diagnostics and for test
+ * suites that exercise the upstream contract: `none` (or `off`, any case)
+ * disables it, any other non-blank value is a path to the document to use
+ * instead. Unset or blank leaves the shipped document in place. A project
+ * opts out through `org.profile: "none"`, never through this variable.
+ */
+exports.EMBEDDED_ORG_PROFILE_ENV = 'PP_EMBEDDED_ORG_PROFILE';
+/**
+ * The embedded document path in force for this process: `opts._embeddedPath`
+ * (test seam) when given, else the `EMBEDDED_ORG_PROFILE_ENV` override, else
+ * `embeddedOrgProfilePath()`. `null` means no embedded profile applies.
+ */
+function effectiveEmbeddedOrgProfilePath(opts) {
+    if (opts && opts._embeddedPath !== undefined)
+        return opts._embeddedPath;
+    const override = process.env[exports.EMBEDDED_ORG_PROFILE_ENV];
+    if (typeof override === 'string' && override.trim() !== '') {
+        const trimmed = override.trim();
+        return ['none', 'off'].includes(trimmed.toLowerCase()) ? null : trimmed;
+    }
+    return embeddedOrgProfilePath();
+}
+/**
+ * The version reported for the embedded profile: the pp-core release that
+ * ships it. Probes the `VERSION` beside the document (the installer writes
+ * `pp-core/VERSION` into every installed tree), then the repo root's. Returns
+ * `null` when neither is readable and semver-shaped.
+ */
+function readEmbeddedProfileVersion(dataPath) {
+    const dir = node_path_1.default.dirname(dataPath);
+    for (const candidate of [node_path_1.default.join(dir, 'VERSION'), node_path_1.default.join(dir, '..', 'VERSION')]) {
+        try {
+            const raw = node_fs_1.default.readFileSync(candidate, 'utf-8').trim();
+            if (/^\d+\.\d+\.\d+/.test(raw))
+                return raw;
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return null;
+}
+/** The dotted key naming the vault load policy (02-04, GATE-05 / STRICT-01).
+ * Declared in `capabilities/vault/capability.json`'s federated config block,
+ * boolean, default `false`. Named here so neither the allowlist, the value
+ * guard nor `resolveVaultRequired` hand-restates the string. */
+exports.VAULT_REQUIRED_CONFIG_KEY = 'vault.required';
+/**
+ * D-06's fixed allowlist: a profile may contribute exactly these seven dotted
+ * config keys (five coordinates and two policy keys; the seventh, vault.mode,
+ * is documented at its entry). Entry order is not contractual; membership is. Anything else
  * present in a profile document is dropped with a bounded warning.
+ *
+ * FIVE COORDINATES AND ONE POLICY (02-04, D-VH-4 / STRICT-01). The first five
+ * members answer *where to fetch from* — a provider, three shared-vault
+ * coordinates and a platform host. `vault.required` answers something
+ * categorically different: *whether the fetch is mandatory*. It is the first
+ * POLICY member of this list, and it is here deliberately, so one org-profile
+ * package can turn the load gate on across a whole fleet without a per-repo
+ * edit.
+ *
+ * That is also this list's sharpest widening, and it is recorded rather than
+ * glossed (threat T-02-17): an `npm update` of the profile package can now
+ * move the value of a build gate without a code review in the consuming repo.
+ * Three things bound it. First, precedence — project config outranks the
+ * profile for every member, so any project can opt out explicitly, and
+ * `tests/org-profile.test.cjs` pins that direction with a non-vacuity partner
+ * rather than assuming it. Second, direction — the profile can only ever make
+ * the gate MORE strict from the built-in default of `false`, and a gate
+ * turning on is fail-closed. Third, the value guard below accepts only the two
+ * boolean literals for this key, so a profile cannot smuggle an arbitrary
+ * string into the policy.
+ *
+ * The warning in the block beneath this one is NOT retracted: it is still
+ * exactly right about the seed section, which stays off this list. A key that
+ * layers at runtime is a key an `npm update` can silently move — the
+ * difference is that for `vault.required` that consequence was weighed and
+ * accepted under a locked decision, and for `bindings.*` it was not.
  */
 exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
     'vault.provider',
@@ -73,6 +196,15 @@ exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
     'vault.fallback_ref',
     'vault.fallback_host',
     'platform.host',
+    'vault.required',
+    // Vault Assurance 13-03 (D-06): the second POLICY key, after vault.required
+    // (02-04). Unlike vault.required, a profile value here can make a gate LESS
+    // strict — `standards` turns the blocking vault.audit gate into
+    // not_applicable — so the widening is accepted and bounded in 13-CONTEXT
+    // D-24 (threat T-13-01): project config outranks the profile, only the two
+    // literals pass the disposition below, and the embedded fork profile does
+    // not seed it. vault.enabled and init.* stay absent from this list.
+    VAULT_MODE_CONFIG_KEY,
 ]);
 /**
  * The single top-level key naming the Phase 34 init-only seed section.
@@ -90,6 +222,15 @@ exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
  * directly from the package.
  */
 exports.ORG_PROFILE_SEED_SECTION = 'bindings';
+/**
+ * PBI 74299: the top-level key naming the init-answers section — fixed answers
+ * for `pp-tools init` questions (`client_name`, `provider`, `visibility`) and
+ * `derive_slugs`. Read ONLY by `src/init-contract.cts` through
+ * `resolveOrgProfileDocument`; like the seed section it is deliberately absent
+ * from `ORG_PROFILE_ALLOWLIST`, because it answers questions once at init and
+ * never layers a runtime config key.
+ */
+exports.ORG_PROFILE_INIT_SECTION = 'init';
 /**
  * The five dotted leaf keys the seed section may carry, each prefixed with
  * `ORG_PROFILE_SEED_SECTION`. Membership is contractual; entry ORDER is not.
@@ -224,51 +365,125 @@ function describeUnknown(value) {
 /**
  * D-03's "global" half of the two-path resolution ladder, as a pure
  * heuristic with NO subprocess spawn (this repo avoids spawning a
- * subprocess for a computation that does not strictly require one):
+ * subprocess for a computation that does not strictly require one).
+ * Returns an ORDERED list of existing candidate roots (init-friction F1 —
+ * the single-root version silently missed Homebrew layouts):
  *
  * 1. `NPM_CONFIG_PREFIX` / `npm_config_prefix`, when set to a non-blank
  *    string: `<prefix>/node_modules` on `win32`, `<prefix>/lib/node_modules`
  *    otherwise.
- * 2. Otherwise, derived from `process.execPath`: with
- *    `execDir = path.dirname(process.execPath)`, `path.join(execDir,
- *    'node_modules')` on `win32`, `path.resolve(execDir, '..', 'lib',
- *    'node_modules')` otherwise.
+ * 2. Every PATH directory containing a `node` entry, mapped through the
+ *    same `<bin>` → `<global tree>` rule — WITHOUT resolving symlinks.
+ *    This is what fixes Homebrew: `process.execPath` resolves
+ *    `/opt/homebrew/bin/node` into the Cellar, whose `lib/node_modules`
+ *    exists but holds only npm itself, while the real global tree lives at
+ *    `/opt/homebrew/lib/node_modules` beside the PATH symlink.
+ * 3. Derived from `process.execPath` (the pre-existing heuristic) — still
+ *    correct for nvm/Volta layouts.
  *
- * The candidate is returned only when `fs.existsSync(candidate)`;
- * otherwise `null`.
+ * Candidates are deduped and filtered to `fs.existsSync`; resolution tries
+ * each in order (first hit wins), so a wrong-but-existing root earlier in
+ * the list cannot mask a later root that actually holds the package.
  *
- * Accepted residual: an nvm/Volta-style layout that honours neither
- * `NPM_CONFIG_PREFIX` nor places the global tree beside the node binary
- * will simply not resolve a globally-installed profile — this degrades
- * per D-09 (falls through to the no-profile behaviour with a warning)
- * rather than failing.
+ * Accepted residual: a layout that honours none of the three sources will
+ * still not resolve a globally-installed profile — this degrades per D-09
+ * (falls through to the no-profile behaviour with a warning) rather than
+ * failing.
  *
  * pp-core's own install directory is deliberately NOT a candidate here:
  * the AI-runtime install is a bare directory copy with no `package.json`
  * and no `node_modules` of its own, so resolving relative to it would
  * never find a sibling package.
+ *
+ * TWO READERS, ONE BUILDER, ONE FLAG (UAT-13-F2). RESOLUTION — the
+ * answer-time probe (`probeOrgProfilePackage`) and profile load
+ * (`resolveOrgProfileDocument`) — walks the full list above. DETECTION —
+ * `buildInitQuestions`' org-profile hint and `verifyInitInvariants`'
+ * INIT_QUESTIONS_ORG_PROFILE_UNASKED check in `src/init-contract.cts` —
+ * passes `explicitPrefixOnly: true`: when `NPM_CONFIG_PREFIX` /
+ * `npm_config_prefix` is set, only the prefix-derived root is scanned.
+ * An explicit prefix is the operator's — or a test harness's — statement
+ * of where the global tree is, and a hint or a violation must never be
+ * produced from a tree the operator did not point at. Detection roots are
+ * therefore a SUBSET of resolution roots: anything detected resolves by
+ * name, and a package that sits only on a PATH-derived root while an
+ * explicit prefix is set is still selectable by typing its name. Without a
+ * prefix both readers see the same list, which is what lets detection find
+ * a Homebrew layout at all.
  */
-function resolveGlobalPackageRoot() {
+/** Bounds the PATH scan below — a DoS guard in the same convention as
+ * `PROFILE_FLATTEN_LEAF_CAP` (a pathological PATH cannot make resolution
+ * scan unboundedly many directories). */
+const GLOBAL_ROOT_PATH_SCAN_CAP = 64;
+/** The `<bin dir>` → `<global node_modules>` mapping npm itself uses:
+ * `<bin>/node_modules` on win32, `<bin>/../lib/node_modules` elsewhere. */
+function globalRootFromBinDir(binDir) {
+    return process.platform === 'win32'
+        ? node_path_1.default.join(binDir, 'node_modules')
+        : node_path_1.default.resolve(binDir, '..', 'lib', 'node_modules');
+}
+function resolveGlobalPackageRootCandidates(opts = {}) {
+    const candidates = [];
+    const push = (c) => {
+        if (!candidates.includes(c))
+            candidates.push(c);
+    };
+    const existing = () => candidates.filter((c) => {
+        try {
+            return node_fs_1.default.existsSync(c);
+        }
+        catch {
+            return false;
+        }
+    });
     try {
+        // 1. Explicit prefix always wins — same rule as before.
         const prefixEnv = process.env.NPM_CONFIG_PREFIX ?? process.env.npm_config_prefix;
-        let candidate;
         if (typeof prefixEnv === 'string' && prefixEnv.trim() !== '') {
             const prefix = prefixEnv.trim();
-            candidate =
-                process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules');
+            push(process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules'));
+            // Detection mode (see the header): an explicit prefix is authoritative.
+            // A prefix that points nowhere yields [] — still the authoritative
+            // answer ("no global tree"), never a fall-through to PATH.
+            if (opts.explicitPrefixOnly === true)
+                return existing();
         }
-        else {
-            const execDir = node_path_1.default.dirname(process.execPath);
-            candidate =
-                process.platform === 'win32'
-                    ? node_path_1.default.join(execDir, 'node_modules')
-                    : node_path_1.default.resolve(execDir, '..', 'lib', 'node_modules');
+        // 2. PATH scan for the directory holding the `node` entry AS INVOKED
+        //    (symlink not resolved). `process.execPath` resolves symlinks, so a
+        //    Homebrew layout (`/opt/homebrew/bin/node` → Cellar) lands in the
+        //    Cellar's private `lib/node_modules` (npm only) and misses the real
+        //    global tree at `/opt/homebrew/lib/node_modules`. The un-resolved
+        //    PATH entry is what npm's own prefix derivation is anchored to.
+        const pathEnv = process.env.PATH ?? '';
+        const pathDirs = pathEnv
+            .split(node_path_1.default.delimiter)
+            .filter((d) => d.trim() !== '')
+            .slice(0, GLOBAL_ROOT_PATH_SCAN_CAP);
+        const nodeNames = process.platform === 'win32' ? ['node.exe', 'node.cmd', 'node'] : ['node'];
+        for (const dir of pathDirs) {
+            for (const name of nodeNames) {
+                let found = false;
+                try {
+                    found = node_fs_1.default.existsSync(node_path_1.default.join(dir, name));
+                }
+                catch {
+                    // unreadable PATH entry — skip it
+                }
+                if (found) {
+                    push(globalRootFromBinDir(dir));
+                    break;
+                }
+            }
         }
-        return node_fs_1.default.existsSync(candidate) ? candidate : null;
+        // 3. execPath-derived (the pre-existing heuristic) — still the correct
+        //    root for nvm/Volta-style layouts where the global tree sits beside
+        //    the real binary.
+        push(globalRootFromBinDir(node_path_1.default.dirname(process.execPath)));
     }
     catch {
-        return null;
+        // degrade to whatever was collected before the fault
     }
+    return existing();
 }
 // ─── resolveProfilePackage ───────────────────────────────────────────────────
 /**
@@ -283,23 +498,54 @@ function resolveGlobalPackageRoot() {
  * 220-228): the same try/catch-returns-null shape, one level removed
  * (resolving a data file's sibling `package.json`, not a CLI entry point).
  */
-function resolveProfilePackage(pkgName, cwd, globalRoot) {
+function resolveProfilePackage(pkgName, cwd, globalRoots) {
     try {
         return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [cwd] }), source: 'project' };
     }
     catch {
-        // fall through to the global attempt below
+        // fall through to the global attempts below
     }
-    if (globalRoot) {
+    for (const globalRoot of globalRoots) {
         try {
             return { pkgJsonPath: require.resolve(`${pkgName}/package.json`, { paths: [globalRoot] }), source: 'global' };
         }
         catch {
-            // fall through to null below
+            // try the next candidate root
         }
     }
     return null;
 }
+/** Map the `_globalRoot` test seam (a single root, or `null` for "no global
+ * root found") onto the candidate-list shape resolution now uses; when the
+ * seam is absent, run the production heuristic. The seam wins over
+ * `explicitPrefixOnly`, which only shapes the production heuristic —
+ * detection passes it, resolution does not (see the builder's header). */
+function globalRootCandidatesFor(opts) {
+    if (opts && opts._globalRoot !== undefined) {
+        return opts._globalRoot === null ? [] : [opts._globalRoot];
+    }
+    return resolveGlobalPackageRootCandidates({ explicitPrefixOnly: opts?.explicitPrefixOnly === true });
+}
+/**
+ * Answer-time probe for `/pp-init`'s `org_profile` question (init-friction
+ * F2): does `pkgName` resolve from the project or any global root right
+ * now? Returns the probed global roots so a rejection message can name
+ * them. Never throws (D-09) — any fault reports `resolved: false` with the
+ * roots collected so far.
+ */
+function probeOrgProfilePackage(pkgName, cwd, opts) {
+    let probedGlobalRoots = [];
+    try {
+        probedGlobalRoots = globalRootCandidatesFor(opts);
+        const trimmed = typeof pkgName === 'string' ? pkgName.trim() : '';
+        if (trimmed === '')
+            return { resolved: false, probedGlobalRoots };
+        return { resolved: resolveProfilePackage(trimmed, cwd, probedGlobalRoots) !== null, probedGlobalRoots };
+    }
+    catch {
+        return { resolved: false, probedGlobalRoots };
+    }
+}
 /**
  * Flatten a parsed profile document to dotted leaf paths, recursing only
  * through plain objects. Bounded on two axes (T-33-06, denial-of-service):
@@ -345,7 +591,17 @@ function flattenProfileDocument(doc) {
  * a DISPOSITION over the shared shape predicates, never as a parallel
  * regex (D-10's "one source of shape truth" requirement).
  *
- * Scalar guard, applied to every key: the value must be a string; its
+ * `vault.required` (02-04) is handled BEFORE the scalar guard, because it is
+ * the list's only boolean-typed key and the natural JSON an operator writes
+ * for it is `true`, not `"true"`. It accepts exactly four inputs — the JSON
+ * booleans `true`/`false` and the trimmed strings `'true'`/`'false'` — and
+ * carries forward the canonical `'true'`/`'false'` string, so `contributes`
+ * stays a `Record<string, string>`. Everything else is rejected, which means
+ * a profile cannot smuggle an arbitrary value into a build-gate policy: a
+ * typo like `"yes"` is dropped with a bounded warning and the gate stays at
+ * its `false` default rather than silently becoming truthy.
+ *
+ * Scalar guard, applied to every other key: the value must be a string; its
  * trimmed form must be non-empty; the UNTRIMMED value must carry no ASCII
  * control character; the TRIMMED value must carry no whitespace (so
  * leading/trailing padding — e.g. `' azure '` — is tolerated, matching
@@ -388,9 +644,37 @@ function flattenProfileDocument(doc) {
  */
 function profileValueDisposition(key, value) {
     try {
+        // 02-04: the one boolean-typed allowlist member, disposed of before the
+        // string-only scalar guard below would reject its natural JSON form.
+        if (key === exports.VAULT_REQUIRED_CONFIG_KEY) {
+            if (value === true || value === false)
+                return { ok: true, value: String(value) };
+            if (typeof value === 'string') {
+                const t = value.trim();
+                if (t === 'true' || t === 'false')
+                    return { ok: true, value: t };
+            }
+            return { ok: false, reason: 'value must be the boolean true or false' };
+        }
+        // 13-03 (D-06, D-09): the mode accepts only its two literals, trimmed.
+        // Anything else is dropped through the existing warning / rejected[]
+        // path, and the mode then resolves to the default. The reason names the
+        // allowed values and never echoes the rejected one.
+        if (key === VAULT_MODE_CONFIG_KEY) {
+            if (isVaultMode(value))
+                return { ok: true, value: value.trim() };
+            return { ok: false, reason: 'value must be practices or standards' };
+        }
         if (typeof value !== 'string') {
             return { ok: false, reason: 'value must be a string' };
         }
+        // PBI 74316: exactly "" for the shared repo is an explicit opt-out of the
+        // shared tier — the same decision an empty `vault.fallback_repo` in project
+        // config already records (see `resolveSharedCoordinates`). Whitespace is
+        // not "", so it still falls through to the blank rejection below.
+        if (key === 'vault.fallback_repo' && value === '') {
+            return { ok: true, value: '' };
+        }
         const trimmed = value.trim();
         if (trimmed === '') {
             return { ok: false, reason: 'value must not be blank' };
@@ -462,10 +746,19 @@ function profileValueDisposition(key, value) {
  * explicitly (including `null`, to simulate "no global root found")
  * overrides the production heuristic for that one call.
  *
+ * FORK-ONLY (PBI 74316) — the embedded profile. Where upstream resolves
+ * nothing, this fork resolves `embeddedOrgProfilePath()`: an absent key, a
+ * blank or non-string pointer, and a configured package that cannot be found
+ * all yield the embedded document (source `embedded`). Only the explicit
+ * `ORG_PROFILE_NONE` pointer yields the fully-absent shape, so a project can
+ * still opt out. A configured package that DOES resolve always wins. The
+ * `_embeddedPath` option is the test seam for that document: a path replaces
+ * it, `null` simulates a tree that ships none; without it the
+ * `EMBEDDED_ORG_PROFILE_ENV` override applies (`effectiveEmbeddedOrgProfilePath`).
+ *
  * Never throws (D-09): any fault anywhere in this function degrades to the
- * fully-absent shape plus one bounded warning, exactly as if no profile
- * were configured. The document is read only via `fs.readFileSync` +
- * `JSON.parse`, never `require` (D-08).
+ * fully-absent shape plus one bounded warning. The document is read only via
+ * `fs.readFileSync` + `JSON.parse`, never `require` (D-08).
  */
 function resolveOrgProfileDocument(cwd, opts) {
     const absentDocShape = (warnings = []) => ({
@@ -478,36 +771,78 @@ function resolveOrgProfileDocument(cwd, opts) {
         document: {},
         warnings,
     });
+    const embeddedDocShape = (configured) => {
+        const dataPath = effectiveEmbeddedOrgProfilePath(opts);
+        if (dataPath === null) {
+            return { ...absentDocShape(), configured };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(node_fs_1.default.readFileSync(dataPath, 'utf-8'));
+        }
+        catch {
+            return {
+                ...absentDocShape([bound('the embedded org profile could not be read — no coordinates contributed.')]),
+                configured,
+            };
+        }
+        if (!isObject(parsed)) {
+            return {
+                ...absentDocShape([bound('the embedded org profile is not a JSON object — no coordinates contributed.')]),
+                configured,
+            };
+        }
+        return {
+            configured,
+            resolved: true,
+            packageName: exports.EMBEDDED_ORG_PROFILE_NAME,
+            version: readEmbeddedProfileVersion(dataPath),
+            source: 'embedded',
+            dataPath,
+            document: parsed,
+            warnings: [],
+        };
+    };
     try {
         // Step 1: read the pointer. An absent key (undefined) or a blank string
-        // is the fully-absent shape with ZERO warnings and no further
-        // filesystem access — this is the ORG-02 contract. A present
-        // non-string value is the one exception: same absent shape, plus
-        // exactly one bounded warning.
+        // resolves the embedded profile with ZERO warnings. A present non-string
+        // value does the same, plus exactly one bounded warning. The explicit
+        // opt-out is the one pointer that resolves nothing.
         const rawPointer = cfgGet(cwd, exports.ORG_PROFILE_CONFIG_KEY, undefined);
         if (rawPointer === undefined) {
-            return absentDocShape();
+            return embeddedDocShape(null);
         }
         if (typeof rawPointer !== 'string') {
             const echoed = sanitizeForWarning(describeUnknown(rawPointer));
-            return absentDocShape([
-                bound(`${exports.ORG_PROFILE_CONFIG_KEY} value "${echoed}" is not a string — ignoring, no org profile applied.`),
-            ]);
+            const embedded = embeddedDocShape(null);
+            const consequence = embedded.resolved ? 'ignoring it, the embedded org profile applies.' : 'ignoring, no org profile applied.';
+            return {
+                ...embedded,
+                warnings: [bound(`${exports.ORG_PROFILE_CONFIG_KEY} value "${echoed}" is not a string — ${consequence}`), ...embedded.warnings],
+            };
         }
         const pkgName = rawPointer.trim();
         if (pkgName === '') {
-            return absentDocShape();
+            return embeddedDocShape(null);
         }
-        // Step 2: resolve the package (project, then global).
-        const globalRoot = opts && opts._globalRoot !== undefined ? opts._globalRoot : resolveGlobalPackageRoot();
-        const hit = resolveProfilePackage(pkgName, cwd, globalRoot);
+        if (pkgName.toLowerCase() === exports.ORG_PROFILE_NONE) {
+            return { ...absentDocShape(), configured: pkgName };
+        }
+        // Step 2: resolve the package (project, then every global candidate).
+        const globalRoots = globalRootCandidatesFor(opts);
+        const hit = resolveProfilePackage(pkgName, cwd, globalRoots);
         if (!hit) {
             const echoed = sanitizeForWarning(pkgName);
+            const probed = globalRoots.length > 0
+                ? `the global npm root(s) ${globalRoots.map((r) => sanitizeForWarning(r)).join(', ')}`
+                : 'no locatable global npm root';
+            const embedded = embeddedDocShape(pkgName);
+            const fallback = embedded.resolved ? 'Falling back to the embedded org profile.' : 'Falling back to built-in defaults.';
             return {
-                ...absentDocShape(),
-                configured: pkgName,
+                ...embedded,
                 warnings: [
-                    bound(`org profile "${echoed}" was not found — resolution was attempted from the project and the global npm root and found nothing. Falling back to built-in defaults.`),
+                    bound(`org profile "${echoed}" was not found — resolution was attempted from the project and ${probed} and found nothing. ${fallback}`),
+                    ...embedded.warnings,
                 ],
             };
         }
@@ -612,6 +947,9 @@ function resolveOrgProfile(cwd, opts) {
             if (leaf.key === exports.ORG_PROFILE_SEED_SECTION || leaf.key.startsWith(`${exports.ORG_PROFILE_SEED_SECTION}.`)) {
                 continue;
             }
+            if (leaf.key === exports.ORG_PROFILE_INIT_SECTION || leaf.key.startsWith(`${exports.ORG_PROFILE_INIT_SECTION}.`)) {
+                continue;
+            }
             if (!exports.ORG_PROFILE_ALLOWLIST.includes(leaf.key)) {
                 ignored.push(leaf.key);
                 if (ignoredWarningCount < PROFILE_IGNORED_WARNING_CAP) {
@@ -694,3 +1032,156 @@ function readProfileValue(cwd, key, opts) {
         source: resolution.source,
     };
 }
+// ─── resolveVaultRequired (02-04, D-VH-4 / STRICT-01) ────────────────────────
+/**
+ * The four inputs a boolean policy value may take, and nothing else — the SAME
+ * disposition `profileValueDisposition` above already applies to this key.
+ * Returns `undefined` for anything else, which is not the same as `false`: it
+ * means "this value expresses no policy".
+ *
+ * 02-SECURITY UF-01. The project-config read used to be
+ * `value === true || value === 'true'`, which collapsed every other spelling
+ * to `false` — while `config-set vault.required TRUE|True|1|yes|on|enabled`
+ * all answered `{"updated": true}` and wrote exactly those, so the supported
+ * CLI could leave a build gate OFF while reporting success. UF-01 closed the
+ * READ half (here); 07-14 closed the WRITE half, and `config-set` now refuses
+ * every one of those spellings with a usage error and writes nothing, so this
+ * function's `undefined` arm is reachable only from a hand-edited config.json
+ * or an org profile. The asymmetry made it sharper: the LOWER-trust org
+ * profile validated to four literals and warned, while project config — which
+ * outranks it — did not, so a project `"TRUE"` both failed to arm the gate AND
+ * suppressed a profile value that would have, because `found` rather than
+ * validity decided precedence.
+ *
+ * Moved here from `src/vault.cts` together with the gate's ladder
+ * (13-REVIEW CR-02), so the gate and the report share one reading.
+ */
+function booleanPolicyValue(value) {
+    if (value === true || value === false)
+        return value;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === 'true')
+            return true;
+        if (trimmed === 'false')
+            return false;
+    }
+    return undefined;
+}
+/**
+ * Resolve the `vault.required` POLICY for `cwd`: project config first, the
+ * org profile second, the registered default (`false`) last. This is the ONE
+ * reader of the policy ladder (13-REVIEW CR-02): the load gate
+ * (`resolveVaultRequiredFlag` in `src/vault.cts`) asks it after its own
+ * `vault.enabled` check, and the `vault org-profile` report asks it for the
+ * `effective` row — so the report and the gate cannot disagree about which
+ * level won for the same inputs. Before CR-02 this function read only the
+ * root `.planning/config.json` and counted only `=== true || === 'true'`,
+ * while the gate read the workstream config first and trimmed, so a project
+ * `" true"` or `"yes"` was reported as overriding a profile `true` that the
+ * gate in fact enforced.
+ *
+ * PROJECT CONFIG OUTRANKS THE PROFILE (T-02-17), so the ordering below is
+ * load-bearing. Level 1 reads RAW config through `resolveConfigKey` with
+ * `config: {}` and `registry: {}`: the workstream config.json, then the root
+ * config.json, each in either dotted form (nested first), with no schema
+ * default. A project value of `false` is a real value and wins. A project
+ * value that is PRESENT BUT UNPARSEABLE (`booleanPolicyValue` answers
+ * `undefined`) does not consume the decision: the profile is consulted as if
+ * the project had said nothing, because a value that expresses no policy must
+ * not outrank one that does. It is returned as `ignoredConfigValue` so the
+ * gate can say so on stderr; this function prints nothing.
+ *
+ * This answers the POLICY, not whether a gate exists: on a project with
+ * `vault.enabled` off no gate renders and `resolveVaultRequiredFlag` answers
+ * `false` whatever this returns.
+ *
+ * Never throws — a failed config read falls through to the profile, and the
+ * profile seam already degrades to a miss on any fault.
+ */
+function resolveVaultRequired(cwd, opts) {
+    // Level 1 — project config, raw (ws then root, either dotted form).
+    let ignoredConfigValue;
+    let ignored = false;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const activation = require('./capability-activation.cjs');
+        const fromConfig = activation.resolveConfigKey(exports.VAULT_REQUIRED_CONFIG_KEY, { config: {}, cwd, registry: {} });
+        if (fromConfig.found) {
+            const decided = booleanPolicyValue(fromConfig.value);
+            if (decided !== undefined)
+                return { required: decided, source: 'config', warnings: [] };
+            ignored = true;
+            ignoredConfigValue = fromConfig.value;
+        }
+    }
+    catch { /* fall through to the profile */ }
+    const withIgnored = (r) => (ignored ? { ...r, ignoredConfigValue } : r);
+    // Level 2 — the org profile. Already narrowed to 'true'/'false' by
+    // profileValueDisposition; booleanPolicyValue agrees with it by construction.
+    const profile = readProfileValue(cwd, exports.VAULT_REQUIRED_CONFIG_KEY, opts);
+    if (profile.value !== undefined) {
+        const decided = booleanPolicyValue(profile.value);
+        if (decided !== undefined)
+            return withIgnored({ required: decided, source: 'profile', warnings: profile.warnings });
+    }
+    // Level 3 — the registered default from capabilities/vault/capability.json.
+    return withIgnored({ required: false, source: 'default', warnings: profile.warnings });
+}
+/**
+ * Resolve `vault.mode` for `cwd`: project config, then the org profile, then
+ * the registered default `practices` — the same three levels as
+ * `resolveVaultRequired` above.
+ *
+ * Like `resolveVaultRequired` (the one ladder both the load gate and the
+ * report ask, since 13-REVIEW CR-02), this resolver is the ONE reader of the
+ * mode for every mode-aware surface: the `vault
+ * org-profile` report (13-05), the gate, refusals and status field (13-06)
+ * and the parked practices surfaces (13-07). No surface re-reads the key
+ * from config itself; the negative-grep anti-drift test in
+ * `tests/vault-mode.test.cjs` is what keeps a second reader from appearing.
+ *
+ * Level 1 reads RAW config (D-21): `resolveConfigKey` with `config: {}` and
+ * `registry: {}` reads the workstream config.json and then the root
+ * config.json, each in either dotted form (nested first), with NO schema
+ * default and no federated fallback. The merged config from
+ * `config-loader.cts` is deliberately not used:
+ * `federated-config`'s `_typeMatches` substitutes the schema default for an
+ * out-of-enum value, and its warning is suppressed at load
+ * (`config-loader.cts`), so `"whatever"` would silently read as `practices`.
+ * A project value that is present but not one of the two literals returns
+ * `ok: false` with `vault_mode_invalid` and NEVER falls back (D-08): an
+ * unknown mode must be refused, not treated as practices.
+ *
+ * Level 2 is `readProfileValue`; `profileValueDisposition` has already
+ * narrowed the profile value to one of the two literals or dropped it with a
+ * warning (D-09), so an invalid profile value lands at level 3.
+ *
+ * KNOWN GAP (D-25), recorded rather than hidden: `config-get` reads only the
+ * planning dir's config.json, while level 1 here reads the workstream config
+ * and then the root config. In flat mode the two agree (pinned by the parity
+ * test in `tests/vault-mode.test.cjs`); on a partitioned project a root-only
+ * `vault.mode` can read differently. Filed as a todo; the same gap pre-exists
+ * for `vault.required`.
+ *
+ * Never throws: both seams already degrade to a miss on any fault.
+ */
+function resolveVaultMode(cwd, opts) {
+    // Level 1 — project config, raw (ws then root, either dotted form).
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const activation = require('./capability-activation.cjs');
+    const fromConfig = activation.resolveConfigKey(VAULT_MODE_CONFIG_KEY, { config: {}, cwd, registry: {} });
+    if (fromConfig.found) {
+        if (isVaultMode(fromConfig.value)) {
+            return { ok: true, mode: fromConfig.value.trim(), source: 'config', warnings: [] };
+        }
+        return { ok: false, source: 'config', reason: VAULT_MODE_REASON.INVALID, warnings: [] };
+    }
+    // Level 2 — the org profile, already narrowed by profileValueDisposition.
+    const profile = readProfileValue(cwd, VAULT_MODE_CONFIG_KEY, opts);
+    if (isVaultMode(profile.value)) {
+        return { ok: true, mode: profile.value.trim(), source: 'profile', warnings: profile.warnings };
+    }
+    // Level 3 — the registered default from capabilities/vault/capability.json.
+    return { ok: true, mode: DEFAULT_VAULT_MODE, source: 'default', warnings: profile.warnings };
+}