@abarcenas/ai-workflow-template 1.40.0 → 1.43.0

package/scripts/setup/constants.js

@@ -46,11 +46,12 @@ export const TEMPLATE_HOOKS = {
       '#!/bin/sh',
       '',
       'node scripts/bump-version.js',
+      'node scripts/vocab-sync.js',
       'node scripts/validate-memory-schema.js',
       '',
     ].join('\n'),
     description:
-      'Auto-bump version + validate memory-bank schema before commits',
+      'Auto-bump version + sync vocabulary + validate memory-bank schema before commits',
   },
   'post-merge': {
     source: '.husky/post-merge',

package/scripts/sync.js

@@ -180,6 +180,7 @@ const scriptsToSync = [
   'memory-index.js',
   'bump-version.js',
   'validate-memory-schema.js',
+  'vocab-sync.js',
   'mcp-memory-server.js',
   'mcp/playwright-mcp-launcher.js',
   // Knowledgebase scripts

package/scripts/sync.test.js

@@ -53,6 +53,7 @@ describe('__scripts__ sync behavior', () => {
     'memory-index.js',
     'bump-version.js',
     'validate-memory-schema.js',
+    'vocab-sync.js',
     'mcp-memory-server.js',
     'mcp/playwright-mcp-launcher.js',
   ]
@@ -75,7 +76,7 @@ describe('__scripts__ sync behavior', () => {
     const result = runSync(tempDir)
     expect(result.status).toBe(0)
 
-    // Verify all 6 script files were created in the consumer's scripts/ dir
+    // Verify all 7 script files were created in the consumer's scripts/ dir
     for (const script of scriptsToSync) {
       const targetFile = join(tempDir, 'scripts', script)
       expect(
@@ -137,7 +138,7 @@ describe('__scripts__ sync behavior', () => {
     const result = runSync(tempDir, ['--force'])
     expect(result.status).toBe(0)
 
-    // Verify all 6 files were overwritten with source content
+    // Verify all 7 files were overwritten with source content
     for (const script of scriptsToSync) {
       const targetFile = join(tempDir, 'scripts', script)
       const sourceFile = join(sourceScriptsDir, script)
@@ -178,7 +179,7 @@ describe('__scripts__ sync behavior', () => {
       readFileSync(join(tempDir, '.agents-sync-manifest.json'), 'utf8'),
     )
 
-    // Verify all 6 __scripts__ entries are tracked with valid SHA-256 hashes
+    // Verify all 7 __scripts__ entries are tracked with valid SHA-256 hashes
     for (const script of scriptsToSync) {
       const key = `__scripts__/${script}`
       expect(updatedManifest.files[key]).toBeDefined()

package/scripts/validate-memory-schema.js

@@ -15,6 +15,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const MEMORY_BANK_DIR = resolve(process.cwd(), 'memory-bank');
 const VOCAB_PATH = resolve(MEMORY_BANK_DIR, '.vocabulary.json');
@@ -128,8 +129,21 @@ function validateFile(filePath, vocab) {
 
   // tags must be from vocabulary (warn only — don't block for new user-defined tags)
   if (fm.tags && Array.isArray(fm.tags) && vocab?.tags) {
-    const allTags = Object.values(vocab.tags).flat();
-    const unknown = fm.tags.filter(t => !allTags.includes(t));
+    // Known tags = all tags.* group values PLUS entity_patterns keys (e.g. npm, vitest, playwright)
+    const allTags = [
+      ...Object.values(vocab.tags).flat(),
+      ...Object.keys(vocab.entity_patterns || {}),
+    ];
+    // Normalize BOTH sides before the unknown-tag filter for parity with
+    // vocab-sync.js (which lowercases/kebab-cases tags before comparing and
+    // appending). Without this, a staged `My Tag` still warns "Unknown tags:
+    // [My Tag]" on every commit even after vocab-sync appends `my-tag`.
+    const normalizeTag = (tag) => String(tag).toLowerCase().trim().replace(/[\s_]+/g, '-');
+    const knownTags = new Set(allTags.map(normalizeTag).filter(Boolean));
+    const unknown = fm.tags.filter((t) => {
+      const normalized = normalizeTag(t);
+      return normalized && !knownTags.has(normalized);
+    });
     if (unknown.length > 0) {
       console.warn(
         `[validate-memory] ⚠ ${filePath}: Unknown tags: [${unknown.join(', ')}]. ` +
@@ -187,4 +201,15 @@ function main() {
   process.exit(0);
 }
 
-main();
+// Only run when executed directly (node scripts/validate-memory-schema.js).
+// When the module is imported — e.g. by unit tests exercising validateFile —
+// no side effects are triggered (main() calls process.exit(), which would
+// terminate the test runner).
+const isDirectRun =
+  process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectRun) {
+  main();
+}
+
+export { validateFile, main };

package/scripts/validate-memory-schema.test.js

@@ -0,0 +1,328 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// validate-memory-schema.test.js — Unit tests for the pre-commit validator
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Covers plan/feature-vocab-sync-1.md T10 (TEST-01..05) — the T3
+// entity_patterns awareness fix: `entity_patterns` keys (npm, vitest, …) count
+// as known tags, so they no longer produce false-positive "Unknown tags"
+// warnings; genuinely unknown tags still warn; and the validator keeps the
+// warn-don't-block contract (exit code stays 0 on warnings).
+//
+// The validator is exercised through its exported functions (testability seam
+// added in T10: `export { validateFile, main }` + `isDirectRun` guard, matching
+// scripts/vocab-sync.js / scripts/mcp-knowledgebase-server.js convention).
+// child_process.execSync (staged-file detection) and node:fs.readFileSync
+// (file + vocab content) are mocked hermetically so no git/FS side effects occur.
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'
+
+// Module-level mocks — the validator imports execSync from node:child_process
+// and readFileSync/existsSync from node:fs. vi.mock is hoisted above imports,
+// so the validator under test receives these mocked implementations.
+vi.mock('node:child_process', async () => {
+  const actual = await vi.importActual('node:child_process')
+  return { ...actual, execSync: vi.fn() }
+})
+
+vi.mock('node:fs', async () => {
+  const actual = await vi.importActual('node:fs')
+  return {
+    ...actual,
+    readFileSync: vi.fn(),
+    existsSync: vi.fn(() => true),
+  }
+})
+
+import { readFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+
+import { validateFile, main } from './validate-memory-schema.js'
+
+// ── Fixtures ─────────────────────────────────────────────────────────
+
+const FILE_PATH = 'memory-bank/sample.md'
+
+function makeFileContent({
+  id = 'sample',
+  title = 'Sample',
+  updated = '2026-08-03',
+  tags = [],
+  category = 'memory_ops',
+} = {}) {
+  return [
+    '---',
+    `id: ${id}`,
+    `title: "${title}"`,
+    `updated: ${updated}`,
+    `tags: [${tags.join(', ')}]`,
+    'entities: [sample]',
+    `category: ${category}`,
+    '---',
+    '',
+    '# Sample',
+    '',
+    'Body.',
+    '',
+  ].join('\n')
+}
+
+// Mirrors the real memory-bank/.vocabulary.json shape: tags.* groups hold
+// known concept tags; entity_patterns keys hold component/tool names.
+const VOCAB = {
+  categories: { memory_ops: 'Memory operations', context: 'Context files' },
+  tags: {
+    agent_roles: ['architect', 'implementer'],
+    workflow: ['planning', 'review'],
+    memory_ops: ['indexing'],
+    topic: ['mcp', 'graphify'],
+  },
+  entity_patterns: {
+    npm: { patterns: ['\\bnpm\\b'] },
+    vitest: { patterns: ['\\bvitest\\b'] },
+    playwright: { patterns: ['\\bplaywright\\b'] },
+  },
+}
+
+// ── Test harness ─────────────────────────────────────────────────────
+
+let warnSpy
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+// ═════════════════════════════════════════════════════════════════════════════
+// T10 scenarios — entity_patterns awareness (plan TEST-01..05)
+// ═════════════════════════════════════════════════════════════════════════════
+
+describe('validateFile — entity_patterns awareness (plan T10)', () => {
+  it('TEST-01: does NOT warn when a tag is an entity_patterns key (npm)', () => {
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['npm'] }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(errors).toEqual([])
+  })
+
+  it('TEST-02: does NOT warn when a tag is in a tags.* group (mcp in tags.topic)', () => {
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['mcp'] }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(errors).toEqual([])
+  })
+
+  it('TEST-03: warns when a tag is genuinely unknown (some-random-tag)', () => {
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['some-random-tag'] }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('some-random-tag'))
+    // warn-don't-block: a warning is NOT a validation error
+    expect(errors).toEqual([])
+  })
+
+  it('TEST-04: warns ONLY for truly unknown tags when mixed with entity_patterns keys', () => {
+    readFileSync.mockReturnValue(
+      makeFileContent({ tags: ['npm', 'vitest', 'some-random-tag'] })
+    )
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    const warnText = warnSpy.mock.calls.map((call) => String(call[0])).join(' ')
+    expect(warnText).toContain('Unknown tags')
+    expect(warnText).toContain('some-random-tag')
+    expect(warnText).not.toContain('npm')
+    expect(warnText).not.toContain('vitest')
+    expect(errors).toEqual([])
+  })
+
+  it('TEST-05: handles a vocab with no entity_patterns key gracefully (no crash)', () => {
+    const vocabNoEntityPatterns = {
+      categories: { memory_ops: 'Memory operations' },
+      tags: { topic: ['mcp'] },
+      // deliberately NO entity_patterns key
+    }
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['npm'] }))
+
+    // `Object.keys(vocab.entity_patterns || {})` must not throw on undefined
+    expect(() => validateFile(FILE_PATH, vocabNoEntityPatterns)).not.toThrow()
+    // without entity_patterns, 'npm' is genuinely unknown → degrades to a warning
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('npm'))
+  })
+
+  it('TEST-05b: does not crash with a completely empty vocab object ({})', () => {
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['whatever'] }))
+
+    expect(() => validateFile(FILE_PATH, {})).not.toThrow()
+    // no tags.* groups and no entity_patterns → tag check skipped, no warning
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+  })
+})
+
+// ═════════════════════════════════════════════════════════════════════════════
+// Reviewer M1 — normalization parity with vocab-sync
+// ═════════════════════════════════════════════════════════════════════════════
+// vocab-sync.js normalizes tags (lowercase, kebab-case) before comparing and
+// appending, so after it appends `my-tag` a staged file whose frontmatter still
+// says `My Tag` must NOT warn. The validator therefore normalizes both sides
+// before the unknown-tag filter (reviewer finding M1). The three scenarios below
+// lock in: (a) normalized-known no-warn, (b) genuinely unknown still warns,
+// (c) mixed-case genuinely unknown still warns.
+
+describe('validateFile — tag normalization parity with vocab-sync (reviewer M1)', () => {
+  it('M1-a: does NOT warn when a mixed-case staged tag normalizes to a known tag (My Tag → my-tag)', () => {
+    const vocabWithNormalized = {
+      ...VOCAB,
+      tags: { ...VOCAB.tags, topic: [...VOCAB.tags.topic, 'my-tag'] },
+    }
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['My Tag'] }))
+
+    const errors = validateFile(FILE_PATH, vocabWithNormalized)
+
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(errors).toEqual([])
+  })
+
+  it('M1-b: still warns when a tag is genuinely unknown after normalization (some-random-tag)', () => {
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['some-random-tag'] }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('some-random-tag'))
+    // warn-don't-block: a warning is NOT a validation error
+    expect(errors).toEqual([])
+  })
+
+  it('M1-c: still warns for a mixed-case tag that is NOT in the vocabulary', () => {
+    readFileSync.mockReturnValue(makeFileContent({ tags: ['Random Tag'] }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Random Tag'))
+    // warn-don't-block: a warning is NOT a validation error
+    expect(errors).toEqual([])
+  })
+})
+
+// ═════════════════════════════════════════════════════════════════════════════
+// main() — exit-code contract (warn-don't-block, REQ-05 / CON-02)
+// ═════════════════════════════════════════════════════════════════════════════
+
+describe('main() — exit code behavior', () => {
+  it('exits 0 when unknown-tag warnings occur (warnings do NOT block the commit)', () => {
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {})
+    execSync.mockReturnValue(`${FILE_PATH}\n`)
+    readFileSync.mockImplementation((filePath) => {
+      if (String(filePath).includes('.vocabulary.json')) return JSON.stringify(VOCAB)
+      return makeFileContent({ tags: ['some-random-tag'] })
+    })
+
+    main()
+
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Unknown tags'))
+    expect(exitSpy).toHaveBeenCalledWith(0)
+  })
+
+  it('exits 0 when no memory-bank files are staged', () => {
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {})
+    execSync.mockReturnValue('')
+
+    main()
+
+    expect(exitSpy).toHaveBeenCalledWith(0)
+  })
+
+  it('exits 1 when validation errors are found', () => {
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {})
+    execSync.mockReturnValue(`${FILE_PATH}\n`)
+    readFileSync.mockImplementation((filePath) => {
+      if (String(filePath).includes('.vocabulary.json')) return JSON.stringify(VOCAB)
+      // id does not match the filename → real validation error
+      return makeFileContent({ id: 'mismatched-id', tags: ['mcp'] })
+    })
+
+    main()
+
+    expect(exitSpy).toHaveBeenCalledWith(1)
+  })
+})
+
+// ═════════════════════════════════════════════════════════════════════════════
+// validateFile — error branches (robustness / coverage support)
+// ═════════════════════════════════════════════════════════════════════════════
+
+describe('validateFile — error branches', () => {
+  it('returns a "Cannot read file" error when the file is unreadable', () => {
+    readFileSync.mockImplementation(() => {
+      throw new Error('ENOENT')
+    })
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(errors).toEqual([`Cannot read file: ${FILE_PATH}`])
+  })
+
+  it('reports missing YAML frontmatter', () => {
+    readFileSync.mockReturnValue('# No frontmatter here\n')
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(errors).toEqual(['Missing YAML frontmatter (file must start with ---...---)'])
+  })
+
+  it('reports missing required fields', () => {
+    readFileSync.mockReturnValue('---\nid: sample\n---\n')
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(errors).toEqual([
+      "Missing required field: 'title'",
+      "Missing required field: 'updated'",
+      "Missing required field: 'tags'",
+      "Missing required field: 'category'",
+    ])
+  })
+
+  it('reports an id/filename mismatch', () => {
+    readFileSync.mockReturnValue(makeFileContent({ id: 'mismatched-id' }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(errors).toContain(
+      `Field 'id' (mismatched-id) does not match filename (sample)`
+    )
+  })
+
+  it('reports an invalid updated date', () => {
+    readFileSync.mockReturnValue(makeFileContent({ updated: 'yesterday' }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(errors).toContain(
+      `Field 'updated' (yesterday) is not a valid date. Use YYYY-MM-DD format.`
+    )
+  })
+
+  it('reports an invalid category', () => {
+    readFileSync.mockReturnValue(makeFileContent({ category: 'not-a-category' }))
+
+    const errors = validateFile(FILE_PATH, VOCAB)
+
+    expect(errors).toContain(
+      `Invalid category 'not-a-category'. Allowed: memory_ops, context`
+    )
+  })
+})

package/scripts/vocab-sync.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+/**
+ * vocab-sync.js — Pre-commit hook vocabulary sync.
+ *
+ * Scans STAGED memory-bank/*.md files for YAML frontmatter tags and appends
+ * any genuinely-new tags to memory-bank/.vocabulary.json under the `topic`
+ * group (the default catch-all). A tag is considered "known" when it exists
+ * in any `tags.*` group or as an `entity_patterns` key.
+ *
+ * Warning-only hook — never blocks the commit. Exits 0 unless an unexpected
+ * error occurs (then exits 1 with an error message).
+ *
+ * Usage (in .husky/pre-commit, BEFORE validate-memory-schema.js):
+ *   node scripts/vocab-sync.js
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MEMORY_BANK_DIR = resolve(process.cwd(), 'memory-bank');
+const VOCAB_PATH = resolve(MEMORY_BANK_DIR, '.vocabulary.json');
+
+// ── Load vocabulary ──────────────────────────────────────────────────
+
+function loadVocabulary() {
+  if (!existsSync(VOCAB_PATH)) {
+    console.warn('[vocab-sync] ⚠ No .vocabulary.json found at memory-bank/.vocabulary.json');
+    console.warn('[vocab-sync]   Vocabulary sync skipped.');
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(VOCAB_PATH, 'utf8'));
+  } catch (err) {
+    console.warn(`[vocab-sync] ⚠ Failed to parse .vocabulary.json: ${err.message}`);
+    console.warn('[vocab-sync]   Vocabulary sync skipped.');
+    return null;
+  }
+}
+
+// ── Get staged memory-bank files ─────────────────────────────────────
+
+function getStagedMemoryFiles() {
+  try {
+    const output = execSync(
+      'git diff --cached --name-only --diff-filter=ACM',
+      { encoding: 'utf8', cwd: process.cwd() }
+    );
+    return output
+      .split('\n')
+      .filter(f => f.startsWith('memory-bank/') && f.endsWith('.md') && !f.includes('/.index/'));
+  } catch {
+    return [];
+  }
+}
+
+// ── Parse frontmatter ────────────────────────────────────────────────
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const raw = match[1];
+  const fm = {};
+  for (const line of raw.split('\n')) {
+    const kv = line.match(/^(\w[\w-]*):\s*(.*)/);
+    if (kv) {
+      const key = kv[1];
+      let value = kv[2].trim();
+      // Parse arrays
+      if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+      } else if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      fm[key] = value;
+    }
+  }
+  return fm;
+}
+
+// ── Tag normalization ────────────────────────────────────────────────
+
+function normalizeTag(tag) {
+  return String(tag)
+    .toLowerCase()
+    .trim()
+    .replace(/[\s_]+/g, '-');
+}
+
+// ── Known tag collection ─────────────────────────────────────────────
+
+function buildKnownTags(vocab) {
+  const known = new Set();
+
+  // All values across all tags.* groups
+  for (const group of Object.values(vocab?.tags || {})) {
+    // Guard against malformed vocab shapes (consumer-controlled input): if
+    // `vocab.tags` is an array or a group is a plain string, iterating the
+    // group directly would walk CHARACTERS instead of tags. Skip non-arrays.
+    if (!Array.isArray(group)) continue;
+    for (const tag of group) {
+      const normalized = normalizeTag(tag);
+      if (normalized) known.add(normalized);
+    }
+  }
+
+  // All entity_patterns keys (component/tool names)
+  for (const key of Object.keys(vocab?.entity_patterns || {})) {
+    const normalized = normalizeTag(key);
+    if (normalized) known.add(normalized);
+  }
+
+  return known;
+}
+
+// ── Collect new tags ─────────────────────────────────────────────────
+
+function collectNewTags(stagedFiles, vocab) {
+  const known = buildKnownTags(vocab);
+  const newTags = new Set();
+
+  for (const file of stagedFiles) {
+    let content;
+    try {
+      content = readFileSync(resolve(process.cwd(), file), 'utf8');
+    } catch {
+      continue; // unreadable file — skip
+    }
+
+    const fm = parseFrontmatter(content);
+    if (!fm || !Array.isArray(fm.tags)) continue;
+
+    for (const rawTag of fm.tags) {
+      const tag = normalizeTag(rawTag);
+      if (!tag) continue; // empty / whitespace-only
+      if (known.has(tag)) continue; // already in vocabulary
+      newTags.add(tag);
+    }
+  }
+
+  return [...newTags].sort();
+}
+
+// ── Sync ─────────────────────────────────────────────────────────────
+
+function syncVocabulary(stagedFiles, vocab) {
+  const newTags = collectNewTags(stagedFiles, vocab);
+  if (newTags.length === 0) return false; // nothing to do — no-op
+
+  // Default placement: the `topic` catch-all group
+  if (!vocab.tags) vocab.tags = {};
+  if (!Array.isArray(vocab.tags.topic)) vocab.tags.topic = [];
+
+  // Append, normalize existing entries, dedupe, sort alphabetically
+  const merged = new Set([
+    ...vocab.tags.topic.map(normalizeTag).filter(Boolean),
+    ...newTags,
+  ]);
+  vocab.tags.topic = [...merged].sort();
+
+  // Write back with 2-space indent + trailing newline (matches existing format)
+  writeFileSync(VOCAB_PATH, `${JSON.stringify(vocab, null, 2)}\n`, 'utf8');
+
+  // Stage the updated vocabulary so it commits with the same change
+  try {
+    execSync('git add memory-bank/.vocabulary.json', { cwd: process.cwd() });
+  } catch (err) {
+    console.warn(`[vocab-sync] ⚠ Could not stage memory-bank/.vocabulary.json: ${err.message}`);
+  }
+
+  console.warn(
+    `[vocab-sync] Added ${newTags.length} tag(s) to memory-bank/.vocabulary.json: [${newTags.join(', ')}]`
+  );
+  return true;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────
+
+function main() {
+  const stagedFiles = getStagedMemoryFiles();
+  if (stagedFiles.length === 0) return; // no memory-bank files staged — silent no-op
+
+  const vocab = loadVocabulary();
+  if (!vocab) return; // graceful skip when vocabulary is unavailable
+
+  syncVocabulary(stagedFiles, vocab);
+}
+
+// Only run when executed directly (node scripts/vocab-sync.js). When the
+// module is imported — e.g. by unit tests — no side effects are triggered.
+const isDirectRun =
+  process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectRun) {
+  try {
+    main();
+  } catch (err) {
+    console.error(`[vocab-sync] ❌ Unhandled error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+export {
+  loadVocabulary,
+  getStagedMemoryFiles,
+  parseFrontmatter,
+  normalizeTag,
+  buildKnownTags,
+  collectNewTags,
+  syncVocabulary,
+  main,
+};