Skip to content

feat(core): add fast path execution gate - #693

Merged
rafaelscosta merged 1 commit into
mainfrom
devops/issue-616-fast-path-gate-20260508
May 8, 2026
Merged

feat(core): add fast path execution gate#693
rafaelscosta merged 1 commit into
mainfrom
devops/issue-616-fast-path-gate-20260508

Conversation

@rafaelscosta

@rafaelscosta rafaelscosta commented May 8, 2026

Copy link
Copy Markdown
Collaborator

Summary

Implements a deterministic Fast Path Gate for issue #616 so mechanical, repeated, and structured-data tasks can be routed away from slow one-by-one conversational execution.

Delivered

  • Adds .aiox-core/core/orchestration/fast-path-gate.js with evaluateFastPath().
  • Exports FastPathGate and evaluateFastPath from the orchestration module.
  • Adds dev.fast_path defaults to framework config and schema.
  • Adds the operational task .aiox-core/development/tasks/fast-path-gate.md.
  • Adds focused tests for YAML batch population, risk fallback, external executor recommendation, disabled config, and schema defaults.
  • Regenerates install manifest.

Validation

  • node -c .aiox-core/core/orchestration/fast-path-gate.js
  • jest tests/core/orchestration/fast-path-gate.test.js tests/config/schema-validation.test.js --runInBand --forceExit
  • node scripts/validate-manifest.js
  • node scripts/validate-package-completeness.js
  • node bin/utils/validate-publish.js
  • npm run lint (0 errors, 114 baseline warnings)
  • npm run typecheck
  • Full Jest: 11 skipped, 330 passed, 330/341 suites; 149 skipped, 8330 passed, 8479 tests
  • git diff --check

Refs #616

Summary by CodeRabbit

  • New Features

    • Added a fast-path gating system that auto-selects execution modes (parallel batch, external executor, deterministic batch, or standard) based on task content, file signals, confidence, batch size, and risk; supports disabling.
  • Documentation

    • Added a developer guide describing fast-path inputs, flows, acceptance criteria, fallback behavior, and anti-patterns.
  • Tests

    • Extended config and gate tests to validate new settings, clamping, normalization, decision outcomes, and defensive copying.
  • Chores

    • Added configurable fast-path defaults and thresholds to config.

@vercel

vercel Bot commented May 8, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
aiox-core Ready Ready Preview, Comment May 8, 2026 3:59am

Request Review

@github-actions github-actions Bot added area: agents Agent system related area: workflows Workflow system related squad mcp type: test Test coverage and quality area: core Core framework (.aios-core/core/) area: installer Installer and setup (packages/installer/) area: synapse SYNAPSE context engine area: cli CLI tools (bin/, packages/aios-pro-cli/) area: pro Pro features (pro/) area: health-check Health check system area: docs Documentation (docs/) area: devops CI/CD, GitHub Actions (.github/) labels May 8, 2026
@coderabbitai

coderabbitai Bot commented May 8, 2026

Copy link
Copy Markdown

Review Change Stack

Walkthrough

This PR introduces a fast path gate that intelligently evaluates automation tasks to recommend the optimal execution mode (external executor, parallel batch, deterministic batch, or standard) based on task patterns, confidence scoring, and configurable thresholds. The implementation includes schema definitions, core gating logic with signal analysis, module integration, documentation, and comprehensive test coverage.

Changes

Fast Path Gate Feature

Layer / File(s) Summary
Configuration Schema & Defaults
.aiox-core/core/config/schemas/framework-config.schema.json, .aiox-core/framework-config.yaml
JSON schema defines dev.fast_path block with enabled, min_confidence (0.58), min_batch_items (3), and external_executor_threshold (0.78). YAML config instantiates these defaults.
Core Gate Implementation
.aiox-core/core/orchestration/fast-path-gate.js
Module exports evaluateFastPath() alongside helpers: normalizeConfig() and normalizeTask() support camelCase/snake_case config fields; helpers extract file extensions and build searchable text; scoreFastPath() computes bounded confidence from weighted signals; chooseMode() selects execution mode based on thresholds and task characteristics; buildActions() generates mode-specific recommendations.
Module Integration & Exports
.aiox-core/core/orchestration/index.js
Imports fastPathGate module and exposes FastPathGate object and evaluateFastPath() function as public API.
Documentation & Test Coverage
.aiox-core/development/tasks/fast-path-gate.md, tests/core/orchestration/fast-path-gate.test.js, tests/config/schema-validation.test.js
Task documentation codifies gate inputs, execution modes, acceptance criteria, and anti-patterns. Jest suite validates parallel batch selection, risk rejection, external executor delegation, disabled state handling, and config normalization across scenarios. Schema validation test asserts default config values.
Install Manifest
.aiox-core/install-manifest.yaml
Generated manifest metadata updated to include the new schema changes, added fast-path-gate.js, updated orchestration index entry, and added task documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • SynkraAI/aiox-core#692: Adds external executor delegation and aiox-delegate CLI, which complements this PR's external_executor mode and threshold configuration.

