@pareto4/pp-core 1.12.1 → 1.17.1

package/scripts/changeset/cli.cjs

@@ -90,11 +90,12 @@ function parseArgs(argv) {
   return { ok: true, opts };
 }
 
-// Bare-checkout verify. A release tag job may run `verify` on a bare checkout:
-// no `npm ci`, no `build:lib`, and the compiled semver module under
-// pp-core/bin/lib is gitignored build output. Requiring that module at the top
-// of this file made `verify` (and `render`) die at require time on such a
-// checkout.
+// Release tag gate (#71924 gap plan 01-06). CI's
+// `tag_version_check` job runs `verify` on a bare checkout: no `npm ci`, no
+// `build:lib`, and the compiled semver module under pp-core/bin/lib is
+// gitignored build output. The first shipped version of that step required the
+// compiled module at the top of this file, so it died at require time on every
+// hosted checkout (never observed live: the step was skipped on every probe).
 // `verify` and `render` therefore require node builtins and tracked files only;
 // the compiled dependency is loaded lazily by `extract`, which the update
 // workflow runs on built trees.

package/scripts/changeset/new.cjs

@@ -4,56 +4,42 @@
 /**
  * Scaffolds a new changeset fragment (#2975).
  *
- *   npm run changeset -- --type Fixed --pr 1234 --body "fix the thing"
+ *   npm run changeset -- --type Fixed --pr 1234 --body "fix the thing" [--name <slug>]
  *
- * Writes `.changeset/<adjective>-<noun>-<noun>.md` with frontmatter
- * + body. The random three-word filename minimizes filename collision
- * across concurrent PRs.
+ * Writes `.changeset/<pr>-<slug>.md` with frontmatter + body. The slug is
+ * --name, else derived from the bold lead sentence; a taken name gets -2, -3, ...
+ * FORK-ONLY (PBI 74336): upstream draws a random three-word name.
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
 const { ExitError, runMain } = require('../lib/cli-exit.cjs');
 
-// Small word lists — keep the function simple and dependency-free.
-// Together this gives ~40 * 40 * 40 = 64,000 distinct names. The lint
-// rejects any duplicate filename, so collisions are caught even when
-// the random draw repeats.
-const ADJECTIVES = [
-  'silly', 'brave', 'calm', 'eager', 'gentle', 'happy', 'jolly', 'kind',
-  'lively', 'merry', 'nimble', 'plucky', 'quick', 'sturdy', 'witty', 'zesty',
-  'bold', 'clever', 'daring', 'fierce', 'graceful', 'humble', 'lucky', 'noble',
-  'proud', 'rapid', 'sharp', 'tidy', 'vivid', 'wise', 'agile', 'curious',
-  'eager', 'gallant', 'mellow', 'patient', 'serene', 'steady', 'sturdy', 'sunny',
-];
-const NOUNS_A = [
-  'bears', 'birds', 'cats', 'dogs', 'elks', 'foxes', 'goats', 'hawks',
-  'ibex', 'jays', 'koalas', 'lynx', 'moles', 'newts', 'otters', 'pumas',
-  'quails', 'rams', 'seals', 'tigers', 'voles', 'wolves', 'yaks', 'zebras',
-  'badgers', 'cranes', 'deer', 'eagles', 'finches', 'geese', 'herons', 'jaguars',
-  'lemurs', 'mice', 'orcas', 'pandas', 'ravens', 'sloths', 'tunas', 'wasps',
-];
-const NOUNS_B = [
-  'dance', 'sing', 'leap', 'run', 'jump', 'climb', 'fly', 'swim',
-  'rest', 'wake', 'roam', 'greet', 'wander', 'gather', 'forage', 'travel',
-  'glide', 'sprint', 'tumble', 'wave', 'cheer', 'rally', 'parade', 'march',
-  'hop', 'frolic', 'caper', 'romp', 'zip', 'dart', 'snooze', 'munch',
-  'chatter', 'squeak', 'howl', 'bark', 'purr', 'roar', 'hum', 'click',
-];
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_STOPWORDS = new Set(['a', 'an', 'the', 'and', 'or', 'of', 'to', 'for', 'in', 'on', 'is', 'are', 'now', 'its']);
+const SLUG_MAX_WORDS = 7;
 
-function pick(arr) {
-  return arr[Math.floor(Math.random() * arr.length)];
+// Kebab-case slug from the bold lead sentence (or the first sentence), minus filler words.
+function deriveFragmentSlug(body) {
+  const bold = /\*\*([^*]+)\*\*/.exec(body || '');
+  const lead = bold ? bold[1] : String(body || '').trim().split(/[.!?\n]/)[0];
+  const words = lead
+    .toLowerCase()
+    .replace(/'s\b/g, '')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w && !SLUG_STOPWORDS.has(w));
+  return words.slice(0, SLUG_MAX_WORDS).join('-') || 'change';
 }
 
-function generateFragmentName() {
-  return `${pick(ADJECTIVES)}-${pick(NOUNS_A)}-${pick(NOUNS_B)}`;
+function fragmentBaseName({ pr, body, name }) {
+  return `${pr}-${name || deriveFragmentSlug(body)}`;
 }
 
 // Allowed Keep-a-Changelog section types. Used by both scaffoldFragment
 // (sanitization at write time) and parse.cjs (validation at consume time).
 const ALLOWED_TYPES = new Set(['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']);
 
-function scaffoldFragment({ repo, type, pr, body }) {
+function scaffoldFragment({ repo, type, pr, body, name = null }) {
   // Sanitize: reject any type value not on the allowlist BEFORE embedding it
   // in frontmatter. A newline in `type` would corrupt the fragment; an
   // unrecognized value would be rejected later by parse.cjs but with a
@@ -63,28 +49,24 @@ function scaffoldFragment({ repo, type, pr, body }) {
       `scaffoldFragment: type=${JSON.stringify(type)} is not one of [${[...ALLOWED_TYPES].join(', ')}]`,
     );
   }
+  if (name !== null && !SLUG_RE.test(name)) {
+    throw new Error(`scaffoldFragment: name=${JSON.stringify(name)} is not kebab-case (a-z, 0-9, hyphens)`);
+  }
   const dir = path.join(repo, '.changeset');
   fs.mkdirSync(dir, { recursive: true });
   const content = `---\ntype: ${type}\npr: ${pr}\n---\n${body}\n`;
-  // Atomic create: writeFileSync with `flag: 'wx'` fails (EEXIST) when the
-  // file already exists, so concurrent invocations can't race past
-  // `existsSync` and overwrite each other. Re-roll the random name on
-  // collision; fail loudly after exhausting the retry budget.
-  for (let i = 0; i < 16; i++) {
-    const name = generateFragmentName();
-    const target = path.join(dir, `${name}.md`);
+  // flag 'wx' fails with EEXIST instead of overwriting, so concurrent runs cannot clobber a fragment.
+  const base = fragmentBaseName({ pr, body, name });
+  for (let i = 1; i <= 50; i++) {
+    const target = path.join(dir, `${i === 1 ? base : `${base}-${i}`}.md`);
     try {
       fs.writeFileSync(target, content, { flag: 'wx' });
       return target;
     } catch (e) {
       if (e.code !== 'EEXIST') throw e;
-      // collision — try another random draw
     }
   }
-  throw new Error(
-    'scaffoldFragment: 16 random filename draws all collided; ' +
-    'expand the word lists or investigate corrupted .changeset/ state',
-  );
+  throw new Error(`scaffoldFragment: ${base}.md and 49 numbered variants already exist; pass --name`);
 }
 
 function parseArgs(argv) {
@@ -102,7 +84,7 @@ function parseArgs(argv) {
 
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--type' || a === '--pr' || a === '--body' || a === '--repo') {
+    if (a === '--type' || a === '--pr' || a === '--body' || a === '--name' || a === '--repo') {
       const r = requireValue(a, i);
       if (!r.ok) return { ok: false, error: r.error };
       if (a === '--type') opts.type = r.value;
@@ -114,6 +96,7 @@ function parseArgs(argv) {
         const trimmed = r.value.trim();
         opts.pr = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
       } else if (a === '--body') opts.body = r.value;
+      else if (a === '--name') opts.name = r.value;
       else if (a === '--repo') opts.repo = r.value;
       i++;
       continue;
@@ -127,7 +110,7 @@ function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if (!parsed.ok) {
     process.stderr.write(`${parsed.error}\n`);
-    process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."\n');
+    process.stderr.write('usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..." [--name <slug>]\n');
     throw new ExitError(2);
   }
   const { opts } = parsed;
@@ -140,7 +123,7 @@ function main() {
   const prMissing = opts.pr === null;
   const prNaN = typeof opts.pr === 'number' && Number.isNaN(opts.pr);
   if (!opts.type || prMissing || prNaN || !opts.body) {
-    throw new ExitError(2, 'usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."');
+    throw new ExitError(2, 'usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..." [--name <slug>]');
   }
   const file = scaffoldFragment(opts);
   process.stdout.write(`${path.relative(process.cwd(), file)}\n`);
@@ -148,4 +131,4 @@ function main() {
 
 if (require.main === module) runMain(main);
 
-module.exports = { generateFragmentName, scaffoldFragment, parseArgs, ALLOWED_TYPES };
+module.exports = { deriveFragmentSlug, fragmentBaseName, scaffoldFragment, parseArgs, ALLOWED_TYPES };

package/scripts/dev-env.cjs

@@ -2,16 +2,16 @@
 'use strict';
 
 /**
- * dev-env.cjs — keep a stable pp-core install and a development build apart.
+ * dev-env.cjs — keep the global pp-core install and a development build apart.
+ * FORK-ONLY (PBI 74336)
  *
- *   stable [<tag>] [--dir <dir>] [--runtime <id>]  worktree on the latest release tag, installed --global
+ *   setup [--runtime <id>]                      build this checkout on its current branch, installed --global
  *   dev-setup [--config-dir <dir>] [--no-shell] npm ci, install the dev profile, put claude-dev on PATH
  *   install [--config-dir <dir>] [--no-build]   build, install into a separate Claude profile
  *   install --local [<dir>] [--no-build]        build, install into a sandbox project
  *   claude [--config-dir <dir>] [-- <args>]     start the Claude CLI on the dev profile
  *
- * Defaults: the worktree is pp-core-stable next to the main checkout; the profile is
- * PP_DEV_CONFIG_DIR, else ~/.claude-dev; the sandbox is ../pp-sandbox.
+ * Defaults: the profile is PP_DEV_CONFIG_DIR, else ~/.claude-dev; the sandbox is ../pp-sandbox.
  */
 
 const fs = require('node:fs');
@@ -25,27 +25,21 @@ const INSTALLER = path.join(ROOT, 'bin', 'install.js');
 
 const USAGE = [
   'Usage:',
-  '  npm run setup [-- [<tag>] [--dir <dir>] [--runtime <id>]]',
+  '  npm run setup [-- --runtime <id>]',
   '  npm run dev:setup [-- [--config-dir <dir>] [--no-shell]]',
   '  npm run dev:install [-- [--config-dir <dir>] [--no-build]]',
   '  npm run dev:install -- --local [<dir>] [--no-build]',
   '  npm run dev:claude [-- <claude args>]',
 ].join('\n');
 
-function parseStableArgs(rest) {
-  const opts = { command: 'stable', tag: null, dir: null, runtime: 'claude' };
+function parseSetupArgs(rest) {
+  const opts = { command: 'setup', runtime: 'claude' };
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
-    if (arg === '--dir') {
-      const value = rest[++i];
-      if (!value) return { error: '--dir requires a path' };
-      opts.dir = value;
-    } else if (arg === '--runtime') {
+    if (arg === '--runtime') {
       const value = rest[++i];
       if (!value) return { error: '--runtime requires a runtime id' };
       opts.runtime = value;
-    } else if (!arg.startsWith('-') && opts.tag === null) {
-      opts.tag = arg;
     } else {
       return { error: `unknown option: ${arg}` };
     }
@@ -72,7 +66,7 @@ function parseDevSetupArgs(rest) {
 
 function parseArgs(argv) {
   const [command, ...rest] = argv;
-  if (command === 'stable') return parseStableArgs(rest);
+  if (command === 'setup') return parseSetupArgs(rest);
   if (command === 'dev-setup') return parseDevSetupArgs(rest);
   if (command !== 'install' && command !== 'claude') {
     return { error: `unknown command: ${command === undefined ? '(none)' : command}` };
@@ -133,7 +127,7 @@ function resolveLocalDir(opts, root = ROOT) {
   return path.resolve(opts.localDir || path.join(root, '..', 'pp-sandbox'));
 }
 
-// The stable profile is ~/.claude; overwriting it with a dev build is what this script exists to avoid.
+// ~/.claude holds the global install from npm run setup; the dev routes never write there.
 function assertNotStableProfile(dir, home = os.homedir()) {
   if (samePath(dir, path.join(home, '.claude'))) {
     throw new ExitError(1, `Refusing to install a dev build into the stable profile ${dir}.`);
@@ -167,23 +161,6 @@ function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
-// Highest vX.Y.Z (or X.Y.Z) tag; pre-release tags are skipped.
-function pickLatestTag(tags) {
-  const parsed = tags
-    .map((tag) => ({ tag, m: /^v?(\d+)\.(\d+)\.(\d+)$/.exec(tag) }))
-    .filter((t) => t.m)
-    .map((t) => ({ tag: t.tag, v: t.m.slice(1).map(Number) }));
-  parsed.sort((a, b) => b.v[0] - a.v[0] || b.v[1] - a.v[1] || b.v[2] - a.v[2]);
-  return parsed.length ? parsed[0].tag : null;
-}
-
-// Next to the main checkout, so running this from any worktree finds the same directory.
-function resolveStableDir(opts, repo = ROOT) {
-  if (opts.dir) return path.resolve(opts.dir);
-  const commonDir = path.resolve(repo, git(['rev-parse', '--git-common-dir'], repo));
-  return path.join(path.dirname(commonDir), '..', 'pp-core-stable');
-}
-
 // The runtimes install.js takes as --<id>, read from the capability manifests so no build is needed.
 function listRuntimes(root = ROOT) {
   const capDir = path.join(root, 'capabilities');
@@ -206,57 +183,22 @@ function resolveRuntime(id, root = ROOT) {
   return found;
 }
 
-function listWorktrees(repo) {
-  return git(['worktree', 'list', '--porcelain'], repo)
-    .split(/\r?\n/)
-    .filter((line) => line.startsWith('worktree '))
-    .map((line) => path.resolve(line.slice('worktree '.length)));
-}
-
-// Adds the worktree at the tag, or moves an existing clean one to it; never touches your own checkout.
-function prepareStableWorktree({ repo, dir, tag }) {
-  try {
-    git(['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`], repo);
-  } catch {
-    throw new ExitError(1, `Tag ${tag} does not exist in ${repo}.`);
-  }
-  let known = listWorktrees(repo).some((w) => samePath(w, dir));
-  // A worktree folder deleted by hand stays registered; prune it so it is added again.
-  if (known && !fs.existsSync(dir)) {
-    git(['worktree', 'prune'], repo);
-    known = false;
-  }
-  if (!known) {
-    if (fs.existsSync(dir)) {
-      throw new ExitError(1, `${dir} exists but is not a worktree of ${repo}; pass --dir <other dir>.`);
-    }
-    git(['worktree', 'add', '--detach', dir, tag], repo);
-    return;
-  }
-  if (git(['status', '--porcelain'], dir) !== '') {
-    throw new ExitError(1, `The stable worktree ${dir} has local changes; commit or discard them first.`);
-  }
-  git(['checkout', '--quiet', '--detach', tag], dir);
-}
-
-function installStable(opts) {
+// Installs the checkout this runs from, so the global install follows its current branch.
+function installSetup(opts) {
   const runtime = resolveRuntime(opts.runtime);
   npmCliPath();
-  const dir = resolveStableDir(opts);
-  try {
-    git(['fetch', '--tags', '--quiet', 'origin'], ROOT);
-  } catch {
-    process.stderr.write('Could not fetch tags from origin; using the tags already in this clone.\n');
-  }
-  const tag = opts.tag || pickLatestTag(git(['tag', '--list'], ROOT).split(/\r?\n/));
-  if (!tag) throw new ExitError(1, 'No release tag found; pass one: npm run setup -- <tag>.');
-  prepareStableWorktree({ repo: ROOT, dir, tag });
-  process.stdout.write(`Stable worktree ${dir} is on ${tag}.\n`);
-  runNpm(['ci'], dir);
-  runNpm(['run', 'build'], dir);
-  execFileSync(process.execPath, [path.join(dir, 'bin', 'install.js'), `--${runtime.id}`, '--global'], { cwd: dir, stdio: 'inherit' });
+  runNpm(['ci'], ROOT);
+  runBuild();
+  execFileSync(process.execPath, [INSTALLER, `--${runtime.id}`, '--global'], { cwd: ROOT, stdio: 'inherit' });
   const again = runtime.id === 'claude' ? 'npm run setup' : `npm run setup -- --runtime ${runtime.id}`;
-  process.stdout.write(`\npp-core ${tag} is installed as the global pp-core for ${runtime.title}. Update later with: ${again}\n`);
+  process.stdout.write(`
+pp-core from ${describeCheckout(devBuildInfo())} is installed as the global pp-core for ${runtime.title}. Update later with: ${again}
+`);
+}
+
+function describeCheckout(info) {
+  const ref = info.commit ? `${info.branch || 'detached HEAD'}@${info.commit}` : info.checkout;
+  return info.dirty ? `${ref} (with uncommitted changes)` : ref;
 }
 
 // The statusline shows a DEV badge with this build's branch and commit when this file is present.
@@ -429,7 +371,7 @@ function main(argv = process.argv.slice(2)) {
   if (opts.error) throw new ExitError(2, `${opts.error}\n${USAGE}`);
   if (opts.command === 'claude') return launchClaude(opts);
   if (opts.command === 'dev-setup') devSetup(opts);
-  else if (opts.command === 'stable') installStable(opts);
+  else if (opts.command === 'setup') installSetup(opts);
   else if (opts.local) installSandbox(opts);
   else installProfile(opts);
   return 0;
@@ -441,9 +383,9 @@ module.exports = {
   parseArgs,
   resolveConfigDir,
   resolveLocalDir,
-  resolveStableDir,
   resolveLaunchDir,
   devBuildInfo,
+  describeCheckout,
   renderRcLauncher,
   upsertLauncher,
   windowsLauncherDir,
@@ -452,10 +394,8 @@ module.exports = {
   writeWindowsLaunchers,
   pathHasEntry,
   appendPathEntry,
-  pickLatestTag,
   listRuntimes,
   resolveRuntime,
-  prepareStableWorktree,
   assertNotStableProfile,
   assertOutsideRepo,
   samePath,

package/scripts/gen-capability-registry.cjs

@@ -568,6 +568,18 @@ function validateFeatureBody(cap) {
     }
   }
 
+  // Quick 261015-ect (QD-13): requiresPlatformBindings, optional. When present it
+  // must be a boolean; the loop resolver drops every hook of a capability that
+  // declares `true` on a project with no .platform-bindings.json. Which
+  // capabilities MUST declare it is a cross-capability rule
+  // (validatePlatformBindingsField).
+  if (cap.requiresPlatformBindings !== undefined && typeof cap.requiresPlatformBindings !== 'boolean') {
+    errors.push(
+      'capability "' + (cap.id || '(unknown)') + '" requiresPlatformBindings must be a boolean (got: ' +
+      JSON.stringify(cap.requiresPlatformBindings) + ')',
+    );
+  }
+
   return errors;
 }
 
@@ -1319,6 +1331,177 @@ function validateAgainstContract(cap, capId, knownAgentIds) {
   return errors;
 }
 
+/**
+ * Phase 15 D-02: validate the per-hook `vaultMode` filter field.
+ *
+ * The pure loop resolver evaluates `vaultMode` against an injected mode value
+ * and never emits it, so an unknown or misplaced value must be refused HERE,
+ * at generation, never interpreted at runtime. Three rules, each reported on
+ * its own:
+ *   (a) the field is allowed on contributions and gates only (a step is
+ *       refused);
+ *   (b) the value must be a string in the vault capability's declared
+ *       `config["vault.mode"].values`. That enum declaration is the ONE owner of
+ *       the closed set; it is read here, never restated. With no vault
+ *       capability, or no such values array, there is no closed set and every
+ *       `vaultMode` is refused (fail closed);
+ *   (c) the declaring capability must be `vault` or list `vault` in `requires`,
+ *       so a filtered hook can only exist where the vault gate's closure holds.
+ *
+ * Presence is own-property presence, so a JSON `null` is refused under (b).
+ *
+ * @param {Map<string, object>} capMap
+ * @returns {string[]} error strings; empty = all pass
+ */
+function validateVaultModeField(capMap) {
+  const errors = [];
+  const vaultCap = capMap.get('vault');
+  const modeDecl = vaultCap && vaultCap.config && typeof vaultCap.config === 'object'
+    ? vaultCap.config['vault.mode']
+    : undefined;
+  const allowed = modeDecl && Array.isArray(modeDecl.values)
+    ? modeDecl.values.filter((v) => typeof v === 'string')
+    : null;
+  const KINDS = [['steps', 'step'], ['contributions', 'contribution'], ['gates', 'gate']];
+  for (const [capId, cap] of capMap) {
+    if (!cap || typeof cap !== 'object') continue;
+    const prefix = 'capability "' + capId + '"';
+    const requiresVault = Array.isArray(cap.requires) && cap.requires.includes('vault');
+    for (const [arrKey, kind] of KINDS) {
+      const arr = Array.isArray(cap[arrKey]) ? cap[arrKey] : [];
+      for (const hook of arr) {
+        if (!hook || typeof hook !== 'object') continue;
+        if (!Object.prototype.hasOwnProperty.call(hook, 'vaultMode')) continue;
+        const where = prefix + ' ' + kind + ' at point "' + String(hook.point) + '"';
+        const value = hook.vaultMode;
+        if (kind === 'step') {
+          errors.push(where + ': vaultMode is allowed on contributions and gates only');
+        }
+        if (allowed === null) {
+          errors.push(
+            where + ': vaultMode ' + JSON.stringify(value) + ' cannot be checked: the vault capability ' +
+            'declares no "vault.mode" values, which own the closed set',
+          );
+        } else if (typeof value !== 'string' || !allowed.includes(value)) {
+          errors.push(
+            where + ': vaultMode ' + JSON.stringify(value) + ' is not one of [' + allowed.join(', ') +
+            '] (the closed set owned by the vault capability\'s "vault.mode" values)',
+          );
+        }
+        if (capId !== 'vault' && !requiresVault) {
+          errors.push(
+            where + ': vaultMode is allowed only on the "vault" capability or a capability that ' +
+            'lists "vault" in requires',
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Quick 261015-ect (QD-13): the vault-family rule for `requiresPlatformBindings`,
+ * the mirror of the vaultMode rule (c) above. A capability that is `vault` or
+ * lists `vault` in `requires` MUST declare the field, so a vault-family
+ * capability added later cannot render hooks on a project the vault does not
+ * govern by forgetting it. A capability outside the family may declare it too.
+ *
+ * @param {Map<string, object>} capMap
+ * @returns {string[]} error strings; empty = all pass
+ */
+function validatePlatformBindingsField(capMap) {
+  const errors = [];
+  for (const [capId, cap] of capMap) {
+    if (!cap || typeof cap !== 'object') continue;
+    const requiresVault = Array.isArray(cap.requires) && cap.requires.includes('vault');
+    if (capId !== 'vault' && !requiresVault) continue;
+    if (!Object.prototype.hasOwnProperty.call(cap, 'requiresPlatformBindings')) {
+      errors.push(
+        'capability "' + capId + '" is vault or requires vault and must declare requiresPlatformBindings, ' +
+        'so a vault-family capability cannot render hooks on a project the vault does not govern',
+      );
+    }
+  }
+  return errors;
+}
+
+/**
+ * Phase 16 D-19: the per-hook seal field's name. The resolver reads it as
+ * `SEAL_FIELD` from capability-state; this generator cannot require that module
+ * (its load graph reaches surface.cjs and config-loader.cjs, which read the
+ * very registry this script regenerates), so the literal is restated here and
+ * pinned equal to `SEAL_FIELD` by tests/capability-registry.test.cjs.
+ */
+const SEAL_FIELD_NAME = 'onRecordedArtifacts';
+
+/**
+ * Phase 16 D-19 / D-25 / D-26: validate the per-hook seal field.
+ *
+ * A gate carrying the field renders for an enabled, config-inactive capability
+ * over recorded vault artifacts, bypassing the capability's active check and
+ * its `when` (D-18). That is a widening of render behaviour, so the field is
+ * closed HERE, at generation, to exactly the shape the two shipped seal gates
+ * have. Six rules, each reported on its own:
+ *   (a) gates only (a step or contribution carrying it is refused);
+ *   (b) the value is literal `true` (`"true"`, `1`, `null`, `false` refused);
+ *   (c) the declaring capability lists `vault` in `requires` and is not `vault`
+ *       itself (D-26: with the vault off the injected mode is null, so both
+ *       modes' filtered gates pass and sealing the vault capability too would
+ *       dispatch `check vault.trace` twice);
+ *   (d) the gate also carries `vaultMode` (the resolver filters by mode BEFORE
+ *       the predicate, research C-1);
+ *   (e) the gate is `blocking: true`;
+ *   (f) the point is `ship:pre` (D-21: the requirement's block point; a seal at
+ *       verify:post would halt execute-phase on a switch set on purpose).
+ *
+ * Presence is own-property presence.
+ *
+ * @param {Map<string, object>} capMap
+ * @returns {string[]} error strings; empty = all pass
+ */
+function validateSealField(capMap) {
+  const errors = [];
+  const KINDS = [['steps', 'step'], ['contributions', 'contribution'], ['gates', 'gate']];
+  for (const [capId, cap] of capMap) {
+    if (!cap || typeof cap !== 'object') continue;
+    const prefix = 'capability "' + capId + '"';
+    const requiresVault = Array.isArray(cap.requires) && cap.requires.includes('vault');
+    for (const [arrKey, kind] of KINDS) {
+      const arr = Array.isArray(cap[arrKey]) ? cap[arrKey] : [];
+      for (const hook of arr) {
+        if (!hook || typeof hook !== 'object') continue;
+        if (!Object.prototype.hasOwnProperty.call(hook, SEAL_FIELD_NAME)) continue;
+        const where = prefix + ' ' + kind + ' at point "' + String(hook.point) + '"';
+        const value = hook[SEAL_FIELD_NAME];
+        if (kind !== 'gate') {
+          errors.push(where + ': ' + SEAL_FIELD_NAME + ' is allowed on gates only');
+          continue;
+        }
+        if (value !== true) {
+          errors.push(where + ': ' + SEAL_FIELD_NAME + ' must be literal true (got ' + JSON.stringify(value) + ')');
+        }
+        if (capId === 'vault' || !requiresVault) {
+          errors.push(
+            where + ': ' + SEAL_FIELD_NAME + ' is allowed only on a capability that lists "vault" in requires ' +
+            'and is not "vault" itself',
+          );
+        }
+        if (!Object.prototype.hasOwnProperty.call(hook, 'vaultMode')) {
+          errors.push(where + ': a gate carrying ' + SEAL_FIELD_NAME + ' must also carry vaultMode');
+        }
+        if (hook.blocking !== true) {
+          errors.push(where + ': a gate carrying ' + SEAL_FIELD_NAME + ' must be blocking: true');
+        }
+        if (hook.point !== 'ship:pre') {
+          errors.push(where + ': ' + SEAL_FIELD_NAME + ' is allowed only at point "ship:pre"');
+        }
+      }
+    }
+  }
+  return errors;
+}
+
 /**
  * C1+C2: Global consumes-satisfiability validation.
  *
@@ -1479,6 +1662,18 @@ const TIER_RANK = { core: 0, standard: 1, full: 2 };
 function validateCrossCapability(capMap, centralKeys) {
   const errors = [];
 
+  // Phase 15 D-02: the per-hook vaultMode filter field (needs capMap to read the
+  // vault capability's closed value set and every capability's `requires`).
+  errors.push(...validateVaultModeField(capMap));
+
+  // Phase 16 D-19: the per-hook seal field (needs capMap for every capability's
+  // `requires`).
+  errors.push(...validateSealField(capMap));
+
+  // Quick 261015-ect (QD-13): every vault-family capability declares
+  // requiresPlatformBindings (needs capMap for every capability's `requires`).
+  errors.push(...validatePlatformBindingsField(capMap));
+
   // Ownership: one owner per skill stem + agent name
   const skillOwner = new Map(); // skill → capId
   const agentOwner = new Map(); // agent → capId
@@ -2646,6 +2841,10 @@ module.exports = {
   validateAgainstContract,
   validateConsumesGlobal,
   validateCrossCapability,
+  validateVaultModeField,
+  validateSealField,
+  validatePlatformBindingsField,
+  SEAL_FIELD_NAME,
   classifyCrossErrors,
   loadCentralConfigKeys,
   loadAndValidate,