feat(core): add fast path execution gate

Author: rafaelscosta

.aiox-core/core/config/schemas/framework-config.schema.json

@@ -97,6 +97,34 @@
           "type": "boolean",
           "description": "Require orchestrator review before story state mutation",
           "default": true
+        },
+        "fast_path": {
+          "type": "object",
+          "description": "Fast-path gate defaults for mechanical, batchable, or parallelizable tasks",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true
+            },
+            "min_confidence": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.58
+            },
+            "min_batch_items": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 3
+            },
+            "external_executor_threshold": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.78
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

.aiox-core/core/orchestration/fast-path-gate.js

@@ -0,0 +1,310 @@
+'use strict';
+
+const DEFAULT_FAST_PATH_CONFIG = Object.freeze({
+  enabled: true,
+  minConfidence: 0.58,
+  minBatchItems: 3,
+  externalExecutorThreshold: 0.78,
+});
+
+const STRUCTURED_FILE_EXTENSIONS = new Set([
+  '.csv',
+  '.json',
+  '.jsonl',
+  '.md',
+  '.toml',
+  '.tsv',
+  '.txt',
+  '.yaml',
+  '.yml',
+]);
+
+const AUTOMATION_PATTERNS = Object.freeze([
+  {
+    id: 'bulk-edit',
+    weight: 3,
+    pattern: /\b(batch|bulk|many files|multiple files|all files|in one shot|one shot)\b/i,
+  },
+  {
+    id: 'structured-transform',
+    weight: 3,
+    pattern: /\b(yaml|json|csv|markdown|frontmatter|schema|variable|variables|field|fields)\b/i,
+  },
+  {
+    id: 'mechanical-edit',
+    weight: 3,
+    pattern: /\b(replace|rename|populate|fill|complete|update|convert|transform|normalize|format)\b/i,
+  },
+  {
+    id: 'map-then-apply',
+    weight: 2,
+    pattern: /\b(map|extract|derive|template|codemod|script)\b/i,
+  },
+  {
+    id: 'repetition',
+    weight: 2,
+    pattern: /\b(repeated|repetitive|same change|similar change|dumb task|tedious)\b/i,
+  },
+  {
+    id: 'parallelizable',
+    weight: 2,
+    pattern: /\b(parallel|independent|per file|per item|per record)\b/i,
+  },
+]);
+
+const RISK_PATTERNS = Object.freeze([
+  {
+    id: 'architecture',
+    weight: 3,
+    pattern: /\b(architecture|architectural|design decision|adr|contract)\b/i,
+  },
+  {
+    id: 'security',
+    weight: 3,
+    pattern: /\b(security|secret|token|credential|auth|permission|pii|rls)\b/i,
+  },
+  {
+    id: 'destructive',
+    weight: 3,
+    pattern: /\b(delete|remove data|drop|reset|rewrite history|destructive)\b/i,
+  },
+  {
+    id: 'production',
+    weight: 2,
+    pattern: /\b(production|prod|release|billing|payment|customer)\b/i,
+  },
+  {
+    id: 'migration',
+    weight: 2,
+    pattern: /\b(migration|migrate|schema change|breaking change)\b/i,
+  },
+]);
+
+function normalizeConfig(config = {}) {
+  const clamp01 = (value, fallback) => {
+    const numericValue = Number(value);
+    if (!Number.isFinite(numericValue)) {
+      return fallback;
+    }
+    return Math.min(1, Math.max(0, numericValue));
+  };
+  const positiveInteger = (value, fallback) => {
+    const numericValue = Number(value);
+    if (!Number.isFinite(numericValue)) {
+      return fallback;
+    }
+    return Math.max(1, Math.floor(numericValue));
+  };
+
+  return {
+    enabled: config.enabled !== false,
+    minConfidence: clamp01(
+      config.minConfidence ?? config.min_confidence,
+      DEFAULT_FAST_PATH_CONFIG.minConfidence,
+    ),
+    minBatchItems: positiveInteger(
+      config.minBatchItems ?? config.min_batch_items,
+      DEFAULT_FAST_PATH_CONFIG.minBatchItems,
+    ),
+    externalExecutorThreshold: clamp01(
+      config.externalExecutorThreshold ?? config.external_executor_threshold,
+      DEFAULT_FAST_PATH_CONFIG.externalExecutorThreshold,
+    ),
+  };
+}
+
+function normalizeTask(input = {}) {
+  const task = input.task || input;
+  return {
+    description: String(task.description || task.summary || task.title || ''),
+    files: Array.isArray(task.files) ? task.files : [],
+    acceptanceCriteria: Array.isArray(task.acceptanceCriteria)
+      ? task.acceptanceCriteria
+      : Array.isArray(task.acceptance_criteria)
+        ? task.acceptance_criteria
+        : [],
+    itemCount: Number.isFinite(task.itemCount)
+      ? task.itemCount
+      : Number.isFinite(task.item_count)
+        ? task.item_count
+        : null,
+  };
+}
+
+function normalizePathExtension(filePath) {
+  const match = String(filePath || '').toLowerCase().match(/(\.[a-z0-9]+)$/);
+  return match ? match[1] : '';
+}
+
+function collectSignals(patterns, text) {
+  return patterns
+    .filter(({ pattern }) => pattern.test(text))
+    .map(({ id, weight }) => ({ id, weight }));
+}
+
+function getTaskText(task) {
+  return [
+    task.description,
+    ...task.acceptanceCriteria.map((criterion) => String(criterion || '')),
+    ...task.files.map((file) => String(file || '')),
+  ].join('\n');
+}
+
+function scoreFastPath({ automationSignals, riskSignals, files, structuredFileCount, batchSize }) {
+  const automationWeight = automationSignals.reduce((sum, signal) => sum + signal.weight, 0);
+  const riskWeight = riskSignals.reduce((sum, signal) => sum + signal.weight, 0);
+  const fileWeight = Math.min(files.length, 8) * 0.45;
+  const structuredWeight = Math.min(structuredFileCount, 6) * 0.55;
+  const batchWeight = Math.min(batchSize, 10) * 0.35;
+
+  const rawScore = automationWeight + fileWeight + structuredWeight + batchWeight - riskWeight * 1.35;
+  return Math.max(0, Math.min(1, rawScore / 13));
+}
+
+function chooseMode({
+  confidence,
+  config,
+  externalExecutorsEnabled,
+  parallelizable,
+  structuredFileCount,
+  batchSize,
+}) {
+  if (externalExecutorsEnabled && confidence >= config.externalExecutorThreshold) {
+    return 'external_executor';
+  }
+
+  if (parallelizable && batchSize >= config.minBatchItems) {
+    return 'parallel_batch';
+  }
+
+  if (structuredFileCount > 0 || batchSize >= config.minBatchItems) {
+    return 'deterministic_batch';
+  }
+
+  return 'standard';
+}
+
+function buildActions(mode) {
+  if (mode === 'external_executor') {
+    return [
+      'Prepare a bounded prompt with target files, schema, acceptance criteria, and validation commands.',
+      'Run a dry-run plan first, then delegate with the configured external executor sandbox.',
+      'Review the executor diff before mutating story or issue state.',
+    ];
+  }
+
+  if (mode === 'parallel_batch') {
+    return [
+      'Map target files or records once before editing.',
+      'Group independent changes by file or record and apply them as a batch.',
+      'Run targeted validation on the changed surface before broader checks.',
+    ];
+  }
+
+  if (mode === 'deterministic_batch') {
+    return [
+      'Extract the data shape and replacement rules before editing.',
+      'Use a deterministic transform or structured parser instead of conversational one-by-one edits.',
+      'Validate output syntax and diff size before continuing.',
+    ];
+  }
+
+  return [
+    'Use the standard story/task workflow.',
+    'Keep changes sequential when risk or ambiguity is higher than the automation signal.',
+  ];
+}
+
+function evaluateFastPath(input = {}) {
+  const config = normalizeConfig(input.config || input.fastPath || {});
+  const task = normalizeTask(input);
+  const text = getTaskText(task);
+  const automationSignals = collectSignals(AUTOMATION_PATTERNS, text);
+  const riskSignals = collectSignals(RISK_PATTERNS, text);
+  const structuredFileCount = task.files.filter((file) => (
+    STRUCTURED_FILE_EXTENSIONS.has(normalizePathExtension(file))
+  )).length;
+  const batchSize = task.itemCount ?? Math.max(task.files.length, structuredFileCount);
+  const parallelizable = (
+    task.files.length >= config.minBatchItems ||
+    automationSignals.some((signal) => signal.id === 'parallelizable')
+  );
+
+  if (!config.enabled) {
+    return {
+      gate: 'fast_path',
+      enabled: false,
+      passed: false,
+      mode: 'standard',
+      confidence: 0,
+      parallelizable: false,
+      riskLevel: 'unknown',
+      reasons: ['fast path gate disabled by configuration'],
+      evidence: { automationSignals: [], riskSignals: [], fileCount: task.files.length, structuredFileCount, batchSize },
+      actions: buildActions('standard'),
+    };
+  }
+
+  const confidence = scoreFastPath({
+    automationSignals,
+    riskSignals,
+    files: task.files,
+    structuredFileCount,
+    batchSize,
+  });
+  const passed = confidence >= config.minConfidence && riskSignals.length === 0;
+  const mode = passed
+    ? chooseMode({
+      confidence,
+      config,
+      externalExecutorsEnabled: Boolean(input.externalExecutorsEnabled || input.external_executors_enabled),
+      parallelizable,
+      structuredFileCount,
+      batchSize,
+    })
+    : 'standard';
+  const riskLevel = riskSignals.length >= 2 ? 'high' : riskSignals.length === 1 ? 'medium' : 'low';
+  const reasons = [
+    ...automationSignals.map((signal) => `automation signal: ${signal.id}`),
+    ...riskSignals.map((signal) => `risk signal: ${signal.id}`),
+  ];
+
+  if (structuredFileCount > 0) {
+    reasons.push(`structured files detected: ${structuredFileCount}`);
+  }
+  if (batchSize >= config.minBatchItems) {
+    reasons.push(`batch size meets threshold: ${batchSize}`);
+  }
+  if (!passed && reasons.length === 0) {
+    reasons.push('insufficient automation signal for fast path');
+  }
+
+  return {
+    gate: 'fast_path',
+    enabled: true,
+    passed,
+    mode,
+    confidence,
+    parallelizable: passed && parallelizable,
+    riskLevel,
+    reasons,
+    evidence: {
+      automationSignals,
+      riskSignals,
+      fileCount: task.files.length,
+      structuredFileCount,
+      batchSize,
+    },
+    actions: buildActions(mode),
+  };
+}
+
+module.exports = {
+  DEFAULT_FAST_PATH_CONFIG,
+  STRUCTURED_FILE_EXTENSIONS,
+  AUTOMATION_PATTERNS,
+  RISK_PATTERNS,
+  evaluateFastPath,
+  normalizeConfig,
+  normalizeTask,
+};

