@ryuenn3123/agentic-senior-core 2.0.2 → 2.0.4

package/.agent-context/state/token-optimization-benchmark.json

@@ -0,0 +1,130 @@
+{
+  "generatedAt": "2026-04-11T06:14:10.052Z",
+  "reportName": "token-optimization-benchmark",
+  "methodology": {
+    "tokenEstimate": "estimated_tokens = ceil(output_chars / 4)",
+    "scope": "command-output estimate only; model-specific tokenization differs by provider",
+    "repositoryRoot": "E:\\Project\\Agentic-Senior-Core"
+  },
+  "environment": {
+    "nodeVersion": "v22.22.0",
+    "platform": "win32",
+    "rtk": {
+      "isAvailable": true,
+      "version": "0.35.0",
+      "source": "local-tools",
+      "executablePath": "E:\\Project\\Agentic-Senior-Core\\.benchmarks\\tools\\rtk\\rtk.exe",
+      "reason": null
+    }
+  },
+  "scenarios": [
+    {
+      "scenarioId": "git-show",
+      "scenarioName": "Latest commit detail review",
+      "baseline": {
+        "command": "git show HEAD --stat --patch --no-color",
+        "exitCode": 0,
+        "outputChars": 15191,
+        "outputLines": 368,
+        "estimatedTokens": 3798
+      },
+      "nativeOptimized": {
+        "command": "git show HEAD --stat --no-color",
+        "exitCode": 0,
+        "outputChars": 706,
+        "outputLines": 14,
+        "estimatedTokens": 177
+      },
+      "nativeSavings": {
+        "tokenDelta": 3621,
+        "savingsPercent": 95.34
+      },
+      "rtk": {
+        "command": "E:\\Project\\Agentic-Senior-Core\\.benchmarks\\tools\\rtk\\rtk.exe git show HEAD --stat --patch --no-color",
+        "exitCode": 0,
+        "outputChars": 15191,
+        "outputLines": 368,
+        "estimatedTokens": 3798
+      },
+      "rtkSavings": {
+        "tokenDelta": 0,
+        "savingsPercent": 0
+      }
+    },
+    {
+      "scenarioId": "git-log",
+      "scenarioName": "Commit history review",
+      "baseline": {
+        "command": "git log -n 50",
+        "exitCode": 0,
+        "outputChars": 14918,
+        "outputLines": 385,
+        "estimatedTokens": 3730
+      },
+      "nativeOptimized": {
+        "command": "git log --oneline -n 50",
+        "exitCode": 0,
+        "outputChars": 3555,
+        "outputLines": 50,
+        "estimatedTokens": 889
+      },
+      "nativeSavings": {
+        "tokenDelta": 2841,
+        "savingsPercent": 76.17
+      },
+      "rtk": {
+        "command": "E:\\Project\\Agentic-Senior-Core\\.benchmarks\\tools\\rtk\\rtk.exe git log -n 50",
+        "exitCode": 0,
+        "outputChars": 6437,
+        "outputLines": 74,
+        "estimatedTokens": 1610
+      },
+      "rtkSavings": {
+        "tokenDelta": 2120,
+        "savingsPercent": 56.84
+      }
+    },
+    {
+      "scenarioId": "search-token",
+      "scenarioName": "Search result scan",
+      "baseline": {
+        "command": "git grep -n token",
+        "exitCode": 0,
+        "outputChars": 21353,
+        "outputLines": 190,
+        "estimatedTokens": 5339
+      },
+      "nativeOptimized": {
+        "command": "git grep -n token README.md docs",
+        "exitCode": 0,
+        "outputChars": 4395,
+        "outputLines": 38,
+        "estimatedTokens": 1099
+      },
+      "nativeSavings": {
+        "tokenDelta": 4240,
+        "savingsPercent": 79.42
+      },
+      "rtk": {
+        "command": "E:\\Project\\Agentic-Senior-Core\\.benchmarks\\tools\\rtk\\rtk.exe git grep -n token",
+        "exitCode": 0,
+        "outputChars": 21353,
+        "outputLines": 190,
+        "estimatedTokens": 5339
+      },
+      "rtkSavings": {
+        "tokenDelta": 0,
+        "savingsPercent": 0
+      }
+    }
+  ],
+  "summary": {
+    "scenarioCount": 3,
+    "averageNativeSavingsPercent": 83.64,
+    "averageRtkSavingsPercent": 18.95
+  },
+  "artifact": {
+    "path": "E:\\Project\\Agentic-Senior-Core\\.agent-context\\state\\token-optimization-benchmark.json",
+    "writeMode": "stdout-and-file"
+  }
+}

