@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/session-store.mjs

@@ -19,6 +19,7 @@ import path from "node:path";
 import { cosineSimilarity, rankByBm25 } from "./storage/embeddings.mjs";
 import { embedSync as embedText } from "./storage/embeddings-legacy.mjs";
 import { withFileLockSync } from "./storage/file-lock.mjs";
+import { ensureCxDir } from "./project-init-shared.mjs";
 
 const SESSIONS_DIR = ".cx/sessions";
 const INDEX_FILE = "index.json";
@@ -29,7 +30,8 @@ const MAX_DECISIONS = 20;
 const MAX_FILES = 50;
 const MAX_OPEN_QUESTIONS = 10;
 
-function ensureDir(dir) {
+function ensureDir(dir, rootDir = null) {
+  if (rootDir) ensureCxDir(rootDir);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
@@ -52,7 +54,7 @@ function readVectors(rootDir) {
 }
 
 function writeVectors(rootDir, records) {
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   const target = vectorsPath(rootDir);
   withFileLockSync(target, () => {
     fs.writeFileSync(target, JSON.stringify(records.slice(0, MAX_INDEX_ENTRIES), null, 2) + "\n");
@@ -86,7 +88,7 @@ function readIndex(rootDir) {
 }
 
 function writeIndex(rootDir, entries) {
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX_ENTRIES);
   const target = indexPath(rootDir);
   withFileLockSync(target, () => {
@@ -137,7 +139,7 @@ export function createSession(rootDir, {
     taskSnapshot: [],
   };
 
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   fs.writeFileSync(
     path.join(sessionsDir(rootDir), `${id}.json`),
     JSON.stringify(record, null, 2) + "\n"

package/lib/setup.mjs

@@ -420,7 +420,7 @@ function ensureOpenCodeConfig() {
 // repo but never executed by git. Idempotent: leaves a user-set value alone
 // rather than clobbering it.
 
-function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
+export function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
   const hooksDir = path.join(cwd, '.beads', 'hooks');
   if (!fs.existsSync(path.join(hooksDir, 'pre-commit'))) {
     return { status: 'skipped', reason: 'no .beads/hooks/pre-commit in this directory' };
@@ -435,10 +435,21 @@ function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
   if (currentValue === desired) {
     return { status: 'ok', message: 'core.hooksPath already wired to .beads/hooks' };
   }
-  if (currentValue && currentValue !== desired) {
+
+  // Treat the git default (`.git/hooks` or an absolute path to it) as
+  // equivalent to unset. A user who has accepted the default has not made an
+  // active choice that justifies "leave alone" semantics; without this branch
+  // an install that happens to land while `.git/hooks` is already in play
+  // leaves policy gates inactive permanently.
+  const isGitDefault =
+    !currentValue ||
+    currentValue === '.git/hooks' ||
+    currentValue === path.join(cwd, '.git', 'hooks') ||
+    currentValue.replace(/\/+$/, '').endsWith(`${path.sep}.git${path.sep}hooks`);
+  if (!isGitDefault) {
     return {
       status: 'warning',
-      message: `core.hooksPath is set to '${currentValue}'. Leaving alone — set to '.beads/hooks' to activate Construct policy gates.`,
+      message: `core.hooksPath is set to '${currentValue}'. Leaving alone. Set to '.beads/hooks' to activate Construct policy gates.`,
     };
   }
   const result = spawnSync('git', ['config', 'core.hooksPath', desired], { cwd, stdio: 'pipe', encoding: 'utf8' });

package/lib/{agent-contracts-enforce.mjs → specialist-contracts-enforce.mjs}

@@ -1,7 +1,7 @@
 /**
- * lib/agent-contracts-enforce.mjs — runtime contract enforcement.
+ * lib/specialist-contracts-enforce.mjs — runtime contract enforcement.
  *
- * Wraps `validatePacket` from `lib/agent-contracts.mjs` with three production
+ * Wraps `validatePacket` from `lib/specialist-contracts.mjs` with three production
  * concerns:
  *
  *   1. Block on violation. `enforcePacket` throws a `ContractViolationError`
@@ -27,8 +27,8 @@ import { existsSync, mkdirSync, statSync, readFileSync, appendFileSync } from 'n
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
-import { getContractById, validatePacket } from './agent-contracts.mjs';
-import { validatePostconditions } from './agents/postconditions.mjs';
+import { getContractById, validatePacket } from './specialist-contracts.mjs';
+import { validatePostconditions } from './specialists/postconditions.mjs';
 
 const CX_DIR = join(homedir(), '.cx');
 const LOG_FILE = join(CX_DIR, 'contract-violations.jsonl');

package/lib/{agent-contracts.mjs → specialist-contracts.mjs}

@@ -1,5 +1,5 @@
 /**
- * lib/agent-contracts.mjs — loader + query layer for agents/contracts.json.
+ * lib/specialist-contracts.mjs — loader + query layer for specialists/contracts.json.
  *
  * Agent contracts are explicit service contracts between Construct roles —
  * "when cx-product-manager hands off to cx-architect, the packet MUST contain
@@ -20,7 +20,7 @@ import { fileURLToPath } from 'node:url';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(MODULE_DIR, '..');
-const CONTRACTS_PATH = join(REPO_ROOT, 'agents', 'contracts.json');
+const CONTRACTS_PATH = join(REPO_ROOT, 'specialists', 'contracts.json');
 
 let _cache = null;
 
@@ -157,10 +157,10 @@ export function resolveContractChain(ctx = {}) {
   return chain;
 }
 
-function fieldPresent(packet, key) {
-  const value = packet?.[key];
+function isPresent(value) {
   if (value === undefined || value === null) return false;
   if (typeof value === 'string' && value.trim() === '') return false;
+  if (Array.isArray(value) && value.length === 0) return false;
   return true;
 }
 
@@ -187,14 +187,14 @@ export function validatePacket(contractId, packet, direction = 'input') {
 
   if (Array.isArray(spec.mustContain)) {
     for (const key of spec.mustContain) {
-      if (!fieldPresent(packet, key)) missing.push(key);
+      if (!isPresent(packet?.[key])) missing.push(key);
     }
   }
 
   if (Array.isArray(spec.mustContainOneOf)) {
     for (const group of spec.mustContainOneOf) {
       if (!Array.isArray(group) || group.length === 0) continue;
-      const anyPresent = group.some((key) => fieldPresent(packet, key));
+      const anyPresent = group.some((key) => isPresent(packet?.[key]));
       if (!anyPresent) missing.push(group.join('|'));
     }
   }
@@ -202,8 +202,9 @@ export function validatePacket(contractId, packet, direction = 'input') {
   if (spec.mustMatchEnum && typeof spec.mustMatchEnum === 'object') {
     for (const [key, allowed] of Object.entries(spec.mustMatchEnum)) {
       if (!Array.isArray(allowed) || allowed.length === 0) continue;
-      if (!fieldPresent(packet, key)) continue;
-      if (!allowed.includes(packet[key])) missing.push(`${key}!=${allowed.join('|')}`);
+      const value = packet?.[key];
+      if (value === undefined || value === null) continue;
+      if (!allowed.includes(value)) missing.push(`${key}!=${allowed.join('|')}`);
     }
   }
 

package/lib/{agents → specialists}/postconditions.mjs

@@ -1,7 +1,7 @@
 /**
- * lib/agents/postconditions.mjs — hard binary postconditions per producer persona.
+ * lib/specialists/postconditions.mjs — hard binary postconditions per producer persona.
  *
- * `agents/contracts.json` carries free-text postconditions for documentation
+ * `specialists/contracts.json` carries free-text postconditions for documentation
  * purposes. This module adds binary, programmatically-validated assertions
  * that the persona's output packet must satisfy before a handoff is allowed
  * to proceed. Failure throws `ContractViolationError` with reason
@@ -40,7 +40,7 @@ function isLaterOrEqual(a, b) {
 }
 
 /**
- * Rule table. Keyed by producer name (matching agents/registry.json).
+ * Rule table. Keyed by producer name (matching specialists/registry.json).
  * Each rule:
  *   id          — stable identifier for violation logs
  *   description — single-line documentation

package/lib/{agents → specialists}/schema.mjs

@@ -1,5 +1,5 @@
 /**
- * lib/agents/schema.mjs — validation contract for agents/registry.json entries.
+ * lib/specialists/schema.mjs — validation contract for specialists/registry.json entries.
  *
  * Catches drift before it ships: missing description, unknown tool names,
  * promptFile pointing at a path that does not resolve, unrecognized
@@ -90,13 +90,13 @@ export function validateAgentRecord(record, { rootDir, registryKey } = {}) {
  * Validate every agent in a registry. Returns { errors: string[], agentCount }.
  */
 export function validateRegistry(registry, { rootDir } = {}) {
-  if (!registry || !Array.isArray(registry.agents)) {
-    return { errors: ['registry.agents is missing or not an array'], agentCount: 0 };
+  if (!registry || !Array.isArray(registry.specialists)) {
+    return { errors: ['registry.specialists is missing or not an array'], agentCount: 0 };
   }
   const errors = [];
   const seenNames = new Set();
-  for (let i = 0; i < registry.agents.length; i += 1) {
-    const record = registry.agents[i];
+  for (let i = 0; i < registry.specialists.length; i += 1) {
+    const record = registry.specialists[i];
     const recordErrors = validateAgentRecord(record, { rootDir, registryKey: i });
     errors.push(...recordErrors);
     if (record?.name) {
@@ -104,7 +104,7 @@ export function validateRegistry(registry, { rootDir } = {}) {
       seenNames.add(record.name);
     }
   }
-  return { errors, agentCount: registry.agents.length };
+  return { errors, agentCount: registry.specialists.length };
 }
 
 /**

package/lib/status.mjs

@@ -725,19 +725,21 @@ export async function buildStatus({
     executionContractModel,
   });
 
-  const personas = (registry.personas ?? []).map((persona) => ({
-    name: persona.name,
-    displayName: persona.displayName ?? persona.name,
-    role: persona.role ?? '',
-    description: persona.description ?? '',
-    modelTier: persona.modelTier ?? 'standard',
-  }));
+  const personas = registry.orchestrator
+    ? {
+        name: registry.orchestrator.name,
+        displayName: registry.orchestrator.displayName ?? registry.orchestrator.name,
+        role: registry.orchestrator.role ?? '',
+        description: registry.orchestrator.description ?? '',
+        modelTier: registry.orchestrator.modelTier ?? 'standard',
+      }
+    : null;
 
   const prefix = `${registry.prefix ?? 'cx'}-`;
-  const specialists = (registry.agents ?? []).map((agent) => ({
-    name: `${prefix}${agent.name}`,
-    description: agent.description ?? '',
-    modelTier: agent.modelTier ?? 'standard',
+  const specialists = (registry.specialists ?? []).map((specialist) => ({
+    name: `${prefix}${specialist.name}`,
+    description: specialist.description ?? '',
+    modelTier: specialist.modelTier ?? 'standard',
   }));
 
   const hooks = [];

package/lib/storage/backup.mjs

@@ -8,7 +8,7 @@
  *   observations/          — ~/.cx/observations/*.json
  *   sessions/              — ~/.cx/sessions/*.json
  *   config.env             — ~/.construct/config.env (secrets stripped unless opts.includeSecrets)
- *   registry.json          — agents/registry.json snapshot
+ *   registry.json          — specialists/registry.json snapshot
  *
  * The manifest uses SHA-256 checksums over each included file so
  * `backup verify` can detect corruption without extracting.
@@ -72,7 +72,7 @@ function archiveName() {
  *
  * @param {object} [opts]
  * @param {boolean} [opts.includeSecrets] - include raw secret values in config.env
- * @param {string} [opts.registryPath] - path to agents/registry.json
+ * @param {string} [opts.registryPath] - path to specialists/registry.json
  * @param {string} [opts.destDir] - destination directory (default: ~/.construct/backups)
  * @returns {{ path: string, manifest: object }}
  */

package/lib/tags/lifecycle.mjs

@@ -0,0 +1,278 @@
+/**
+ * lib/tags/lifecycle.mjs — tag lifecycle management for project and repo vocabularies.
+ *
+ * Pure file-read/write functions for the CLI to manage the tag
+ * controlled vocabulary over time: proposing new tags, adding project-local
+ * overrides, deprecating or archiving tags, and auditing tag usage across
+ * knowledge files.
+ *
+ * No LLM calls. No database calls. All functions are synchronous and
+ * operate on the filesystem via node:fs and node:path.
+ *
+ * File locations:
+ *   .cx/tags/proposed.jsonl              — append-only proposals from agents or mining
+ *   .cx/tags/vocabulary-overrides.json   — project-local tag additions/overrides
+ *   config/tag-vocabulary.json           — repo-wide vocabulary (edited by deprecateTag/archiveTag)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadVocabulary } from './vocabulary.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readJsonFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+function writeJsonFile(filePath, data) {
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function appendJsonlLine(filePath, record) {
+  ensureDir(filePath);
+  fs.appendFileSync(filePath, JSON.stringify(record) + '\n', 'utf8');
+}
+
+function proposedPath(rootDir) {
+  return path.join(rootDir, '.cx', 'tags', 'proposed.jsonl');
+}
+
+function overridesPath(rootDir) {
+  return path.join(rootDir, '.cx', 'tags', 'vocabulary-overrides.json');
+}
+
+function repoVocabPath(rootDir) {
+  return path.join(rootDir, 'config', 'tag-vocabulary.json');
+}
+
+function loadOverrides(rootDir) {
+  const p = overridesPath(rootDir);
+  if (!fs.existsSync(p)) return { version: 1, tags: [], facets: {} };
+  return readJsonFile(p);
+}
+
+function updateRepoVocabTag(rootDir, id, updates) {
+  const p = repoVocabPath(rootDir);
+  const vocab = readJsonFile(p);
+  const idx = vocab.tags.findIndex(t => t.id === id);
+  if (idx === -1) throw new Error(`tag not found in repo vocab: ${id}`);
+  vocab.tags[idx] = { ...vocab.tags[idx], ...updates };
+  writeJsonFile(p, vocab);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Appends a draft proposal entry to .cx/tags/proposed.jsonl.
+ * Does not validate against existing vocab: proposals may be genuinely new.
+ */
+export function proposeTag(id, { facet, label, autoThreshold, rootDir }) {
+  const record = {
+    id,
+    facet,
+    label,
+    auto_threshold: autoThreshold ?? null,
+    proposed_at: new Date().toISOString(),
+    status: 'proposed',
+  };
+  appendJsonlLine(proposedPath(rootDir), record);
+  return record;
+}
+
+/**
+ * Adds a project-local tag entry to .cx/tags/vocabulary-overrides.json.
+ * If the file does not exist it is created. If the tag id already exists in
+ * overrides it is replaced.
+ */
+export function addTag(id, { facet, label, scope = 'project', rootDir }) {
+  const overrides = loadOverrides(rootDir);
+  const entry = { id, facet, label, scope, status: 'active', added_at: new Date().toISOString() };
+  const existing = overrides.tags.findIndex(t => t.id === id);
+  if (existing !== -1) {
+    overrides.tags[existing] = entry;
+  } else {
+    overrides.tags.push(entry);
+  }
+  writeJsonFile(overridesPath(rootDir), overrides);
+  return entry;
+}
+
+/**
+ * Marks a tag as deprecated in the vocabulary.
+ * For repo-level tags (present in config/tag-vocabulary.json), edits that file.
+ * For project-local tags, edits .cx/tags/vocabulary-overrides.json.
+ */
+export function deprecateTag(id, { reason, gracePeriodDays = 90, replacedBy = null, rootDir }) {
+  const updates = {
+    status: 'deprecated',
+    deprecated_at: new Date().toISOString(),
+    deprecation_reason: reason,
+    grace_period_days: gracePeriodDays,
+    replaced_by: replacedBy,
+  };
+
+  const repoVocab = readJsonFile(repoVocabPath(rootDir));
+  const inRepo = repoVocab.tags.some(t => t.id === id);
+
+  if (inRepo) {
+    updateRepoVocabTag(rootDir, id, updates);
+    return { source: 'repo', id, ...updates };
+  }
+
+  const overrides = loadOverrides(rootDir);
+  const idx = overrides.tags.findIndex(t => t.id === id);
+  if (idx !== -1) {
+    overrides.tags[idx] = { ...overrides.tags[idx], ...updates };
+  } else {
+    overrides.tags.push({ id, facet: 'unknown', label: id, ...updates });
+  }
+  writeJsonFile(overridesPath(rootDir), overrides);
+  return { source: 'project', id, ...updates };
+}
+
+/**
+ * Marks a tag as archived in the vocabulary.
+ * Same source-selection logic as deprecateTag.
+ */
+export function archiveTag(id, { rootDir }) {
+  const updates = { status: 'archived', archived_at: new Date().toISOString() };
+
+  const repoVocab = readJsonFile(repoVocabPath(rootDir));
+  const inRepo = repoVocab.tags.some(t => t.id === id);
+
+  if (inRepo) {
+    updateRepoVocabTag(rootDir, id, updates);
+    return { source: 'repo', id, ...updates };
+  }
+
+  const overrides = loadOverrides(rootDir);
+  const idx = overrides.tags.findIndex(t => t.id === id);
+  if (idx !== -1) {
+    overrides.tags[idx] = { ...overrides.tags[idx], ...updates };
+  } else {
+    overrides.tags.push({ id, facet: 'unknown', label: id, ...updates });
+  }
+  writeJsonFile(overridesPath(rootDir), overrides);
+  return { source: 'project', id, ...updates };
+}
+
+/**
+ * Reads .cx/tags/proposed.jsonl and returns an array of proposal records.
+ * Returns [] if the file does not exist.
+ */
+export function listProposed(rootDir) {
+  const p = proposedPath(rootDir);
+  if (!fs.existsSync(p)) return [];
+  const lines = fs.readFileSync(p, 'utf8').split('\n').filter(l => l.trim() !== '');
+  return lines.map(l => JSON.parse(l));
+}
+
+/**
+ * Scans .cx/knowledge/**\/*.md frontmatter for tags and cross-references them
+ * against the vocabulary. Returns:
+ *   { active, overBudget, deprecated, unknown, orphan }
+ *
+ * active:      tags in use that are valid and current
+ * overBudget:  tags that exceed their expected_cardinality (checked per window)
+ * deprecated:  tags in use that are deprecated
+ * unknown:     tags in use that are not in vocabulary
+ * orphan:      tags in vocabulary with no usage in any document
+ */
+export function auditTags(rootDir) {
+  const vocab = loadVocabulary(rootDir);
+  const knowledgeDir = path.join(rootDir, '.cx', 'knowledge');
+
+  const usageCounts = new Map();
+
+  if (fs.existsSync(knowledgeDir)) {
+    collectTagsFromDir(knowledgeDir, usageCounts);
+  }
+
+  const active = [];
+  const overBudget = [];
+  const deprecated = [];
+  const unknown = [];
+
+  for (const [tagId, count] of usageCounts) {
+    const entry = vocab._tagMap ? vocab._tagMap.get(tagId) : vocab.tags.find(t => t.id === tagId);
+    if (!entry) {
+      unknown.push({ id: tagId, count });
+      continue;
+    }
+    if (entry.status === 'deprecated') {
+      deprecated.push({ id: tagId, count });
+      continue;
+    }
+    if (entry.expected_cardinality && count > entry.expected_cardinality) {
+      overBudget.push({ id: tagId, count, budget: entry.expected_cardinality });
+    } else {
+      active.push({ id: tagId, count });
+    }
+  }
+
+  const orphan = vocab.tags
+    .filter(t => t.status === 'active' && !usageCounts.has(t.id))
+    .map(t => ({ id: t.id, facet: t.facet }));
+
+  return { active, overBudget, deprecated, unknown, orphan };
+}
+
+// ---------------------------------------------------------------------------
+// Internal: recursive directory scanner for frontmatter tags
+// ---------------------------------------------------------------------------
+
+function collectTagsFromDir(dir, usageCounts) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectTagsFromDir(full, usageCounts);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const content = fs.readFileSync(full, 'utf8');
+      const tags = extractFrontmatterTags(content);
+      for (const tag of tags) {
+        usageCounts.set(tag, (usageCounts.get(tag) ?? 0) + 1);
+      }
+    }
+  }
+}
+
+function extractFrontmatterTags(content) {
+  if (!content.startsWith('---\n')) return [];
+  const closeIdx = content.indexOf('\n---\n', 4);
+  if (closeIdx === -1) return [];
+  const block = content.slice(4, closeIdx);
+  const tagLine = block.split('\n').find(l => l.startsWith('tags:'));
+  if (!tagLine) return [];
+
+  const inlineMatch = tagLine.match(/^tags:\s*\[(.+)\]/);
+  if (inlineMatch) {
+    return inlineMatch[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  }
+
+  const indented = [];
+  const lines = block.split('\n');
+  let inTagsBlock = false;
+  for (const line of lines) {
+    if (line.startsWith('tags:')) { inTagsBlock = true; continue; }
+    if (inTagsBlock) {
+      if (/^\s+-\s+/.test(line)) {
+        indented.push(line.replace(/^\s+-\s+/, '').trim().replace(/^["']|["']$/g, ''));
+      } else if (line.trim() !== '' && !/^\s/.test(line)) {
+        break;
+      }
+    }
+  }
+  return indented;
+}

package/lib/tags/vocabulary.mjs

@@ -0,0 +1,140 @@
+/**
+ * lib/tags/vocabulary.mjs — controlled tag vocabulary loader and validator.
+ *
+ * Loads the repo-wide controlled vocabulary from config/tag-vocabulary.json
+ * and optionally merges project-local overrides from .cx/tags/vocabulary-overrides.json.
+ *
+ * Exports:
+ *   loadVocabulary(rootDir)       — loads and merges vocab files, returns vocab object
+ *   validateTags(tagArray, vocab) — validates tags against vocab, returns classified result
+ *   lookupTag(id, vocab)          — returns tag entry or null
+ *   getTagsByFacet(facet, vocab)  — returns all active tags in a facet
+ *   isTagDeprecated(id, vocab)    — boolean
+ *   isTagArchived(id, vocab)      — boolean
+ *
+ * Merge semantics: project overrides may add new tags or change status fields
+ * on existing tags. They cannot remove repo-wide tags, only shadow/supersede them.
+ * Tags with the same id in both sources: the override entry wins entirely.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function readJsonFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+function buildTagMap(tags) {
+  const map = new Map();
+  for (const tag of tags) {
+    map.set(tag.id, tag);
+  }
+  return map;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Loads config/tag-vocabulary.json from rootDir and merges any project-local
+ * overrides from .cx/tags/vocabulary-overrides.json if the file exists.
+ * Returns the merged vocabulary object with a `_tagMap` cache attached.
+ */
+export function loadVocabulary(rootDir) {
+  const repoVocabPath = path.join(rootDir, 'config', 'tag-vocabulary.json');
+  const vocab = readJsonFile(repoVocabPath);
+
+  const overridePath = path.join(rootDir, '.cx', 'tags', 'vocabulary-overrides.json');
+  if (fs.existsSync(overridePath)) {
+    const overrides = readJsonFile(overridePath);
+    if (Array.isArray(overrides.tags)) {
+      const overrideById = buildTagMap(overrides.tags);
+      const merged = vocab.tags.map(t => overrideById.has(t.id) ? overrideById.get(t.id) : t);
+      for (const [id, entry] of overrideById) {
+        if (!vocab.tags.some(t => t.id === id)) {
+          merged.push(entry);
+        }
+      }
+      vocab.tags = merged;
+    }
+    if (overrides.facets) {
+      vocab.facets = { ...vocab.facets, ...overrides.facets };
+    }
+  }
+
+  vocab._tagMap = buildTagMap(vocab.tags);
+  return vocab;
+}
+
+/**
+ * Validates an array of tag IDs against the loaded vocabulary.
+ * Returns { valid: string[], unknown: string[], duplicateFacets: string[] }.
+ *
+ * unknown: tag IDs not present in vocab at all.
+ * duplicateFacets: tag IDs that violate an exclusive facet constraint (second
+ *   and subsequent tags from the same exclusive facet are listed here).
+ */
+export function validateTags(tagArray, vocab) {
+  const valid = [];
+  const unknown = [];
+  const duplicateFacets = [];
+  const seenExclusiveFacets = new Map();
+
+  for (const id of tagArray) {
+    const entry = vocab._tagMap ? vocab._tagMap.get(id) : vocab.tags.find(t => t.id === id);
+    if (!entry) {
+      unknown.push(id);
+      continue;
+    }
+
+    const facetDef = vocab.facets[entry.facet];
+    if (facetDef && facetDef.exclusive) {
+      if (seenExclusiveFacets.has(entry.facet)) {
+        duplicateFacets.push(id);
+        continue;
+      }
+      seenExclusiveFacets.set(entry.facet, id);
+    }
+
+    valid.push(id);
+  }
+
+  return { valid, unknown, duplicateFacets };
+}
+
+/**
+ * Returns the tag entry for the given id, or null if not found.
+ */
+export function lookupTag(id, vocab) {
+  if (vocab._tagMap) return vocab._tagMap.get(id) ?? null;
+  return vocab.tags.find(t => t.id === id) ?? null;
+}
+
+/**
+ * Returns all active tags belonging to the given facet.
+ */
+export function getTagsByFacet(facet, vocab) {
+  return vocab.tags.filter(t => t.facet === facet && t.status === 'active');
+}
+
+/**
+ * Returns true if the tag with the given id has status 'deprecated'.
+ */
+export function isTagDeprecated(id, vocab) {
+  const entry = lookupTag(id, vocab);
+  return entry !== null && entry.status === 'deprecated';
+}
+
+/**
+ * Returns true if the tag with the given id has status 'archived'.
+ */
+export function isTagArchived(id, vocab) {
+  const entry = lookupTag(id, vocab);
+  return entry !== null && entry.status === 'archived';
+}