Suggested labels

type: docs

Suggested reviewers

  • Pedrovaleriolopez
  • oalanicolas
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'feat(core): add fast path execution gate' directly and clearly summarizes the main change—introducing a new fast path execution gate feature in the core module. It accurately reflects the primary deliverable across all modified files.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch devops/issue-616-fast-path-gate-20260508

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented May 8, 2026

Copy link
Copy Markdown
Contributor

📊 Coverage Report

Coverage report not available

📈 Full coverage report available in Codecov


Generated by PR Automation (Story 6.1)

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (2)
.aiox-core/core/orchestration/index.js (1)

26-26: ⚡ Quick win

Use absolute import for fast-path gate module

Line 26 introduces a relative import; this conflicts with the repository import rule.

As per coding guidelines, **/*.{js,jsx,ts,tsx}: Use absolute imports instead of relative imports in all code.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.aiox-core/core/orchestration/index.js at line 26, Replace the relative
require for the fast-path gate with an absolute import per repo rules: find the
require call using the symbol fastPathGate (require('./fast-path-gate')) and
change it to use the package/root-absolute path that maps to the same module
(e.g., require('core/orchestration/fast-path-gate') or the project's configured
absolute alias) so the import is absolute rather than relative.
tests/core/orchestration/fast-path-gate.test.js (1)

7-8: ⚡ Quick win

Switch test imports to absolute paths

Lines 7-8 use deep relative imports; align these with the project’s absolute import convention.

As per coding guidelines, **/*.{js,jsx,ts,tsx}: Use absolute imports instead of relative imports in all code.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/core/orchestration/fast-path-gate.test.js` around lines 7 - 8, Replace
the deep relative requires for the fast-path-gate import and the orchestration
import with the project’s absolute import alias; locate the two require
statements that import from
'../../../.aiox-core/core/orchestration/fast-path-gate' and
'../../../.aiox-core/core/orchestration' and change them to use the configured
absolute module specifier (for example
'@aiox-core/core/orchestration/fast-path-gate' and
'@aiox-core/core/orchestration' or the project's equivalent alias) so the test
follows the absolute import convention.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.aiox-core/core/orchestration/fast-path-gate.js:
- Line 215: The current calculation for batchSize uses the || operator which
treats a valid task.itemCount of 0 as missing; change the expression that
computes batchSize to use the nullish coalescing operator so that task.itemCount
is used when explicitly set (including 0) and only falls back to
Math.max(task.files.length, structuredFileCount) when itemCount is null or
undefined; update the expression referencing batchSize, task.itemCount,
task.files, and structuredFileCount accordingly.
- Around line 83-101: normalizeConfig currently accepts out-of-range values
(e.g., minConfidence > 1 or < 0, minBatchItems < 1) and can silently break
routing; update normalizeConfig (used by evaluateFastPath) to validate and clamp
inputs to safe ranges: clamp minConfidence to [0,1], enforce minBatchItems to a
positive integer >= 1 (coerce/round if necessary), and ensure
externalExecutorThreshold is non-negative (or within any documented max); apply
same validation for both camelCase and snake_case keys
(minConfidence/min_confidence, minBatchItems/min_batch_items,
externalExecutorThreshold/external_executor_threshold) and fall back to
DEFAULT_FAST_PATH_CONFIG only after clamping/validation.

In `@tests/config/schema-validation.test.js`:
- Around line 122-124: Add an assertion to the test that checks the default
value for external_executor_threshold so config/schema drift is detected;
specifically, in the same test block that asserts
frameworkConfig.dev.fast_path.enabled, .min_confidence, and .min_batch_items,
add an expectation for frameworkConfig.dev.fast_path.external_executor_threshold
to equal the intended default (e.g., the numeric default your config defines) so
the test fails if that default changes unexpectedly.

---

Nitpick comments:
In @.aiox-core/core/orchestration/index.js:
- Line 26: Replace the relative require for the fast-path gate with an absolute
import per repo rules: find the require call using the symbol fastPathGate
(require('./fast-path-gate')) and change it to use the package/root-absolute
path that maps to the same module (e.g.,
require('core/orchestration/fast-path-gate') or the project's configured
absolute alias) so the import is absolute rather than relative.

In `@tests/core/orchestration/fast-path-gate.test.js`:
- Around line 7-8: Replace the deep relative requires for the fast-path-gate
import and the orchestration import with the project’s absolute import alias;
locate the two require statements that import from
'../../../.aiox-core/core/orchestration/fast-path-gate' and
'../../../.aiox-core/core/orchestration' and change them to use the configured
absolute module specifier (for example
'@aiox-core/core/orchestration/fast-path-gate' and
'@aiox-core/core/orchestration' or the project's equivalent alias) so the test
follows the absolute import convention.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c56a524c-c490-460b-ba09-5d5e257e996e

📥 Commits

Reviewing files that changed from the base of the PR and between ce322bf and 2016354.

📒 Files selected for processing (8)
  • .aiox-core/core/config/schemas/framework-config.schema.json
  • .aiox-core/core/orchestration/fast-path-gate.js
  • .aiox-core/core/orchestration/index.js
  • .aiox-core/development/tasks/fast-path-gate.md
  • .aiox-core/framework-config.yaml
  • .aiox-core/install-manifest.yaml
  • tests/config/schema-validation.test.js
  • tests/core/orchestration/fast-path-gate.test.js

Comment thread .aiox-core/core/orchestration/fast-path-gate.js
Comment thread .aiox-core/core/orchestration/fast-path-gate.js Outdated
Comment thread tests/config/schema-validation.test.js

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.aiox-core/core/orchestration/fast-path-gate.js:
- Around line 10-53: STRUCTURED_FILE_EXTENSIONS and AUTOMATION_PATTERNS are
exported as mutable structures; change to internal frozen constants and expose
defensive copies/read-only accessors: keep an internal frozen Set
(STRUCTURED_FILE_EXTENSIONS_FROZEN) and a frozen array of frozen pattern objects
(AUTOMATION_PATTERNS_FROZEN using Object.freeze on each pattern object), then
replace direct exports with functions like getStructuredFileExtensions() that
return new Set(STRUCTURED_FILE_EXTENSIONS_FROZEN) or an array-copy of
AUTOMATION_PATTERNS_FROZEN (e.g., return AUTOMATION_PATTERNS_FROZEN.map(p => ({
id: p.id, weight: p.weight, pattern: p.pattern }))) so consumers cannot mutate
core singleton state; update any references to use the new accessors
(STRUCTURED_FILE_EXTENSIONS -> getStructuredFileExtensions, AUTOMATION_PATTERNS
-> getAutomationPatterns).
- Around line 99-113: The boolean flags are currently taking any truthy value
(e.g., the string "false") which can flip behavior; update normalization so the
returned enabled and the external-executor boolean flag are derived only from
explicit booleans or parsed boolean strings and otherwise fall back to the
DEFAULT_FAST_PATH_CONFIG defaults. Concretely, change how the returned enabled
property is computed (symbol: enabled) to: if typeof config.enabled ===
'boolean' use it, else if typeof config.enabled === 'string' accept only
'true'/'false' (map to true/false), otherwise use
DEFAULT_FAST_PATH_CONFIG.minEnabled/default; apply the same explicit
normalization pattern to the external executor boolean config (the boolean flag
used near externalExecutorThreshold) so string values don't become truthy and
the default from DEFAULT_FAST_PATH_CONFIG is used when the input is not a clear
boolean. Ensure you reference and update the same config keys used in the file
(config.enabled and the external executor boolean key adjacent to
externalExecutorThreshold) and keep minConfidence/minBatchItems handling
unchanged.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c40d8698-2864-42ae-963a-3f6ba019a082

📥 Commits

Reviewing files that changed from the base of the PR and between 2016354 and a770860.

📒 Files selected for processing (8)
  • .aiox-core/core/config/schemas/framework-config.schema.json
  • .aiox-core/core/orchestration/fast-path-gate.js
  • .aiox-core/core/orchestration/index.js
  • .aiox-core/development/tasks/fast-path-gate.md
  • .aiox-core/framework-config.yaml
  • .aiox-core/install-manifest.yaml
  • tests/config/schema-validation.test.js
  • tests/core/orchestration/fast-path-gate.test.js
✅ Files skipped from review due to trivial changes (4)
  • .aiox-core/core/orchestration/index.js
  • .aiox-core/core/config/schemas/framework-config.schema.json
  • .aiox-core/framework-config.yaml
  • .aiox-core/install-manifest.yaml
🚧 Files skipped from review as they are similar to previous changes (2)
  • tests/config/schema-validation.test.js
  • tests/core/orchestration/fast-path-gate.test.js

Comment thread .aiox-core/core/orchestration/fast-path-gate.js Outdated
Comment thread .aiox-core/core/orchestration/fast-path-gate.js

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.aiox-core/development/tasks/fast-path-gate.md:
- Around line 3-14: Add a new "Elicitation" section into fast-path-gate.md
(placed after Purpose and before Inputs) that inserts two explicit checkpoints:
"Before mode selection" and "Before external delegation", each listing required
confirmation questions such as: clarify ambiguous `description` details,
validate `files` list and `itemCount`, confirm `acceptanceCriteria`, and
explicitly request user permission to use `externalExecutorsEnabled` (and any
needed delegation constraints); ensure the section clearly marks that both
checkpoints must be answered before proceeding to mode selection or invoking
external delegation.
- Around line 17-23: Add a pre-evaluation elicitation step before calling
evaluateFastPath(): prompt/record confirmations for scope validation, intended
files, security/production risk, and any sandbox constraints. Surround the
evaluateFastPath() call with explicit error handling: if it throws, returns
invalid output, or an unknown mode, set mode to "standard", record the error and
decision in evidence/logs, and continue the normal workflow. For external
executor runs (aiox-delegate), add timeout and retry/failure handling that
records the executor error, falls back to "standard" mode, and resumes
validation; ensure failures are surfaced in the targeted validation step.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f180c9c3-f4f2-443c-87d7-eb31ee4a8b79

📥 Commits

Reviewing files that changed from the base of the PR and between a770860 and b826379.

📒 Files selected for processing (8)
  • .aiox-core/core/config/schemas/framework-config.schema.json
  • .aiox-core/core/orchestration/fast-path-gate.js
  • .aiox-core/core/orchestration/index.js
  • .aiox-core/development/tasks/fast-path-gate.md
  • .aiox-core/framework-config.yaml
  • .aiox-core/install-manifest.yaml
  • tests/config/schema-validation.test.js
  • tests/core/orchestration/fast-path-gate.test.js
✅ Files skipped from review due to trivial changes (3)
  • .aiox-core/framework-config.yaml
  • .aiox-core/install-manifest.yaml
  • .aiox-core/core/config/schemas/framework-config.schema.json
🚧 Files skipped from review as they are similar to previous changes (4)
  • .aiox-core/core/orchestration/index.js
  • tests/config/schema-validation.test.js
  • tests/core/orchestration/fast-path-gate.test.js
  • .aiox-core/core/orchestration/fast-path-gate.js

Comment thread .aiox-core/development/tasks/fast-path-gate.md
Comment thread .aiox-core/development/tasks/fast-path-gate.md Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
.aiox-core/core/orchestration/index.js (1)

26-26: ⚡ Quick win

Use an absolute import for the new fast-path module

Line 26 introduces a relative import (require('./fast-path-gate')), which conflicts with the repository rule for JS/TS imports. Please switch this new import to the project’s absolute import form.

As per coding guidelines, "Use absolute imports instead of relative imports in all code".

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.aiox-core/core/orchestration/index.js at line 26, Replace the relative
require('./fast-path-gate') with the project's absolute import for that module
so it follows the repo's absolute-import convention; keep the variable name
fastPathGate and the exported module usage unchanged (i.e., update the require
call for fastPathGate to the same absolute module path pattern used by other
imports in the project).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.aiox-core/core/orchestration/index.js:
- Line 26: Replace the relative require('./fast-path-gate') with the project's
absolute import for that module so it follows the repo's absolute-import
convention; keep the variable name fastPathGate and the exported module usage
unchanged (i.e., update the require call for fastPathGate to the same absolute
module path pattern used by other imports in the project).

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 35db7769-a4c3-41a2-bb66-5b3fc02403b0

📥 Commits

Reviewing files that changed from the base of the PR and between b826379 and c05b05a.

📒 Files selected for processing (8)
  • .aiox-core/core/config/schemas/framework-config.schema.json
  • .aiox-core/core/orchestration/fast-path-gate.js
  • .aiox-core/core/orchestration/index.js
  • .aiox-core/development/tasks/fast-path-gate.md
  • .aiox-core/framework-config.yaml
  • .aiox-core/install-manifest.yaml
  • tests/config/schema-validation.test.js
  • tests/core/orchestration/fast-path-gate.test.js
✅ Files skipped from review due to trivial changes (1)
  • .aiox-core/install-manifest.yaml
🚧 Files skipped from review as they are similar to previous changes (3)
  • tests/config/schema-validation.test.js
  • .aiox-core/core/config/schemas/framework-config.schema.json
  • .aiox-core/core/orchestration/fast-path-gate.js

@rafaelscosta
rafaelscosta merged commit 514b193 into main May 8, 2026
42 checks passed
@rafaelscosta
rafaelscosta deleted the devops/issue-616-fast-path-gate-20260508 branch May 8, 2026 04:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: agents Agent system related area: cli CLI tools (bin/, packages/aios-pro-cli/) area: core Core framework (.aios-core/core/) area: devops CI/CD, GitHub Actions (.github/) area: docs Documentation (docs/) area: health-check Health check system area: installer Installer and setup (packages/installer/) area: pro Pro features (pro/) area: synapse SYNAPSE context engine area: workflows Workflow system related mcp squad type: test Test coverage and quality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant