@pareto4/pp-core 1.13.0 → 1.18.0

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

@@ -11,12 +11,14 @@
  * 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`,
+ * no `./vault.cjs`, `./vault-coordinates.cjs`,
  * `./io.cjs`, `./shell-command-projection.cjs`. This is load-bearing: in
  * 33-03 BOTH `src/git-provider.cts` and `src/vault-coordinates.cts` import
  * THIS module at their own top level. If this module imported either of
@@ -31,7 +33,7 @@
  * inside `profileValueDisposition`, executed only when a profile value is
  * actually being validated, never at module load. This is the same
  * lazy-require seam `src/vault-command-router.cts` already uses for
- * `./vault.cjs` and `./vault-write-back.cjs`, and it is safe here precisely
+ * `./vault.cjs`, and it is safe here precisely
  * because `git-provider.cjs` has no top-level dependency on this module —
  * by the time any value is being validated, that module is either already
  * in the require cache or loads cleanly on its own. D-10 requires reusing
@@ -48,14 +50,17 @@ 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.TRACE_ACCEPTED_PREDICATE_MAX = exports.TRACE_ACCEPTED_PREDICATES_CAP = exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY = exports.VAULT_REQUIRED_CONFIG_KEY = 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.resolveAcceptedTracePredicates = resolveAcceptedTracePredicates;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // ─── Constants ───────────────────────────────────────────────────────────────
@@ -66,41 +71,113 @@ exports.ORG_PROFILE_CONFIG_KEY = 'org.profile';
 /** The fixed filename read from the resolved package's own directory — never the
  * package's `main`/`exports` entry, and never loaded via `require` (D-08). */
 exports.ORG_PROFILE_DATA_FILE = 'org-profile.json';
-/** The dotted key naming the vault load policy, declared boolean (default
- * false) by `capabilities/vault/capability.json`. Named once here so neither
- * the allowlist, the value guard nor `resolveVaultRequired` restates it. */
-exports.VAULT_REQUIRED_CONFIG_KEY = 'vault.required';
 /**
- * The dotted key naming the practice-trace predicate types a READER accepts
- * besides pp-core's own (`TRACE_PREDICATE_TYPE` in src/vault-trace.cts). It
- * exists so a project that switches engine mid-engagement can keep reading
- * the traces its earlier engine wrote: the org profile of that engagement
- * lists the earlier engine's predicate URI here. Writers never use it — pp-core
- * always writes its own URI — and pp-core itself names no such URI.
+ * 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.
  */
-exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY = 'vault.trace.accepted_predicates';
-/** At most this many accepted predicate URIs, each at most this long. */
-exports.TRACE_ACCEPTED_PREDICATES_CAP = 8;
-exports.TRACE_ACCEPTED_PREDICATE_MAX = 200;
+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();
+}
 /**
- * D-06's fixed allowlist: a profile may contribute exactly these seven dotted
- * config keys. 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. The first five answer where to fetch from.
- * `vault.required` answers whether the vault load is mandatory, so one
- * org-profile package can turn the load gate on across a fleet without a
- * per-repository edit. That is this list's sharpest widening: an `npm update`
- * of the profile package can move a build gate without a review in the
- * consuming repository. It is bounded three ways: project config outranks the
- * profile, so any project can opt out explicitly; the profile can only raise
- * the gate from the built-in default `false` (a gate turning on fails
- * closed); and the value guard accepts only the two boolean literals.
- * `vault.enabled` (arming the capability) stays off the list.
- *
- * `vault.trace.accepted_predicates` is READ-ONLY widening: it lets the trace
- * readers accept another engine's predicate URI (a list of https URIs). It
- * changes no writer and no gate polarity.
+ * 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 six dotted
+ * config keys (five coordinates and one policy key). Entry order is not
+ * contractual; membership is. Anything else present in a profile document is
+ * dropped with a bounded warning, except the retired keys below.
+ *
+ * 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',
@@ -108,9 +185,15 @@ exports.ORG_PROFILE_ALLOWLIST = Object.freeze([
     'vault.fallback_ref',
     'vault.fallback_host',
     'platform.host',
-    exports.VAULT_REQUIRED_CONFIG_KEY,
-    exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY,
+    'vault.required',
 ]);
+/**
+ * Keys a profile written for an older pp-core may still carry, which this
+ * engine no longer reads (FORK-ONLY: the vault once had a second, practices
+ * mode). They are dropped without a warning: a profile that still says
+ * `vault.mode` needs no attention, because the standards vault is the only vault.
+ */
+const RETIRED_PROFILE_KEYS = new Set(['vault.mode', 'vault.practices_enabled']);
 /**
  * The single top-level key naming the Phase 34 init-only seed section.
  *
@@ -127,6 +210,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.
@@ -257,39 +349,66 @@ function describeUnknown(value) {
         return Object.prototype.toString.call(value);
     }
 }
-// ─── Global package roots ────────────────────────────────────────────────────
+// ─── resolveGlobalPackageRoot ────────────────────────────────────────────────
 /**
- * D-03's "global" half of the two-path resolution ladder, as a pure heuristic
- * with NO subprocess spawn. Returns an ORDERED list of existing candidate
- * roots (a single root silently missed Homebrew layouts):
+ * 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).
+ * 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. Every PATH directory containing a `node` entry, mapped through the same
- *    `<bin>` → `<global tree>` rule — WITHOUT resolving symlinks. This is what
- *    finds Homebrew: `process.execPath` resolves `/opt/homebrew/bin/node` into
- *    the Cellar, whose `lib/node_modules` exists but holds only npm, while the
- *    real global tree lives at `/opt/homebrew/lib/node_modules` beside the
- *    PATH symlink.
- * 3. Derived from `process.execPath` — still correct for nvm/Volta layouts.
+ * 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.
  *
  * Candidates are deduped and filtered to `fs.existsSync`; resolution tries
- * each in order (first hit wins), so an existing-but-empty earlier root cannot
- * mask a later root that holds the package.
+ * 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: 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.
  *
- * Detection (the `/pp-init` org-profile hint and its invariant check) passes
- * `explicitPrefixOnly: true`: with `NPM_CONFIG_PREFIX` set, only the prefix
- * root is scanned, because a hint must never come from a tree the operator did
- * not point at. Detection roots are therefore a subset of resolution roots.
+ * 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.
  *
- * pp-core's own install directory is deliberately NOT a candidate: the
- * runtime install is a bare directory copy with no `node_modules` of its own.
+ * 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.
  */
+/** 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;
-/** npm's own `<bin dir>` → `<global node_modules>` mapping. */
+/** 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');
+    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 = [];
@@ -306,16 +425,25 @@ function resolveGlobalPackageRootCandidates(opts = {}) {
         }
     });
     try {
+        // 1. Explicit prefix always wins — same rule as before.
         const prefixEnv = process.env.NPM_CONFIG_PREFIX ?? process.env.npm_config_prefix;
         if (typeof prefixEnv === 'string' && prefixEnv.trim() !== '') {
             const prefix = prefixEnv.trim();
             push(process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules'));
-            // An explicit prefix is authoritative for detection; one that points
-            // nowhere yields [] — never a fall-through to PATH.
+            // 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();
         }
-        const pathDirs = (process.env.PATH ?? '')
+        // 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);
@@ -335,6 +463,9 @@ function resolveGlobalPackageRootCandidates(opts = {}) {
                 }
             }
         }
+        // 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 {
@@ -342,23 +473,12 @@ function resolveGlobalPackageRootCandidates(opts = {}) {
     }
     return existing();
 }
-/**
- * Map the `_globalRoot` test seam (a single root, or `null` for "no global
- * root found") onto the candidate-list shape; when the seam is absent, run the
- * production heuristic. The seam wins over `explicitPrefixOnly`.
- */
-function globalRootCandidatesFor(opts) {
-    if (opts && opts._globalRoot !== undefined) {
-        return opts._globalRoot === null ? [] : [opts._globalRoot];
-    }
-    return resolveGlobalPackageRootCandidates({ explicitPrefixOnly: opts?.explicitPrefixOnly === true });
-}
 // ─── resolveProfilePackage ───────────────────────────────────────────────────
 /**
  * D-03's two-path resolution ladder. Attempt `require.resolve(pkgName +
  * '/package.json', { paths: [cwd] })` first and report `source: 'project'`;
- * on failure attempt the same with `paths: [root]` for each global candidate
- * root in order and report `source: 'global'`; otherwise `null`. The
+ * on failure attempt the same with `paths: [globalRoot]` when a global root
+ * was found and report `source: 'global'`; otherwise `null`. The
  * project-local hit always wins when both would resolve — the global
  * attempt is only ever reached when the project attempt threw.
  *
@@ -383,6 +503,37 @@ function resolveProfilePackage(pkgName, cwd, globalRoots) {
     }
     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):
@@ -428,7 +579,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
@@ -471,9 +632,8 @@ function flattenProfileDocument(doc) {
  */
 function profileValueDisposition(key, value) {
     try {
-        // The one boolean-typed member, disposed of before the string-only scalar
-        // guard below would reject its natural JSON form. Carried as the canonical
-        // string "true" / "false".
+        // 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) };
@@ -484,35 +644,16 @@ function profileValueDisposition(key, value) {
             }
             return { ok: false, reason: 'value must be the boolean true or false' };
         }
-        // The one list-typed member. Carried forward as a canonical JSON array
-        // string, so `contributes` stays a string map.
-        if (key === exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY) {
-            const list = Array.isArray(value) ? value : null;
-            if (list === null || list.length === 0) {
-                return { ok: false, reason: 'value must be a non-empty list of https URIs' };
-            }
-            if (list.length > exports.TRACE_ACCEPTED_PREDICATES_CAP) {
-                return { ok: false, reason: `value lists more than ${exports.TRACE_ACCEPTED_PREDICATES_CAP} URIs` };
-            }
-            const kept = [];
-            for (const item of list) {
-                if (typeof item !== 'string')
-                    return { ok: false, reason: 'every entry must be a string' };
-                const t = item.trim();
-                if (t.length > exports.TRACE_ACCEPTED_PREDICATE_MAX) {
-                    return { ok: false, reason: `an entry is longer than ${exports.TRACE_ACCEPTED_PREDICATE_MAX} characters` };
-                }
-                if (!/^https:\/\/[^\s\x00-\x1f\x7f"'<>`\\]+$/.test(t)) {
-                    return { ok: false, reason: 'every entry must be an https URI with no whitespace or quotes' };
-                }
-                if (!kept.includes(t))
-                    kept.push(t);
-            }
-            return { ok: true, value: JSON.stringify(kept) };
-        }
         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' };
