Enforced mode and the commit gate

The commit gate is optional. With quiz.enforced enabled, it holds commits until you pass enough questions about the current session’s work. Editing, testing, and pushing remain available.

Enable enforcement for a project

Run these commands inside the repository you want to gate:

# Keep questions enabled so there is a way to pass the gate.
eklavya config set quiz.enabled true --project
eklavya config set quiz.enforced true --project

Where you commit	What checks the gate	Setup
Claude Code’s Bash tool	The plugin’s before-tool hook	Included with the plugin.
A terminal or another editor	Git’s pre-commit hook	Install separately below.

Project settings stay under ~/.eklavya/projects/; they are not committed to your repository or imposed on teammates. Global enforcement applies inside Claude Code, but the Git hook requires project-level opt-in. A global quiz.enabled: false releases the Git gate unless the project enables questions again.

Note

Cowork can record quiz progress, but it has no commit gate: it produces documents rather than Git commits. See installation options.

What “enough” means, exactly

The gate counts concepts from this session’s work that were unmastered when logged, capped by max_questions_per_task. Its target is:

passes needed = ceil(required concepts × pass_threshold)

With four required concepts and the default threshold of 0.7, you need three distinct concepts passed at grade 3 or higher. Skips and wrong answers count as attempts, but do not pass, and a skip or “I don’t know” never passes whatever grade it carries: Claude cannot record one with a passing grade. Review questions and unrelated topics do not clear an obligation created by this session’s work. Nor does correcting a missed answer from its explainer page: the concept stays on the retry list.

Example: a gate requiring three passes

Check the passing count with /eklavya:gate. A retry is useful only if it adds a passing concept.

1. 01 Log four concepts

   Four unmastered concepts establish the requirement. The threshold needs three passes.

2. 02 Pass two

   Two concepts score at least 3. A third answer is wrong, so the commit is still held.

3. 03 Pass another

   Answer a remaining work concept correctly, or pass a new question in a retry.

4. 04 Commit again

   Three distinct work concepts have passed. The gate now allows the commit.

The required count can grow as new work is logged; it never shrinks because you mastered something mid-quiz. While enforcement is pending, the planner prioritizes this session’s work over review debt and a separate focus: "learn" topic. The topic resumes once the gate passes.

Installing the git hook

This optional hook needs a POSIX shell, jq, and the sqlite3 command-line tool. On macOS, install the extra tools with brew install jq sqlite; on Debian or Ubuntu, use sudo apt-get install -y jq sqlite3.

After the standard eklavya install, run this from the repository to gate:

sh "${EKLAVYA_HOME:-$HOME/.eklavya}/runtime/node_modules/eklavya/dist/plugin/scripts/install-git-hook.sh"

If you work from a source checkout, use its scripts/install-git-hook.sh instead. You can pass a repository path as the final argument. The installer preserves an existing pre-commit hook as pre-commit.local and runs it first. Running the installer again updates an older Eklavya hook.

Worktrees and existing hook managers

Linked worktrees share the main repository’s hooks directory. Installing once covers those worktrees and uses the main checkout’s project settings. A commit in a worktree is held by the latest gate saved for either the worktree or its main checkout, so a session started in the main checkout still gates the worktree it builds in.

If core.hooksPath is set, the installer exits with code 2 and prints the line to add to your hook manager’s pre-commit file. It does not install an unused hook in the standard location. Follow that output for Husky, Lefthook, or another hook manager.

The installed hook looks for Eklavya in the managed runtime first, then at the original install path. If both disappear, it warns and allows the commit.

To remove the hook and restore the previous one:

sh "${EKLAVYA_HOME:-$HOME/.eklavya}/runtime/node_modules/eklavya/dist/plugin/scripts/install-git-hook.sh" --uninstall

How to get through it

1. Check the gate

   Run /eklavya:gate in Claude Code to see the passing count and target. The blocked-commit message’s answered count includes wrong answers and skips.

2. Finish the quiz

   Run /eklavya:quiz. If you do not know an answer, ask for the explanation. Once the other candidates are exhausted, missed concepts can return at a lower tier with a different question.

3. Commit again

   When enough concepts have passed, retry the commit.

A clean decline without feedback is not retried. A decline that included an explanation can be offered again. To stop enforcement for this project:

eklavya config set quiz.enforced false --project

The safety rules

• Failures allow commits. Missing dependencies, an unavailable database, or unreadable configuration cause the gate to fail open. Run eklavya doctor if enforcement appears inactive.
• No gate row means no block. A session with no logged learning requirement has nothing to satisfy.
• The Claude hook has limits. It recognizes common shell forms of git commit and git merge --continue, but cannot see through Git aliases, command variables, or scripts that commit. Install the Git hook to cover those paths.
• This is a learning aid. Local hooks can be bypassed; the gate is not a security or team-policy boundary.