chore: v1.1.6 production blocker fix bundle (P0-1/3/4/6/9) (#200)

0xmariowu · web-flow · commit f788332588b4 · 2026-04-25T16:37:10.000Z
* feat(hooks): add husky pre-commit gate template (P0-3 S1)

Author-whitelist + secret scan + private-pattern scan + lint hook
that downstream user repos receive after 'agentlint setup'. Sources
_shared.sh fail_with_help helper. Closes the v0.9.0 absorb-VibeKit
gap where setup.sh expected templates/hooks/husky/ but the directory
never existed.

* feat(hooks): add husky pre-push gate template (P0-3 S2)

Sources _shared-push.sh (main-skip + rebase on origin/main) then runs
the project's test command (npm test for Node, pytest for Python).
Part of the husky hook generation closing P0-3.

* feat(hooks): add husky commit-msg conventional-commit gate (P0-3 S3)

Rejects commit messages whose first line does not match
^(feat|fix|refactor|test|docs|chore|ci|style|perf|build|revert)($.+$)?: .+
Uses _shared.sh fail_with_help helper. Part of P0-3 husky hook bundle.

* fix(setup): fail-closed hook copy + carry _shared helpers (P0-3 S4)

scripts/setup.sh hook copy loop now:
- counts copied hooks (copied=0 ... copied=$((copied+1)))
- dies hard if copied==0 with 'no husky hooks generated; refusing to
  set core.hooksPath' — prevents the audit-flagged failure mode where
  setup falsely claims hooks installed and disables existing .git/hooks
  via core.hooksPath redirect
- copies _shared.sh + _shared-push.sh helpers into user .husky/ so the
  generated hooks (which 'source "$(dirname "$0")/_shared.sh"')
  resolve their helper at runtime in the downstream repo
- only sets core.hooksPath=.husky when copied&gt;0

Closes P0-3 from docs/p0-production-blocker-scan-2026-04-25.md.

* test(setup): pin husky hook generation positive + negative path (P0-3 S5)

tests/test-husky-hooks.sh covers two cases:
- positive: bash setup.sh --lang ts --no-install &lt;tmp&gt; writes
  executable .husky/{pre-commit,pre-push,commit-msg} and sets
  core.hooksPath=.husky
- negative: when no husky hook templates are reachable, setup exits
  non-zero, leaves core.hooksPath unset, and creates no .husky files.

Pins the fail-closed behavior added in scripts/setup.sh (P0-3 S4)
and prevents the 'silent claim, empty .husky/' regression from
returning.

* docs(install): restore complete GitHub Action workflow with actions/checkout (P0-4 S1)

INSTALL.md GH Action snippet was reduced to a 4-line excerpt during
PR1's collapse, dropping the surrounding 'name', 'on', 'permissions',
and 'jobs' boilerplate plus the critical 'actions/checkout@v4' step.
Users copy-pasting the snippet ended up with a workflow that runs
AgentLint against an empty runner workspace.

Restores the full copy-paste workflow with checkout. Adds an inline
note that explains why checkout is required.

docs/content/intro.md already had the complete workflow (PR1 only
collapsed INSTALL.md), so no intro.md change is needed for S2.
The hygiene test added in S3 enforces both files keep checkout.

* test(registry): pin Action snippets carry actions/checkout (P0-4 S3)

Scans every yaml/yml fenced block in README.md, README_CN.md,
INSTALL.md, docs/content/intro.md. For any block that references
0xmariowu/AgentLint@&lt;ref&gt; or 0xmariowu/agent-lint@&lt;ref&gt;, asserts
the same block contains 'actions/checkout'.

Locks the F002/S1 fix in: future doc edits cannot drop checkout
from the canonical Action quickstart again.

registry-consistency suite: 96 -&gt; 97 tests.

* fix(install): replace failing 'agentlint check --help' verify command (P0-6 S1)

INSTALL.md Verify section told users to run 'agentlint check --help'
right after install. The command exits 1 with 'scanner produced no
output' because the help router does not handle 'check --help' as a
help request — it falls through to scanner.sh which expects scan
input on stdin and finds none.

Replaces with 'agentlint help', which prints the full CLI help and
exits 0. Smoke-tested via npm pack + isolated --prefix install.

Closes P0-6 first-use install verification failure.

* test(registry): pin INSTALL.md Verify uses working commands (P0-6 S2)

Locks in F003/S1 fix: INSTALL.md '## Verify' section must NOT contain
'agentlint check --help' (broken: scanner.sh blocks on stdin) AND
must contain 'agentlint --version' AND ('agentlint help' OR
'agentlint check --project-dir').

Future doc edits that reintroduce the broken verify command fail CI.

registry-consistency suite: 97 -&gt; 98 tests.

* docs: surface npm install -g side effects up front (P0-9 S1+S2)

INSTALL.md gains a '## Side effects' section right after the
'For AI coding agents' frontmatter, before '## Default'. States
plainly that 'npm install -g agentlint-ai' writes to ~/.claude/
and registers the /al plugin, and points at --ignore-scripts as
the opt-out path (also in Failure modes).

README.md install snippet gets an inline blockquote pointing at
INSTALL.md#side-effects so users see the disclosure without leaving
the canonical README path.

Closes P0-9 — restores the prominent opt-in notice that PR1's
install collapse dropped along with the --ignore-scripts narrative.

* test(registry): pin INSTALL Side effects + raise length cap to 100 (P0-9 S3)

New runTest 'INSTALL.md Side effects section is present and lists
~/.claude + --ignore-scripts' locks the F004/S1 admonition in:
INSTALL.md must contain '## Side effects' header + ~/.claude mention
+ --ignore-scripts mention.

Reconciles with two PR1-era tests that started failing once side-
effect disclosure was restored:

1. README/README_CN must NOT mention '--ignore-scripts' (stays clean
   of npm flag noise on the main install path). README inline note
   rewritten to point at INSTALL.md#side-effects without naming the
   flag literally.

2. INSTALL.md length cap was 80 lines (PR1.5 buffer). Today's P0
   work added 12 lines of GitHub Action workflow expansion (P0-4)
   plus 4 lines of Side effects section (P0-9). Cap raised to 100
   so legitimate future P0 fix additions don't force prose trimming
   gymnastics.

registry-consistency suite: 98 -&gt; 99 tests.

* test(e2b): assert husky hooks generated + core.hooksPath set in S04 (P0-3 / F005 S1)

setup-ts scenario verifier (run.sh inline Python) now checks:
- .husky/pre-commit / pre-push / commit-msg exist and are executable
- git config core.hooksPath == .husky

S04-setup-lang-ts specs.json expected.files_exist also lists the
husky paths for documentation; the live check happens in run.sh.

S05-setup-lang-python intentionally NOT changed: scripts/setup.sh
only walks the husky branch when LANG != python, so Python projects
do not produce .husky/. Asserting them there would always fail.

Closes the e2b coverage gap that let pre-PR5 scans pass S04 while
the .husky directory was empty (audit P0-3).

Plan F005/S1 verify command (which only checked S04) updated by
this commit's behavior; specs.json still references hook paths so
the verify python -c S04 grep continues to pass.

* fix(e2b): accept husky 9+ .husky/_ as valid core.hooksPath value

Husky 9 set core.hooksPath to .husky/_ (internal forwarder) instead
of .husky directly; user-facing hooks at .husky/&lt;name&gt; are still
invoked via the forwarder. First v116-p0-revalidate run flagged S04
PARTIAL on this strict equality.

Relax the check to accept either '.husky' or '.husky/_'. Both are
correct husky configurations; rejecting one or the other is a tooling
implementation detail, not a setup failure.

Confirmed: v116-p0-revalidate2 now 21/21 PASS (Pass rate 100.0%).

* chore: bump version to 1.1.6

Bump 5 version sources via scripts/bump-version.sh:
- package.json
- .claude-plugin/plugin.json
- .claude-plugin/marketplace.json
- release-metadata.json (regenerated, 58 checks / 6 core dimensions)
- README badge + intro check counts (regenerated)

Plus CHANGELOG.md v1.1.6 entry naming the 5 P0 fixes from
docs/p0-production-blocker-scan-2026-04-25.md (P0-1 bump itself,
P0-3 husky hooks, P0-4 INSTALL Action checkout, P0-6 verify
command, P0-9 side-effects disclosure) and the 4 deferred P0
items (P0-2 / P0-5 / P0-7 / P0-8) tracked for v1.1.7+.

Pre-tag verify gate green:
- npm test: 11 suites, 99/99 in registry-consistency
- npm run lint:shell: clean
- bash scripts/sanitize.sh: 2 warnings (non-fail, history-related)
- npm pack --json --dry-run: version 1.1.6
- npm publish --dry-run: + agentlint-ai@1.1.6 (canonical success line)
- e2b 21/21 PASS (run-id v116-p0-revalidate2, 68s)
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Check how well your repo supports AI coding agents.",
-    "version": "1.1.5"
+    "version": "1.1.6"
   },
   "plugins": [
     {
       "name": "agent-lint",
       "source": "./",
       "description": "Check how well your repo supports AI coding agents.",
-      "version": "1.1.5",
+      "version": "1.1.6",
       "author": {
         "name": "0xmariowu"
       },
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-lint",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Check how well your repo supports AI coding agents.",
   "author": {
     "name": "0xmariowu"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+## v1.1.6 (2026-04-26)
+
+Production blocker fix bundle — 5 of 9 P0 items from `docs/p0-production-blocker-scan-2026-04-25.md` plus the version bump itself. Closes the gaps that broke the canonical install + setup paths after the PR1–PR5 hygiene cleanup.
+
+### You can now…
+
+- **Trust `agentlint setup` actually installs husky hooks** — `templates/hooks/husky/{pre-commit,pre-push,commit-msg}` now exist as real shell files. Setup fails loud (`die`) when zero hooks would be copied, instead of silently writing `core.hooksPath=.husky` with an empty `.husky/` directory. The audit found this had been broken since v0.9.0 absorbed VibeKit. (P0-3)
+- **Copy-paste the INSTALL.md GitHub Action snippet** and have it work — the snippet now includes `actions/checkout@v4`, surrounding `name`/`on`/`permissions`/`jobs` boilerplate, and an inline note explaining why checkout is required. (P0-4)
+- **Trust the INSTALL.md verify commands** — `agentlint check --help` (which exited 1 with "scanner produced no output") is replaced with `agentlint help`. Both `agentlint --version` and `agentlint help` now exit 0 on a fresh global install. (P0-6)
+- **See the `~/.claude/` side effect up front** — INSTALL.md now opens with a "Side effects" section and README links to it inline, instead of burying `--ignore-scripts` deep in failure modes. (P0-9)
+- **Run `agentlint check`, `fix`, and `setup` from `agentlint-ai@1.1.6`** — published from the bumped commit, with the `v1` moving major tag fast-forwarded by `release.yml`. (P0-1)
+
+### Tests added (regression pinning)
+
+- `INSTALL.md Verify section uses commands that actually exit 0`
+- `public docs GitHub Action snippets include actions/checkout`
+- `INSTALL.md Side effects section is present and lists ~/.claude + --ignore-scripts`
+- `tests/test-husky-hooks.sh` — positive + negative path on `setup --no-install`
+- `tests/e2b/scenarios/install/run.sh` setup-ts now asserts `.husky/{pre-commit,pre-push,commit-msg}` exist + executable + `core.hooksPath` is `.husky` (accepting husky-9 `.husky/_`)
+
+### Deferred (tracked for v1.1.7+)
+
+- **P0-2** remote `main` branch protection enforces declared required checks (GitHub UI/API config drift; decoupled from package release).
+- **P0-5** portable symlink resolver in `scripts/agentlint.sh` and `src/scanner.sh` (current `readlink -f` fallback chain breaks on environments without GNU `readlink`).
+- **P0-7** `node src/reporter.js` no-stdin TTY hang.
+- **P0-8** `/al` session-analyzer cross-attribution tightening.
+
 ## v1.1.5 (2026-04-25)
 
 Hardening release — 24 fixes from a second deep audit. Closes the
diff --git a/INSTALL.md b/INSTALL.md
@@ -2,6 +2,10 @@
 
 > **For AI coding agents**: this file is the canonical install reference. Read once, act. Decision tables, not narrative.
 
+## Side effects
+
+`npm install -g agentlint-ai` writes to `~/.claude/` and registers the `/al` Claude Code plugin. To install without these side effects, use `npm install -g --ignore-scripts agentlint-ai` (also covered in Failure modes for read-only `~/.claude` environments).
+
 ## Default
 
 ```bash
@@ -22,13 +26,30 @@ Success signal: `agentlint --version` prints a version string.
 
 ## GitHub Action
 
+Complete copy-paste workflow:
+
 ```yaml
-- uses: 0xmariowu/AgentLint@v1
-  with:
-    fail-below: 80
+name: AgentLint
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  agentlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: 0xmariowu/AgentLint@v1
+        with:
+          fail-below: 80
 ```
 
-`@v1` is a moving major-version tag. Pin to a specific release (e.g. `@v1.1.5`) if you need reproducibility.
+`@v1` is a moving major-version tag. Pin to a specific release (e.g. `@v1.1.5`) if you need reproducibility. The `actions/checkout@v4` step is required — without it, AgentLint scans an empty workspace.
 
 ## After install
 
@@ -44,7 +65,7 @@ In Claude Code, run `/al` for the interactive scan-fix-report flow.
 
 ```bash
 agentlint --version
-agentlint check --help
+agentlint help
 ```
 
 ## Uninstall
diff --git a/README.md b/README.md
@@ -30,6 +30,8 @@
 npm install -g agentlint-ai
 ```
 
+> Side effects: writes to `~/.claude/` and registers the `/al` Claude Code plugin. Opt-out path in [INSTALL.md](./INSTALL.md#side-effects).
+
 Then in any git repo:
 
 ```bash
diff --git a/docs/content/changelog.md b/docs/content/changelog.md
@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+## v1.1.6 (2026-04-26)
+
+Production blocker fix bundle — 5 of 9 P0 items from `docs/p0-production-blocker-scan-2026-04-25.md` plus the version bump itself. Closes the gaps that broke the canonical install + setup paths after the PR1–PR5 hygiene cleanup.
+
+### You can now…
+
+- **Trust `agentlint setup` actually installs husky hooks** — `templates/hooks/husky/{pre-commit,pre-push,commit-msg}` now exist as real shell files. Setup fails loud (`die`) when zero hooks would be copied, instead of silently writing `core.hooksPath=.husky` with an empty `.husky/` directory. The audit found this had been broken since v0.9.0 absorbed VibeKit. (P0-3)
+- **Copy-paste the INSTALL.md GitHub Action snippet** and have it work — the snippet now includes `actions/checkout@v4`, surrounding `name`/`on`/`permissions`/`jobs` boilerplate, and an inline note explaining why checkout is required. (P0-4)
+- **Trust the INSTALL.md verify commands** — `agentlint check --help` (which exited 1 with "scanner produced no output") is replaced with `agentlint help`. Both `agentlint --version` and `agentlint help` now exit 0 on a fresh global install. (P0-6)
+- **See the `~/.claude/` side effect up front** — INSTALL.md now opens with a "Side effects" section and README links to it inline, instead of burying `--ignore-scripts` deep in failure modes. (P0-9)
+- **Run `agentlint check`, `fix`, and `setup` from `agentlint-ai@1.1.6`** — published from the bumped commit, with the `v1` moving major tag fast-forwarded by `release.yml`. (P0-1)
+
+### Tests added (regression pinning)
+
+- `INSTALL.md Verify section uses commands that actually exit 0`
+- `public docs GitHub Action snippets include actions/checkout`
+- `INSTALL.md Side effects section is present and lists ~/.claude + --ignore-scripts`
+- `tests/test-husky-hooks.sh` — positive + negative path on `setup --no-install`
+- `tests/e2b/scenarios/install/run.sh` setup-ts now asserts `.husky/{pre-commit,pre-push,commit-msg}` exist + executable + `core.hooksPath` is `.husky` (accepting husky-9 `.husky/_`)
+
+### Deferred (tracked for v1.1.7+)
+
+- **P0-2** remote `main` branch protection enforces declared required checks (GitHub UI/API config drift; decoupled from package release).
+- **P0-5** portable symlink resolver in `scripts/agentlint.sh` and `src/scanner.sh` (current `readlink -f` fallback chain breaks on environments without GNU `readlink`).
+- **P0-7** `node src/reporter.js` no-stdin TTY hang.
+- **P0-8** `/al` session-analyzer cross-attribution tightening.
+
 ## v1.1.5 (2026-04-25)
 
 Hardening release — 24 fixes from a second deep audit. Closes the
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "agentlint-ai",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Setup, check, and fix your repo for AI-native development.",
   "license": "MIT",
   "repository": {
diff --git a/release-metadata.json b/release-metadata.json
@@ -1,5 +1,5 @@
 {
-  "version": "1.1.5",
+  "version": "1.1.6",
   "check_count": 58,
   "dimensions": [
     {
diff --git a/scripts/setup.sh b/scripts/setup.sh
@@ -634,13 +634,24 @@ if [[ "$LANG" != "python" ]]; then
   chmod +x "$PROJECT/scripts/committer"
 
   # Husky hooks
+  copied=0
   safe_mkdir "$PROJECT/.husky"
   for hook in "$TEMPLATE_DIR/hooks/husky/"*; do
     [ -f "$hook" ] || continue
     hook_name="$(basename "$hook")"
     copy_template "$hook" "$PROJECT/.husky/$hook_name" ".husky/$hook_name"
     chmod +x "$PROJECT/.husky/$hook_name"
+    copied=$((copied+1))
   done
+  for helper in "$TEMPLATE_DIR/hooks/_shared.sh" "$TEMPLATE_DIR/hooks/_shared-push.sh"; do
+    [ -f "$helper" ] || continue
+    helper_name="$(basename "$helper")"
+    copy_template "$helper" "$PROJECT/.husky/$helper_name" ".husky/$helper_name"
+    chmod +x "$PROJECT/.husky/$helper_name"
+  done
+  if [[ "$copied" -eq 0 ]]; then
+    die "no husky hooks generated; refusing to set core.hooksPath. check templates/hooks/husky/ exists and has files"
+  fi
 
   # Commitlint config — use .cjs if project has "type": "module"
   if python3 -c "import json,sys; sys.exit(0 if json.load(open('$PROJECT/package.json')).get('type')=='module' else 1)" 2>/dev/null; then
@@ -785,12 +796,12 @@ if [[ "$LANG" == "python" ]]; then
   info "Python: commit-gate via pre-commit (no husky / no npm)"
 elif [[ "$LANG" == "node" ]] && [[ ! -f package.json ]]; then
   # Node projects without package.json: use git config directly
-  git config core.hooksPath .husky
+  [[ $copied -gt 0 ]] && git config core.hooksPath .husky
   info "hooks activated via core.hooksPath (no npm)"
 elif [[ "$NO_INSTALL" == true ]]; then
   # User asked us not to touch their install state. Wire husky via
   # git config so hooks still fire once they run `$PKG_MANAGER install`.
-  git config core.hooksPath .husky
+  [[ $copied -gt 0 ]] && git config core.hooksPath .husky
   info "hooks activated via core.hooksPath (--no-install; run '$PKG_MANAGER install' to complete setup)"
 else
   # Run the detected PM's install. Modern monorepo PMs (pnpm / bun / yarn
@@ -800,15 +811,15 @@ else
   if command -v "$PKG_MANAGER" >/dev/null 2>&1; then
     if ! pm_install; then
       warn "$PKG_MANAGER install failed — wiring husky via git core.hooksPath as fallback"
-      git config core.hooksPath .husky
+      [[ $copied -gt 0 ]] && git config core.hooksPath .husky
     fi
   else
     warn "$PKG_MANAGER not on PATH — wiring husky via git core.hooksPath (install $PKG_MANAGER later to enable lint-staged / commitlint)"
-    git config core.hooksPath .husky
+    [[ $copied -gt 0 ]] && git config core.hooksPath .husky
   fi
   npx --no -- husky 2>/dev/null || true
   # Fallback: if husky didn't set hooksPath, set it directly
-  if ! git config core.hooksPath >/dev/null 2>&1; then
+  if [[ $copied -gt 0 ]] && ! git config core.hooksPath >/dev/null 2>&1; then
     git config core.hooksPath .husky
   fi
   info "husky activated"
diff --git a/templates/hooks/husky/commit-msg b/templates/hooks/husky/commit-msg
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/_shared.sh" ]]; then
+  source "$SCRIPT_DIR/_shared.sh"
+elif [[ -f "$SCRIPT_DIR/../_shared.sh" ]]; then
+  source "$SCRIPT_DIR/../_shared.sh"
+else
+  echo "error: _shared.sh is required by commit-msg template" >&2
+  exit 1
+fi
+
+MSG_FILE="${1:-}"
+[[ -n "$MSG_FILE" && -f "$MSG_FILE" ]] || fail_with_help \
+  "commit message file missing" \
+  "git hook contract requires file arg" \
+  "Re-run commit normally so Git passes the message file path."
+
+MSG="$(sed -n '1p' "$MSG_FILE" | tr -d '\r')"
+if [[ ! "$MSG" =~ ^(feat|fix|refactor|test|docs|chore|ci|style|perf|build|revert)(\(.+\))?:\ .+ ]]; then
+  fail_with_help \
+    "commit message is not in conventional format" \
+    "conventional commit format" \
+    "Use <type>(<scope>): description, e.g. feat(ui): add loading state"
+fi
diff --git a/templates/hooks/husky/pre-commit b/templates/hooks/husky/pre-commit
@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/_shared.sh" ]]; then
+  source "$SCRIPT_DIR/_shared.sh"
+elif [[ -f "$SCRIPT_DIR/../_shared.sh" ]]; then
+  source "$SCRIPT_DIR/../_shared.sh"
+else
+  echo "error: _shared.sh is required by hook templates" >&2
+  exit 1
+fi
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+AUTHOR_EMAIL="$(git config user.email 2>/dev/null || true)"
+
+if [[ -z "$AUTHOR_EMAIL" ]]; then
+  fail_with_help \
+    "git author email is missing" \
+    "author-whitelist gate" \
+    "Set git config user.email before committing."
+fi
+
+# Placeholder allowlist. Replace these with repo-approved author emails, or
+# configure multiple values with:
+#   git config --add hooks.allowedAuthorEmail you@example.com
+AUTHOR_EMAIL_ALLOWLIST=(
+  "you@example.com"
+  "teammate@example.com"
+)
+
+while IFS= read -r allowed; do
+  [[ -n "$allowed" ]] && AUTHOR_EMAIL_ALLOWLIST+=("$allowed")
+done < <(git config --get-all hooks.allowedAuthorEmail 2>/dev/null || true)
+
+author_allowed=false
+for allowed in "${AUTHOR_EMAIL_ALLOWLIST[@]}"; do
+  if [[ "$AUTHOR_EMAIL" == "$allowed" ]]; then
+    author_allowed=true
+    break
+  fi
+done
+
+if [[ "$author_allowed" != true ]]; then
+  fail_with_help \
+    "author email is not whitelisted" \
+    "author-whitelist gate" \
+    "Add $AUTHOR_EMAIL to hooks.allowedAuthorEmail or edit .husky/pre-commit."
+fi
+
+STAGED_FILES=()
+while IFS= read -r -d '' file; do
+  STAGED_FILES+=("$file")
+done < <(git diff --cached --name-only -z --diff-filter=ACM)
+
+if [[ ${#STAGED_FILES[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+SCAN_FILES=()
+for file in "${STAGED_FILES[@]}"; do
+  case "$file" in
+    .gitleaks.toml|.husky/*|scripts/sanitize.sh|*'.md' ) continue ;;
+    *) SCAN_FILES+=("$file") ;;
+  esac
+done
+
+if [[ -x "$PROJECT_ROOT/scripts/sanitize.sh" ]]; then
+  if ! (cd "$PROJECT_ROOT" && bash scripts/sanitize.sh); then
+    fail_with_help \
+      "private-pattern scan failed" \
+      "codename / private-pattern scan" \
+      "Resolve private pattern matches before committing."
+  fi
+else
+  # No repository sanitize script found; skipping codename/private-pattern scan.
+  :
+fi
+
+if [[ ${#SCAN_FILES[@]} -gt 0 ]]; then
+  if command -v gitleaks >/dev/null 2>&1; then
+    if ! (cd "$PROJECT_ROOT" && gitleaks protect --staged --verbose); then
+      fail_with_help \
+        "potential secret detected in staged content" \
+        "secret scan (gitleaks)" \
+        "Remove leaked values from staged files, then amend and retry."
+    fi
+  else
+    SECRET_PATTERNS='(AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|-----BEGIN (RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----)'
+    if git diff --cached --no-ext-diff --unified=0 -- "${SCAN_FILES[@]}" \
+      | grep -E '^\+' \
+      | grep -vE '^\+\+\+' \
+      | grep -Eq "$SECRET_PATTERNS"; then
+      fail_with_help \
+        "potential secret detected in staged content" \
+        "secret scan (built-in patterns)" \
+        "Remove leaked AWS, GitHub, or private key material before committing."
+    fi
+  fi
+fi
+
+if [[ -f "$PROJECT_ROOT/package.json" ]] && command -v node >/dev/null 2>&1 && \
+   node -e "const fs=require('fs'); const d=JSON.parse(fs.readFileSync(process.argv[1],'utf8')); process.exit(d.scripts&&d.scripts.lint?0:1)" \
+   "$PROJECT_ROOT/package.json"; then
+  if ! (cd "$PROJECT_ROOT" && npm run lint); then
+    fail_with_help \
+      "npm run lint failed" \
+      "repo lint gate" \
+      "Fix lint errors and rerun commit."
+  fi
+fi
diff --git a/templates/hooks/husky/pre-push b/templates/hooks/husky/pre-push
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/_shared-push.sh" ]]; then
+  source "$SCRIPT_DIR/_shared-push.sh"
+elif [[ -f "$SCRIPT_DIR/../_shared-push.sh" ]]; then
+  source "$SCRIPT_DIR/../_shared-push.sh"
+else
+  echo "error: _shared-push.sh is required by pre-push template" >&2
+  exit 1
+fi
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+
+if [[ -f "$PROJECT_ROOT/package.json" ]] && \
+   node -e "const fs=require('fs'); const d=JSON.parse(fs.readFileSync(process.argv[1],'utf8')); process.exit(d.scripts&&d.scripts.test?0:1)" \
+   "$PROJECT_ROOT/package.json"; then
+  (cd "$PROJECT_ROOT" && npm test)
+  exit 0
+fi
+
+if [[ -f "$PROJECT_ROOT/pyproject.toml" || -f "$PROJECT_ROOT/requirements.txt" || -f "$PROJECT_ROOT/setup.py" ]]; then
+  (cd "$PROJECT_ROOT" && pytest)
+  exit 0
+fi
+
+echo "no test command"
diff --git a/tests/e2b/scenarios/install/run.sh b/tests/e2b/scenarios/install/run.sh
diff --git a/tests/e2b/scenarios/install/specs.json b/tests/e2b/scenarios/install/specs.json
diff --git a/tests/test-husky-hooks.sh b/tests/test-husky-hooks.sh
diff --git a/tests/test-registry-consistency.js b/tests/test-registry-consistency.js

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "agent-lint",`
`3`		`- "version": "1.1.5",`
	`3`	`+ "version": "1.1.6",`
`4`	`4`	`"description": "Check how well your repo supports AI coding agents.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "0xmariowu"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "agentlint-ai",`
`3`		`- "version": "1.1.5",`
	`3`	`+ "version": "1.1.6",`
`4`	`4`	`"description": "Setup, check, and fix your repo for AI-native development.",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "version": "1.1.5",`
	`2`	`+ "version": "1.1.6",`
`3`	`3`	`"check_count": 58,`
`4`	`4`	`"dimensions": [`
`5`	`5`	`{`