git:20260923.d2d9db0 to git:20260924.fa28c43

- **This directory is not the `eklavya` binary.** That is `mcp/src/cli.ts`,

- published as `dist/cli.js` and the package's only `bin`. `cli/` holds exactly one

- file: `eklavya-gate`, the POSIX commit-gate script. The name invites the

- confusion, so check which one a request means before you edit anything —

- `eklavya config`, `eklavya doctor`, `eklavya dashboard` and `eklavya install` all

- live in `mcp/src/cli.ts`.

-

- It is a shell script and not Node on purpose: it runs as a git `pre-commit` hook

- on every commit, and a git hook must not pay Node's startup cost. Keep it POSIX

- `sh` — the installed hook execs it with `#!/bin/sh`, and `mcp/test/gate.test.ts`

- drives it through `/bin/sh`.

-

- ## It is opt-in, twice over

-

- Nothing in `eklavya install` puts this on a repo. `scripts/install-git-hook.sh`

- does, as a separate step the user runs per repo; it writes `pre-commit` in the

- **common** git directory's `hooks/` (so a linked worktree gets the main

- checkout's hook, which is the one git runs), between the `# >>> eklavya gate >>>`

- markers, and if a `pre-commit` already existed it moves it to `pre-commit.local`

- and chains it first. `--uninstall` restores it. Re-running it rewrites an older

- Eklavya hook in place. With `core.hooksPath` set (husky, lefthook) it installs

- nothing, prints the line to add to the manager's hook, and exits 2.

-

- The installed hook does not `exec` this file at a fixed path any more. It runs

- the first that exists of `~/.eklavya/runtime/node_modules/eklavya/dist/plugin/cli/eklavya-gate`

- (honouring `EKLAVYA_RUNTIME` and `EKLAVYA_HOME`) and the path the installer ran

- from, with `sh` so a lost executable bit cannot block. If neither exists the

- commit goes through with one stderr line. The old fixed-path `exec` meant a

- plugin update that moved the directory made every commit fail — the one failure

- this gate must never have. `eklavya uninstall` warns about the hook and prints

- the command to remove it; it never deletes it.

- Then the script itself only acts on a project whose config sets `quiz.enforced`

- (or the retired `"mode": "enforced"`, which it still reads). That config is at

- `~/.eklavya/projects/<slug>/config.json` — the script rebuilds the slug itself,

- in shell, from `git rev-parse --show-toplevel` folded to the main checkout via

- `--git-common-dir`, because a worktree shares its parent's settings. Note that it

- reads enforcement from **only** the project file — not `~/.eklavya/config.json` —

- so a globally set gate does not hold a bare terminal. The global file is read for

- one thing: a `quiz.enabled: false` (or `mode: off`) there, not overridden by the

- project, releases the gate, exactly as `coerce()` does — otherwise a terminal

- commit is held by a gate no quiz will ever run to clear. The slug path is built

- with `pwd -P` so a checkout reached through a symlink still finds its file.

- It reads `<repo>/.eklavya.json` as a fallback and does **not** migrate it. The

- node half moves that file out automatically; a git pre-commit hook is the wrong

- place to start rewriting somebody's working tree, so it reads the old location

- and lets the next ordinary session do the move. Any doc claiming a terminal commit is gated has to attach the installer

- step and the repo config; `web/src/content/docs/docs/commit-gate.mdx` and

- `skills/setup/SKILL.md` are where that lives.

- ## It fails open, always

- A learning tool that bricks commits gets uninstalled, and an unpassable gate

- teaches nothing. Every one of these exits 0:

- - not inside a git repo, or `git rev-parse` fails;

- - no config for this project, at either the current or the legacy location;

- - `jq` not on PATH (warns on stderr) — **or** `sqlite3` not on PATH (warns too).

- It needs both, not just `jq`;

- - the config does not ask for enforcement — `quiz.enforced` false or absent with

- no `mode: enforced` behind it, or `quiz.enabled` false — in the project file,

- or in the global one when the project does not say;

- - the database file does not exist;

- - the `sqlite3` query errors, or returns no gate row for this repo.

- Exit 1 happens on exactly one condition: a gate row for this repo whose `passed`

- is not `1`. Adding a new failure mode means adding a new `exit 0` path.

- ## It reads the database directly

- There is no server in a git hook, so the script talks to `knowledge.db` in raw

- SQL and duplicates things it cannot import. Keep it in step with:

- - the `gates` table shape — it selects `passed, required, answered` and picks the

- repo's most recent row by `updated_at`. `syncGate` in `mcp/src/store.ts` is the

- only writer; a renamed or added column lands here in the same commit.

- - `DEFAULT_CONFIG.quiz` in `mcp/src/config.ts` — the script defaults a config

- with neither `quiz` nor `mode` to unenforced.

- - `projectSlug` in `mcp/src/paths.ts` — the script rebuilds it with

- `tr '/\\:' '-'`, and `test/gate.test.ts` runs both parsers over one set of

- configs so the two cannot drift apart silently.

- - the `mode` → `quiz` alias in `normalizeLegacyKeys`, and the rule that

- `quiz.enabled: false` forces `enforced` off. Both are duplicated here in jq,

- spelled out with `if`/`elif` rather than `//`: jq's `//` is an alternative

- operator, so `.quiz.enforced // (.mode == "enforced")` reads an explicit

- `false` as unset and falls back to a stale `mode` in the same file — a gate

- that keeps holding commits after somebody switched it off.

- `test/gate.test.ts` runs both parsers over the same five configs.

- The pass/fail arithmetic itself (`PASSING_GRADE`, `pass_threshold`,

- `ceil(required * pass_threshold)`) is **not** duplicated here — the script trusts

- the persisted `passed` column. Keep it that way: a change to the gate's rule

- belongs in `syncGate` alone. What is duplicated is the lookup key, and it differs

- from the in-session hook on purpose: `mcp/src/hooks/pre-tool-gate.ts` looks the

- gate up by `session_id`, this script by `repo`, because a terminal commit has no

- session.

- ## Tests

- `mcp/test/gate.test.ts` runs the real script and the real installer against a

- temp repo, and ends with an actual `git commit`. From `mcp/`:

- ```sh

- npm test -- gate

- ```

- `pretest` builds `dist/`, which `pre-tool-gate.js` in the same file needs.