@wazir-dev/cli 1.0.0

package/tooling/src/capture/usage.js

@@ -0,0 +1,270 @@
+import fs from 'node:fs';
+
+export function estimateTokens(bytes) {
+  if (bytes < 0) {
+    process.stderr.write(`warning: estimateTokens called with negative bytes (${bytes}), returning 0\n`);
+    return 0;
+  }
+  if (bytes === 0) return 0;
+  return Math.ceil(bytes / 4);
+}
+
+function createDefaultUsage(runId) {
+  const now = new Date().toISOString();
+  return {
+    schema_version: 1,
+    run_id: runId,
+    created_at: now,
+    updated_at: now,
+    phases: {},
+    roles: {},
+    savings: {
+      capture_routing: {
+        raw_bytes: 0,
+        summary_bytes: 0,
+        estimated_tokens_avoided: 0,
+        strategy: 'byte_heuristic',
+      },
+      context_mode: {
+        available: false,
+        raw_kb: 0,
+        context_kb: 0,
+        savings_ratio: '0%',
+        per_tool: {},
+      },
+      compaction: {
+        compaction_count: 0,
+        pre_compaction_tokens_est: 0,
+        post_compaction_tokens_est: 0,
+      },
+    },
+    totals: {
+      total_events: 0,
+      total_capture_bytes_raw: 0,
+      total_capture_bytes_summary: 0,
+      total_estimated_tokens_if_raw: 0,
+      total_estimated_tokens_avoided: 0,
+      savings_percentage: '0%',
+    },
+  };
+}
+
+function writeUsageAtomic(runPaths, usage) {
+  usage.updated_at = new Date().toISOString();
+  const tmpPath = `${runPaths.usagePath}.tmp`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(usage, null, 2)}\n`);
+  fs.renameSync(tmpPath, runPaths.usagePath);
+}
+
+function recalcTotals(usage) {
+  let totalEvents = 0;
+  let totalRaw = 0;
+  let totalSummary = 0;
+
+  for (const phase of Object.values(usage.phases)) {
+    totalEvents += phase.events_count ?? 0;
+    totalRaw += phase.capture_bytes_raw ?? 0;
+    totalSummary += phase.capture_bytes_summary ?? 0;
+  }
+
+  usage.totals.total_events = totalEvents;
+  usage.totals.total_capture_bytes_raw = totalRaw;
+  usage.totals.total_capture_bytes_summary = totalSummary;
+  usage.totals.total_estimated_tokens_if_raw = estimateTokens(totalRaw);
+  usage.totals.total_estimated_tokens_avoided = estimateTokens(totalRaw - totalSummary);
+
+  const ifRaw = usage.totals.total_estimated_tokens_if_raw;
+  const avoided = usage.totals.total_estimated_tokens_avoided;
+  usage.totals.savings_percentage = ifRaw > 0
+    ? `${((avoided / ifRaw) * 100).toFixed(1)}%`
+    : '0%';
+}
+
+export function readUsage(runPaths) {
+  if (!fs.existsSync(runPaths.usagePath)) {
+    return createDefaultUsage('unknown');
+  }
+
+  try {
+    const raw = fs.readFileSync(runPaths.usagePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    process.stderr.write(`warning: malformed usage.json at ${runPaths.usagePath}, using defaults\n`);
+    return createDefaultUsage('unknown');
+  }
+}
+
+export function initUsage(runPaths, runId) {
+  if (fs.existsSync(runPaths.usagePath)) {
+    return readUsage(runPaths);
+  }
+
+  const usage = createDefaultUsage(runId);
+  writeUsageAtomic(runPaths, usage);
+  return usage;
+}
+
+export function recordCaptureSavings(runPaths, rawBytes, summaryBytes) {
+  const usage = readUsage(runPaths);
+  usage.savings.capture_routing.raw_bytes += rawBytes;
+  usage.savings.capture_routing.summary_bytes += summaryBytes;
+  usage.savings.capture_routing.estimated_tokens_avoided = estimateTokens(
+    usage.savings.capture_routing.raw_bytes - usage.savings.capture_routing.summary_bytes,
+  );
+  writeUsageAtomic(runPaths, usage);
+}
+
+export function recordPhaseUsage(runPaths, phase, data) {
+  const usage = readUsage(runPaths);
+  const existing = usage.phases[phase] ?? {
+    started_at: new Date().toISOString(),
+    completed_at: null,
+    events_count: 0,
+    capture_bytes_raw: 0,
+    capture_bytes_summary: 0,
+    estimated_tokens_if_raw: 0,
+    estimated_tokens_avoided: 0,
+  };
+
+  existing.events_count += data.events_count ?? 0;
+  existing.capture_bytes_raw = data.capture_bytes_raw ?? existing.capture_bytes_raw;
+  existing.capture_bytes_summary = data.capture_bytes_summary ?? existing.capture_bytes_summary;
+  existing.estimated_tokens_if_raw = estimateTokens(existing.capture_bytes_raw);
+  existing.estimated_tokens_avoided = estimateTokens(existing.capture_bytes_raw - existing.capture_bytes_summary);
+
+  if (data.completed_at) {
+    existing.completed_at = data.completed_at;
+  }
+
+  usage.phases[phase] = existing;
+  recalcTotals(usage);
+  writeUsageAtomic(runPaths, usage);
+}
+
+// Totals are derived from phase data, not role data — intentionally no recalcTotals here
+export function recordRoleUsage(runPaths, role, data) {
+  const usage = readUsage(runPaths);
+  const existing = usage.roles[role] ?? {
+    events_count: 0,
+    capture_bytes_raw: 0,
+    estimated_tokens_if_raw: 0,
+  };
+
+  existing.events_count = data.events_count ?? existing.events_count;
+  existing.capture_bytes_raw = data.capture_bytes_raw ?? existing.capture_bytes_raw;
+  existing.estimated_tokens_if_raw = estimateTokens(existing.capture_bytes_raw);
+
+  usage.roles[role] = existing;
+  writeUsageAtomic(runPaths, usage);
+}
+
+export function recordContextModeSavings(runPaths, statsData) {
+  const usage = readUsage(runPaths);
+
+  if (statsData.raw_kb === 0 && usage.savings.context_mode.raw_kb > 0) {
+    return;
+  }
+
+  usage.savings.context_mode = {
+    available: statsData.available ?? false,
+    raw_kb: statsData.raw_kb ?? 0,
+    context_kb: statsData.context_kb ?? 0,
+    savings_ratio: statsData.savings_ratio ?? '0%',
+    per_tool: statsData.per_tool ?? {},
+  };
+
+  writeUsageAtomic(runPaths, usage);
+}
+
+export function recordCompaction(runPaths, preTokens, postTokens) {
+  const usage = readUsage(runPaths);
+  usage.savings.compaction.compaction_count += 1;
+  usage.savings.compaction.pre_compaction_tokens_est += preTokens;
+  usage.savings.compaction.post_compaction_tokens_est += postTokens;
+  writeUsageAtomic(runPaths, usage);
+}
+
+function formatNumber(n) {
+  return n.toLocaleString('en-US');
+}
+
+export function generateReport(runPaths, format, options = {}) {
+  const usage = readUsage(runPaths);
+
+  // Filter to a single phase if requested
+  if (options.phase && usage.phases[options.phase]) {
+    const filtered = {
+      ...usage,
+      phases: { [options.phase]: usage.phases[options.phase] },
+    };
+    if (format === 'json') {
+      return JSON.stringify(filtered, null, 2);
+    }
+    // Fall through to render with filtered usage
+    Object.assign(usage, filtered);
+  } else if (format === 'json') {
+    return JSON.stringify(usage, null, 2);
+  }
+
+  const cr = usage.savings.capture_routing;
+  const cm = usage.savings.context_mode;
+  const co = usage.savings.compaction;
+
+  const crRaw = cr.estimated_tokens_avoided + estimateTokens(cr.summary_bytes);
+  const crAfter = estimateTokens(cr.summary_bytes);
+  const cmRaw = estimateTokens(Math.round(cm.raw_kb * 1024));
+  const cmAfter = estimateTokens(Math.round(cm.context_kb * 1024));
+  const coSaved = co.pre_compaction_tokens_est - co.post_compaction_tokens_est;
+
+  const withoutSavings = crRaw + cmRaw + co.pre_compaction_tokens_est;
+  const saOnly = cmRaw + co.post_compaction_tokens_est + crAfter;
+  const withAll = crAfter + cmAfter + co.post_compaction_tokens_est;
+  const overallPct = withoutSavings > 0
+    ? ((1 - withAll / withoutSavings) * 100).toFixed(1)
+    : '0.0';
+
+  let report = `# Usage Report: ${usage.run_id}\n\n`;
+
+  report += '## Token Savings by Strategy\n';
+  report += '| Strategy         | Raw (est. tokens) | After (est. tokens) | Avoided            |\n';
+  report += '|------------------|--------------------|---------------------|--------------------|\n';
+  report += `| Capture routing  | ${formatNumber(crRaw).padStart(18)} | ${formatNumber(crAfter).padStart(19)} | ${formatNumber(cr.estimated_tokens_avoided).padStart(18)} |\n`;
+  report += `| Context-mode     | ${formatNumber(cmRaw).padStart(18)} | ${formatNumber(cmAfter).padStart(19)} | ${formatNumber(cmRaw - cmAfter).padStart(18)} |\n`;
+  report += `| Compaction       | ${formatNumber(co.pre_compaction_tokens_est).padStart(18)} | ${formatNumber(co.post_compaction_tokens_est).padStart(19)} | ${formatNumber(coSaved).padStart(18)} |\n`;
+  report += '\n';
+
+  report += '## "What If" Comparison\n';
+  report += '| Scenario                          | Est. tokens consumed |\n';
+  report += '|-----------------------------------|----------------------|\n';
+  report += `| Without any savings strategies    | ${formatNumber(withoutSavings).padStart(20)} |\n`;
+  report += `| With Wazir savings only      | ${formatNumber(saOnly).padStart(20)} |\n`;
+  report += `| With Wazir + context-mode    | ${formatNumber(withAll).padStart(20)} |\n`;
+  report += `| **Actual savings**                | **${overallPct}%**${' '.repeat(Math.max(0, 14 - overallPct.length))} |\n`;
+  report += '\n';
+
+  const phases = Object.entries(usage.phases);
+  if (phases.length > 0) {
+    report += '## Phase Breakdown\n';
+    report += '| Phase    | Events | Raw bytes   | Summary bytes | Est. tokens avoided |\n';
+    report += '|----------|--------|-------------|---------------|---------------------|\n';
+    for (const [name, p] of phases) {
+      report += `| ${name.padEnd(8)} | ${String(p.events_count).padStart(6)} | ${formatNumber(p.capture_bytes_raw).padStart(11)} | ${formatNumber(p.capture_bytes_summary).padStart(13)} | ${formatNumber(p.estimated_tokens_avoided).padStart(19)} |\n`;
+    }
+    report += '\n';
+  }
+
+  const roles = Object.entries(usage.roles);
+  if (roles.length > 0) {
+    report += '## Role Breakdown\n';
+    report += '| Role       | Events | Raw bytes   | Est. tokens if raw |\n';
+    report += '|------------|--------|-------------|--------------------|\n';
+    for (const [name, r] of roles) {
+      report += `| ${name.padEnd(10)} | ${String(r.events_count).padStart(6)} | ${formatNumber(r.capture_bytes_raw).padStart(11)} | ${formatNumber(r.estimated_tokens_if_raw).padStart(18)} |\n`;
+    }
+    report += '\n';
+  }
+
+  report += 'Estimation method: byte heuristic (ceil(bytes/4))\n';
+
+  return report;
+}

