@pareto4/pp-core 1.17.1 → 1.19.0

package/pp-core/bin/lib/clusters.cjs

@@ -45,8 +45,8 @@ exports.CLUSTERS = Object.freeze({
         'add-tests',
         'secure-phase',
         // Retroactive, non-gating review of a completed phase against the client
-        // vault's practices (Vault Assurance #71924, 06-07) — the same family as
-        // secure-phase / ui-review / validate-phase.
+        // vault's standards documents (`check vault-review`, a report) — the same
+        // family as secure-phase / ui-review / validate-phase.
         'vault-review',
     ]),
     milestone: Object.freeze([

package/pp-core/bin/lib/commands.cjs

@@ -14,7 +14,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output, error } = ioMod;
+const { output, error, ERROR_REASON } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig, isGitIgnored } = configLoaderMod;
@@ -423,10 +423,76 @@ function cmdEffortSync(cwd, raw, opts) {
     }
     output({ synced, skipped, changes, dry_run: dryRun, agents_dir: agentsDir }, raw, synced > 0 ? 'changed' : 'ok');
 }
-function cmdCommit(cwd, message, files, raw, amend, noVerify) {
+// ─── Commit trailers (Phase: / Quick:) ────────────────────────────────────────
+//
+// The Conventional Commit scope names a part of the codebase (`docs(planning)`,
+// `feat(auth)`), never a phase or plan number. The phase, plan or quick-task
+// identity a commit belongs to travels as ONE git trailer instead —
+// `Phase: 02-03`, `Phase: 02` or `Quick: <id>` — so readers find it with
+// `%(trailers:key=Phase)` rather than by parsing the subject.
+/** Loose id shape: digits, letters, dots, dashes, underscores; no whitespace. */
+const COMMIT_TRAILER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * Pull `--phase <id>` and `--quick <id>` (and their `--flag=<id>` forms) out of
+ * a `commit` / `commit-to-subrepo` argv, so neither the value nor the flag is
+ * taken for part of the message or for a `--files` path. A flag with no value
+ * yields the empty string, which `buildCommitTrailer` rejects.
+ */
+function extractCommitTrailerArgs(args) {
+    const rest = [];
+    let phase;
+    let quick;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const eq = /^--(phase|quick)=(.*)$/s.exec(a);
+        if (eq) {
+            if (eq[1] === 'phase')
+                phase = eq[2];
+            else
+                quick = eq[2];
+            continue;
+        }
+        if (a === '--phase' || a === '--quick') {
+            const next = args[i + 1];
+            const hasValue = next !== undefined && !next.startsWith('--');
+            const value = hasValue ? next : '';
+            if (hasValue)
+                i++;
+            if (a === '--phase')
+                phase = value;
+            else
+                quick = value;
+            continue;
+        }
+        rest.push(a);
+    }
+    return { args: rest, phase, quick };
+}
+/**
+ * The trailer paragraph for a commit, or null when neither id is given.
+ * Both ids may be given; they share one paragraph so git reads both as
+ * trailers. Errors (exit 1, reason `usage`) on an id that is empty or holds
+ * anything but letters, digits, dots, dashes or underscores — a newline in
+ * an id would otherwise forge further trailers.
+ */
+function buildCommitTrailer(opts) {
+    const lines = [];
+    for (const [key, flag, value] of [['Phase', '--phase', opts.phase], ['Quick', '--quick', opts.quick]]) {
+        if (value === undefined)
+            continue;
+        if (!COMMIT_TRAILER_ID_RE.test(value)) {
+            error(`${flag} must be a phase/plan or quick-task id such as 02 or 02-03 (letters, digits, dots, dashes; got ${JSON.stringify(value)})`, ERROR_REASON.USAGE);
+        }
+        lines.push(`${key}: ${value}`);
+    }
+    return lines.length > 0 ? lines.join('\n') : null;
+}
+function cmdCommit(cwd, message, files, raw, amend, noVerify, trailerIds = {}) {
     if (!message && !amend) {
         error('commit message required');
     }
+    // --amend keeps the previous message (--no-edit), so a trailer is ignored there.
+    const trailer = amend ? null : buildCommitTrailer(trailerIds);
     // Sanitize commit message: strip invisible chars and injection markers
     // that could hijack agent context when commit messages are read back
     let sanitizedMessage = message;
@@ -513,6 +579,9 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
     }
     // Commit (--no-verify skips pre-commit hooks, used by parallel executor agents)
     const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', sanitizedMessage];
