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

> Discover AIOX-Core's multi-layer validation system. Learn how pre-commit, pre-push, and CI/CD checks ensure code quality and security before and after every commit.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: deep-dive
- Published: 2026-03-15

---

**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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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.

```javascript
// 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`](https://github.com/SynkraAI/aiox-core/blob/main/scripts/ensure-manifest.js) validates that [`install-manifest.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/bin/aiox.js) correctly references the installation wizard at [`packages/installer/src/wizard/index.js`](https://github.com/SynkraAI/aiox-core/blob/main/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:

```bash
$ 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:

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

```

### Running Dependency Validation Locally

Developers can verify dependency declarations before pushing:

```bash
$ 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`](https://github.com/SynkraAI/aiox-core/blob/main/bin/utils/framework-guard.js), blocking unauthorized changes to L1/L2 protected paths defined in [`core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config.yaml) while ensuring [`install-manifest.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/install-manifest.yaml) remains synchronized.
- **Pre-push hooks** maintain entity registry freshness through [`.aiox-core/hooks/ids-pre-push.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/hooks/ids-pre-push.js) without blocking developer workflows.
- **CI/CD pipeline** in [`.github/workflows/ci.yml`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/bin/utils/framework-guard.js). When the YAML parser fails to read [`.aiox-core/core-config.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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.