package/tooling/src/checks/branches.js

@@ -0,0 +1,50 @@
+import { execFileSync } from 'node:child_process';
+
+const ALLOWED_PATTERNS = [
+  /^main$/,
+  /^develop$/,
+  /^feat\/.+$/,
+  /^feature\/.+$/,
+  /^fix\/.+$/,
+  /^chore\/.+$/,
+  /^codex\/.+$/,
+  /^release\/.+$/,
+  /^hotfix\/.+$/,
+  /^worktree-.+$/,
+];
+
+function getCurrentBranch(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf8',
+      cwd,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function validateBranchName(branchName, options = {}) {
+  const branch = branchName || getCurrentBranch(options.cwd);
+
+  if (!branch) {
+    return {
+      exitCode: 1,
+      stderr: 'Branch name validation failed:\n- Could not determine current branch name\n',
+    };
+  }
+
+  const isAllowed = ALLOWED_PATTERNS.some((pattern) => pattern.test(branch));
+
+  if (!isAllowed) {
+    return {
+      exitCode: 1,
+      stderr: `Branch name validation failed:\n- "${branch}" does not match any allowed pattern: main, develop, feat/*, feature/*, fix/*, chore/*, codex/*, release/*, hotfix/*, worktree-*\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: `Branch name validation passed: "${branch}"\n`,
+  };
+}

package/tooling/src/checks/brand-truth.js

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const EXCLUDED_DOC_DIRS = new Set(['plans']);
+const EXCLUDED_DOC_FILES = new Set([
+  'terminology-policy.md',
+]);
+
+const BRAND_PATTERNS = [
+  { label: 'Agent OS', regex: /\bAgent OS\b/g },
+  { label: 'agent-os', regex: /\bagent-os\b/g },
+  { label: 'Symphony', regex: /\bSymphony\b/g },
+  { label: 'Wazir OS', regex: /\bWazir OS\b/g },
+];
+
+function normalizeAllowedLegacyReferences(content) {
+  return content
+    .replace(/archive\/legacy-agent-os\/[^\s)`]*/g, 'archive/<legacy>')
+    .replace(/archive\/v5\.1-agent-os-daemon\/[^\s)`]*/g, 'archive/<legacy>')
+    .replace(/migration\/v5\.1-agent-os-to-wazir\.md/g, 'migration/<legacy>');
+}
+
+function walkMarkdownFiles(dirPath, files = []) {
+  if (!fs.existsSync(dirPath)) {
+    return files;
+  }
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!EXCLUDED_DOC_DIRS.has(entry.name)) {
+        walkMarkdownFiles(path.join(dirPath, entry.name), files);
+      }
+      continue;
+    }
+
+    if (entry.name.endsWith('.md') && !EXCLUDED_DOC_FILES.has(entry.name)) {
+      files.push(path.join(dirPath, entry.name));
+    }
+  }
+
+  return files;
+}
+
+function walkFiles(dirPath, files = []) {
+  if (!fs.existsSync(dirPath)) {
+    return files;
+  }
+
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const absolutePath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      walkFiles(absolutePath, files);
+      continue;
+    }
+
+    files.push(absolutePath);
+  }
+
+  return files;
+}
+
+function collectBrandSurfaceFiles(projectRoot) {
+  return [
+    path.join(projectRoot, 'README.md'),
+    path.join(projectRoot, 'CLAUDE.md'),
+    path.join(projectRoot, 'AGENTS.md'),
+    path.join(projectRoot, 'CHANGELOG.md'),
+    ...walkMarkdownFiles(path.join(projectRoot, 'docs')),
+    ...walkFiles(path.join(projectRoot, 'expertise')),
+    ...walkFiles(path.join(projectRoot, 'examples')),
+    ...walkFiles(path.join(projectRoot, 'roles')),
+    ...walkFiles(path.join(projectRoot, 'workflows')),
+    ...walkFiles(path.join(projectRoot, 'skills')),
+    path.join(projectRoot, 'hooks', 'README.md'),
+    path.join(projectRoot, 'hooks', 'session-start'),
+    ...walkFiles(path.join(projectRoot, 'templates', 'artifacts')),
+    path.join(projectRoot, 'templates', 'README.md'),
+    ...walkFiles(path.join(projectRoot, 'exports', 'hosts')),
+  ].filter((filePath) => fs.existsSync(filePath) && fs.statSync(filePath).isFile());
+}
+
+export function validateBrandTruthAtProjectRoot(projectRoot) {
+  const errors = [];
+
+  for (const filePath of collectBrandSurfaceFiles(projectRoot)) {
+    const relativePath = path.relative(projectRoot, filePath);
+    const content = normalizeAllowedLegacyReferences(fs.readFileSync(filePath, 'utf8'));
+
+    for (const pattern of BRAND_PATTERNS) {
+      pattern.regex.lastIndex = 0;
+
+      if (pattern.regex.test(content)) {
+        errors.push(`${relativePath}: contains forbidden brand term "${pattern.label}"`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      exitCode: 1,
+      stderr: `Brand truth validation failed:\n- ${errors.join('\n- ')}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: 'Brand truth validation passed.\n',
+  };
+}

package/tooling/src/checks/changelog.js

@@ -0,0 +1,231 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const VALID_CATEGORIES = new Set([
+  'Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security',
+]);
+
+const UNRELEASED_PATTERN = /^## \[Unreleased\]/m;
+const ENTRY_PATTERN = /^- .+$/m;
+// Lowercase v + three-component semver. Filters out legacy tags like V5.1, V6.1 (capital V, two-component).
+const SEMVER_TAG_PATTERN = /^v\d+\.\d+\.\d+$/;
+
+function parseChangelog(content) {
+  const errors = [];
+
+  if (!UNRELEASED_PATTERN.test(content)) {
+    errors.push('Missing [Unreleased] section');
+  }
+
+  // Validate categories and check for empty ones
+  const categoryRegex = /^### (.+)$/gm;
+  let match;
+  while ((match = categoryRegex.exec(content)) !== null) {
+    const category = match[1].trim();
+    if (!VALID_CATEGORIES.has(category)) {
+      errors.push(`Invalid category "${category}" — allowed: ${[...VALID_CATEGORIES].join(', ')}`);
+    } else {
+      // Check if category has at least one entry before next heading or EOF
+      const afterCategory = content.slice(match.index + match[0].length);
+      const nextHeading = afterCategory.search(/^##/m);
+      const block = nextHeading === -1 ? afterCategory : afterCategory.slice(0, nextHeading);
+      if (!ENTRY_PATTERN.test(block)) {
+        errors.push(`Empty category "${category}" — remove it or add entries`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+function getUnreleasedEntries(content) {
+  const unreleasedIdx = content.search(UNRELEASED_PATTERN);
+  if (unreleasedIdx === -1) return [];
+
+  const afterUnreleased = content.slice(unreleasedIdx + '## [Unreleased]'.length);
+  const nextSection = afterUnreleased.search(/^## \[/m);
+  const unreleasedBlock = nextSection === -1 ? afterUnreleased : afterUnreleased.slice(0, nextSection);
+
+  const entries = [];
+  const entryRegex = /^- (.+)$/gm;
+  let m;
+  while ((m = entryRegex.exec(unreleasedBlock)) !== null) {
+    entries.push(m[1].trim());
+  }
+  return entries;
+}
+
+function getLatestSemverTag(cwd) {
+  try {
+    const tags = execFileSync('git', ['tag', '--sort=-creatordate'], {
+      encoding: 'utf8',
+      cwd: cwd || process.cwd(),
+    }).trim().split('\n').filter(Boolean);
+
+    return tags.find((tag) => SEMVER_TAG_PATTERN.test(tag)) || null;
+  } catch {
+    return null;
+  }
+}
+
+function getFirstCommit(cwd) {
+  try {
+    return execFileSync('git', ['rev-list', '--max-parents=0', 'HEAD'], {
+      encoding: 'utf8',
+      cwd: cwd || process.cwd(),
+    }).trim().split('\n')[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+function getCommitTypesSinceRef(ref, head, cwd) {
+  const range = head ? `${ref}..${head}` : `${ref}..HEAD`;
+  try {
+    const output = execFileSync('git', ['log', range, '--format=%s'], {
+      encoding: 'utf8',
+      cwd: cwd || process.cwd(),
+    });
+    const messages = output.trim().split('\n').filter(Boolean);
+    const types = messages.map((msg) => {
+      const m = msg.match(/^(feat|fix|docs|chore|refactor|test|ci|perf|build)/);
+      return m ? m[1] : null;
+    }).filter(Boolean);
+    return { types, count: messages.length };
+  } catch {
+    return { types: [], count: 0 };
+  }
+}
+
+function getChangelogContentAtRef(ref, cwd) {
+  return execFileSync(
+    'git', ['show', `${ref}:CHANGELOG.md`],
+    { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'] },
+  );
+}
+
+function countNewEntriesSinceBase(projectRoot, base, head) {
+  // Read head changelog: use git show if head is explicit, else read worktree
+  const headContent = head
+    ? execFileSync('git', ['show', `${head}:CHANGELOG.md`], { encoding: 'utf8', cwd: projectRoot, stdio: ['pipe', 'pipe', 'pipe'] })
+    : fs.readFileSync(path.join(projectRoot, 'CHANGELOG.md'), 'utf8');
+  const headEntries = getUnreleasedEntries(headContent);
+
+  // Read base changelog — if base has no CHANGELOG.md, that's a real error
+  // unless this is the initial commit (no parent)
+  let baseEntries;
+  try {
+    const baseContent = getChangelogContentAtRef(base, projectRoot);
+    baseEntries = new Set(getUnreleasedEntries(baseContent));
+  } catch (err) {
+    // Safe cases: base doesn't have CHANGELOG.md at all (first creation)
+    // git show errors: "does not exist" or "exists on disk, but not in '<ref>'"
+    const stderr = err.stderr?.toString() || '';
+    if (err.status && (stderr.includes('does not exist') || stderr.includes('exists on disk, but not in'))) {
+      return headEntries.length; // All entries are new
+    }
+    throw err; // Surface the actual error
+  }
+
+  // Exact-match subtraction (reorder-safe, rename counts as new — documented limitation)
+  return headEntries.filter((e) => !baseEntries.has(e)).length;
+}
+
+function readChangelogContent(projectRoot, head) {
+  if (head) {
+    // When --head is specified, read changelog at that commit (not worktree)
+    return execFileSync(
+      'git', ['show', `${head}:CHANGELOG.md`],
+      { encoding: 'utf8', cwd: projectRoot, stdio: ['pipe', 'pipe', 'pipe'] },
+    );
+  }
+  const changelogPath = path.join(projectRoot, 'CHANGELOG.md');
+  if (!fs.existsSync(changelogPath)) return null;
+  return fs.readFileSync(changelogPath, 'utf8');
+}
+
+export function validateChangelog(projectRoot, options = {}) {
+  let content;
+  try {
+    content = readChangelogContent(projectRoot, options.head);
+  } catch (err) {
+    return {
+      exitCode: 1,
+      stderr: `Changelog validation failed:\n- Could not read CHANGELOG.md at "${options.head}": ${err.message}\n`,
+    };
+  }
+
+  if (content === null) {
+    return {
+      exitCode: 1,
+      stderr: 'Changelog validation failed:\n- CHANGELOG.md not found\n',
+    };
+  }
+
+  const errors = parseChangelog(content);
+
+  if (errors.length > 0) {
+    return {
+      exitCode: 1,
+      stderr: `Changelog validation failed:\n- ${errors.join('\n- ')}\n`,
+    };
+  }
+
+  // --require-entries: diff-aware — compares entries against base branch
+  if (options.requireEntries) {
+    const base = options.base;
+    if (base) {
+      try {
+        const newEntryCount = countNewEntriesSinceBase(projectRoot, base, options.head);
+        if (newEntryCount === 0) {
+          return {
+            exitCode: 1,
+            stderr: 'Changelog validation failed:\n- No entries in [Unreleased] section since base branch (--require-entries was set)\n',
+          };
+        }
+      } catch (err) {
+        return {
+          exitCode: 1,
+          stderr: `Changelog validation failed:\n- Could not diff changelog against base "${base}": ${err.message}\n`,
+        };
+      }
+    } else if (getUnreleasedEntries(content).length === 0) {
+      return {
+        exitCode: 1,
+        stderr: 'Changelog validation failed:\n- No entries in [Unreleased] section (--require-entries was set)\n',
+      };
+    }
+  }
+
+  // Diff-aware gap detection (warning only, does not fail)
+  const warnings = [];
+  const diffRef = options.base || getLatestSemverTag(projectRoot) || getFirstCommit(projectRoot);
+  if (diffRef) {
+    try {
+      const { types } = getCommitTypesSinceRef(diffRef, options.head, projectRoot);
+      const userFacingTypes = types.filter((t) => t === 'feat' || t === 'fix');
+      if (userFacingTypes.length > 0) {
+        // Check for new entries relative to base, not just non-empty
+        let newCount;
+        try {
+          newCount = countNewEntriesSinceBase(projectRoot, diffRef, options.head);
+        } catch {
+          newCount = getUnreleasedEntries(content).length;
+        }
+        if (newCount === 0) {
+          warnings.push(`${userFacingTypes.length} feat/fix commit(s) since "${diffRef}" but no new [Unreleased] entries`);
+        }
+      }
+    } catch (err) {
+      warnings.push(`Could not perform diff-aware check: ${err.message}`);
+    }
+  }
+
+  const warningText = warnings.length > 0 ? `\nWarnings:\n- ${warnings.join('\n- ')}\n` : '';
+
+  return {
+    exitCode: 0,
+    stdout: `Changelog validation passed.${warningText}\n`,
+  };
+}

package/tooling/src/checks/command-registry.js

@@ -0,0 +1,36 @@
+export const SUPPORTED_COMMAND_SUBJECTS = new Set([
+  'wazir validate',
+  'wazir validate manifest',
+  'wazir validate hooks',
+  'wazir validate docs',
+  'wazir validate brand',
+  'wazir validate runtime',
+  'wazir validate artifacts',
+  'wazir validate branches',
+  'wazir validate commits',
+  'wazir validate changelog',
+  'wazir validate docs-drift',
+  'wazir export',
+  'wazir export build',
+  'wazir export --check',
+  'wazir index',
+  'wazir index build',
+  'wazir index refresh',
+  'wazir index stats',
+  'wazir index summarize',
+  'wazir index search-symbols',
+  'wazir index get-symbol',
+  'wazir index get-file-outline',
+  'wazir recall',
+  'wazir recall file',
+  'wazir recall symbol',
+  'wazir doctor',
+  'wazir status',
+  'wazir capture',
+  'wazir capture init',
+  'wazir capture event',
+  'wazir capture route',
+  'wazir capture output',
+  'wazir capture summary',
+  'wazir capture usage',
+]);