+    // A second -m is its own paragraph, which git reads as the trailer block.
+    if (trailer)
+        commitArgs.push('-m', trailer);
     if (noVerify)
         commitArgs.push('--no-verify');
     const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd });
@@ -591,10 +660,11 @@ function groupFilesBySubrepo(files, subRepos) {
     }
     return { grouped, unmatched };
 }
-function cmdCommitToSubrepo(cwd, message, files, raw) {
+function cmdCommitToSubrepo(cwd, message, files, raw, trailerIds = {}) {
     if (!message) {
         error('commit message required');
     }
+    const trailer = buildCommitTrailer(trailerIds);
     const config = loadConfig(cwd);
     const subRepos = config['sub_repos'];
     if (!subRepos || subRepos.length === 0) {
@@ -617,7 +687,10 @@ function cmdCommitToSubrepo(cwd, message, files, raw) {
             (0, shell_command_projection_cjs_1.execGit)(['add', relativePath], { cwd: repoCwd });
         }
         // Commit
-        const commitResult = (0, shell_command_projection_cjs_1.execGit)(['commit', '-m', message], { cwd: repoCwd });
+        const commitArgs = ['commit', '-m', message];
+        if (trailer)
+            commitArgs.push('-m', trailer);
+        const commitResult = (0, shell_command_projection_cjs_1.execGit)(commitArgs, { cwd: repoCwd });
         if (commitResult.exitCode !== 0) {
             if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
                 repos[repo] = { committed: false, hash: null, files: repoFiles, reason: 'nothing_to_commit' };
@@ -1252,6 +1325,8 @@ module.exports = {
     cmdEffortSync,
     cmdCommit,
     cmdCommitToSubrepo,
+    extractCommitTrailerArgs,
+    buildCommitTrailer,
     cmdSummaryExtract,
     cmdWebsearch,
     cmdProgressRender,

package/pp-core/bin/lib/compose-bindings.cjs

@@ -31,8 +31,8 @@
  * `JSON.stringify`/object literals — never by `.md` shell string
  * concatenation.
  *
- * Its importers today are `src/vault-update.cts`, `src/init-contract.cts`,
- * `src/vault-practices.cts` and (quick 261003-lqi) `src/check-command-router.cts`
+ * Its importers today are `src/vault-update.cts`, `src/init-contract.cts`
+ * and (quick 261003-lqi) `src/check-command-router.cts`
  * — and this module imports none of them, so its top-level imports of `./org-profile.cjs`, `./platform-bindings.cjs`,
  * `./git-provider.cjs`, `./vault-coordinates.cjs`, `./io.cjs`,
  * `./project-root.cjs`, `./package-identity.cjs` and
@@ -54,6 +54,8 @@ exports.resolveLatestVaultTag = resolveLatestVaultTag;
 exports.resolvePlatformRepoUrl = resolvePlatformRepoUrl;
 exports.resolveLatestPlatformTag = resolveLatestPlatformTag;
 exports.resolveCreatedWithFrom = resolveCreatedWithFrom;
+exports.clientVaultChoice = clientVaultChoice;
+exports.validateClientVaultAnswer = validateClientVaultAnswer;
 exports.composeBindings = composeBindings;
 exports.redactComposeResultForEmission = redactComposeResultForEmission;
 exports.cmdComposeBindings = cmdComposeBindings;
@@ -579,7 +581,7 @@ function resolveCreatedWith() {
  * string. Every emitted field is one the schema's `additionalProperties:
  * false` property sets already allow.
  */
-function composeCandidate(cwd, seed, provider, opts) {
+function composeCandidate(cwd, seed, provider, opts, existingClient) {
     const candidate = {};
     const provenance = {};
     const warnings = [];
@@ -614,23 +616,37 @@ function composeCandidate(cwd, seed, provider, opts) {
     // client.name / client.slug (project-answer)
     setField('client.name', cfgGet(cwd, 'project.client_name', undefined), 'project-answer');
     setField('client.slug', cfgGet(cwd, 'project.client_slug', undefined), 'project-answer');
-    // client.vaultRepo / vaultRef / vaultHost (profile-seed)
-    setField('client.vaultRepo', seed.clientVaultRepo, 'profile-seed');
-    setField('client.vaultRef', seed.clientVaultRef, 'profile-seed');
-    setField('client.vaultHost', seed.clientVaultHost, 'profile-seed');
-    // client.vaultRef (resolved-tag) — FORK-ONLY (PBI 74316). When the seed
-    // names a vault repo but no ref, propose the repo's latest stable tag.
-    if (isUsableString(seed.clientVaultRepo) && !isUsableString(seed.clientVaultRef)) {
+    // client.vaultRepo (project-answer or profile-seed). The seeded ref and
+    // host describe the seeded repo, so they are proposed only while that repo
+    // is the one the binding will name.
+    const answerRepo = isUsableString(opts.clientVaultRepo) ? opts.clientVaultRepo.trim() : undefined;
+    const boundRepo = existingClient.vaultRepo ?? answerRepo ?? seed.clientVaultRepo;
+    const seedIsBound = answerRepo === undefined && boundRepo === seed.clientVaultRepo;
+    if (answerRepo !== undefined) {
+        setField('client.vaultRepo', answerRepo, 'project-answer');
+    }
+    else {
+        setField('client.vaultRepo', seed.clientVaultRepo, 'profile-seed');
+    }
+    if (seedIsBound) {
+        setField('client.vaultRef', seed.clientVaultRef, 'profile-seed');
+        setField('client.vaultHost', seed.clientVaultHost, 'profile-seed');
+    }
+    // client.vaultRef (resolved-tag) — FORK-ONLY (PBI 74316). When the bound
+    // vault repo has no ref yet, propose that repo's latest stable tag.
+    const boundRef = existingClient.vaultRef ?? (seedIsBound ? seed.clientVaultRef : undefined);
+    if (isUsableString(boundRepo) && !isUsableString(boundRef)) {
         if (opts.offline === true) {
             pushDeduped(warnings, [
                 bound('client.vaultRef was not proposed (offline) — the vault resolves "main" until the project is pinned with "pp-tools vault update <tag>".'),
             ]);
         }
         else {
-            const vaultHost = isUsableString(seed.clientVaultHost)
-                ? seed.clientVaultHost
-                : (hostRes.host ?? (0, vault_coordinates_cjs_1.defaultHostForProvider)(provider));
-            const vaultTag = resolveLatestVaultTag(seed.clientVaultRepo, vaultHost, provider, opts);
+            const vaultHost = existingClient.vaultHost ??
+                (seedIsBound && isUsableString(seed.clientVaultHost) ? seed.clientVaultHost : undefined) ??
+                hostRes.host ??
+                (0, vault_coordinates_cjs_1.defaultHostForProvider)(provider);
+            const vaultTag = resolveLatestVaultTag(boundRepo, vaultHost, provider, opts);
             pushDeduped(warnings, vaultTag.warnings);
             if (vaultTag.tag) {
                 setField('client.vaultRef', vaultTag.tag, 'resolved-tag');
@@ -746,6 +762,73 @@ function readExistingBindings(cwd) {
         };
     }
 }
+/** Read the usable `client.vault*` strings of an existing binding; the merge
+ * keeps them, so the ref proposal must follow the repo they name. */
+function existingVaultCoordinates(data) {
+    const client = data.client;
+    if (!isObject(client))
+        return {};
+    const out = {};
+    if (isUsableString(client.vaultRepo))
+        out.vaultRepo = client.vaultRepo;
+    if (isUsableString(client.vaultRef))
+        out.vaultRef = client.vaultRef;
+    if (isUsableString(client.vaultHost))
+        out.vaultHost = client.vaultHost;
+    return out;
+}
+/**
+ * Whether `/pp-init` asks for a client vault: whenever the project has none
+ * bound yet and a binding can be composed at all. Without a `platform.repo`
+ * from the org profile or an existing binding nothing is written (INIT-02),
+ * so an answer would be dropped silently. `defaultRepo` is the org
+ * profile's seeded vault a blank answer keeps, display-safe
+ * (`redactCoordinateForEmission`), or `null` when nothing is seeded and a
+ * blank answer binds no client vault. Never throws.
+ */
+function clientVaultChoice(cwd, opts = {}) {
+    try {
+        const seed = readSeed(cwd, opts).values;
+        const seedRepo = seed.clientVaultRepo;
+        const existing = readExistingBindings(cwd);
+        const existingPlatform = existing.data.platform;
+        const composable = isUsableString(seed.platformRepo) || (isObject(existingPlatform) && isUsableString(existingPlatform.repo));
+        const offered = composable && !existing.malformed && existingVaultCoordinates(existing.data).vaultRepo === undefined;
+        return { offered, defaultRepo: offered && isUsableString(seedRepo) ? String((0, platform_bindings_cjs_1.redactCoordinateForEmission)(seedRepo)) : null };
+    }
+    catch {
+        return { offered: false, defaultRepo: null };
+    }
+}
+// ─── validateClientVaultAnswer ────────────────────────────────────────────────
+/**
+ * Validate the `/pp-init` client-vault answer. Blank or `none` means "keep
+ * the org profile's seeded vault, if any" (`value: null`). Anything else must pass the
+ * seed scalar guard, `validateBindings`' own `client.vaultRepo` rule without
+ * its machine-specific warning, and carry nothing the emission redactor would
+ * hide, so this adds no second pattern for the field.
+ */
+function validateClientVaultAnswer(answer) {
+    if (typeof answer !== 'string' || answer.trim() === '' || answer.trim().toLowerCase() === 'none') {
+        return { ok: true, value: null };
+    }
+    const scalar = dispositionSeedValue(`${org_profile_cjs_1.ORG_PROFILE_SEED_SECTION}.client.vaultRef`, answer);
+    if (!scalar.ok)
+        return { ok: false, reason: scalar.reason };
+    const probe = (0, platform_bindings_cjs_1.validateBindings)({
+        schemaVersion: platform_bindings_cjs_1.CONTRACT_SCHEMA_VERSION,
+        platform: { repo: 'placeholder/placeholder' },
+        client: { vaultRepo: scalar.value },
+    });
+    // The binding is committed: a machine-specific path resolves nowhere else, and a credential would be published.
+    const vaultIssues = [...probe.errors, ...probe.warnings].filter((e) => leadingToken(e).startsWith('client.vaultRepo'));
+    if (vaultIssues.length > 0)
+        return { ok: false, reason: vaultIssues.join('; ') };
+    if ((0, platform_bindings_cjs_1.redactCoordinateForEmission)(scalar.value) !== scalar.value) {
+        return { ok: false, reason: 'a vault repo must not carry credentials — the binding is committed; use a credential helper' };
+    }
+    return { ok: true, value: scalar.value };
+}
 /**
  * D-08's absent-only merge. `merged` starts as a deep clone of `existing` —
  * every field the existing file already carries (including the provisional
@@ -816,9 +899,9 @@ function composeBindings(cwd, opts = {}) {
         pushDeduped(warnings, providerWarnings);
         const seedResult = readSeed(cwd, { _globalRoot: opts._globalRoot });
         pushDeduped(warnings, seedResult.warnings);
-        const candidateResult = composeCandidate(cwd, seedResult.values, provider, opts);
-        pushDeduped(warnings, candidateResult.warnings);
         const existing = readExistingBindings(cwd);
+        const candidateResult = composeCandidate(cwd, seedResult.values, provider, opts, existingVaultCoordinates(existing.data));
+        pushDeduped(warnings, candidateResult.warnings);
         pushDeduped(warnings, existing.warnings);
         if (existing.malformed) {
             return {

package/pp-core/bin/lib/config.cjs

@@ -527,7 +527,6 @@ function isStringMember(list, value) {
  */
 const BOOLEAN_ONLY_CONFIG_KEYS = Object.freeze([
     'vault.enabled',
-    'vault.practices_enabled',
     'vault.required',
     'workflow.schema_drift_gate',
     'workflow.nyquist_validation',
@@ -641,8 +640,8 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
         error(`Invalid plan_review.source_grounding_authority '${val}'. Valid values: ${VALID_SOURCE_GROUNDING_AUTHORITIES.join(', ')}`);
     }
     // Capability enum keys, in ONE place (Vault Assurance 13-05, D-07). Measured
-    // 2026-10-09: `config-set workflow.code_review_depth bogus` and
-    // `config-set vault.mode whatever` both wrote at exit 0, because no guard
+    // 2026-10-09: `config-set workflow.code_review_depth bogus` wrote at exit 0,
+    // because no guard
     // consulted the registry's declared `values`. This runs AFTER every
     // hand-coded guard above, so a key that already has its own guard
     // (`workflow.drift_action`) keeps its message byte-identical; the
@@ -653,9 +652,7 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     // The TYPE is checked before membership (13-REVIEW CR-01): a value starting
     // with `[` is JSON-parsed above, and `String(['standards']) === 'standards'`,
     // so a membership-only test let a one-element array through and wrote it —
-    // which `resolveVaultMode` then refused on every vault command, and which
-    // `federated-config` silently reads back as the default for the other enum
-    // keys. Every declared capability enum value is a string, so a non-string
+    // which `federated-config` silently reads back as the default. Every declared capability enum value is a string, so a non-string
     // parse (array, object, number, boolean) can never be a member.
     const enumValues = capabilityEnumValues(kp);
     if (enumValues && !isStringMember(enumValues, parsedValue)) {

package/pp-core/bin/lib/discovery-rollup.cjs

@@ -12,11 +12,12 @@
  * relation suffix (`refines` / `absorbed into`) whose target requirement ID
  * must exist in the same table. Grammar single-source: same reference file.
  *
- * Phase 3 (D-44), extended by Phase 4 (D-50): a Prefix Registry row may not
- * claim one of the six reserved prefixes (`D-` `A-` `SP-` `DG-` `RS-` `SCR-`)
- * — they all match the requirement-ID regex, so registering one collides with
- * the decision / action / sparring / data-gathering / research / screen ID
- * families. Reserved set single-source: same reference file.
+ * Phase 3 (D-44), extended by Phase 4 (D-50) and issue #12: a Prefix Registry
+ * row may not claim one of the seven reserved prefixes (`D-` `A-` `SP-` `DG-`
+ * `RS-` `SCR-` `PRC-`) — they all match the requirement-ID regex, so
+ * registering one collides with the decision / action / sparring /
+ * data-gathering / research / screen / process ID families. Reserved set
+ * single-source: same reference file.
  *
  * Fail-loud contract (D-08): any unparseable row, malformed/duplicate ID,
  * unknown prefix, out-of-enum MoSCoW/Disposition, or strike/disposition
@@ -46,7 +47,9 @@ const MOSCOW = Object.freeze({ MUST: 'Must', SHOULD: 'Should', COULD: 'Could', W
 // `SCR-<nn>` sequence, so an engagement registering `SCR-` as a domain prefix
 // would make `SCR-01` ambiguous between the screen inventory and the
 // requirements table.
-const RESERVED_PREFIXES = new Set(['D-', 'A-', 'SP-', 'DG-', 'RS-', 'SCR-']);
+// Issue #12 added `PRC-`: Session 2 numbers its Process Inventory `PRC-<nn>`,
+// which a later session cites beside requirement IDs.
+const RESERVED_PREFIXES = new Set(['D-', 'A-', 'SP-', 'DG-', 'RS-', 'SCR-', 'PRC-']);
 const ROW_ID_RE = /^([A-Z][A-Z0-9]*-)(\d+)$/;
 const DROPPED_RE = /^Dropped \((D-\d{2}-\d+)\)$/;
 const SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;

package/pp-core/bin/lib/discovery-screens.cjs

@@ -1287,6 +1287,23 @@ const SCAN_SKIP_DIRS = Object.freeze(new Set([
     '.next', '.nuxt', '.turbo', '.cache', 'coverage',
     '.venv', 'venv', '__pycache__', 'vendor', 'target',
 ]));
+/**
+ * True when `dir` holds a pp-core install (`<dir>/pp-core/VERSION`, the marker
+ * `update-context` reads): a project-local runtime directory such as
+ * `.claude` or `.codex`. The walk never enters one. Its engine files, agents
+ * and commands spell the instrumentation literals out, and none of it ships
+ * in the engagement's build, so walking it reports pp-core itself as a leak
+ * (issue #12, item 7). Keyed on the marker rather than on directory names so
+ * every runtime's install directory is covered without a third list of them.
+ */
+function isPpCoreInstallDir(dir) {
+    try {
+        return node_fs_1.default.statSync(node_path_1.default.join(dir, 'pp-core', 'VERSION')).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The file extensions the scan actually READS. An allowlist rather than a
  * denylist, because the bound has to hold for file types nobody has thought of
@@ -1475,7 +1492,8 @@ function loadScanAllowlist(loaded) {
  *   - every entry is resolved and confirmed strictly beneath the resolved
  *     project root before any stat or read, the same posture the roll-up
  *     traversal guard takes (T-04-16);
- *   - `SCAN_SKIP_DIRS` keeps the walk out of the dependency tree;
+ *   - `SCAN_SKIP_DIRS` keeps the walk out of the dependency tree, and
+ *     `isPpCoreInstallDir` out of a project-local pp-core install;
  *   - `SCAN_EXTENSIONS` bounds what is read;
  *   - the file and byte caps stop the walk.
  *
@@ -1536,7 +1554,7 @@ function scanBuildTree(cwd, options = {}) {
             if (stat.isSymbolicLink())
                 continue;
             if (stat.isDirectory()) {
-                if (!SCAN_SKIP_DIRS.has(name))
+                if (!SCAN_SKIP_DIRS.has(name) && !isPpCoreInstallDir(full))
                     stack.push(full);
                 continue;
             }

package/pp-core/bin/lib/discovery-sweep.cjs

@@ -63,12 +63,21 @@ function parseAttrs(src) {
     }
     return attrs;
 }
-function isFunctional(tag, attrs) {
+/**
+ * A multi-word PascalCase name (`UiButton`, `UiSelect`): the component spelling
+ * of a kebab-case custom element (`ui-button`), which a string template keeps
+ * and lowercasing would hide (issue #12, item 8). A single word (`Div`) or an
+ * all-caps tag (`BUTTON`) is plain HTML.
+ */
+function isPascalComponent(rawTag) {
+    return /^[A-Z][a-z0-9]+[A-Z]/.test(rawTag);
+}
+function isFunctional(tag, attrs, rawTag = tag) {
     if (attrs.has('data-req'))
         return true;
     if (tag === 'input' && (attrs.get('type') || '').toLowerCase() === 'hidden')
         return false;
-    if (FUNCTIONAL_TAGS.has(tag) || tag.includes('-'))
+    if (FUNCTIONAL_TAGS.has(tag) || tag.includes('-') || isPascalComponent(rawTag))
         return true;
     const role = (attrs.get('role') || '').toLowerCase();
     return FUNCTIONAL_ROLES.has(role);
@@ -107,7 +116,7 @@ function scanPage(page, html, violations) {
         const parentScreen = stack.length ? stack[stack.length - 1].screen : null;
         const screen = screenFrom(tag, attrs) ?? parentScreen;
         const line = lineAt(text, m.index);
-        if (isFunctional(tag, attrs)) {
+        if (isFunctional(tag, attrs, m[2])) {
             const id = attrs.get('id') ?? null;
             let reqs = [];
             if (attrs.has('data-req')) {

package/pp-core/bin/lib/discovery-vault-check.cjs

@@ -12,7 +12,11 @@
  *   - every entry is one well-formed line (`- `<path>` — <why>`, or
  *     `- (none) — <why>` when nothing was selected);
  *   - every selected document was USED: cited `[vault: <path>]` somewhere in
- *     the session notes, or marked `— not used: <reason>` on its own line.
+ *     the session notes, or marked `— not used: <reason>` on its own line;
+ *   - when the selection used `INDEX.md`, every entry the vault marks
+ *     `[cross-cutting]` has a record line (issue #12, items 16-17): those rules
+ *     bind every session, so leaving one out is how an approval route went
+ *     unseen until Session 12.
  *
  * The selection itself is the facilitator's judgement and is not re-derived
  * here; what is checked is that the record exists, is complete, and that what
@@ -109,7 +113,7 @@ function parseEntry(n, text) {
  * A citation counts only OUTSIDE the section: the record naming a path is not
  * evidence that the path was used.
  */
-function checkVaultContext(content) {
+function checkVaultContext(content, crossCutting = []) {
     const violations = [];
     const section = extractSection(content);
     if (section === null) {
@@ -163,8 +167,38 @@ function checkVaultContext(content) {
             violations.push({ reason: 'document_unused', line: doc.line, path: doc.path });
         }
     }
+    // The cross-cutting entries are owed a line only when the selection read the
+    // vault's own index: SUMMARY.md carries no mark, and `none` read nothing.
+    if (index === 'INDEX.md') {
+        const recorded = new Set(docs.map((d) => d.path));
+        for (const p of crossCutting) {
+            if (!recorded.has(p))
+                violations.push({ reason: 'cross_cutting_missing', path: p });
+        }
+    }
     return { ok: violations.length === 0, index, documents: docs.length, cited, not_used: notUsed, violations };
 }
+/**
+ * The paths the cached `INDEX.md` marks `[cross-cutting]`, read through the
+ * vault's one index-state function so the bounded read, the withheld filter
+ * and the path rule are the engine's own. Withheld entries never reach it;
+ * unsafe ones are dropped, since no record line could name them. A vault that
+ * is off, uncached or unreadable owes nothing here — `vault status` reports
+ * that state.
+ */
+function crossCuttingPaths(cwd) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const vault = require('./vault.cjs');
+        const state = vault.computeVaultIndexState(cwd);
+        if (state === null)
+            return [];
+        return state.entries.filter((e) => e.crossCutting === true && e.resolution !== 'unsafe').map((e) => e.path);
+    }
+    catch {
+        return [];
+    }
+}
 /** Parse the session argument: a bare integer 1–13, leading zeros allowed (`03` is session 3). */
 function parseSessionArg(raw) {
     if (typeof raw !== 'string' || !/^\d{1,3}$/.test(raw))
@@ -189,7 +223,7 @@ function checkSessionVaultContext(cwd, n) {
             violations: [{ reason: 'session_file_missing' }],
         };
     }
-    return { session: n, file: rel, ...checkVaultContext(content) };
+    return { session: n, file: rel, ...checkVaultContext(content, crossCuttingPaths(cwd)) };
 }
 function formatViolation(v) {
     const where = v.line !== undefined ? `line ${v.line}: ` : '';

package/pp-core/bin/lib/git-base-branch.cjs

@@ -118,12 +118,11 @@ function isPlausibleBranchRef(value) {
 }
 /**
  * WHAT A CALLER SAYS WHEN THE OVERRIDE IS REFUSED. One sentence, exported, for
- * every channel — three call sites state it and none of them spells it.
+ * every channel — a caller states it and never spells it.
  *
  * A second spelling of this sentence would be a second definition of what the
- * mechanism did, and this phase has already paid for that twice. The
- * `check vault-review` payload, the `check vault.audit` notes and the
- * `check ship.practices` message all carry these exact bytes.
+ * mechanism did, so every channel that states the refusal carries these exact
+ * bytes.
  *
  * The reason carries NO copy of the refused value: the value is client-supplied
  * and one of its shapes is an absolute filesystem path, so echoing it back onto
@@ -296,15 +295,13 @@ function resolveBaseBranchResult(cwd, deps) {
  * Consults the full precedence ladder and always returns a non-empty string.
  * Never throws.
  *
- * The bare-string form. EVERY consumer that computes a range now takes
- * `resolveBaseBranchResult` instead and states the refusal (W16): the two that
- * took this wrapper — `vault-audit.cts`, which is the shipped BLOCKING command,
- * and `cmdShipPractices`, a declared ship:pre gate — refused in silence, so a
- * gate ran over a range the project never configured and reported success on
- * it. What remains here is `cmdGitBaseBranch`, whose entire contract is one
- * branch name on stdout and which therefore genuinely has nowhere to put a
- * sentence. A new caller reaching for this form should ask whether that is true
- * of it as well; if it has a channel, it owes the operator the reason.
+ * The bare-string form. A consumer that computes a range takes
+ * `resolveBaseBranchResult` instead and states the refusal (W16): a gate that
+ * refused in silence would run over a range the project never configured and
+ * report success on it. What remains here is `cmdGitBaseBranch`, whose entire
+ * contract is one branch name on stdout and which therefore genuinely has
+ * nowhere to put a sentence. A new caller reaching for this form should ask
+ * whether that is true of it as well; if it has a channel, it owes the operator the reason.
  */
 function resolveBaseBranch(cwd, deps) {
     return resolveBaseBranchResult(cwd, deps).branch;

package/pp-core/bin/lib/git-provider.cjs

@@ -14,9 +14,9 @@
  * provider, what environment a clone needs, and whether a host CLI (`glab`)
  * may be spawned at all. It imports node builtins plus `./org-profile.cjs` —
  * still never `./vault.cjs`, `./vault-coordinates.cjs`, `./io.cjs` or
- * `./shell-command-projection.cjs` — so that both `src/vault.cts` and
- * `src/vault-write-back.cts` can import it (since 30-02 and 30-03) without
- * forming a require cycle in the CommonJS graph `require()` loads.
+ * `./shell-command-projection.cjs` — so that `src/vault.cts`, the vault write
+ * path and the other vault modules can import it without forming a require
+ * cycle in the CommonJS graph `require()` loads.
  * `./org-profile.cjs` is the one exception: it is itself a zero-import leaf
  * (node builtins only, see its own header), so importing it here creates no
  * load-time cycle even though it lazily requires this module back at
@@ -176,9 +176,8 @@ const compiledLiteralCloneTargetPatterns = exports.LITERAL_CLONE_TARGET_PATTERNS
  * absolute path, a scheme-qualified URL, or scp-style `user@host:path` —
  * rather than a `group/project` slug that must be composed onto a host.
  *
- * This is now the SINGLE definition. `src/vault.cts` and
- * `src/vault-write-back.cts` import it from here (30-02, 30-03) rather than
- * each keeping a copy — a read/write divergence in this predicate was defect
+ * This is now the SINGLE definition. `src/vault.cts` imports it from here
+ * (30-02) rather than keeping a copy — a read/write divergence in this predicate was defect
  * P-1 in Phase 29 (the write path used the value verbatim while the read path
  * always composed a URL, so a slug broke writing and a path broke reading).
  *