ai-agents-config-catalog
Catalog of every configuration axis in this repo, env vars, commit markers, frontmatter keys, QA skip verdicts, and escape hatches, each with its enforcement point and abuse story, plus the checklist for adding a new flag safely. Use when you say `what does a skip flag do`, `list escape hatches`, `can I skip this gate`, `add a config flag`. Do NOT use for hook runtime behavior (use `agent-harness-reference`) or change gating policy (use `ai-agents-change-control`).
rjmurillo · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rjmurillo/ai-agents --skill ai-agents-config-catalog技能说明
name: ai-agents-config-catalog
description: Catalog of every configuration axis in this repo, env vars, commit markers, frontmatter keys, QA skip verdicts, and escape hatches, each with its enforcement point and abuse story, plus the checklist for adding a new flag safely. Use when you say what does a skip flag do, list escape hatches, can I skip this gate, add a config flag. Do NOT use for hook runtime behavior (use agent-harness-reference) or change gating policy (use ai-agents-change-control).
version: 1.0.0
license: MIT
metadata:
routing:
role: conditional-adjunct
invoker: ai-agents-debugging-playbook
trigger: ai-agents-debugging-playbook points here for the full catalog of env vars, markers, and escape hatches
user-facing: false
AI Agents Config Catalog
Every flag, marker, and skip semantic in this repo, verified against code as of 2026-07-03. Hook registration surfaces were rechecked on 2026-09-01. Each escape hatch exists because a gate sometimes misfires; each one also has an abuse story or a guard. Before you set any of these, read its row. The house rule (learned in session 1187, see the Removed Flags section): escape hatches get teeth or get abused.
Related skills: ai-agents-change-control owns when a bypass is allowed; agent-harness-reference and ai-agents-architecture-contract own what the hooks themselves do; ai-agents-debugging-playbook owns triaging a gate that fired on you.
Triggers
what does the drift allowlist dolist escape hatchescan I skip this gateadd a config flagis this skip marker allowed
Process
- Identify the axis type: env var, commit marker, text directive, frontmatter key, file, or verdict string.
- Find its row in the tables below. Read the effect AND the guard/abuse column before using it.
- If you are about to use an escape hatch, confirm the legitimate trigger condition holds (for example, a workflow actually unrunnable under act). Bypassing because a gate is slow or annoying is the session 1187 failure mode.
- Re-verify the flag in its defining validator with the one-liner in Provenance. Documentation can drift after validator changes.
- Adding a new flag? Follow the checklist in "How to Add a New Flag" and add a row plus a re-verify one-liner to this catalog.
Environment Variables: LSP Gate (retired)
The LSP-first runtime gate and its three environment escapes (SKIP_LSP_GATE, LSP_GATE_MODE, LSP_DOWN) were retired in #3216 when ADR-062 was amended to keep LSP-first navigation as static steering only. No environment variable governs it now; the guidance lives in .claude/rules/lsp-first.md. Nothing to set, nothing to escape.
Git Hook Configuration
Lefthook is the sole Git hook manager. lefthook.yml declares the events,
filters, named jobs, and validator commands. Do not infer a bypass from a
deleted custom payload. Inspect the named validator's current interface before
using or documenting an environment variable.
Removed and Stale Flags (do not use, do not reintroduce)
| Name | Status as of 2026-07-03 | Story |
|---|---|---|
SKIP_PREPUSH | REMOVED | Historical: abused 3x within hours of creation (session 1187, retro .project-toolkit/retrospective/2026-02-08-session-1187-skip-prepush-abuse.md) |
SKIP_TESTS | REMOVED | Removed from the pre-push hook during the Lefthook migration, but it outlived that as the env default for pre_pr.py --skip-tests, which was parsed and never read; flag, env default, and the --verbose beside it were deleted once no gate set skip_flag |
Lesson encoded: a global bypass with no teeth (no telemetry, no approval step) will be reached for under pressure. New escape hatches must be narrow, announced in output, and observable.
Environment Variables: Tests and Tooling
| Name | Type | Effect | Status | Guard / abuse story | Where defined |
|---|---|---|---|---|---|
GIT_CONFIG_COUNT + GIT_CONFIG_KEY_0/GIT_CONFIG_VALUE_0 | env vars (set by conftest) | Test session injects commit.gpgsign=false with command-line precedence so test repos never invoke the user's signing setup | Production test infra | Only sets index 0 when GIT_CONFIG_COUNT is unset, so an outer process's config is not clobbered | tests/conftest.py:76-78 |
SERENA_PROJECT_ROOT | env var (user-set) | Formerly overrode automatic Serena project root detection in the worktree scope guard. Set to the absolute path of the intended worktree when switching projects | Retired hook (ADR-097) | Was validated: path had to contain .serena/project.yml or the override was ignored; blocked writes when unset and CLAUDE_PROJECT_DIR was absent. invoke_serena_worktree_scope_guard.py is deleted, so nothing reads this variable today | historical: .claude/hooks/PreToolUse/invoke_serena_worktree_scope_guard.py (path no longer exists) |
| PEP 668 / uv | environment reality | Bare pip fails (externally managed env). Everything goes through uv sync --frozen --extra dev; skill scripts need uv run python, not python3 (PyYAML lives in the venv) | Production | ModuleNotFoundError: No module named 'yaml' means you used the wrong interpreter | pyproject.toml, .python-version (3.14.6) |
pytest markers unit, integration, safe_push_transport, security, smoke, claude, copilot, codex, windows_path | pytest -m selectors | Filter test classes; smoke = real-CLI tests needing auth/credits or an installed CLI, run on pull requests by plugin-cli-smoke.yml, and the smoke gate asserts they were NOT skipped (issue #2231 item 4); safe_push_transport |