@wazir-dev/cli 1.1.0 → 1.3.0

package/tooling/src/checks/skills.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Known superpowers skill names that conflict with Wazir skill names.
+ * A Wazir skill may share a name with a superpowers skill ONLY if it uses
+ * the wz: prefix — the Augment tier (CONTEXT.md companion) is not
+ * implementable (concluded in Task 18 R2) and is no longer supported.
+ */
+const SUPERPOWERS_SKILL_NAMES = new Set([
+  'brainstorming',
+  'dispatching-parallel-agents',
+  'executing-plans',
+  'finishing-a-development-branch',
+  'receiving-code-review',
+  'requesting-code-review',
+  'subagent-driven-development',
+  'using-git-worktrees',
+  'verification',
+  'writing-plans',
+  'writing-skills',
+]);
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const fields = {};
+  for (const line of match[1].split('\n')) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+    fields[key] = value;
+  }
+
+  return fields;
+}
+
+function listSkillDirs(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export function validateSkillsAtProjectRoot(projectRoot) {
+  const skillsDir = path.join(projectRoot, 'skills');
+  const errors = [];
+  const skillDirs = listSkillDirs(skillsDir);
+  let checkedCount = 0;
+
+  for (const dirName of skillDirs) {
+    const skillMdPath = path.join(skillsDir, dirName, 'SKILL.md');
+
+    if (!fs.existsSync(skillMdPath)) continue;
+
+    checkedCount++;
+    const content = fs.readFileSync(skillMdPath, 'utf8');
+    const frontmatter = parseFrontmatter(content);
+
+    if (!frontmatter) {
+      errors.push(`${dirName}: SKILL.md missing YAML frontmatter`);
+      continue;
+    }
+
+    if (!frontmatter.name) {
+      errors.push(`${dirName}: SKILL.md missing name field in frontmatter`);
+      continue;
+    }
+
+    const skillName = frontmatter.name;
+    const baseName = skillName.startsWith('wz:') ? skillName.slice(3) : skillName;
+    const hasWzPrefix = skillName.startsWith('wz:');
+    const conflictsWithSuperpowers = SUPERPOWERS_SKILL_NAMES.has(baseName);
+    const contextMdPath = path.join(skillsDir, dirName, 'CONTEXT.md');
+    const hasContextMd = fs.existsSync(contextMdPath);
+
+    // Check: conflicting name without wz: prefix must be flagged.
+    // Augment tier is not supported — the only resolution is the wz: prefix.
+    if (conflictsWithSuperpowers && !hasWzPrefix) {
+      errors.push(
+        `${dirName}: skill name "${skillName}" conflicts with superpowers:${baseName} — ` +
+        'add wz: prefix to resolve the conflict',
+      );
+    }
+
+    // Check: CONTEXT.md files are stale — augment tier is not implementable
+    // (concluded in Task 18 R2). Flag any remaining CONTEXT.md as an error.
+    if (hasContextMd) {
+      errors.push(
+        `${dirName}: CONTEXT.md is not supported — augment tier was removed. ` +
+        'Delete CONTEXT.md; all Wazir skills use the Own tier with wz: prefix.',
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      exitCode: 1,
+      stderr: `Skill validation failed:\n- ${errors.join('\n- ')}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: `Skill validation passed. Checked ${checkedCount} skills.\n`,
+  };
+}

package/tooling/src/cli.js

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
 
+// Suppress Node.js ExperimentalWarning for built-in SQLite (node:sqlite).
+// Must run before any module that transitively imports node:sqlite loads,
+// so command handlers are lazy-imported below instead of using static imports.
+const _originalEmit = process.emit;
+process.emit = function (event, ...args) {
+  if (event === 'warning' && args[0]?.name === 'ExperimentalWarning' &&
+      args[0]?.message?.includes('SQLite')) {
+    return false;
+  }
+  return _originalEmit.apply(this, [event, ...args]);
+};
+
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-import { runCaptureCommand } from './capture/command.js';
-import { runValidateCommand } from './commands/validate.js';
-import { runDoctorCommand } from './doctor/command.js';
-import { runExportCommand as runGeneratedExportCommand } from './export/command.js';
-import { runIndexCommand } from './index/command.js';
-import { runInitCommand } from './init/command.js';
-import { runRecallCommand } from './recall/command.js';
-import { runStatusCommand } from './status/command.js';
-
 const COMMAND_FAMILIES = [
   'export',
   'validate',
@@ -19,19 +22,26 @@ const COMMAND_FAMILIES = [
   'index',
   'init',
   'recall',
+  'report',
+  'state',
   'status',
+  'stats',
   'capture'
 ];
 
-const COMMAND_HANDLERS = {
-  export: runGeneratedExportCommand,
-  validate: runValidateCommand,
-  doctor: runDoctorCommand,
-  index: runIndexCommand,
-  init: runInitCommand,
-  recall: runRecallCommand,
-  status: runStatusCommand,
-  capture: runCaptureCommand,
+// Lazy-load command handlers so the warning filter is active before node:sqlite loads
+const COMMAND_LOADERS = {
+  export:   () => import('./export/command.js').then(m => m.runExportCommand),
+  validate: () => import('./commands/validate.js').then(m => m.runValidateCommand),
+  doctor:   () => import('./doctor/command.js').then(m => m.runDoctorCommand),
+  index:    () => import('./index/command.js').then(m => m.runIndexCommand),
+  init:     () => import('./init/command.js').then(m => m.runInitCommand),
+  recall:   () => import('./recall/command.js').then(m => m.runRecallCommand),
+  report:   () => import('./reports/command.js').then(m => m.runReportCommand),
+  state:    () => import('./state/command.js').then(m => m.runStateCommand),
+  status:   () => import('./status/command.js').then(m => m.runStatusCommand),
+  stats:    () => import('./commands/stats.js').then(m => m.runStatsCommand),
+  capture:  () => import('./capture/command.js').then(m => m.runCaptureCommand),
 };
 
 export function parseArgs(argv) {
@@ -79,9 +89,9 @@ export async function main(argv = process.argv.slice(2)) {
     return 1;
   }
 
-  const handler = COMMAND_HANDLERS[parsed.command];
+  const loader = COMMAND_LOADERS[parsed.command];
 
-  if (!handler) {
+  if (!loader) {
     console.error(`wazir ${parsed.command} is not implemented yet`);
     return 2;
   }
@@ -89,6 +99,7 @@ export async function main(argv = process.argv.slice(2)) {
   let result;
 
   try {
+    const handler = await loader();
     result = await handler(parsed);
   } catch (error) {
     console.error(error.message);

package/tooling/src/commands/stats.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseCommandOptions } from '../command-options.js';
+import { readYamlFile } from '../loaders.js';
+import { findProjectRoot } from '../project-root.js';
+import { resolveStateRoot } from '../state-root.js';
+import { getRunPaths } from '../capture/store.js';
+import { readUsage, estimateTokens, consumeRoutingLog } from '../capture/usage.js';
+
+function formatNumber(n) {
+  return n.toLocaleString('en-US');
+}
+
+function buildStatsPayload(usage) {
+  const savings = usage.savings ?? {};
+  const cr = savings.capture_routing ?? {};
+  const cm = savings.context_mode ?? {};
+  const co = savings.compaction ?? {};
+  const iq = savings.index_queries ?? {};
+
+  const totalQueriesFromPhases = Object.values(usage.phases)
+    .reduce((sum, p) => sum + (p.events_count ?? 0), 0);
+  const totalQueries = totalQueriesFromPhases + (iq.count ?? 0);
+
+  const crTokensSaved = cr.estimated_tokens_avoided ?? 0;
+  const cmRawTokens = estimateTokens(Math.round((cm.raw_kb ?? 0) * 1024));
+  const cmAfterTokens = estimateTokens(Math.round((cm.context_kb ?? 0) * 1024));
+  const cmTokensSaved = cmRawTokens - cmAfterTokens;
+  const coTokensSaved = (co.pre_compaction_tokens_est ?? 0) - (co.post_compaction_tokens_est ?? 0);
+  const iqTokensSaved = iq.estimated_tokens_saved ?? 0;
+
+  const totalEstimatedTokensSaved = crTokensSaved + cmTokensSaved + coTokensSaved + iqTokensSaved;
+  const totalBytesAvoided = (cr.raw_bytes ?? 0) - (cr.summary_bytes ?? 0) + (iq.bytes_avoided ?? 0);
+
+  const crRawTokens = crTokensSaved + estimateTokens(cr.summary_bytes ?? 0);
+  const iqRawTokens = estimateTokens(iq.total_raw_bytes ?? 0);
+  const iqAfterTokens = estimateTokens(iq.total_summary_bytes ?? 0);
+  const withoutSavings = crRawTokens + cmRawTokens + (co.pre_compaction_tokens_est ?? 0) + iqRawTokens;
+  const withAll = estimateTokens(cr.summary_bytes ?? 0) + cmAfterTokens + (co.post_compaction_tokens_est ?? 0) + iqAfterTokens;
+  const savingsRatio = withoutSavings > 0
+    ? `${((1 - withAll / withoutSavings) * 100).toFixed(1)}%`
+    : '0.0%';
+
+  return {
+    run_id: usage.run_id,
+    total_queries: totalQueries,
+    total_estimated_tokens_saved: totalEstimatedTokensSaved,
+    total_bytes_avoided: totalBytesAvoided,
+    savings_ratio: savingsRatio,
+    per_tool: {
+      capture_routing: {
+        tokens_saved: crTokensSaved,
+        raw_bytes: cr.raw_bytes ?? 0,
+        summary_bytes: cr.summary_bytes ?? 0,
+      },
+      context_mode: {
+        tokens_saved: cmTokensSaved,
+        raw_kb: cm.raw_kb ?? 0,
+        context_kb: cm.context_kb ?? 0,
+      },
+      compaction: {
+        tokens_saved: coTokensSaved,
+        compaction_count: co.compaction_count ?? 0,
+      },
+      index_queries: {
+        tokens_saved: iqTokensSaved,
+        query_count: iq.count ?? 0,
+        bytes_avoided: iq.bytes_avoided ?? 0,
+      },
+    },
+  };
+}
+
+function formatTextOutput(payload) {
+  const lines = [
+    `Stats: ${payload.run_id}`,
+    '',
+    `Total queries:              ${formatNumber(payload.total_queries)}`,
+    `Total estimated tokens saved: ${formatNumber(payload.total_estimated_tokens_saved)}`,
+    `Total bytes avoided:        ${formatNumber(payload.total_bytes_avoided)}`,
+    `Overall savings ratio:      ${payload.savings_ratio}`,
+    '',
+    'Per-tool breakdown:',
+    `  Capture routing:  ${formatNumber(payload.per_tool.capture_routing.tokens_saved)} tokens saved`,
+    `  Context-mode:     ${formatNumber(payload.per_tool.context_mode.tokens_saved)} tokens saved`,
+    `  Compaction:       ${formatNumber(payload.per_tool.compaction.tokens_saved)} tokens saved (${payload.per_tool.compaction.compaction_count} compactions)`,
+    `  Index queries:    ${formatNumber(payload.per_tool.index_queries.tokens_saved)} tokens saved (${payload.per_tool.index_queries.query_count} queries)`,
+  ];
+
+  return lines.join('\n');
+}
+
+export function runStatsCommand(parsed, context = {}) {
+  try {
+    if (parsed.subcommand) {
+      return {
+        exitCode: 1,
+        stderr: 'Usage: wazir stats --run <id> [--state-root <path>] [--json]\n',
+      };
+    }
+
+    const { options } = parseCommandOptions(parsed.args, {
+      boolean: ['json', 'help'],
+      string: ['run', 'state-root'],
+    });
+
+    if (options.help) {
+      return {
+        exitCode: 0,
+        stdout: 'Usage: wazir stats --run <id> [--state-root <path>] [--json]\n\nShow token savings statistics for a run.\n',
+      };
+    }
+
+    if (!options.run) {
+      return {
+        exitCode: 1,
+        stderr: 'wazir stats requires --run <id>\n',
+      };
+    }
+
+    const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+    const manifest = readYamlFile(path.join(projectRoot, 'wazir.manifest.yaml'));
+    const stateRoot = resolveStateRoot(projectRoot, manifest, {
+      cwd: context.cwd ?? process.cwd(),
+      override: options.stateRoot,
+    });
+    const runPaths = getRunPaths(stateRoot, options.run);
+
+    if (!fs.existsSync(runPaths.usagePath)) {
+      return {
+        exitCode: 1,
+        stderr: `Run usage data not found: ${runPaths.usagePath}\n`,
+      };
+    }
+
+    // Lazy aggregation: consume the routing log before computing stats
+    // so that routing decisions are reflected in the usage data.
+    consumeRoutingLog(runPaths);
+
+    const usage = readUsage(runPaths);
+    const payload = buildStatsPayload(usage);
+
+    if (options.json) {
+      return {
+        exitCode: 0,
+        stdout: `${JSON.stringify(payload, null, 2)}\n`,
+      };
+    }
+
+    return {
+      exitCode: 0,
+      stdout: `${formatTextOutput(payload)}\n`,
+    };
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stderr: `${error.message}\n`,
+    };
+  }
+}

package/tooling/src/commands/validate.js

@@ -12,6 +12,7 @@ import { validateBranchName } from '../checks/branches.js';
 import { validateCommits } from '../checks/commits.js';
 import { validateChangelog } from '../checks/changelog.js';
 import { runDocsDriftCheck } from '../checks/docs-drift.js';
+import { validateSkillsAtProjectRoot } from '../checks/skills.js';
 
 function success(stdout) {
   return { exitCode: 0, stdout: `${stdout}\n` };
@@ -254,9 +255,11 @@ export function runValidateCommand(parsed, context = {}) {
         strict: hasFlag(parsed.args, '--strict'),
         cwd: projectRoot,
       });
+    case 'skills':
+      return validateSkillsAtProjectRoot(projectRoot);
     default: {
       if (parsed.subcommand != null) {
-        return failure(`Unknown validator: ${parsed.subcommand}\nUsage: wazir validate <manifest|hooks|docs|brand|runtime|branches|commits|changelog|docs-drift>`);
+        return failure(`Unknown validator: ${parsed.subcommand}\nUsage: wazir validate <manifest|hooks|docs|brand|runtime|branches|commits|changelog|docs-drift|skills>`);
       }
 
       if (parsed.args.length > 0) {
@@ -290,6 +293,7 @@ export function runValidateCommand(parsed, context = {}) {
         { name: 'branches', fn: () => validateBranchName(undefined, { cwd: projectRoot }), available: hasBranch },
         { name: 'commits', fn: () => validateCommits({ cwd: projectRoot }), available: hasGit },
         { name: 'changelog', fn: () => validateChangelog(projectRoot, {}), available: hasChangelog },
+        { name: 'skills', fn: () => validateSkillsAtProjectRoot(projectRoot) },
       ];
 
       const lines = [];

package/tooling/src/export/compiler.js

@@ -40,12 +40,18 @@ function listDeclaredWorkflowFiles(projectRoot, manifest) {
 }
 
 function collectCanonicalSources(projectRoot, manifest) {
-  return [
+  const sources = [
     path.join(projectRoot, 'wazir.manifest.yaml'),
     ...listDeclaredRoleFiles(projectRoot, manifest),
     ...listDeclaredWorkflowFiles(projectRoot, manifest),
     ...listHookDefinitions(path.join(projectRoot, 'hooks', 'definitions')),
   ];
+  // hooks.json is a canonical source for Claude settings generation
+  const hooksJson = path.join(projectRoot, 'hooks', 'hooks.json');
+  if (fs.existsSync(hooksJson)) {
+    sources.push(hooksJson);
+  }
+  return sources;
 }
 
 function toRelativeMap(projectRoot, filePaths) {
@@ -82,41 +88,27 @@ function renderCommonInstructions(host, manifest) {
   ].join('\n');
 }
 
-function renderClaudeSettings() {
-  return JSON.stringify({
-    hooks: {
-      PreToolUse: [
-        {
-          matcher: 'Write|Edit',
-          hooks: [
-            {
-              type: 'command',
-              command: './hooks/protected-path-write-guard',
-            },
-          ],
-        },
-      ],
-      SessionStart: [
-        {
-          hooks: [
-            {
-              type: 'command',
-              command: './hooks/loop-cap-guard',
-            },
-          ],
-        },
-        {
-          matcher: 'startup|resume|clear|compact',
-          hooks: [
-            {
-              type: 'command',
-              command: './hooks/session-start',
-            },
-          ],
-        },
-      ],
-    },
-  }, null, 2);
+const DEFAULT_CLAUDE_HOOKS = {
+  hooks: {
+    PreToolUse: [
+      { matcher: 'Write|Edit', hooks: [{ type: 'command', command: './hooks/protected-path-write-guard' }] },
+      { matcher: 'Bash', hooks: [{ type: 'command', command: './hooks/context-mode-router' }] },
+    ],
+    SessionStart: [
+      { hooks: [{ type: 'command', command: './hooks/loop-cap-guard' }] },
+      { matcher: 'startup|resume|clear|compact', hooks: [{ type: 'command', command: './hooks/session-start' }] },
+    ],
+  },
+};
+
+function renderClaudeSettings(projectRoot) {
+  const hooksPath = path.join(projectRoot, 'hooks', 'hooks.json');
+  if (fs.existsSync(hooksPath)) {
+    const hooksContent = JSON.parse(fs.readFileSync(hooksPath, 'utf8'));
+    return JSON.stringify(hooksContent, null, 2);
+  }
+  // Fallback: default hooks when hooks.json doesn't exist (e.g., new projects)
+  return JSON.stringify(DEFAULT_CLAUDE_HOOKS, null, 2);
 }
 
 function renderCursorHooks() {
@@ -130,6 +122,10 @@ function renderCursorHooks() {
         name: 'loop-cap-guard',
         command: './hooks/loop-cap-guard',
       },
+      {
+        name: 'context-mode-router',
+        command: './hooks/context-mode-router',
+      },
       {
         name: 'session-start',
         command: './hooks/session-start',
@@ -146,7 +142,7 @@ function generateHostFiles(projectRoot, manifest, host) {
 
   if (host === 'claude') {
     files['CLAUDE.md'] = common;
-    files['.claude/settings.json'] = renderClaudeSettings();
+    files['.claude/settings.json'] = renderClaudeSettings(projectRoot);
 
     for (const roleFile of roleFiles) {
       files[path.join('.claude', 'agents', path.basename(roleFile))] = fs.readFileSync(roleFile, 'utf8');

package/tooling/src/gating/agent.js

@@ -0,0 +1,145 @@
+import { readYamlFile } from '../loaders.js';
+
+/**
+ * Resolve a dotted field path (e.g. "quality_metrics.test_fail_count") on an object.
+ * Returns undefined when any segment is missing.
+ */
+function resolvePath(obj, fieldPath) {
+  const segments = fieldPath.split('.');
+  let current = obj;
+  for (const seg of segments) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[seg];
+  }
+  return current;
+}
+
+/**
+ * Check whether a single condition holds against a report.
+ */
+function evaluateCondition(report, condition) {
+  const value = resolvePath(report, condition.field);
+
+  switch (condition.operator) {
+    case 'eq':
+      return value === condition.value;
+
+    case 'gt':
+      return typeof value === 'number' && value > condition.value;
+
+    case 'lt':
+      return typeof value === 'number' && value < condition.value;
+
+    case 'none_match': {
+      // field must be an array; none of its items may match all key/value
+      // pairs in condition.match
+      if (!Array.isArray(value)) return value === undefined || value === null;
+      const matchEntries = Object.entries(condition.match);
+      return value.every(
+        (item) => !matchEntries.every(([k, v]) => item[k] === v),
+      );
+    }
+
+    default:
+      // Unknown operator — treat as ambiguous → condition fails
+      return false;
+  }
+}
+
+/**
+ * Extract human-readable failure descriptions from the report for loop_back fixes.
+ */
+function extractFixes(report) {
+  const fixes = [];
+
+  const testFails = resolvePath(report, 'quality_metrics.test_fail_count');
+  if (typeof testFails === 'number' && testFails > 0) {
+    fixes.push(`fix ${testFails} failing test(s)`);
+  }
+
+  const lintErrors = resolvePath(report, 'quality_metrics.lint_errors');
+  if (typeof lintErrors === 'number' && lintErrors > 0) {
+    fixes.push(`fix ${lintErrors} lint error(s)`);
+  }
+
+  const typeErrors = resolvePath(report, 'quality_metrics.type_errors');
+  if (typeof typeErrors === 'number' && typeErrors > 0) {
+    fixes.push(`fix ${typeErrors} type error(s)`);
+  }
+
+  return fixes;
+}
+
+/**
+ * Evaluate a phase report against gating rules and return a verdict.
+ *
+ * @param {object|null|undefined} report  — parsed phase report JSON
+ * @param {string} rulesPath              — path to gating-rules.yaml
+ * @param {object} [context={}]           — additional context for the evaluation
+ * @param {string} [context.userInput]    — optional user input that triggered the evaluation
+ * @param {object} [context.decisions]    — optional prior decisions for multi-phase flows
+ * @returns {{ verdict: string, reason: string, fixes?: string[] }}
+ */
+export function evaluatePhaseReport(report, rulesPath, context = {}) {
+  // --- Load rules --------------------------------------------------------
+  let rules;
+  try {
+    rules = readYamlFile(rulesPath);
+  } catch (err) {
+    return {
+      verdict: 'escalate',
+      reason: `Failed to load gating rules: ${err.message}`,
+    };
+  }
+
+  // --- Guard: missing / empty report -------------------------------------
+  if (report == null || typeof report !== 'object' || Object.keys(report).length === 0) {
+    return {
+      verdict: rules.default_verdict ?? 'escalate',
+      reason: 'Report is empty or missing',
+    };
+  }
+
+  // --- Try "continue" rule -----------------------------------------------
+  const continueRule = rules.rules?.continue;
+  if (continueRule && Array.isArray(continueRule.conditions) && continueRule.conditions.length > 0) {
+    const allPass = continueRule.conditions.every((c) => evaluateCondition(report, c));
+    if (allPass) {
+      return { verdict: 'continue', reason: continueRule.description };
+    }
+  }
+
+  // --- Try "loop_back" rule ----------------------------------------------
+  // The loop_back rule fires when ANY deterministic failure exists.
+  // The YAML conditions encode test_fail_count > 0 explicitly; the agent
+  // also checks lint_errors > 0 and type_errors > 0 per the rule comments
+  // ("# OR lint_errors > 0 OR type_errors > 0").
+  const loopBackRule = rules.rules?.loop_back;
+  if (loopBackRule) {
+    const explicitMatch = Array.isArray(loopBackRule.conditions)
+      && loopBackRule.conditions.length > 0
+      && loopBackRule.conditions.some((c) => evaluateCondition(report, c));
+
+    const lintErrors = resolvePath(report, 'quality_metrics.lint_errors');
+    const typeErrors = resolvePath(report, 'quality_metrics.type_errors');
+    const implicitMatch =
+      (typeof lintErrors === 'number' && lintErrors > 0)
+      || (typeof typeErrors === 'number' && typeErrors > 0);
+
+    if (explicitMatch || implicitMatch) {
+      const fixes = extractFixes(report);
+      return {
+        verdict: 'loop_back',
+        reason: loopBackRule.description,
+        fixes,
+      };
+    }
+  }
+
+  // --- Fallback to "escalate" --------------------------------------------
+  const escalateRule = rules.rules?.escalate;
+  return {
+    verdict: 'escalate',
+    reason: escalateRule?.description ?? 'Default escalation — no rule matched',
+  };
+}