@pareto4/pp-core 1.18.0 → 1.19.0

package/pp-core/bin/lib/check-command-router.cjs

@@ -771,6 +771,57 @@ function cmdUiSafetyGate(projectDir, args, raw) {
     }
     output(computeUiSafetyGate(projectDir, phase), raw, undefined);
 }
+/** Subject types the TDD review gate looks for. */
+const TDD_GATE_TYPES = new Set(['test', 'feat', 'refactor']);
+/**
+ * Parse one commit message into the TDD gate keys it satisfies, each
+ * `<type>\0<plan id>`. The type comes from the Conventional Commit subject
+ * (`test(auth): …`, `test: …`, `test!: …`); the plan id from every
+ * `Phase: <id>` line in the message's last paragraph (the git trailer block).
+ * A subject whose scope IS the plan id (`test(01-02): …`, the convention
+ * before the trailer) yields that id too, so older history still counts.
+ */
+function tddGateKeys(message) {
+    const text = message.replace(/\r\n/g, '\n').trim();
+    const subject = text.split('\n', 1)[0] || '';
+    const m = /^([a-z]+)(?:\(([^)]*)\))?!?:/.exec(subject);
+    if (!m || !TDD_GATE_TYPES.has(m[1]))
+        return [];
+    const type = m[1];
+    const ids = new Set();
+    const paragraphs = text.split(/\n[ \t]*\n/);
+    if (paragraphs.length > 1) {
+        for (const line of paragraphs[paragraphs.length - 1].split('\n')) {
+            const t = /^Phase:[ \t]*(\S+)[ \t]*$/.exec(line);
+            if (t)
+                ids.add(t[1]);
+        }
+    }
+    // Legacy: a scope shaped like a plan id (starts with a digit), never a codebase noun.
+    if (m[2] && /^\d[\w.-]*$/.test(m[2].trim()))
+        ids.add(m[2].trim());
+    return [...ids].map((id) => `${type}\0${id}`);
+}
+/**
+ * Every TDD gate key satisfied by a commit that touches the working tree
+ * (`-- .`, as before), read in one `git log`. An unreadable history (no git,
+ * no commits) yields the empty set, so every gate reads as missing.
+ */
+function readTddGateCommits(projectDir) {
+    const keys = new Set();
+    let log = '';
+    try {
+        log = (0, node_child_process_1.execFileSync)('git', ['log', '--format=%x1e%B', '--', '.'], {
+            cwd: projectDir, encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch { /* git unavailable or no commits */ }
+    for (const record of log.split('\x1e')) {
+        for (const key of tddGateKeys(record))
+            keys.add(key);
+    }
+    return keys;
+}
 function cmdTddReviewCheckpoint(projectDir, args, raw) {
     // args[0] = 'check', args[1] = 'tdd-review-checkpoint' (normalized), args[2] = phase
     const phase = args[2] || '';
@@ -830,31 +881,19 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
         return;
     }
     // For each TDD plan, extract the plan ID (padded plan number) and check git log
+    const gateCommits = readTddGateCommits(projectDir);
     const rows = [];
     for (const planPath of tddPlanFiles) {
         // Extract plan ID from filename (e.g. "01-02-PLAN.md" → "01-02", or "03-PLAN.md" → "03")
         const basename = node_path_1.default.basename(planPath, '-PLAN.md');
         // planId for commit grep: phase-plan format, e.g. "01-02"
         const planId = basename;
-        // Check for RED gate commit: test({planId}):
-        let red = false;
-        let green = false;
-        let refactor = false;
-        try {
-            const redCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^test(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
-            red = redCommit.trim().length > 0;
-        }
-        catch { /* git unavailable or no match */ }
-        try {
-            const greenCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^feat(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
-            green = greenCommit.trim().length > 0;
-        }
-        catch { /* git unavailable or no match */ }
-        try {
-            const refactorCommit = (0, node_child_process_1.execFileSync)('git', ['log', '--oneline', `--grep=^refactor(${planId}):`, '--', '.'], { cwd: projectDir, encoding: 'utf-8', maxBuffer: 1024 * 1024, windowsHide: true });
-            refactor = refactorCommit.trim().length > 0;
-        }
-        catch { /* git unavailable or no match */ }
+        // Gate commits are found by type and the `Phase: {planId}` trailer — the
+        // scope names a part of the codebase, never the plan. A commit made before
+        // the trailer convention (`test({planId}): …`) still counts.
+        const red = gateCommits.has(`test\0${planId}`);
+        const green = gateCommits.has(`feat\0${planId}`);
+        const refactor = gateCommits.has(`refactor\0${planId}`);
         const missing = [];
         if (!red)
             missing.push('RED');
@@ -884,7 +923,7 @@ function cmdTddReviewCheckpoint(projectDir, args, raw) {
         table += '\n\n⚠ Gate violations are advisory — review before advancing.';
         for (const r of rows.filter(row => row.status === 'FAIL')) {
             table += `\n  Plan ${r.planId} missing: ${r.missing.join(', ')} gate commit(s).`;
-            table += `\n  Expected commit pattern: test(${r.planId}): ... → feat(${r.planId}): ...`;
+            table += `\n  Expected commits: test(<area>): ... → feat(<area>): ..., each with the trailer Phase: ${r.planId}`;
         }
     }
     const result = {
@@ -3154,6 +3193,7 @@ module.exports = {
     computeUiSafetyGate,
     cmdGapAnalysisPlanPost,
     cmdTddReviewCheckpoint,
+    tddGateKeys,
     cmdShipPlatformDrift,
     cmdVaultStatus,
     // Exported so tests HARVEST the volatility sentence rather than restating its

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

@@ -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/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}: ` : '';