.aiox-core/core/orchestration/index.js

@@ -23,6 +23,7 @@ const TechStackDetector = require('./tech-stack-detector');
 const ConditionEvaluator = require('./condition-evaluator');
 const SkillDispatcher = require('./skill-dispatcher');
 const executionProfileResolver = require('./execution-profile-resolver');
+const fastPathGate = require('./fast-path-gate');
 
 // Epic 0: Master Orchestrator (ADE)
 const MasterOrchestrator = require('./master-orchestrator');
@@ -162,6 +163,8 @@ module.exports = {
   SkillDispatcher,
   ExecutionProfileResolver: executionProfileResolver,
   resolveExecutionProfile: executionProfileResolver.resolveExecutionProfile,
+  FastPathGate: fastPathGate,
+  evaluateFastPath: fastPathGate.evaluateFastPath,
 
   // Epic 0: Orchestrator constants
   OrchestratorState: MasterOrchestrator.OrchestratorState,

.aiox-core/development/tasks/fast-path-gate.md

@@ -0,0 +1,36 @@
+# Fast Path Gate
+
+## Purpose
+
+Choose the fastest safe execution path before starting a task. This gate prevents slow one-by-one conversational edits for mechanical work such as YAML population, bulk replacements, structured data normalization, and repeated per-file updates.
+
+## Inputs
+
+- `description` — task summary or user request
+- `files` — known target files
+- `acceptanceCriteria` — expected outcomes
+- `itemCount` — optional number of records, fields, or files to process
+- `externalExecutorsEnabled` — whether delegation through `aiox-delegate` is allowed
+
+## Execution
+
+1. Evaluate the task with `evaluateFastPath()` from `.aiox-core/core/orchestration/fast-path-gate.js`.
+2. If the gate returns `mode: standard`, continue with the normal story/task workflow.
+3. If the gate returns `mode: deterministic_batch`, extract the schema and write one deterministic transform or structured edit plan before changing files.
+4. If the gate returns `mode: parallel_batch`, map all independent targets first, then apply grouped edits in parallel batches.
+5. If the gate returns `mode: external_executor`, create a bounded executor prompt and run `aiox-delegate` with the configured sandbox.
+6. Always review the resulting diff and run targeted validation before story or issue closure.
+
+## Acceptance Criteria
+
+- Mechanical repeated tasks are not executed as long sequential conversational edits.
+- Security, production, destructive, migration, and architectural tasks fall back to the standard workflow unless explicitly re-scoped.
+- Fast-path decisions include confidence, reasons, evidence, and next actions.
+- External executor usage remains opt-in and sandboxed by configuration.
+
+## Anti-Patterns
+
+- Do not use fast path for ambiguous architecture or security decisions.
+- Do not skip validation because a task is mechanical.
+- Do not delegate externally when the task contains secrets or production risk.
+- Do not mutate story or issue state until the diff has been reviewed.