@wazir-dev/cli 1.1.0 → 1.2.0

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',
+  };
+}

package/tooling/src/guards/phase-prerequisite-guard.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readYamlFile } from '../loaders.js';
+import { getRunPaths, readPhaseExitEvents } from '../capture/store.js';
+
+export function evaluateScopeCoverageGuard(payload) {
+  const { input_item_count: inputCount, plan_task_count: planCount, user_approved_reduction: userApproved } = payload;
+
+  const safeInputCount = inputCount ?? 0;
+  const safePlanCount = planCount ?? 0;
+
+  if (safeInputCount === 0) {
+    return {
+      allowed: true,
+      reason: 'No input items to check against.',
+      input_count: safeInputCount,
+      plan_count: safePlanCount,
+    };
+  }
+
+  if (safePlanCount >= safeInputCount) {
+    return {
+      allowed: true,
+      reason: `Plan covers all input items (${safePlanCount} tasks >= ${safeInputCount} items).`,
+      input_count: safeInputCount,
+      plan_count: safePlanCount,
+    };
+  }
+
+  if (userApproved === true) {
+    return {
+      allowed: true,
+      reason: `User explicitly approved scope reduction (${safePlanCount} tasks < ${safeInputCount} items).`,
+      input_count: safeInputCount,
+      plan_count: safePlanCount,
+    };
+  }
+
+  return {
+    allowed: false,
+    reason: `Scope reduction detected: plan has ${safePlanCount} tasks but input has ${safeInputCount} items. User approval required.`,
+    input_count: safeInputCount,
+    plan_count: safePlanCount,
+  };
+}
+
+export function evaluatePhasePrerequisiteGuard(payload) {
+  const { run_id: runId, phase, state_root: stateRoot, project_root: projectRoot } = payload;
+
+  if (!runId) {
+    throw new Error('run_id is required');
+  }
+
+  if (!phase) {
+    throw new Error('phase is required');
+  }
+
+  if (!stateRoot) {
+    throw new Error('state_root is required');
+  }
+
+  if (!projectRoot) {
+    throw new Error('project_root is required');
+  }
+
+  const runPaths = getRunPaths(stateRoot, runId);
+
+  if (!fs.existsSync(runPaths.statusPath)) {
+    throw new Error(`status.json not found for run ${runId}`);
+  }
+
+  const manifestPath = path.join(projectRoot, 'wazir.manifest.yaml');
+  const manifest = readYamlFile(manifestPath);
+  const prerequisites = manifest.phase_prerequisites?.[phase];
+
+  if (!prerequisites || (Object.keys(prerequisites).length === 0)) {
+    return {
+      allowed: true,
+      reason: `No prerequisites defined for phase ${phase}.`,
+    };
+  }
+
+  const requiredArtifacts = prerequisites.required_artifacts ?? [];
+  const requiredPhaseExits = prerequisites.required_phase_exits ?? [];
+
+  const missingArtifacts = [];
+  for (const artifact of requiredArtifacts) {
+    const artifactPath = path.join(runPaths.runRoot, artifact);
+    if (!fs.existsSync(artifactPath)) {
+      missingArtifacts.push(artifact);
+    }
+  }
+
+  const completedPhases = readPhaseExitEvents(runPaths);
+  const missingPhaseExits = [];
+  for (const requiredPhase of requiredPhaseExits) {
+    if (!completedPhases.includes(requiredPhase)) {
+      missingPhaseExits.push(requiredPhase);
+    }
+  }
+
+  // OR-logic for resumed runs: if all artifacts exist, pass even without phase_exit events.
+  // Artifacts are the hard evidence; phase_exits are supplementary.
+  // But if artifacts are missing, phase_exits alone are not sufficient.
+  if (missingArtifacts.length === 0) {
+    return {
+      allowed: true,
+      reason: `All prerequisite artifacts present for phase ${phase}.`,
+    };
+  }
+
+  const reasons = [];
+  if (missingArtifacts.length > 0) {
+    reasons.push(`Missing artifacts: ${missingArtifacts.join(', ')}`);
+  }
+  if (missingPhaseExits.length > 0) {
+    reasons.push(`Missing phase exits: ${missingPhaseExits.join(', ')}`);
+  }
+
+  return {
+    allowed: false,
+    reason: reasons.join('. '),
+    missing_artifacts: missingArtifacts.length > 0 ? missingArtifacts : undefined,
+    missing_phase_exits: missingPhaseExits.length > 0 ? missingPhaseExits : undefined,
+  };
+}

package/tooling/src/hooks/routing-logic.js

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function firstToken(cmd) {
+  return cmd.split(/\s+/)[0] || '';
+}
+
+function hasPipe(cmd) {
+  return /(?<![\\])\|/.test(cmd);
+}
+
+function hasRedirect(cmd) {
+  return /(?<![\\])[>]/.test(cmd);
+}
+
+export function loadRoutingMatrix(projectRoot) {
+  const matrixPath = join(projectRoot, 'hooks', 'routing-matrix.json');
+  return JSON.parse(readFileSync(matrixPath, 'utf8'));
+}
+
+export function classifyCommand(cmd, matrix) {
+  const command = (cmd || '').trim();
+
+  if (!matrix) {
+    return { route: 'small', reason: 'matrix missing — safe fallback' };
+  }
+
+  // 1. Explicit context-mode marker always wins
+  if (command.includes('# wazir:context-mode')) {
+    return { route: 'large', reason: 'explicit context-mode marker' };
+  }
+
+  // 2. Check large patterns FIRST — large commands are never downgraded
+  for (const pattern of matrix.large) {
+    if (command === pattern || command.startsWith(pattern + ' ') || command.startsWith(pattern + '\t')) {
+      return { route: 'large', reason: `matched large pattern: ${pattern}` };
+    }
+  }
+
+  // 3. Passthrough marker — only honoured when command is NOT large
+  if (command.includes('# wazir:passthrough')) {
+    return { route: 'small', reason: 'explicit passthrough marker' };
+  }
+
+  // 4. Check small patterns
+  for (const pattern of matrix.small) {
+    if (command === pattern || command.startsWith(pattern + ' ') || command.startsWith(pattern + '\t')) {
+      return { route: 'small', reason: `matched small pattern: ${pattern}` };
+    }
+  }
+
+  // 5. Ambiguous heuristics
+  const heuristic = matrix.ambiguous_heuristic || {};
+
+  if (heuristic.pipe_detected && hasPipe(command)) {
+    return { route: 'ambiguous', reason: 'pipe detected' };
+  }
+  if (heuristic.redirect_detected && hasRedirect(command)) {
+    return { route: 'ambiguous', reason: 'redirect detected' };
+  }
+
+  const bin = firstToken(command);
+  if (Array.isArray(heuristic.verbose_binaries) && heuristic.verbose_binaries.includes(bin)) {
+    return { route: 'ambiguous', reason: `verbose binary: ${bin}` };
+  }
+
+  // Default: unknown commands pass through
+  return { route: 'small', reason: 'no pattern matched — default passthrough' };
+}