package/.cursorrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.2
+Generated by Agentic-Senior-Core CLI v2.0.4
 Timestamp: 2026-04-08T14:58:53.570Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/.windsurfrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.2
+Generated by Agentic-Senior-Core CLI v2.0.4
 Timestamp: 2026-04-08T14:58:53.570Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/README.md

@@ -128,10 +128,11 @@ agentic-senior-core skill fullstack --json
 
 When you run `init`, the CLI now auto-activates the matching skill packs for the chosen stack and blueprint, so the compiled governance context includes the relevant frontend, backend, fullstack, and CLI guidance by default.
 
-### Token Optimization Mode (Optional and User-Friendly)
+### Token Optimization Mode (Enabled by Default on Init)
 
 Use this mode when your AI session is shell-heavy and context usage is high.
-It is optional by design and works in two modes:
+By default, every `init` flow enables token optimization automatically (npx, npm exec, global CLI, preset, and interactive wizard).
+The optimization engine works in two modes:
 - Native fallback mode (no external dependency required)
 - External proxy mode (auto-detected when available)
 
@@ -144,11 +145,36 @@ agentic-senior-core optimize . --disable
 
 # Auto-enable during project initialization
 npx @ryuenn3123/agentic-senior-core init --token-optimize --token-agent copilot
+
+# Opt out when needed
+npx @ryuenn3123/agentic-senior-core init --no-token-optimize
 ```
 
 When enabled, the CLI writes `.agent-context/state/token-optimization.json`, regenerates compiled rules, and adds compact command guidance to `.cursorrules` and `.windsurfrules`.
 If an external token proxy is available, the CLI prints setup hints. If not, native fallback guidance stays active, so outside users are not forced to install extra tooling.
 
+### Token Efficiency Benchmark Snapshot
+
+Latest local benchmark (2026-04-11) from `.agent-context/state/token-optimization-benchmark.json`:
+
+| Scenario | Baseline Token Estimate | Agentic Native Token Estimate | Native Savings | RTK Token Estimate | RTK Status |
+|----------|-------------------------|-------------------------------|----------------|--------------------|------------|
+| Latest commit detail review | 3798 | 177 | 95.34% | 3798 | Detected (`rtk` v0.35.0) |
+| Commit history review | 3730 | 889 | 76.17% | 1610 | Detected (`rtk` v0.35.0) |
+| Search result scan | 5339 | 1099 | 79.42% | 5339 | Detected (`rtk` v0.35.0) |
+| Average | - | - | 83.64% | 18.95% savings | Detected (`rtk` v0.35.0) |
+
+Method note:
+- Estimate formula is `ceil(output_chars / 4)`.
+- This is a command-output estimate, not provider-specific tokenizer output.
+- RTK results depend on host utilities. On Windows hosts without GNU `grep` or `ls`, RTK may fall back to `rtk git ...` paths for some scenarios.
+
+Reproduce and refresh this table:
+
+```bash
+npm run benchmark:token
+```
+
 ### Install and Setup Choices
 
 The CLI now supports a smaller decision surface for first-time setup:

package/lib/cli/commands/init.mjs

@@ -55,7 +55,7 @@ export function parseInitArguments(commandArguments) {
     blueprint: undefined,
     ci: undefined,
     newbie: false,
-    tokenOptimize: false,
+    tokenOptimize: true,
     tokenAgent: 'copilot',
   };
 
@@ -146,14 +146,12 @@ export function parseInitArguments(commandArguments) {
 
     if (currentArgument === '--token-agent') {
       parsedInitOptions.tokenAgent = commandArguments[argumentIndex + 1] || 'copilot';
-      parsedInitOptions.tokenOptimize = true;
       argumentIndex += 1;
       continue;
     }
 
     if (currentArgument.startsWith('--token-agent=')) {
       parsedInitOptions.tokenAgent = currentArgument.split('=')[1] || 'copilot';
-      parsedInitOptions.tokenOptimize = true;
       continue;
     }
 
@@ -176,6 +174,10 @@ export function parseInitArguments(commandArguments) {
 
 export async function runInitCommand(targetDirectoryArgument, initOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
+  const isTokenOptimizationEnabled = typeof initOptions.tokenOptimize === 'boolean'
+    ? initOptions.tokenOptimize
+    : true;
+  const selectedTokenAgentName = normalizeAgentName(initOptions.tokenAgent || 'copilot');
 
   if (resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows' || resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows\\system32') {
     console.error('\n[FATAL] Target directory resolved to a Windows system folder (C:\\Windows).');
@@ -348,11 +350,11 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
 
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath);
 
-    if (initOptions.tokenOptimize) {
+    if (isTokenOptimizationEnabled) {
       const detectedExternalProxy = detectRtkBinary();
       const tokenOptimizationState = createTokenOptimizationState({
         isEnabled: true,
-        selectedAgentName: initOptions.tokenAgent,
+        selectedAgentName: selectedTokenAgentName,
         rtkDetection: detectedExternalProxy,
       });
 
@@ -417,8 +419,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`- Blocking severities: ${formatBlockingSeverities(selectedProfile.blockingSeverities)}`);
     console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
     console.log('- Generated files: .cursorrules, .windsurfrules, and .agent-context/state/onboarding-report.json');
-    if (initOptions.tokenOptimize) {
-      console.log(`- Token optimization policy: enabled for ${initOptions.tokenAgent}`);
+    if (isTokenOptimizationEnabled) {
+      console.log(`- Token optimization policy: enabled for ${selectedTokenAgentName}`);
+    } else {
+      console.log('- Token optimization policy: disabled (--no-token-optimize)');
     }
     console.log('\nPlain-language summary:');
     console.log(`I prepared a ${selectedProfile.displayName.toLowerCase()} governance pack for a ${toTitleCase(selectedResolvedStackFileName)} project using the ${toTitleCase(selectedResolvedBlueprintFileName)} blueprint.`);

package/lib/cli/utils.mjs

@@ -25,7 +25,7 @@ export function printUsage() {
   console.log('');
   console.log('Usage:');
   console.log('  agentic-senior-core launch');
-  console.log('  agentic-senior-core init [target-directory] [--preset <name>] [--profile <beginner|balanced|strict>] [--profile-pack <name>] [--stack <name>] [--blueprint <name>] [--ci <true|false>] [--newbie] [--token-optimize] [--token-agent <name>]');
+  console.log('  agentic-senior-core init [target-directory] [--preset <name>] [--profile <beginner|balanced|strict>] [--profile-pack <name>] [--stack <name>] [--blueprint <name>] [--ci <true|false>] [--newbie] [--token-optimize] [--no-token-optimize] [--token-agent <name>]');
   console.log('  agentic-senior-core upgrade [target-directory] [--dry-run] [--yes]');
   console.log('  agentic-senior-core optimize [target-directory] [--agent <copilot|claude|cursor|windsurf|gemini|codex|cline>] [--enable|--disable] [--show]');
   console.log('  agentic-senior-core rollback [target-directory]');
@@ -42,9 +42,9 @@ export function printUsage() {
   console.log('  --stack      Override stack selection');
   console.log('  --blueprint  Override blueprint selection');
   console.log('  --ci         Override CI/CD guardrails (true|false)');
-  console.log('  --token-optimize  Enable token optimization policy during init');
+  console.log('  --token-optimize  Explicitly enable token optimization policy during init (default behavior)');
   console.log('  --token-agent     Set token optimization agent target (copilot, claude, cursor, windsurf, gemini, codex, cline)');
-  console.log('  --no-token-optimize  Disable token optimization even if token-agent is provided');
+  console.log('  --no-token-optimize  Disable token optimization policy during init');
   console.log('  --dry-run    Preview upgrade without writing files');
   console.log('  --yes        Skip confirmation prompts for upgrade');
   console.log('  --agent      Target agent integration for token optimization mode');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -47,6 +47,7 @@
     "prepublishOnly": "npm run gate:release",
     "sbom:generate": "node ./scripts/generate-sbom.mjs",
     "benchmark:detection": "node ./scripts/detection-benchmark.mjs",
+    "benchmark:token": "node ./scripts/token-optimization-benchmark.mjs",
     "benchmark:gate": "node ./scripts/benchmark-gate.mjs",
     "benchmark:intelligence": "node ./scripts/benchmark-intelligence.mjs",
     "validate": "node ./scripts/validate.mjs",

package/scripts/token-optimization-benchmark.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+/**
+ * token-optimization-benchmark.mjs
+ *
+ * Measures token-estimate reduction between baseline commands and
+ * native optimized command variants. If RTK is installed, it also
+ * compares RTK command output in the same scenarios.
+ */
+
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = dirname(SCRIPT_FILE_PATH);
+const REPOSITORY_ROOT = resolve(SCRIPT_DIR, '..');
+const REPORT_PATH = join(REPOSITORY_ROOT, '.agent-context', 'state', 'token-optimization-benchmark.json');
+const LOCAL_RTK_BINARY_PATH = join(REPOSITORY_ROOT, '.benchmarks', 'tools', 'rtk', 'rtk.exe');
+const TOKEN_ESTIMATE_DIVISOR = 4;
+const ARGUMENT_FLAGS = new Set(process.argv.slice(2));
+const isStdoutOnlyMode = ARGUMENT_FLAGS.has('--stdout-only');
+
+const BENCHMARK_SCENARIOS = [
+  {
+    scenarioId: 'git-show',
+    scenarioName: 'Latest commit detail review',
+    baselineCommand: { command: 'git', args: ['show', 'HEAD', '--stat', '--patch', '--no-color'] },
+    nativeOptimizedCommand: { command: 'git', args: ['show', 'HEAD', '--stat', '--no-color'] },
+    rtkCommand: { command: 'rtk', args: ['git', 'show', 'HEAD', '--stat', '--patch', '--no-color'] },
+  },
+  {
+    scenarioId: 'git-log',
+    scenarioName: 'Commit history review',
+    baselineCommand: { command: 'git', args: ['log', '-n', '50'] },
+    nativeOptimizedCommand: { command: 'git', args: ['log', '--oneline', '-n', '50'] },
+    rtkCommand: { command: 'rtk', args: ['git', 'log', '-n', '50'] },
+  },
+  {
+    scenarioId: 'search-token',
+    scenarioName: 'Search result scan',
+    baselineCommand: { command: 'git', args: ['grep', '-n', 'token'] },
+    nativeOptimizedCommand: { command: 'git', args: ['grep', '-n', 'token', 'README.md', 'docs'] },
+    rtkCommand: { command: 'rtk', args: ['git', 'grep', '-n', 'token'] },
+  },
+];
+
+function estimateTokenCount(outputText) {
+  if (!outputText || outputText.length === 0) {
+    return 0;
+  }
+
+  return Math.ceil(outputText.length / TOKEN_ESTIMATE_DIVISOR);
+}
+
+function formatCommandLine(commandDefinition) {
+  return [commandDefinition.command, ...commandDefinition.args].join(' ');
+}
+
+function executeCommand(commandDefinition) {
+  const commandResult = spawnSync(commandDefinition.command, commandDefinition.args, {
+    cwd: REPOSITORY_ROOT,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024 * 20,
+  });
+
+  const standardOutput = commandResult.stdout || '';
+  const standardError = commandResult.stderr || '';
+  const combinedOutput = `${standardOutput}${standardError}`;
+  const normalizedOutput = combinedOutput.trimEnd();
+
+  const outputLineCount = normalizedOutput.length === 0
+    ? 0
+    : normalizedOutput.split(/\r?\n/u).length;
+
+  return {
+    command: formatCommandLine(commandDefinition),
+    exitCode: typeof commandResult.status === 'number' ? commandResult.status : 1,
+    outputChars: normalizedOutput.length,
+    outputLines: outputLineCount,
+    estimatedTokens: estimateTokenCount(normalizedOutput),
+  };
+}
+
+function resolveRtkBinaryPath() {
+  const configuredRtkBinaryPath = process.env.RTK_BINARY_PATH;
+
+  if (configuredRtkBinaryPath && existsSync(configuredRtkBinaryPath)) {
+    return {
+      executablePath: configuredRtkBinaryPath,
+      source: 'env',
+    };
+  }
+
+  if (existsSync(LOCAL_RTK_BINARY_PATH)) {
+    return {
+      executablePath: LOCAL_RTK_BINARY_PATH,
+      source: 'local-tools',
+    };
+  }
+
+  return {
+    executablePath: 'rtk',
+    source: 'system-path',
+  };
+}
+
+function detectRtkAvailability() {
+  const rtkBinary = resolveRtkBinaryPath();
+
+  const versionResult = spawnSync(rtkBinary.executablePath, ['--version'], {
+    cwd: REPOSITORY_ROOT,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+  });
+
+  if (versionResult.error || versionResult.status !== 0) {
+    return {
+      isAvailable: false,
+      version: null,
+      source: rtkBinary.source,
+      executablePath: rtkBinary.executablePath,
+      reason: versionResult.error
+        ? versionResult.error.message
+        : (versionResult.stderr || versionResult.stdout || 'RTK command unavailable').trim(),
+    };
+  }
+
+  const versionMatch = (versionResult.stdout || '').match(/\d+\.\d+\.\d+/u);
+  return {
+    isAvailable: true,
+    version: versionMatch ? versionMatch[0] : null,
+    source: rtkBinary.source,
+    executablePath: rtkBinary.executablePath,
+    reason: null,
+  };
+}
+
+function buildRtkCommand(commandDefinition, rtkAvailability) {
+  return {
+    command: rtkAvailability.executablePath || commandDefinition.command,
+    args: commandDefinition.args,
+  };
+}
+
+function computeSavingsSummary(baselineTokens, optimizedTokens) {
+  if (baselineTokens <= 0) {
+    return {
+      tokenDelta: 0,
+      savingsPercent: 0,
+    };
+  }
+
+  const tokenDelta = baselineTokens - optimizedTokens;
+  const savingsPercent = Number(((tokenDelta / baselineTokens) * 100).toFixed(2));
+
+  return {
+    tokenDelta,
+    savingsPercent,
+  };
+}
+
+function calculateAverageSavings(benchmarkRows, savingsKeyName) {
+  const availableSavings = benchmarkRows
+    .map((benchmarkRow) => benchmarkRow[savingsKeyName]?.savingsPercent)
+    .filter((savingsPercent) => typeof savingsPercent === 'number');
+
+  if (availableSavings.length === 0) {
+    return null;
+  }
+
+  const totalSavings = availableSavings.reduce((runningTotal, savingsPercent) => runningTotal + savingsPercent, 0);
+  return Number((totalSavings / availableSavings.length).toFixed(2));
+}
+
+async function runTokenOptimizationBenchmark() {
+  const rtkAvailability = detectRtkAvailability();
+  const scenarioResults = [];
+
+  for (const benchmarkScenario of BENCHMARK_SCENARIOS) {
+    const baselineRun = executeCommand(benchmarkScenario.baselineCommand);
+    const nativeOptimizedRun = executeCommand(benchmarkScenario.nativeOptimizedCommand);
+    const nativeSavings = computeSavingsSummary(
+      baselineRun.estimatedTokens,
+      nativeOptimizedRun.estimatedTokens
+    );
+
+    let rtkRun = null;
+    let rtkSavings = null;
+
+    if (rtkAvailability.isAvailable) {
+      rtkRun = executeCommand(buildRtkCommand(benchmarkScenario.rtkCommand, rtkAvailability));
+      if (rtkRun.exitCode === 0) {
+        rtkSavings = computeSavingsSummary(baselineRun.estimatedTokens, rtkRun.estimatedTokens);
+      }
+    }
+
+    scenarioResults.push({
+      scenarioId: benchmarkScenario.scenarioId,
+      scenarioName: benchmarkScenario.scenarioName,
+      baseline: baselineRun,
+      nativeOptimized: nativeOptimizedRun,
+      nativeSavings,
+      rtk: rtkRun,
+      rtkSavings,
+    });
+  }
+
+  const benchmarkReport = {
+    generatedAt: new Date().toISOString(),
+    reportName: 'token-optimization-benchmark',
+    methodology: {
+      tokenEstimate: `estimated_tokens = ceil(output_chars / ${TOKEN_ESTIMATE_DIVISOR})`,
+      scope: 'command-output estimate only; model-specific tokenization differs by provider',
+      repositoryRoot: REPOSITORY_ROOT,
+    },
+    environment: {
+      nodeVersion: process.version,
+      platform: process.platform,
+      rtk: rtkAvailability,
+    },
+    scenarios: scenarioResults,
+    summary: {
+      scenarioCount: scenarioResults.length,
+      averageNativeSavingsPercent: calculateAverageSavings(scenarioResults, 'nativeSavings'),
+      averageRtkSavingsPercent: calculateAverageSavings(scenarioResults, 'rtkSavings'),
+    },
+    artifact: {
+      path: REPORT_PATH,
+      writeMode: isStdoutOnlyMode ? 'stdout-only' : 'stdout-and-file',
+    },
+  };
+
+  if (!isStdoutOnlyMode) {
+    await fs.mkdir(dirname(REPORT_PATH), { recursive: true });
+    await fs.writeFile(REPORT_PATH, JSON.stringify(benchmarkReport, null, 2) + '\n', 'utf8');
+  }
+
+  return benchmarkReport;
+}
+
+runTokenOptimizationBenchmark()
+  .then((benchmarkReport) => {
+    console.log(JSON.stringify(benchmarkReport, null, 2));
+  })
+  .catch((benchmarkError) => {
+    const errorMessage = benchmarkError instanceof Error ? benchmarkError.message : String(benchmarkError);
+    console.error(`Token benchmark failed: ${errorMessage}`);
+    process.exit(1);
+  });