craftsman-gate 4.1.0__tar.gz

craftsman_gate-4.1.0/.gitattributes

@@ -0,0 +1,12 @@
+* text=auto eol=lf
+*.sh text eol=lf
+*.py text eol=lf
+*.md text eol=lf
+*.json text eol=lf
+*.excalidraw text eol=lf
+*.png binary
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+Makefile text eol=lf
+*.cmd text eol=crlf

craftsman_gate-4.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafał Buczyński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

craftsman_gate-4.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+graft skills
+graft rules
+graft scripts
+graft templates
+include plugin.json hooks.json LICENSE NOTICE README.md setup.py pyproject.toml .gitattributes
+global-exclude __pycache__ *.py[cod] .DS_Store

craftsman_gate-4.1.0/NOTICE

@@ -0,0 +1,12 @@
+Craftsman
+Copyright (c) 2026 Rafał Buczyński
+
+Make AI coding agents prove they reviewed and tested their change.
+
+This software includes:
+- Quality gate and review verification runtime (`craftsman/`).
+- Lifecycle hook scripts and adapters for Claude Code, GitHub Copilot, and Google Antigravity.
+- Curated software engineering review skills and agent templates.
+- Test suites and benchmarks.
+
+All components are licensed under the MIT License (see LICENSE).

craftsman_gate-4.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: craftsman-gate
+Version: 4.1.0
+Summary: Make AI coding agents prove they reviewed and tested their change
+Author-email: Rafał Buczyński <buczynski.rafal2@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/BuczynskiRafal/craftsman
+Project-URL: Repository, https://github.com/BuczynskiRafal/craftsman
+Project-URL: Issues, https://github.com/BuczynskiRafal/craftsman/issues
+Keywords: ai-agents,claude-code,github-copilot,codex,cursor,antigravity,quality-gate,developer-tools,code-review,ai-code-review,llm,coding-agents,agents-md
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# Craftsman
+
+[![CI](https://github.com/BuczynskiRafal/craftsman/actions/workflows/ci.yml/badge.svg)](https://github.com/BuczynskiRafal/craftsman/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/badge/version-4.1.0-emerald.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/plugin.json)
+[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/pyproject.toml)
+[![Dependencies: stdlib only](https://img.shields.io/badge/dependencies-stdlib%20only-brightgreen.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/LICENSE)
+
+Craftsman adds a layer to an AI coding agent that checks the quality and simplicity of the code it
+delivers. The agent cannot finish its work until an independent reviewer has examined the change.
+Craftsman enforces a review loop in which every reported defect is verified and resolved, and at the
+end the tests must pass on the final version of the code.
+
+Craftsman keeps a ledger in the `.git` directory, where it collects evidence from review,
+verification, and tests. When the agent tries to finish, a platform hook checks the ledger and, if
+anything is missing, sends the agent back with a list of what is missing.
+
+It works with Claude Code, GitHub Copilot, and Google Antigravity. In Codex and Cursor, the same
+protocol runs without hooks.
+
+## How It Works
+
+![Craftsman engineering loop](https://raw.githubusercontent.com/BuczynskiRafal/craftsman/main/docs/diagrams/harness-overview.png)
+
+1. `/craftsman <task>` records the base commit that the diff is computed from.
+2. The agent implements the change and cleans it up with `/simplify`.
+3. Craftsman splits the diff into hunks and attaches to each one the context the diff does not show:
+   the rest of the function, its call sites, and risk signals. Defects usually sit where the change
+   meets that code.
+4. Reviewer subagents that did not write the change examine every hunk through several lenses (for
+   example contracts, error handling, tests, security) and record suspected defects.
+5. A separate verifier tries to disprove or reproduce each suspected defect. Searching and judging
+   are kept apart so that the reviewer does not drop leads too early.
+6. The agent fixes confirmed defects. Every piece of evidence in the ledger is tied to a diff
+   fingerprint, so a code change invalidates the old review; the next round covers only the changed
+   parts.
+7. The agent runs the tests through `craftsman run`, which records the exit code.
+8. The stop hook lets the agent finish once the ledger is complete for the current version of the
+   code. The agent prints a report: what was reviewed, what was found, what was fixed, what was
+   dismissed, and what the gate did not assess.
+
+The level of rigor depends on the gear: `quick` for small changes (review in the current context),
+`standard` by default (subagents and a verifier), `deep` for risky changes (all lenses, tests, and
+e2e).
+
+`/code-review` runs only the review of an existing change, without fixes.
+
+## Platforms
+
+| Platform | What blocks completion |
+| :--- | :--- |
+| Claude Code | `Stop` hook |
+| GitHub Copilot in VS Code | `Stop` hook |
+| GitHub Copilot CLI | `agentStop` hook |
+| Google Antigravity | `Stop` hook |
+| Codex, Cursor, and other tools that read `AGENTS.md` | `craftsman gate --complete` |
+
+Where the platform cannot confirm that a separate subagent performed the review, the report marks it
+as `SELF-REVIEWED`.
+
+## Measurements
+
+Pilot on [SWR-Bench](https://doi.org/10.1145/3808144): 5 PRs from `pytest`, `flask`, and `requests`,
+9 confirmed defects, 1 repetition per configuration. The sample is too small for statistical
+conclusions. Details and Claude Code runs: [docs/benchmark.md](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/benchmark.md).
+
+| Configuration | Defects: without → with Craftsman | Avg. time per PR |
+| :--- | :---: | :---: |
+| Antigravity · Gemini 4 Argon `low` | 2/9 → 4/9 | 1.5 → 4.7 min |
+| Antigravity · Gemini 4 Argon `medium` | 2/9 → 5/9 | 2.0 → 6.7 min |
+| Antigravity · Gemini 4 Argon `high` | 3/9 → 7/9 | 15.6 → 26.3 min |
+
+## Installation
+
+Requires Python 3.10+, with no external dependencies.
+
+```bash
+pipx install craftsman-gate        # or: uv tool install craftsman-gate
+craftsman install                  # detects Claude Code, Copilot, and Antigravity
+```
+
+Or as a plugin:
+
+```bash
+/plugin marketplace add BuczynskiRafal/craftsman              # Claude Code
+/plugin install craftsman@craftsman
+agy plugin install https://github.com/BuczynskiRafal/craftsman   # Antigravity
+```
+
+## Usage
+
+```
+/craftsman add pagination to the catalog search
+/craftsman --deep migrate the session store to Redis
+/code-review
+```
+
+`craftsman status` shows the current gear, round, and missing evidence.
+
+## Documentation
+
+- [How it works](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/how-it-works.md): ledger, lenses, gears, platform enforcement
+- [Installation](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/installation.md): flags, platform setup, uninstall, `craftsman doctor`
+- [Usage](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/usage.md): commands, review-only mode
+- [Guards](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/guards.md): gate state machine, search scope guard
+- [Skills](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/skills.md): catalog of bundled skills
+- [Benchmark](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/benchmark.md): methodology, results, replication
+- [Architecture](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/harness-architecture.md): project internals for contributors
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/BuczynskiRafal/craftsman/blob/main/CONTRIBUTING.md).
+
+## Citation
+
+```bibtex
+@article{zeng2026swrbench,
+  author    = {Zeng, Zhengran and Shi, Ruikai and Han, Keke and Li, Yixin and Sun, Kaicheng and Wang, Yidong and Yu, Zhuohao and Xie, Rui and Ye, Wei and Zhang, Shikun},
+  title     = {{SWR-Bench}: Assessing {LLM} Performance in Real-World Code Review Comment Generation},
+  journal   = {Proceedings of the ACM on Software Engineering},
+  volume    = {3},
+  number    = {FSE},
+  articleno = {FSE137},
+  year      = {2026},
+  doi       = {10.1145/3808144}
+}
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/BuczynskiRafal/craftsman/blob/main/LICENSE) and attribution in [NOTICE](https://github.com/BuczynskiRafal/craftsman/blob/main/NOTICE).

craftsman_gate-4.1.0/README.md

@@ -0,0 +1,131 @@
+# Craftsman
+
+[![CI](https://github.com/BuczynskiRafal/craftsman/actions/workflows/ci.yml/badge.svg)](https://github.com/BuczynskiRafal/craftsman/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/badge/version-4.1.0-emerald.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/plugin.json)
+[![Python 3.10–3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/pyproject.toml)
+[![Dependencies: stdlib only](https://img.shields.io/badge/dependencies-stdlib%20only-brightgreen.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/BuczynskiRafal/craftsman/blob/main/LICENSE)
+
+Craftsman adds a layer to an AI coding agent that checks the quality and simplicity of the code it
+delivers. The agent cannot finish its work until an independent reviewer has examined the change.
+Craftsman enforces a review loop in which every reported defect is verified and resolved, and at the
+end the tests must pass on the final version of the code.
+
+Craftsman keeps a ledger in the `.git` directory, where it collects evidence from review,
+verification, and tests. When the agent tries to finish, a platform hook checks the ledger and, if
+anything is missing, sends the agent back with a list of what is missing.
+
+It works with Claude Code, GitHub Copilot, and Google Antigravity. In Codex and Cursor, the same
+protocol runs without hooks.
+
+## How It Works
+
+![Craftsman engineering loop](https://raw.githubusercontent.com/BuczynskiRafal/craftsman/main/docs/diagrams/harness-overview.png)
+
+1. `/craftsman <task>` records the base commit that the diff is computed from.
+2. The agent implements the change and cleans it up with `/simplify`.
+3. Craftsman splits the diff into hunks and attaches to each one the context the diff does not show:
+   the rest of the function, its call sites, and risk signals. Defects usually sit where the change
+   meets that code.
+4. Reviewer subagents that did not write the change examine every hunk through several lenses (for
+   example contracts, error handling, tests, security) and record suspected defects.
+5. A separate verifier tries to disprove or reproduce each suspected defect. Searching and judging
+   are kept apart so that the reviewer does not drop leads too early.
+6. The agent fixes confirmed defects. Every piece of evidence in the ledger is tied to a diff
+   fingerprint, so a code change invalidates the old review; the next round covers only the changed
+   parts.
+7. The agent runs the tests through `craftsman run`, which records the exit code.
+8. The stop hook lets the agent finish once the ledger is complete for the current version of the
+   code. The agent prints a report: what was reviewed, what was found, what was fixed, what was
+   dismissed, and what the gate did not assess.
+
+The level of rigor depends on the gear: `quick` for small changes (review in the current context),
+`standard` by default (subagents and a verifier), `deep` for risky changes (all lenses, tests, and
+e2e).
+
+`/code-review` runs only the review of an existing change, without fixes.
+
+## Platforms
+
+| Platform | What blocks completion |
+| :--- | :--- |
+| Claude Code | `Stop` hook |
+| GitHub Copilot in VS Code | `Stop` hook |
+| GitHub Copilot CLI | `agentStop` hook |
+| Google Antigravity | `Stop` hook |
+| Codex, Cursor, and other tools that read `AGENTS.md` | `craftsman gate --complete` |
+
+Where the platform cannot confirm that a separate subagent performed the review, the report marks it
+as `SELF-REVIEWED`.
+
+## Measurements
+
+Pilot on [SWR-Bench](https://doi.org/10.1145/3808144): 5 PRs from `pytest`, `flask`, and `requests`,
+9 confirmed defects, 1 repetition per configuration. The sample is too small for statistical
+conclusions. Details and Claude Code runs: [docs/benchmark.md](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/benchmark.md).
+
+| Configuration | Defects: without → with Craftsman | Avg. time per PR |
+| :--- | :---: | :---: |
+| Antigravity · Gemini 4 Argon `low` | 2/9 → 4/9 | 1.5 → 4.7 min |
+| Antigravity · Gemini 4 Argon `medium` | 2/9 → 5/9 | 2.0 → 6.7 min |
+| Antigravity · Gemini 4 Argon `high` | 3/9 → 7/9 | 15.6 → 26.3 min |
+
+## Installation
+
+Requires Python 3.10+, with no external dependencies.
+
+```bash
+pipx install craftsman-gate        # or: uv tool install craftsman-gate
+craftsman install                  # detects Claude Code, Copilot, and Antigravity
+```
+
+Or as a plugin:
+
+```bash
+/plugin marketplace add BuczynskiRafal/craftsman              # Claude Code
+/plugin install craftsman@craftsman
+agy plugin install https://github.com/BuczynskiRafal/craftsman   # Antigravity
+```
+
+## Usage
+
+```
+/craftsman add pagination to the catalog search
+/craftsman --deep migrate the session store to Redis
+/code-review
+```
+
+`craftsman status` shows the current gear, round, and missing evidence.
+
+## Documentation
+
+- [How it works](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/how-it-works.md): ledger, lenses, gears, platform enforcement
+- [Installation](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/installation.md): flags, platform setup, uninstall, `craftsman doctor`
+- [Usage](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/usage.md): commands, review-only mode
+- [Guards](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/guards.md): gate state machine, search scope guard
+- [Skills](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/skills.md): catalog of bundled skills
+- [Benchmark](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/benchmark.md): methodology, results, replication
+- [Architecture](https://github.com/BuczynskiRafal/craftsman/blob/main/docs/harness-architecture.md): project internals for contributors
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/BuczynskiRafal/craftsman/blob/main/CONTRIBUTING.md).
+
+## Citation
+
+```bibtex
+@article{zeng2026swrbench,
+  author    = {Zeng, Zhengran and Shi, Ruikai and Han, Keke and Li, Yixin and Sun, Kaicheng and Wang, Yidong and Yu, Zhuohao and Xie, Rui and Ye, Wei and Zhang, Shikun},
+  title     = {{SWR-Bench}: Assessing {LLM} Performance in Real-World Code Review Comment Generation},
+  journal   = {Proceedings of the ACM on Software Engineering},
+  volume    = {3},
+  number    = {FSE},
+  articleno = {FSE137},
+  year      = {2026},
+  doi       = {10.1145/3808144}
+}
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/BuczynskiRafal/craftsman/blob/main/LICENSE) and attribution in [NOTICE](https://github.com/BuczynskiRafal/craftsman/blob/main/NOTICE).

craftsman_gate-4.1.0/craftsman/__init__.py

@@ -0,0 +1,7 @@
+"""Make AI coding agents prove they reviewed and tested their change."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "4.1.0"

craftsman_gate-4.1.0/craftsman/antigravity.py

@@ -0,0 +1,242 @@
+"""The Antigravity Stop hook: `scripts/craftsman-stop-gate.py`, wired by `hooks.json`.
+
+Antigravity has no prompt or subagent hooks, so this hook reads the session transcript instead:
+- a `/craftsman` or `ultracraft` request opens a gate when the agent did not open one itself;
+- `craftsman-reviewer` subagents that finished since the request are recorded in the evidence
+  ledger, which is the proof of reviewer isolation for Antigravity sessions;
+- an unanswered `ask_question` lets the agent stop to wait for the user.
+Then the gate's shared stop decision applies (`craftsman.gate.decide_stop`).
+
+The hook reads a JSON object on stdin with `terminationReason`, `fullyIdle`,
+`artifactDirectoryPath` (the session directory, `<appDataDir>/brain/<conversation id>`) and
+`workspacePaths`, and answers `{"decision": "continue" | "allow", "reason": ...}`. When the gate
+cannot be evaluated, it lets the agent stop and says why on stderr.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+from craftsman.diffscan import DiffScanError, resolve_base_sha, snapshot, worktree_root
+from craftsman.gate import (
+    GateOwner,
+    GateState,
+    GateStateError,
+    GateTier,
+    archive_ledger_for_new_base,
+    decide_stop,
+    state_path_for,
+    update_state,
+)
+from craftsman.ledger import add_agent_event, ledger_path_for, mutate
+from craftsman.records import REVIEWER_AGENT, AgentEvent, Ledger, LedgerError, format_timestamp
+from craftsman.streams import configure_std_streams
+from craftsman.transcript import (
+    Entry,
+    TranscriptError,
+    finished_reviewers,
+    is_waiting_on_question,
+    latest_user_input,
+    read_transcript_entries,
+    step_of,
+)
+from craftsman.trigger import detect_trigger, task_from_prompt
+
+PLATFORM: Literal["antigravity"] = "antigravity"
+TRANSCRIPT = Path(".system_generated") / "logs" / "transcript.jsonl"
+
+
+class PayloadError(ValueError):
+    """The Stop payload lacks what the hook needs to find the session and its work tree."""
+
+
+@dataclass(frozen=True)
+class StopPayload:
+    session_dir: Path
+    workspace: Path
+
+    @classmethod
+    def parse(cls, payload: Mapping[str, Any]) -> StopPayload:
+        session_dir = payload.get("artifactDirectoryPath")
+        workspaces = payload.get("workspacePaths")
+        if not isinstance(session_dir, str) or not session_dir.strip():
+            raise PayloadError("the Stop payload has no artifactDirectoryPath")
+        if not isinstance(workspaces, list) or not workspaces or not isinstance(workspaces[0], str):
+            raise PayloadError("the Stop payload has no workspacePaths")
+        return cls(Path(session_dir).expanduser(), Path(workspaces[0]).expanduser())
+
+    @property
+    def caller(self) -> GateOwner:
+        return GateOwner(PLATFORM, self.session_dir.name)
+
+
+def session_id(payload: Mapping[str, Any]) -> str | None:
+    """The conversation id of an Antigravity hook payload: the name of its session directory."""
+    session_dir = payload.get("artifactDirectoryPath")
+    if isinstance(session_dir, str) and session_dir.strip():
+        return Path(session_dir).expanduser().name
+    return None
+
+
+def is_final_stop(payload: Mapping[str, Any]) -> bool:
+    """True when the agent ends its turn, rather than pausing between tool calls."""
+    reason, idle = payload.get("terminationReason"), payload.get("fullyIdle")
+    if not isinstance(reason, str) or not isinstance(idle, bool):
+        raise PayloadError("the Stop payload needs `terminationReason` and `fullyIdle`")
+    return reason == "NO_TOOL_CALL" and idle
+
+
+def on_stop(stop: StopPayload) -> str | None:
+    """The reason to keep the agent working, or None to let it stop."""
+    root = worktree_root(stop.workspace)
+    entries = read_transcript_entries(stop.session_dir / TRANSCRIPT)
+
+    def decide(state: GateState | None) -> tuple[GateState | None, str | None]:
+        state = _opened_by_request(state, root, entries, stop.caller)
+        if state is None or not state.active or not state.owner.admits(stop.caller):
+            return state, None
+        state = _claimed(state, entries, stop.caller)
+        _record_finished_reviewers(root, stop.session_dir, entries, state.request_step or 0)
+        if is_waiting_on_question(entries):
+            return state, None
+        decision = decide_stop(state, root)
+        if decision.notice is not None:
+            sys.stderr.write(decision.notice + "\n")
+        return decision.state, decision.block_reason
+
+    return update_state(state_path_for(root), decide)
+
+
+def _opened_by_request(
+    state: GateState | None, root: Path, entries: Sequence[Entry], caller: GateOwner
+) -> GateState | None:
+    """The gate, opened for a `/craftsman` request the agent did not open a gate for."""
+    if state is not None and state.active:
+        return state
+    if state is not None and state.owner.admits(caller):
+        if state.request_step is None:
+            # Closed with `craftsman gate --complete` before any stop: the request was handled.
+            latest = latest_user_input(entries)
+            return state if latest is None else replace(state, request_step=latest[0])
+        handled_step = state.request_step
+    else:
+        handled_step = 0
+    request = _latest_trigger(entries, handled_step)
+    if request is None:
+        return state
+    step, tier, prompt = request
+    base_sha = resolve_base_sha(root, None)
+    if snapshot(root, base_sha).is_empty:
+        return state  # nothing changed yet, so there is nothing to gate
+    archive_ledger_for_new_base(root, base_sha)
+    return GateState.open(caller, base_sha, tier, task_from_prompt(prompt), request_step=step)
+
+
+def _latest_trigger(entries: Sequence[Entry], after_step: int) -> tuple[int, GateTier, str] | None:
+    """The step, tier and text of the latest user input after `after_step` that invokes Craftsman."""
+    for position in range(len(entries), 0, -1):
+        entry = entries[position - 1]
+        step = step_of(entry, position)
+        if step <= after_step:
+            return None
+        if entry.get("type") != "USER_INPUT":
+            continue
+        prompt = str(entry.get("content") or "")
+        tier = detect_trigger(prompt)
+        if tier is not None:
+            return step, tier, prompt
+    return None
+
+
+def _claimed(state: GateState, entries: Sequence[Entry], caller: GateOwner) -> GateState:
+    """The gate as this session's stop hook serves it: owned, transcript-isolated, anchored."""
+    request_step = state.request_step
+    if request_step is None:
+        latest = latest_user_input(entries)
+        request_step = latest[0] if latest is not None else 0
+    return replace(
+        state,
+        owner=state.owner.claimed_by(caller),
+        isolation_evidence="transcript",
+        request_step=request_step,
+    )
+
+
+def _record_finished_reviewers(
+    root: Path, session_dir: Path, entries: Sequence[Entry], after_step: int
+) -> None:
+    """Record each finished `craftsman-reviewer` subagent once, at the time its own run ended.
+
+    A subagent's session directory is a sibling of its parent's, named by its conversation id;
+    a subagent without one left no trace of having run, so it is not recorded.
+    """
+    events = [
+        event
+        for sub_id in finished_reviewers(entries, after_step)
+        if (event := _reviewer_stop(session_dir.parent / sub_id, sub_id)) is not None
+    ]
+    if events:
+        mutate(ledger_path_for(root), lambda ledger: (_with_new_events(ledger, events), None))
+
+
+def _reviewer_stop(subagent_dir: Path, sub_id: str) -> AgentEvent | None:
+    try:
+        finished_at = (subagent_dir / TRANSCRIPT).stat().st_mtime
+    except FileNotFoundError:
+        return None
+    return AgentEvent(
+        platform=PLATFORM,
+        event="stop",
+        agent=REVIEWER_AGENT,
+        agent_id=sub_id,
+        at=format_timestamp(datetime.fromtimestamp(finished_at, timezone.utc)),
+    )
+
+
+def _with_new_events(ledger: Ledger, events: Sequence[AgentEvent]) -> Ledger:
+    recorded = {(event.platform, event.agent_id) for event in ledger.agents if event.event == "stop"}
+    for event in events:
+        if (event.platform, event.agent_id) not in recorded:
+            ledger = add_agent_event(ledger, event)
+    return ledger
+
+
+def answer(payload: object) -> dict[str, str]:
+    """The hook's answer to one Stop payload."""
+    if not isinstance(payload, dict):
+        return _allow_after_error("the Stop payload is not a JSON object")
+    try:
+        if not is_final_stop(payload):
+            return {"decision": "allow"}
+        reason = on_stop(StopPayload.parse(payload))
+    except (PayloadError, DiffScanError, LedgerError, GateStateError, TranscriptError, OSError) as exc:
+        return _allow_after_error(str(exc))
+    return {"decision": "continue", "reason": reason} if reason is not None else {"decision": "allow"}
+
+
+def _allow_after_error(problem: str) -> dict[str, str]:
+    sys.stderr.write(
+        f"[craftsman-stop-gate] The quality gate was not checked: {problem}. "
+        "Run `craftsman review check` yourself.\n"
+    )
+    return {"decision": "allow"}
+
+
+def main() -> int:
+    configure_std_streams()
+    try:
+        out = answer(json.loads(sys.stdin.read()))
+    except (OSError, ValueError) as exc:
+        out = _allow_after_error(f"unreadable hook input ({exc})")
+    sys.stdout.write(json.dumps(out, ensure_ascii=False) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())