How AIOX-Core's Multi-Layer Validation System Works: Pre-Commit, Pre-Push, and CI/CD

AIOX-Core enforces code quality through a three-tier validation architecture that runs Framework Guard checks locally before commits, syncs entity registries before pushes, and executes comprehensive security, dependency, and smoke tests in CI/CD.

The SynkraAI/aiox-core repository implements a defense-in-depth strategy that catches errors at the earliest possible stage. This multi-layer validation system coordinates local Git hooks with cloud-based automation to protect architectural boundaries and ensure dependency integrity across Node.js versions 18 through 25.

Pre-Commit Layer: Framework Guard and Manifest Sync

Every local git commit triggers the pre-commit hook at .husky/pre-commit, which executes two critical validation scripts unless bypassed with --no-verify.

Configuration via core-config.yaml

The Framework Guard reads .aiox-core/core-config.yaml to determine protection levels. This file defines boundary.frameworkProtection as a toggle and specifies two glob arrays: protected (L1/L2 boundaries) and exceptions (L3 allowed paths). If the configuration file is missing or malformed, the system falls back to hard-coded constants FALLBACK_PROTECTED and FALLBACK_EXCEPTIONS to ensure core framework files remain protected.

Implementation in framework-guard.js

The core detection logic resides in bin/utils/framework-guard.js. The script uses a line-based YAML parser (zero external dependencies) to load configurations, converts globs to RegExp patterns via globToRegex, and compares staged files against protected paths.

// Detection logic from framework-guard.js
if (matchesAny(normalized, blockedPatterns) && !matchesAny(normalized, allowedPatterns)) {
  blockedFiles.push(normalized);
}

The script collects staged files using git diff --cached --name-only. When a file matches a protected pattern but fails to match an exception pattern, the commit aborts with process.exit(1) and displays instructions for bypassing the guard.

Manifest Synchronization

Simultaneously, scripts/ensure-manifest.js validates that install-manifest.yaml accurately reflects the current framework state. This ensures that installation manifests remain synchronized with source code changes before they enter the repository history.

Pre-Push Layer: IDS Registry Synchronization

Before any code leaves the local environment, the pre-push hook at .husky/pre-push executes .aiox-core/hooks/ids-pre-push.js to update the internal entity-ID registry. This lightweight Node script ensures downstream CI processes operate with a fresh entity map. Unlike the pre-commit layer, this hook operates silently and does not block the push on failure (|| true), allowing the operation to proceed regardless of registry sync status.

CI/CD Layer: Comprehensive Validation Pipeline

The GitHub Actions workflow defined in .github/workflows/ci.yml orchestrates a change-aware pipeline that triggers on every push to main or pull request against main.

Change Detection and Conditional Execution

The pipeline uses dorny/paths-filter to create boolean outputs (code, tests, config, stories) that determine which downstream jobs execute. This selective approach avoids wasting compute on irrelevant changes while ensuring critical paths receive full validation.

Security Audits and Code Quality

The workflow runs npm audit --audit-level=critical to fail only on critical vulnerabilities. Subsequent jobs execute npm run lint for ESLint validation and npm run typecheck for TypeScript compilation across the codebase.

Test Matrix and Story Validation

A multi-node matrix tests the Jest suite across Node.js versions 18 through 25 to guarantee cross-version compatibility. The pipeline also validates Markdown story files using node .aiox-core/utils/aiox-validator.js stories, ensuring all narrative documentation contains required checkbox syntax ([]).

Dependency and Installation Verification

The dependency-validation job runs scripts/validate-aiox-core-deps.js, which scans all .js files in .aiox-core/development/scripts/ for require() calls. The script verifies that every external package dependency appears in .aiox-core/package.json, excluding an internal allow-list.

The brownfield-install-test simulates real-world usage by packing the repository, creating a temporary consumer project, and installing the tarball to verify that nested .aiox-core dependencies resolve correctly in existing project contexts.

Finally, the installer-smoke-test confirms that the CLI entry point at bin/aiox.js correctly references the installation wizard at packages/installer/src/wizard/index.js.

Local Development Workflow Examples

Blocking a Commit to Protected Paths

Attempting to modify core framework files triggers the Framework Guard immediately:

$ echo "console.log('unauthorized');" >> bin/aiox.js
$ git add bin/aiox.js
$ git commit -m "Modify core"
Framework Guard: Commit blocked!

The following framework files are protected (L1/L2):
  - bin/aiox.js

To bypass (framework contributors only):
  git commit --no-verify

Bypassing the Guard

Authorized contributors can override protection when necessary:

git commit -m "Emergency fix" --no-verify

Running Dependency Validation Locally

Developers can verify dependency declarations before pushing:

$ node scripts/validate-aiox-core-deps.js
--- .aiox-core Dependency Validation (INS-4.12) ---

Scanning 12 scripts in .aiox-core/development/scripts/

Found 8 unique external packages across 12 scripts
Declared in .aiox-core/package.json: 7
Allowlisted (optional/dev-time): 10

PASS: All script dependencies are declared in .aiox-core/package.json

Summary

• Pre-commit hooks enforce immediate feedback via bin/utils/framework-guard.js, blocking unauthorized changes to L1/L2 protected paths defined in core-config.yaml while ensuring install-manifest.yaml remains synchronized.
• Pre-push hooks maintain entity registry freshness through .aiox-core/hooks/ids-pre-push.js without blocking developer workflows.
• CI/CD pipeline in .github/workflows/ci.yml executes selective, comprehensive validation including security audits, multi-node testing (Node 18-25), dependency completeness checks, and brownfield installation scenarios.
• Defense-in-depth architecture ensures that simple mistakes are caught locally while complex integration issues are caught in the cloud before reaching the main branch.

Frequently Asked Questions

What happens if core-config.yaml is missing or corrupted?

The Framework Guard implements hard-coded fallback patterns via FALLBACK_PROTECTED and FALLBACK_EXCEPTIONS constants in bin/utils/framework-guard.js. When the YAML parser fails to read .aiox-core/core-config.yaml, the system defaults to these safe values to ensure critical framework files remain protected regardless of configuration state.

Can I disable the pre-commit checks entirely?

While not recommended for standard development, you can bypass the Framework Guard for a single commit using git commit --no-verify. To permanently disable protection, set boundary.frameworkProtection to false in core-config.yaml. Note that the CI/CD pipeline will still enforce all validation rules regardless of local bypasses.

How does the CI pipeline decide which tests to run?

The workflow utilizes dorny/paths-filter in the initial "changes" job to detect modifications across code, tests, config, and stories paths. Downstream jobs include conditional logic (if: needs.changes.outputs.code == 'true') that skips irrelevant validation steps. For example, the Jest test matrix only executes when source or test files change, while story validation runs only when Markdown files in story directories are modified.

What is the brownfield install test and why does it matter?

The brownfield install test simulates installing AIOX-Core into an existing Node.js project rather than a clean environment. The workflow packs the repository into a tarball, initializes a temporary consumer project, and executes npm install with the local package. This verifies that nested dependencies within .aiox-core/ resolve correctly and that the framework integrates properly into projects with pre-existing node_modules structures, preventing "works on my machine" issues in production environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}