@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/registry/custom-scaffold.mjs

@@ -0,0 +1,200 @@
+/**
+ * lib/registry/custom-scaffold.mjs — CLI-facing scaffolding for user-authored
+ * custom specialists and teams (construct-rf26.13).
+ *
+ * Writes into one of two extension tiers, both read back by
+ * lib/registry/assemble.mjs at the same precedence ADR-0052 establishes for
+ * provider manifests (builtin -> user -> project):
+ *   - "user"    ~/.construct/org/**   — usable across every project on the machine
+ *   - "project" <rootDir>/.cx/org/**  — git-tracked, highest precedence, scoped
+ *                                       to one project (the existing overlay
+ *                                       introduced by ADR-0046)
+ *
+ * Refuses to overwrite an existing file unless { force: true }, mirroring
+ * lib/specialists/scaffold.mjs's createSpecialistDraft convention. Validates
+ * with lib/registry/custom-schema.mjs before writing anything, so a scaffolded
+ * record is guaranteed registry-loadable the moment it lands on disk.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeDir } from '../paths.mjs';
+import { assembleRegistry } from './assemble.mjs';
+import { validateCustomSpecialist, validateCustomTeam } from './custom-schema.mjs';
+
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+
+export function customOrgDir(scope, { rootDir = process.cwd() } = {}) {
+  if (scope === 'user') return path.join(homeDir(), '.construct', 'org');
+  return path.join(rootDir, '.cx', 'org');
+}
+
+function existingTeamIds(rootDir) {
+  try {
+    return Object.keys(assembleRegistry(rootDir).teams);
+  } catch {
+    return null;
+  }
+}
+
+function renderPromptStub({ id, role, description }) {
+  return [
+    `# cx-${id}`,
+    '',
+    `Role: ${role}`,
+    '',
+    description || 'TODO: describe this specialist\'s perspective and output format.',
+    '',
+    '## Anti-fabrication contract',
+    '',
+    'Every load-bearing claim cites a source the reader can re-verify. When a fact is not in the source, write `unknown` or `[unverified]`. See `rules/common/no-fabrication.md`.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Scaffold a custom specialist JSON record (+ a minimal prompt stub) into the
+ * requested tier. Throws with actionable, field-named errors on any failure.
+ * @returns {{ path: string, relPath: string, promptPath: string, record: object, scope: string }}
+ */
+export function createCustomSpecialist({
+  rootDir = process.cwd(),
+  scope = 'project',
+  id,
+  role,
+  description,
+  modelTier = 'standard',
+  reasoningEffort,
+  skills = [],
+  fence,
+  team,
+  teamId,
+  handoffCandidates = [],
+  claudeTools = 'Read,Grep,Glob,LS',
+  displayName,
+  force = false,
+} = {}) {
+  if (!id || !ID_RE.test(id)) {
+    throw new Error(`invalid specialist id "${id}" — use lowercase kebab-case (e.g. "widget-specialist")`);
+  }
+  if (scope !== 'user' && scope !== 'project') {
+    throw new Error(`invalid scope "${scope}" — use "user" or "project"`);
+  }
+
+  const orgDir = customOrgDir(scope, { rootDir });
+  const specialistsDir = path.join(orgDir, 'specialists');
+  const filePath = path.join(specialistsDir, `cx-${id}.json`);
+  if (fs.existsSync(filePath) && !force) {
+    throw new Error(`${filePath} already exists — pass force to overwrite`);
+  }
+
+  const resolvedTeam = team || teamId;
+  const knownTeams = existingTeamIds(rootDir);
+  if (resolvedTeam && knownTeams && !knownTeams.includes(resolvedTeam)) {
+    throw new Error(
+      `team "${resolvedTeam}" does not exist — create it first with \`construct team create ${resolvedTeam} --owner=${role || id}\`, ` +
+      `or reference one of: ${knownTeams.slice(0, 10).join(', ')}${knownTeams.length > 10 ? ', …' : ''}`,
+    );
+  }
+
+  const promptRelPath = path.posix.join(
+    path.relative(rootDir, orgDir).split(path.sep).join('/'),
+    'prompts',
+    `cx-${id}.md`,
+  );
+
+  const record = {
+    name: id,
+    displayName: displayName || description,
+    description,
+    role: role || id,
+    modelTier,
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+    skills,
+    fence: fence || { allowedPaths: [] },
+    claudeTools,
+    promptFile: promptRelPath,
+    handoffCandidates,
+    team: resolvedTeam,
+    teamId: resolvedTeam,
+    internal: true,
+    custom: true,
+  };
+
+  const errors = validateCustomSpecialist(record, { rootDir, checkPromptFileExists: false });
+  if (errors.length) {
+    throw new Error(`custom specialist "${id}" failed validation:\n  ${errors.join('\n  ')}`);
+  }
+
+  const promptDir = path.join(orgDir, 'prompts');
+  const promptPath = path.join(rootDir, promptRelPath);
+  fs.mkdirSync(promptDir, { recursive: true });
+  if (!fs.existsSync(promptPath) || force) {
+    fs.writeFileSync(promptPath, renderPromptStub({ id, role: record.role, description }));
+  }
+
+  fs.mkdirSync(specialistsDir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(record, null, 2) + '\n');
+
+  return { path: filePath, relPath: path.relative(rootDir, filePath), promptPath, record, scope };
+}
+
+/**
+ * Scaffold a custom team JSON record into the requested tier. Throws with
+ * actionable, field-named errors on any failure.
+ * @returns {{ path: string, relPath: string, record: object, scope: string }}
+ */
+export function createCustomTeam({
+  rootDir = process.cwd(),
+  scope = 'project',
+  id,
+  name,
+  owner,
+  roles,
+  specialists = [],
+  charter,
+  decisionRights = [],
+  forbiddenDecisions = [],
+  escalationPath,
+  contact = {},
+  groupId,
+  force = false,
+} = {}) {
+  if (!id || !ID_RE.test(id)) {
+    throw new Error(`invalid team id "${id}" — use lowercase kebab-case (e.g. "widget-team")`);
+  }
+  if (scope !== 'user' && scope !== 'project') {
+    throw new Error(`invalid scope "${scope}" — use "user" or "project"`);
+  }
+
+  const orgDir = customOrgDir(scope, { rootDir });
+  const teamsDir = path.join(orgDir, 'teams');
+  const filePath = path.join(teamsDir, `${id}.json`);
+  if (fs.existsSync(filePath) && !force) {
+    throw new Error(`${filePath} already exists — pass force to overwrite`);
+  }
+
+  const resolvedRoles = roles && roles.length ? roles : (owner ? [owner] : []);
+  const record = {
+    name: name || id,
+    owner,
+    roles: resolvedRoles,
+    specialists,
+    decisionRights,
+    forbiddenDecisions,
+    escalationPath: escalationPath && escalationPath.length ? escalationPath : [owner, 'orchestrator'].filter(Boolean),
+    charter,
+    contact,
+    ...(groupId ? { groupId } : {}),
+  };
+
+  const errors = validateCustomTeam({ id, ...record });
+  if (errors.length) {
+    throw new Error(`custom team "${id}" failed validation:\n  ${errors.join('\n  ')}`);
+  }
+
+  fs.mkdirSync(teamsDir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(record, null, 2) + '\n');
+
+  return { path: filePath, relPath: path.relative(rootDir, filePath), record, scope };
+}

package/lib/registry/custom-schema.mjs

@@ -0,0 +1,137 @@
+/**
+ * lib/registry/custom-schema.mjs — validation contract for user-authored custom
+ * specialists and teams (construct-rf26.13).
+ *
+ * Hand-rolled validator, matching the style already established by
+ * lib/specialists/schema.mjs and lib/config/schema.mjs, rather than pulling in
+ * a schema-validation dependency: every error names the offending field and
+ * says what to do about it, so a scaffold failure is actionable without
+ * cross-referencing a generic validator dump. Reuses lib/specialists/schema.mjs's
+ * ALLOWED_TOOLS allowlist so a custom specialist is held to the same
+ * claudeTools contract as a built-in one.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { ALLOWED_TOOLS } from '../specialists/schema.mjs';
+
+export const MODEL_TIERS = ['fast', 'standard', 'reasoning'];
+const SKILL_REF_RE = /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Validate one custom specialist record. Returns an array of actionable error
+ * strings; empty means the record passes.
+ */
+export function validateCustomSpecialist(record, { rootDir, checkPromptFileExists = true } = {}) {
+  const errors = [];
+  const id = record?.name || '(unnamed)';
+
+  if (!record || typeof record !== 'object') {
+    return [`custom specialist: record must be an object`];
+  }
+
+  if (!record.name || !ID_RE.test(record.name)) {
+    errors.push(`${id}: "name" must be lowercase kebab-case (e.g. "widget-specialist"), got ${JSON.stringify(record.name)}`);
+  }
+
+  if (!record.description || String(record.description).trim().length < 20) {
+    errors.push(`${id}: "description" is required and must be at least 20 characters — it is load-bearing for orchestration routing`);
+  } else if (String(record.description).length > 500) {
+    errors.push(`${id}: "description" is too long (>500 chars) — keep it scannable`);
+  }
+
+  if (!record.role || typeof record.role !== 'string') {
+    errors.push(`${id}: "role" is required (e.g. "widget-specialist") — a team's "owner" field must match a specialist's "role" for the team to validate`);
+  }
+
+  if (!record.modelTier || !MODEL_TIERS.includes(record.modelTier)) {
+    errors.push(`${id}: "modelTier" must be one of ${MODEL_TIERS.join(' | ')}, got ${JSON.stringify(record.modelTier)}`);
+  }
+
+  const team = record.team || record.teamId;
+  if (!team || typeof team !== 'string') {
+    errors.push(`${id}: "team" (or "teamId") is required — reference an existing team id, or create one first with \`construct team create <id> --owner=${record.role || '<role>'}\``);
+  }
+
+  if (!Array.isArray(record.skills) || record.skills.length === 0) {
+    errors.push(`${id}: "skills" must be a non-empty array of skill bundle references (e.g. ["frontend-design/accessibility"])`);
+  } else {
+    record.skills.forEach((skill, i) => {
+      if (typeof skill !== 'string' || !SKILL_REF_RE.test(skill)) {
+        errors.push(`${id}: skills[${i}] "${skill}" is not a valid skill bundle reference — expected "<bundle>/<skill>" (e.g. "frontend-design/accessibility")`);
+      }
+    });
+  }
+
+  if (!record.fence || typeof record.fence !== 'object' || Array.isArray(record.fence)) {
+    errors.push(`${id}: "fence" is required — at minimum { "allowedPaths": [...] } to declare the permission boundary`);
+  } else if (!Array.isArray(record.fence.allowedPaths) || record.fence.allowedPaths.length === 0) {
+    errors.push(`${id}: "fence.allowedPaths" must be a non-empty array of path globs this specialist may touch`);
+  }
+
+  if (record.handoffCandidates !== undefined && !Array.isArray(record.handoffCandidates)) {
+    errors.push(`${id}: "handoffCandidates" must be an array of role ids (the delegation spec — who this specialist hands off to)`);
+  }
+
+  if (record.claudeTools) {
+    const tools = String(record.claudeTools).split(',').map((t) => t.trim()).filter(Boolean);
+    for (const tool of tools) {
+      if (!ALLOWED_TOOLS.has(tool)) {
+        errors.push(`${id}: unknown tool "${tool}" in claudeTools — host platforms silently drop unknown tool names, causing this specialist to appear to work without it`);
+      }
+    }
+  }
+
+  if (checkPromptFileExists && record.promptFile && rootDir) {
+    const promptPath = path.join(rootDir, record.promptFile);
+    if (!fs.existsSync(promptPath)) {
+      errors.push(`${id}: promptFile "${record.promptFile}" does not exist under ${rootDir}`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate one custom team record. Returns an array of actionable error
+ * strings; empty means the record passes.
+ */
+export function validateCustomTeam(record) {
+  const errors = [];
+  const id = record?.id || record?.name || '(unnamed)';
+
+  if (!record || typeof record !== 'object') {
+    return [`custom team: record must be an object`];
+  }
+
+  if (!record.name || typeof record.name !== 'string') {
+    errors.push(`${id}: "name" is required (human-readable team name, e.g. "Widget Team")`);
+  }
+
+  if (!record.owner || typeof record.owner !== 'string') {
+    errors.push(`${id}: "owner" is required — the role id that holds primary accountability (must match a specialist's "role" field)`);
+  }
+
+  if (!Array.isArray(record.roles) || record.roles.length === 0) {
+    errors.push(`${id}: "roles" must be a non-empty array of role ids that constitute this team`);
+  } else if (record.owner && !record.roles.includes(record.owner)) {
+    errors.push(`${id}: "roles" must include the owner role "${record.owner}"`);
+  }
+
+  if (!record.charter || String(record.charter).trim().length < 20) {
+    errors.push(`${id}: "charter" is required and must be at least 20 characters — a one-paragraph mission statement for what this team owns`);
+  }
+
+  for (const field of ['decisionRights', 'forbiddenDecisions', 'escalationPath', 'specialists']) {
+    if (record[field] !== undefined && !Array.isArray(record[field])) {
+      errors.push(`${id}: "${field}" must be an array of strings when present`);
+    }
+  }
+
+  if (record.contact !== undefined && (typeof record.contact !== 'object' || Array.isArray(record.contact))) {
+    errors.push(`${id}: "contact" must be an object when present (e.g. { "slack": "#team", "owner": "role-id" })`);
+  }
+
+  return errors;
+}

package/lib/registry/loader.mjs

@@ -10,14 +10,20 @@
 
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
 import { validate } from './validator.mjs';
 import { assembleRegistry, orgDirMtime, listTeamsFromRegistry, listGroupsHierarchical } from './assemble.mjs';
+import { packageRoot } from '../roots.mjs';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ROOT_DIR = path.resolve(__dirname, '..', '..');
+// packageRoot (not a local __dirname-derived constant) because under a
+// Bun-compiled binary every bundled module's import.meta.url collapses to
+// the same virtual /$bunfs/root path, losing this file's real nesting
+// under lib/registry/; packageRoot already falls back to the compiled
+// binary's real on-disk directory (see lib/roots.mjs).
+
+const ROOT_DIR = packageRoot;
 
 let _registry = null;
+let _rootDir = null;
 let _orgMtime = null;
 let _legacyOverlayMtime = null;
 
@@ -62,7 +68,10 @@ export function loadRegistry(opts = {}) {
     legacyOverlay = null;
   }
 
-  if (_registry && _orgMtime === orgMtime && _legacyOverlayMtime === legacyOverlayMtime) {
+  // The cache key must include rootDir: two roots can share an orgMtime/overlay mtime
+  // (tmpdir tests, coincident timestamps), and a cache keyed only on mtimes bleeds one
+  // root's registry into another — a specialist can then surface without its promptFile.
+  if (_registry && _rootDir === rootDir && _orgMtime === orgMtime && _legacyOverlayMtime === legacyOverlayMtime) {
     return _registry;
   }
 
@@ -79,6 +88,7 @@ export function loadRegistry(opts = {}) {
   }
 
   _registry = registry;
+  _rootDir = rootDir;
   _orgMtime = orgMtime;
   _legacyOverlayMtime = legacyOverlayMtime;
 
@@ -127,6 +137,7 @@ export function listSpecialists(teamId, opts = {}) {
 
 export function clearCache() {
   _registry = null;
+  _rootDir = null;
   _orgMtime = null;
   _legacyOverlayMtime = null;
 }

package/lib/registry/manifests/format-engines.default.json

@@ -0,0 +1,15 @@
+{
+  "pdf": { "engine": "pandoc", "writer": null, "pdfEngine": "typst", "extraBinaries": ["typst"] },
+  "docx": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "doc": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [], "via": "libreoffice", "intermediate": "docx" },
+  "deck": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "pptx": { "engine": "pptxgenjs", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "html": { "engine": "pandoc", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "rtf": { "engine": "pandoc", "writer": "rtf", "pdfEngine": null, "extraBinaries": [] },
+  "odt": { "engine": "pandoc", "writer": "odt", "pdfEngine": null, "extraBinaries": [] },
+  "epub": { "engine": "pandoc", "writer": "epub", "pdfEngine": null, "extraBinaries": [] },
+  "tex": { "engine": "pandoc", "writer": "latex", "pdfEngine": null, "extraBinaries": [] },
+  "txt": { "engine": "pandoc", "writer": "plain", "pdfEngine": null, "extraBinaries": [] },
+  "md": { "engine": "copy", "writer": null, "pdfEngine": null, "extraBinaries": [] },
+  "mdx": { "engine": "copy", "writer": null, "pdfEngine": null, "extraBinaries": [] }
+}

package/lib/registry/manifests/surface-map.default.json

@@ -0,0 +1,46 @@
+{
+  "tiers": ["agent-mcp", "thin-cli", "tui", "internal"],
+  "commands": {
+    "install": "thin-cli",
+    "init": "thin-cli",
+    "dev": "thin-cli",
+    "stop": "thin-cli",
+    "status": "thin-cli",
+    "doctor": "thin-cli",
+    "sync": "thin-cli",
+    "ingest": "agent-mcp",
+    "drop": "agent-mcp",
+    "distill": "agent-mcp",
+    "ask": "agent-mcp",
+    "search": "agent-mcp",
+    "knowledge": "agent-mcp",
+    "memory": "agent-mcp",
+    "reflect": "agent-mcp",
+    "intake": "tui",
+    "workflow": "agent-mcp",
+    "graph": "agent-mcp",
+    "capability": "agent-mcp",
+    "execution": "agent-mcp",
+    "orchestrate": "agent-mcp",
+    "models": "agent-mcp",
+    "profile": "tui",
+    "sandbox": "tui",
+    "review": "thin-cli",
+    "telemetry": "thin-cli",
+    "evals": "thin-cli",
+    "improvement": "thin-cli",
+    "ci": "thin-cli",
+    "docs": "thin-cli",
+    "export": "agent-mcp",
+    "diagram": "agent-mcp",
+    "demo": "agent-mcp",
+    "beads": "thin-cli",
+    "hook": "internal",
+    "lint:comments": "internal",
+    "lint:agents": "internal",
+    "registry:status": "internal",
+    "registry:validate": "internal",
+    "registry:generate-docs": "internal",
+    "rules": "thin-cli"
+  }
+}

package/lib/registry/retired-paths.mjs

@@ -29,6 +29,7 @@ export const RETIRED_REGISTRY_PATH_ALLOWLIST = Object.freeze([
   'scripts/patch-registry-readers-v2.mjs',
   'tests/no-monolithic-registry.test.mjs',
   'tests/migration-round-trip.test.mjs',
+  'tests/fixtures/mcp-tool-schemas/results/project_context.result.json',
 ]);
 
 export function isRetiredRegistryPathAllowed(relPath) {

package/lib/registry/surface-map.mjs

@@ -3,6 +3,12 @@
  *
  * Declarative map from CLI command name to primary surface tier. The CLI registry
  * remains the substrate; this file governs discovery posture without removing verbs.
+ * LMCP-B7: the tiers/command map ship as lib/registry/manifests/surface-map.default.json
+ * (loaded once at module init — this file's exports stay byte-identical to the prior
+ * hardcoded dict) with an optional `.cx/registry/surface-map.json` project override
+ * merged in per-call by resolveSurfaceMap()/surfaceForCommand()/validateSurfaceMap().
+ * An override may add or reassign command entries and replace the tier list; it can
+ * never remove a default entry outright (unset keys keep resolving to the default).
  *
  * Surfaces:
  *   agent-mcp — MCP tool canonical; CLI --json twin
@@ -11,64 +17,108 @@
  *   internal  — CI/harness only
  */
 
-export const SURFACE_TIERS = ['agent-mcp', 'thin-cli', 'tui', 'internal'];
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { packageRoot } from '../roots.mjs';
+
+// packageRoot (not a local import.meta.url-derived HERE) because under a
+// Bun-compiled binary every bundled module's import.meta.url collapses to
+// the same virtual /$bunfs/root path, losing this file's real nesting
+// under lib/registry/ — packageRoot already falls back to the compiled
+// binary's real on-disk directory (see lib/roots.mjs), so rebuilding the
+// known relative path from it resolves correctly in every run mode.
+
+const DEFAULT_MANIFEST_PATH = path.join(packageRoot, 'lib', 'registry', 'manifests', 'surface-map.default.json');
+
+function readJsonIfExists(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function loadDefaultManifest() {
+  const manifest = readJsonIfExists(DEFAULT_MANIFEST_PATH);
+  if (!manifest || !Array.isArray(manifest.tiers) || typeof manifest.commands !== 'object') {
+    throw new Error(`lib/registry/surface-map.mjs: missing or malformed default manifest at ${DEFAULT_MANIFEST_PATH}`);
+  }
+  return manifest;
+}
+
+const DEFAULT_MANIFEST = loadDefaultManifest();
+
+// Byte-identical to the pre-manifest hardcoded exports: both are read once at
+// module init from the default manifest, with no project override applied —
+// a direct import of these two names sees exactly the shipped defaults.
+
+export const SURFACE_TIERS = DEFAULT_MANIFEST.tiers;
 
 /** @type {Record<string, string>} */
-export const COMMAND_SURFACE = {
-  install: 'thin-cli',
-  init: 'thin-cli',
-  dev: 'thin-cli',
-  stop: 'thin-cli',
-  status: 'thin-cli',
-  doctor: 'thin-cli',
-  sync: 'thin-cli',
-  ingest: 'agent-mcp',
-  drop: 'agent-mcp',
-  distill: 'agent-mcp',
-  ask: 'agent-mcp',
-  search: 'agent-mcp',
-  knowledge: 'agent-mcp',
-  memory: 'agent-mcp',
-  reflect: 'agent-mcp',
-  intake: 'tui',
-  workflow: 'agent-mcp',
-  graph: 'agent-mcp',
-  capability: 'agent-mcp',
-  execution: 'agent-mcp',
-  orchestrate: 'agent-mcp',
-  models: 'agent-mcp',
-  profile: 'tui',
-  sandbox: 'tui',
-  review: 'thin-cli',
-  telemetry: 'thin-cli',
-  evals: 'thin-cli',
-  improvement: 'thin-cli',
-  ci: 'thin-cli',
-  docs: 'thin-cli',
-  export: 'agent-mcp',
-  diagram: 'agent-mcp',
-  demo: 'agent-mcp',
-  beads: 'thin-cli',
-  hook: 'internal',
-  'lint:comments': 'internal',
-  'lint:agents': 'internal',
-  'registry:status': 'internal',
-  'registry:validate': 'internal',
-  'registry:generate-docs': 'internal',
-  rules: 'thin-cli',
-};
-
-export function surfaceForCommand(name) {
-  if (COMMAND_SURFACE[name]) return COMMAND_SURFACE[name];
+export const COMMAND_SURFACE = DEFAULT_MANIFEST.commands;
+
+const overrideCache = new Map();
+
+function loadOverride(cwd) {
+  if (overrideCache.has(cwd)) return overrideCache.get(cwd);
+  const override = readJsonIfExists(path.join(cwd, '.cx', 'registry', 'surface-map.json'));
+  overrideCache.set(cwd, override);
+  return override;
+}
+
+/**
+ * resolveSurfaceMap({ cwd } = {})
+ *
+ * Merges the default manifest with a project's `.cx/registry/surface-map.json`
+ * override, when present. `commands` in the override are shallow-merged over
+ * the default (an override entry replaces the matching default; every other
+ * default entry survives untouched). `tiers` in the override replaces the
+ * default tier list wholesale when present.
+ */
+export function resolveSurfaceMap({ cwd = process.cwd() } = {}) {
+  const override = loadOverride(cwd);
+  if (!override) return { tiers: SURFACE_TIERS, commands: COMMAND_SURFACE };
+  const tiers = Array.isArray(override.tiers) ? override.tiers : SURFACE_TIERS;
+  const commands = { ...COMMAND_SURFACE, ...(override.commands && typeof override.commands === 'object' ? override.commands : {}) };
+  return { tiers, commands };
+}
+
+export function surfaceForCommand(name, { cwd = process.cwd() } = {}) {
+  const { commands } = resolveSurfaceMap({ cwd });
+  if (commands[name]) return commands[name];
   if (name.includes(':')) return 'internal';
   return 'thin-cli';
 }
 
-export function commandsBySurface(commands) {
-  const grouped = Object.fromEntries(SURFACE_TIERS.map((t) => [t, []]));
+export function commandsBySurface(commands, { cwd = process.cwd() } = {}) {
+  const { tiers } = resolveSurfaceMap({ cwd });
+  const grouped = Object.fromEntries(tiers.map((t) => [t, []]));
   for (const cmd of commands) {
-    const surface = cmd.surface ?? surfaceForCommand(cmd.name);
+    const surface = cmd.surface ?? surfaceForCommand(cmd.name, { cwd });
     grouped[surface]?.push(cmd.name);
   }
   return grouped;
 }
+
+/**
+ * validateSurfaceMap(commandNames, { cwd } = {})
+ *
+ * Stricter than surfaceForCommand's runtime fallback: every name must have an
+ * explicit entry in the resolved (default + override) command map. This is an
+ * opt-in registry/doctor-style check, separate from the CLI's own dispatch
+ * path, so the default fallback behavior for unregistered commands stays
+ * unaffected.
+ */
+export function validateSurfaceMap(commandNames, { cwd = process.cwd() } = {}) {
+  const { commands } = resolveSurfaceMap({ cwd });
+  const errors = commandNames
+    .filter((name) => !commands[name])
+    .map((name) => `command '${name}' has no surface-map entry (add one to .cx/registry/surface-map.json or lib/registry/manifests/surface-map.default.json)`);
+  return { valid: errors.length === 0, errors };
+}
+
+export function __clearSurfaceMapOverrideCache() {
+  overrideCache.clear();
+}

package/lib/registry/validate.mjs

@@ -86,7 +86,7 @@ export function validateCapabilityRegistry({ rootDir = REPO_ROOT, now = Date.now
 
     const hasTest = ver.functional || ver.hostEmulation || ver.untestableRationale;
     if (!hasTest && (cap.criticality === 'P0' || cap.criticality === 'P1')) {
-      warnings.push(`${cap.id}: P0/P1 capability has no functional test or untestableRationale`);
+      errors.push(`${cap.id}: P0/P1 capability has no functional test or untestableRationale`);
     }
 
     const surfaces = cap.surfaces ?? {};
@@ -105,10 +105,10 @@ export function validateCapabilityRegistry({ rootDir = REPO_ROOT, now = Date.now
     if (cap.lastValidated) {
       const age = now - Date.parse(cap.lastValidated);
       if (Number.isFinite(age) && age > STALE_MS) {
-        warnings.push(`${cap.id}: lastValidated older than 90 days (${cap.lastValidated})`);
+        errors.push(`${cap.id}: lastValidated older than 90 days (${cap.lastValidated})`);
       }
     } else if (cap.criticality === 'P0') {
-      warnings.push(`${cap.id}: P0 capability never validated (lastValidated null)`);
+      errors.push(`${cap.id}: P0 capability never validated (lastValidated null)`);
     }
 
     for (const dep of cap.dependencies?.skills ?? []) {