@@ -580,14 +721,23 @@ function profileValueDisposition(key, value) {
  * The `_globalRoot` option is the repo's `_`-prefixed test seam convention
  * (as used by `_vault` / `_exec` / `_writeBack` in
  * `src/vault-command-router.cts`); production callers omit it and the
- * module walks `resolveGlobalPackageRootCandidates()`. Passing `_globalRoot`
+ * module calls `resolveGlobalPackageRoot()`. Passing `_globalRoot`
  * 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 = []) => ({
@@ -600,25 +750,62 @@ 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);
+        }
+        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);
@@ -628,11 +815,13 @@ function resolveOrgProfileDocument(cwd, opts) {
             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 ${probed} 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,
                 ],
             };
         }
@@ -737,6 +926,11 @@ 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 (RETIRED_PROFILE_KEYS.has(leaf.key))
+                continue;
             if (!exports.ORG_PROFILE_ALLOWLIST.includes(leaf.key)) {
                 ignored.push(leaf.key);
                 if (ignoredWarningCount < PROFILE_IGNORED_WARNING_CAP) {
@@ -819,52 +1013,99 @@ function readProfileValue(cwd, key, opts) {
         source: resolution.source,
     };
 }
+// ─── resolveVaultRequired (02-04, D-VH-4 / STRICT-01) ────────────────────────
 /**
- * The ONE ladder for `vault.required`, which `computeVaultVerdict` (the
- * verdict owner) and `vault org-profile` both read:
+ * 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".
  *
- * 1. The project's `.planning/config.json`. A present value wins, whatever
- *    it is: a JSON boolean is used as is; anything else is treated as false
- *    and reported as invalid (the gate card names it), never passed on to the
- *    profile — an explicit project value is the project's decision.
- * 2. The org profile, already narrowed to "true" / "false" by the value guard.
- * 3. The registered default, false.
+ * 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.
  *
- * Never throws.
+ * 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 resolveVaultRequired(cwd, opts) {
-    try {
-        const raw = cfgGet(cwd, exports.VAULT_REQUIRED_CONFIG_KEY, undefined);
-        if (raw !== undefined) {
-            return { required: raw === true, source: 'config', valid: typeof raw === 'boolean', raw, warnings: [] };
-        }
-        const profile = readProfileValue(cwd, exports.VAULT_REQUIRED_CONFIG_KEY, opts);
-        if (profile.value === 'true' || profile.value === 'false') {
-            return { required: profile.value === 'true', source: 'profile', valid: true, raw: undefined, warnings: profile.warnings };
-        }
-        return { required: false, source: 'default', valid: true, raw: undefined, warnings: profile.warnings };
-    }
-    catch {
-        return { required: false, source: 'default', valid: true, raw: undefined, warnings: [] };
+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;
 }
-// ─── resolveAcceptedTracePredicates ──────────────────────────────────────────
 /**
- * The extra practice-trace predicate types the org profile lists under
- * `vault.trace.accepted_predicates` — `[]` when there is no profile, the key is
- * absent, or its value was refused by the value guard. Org profile only: a
- * project config value is not read (the key is not a project setting). Never
- * throws.
+ * 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 resolveAcceptedTracePredicates(cwd, opts) {
+function resolveVaultRequired(cwd, opts) {
+    // Level 1 — project config, raw (ws then root, either dotted form).
+    let ignoredConfigValue;
+    let ignored = false;
     try {
-        const profile = readProfileValue(cwd, exports.VAULT_TRACE_ACCEPTED_PREDICATES_KEY, opts);
-        if (typeof profile.value !== 'string')
-            return [];
-        const parsed = JSON.parse(profile.value);
-        return Array.isArray(parsed) ? parsed.filter((v) => typeof v === 'string') : [];
+        // 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 {
-        return [];
+    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 });
 }