# How to Set Up Pre-Commit and Pre-Push Validation Hooks in aios-core

> Learn to set up pre-commit and pre-push validation hooks in aios-core. Automatically enforce manifest consistency and sync the IDS registry with Husky for efficient code management.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-19

---

**aios-core uses Husky to automatically enforce manifest consistency on every commit and synchronize the IDS entity registry before each push.**

Setting up pre-commit and pre-push validation hooks in aios-core ensures that your install manifest stays synchronized and the IDS (Intelligent Data System) registry remains up-to-date. The SynkraAI/aios-core repository leverages **Husky** to manage Git hooks, automatically installing validation scripts when you run `npm install`.

## How Pre-Commit and Pre-Push Hooks Work in aios-core

The repository defines two primary validation hooks that execute at different stages of your Git workflow.

### Pre-Commit Hook (`.husky/pre-commit`)

The pre-commit hook runs [`scripts/ensure-manifest.js`](https://github.com/SynkraAI/aios-core/blob/main/scripts/ensure-manifest.js) to validate and regenerate [`.aios-core/install-manifest.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/install-manifest.yaml) whenever files under `.aios-core/` are staged.

```bash
#!/usr/bin/env sh

# Keep install-manifest.yaml synchronized whenever .aios-core files are committed.

node scripts/ensure-manifest.js

```

The script performs the following operations:

- **Detect staged files** using `getStagedFiles()` (lines 8-15) to run `git diff --cached --name-only`
- **Decision logic** via `shouldCheckManifest()` (lines 18-25) checks if any staged file lives under `.aios-core/` (excluding the manifest itself)
- **Regeneration flow** in `main()` (lines 27-45) validates the manifest with `scripts/validate-manifest`, regenerates it via [`scripts/generate-install-manifest.js`](https://github.com/SynkraAI/aios-core/blob/main/scripts/generate-install-manifest.js), stages the updated file, and prints a success message

### Pre-Push Hook (`.husky/pre-push`)

The pre-push hook executes [`.aios-core/hooks/ids-pre-push.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/hooks/ids-pre-push.js) to synchronize the IDS entity registry before pushing changes to the remote.

```bash
#!/usr/bin/env sh

# IDS Registry Sync (Story IDS-3)

# Ensures entity registry is up-to-date before push (sync, non-blocking).

node .aios-core/hooks/ids-pre-push.js || true

```

Key implementation details:

- **Change detection** via `getChangedFilesSinceRemote()` (lines 38-86) computes files changed between local `HEAD` and the remote tracking branch using `git diff`
- **Docs-only skip logic** in `isDocsOnlyPush()` (lines 33-36) identifies if the push contains only documentation changes (`docs/`, [`README.md`](https://github.com/SynkraAI/aios-core/blob/main/README.md), [`CHANGELOG.md`](https://github.com/SynkraAI/aios-core/blob/main/CHANGELOG.md), etc.) and skips registry sync when true
- **Registry update** through `main()` (lines 94-123) loads [`.aios-core/core/ids/registry-updater.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/ids/registry-updater.js) and processes changes, logging errors but exiting with code 0 to ensure the push is never blocked

## Setting Up the Validation Hooks

Follow these steps to configure the pre-commit and pre-push validation hooks in your local aios-core environment.

1. **Clone the repository**

   ```bash
   git clone https://github.com/SynkraAI/aios-core.git
   cd aios-core
   ```

2. **Install dependencies**

   ```bash
   npm ci
   ```

   The `prepare` script automatically triggers `husky`, which creates the Git hooks under `.husky/`.

3. **Verify hook installation**

   ```bash
   ls -l .husky
   ```

   You should see `pre-commit` and `pre-push` files, both marked as executable.

4. **Test the pre-commit hook**

   ```bash
   echo "# test" > .aios-core/example.txt

   git add .aios-core/example.txt
   git commit -m "Test pre-commit hook"
   ```

   The hook invokes [`ensure-manifest.js`](https://github.com/SynkraAI/aios-core/blob/main/ensure-manifest.js). If the manifest requires updating, it regenerates automatically and gets staged.

5. **Test the pre-push hook**

   ```bash
   git push
   ```

   The pre-push hook runs [`ids-pre-push.js`](https://github.com/SynkraAI/aios-core/blob/main/ids-pre-push.js). For non-documentation changes, the IDS registry synchronizes before the push completes.

## Customizing the Hooks

You can extend or modify the validation behavior by editing the underlying scripts.

- **Add additional validation** to the pre-commit process by modifying [`scripts/ensure-manifest.js`](https://github.com/SynkraAI/aios-core/blob/main/scripts/ensure-manifest.js) or creating new scripts and referencing them from `.husky/pre-commit`
- **Change registry behavior** by editing [`.aios-core/hooks/ids-pre-push.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/hooks/ids-pre-push.js) to adjust docs-only detection logic or make the sync blocking instead of non-blocking
- **Force registry sync** even on documentation-only pushes by setting the environment variable before pushing:

  ```bash
  export AIOS_IDS_FORCE=1
  git push
  ```

## Summary

- **aios-core** uses **Husky** to manage Git hooks, automatically installing them during `npm install`
- The **pre-commit** hook runs [`scripts/ensure-manifest.js`](https://github.com/SynkraAI/aios-core/blob/main/scripts/ensure-manifest.js) to synchronize [`.aios-core/install-manifest.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/install-manifest.yaml) when files under `.aios-core/` change
- The **pre-push** hook executes [`.aios-core/hooks/ids-pre-push.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/hooks/ids-pre-push.js) to update the IDS entity registry, skipping documentation-only pushes
- Both hooks are located in `.husky/` and call Node.js scripts that implement validation logic using functions like `getStagedFiles()`, `shouldCheckManifest()`, and `isDocsOnlyPush()`

## Frequently Asked Questions

### How do I manually run the manifest validation check?

You can execute the pre-commit validation logic manually by running `node scripts/ensure-manifest.js` from the repository root. This script inspects staged files using `getStagedFiles()` and regenerates the manifest via [`scripts/generate-install-manifest.js`](https://github.com/SynkraAI/aios-core/blob/main/scripts/generate-install-manifest.js) if `.aios-core/` files have changed.

### Can I skip the pre-push hook when pushing documentation changes?

The pre-push hook automatically skips the IDS registry sync when `isDocsOnlyPush()` detects that only documentation files (such as `docs/`, [`README.md`](https://github.com/SynkraAI/aios-core/blob/main/README.md), or [`CHANGELOG.md`](https://github.com/SynkraAI/aios-core/blob/main/CHANGELOG.md)) have changed. If you need to force the registry update anyway, set `AIOS_IDS_FORCE=1` before running `git push`.

### What happens if the IDS registry update fails during pre-push?

The pre-push hook is designed to be non-blocking. Even if [`ids-pre-push.js`](https://github.com/SynkraAI/aios-core/blob/main/ids-pre-push.js) encounters errors while loading [`.aios-core/core/ids/registry-updater.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/ids/registry-updater.js) or processing changes, it logs the error and exits with code 0. The `|| true` in the shell script ensures that `git push` proceeds regardless of the script's exit status.

### Where are the hook scripts located in the repository?

The Git hook entry points reside in `.husky/pre-commit` and `.husky/pre-push`. These shell scripts call the actual validation logic located at [`scripts/ensure-manifest.js`](https://github.com/SynkraAI/aios-core/blob/main/scripts/ensure-manifest.js) (for pre-commit) and [`.aios-core/hooks/ids-pre-push.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/hooks/ids-pre-push.js) (for pre-push), which in turn utilize [`.aios-core/core/ids/registry-updater.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/ids/registry-updater.js) for registry synchronization.