[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6JGDGEMV6D9Y9GF6F1T77GT":3,"skill-same:01M6JGDGEMV6D9Y9GF6F1T77GT":99},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":6,"ownerHtmlUrl":58,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":59,"install":60,"resources":73},"01M6JGDGEMV6D9Y9GF6F1T77GT","quality-gate",null,"When a change owes an e2e test, and the gates that enforce it — pre-push e2e+smoke to master plus the ->review, ->merge and ->done gates. Use when changing the CLI, a shell script, the install flow or any installed hook, and when handing over, merging or closing a card.","muratovv\u002Fai-hats","muratovv","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F7502801?v=4","01M6JGCBN4KEJX012GPJVSH04T","Fedor Muratov","01M6JGCBSNMN7CW3RGTPPE0MN2",3,"MIT","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"quality gate","gate","quality","use","closing","card","gates","enforce","done","e2e test","hooks","smoke","review","shell","e2e","push","merge","change","test","cli","2026-11-10 10:12:30",false,"---\nname: quality-gate\ndescription: >-\n  When a change owes an e2e test, and the gates that enforce it — pre-push\n  e2e+smoke to master plus the ->review, ->merge and ->done gates. Use\n  when changing the CLI, a shell script, the install flow or any installed\n  hook, and when handing over, merging or closing a card.\nai_hats:\n  # hook-carrier skill. `ai-hats self init` installs one\n  # dispatcher per event in `.githooks\u002F`; the script below is resolved from this\n  # directory and run in place at push time (nothing is copied).\n  # Hard gate: no env-var bypass; `git push --no-verify` is the only escape.\n  git_hooks:\n    pre-push:\n      - git_hooks\u002Fpre-push-e2e-master.sh\nlicense: MIT\n---\n\n# quality-gate\n\n**This directory is machinery, not prose.** It carries the gates that guard the\nai-hats codebase — one thin script per edge in `hooks\u002F`, and the git one in\n`git_hooks\u002F` — and the role binds each by path (`ai-hats-dev\u002Froles\u002Fmaintainer\u002Fconfig.yaml`).\nDelete it and the gates stop being installed.\n\n**A gate is a few lines: the stages it requires, and a call into `lib\u002Fgate.sh`.**\n`hooks\u002Fdone-gate.sh --stages` prints the list. How a stage runs, and how a marker\nis earned for it, is the project's `scripts\u002Fgates.sh` — the gate only hands the\nlist over. Nothing here runs a stage itself (ADR-0023 D6\u002FD7).\n\n| gate          | where it fires           | who is at the refusal | asks                            |\n| ------------- | ------------------------ | --------------------- | ------------------------------- |\n| `review-gate` | every road into `review` | the agent, alone      | is this work fit for a reviewer |\n| `merge-gate`  | `wt:pre-merge`           | the agent, alone      | is this branch fit for master   |\n| `done-gate`   | every road into `done`   | the supervisor        | is master green after this card |\n| `push-gate`   | `git push` to master     | a human               | is the pushed tree green        |\n\nBelow the gates sits the policy they enforce: **which changes owe an e2e test at\nall.** That half was a standing rule until it folded in here — one home for\nthe question and the machine that asks it.\n\n## When an e2e test is mandatory\n\nA task may not reach `done` if it changed any of the trigger surface below\nwithout adding at least one e2e test under `tests\u002Fe2e\u002F` that exercises the real\ncommand chain.\n\n**The invariant:** the gate fires on any change to code that runs *outside* the\nPython process — an entry point, a shell script, the install\u002Fvenv flow, or any\nscript the assembler installs as a hook. That is where the contract lives at a\nsubprocess boundary the unit suite cannot observe. The list below names the\ncurrent surfaces; a path that is not on it but crosses the same boundary fires\nthe gate all the same.\n\n- `src\u002Fai_hats\u002Fcli\u002F**\u002F*.py` — click commands, command nesting, CLI args\u002Fflags.\n- `scripts\u002F*.sh` — shell scripts (`install-launcher.sh`, `bootstrap.sh`, …).\n- `src\u002Fai_hats\u002F_bootstrap.py`, `src\u002Fai_hats\u002Fcli\u002Fmaintenance.py` — pip install \u002F launcher \u002F venv flow.\n- `[project.scripts]` in any workspace `packages\u002F*\u002Fpyproject.toml` — new or\n  renamed entry points (the root `pyproject.toml` declares none).\n- `packages\u002Fai-hats-library\u002F**\u002Fhooks\u002F**` and `**\u002Fgit_hooks\u002F**` — PreToolUse \u002F\n  PostToolUse hook scripts and the installed git hooks (`git_hooks` is a\n  distinct segment: a `**\u002Fhooks\u002F**` glob does not match it). Highest blast\n  radius in the repo: a hook gates *every* tool call of *every* role composing\n  it, so a four-line change can disable every agent. The test must drive the\n  **composed chain** (all hooks on the matcher, in order) via\n  `tests\u002Fe2e\u002F_helpers\u002Fhook_chain.py`, never one script in isolation — a\n  single-hook test cannot observe a second hook overriding its verdict, which is\n  how a blanket deny once shipped past a green suite.\n- Anything else crossing an external contract: PEP 508 URL forms, click nesting,\n  shell quoting, venv invocation.\n\n**Does not fire:** internal Python modules (storage, parsing, business logic),\ndocs, tests-only changes, version bumps.\n\n### What counts as an e2e test\n\nAll of these must hold:\n\n- Lives under `tests\u002Fe2e\u002F` (the dedicated real-subprocess CLI layer — see `tests\u002FREADME.md`).\n- Marked `@pytest.mark.integration`.\n- Spawns a **real** subprocess chain: real `bash`, real `pip install`, real\n  `ai-hats` binary. No `MagicMock`, no `monkeypatch` on `subprocess.Popen`, no\n  `CliRunner.invoke()`.\n- Asserts observable end-to-end side effects (exit codes, files on disk,\n  captured output) — not internal call counts.\n\nIn-process `CliRunner` tests do **not** satisfy this, regardless of marker.\nNeither do pipeline-integration tests.\n\n### Plan and review\n\nThe plan names the test by path and by what it asserts — \"will add e2e coverage\"\nis not a name. The reviewer runs it, and checks the one thing a green run cannot\nshow: that it **fails when the change is reverted**. If it does not, it lives\nbeside the change rather than exercising it, and the card returns to `execute`.\n\nOrigin: PROP-031 — two production bugs shipped past `done` because the unit\nsuite stubbed the very contracts the change broke.\n\n## Passing a gate\n\n1. **Transition.** `rack transition \u003CID> review` \u002F `done`, or `ai-hats wt\n   merge`. Run nothing first: the gate reads markers inside the lock and, when\n   they are missing, refuses with the command that earns them.\n2. **Refused?** The refusal ends with that command — run it:\n\n       Missing:\n           \u003Cstage>\n           \u003Cstage>\n\n       Run the gate on that exact content, then retry:\n\n           cd \u003Cworktree> && make done-gate\n\n   (`make done-gate REV=\u003Csha>` for a card already merged; the stages a gate\n   requires are `\u003Cgate>.sh --stages`, never a list in this file.) It runs only the\n   stages the tree has not earned, in order, stops at the first red, and\n   stamps each green one.\n\n   **A stage the gate does not declare** — `e2e-rack`, say, absent from\n   `\u003Cgate>.sh --stages` — is a **zone**: an area of the codebase and the tests\n   that assert it. The gates BEFORE the merge (`review`, `merge`) require what\n   they declare PLUS the zones your diff touches, so the set depends on what you\n   changed and cannot be declared in advance; `->done` never asks for them, so\n   you pay for your zone once — `\u003Cgate>.sh --zones` says which gate asks.\n   `bash scripts\u002Fgates.sh touched` prints what your change adds and\n   `bash scripts\u002Fgates.sh zones` the whole table; `make \u003Cgate>` earns them like\n   any other stage. Nothing is wrong with the gate — read it as the tests your\n   own area owns, asked for where you can still fix them alone.\n3. **Green** — the run's first line is `RESULT …, green`. Its last says what\n   the transition after this one will additionally demand, so you can earn it\n   now instead of being refused for it later:\n\n       [gates] next: done-gate also needs \u003Cstage>, \u003Cstage>\n\n   `next: nothing` means no gate on the road is short of anything. Transition.\n4. **Red** — the run's block, verdict first:\n\n       [gates] RESULT tree 5f225a1b (2ac163eb): 11 cached, 1 ran, FAILED unit (rc=1)\n       [gates] fix unit, then: make done-gate\n       [gates] re-run just these:\n           \u002Fpath\u002Fto\u002Frepo\u002F.venv\u002Fbin\u002Fpython -m pytest tests\u002Ftest_x.py::test_y\n       [gates] unit said:\n       tests\u002Ftest_x.py:12: AssertionError: …\n       1 failed, 6024 passed, 2 skipped in 40.1s\n       [gates] lint: 1203 files already formatted\n       …\n       [gates] cached (11): e2e-catalog …\n       [gates] 2ac163eb (tree 5f225a1b) in place: \u003Cworktree>\n       [gates] transcript: \u002Ftmp\u002Fgates-run.Xy12ab\n\n   In order of importance: the verdict, what to do, what the red stage said\n   (a failing test per line, or a finding per line),\n   one line per green stage, the cached ones, the subject, and the dir holding\n   every stage's full output.\n\n   **`fix \u003Cstage>` assumes the failure is yours, and the gate cannot tell.** When\n   the red is in something this change did not touch, attribute before you fix or\n   ask for anything: skill **red-attribution**. Cheapest first — a stale base is a\n   more common cause than a broken master.\n\n   Triage the red stage:\n\n   - a red pytest stage hands you the narrow command already — paste the\n     `re-run just these` line. Do not rebuild it: the interpreter in it is the\n     one this checkout answers for, and another imports someone else's sources;\n   - the stage alone, bare, exactly what CI runs: `bash scripts\u002Fgates.sh unit`\n     (`bash scripts\u002Fgates.sh list` says what each stage checks);\n   - a checker: the tool itself, `ruff check \u003Cpath>` or\n     `python scripts\u002Fcheck_\u003Cname>.py`;\n   - fix, commit, `make \u003Cgate>` again. A fix is a new tree, and a new tree\n     earns every stamp afresh: the checkers take seconds, `unit` about a\n     minute — do not reach for `--fresh` or a narrower gate to save it.\n\n   **`the desk is dirty`, under the verdict?** A run with uncommitted changes\n   happens in a scratch checkout of the commit, so it judges what is COMMITTED\n   — a red one against a fix that was never there, a green one vouching for a\n   fix that never ran. Commit, then run again.\n5. **Touched what the gate does not name?** No card gate runs the whole tier\n   under one name: `->merge` asks for the zones your diff touches, `->done` for\n   the half no zone claims (`done-gate.sh --stages`), and never for your zones\n   again. What that leaves out is a zone your change breaks WITHOUT\n   touching its prefix, and nothing refuses there. Run the tier yourself and say\n   so. It outlives a foreground call, so run it in the background through the\n   wrapper, which exits with the tier's own status:\n\n       timeout 1800 bash packages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fbin\u002Fruncheck.sh \\\n           --log \u002Ftmp\u002Fe2e.log -- bash scripts\u002Fgates.sh e2e\n\n   Report the number in `\u002Ftmp\u002Fe2e.log.rc`, never the completion notice: that\n   notice reports the whole command, so a hand-rolled `; echo $?` is what it\n   announces — two red tiers arrived as `exit code 0` that way. What a gate\n   requires of every tree:\n\n       bash packages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fhooks\u002Fdone-gate.sh --stages\n\n### What a stamp saves\n\nA marker names the TREE a stage ran on, per stage. It spares the re-run of an\nunchanged tree, never of a fixed one:\n\n- the transition after a green run — instant;\n- `make done-gate` after `make review-gate` — pays the difference, not twice;\n- a merge commit whose tree equals the branch tip — a fast-forward, or a\n  merge into a master that moved nothing else — `REV=\u003Cmerge sha>` finds every\n  stamp already there;\n- a stage marked green that you want to see run anyway:\n  `\u003Cgate>.sh --run --fresh` (no make target).\n\n### Where it runs, and what that costs\n\nThe subject is a commit — `HEAD`, or `REV=\u003Csha>`. The run happens in the\ncheckout only when it is clean and at that commit; otherwise in a one-shot\nscratch checkout of the commit under the shared git dir, with a venv of its\nown. Measured 2026-09-03 with a warm uv cache: +2.5 s on `lint`, +5 s on a\n35 s `unit`. A dirty desk therefore never taints a marker and never blocks\none, and `REV=` is not a cost worth working around.\n\nEither way the stages run under that checkout's `.venv`, and the gate leads\n`PATH` with it: a bare `python3` or `pytest` a test spawns is the same\ninterpreter. Nothing to activate or prefix in your shell first.\n\n## Pushing master\n\n    scripts\u002Frun-e2e-gate.sh    # out of band, BEFORE the push\n    git push origin master     # the hook then passes instantly\n\n## Status is printed, not documented\n\n**Do not come back to this file to find out what happened. Read what the gate\nsaid.** Every branch narrates itself with a reason and a remedy — the refusals,\nthe green, and every quiet pass-through alike. The one thing it never prints is\nthe transcript, which lands beside the card; glob it, never hand-build the name:\n\n    \u003Ctasks_dir>\u002F\u003CID>\u002F.checks\u002F*done-gate.sh*.log\n\n## Why the push gate runs out of band\n\nRunning the suite **inside** the pre-push hook cannot work. Git opens the SSH\nconnection for ref-advertisement *before* running the hook, then runs the hook,\nthen sends the pack. GitHub closes the idle connection after ~30s, so a hook\ntaking minutes dies with `Connection closed by remote host` → SIGPIPE (exit 141)\nand the pack is never sent.\n\n**Do not re-attempt:** client-side `ServerAliveInterval` at 60 **and** 15 did not\nfix it, and the 2022 community keepalive workaround no longer works (paid for twice).\n\n## No bypass\n\nThere is no `AI_HATS_E2E_SKIP`, no `--ack` and no knob. `git push --no-verify`\nand forging a marker are deliberate local acts by the trusted maintainer, never\nan accidental skip.\n\nMaster's own CI verdict is not a card's to pass or to wave through, so no card\ngate asks for it. The push road prints it before a push to master\n(`scripts\u002Fcheck_master_ci.py --notice`, never blocking: the push is how master\ngets fixed), and `bash scripts\u002Fgates.sh master-ci` asks by hand — green only on\na completed green run; a run still going or a verdict it cannot read is unknown,\nand unknown is not green. If a red is not yours, the move is a classification,\nnot a request for a flag: skill **red-attribution**.\n","# quality-gate\n\n**This directory is machinery, not prose.** It carries the gates that guard the\nai-hats codebase — one thin script per edge in `hooks\u002F`, and the git one in\n`git_hooks\u002F` — and the role binds each by path (`ai-hats-dev\u002Froles\u002Fmaintainer\u002Fconfig.yaml`).\nDelete it and the gates stop being installed.\n\n**A gate is a few lines: the stages it requires, and a call into `lib\u002Fgate.sh`.**\n`hooks\u002Fdone-gate.sh --stages` prints the list. How a stage runs, and how a marker\nis earned for it, is the project's `scripts\u002Fgates.sh` — the gate only hands the\nlist over. Nothing here runs a stage itself (ADR-0023 D6\u002FD7).\n\n| gate          | where it fires           | who is at the refusal | asks                            |\n| ------------- | ------------------------ | --------------------- | ------------------------------- |\n| `review-gate` | every road into `review` | the agent, alone      | is this work fit for a reviewer |\n| `merge-gate`  | `wt:pre-merge`           | the agent, alone      | is this branch fit for master   |\n| `done-gate`   | every road into `done`   | the supervisor        | is master green after this card |\n| `push-gate`   | `git push` to master     | a human               | is the pushed tree green        |\n\nBelow the gates sits the policy they enforce: **which changes owe an e2e test at\nall.** That half was a standing rule until it folded in here — one home for\nthe question and the machine that asks it.\n\n## When an e2e test is mandatory\n\nA task may not reach `done` if it changed any of the trigger surface below\nwithout adding at least one e2e test under `tests\u002Fe2e\u002F` that exercises the real\ncommand chain.\n\n**The invariant:** the gate fires on any change to code that runs *outside* the\nPython process — an entry point, a shell script, the install\u002Fvenv flow, or any\nscript the assembler installs as a hook. That is where the contract lives at a\nsubprocess boundary the unit suite cannot observe. The list below names the\ncurrent surfaces; a path that is not on it but crosses the same boundary fires\nthe gate all the same.\n\n- `src\u002Fai_hats\u002Fcli\u002F**\u002F*.py` — click commands, command nesting, CLI args\u002Fflags.\n- `scripts\u002F*.sh` — shell scripts (`install-launcher.sh`, `bootstrap.sh`, …).\n- `src\u002Fai_hats\u002F_bootstrap.py`, `src\u002Fai_hats\u002Fcli\u002Fmaintenance.py` — pip install \u002F launcher \u002F venv flow.\n- `[project.scripts]` in any workspace `packages\u002F*\u002Fpyproject.toml` — new or\n  renamed entry points (the root `pyproject.toml` declares none).\n- `packages\u002Fai-hats-library\u002F**\u002Fhooks\u002F**` and `**\u002Fgit_hooks\u002F**` — PreToolUse \u002F\n  PostToolUse hook scripts and the installed git hooks (`git_hooks` is a\n  distinct segment: a `**\u002Fhooks\u002F**` glob does not match it). Highest blast\n  radius in the repo: a hook gates *every* tool call of *every* role composing\n  it, so a four-line change can disable every agent. The test must drive the\n  **composed chain** (all hooks on the matcher, in order) via\n  `tests\u002Fe2e\u002F_helpers\u002Fhook_chain.py`, never one script in isolation — a\n  single-hook test cannot observe a second hook overriding its verdict, which is\n  how a blanket deny once shipped past a green suite.\n- Anything else crossing an external contract: PEP 508 URL forms, click nesting,\n  shell quoting, venv invocation.\n\n**Does not fire:** internal Python modules (storage, parsing, business logic),\ndocs, tests-only changes, version bumps.\n\n### What counts as an e2e test\n\nAll of these must hold:\n\n- Lives under `tests\u002Fe2e\u002F` (the dedicated real-subprocess CLI layer — see `tests\u002FREADME.md`).\n- Marked `@pytest.mark.integration`.\n- Spawns a **real** subprocess chain: real `bash`, real `pip install`, real\n  `ai-hats` binary. No `MagicMock`, no `monkeypatch` on `subprocess.Popen`, no\n  `CliRunner.invoke()`.\n- Asserts observable end-to-end side effects (exit codes, files on disk,\n  captured output) — not internal call counts.\n\nIn-process `CliRunner` tests do **not** satisfy this, regardless of marker.\nNeither do pipeline-integration tests.\n\n### Plan and review\n\nThe plan names the test by path and by what it asserts — \"will add e2e coverage\"\nis not a name. The reviewer runs it, and checks the one thing a green run cannot\nshow: that it **fails when the change is reverted**. If it does not, it lives\nbeside the change rather than exercising it, and the card returns to `execute`.\n\nOrigin: PROP-031 — two production bugs shipped past `done` because the unit\nsuite stubbed the very contracts the change broke.\n\n## Passing a gate\n\n1. **Transition.** `rack transition \u003CID> review` \u002F `done`, or `ai-hats wt\n   merge`. Run nothing first: the gate reads markers inside the lock and, when\n   they are missing, refuses with the command that earns them.\n2. **Refused?** The refusal ends with that command — run it:\n\n       Missing:\n           \u003Cstage>\n           \u003Cstage>\n\n       Run the gate on that exact content, then retry:\n\n           cd \u003Cworktree> && make done-gate\n\n   (`make done-gate REV=\u003Csha>` for a card already merged; the stages a gate\n   requires are `\u003Cgate>.sh --stages`, never a list in this file.) It runs only the\n   stages the tree has not earned, in order, stops at the first red, and\n   stamps each green one.\n\n   **A stage the gate does not declare** — `e2e-rack`, say, absent from\n   `\u003Cgate>.sh --stages` — is a **zone**: an area of the codebase and the tests\n   that assert it. The gates BEFORE the merge (`review`, `merge`) require what\n   they declare PLUS the zones your diff touches, so the set depends on what you\n   changed and cannot be declared in advance; `->done` never asks for them, so\n   you pay for your zone once — `\u003Cgate>.sh --zones` says which gate asks.\n   `bash scripts\u002Fgates.sh touched` prints what your change adds and\n   `bash scripts\u002Fgates.sh zones` the whole table; `make \u003Cgate>` earns them like\n   any other stage. Nothing is wrong with the gate — read it as the tests your\n   own area owns, asked for where you can still fix them alone.\n3. **Green** — the run's first line is `RESULT …, green`. Its last says what\n   the transition after this one will additionally demand, so you can earn it\n   now instead of being refused for it later:\n\n       [gates] next: done-gate also needs \u003Cstage>, \u003Cstage>\n\n   `next: nothing` means no gate on the road is short of anything. Transition.\n4. **Red** — the run's block, verdict first:\n\n       [gates] RESULT tree 5f225a1b (2ac163eb): 11 cached, 1 ran, FAILED unit (rc=1)\n       [gates] fix unit, then: make done-gate\n       [gates] re-run just these:\n           \u002Fpath\u002Fto\u002Frepo\u002F.venv\u002Fbin\u002Fpython -m pytest tests\u002Ftest_x.py::test_y\n       [gates] unit said:\n       tests\u002Ftest_x.py:12: AssertionError: …\n       1 failed, 6024 passed, 2 skipped in 40.1s\n       [gates] lint: 1203 files already formatted\n       …\n       [gates] cached (11): e2e-catalog …\n       [gates] 2ac163eb (tree 5f225a1b) in place: \u003Cworktree>\n       [gates] transcript: \u002Ftmp\u002Fgates-run.Xy12ab\n\n   In order of importance: the verdict, what to do, what the red stage said\n   (a failing test per line, or a finding per line),\n   one line per green stage, the cached ones, the subject, and the dir holding\n   every stage's full output.\n\n   **`fix \u003Cstage>` assumes the failure is yours, and the gate cannot tell.** When\n   the red is in something this change did not touch, attribute before you fix or\n   ask for anything: skill **red-attribution**. Cheapest first — a stale base is a\n   more common cause than a broken master.\n\n   Triage the red stage:\n\n   - a red pytest stage hands you the narrow command already — paste the\n     `re-run just these` line. Do not rebuild it: the interpreter in it is the\n     one this checkout answers for, and another imports someone else's sources;\n   - the stage alone, bare, exactly what CI runs: `bash scripts\u002Fgates.sh unit`\n     (`bash scripts\u002Fgates.sh list` says what each stage checks);\n   - a checker: the tool itself, `ruff check \u003Cpath>` or\n     `python scripts\u002Fcheck_\u003Cname>.py`;\n   - fix, commit, `make \u003Cgate>` again. A fix is a new tree, and a new tree\n     earns every stamp afresh: the checkers take seconds, `unit` about a\n     minute — do not reach for `--fresh` or a narrower gate to save it.\n\n   **`the desk is dirty`, under the verdict?** A run with uncommitted changes\n   happens in a scratch checkout of the commit, so it judges what is COMMITTED\n   — a red one against a fix that was never there, a green one vouching for a\n   fix that never ran. Commit, then run again.\n5. **Touched what the gate does not name?** No card gate runs the whole tier\n   under one name: `->merge` asks for the zones your diff touches, `->done` for\n   the half no zone claims (`done-gate.sh --stages`), and never for your zones\n   again. What that leaves out is a zone your change breaks WITHOUT\n   touching its prefix, and nothing refuses there. Run the tier yourself and say\n   so. It outlives a foreground call, so run it in the background through the\n   wrapper, which exits with the tier's own status:\n\n       timeout 1800 bash packages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fbin\u002Fruncheck.sh \\\n           --log \u002Ftmp\u002Fe2e.log -- bash scripts\u002Fgates.sh e2e\n\n   Report the number in `\u002Ftmp\u002Fe2e.log.rc`, never the completion notice: that\n   notice reports the whole command, so a hand-rolled `; echo $?` is what it\n   announces — two red tiers arrived as `exit code 0` that way. What a gate\n   requires of every tree:\n\n       bash packages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fhooks\u002Fdone-gate.sh --stages\n\n### What a stamp saves\n\nA marker names the TREE a stage ran on, per stage. It spares the re-run of an\nunchanged tree, never of a fixed one:\n\n- the transition after a green run — instant;\n- `make done-gate` after `make review-gate` — pays the difference, not twice;\n- a merge commit whose tree equals the branch tip — a fast-forward, or a\n  merge into a master that moved nothing else — `REV=\u003Cmerge sha>` finds every\n  stamp already there;\n- a stage marked green that you want to see run anyway:\n  `\u003Cgate>.sh --run --fresh` (no make target).\n\n### Where it runs, and what that costs\n\nThe subject is a commit — `HEAD`, or `REV=\u003Csha>`. The run happens in the\ncheckout only when it is clean and at that commit; otherwise in a one-shot\nscratch checkout of the commit under the shared git dir, with a venv of its\nown. Measured 2026-09-03 with a warm uv cache: +2.5 s on `lint`, +5 s on a\n35 s `unit`. A dirty desk therefore never taints a marker and never blocks\none, and `REV=` is not a cost worth working around.\n\nEither way the stages run under that checkout's `.venv`, and the gate leads\n`PATH` with it: a bare `python3` or `pytest` a test spawns is the same\ninterpreter. Nothing to activate or prefix in your shell first.\n\n## Pushing master\n\n    scripts\u002Frun-e2e-gate.sh    # out of band, BEFORE the push\n    git push origin master     # the hook then passes instantly\n\n## Status is printed, not documented\n\n**Do not come back to this file to find out what happened. Read what the gate\nsaid.** Every branch narrates itself with a reason and a remedy — the refusals,\nthe green, and every quiet pass-through alike. The one thing it never prints is\nthe transcript, which lands beside the card; glob it, never hand-build the name:\n\n    \u003Ctasks_dir>\u002F\u003CID>\u002F.checks\u002F*done-gate.sh*.log\n\n## Why the push gate runs out of band\n\nRunning the suite **inside** the pre-push hook cannot work. Git opens the SSH\nconnection for ref-advertisement *before* running the hook, then runs the hook,\nthen sends the pack. GitHub closes the idle connection after ~30s, so a hook\ntaking minutes dies with `Connection closed by remote host` → SIGPIPE (exit 141)\nand the pack is never sent.\n\n**Do not re-attempt:** client-side `ServerAliveInterval` at 60 **and** 15 did not\nfix it, and the 2022 community keepalive workaround no longer works (paid for twice).\n\n## No bypass\n\nThere is no `AI_HATS_E2E_SKIP`, no `--ack` and no knob. `git push --no-verify`\nand forging a marker are deliberate local acts by the trusted maintainer, never\nan accidental skip.\n\nMaster's own CI verdict is not a card's to pass or to wave through, so no card\ngate asks for it. The push road prints it before a push to master\n(`scripts\u002Fcheck_master_ci.py --notice`, never blocking: the push is how master\ngets fixed), and `bash scripts\u002Fgates.sh master-ci` asks by hand — green only on\na completed green run; a run still going or a verdict it cannot read is unknown,\nand unknown is not green. If a red is not yours, the move is a classification,\nnot a request for a flag: skill **red-attribution**.\n",{"name":5,"ai_hats":49,"license":15,"description":7},{"git_hooks":50},{"pre-push":51},[52],"git_hooks\u002Fpre-push-e2e-master.sh","master","b4819add93efbaf4d80627118ec34680406b309b","packages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate",1,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats","https:\u002F\u002Fgithub.com\u002Fmuratovv","2026-11-05 20:59:10",{"source":8,"skillName":5,"commands":61,"prompt":71,"zipAvailable":72},[62,65,68],{"tool":63,"command":64},"npx","npx skills add muratovv\u002Fai-hats --skill quality-gate",{"tool":66,"command":67},"bunx","bunx skills add muratovv\u002Fai-hats --skill quality-gate",{"tool":69,"command":70},"pnpm","pnpm dlx skills add muratovv\u002Fai-hats --skill quality-gate","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002FSKILL.md",true,[74,80,83,87,91,95],{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"bin\u002Fruncheck.sh","SCRIPT","脚本",2977,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fbin\u002Fruncheck.sh",{"path":52,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":81,"sourceHtmlUrl":82},5698,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fgit_hooks\u002Fpre-push-e2e-master.sh",{"path":84,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":85,"sourceHtmlUrl":86},"hooks\u002Fdone-gate.sh",1165,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fhooks\u002Fdone-gate.sh",{"path":88,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":89,"sourceHtmlUrl":90},"hooks\u002Fmerge-gate.sh",482,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fhooks\u002Fmerge-gate.sh",{"path":92,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":93,"sourceHtmlUrl":94},"hooks\u002Freview-gate.sh",397,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Fhooks\u002Freview-gate.sh",{"path":96,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":97,"sourceHtmlUrl":98},"lib\u002Fgate.sh",19057,"https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fai-hats-dev\u002Fskills\u002Fquality-gate\u002Flib\u002Fgate.sh",[100,126,150,171,195,208],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":44},"01M6PVFB1SM738R2SRSRSF7CY6","tool-evaluation-protocol","Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML\u002FLLM frameworks, testing approaches), or following up on a hype-driven recommendation.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Ftool-evaluation-protocol\u002FSKILL.md",[],[107,108,109,110,111,112,113,114,115,116,27,117,118,119,120,121,122,123,124,125],"protocol","Evaluation","tool","tool evaluation protocol","testing","ml","libraries","adoption","methodology","Tools","dependency","up","frameworks","time","project","recommendation","for","bounded","candidate",{"skillNo":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":44},"01M6PVF7HATBEX1G7N50E2QT57","systematic-debugging","4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",[],[133,134,135,42,107,136,137,138,139,140,27,141,142,143,144,145,146,147,148,149],"systematic debugging","debugging","systematic","monitoring","hypothesis","verify","behavior","fix","evidence","bug","reports","pattern","users","error","with","bug-fix","phase",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":159,"publishedAt":44},"01M6PVF3MTQN3RPF73AN34856J","skill-template","Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fskill-template\u002FSKILL.md",[156],{"categoryNo":157,"categoryName":158,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[160,161,162,163,164,139,165,27,166,144,167,168,169,123,170],"template","skill template","validation","compliance","hats","guide","new skill","structural","canonical","which","Existing",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":178,"publishedAt":44},"01M6PVF06SCV28QARM5MQPANC9","skill-optimization","Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fskill-optimization\u002FSKILL.md",[177],{"categoryNo":157,"categoryName":158,"taxonomyType":21,"taxonomyTypeDesc":22},[179,180,181,182,183,184,185,186,187,188,27,189,190,191,192,193,194],"Optimization","skill optimization","components","component","issues","library","audit","refactor","Budget","Rules","periodic","maintenance","token","token budget","role","high",{"skillNo":196,"name":197,"nameZh":6,"description":198,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":199,"categories":200,"keywords":201,"publishedAt":44},"01M6PVEXM9717016T9MW82HDCT","silent-fallback-gate","PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fsilent-fallback-gate\u002FSKILL.md",[],[25,202,203,204,205,206,27,207,123],"fallback","silent fallback gate","python","write","edit","hook",{"skillNo":209,"name":210,"nameZh":6,"description":211,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":212,"categories":213,"keywords":215,"publishedAt":44},"01M6PVESM49C5NT7SB7N3F76VS","retro-to-framework","Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.","https:\u002F\u002Fgithub.com\u002Fmuratovv\u002Fai-hats\u002Fblob\u002Fmaster\u002Fpackages\u002Fai-hats-library\u002Fsrc\u002Fai_hats_library\u002Fexperimental\u002Fusage\u002Fskills\u002Fretro-to-framework\u002FSKILL.md",[214],{"categoryNo":157,"categoryName":158,"taxonomyType":21,"taxonomyTypeDesc":22},[216,217,218,41,182,219,220,221,188,139,27,222,223,121,224,225,226,227,228,229],"framework","retro","retro to framework","retrospective","projects","convert","incident","across","problem","about","more","skill update","single","generic"]