pi-dev-team 0.2.0

package/hooks/lib/doc_classification.py

@@ -0,0 +1,116 @@
+"""hooks/lib/doc_classification.py — shared documentation-classification
+literal tables (#1477).
+
+`hooks/pre_commit_review.py`'s doc-only exemption predicate
+(`hooks/lib/pre_commit_doc_classifier.py` as of this same change) and
+`skills/code-review/scripts/change_shape.py`'s low-yield-lens gate both
+classify a changed file as "documentation" — but for different purposes and
+at different strictness levels (see `pre_commit_doc_classifier.py`'s module
+docstring: the pre-commit gate's predicate is a deliberate STRICT SUBSET of
+`change_shape.py`'s, never a superset, so the two must never be forced into
+lockstep). Prior to this module the two call sites hand-duplicated the same
+literal word lists, kept in sync only by comment convention — exactly the
+class of gap that needed fixing across four separate `pre_commit_review.py`
+hardening rounds (#1461) without anything forcing the `change_shape.py`
+sibling copy to be checked too.
+
+This module carries ONLY the literal data that is actually identical between
+the two call sites today, with one exception: `is_functional_config` below
+(#1923's third caller, `scripts/select_lenses.py`) IS shared logic, not just
+data — but only because `change_shape.py` and `select_lenses.py` want the
+exact same predicate over the exact same composed segment set (the
+`"templates"` addition included), with no matching-semantics divergence
+between them the way `pre_commit_doc_classifier.py` has from both (see the
+`CORE_FUNCTIONAL_CONFIG_SEGMENTS` comment below). `pre_commit_doc_classifier.py`
+does NOT call this function — it keeps its own inline check reading the raw
+`CORE_FUNCTIONAL_CONFIG_SEGMENTS`/`FUNCTIONAL_CONFIG_NAMES` constants
+directly, staying the strict subset its own docstring requires. Every other
+matching *logic* here (exact-name vs. prefix match for doc detection) stays
+local to each caller by design — unifying THAT, not just the data, would
+re-introduce the subset/superset coupling the pre-commit gate's docstring
+explicitly warns against.
+
+Location: `hooks/lib/` rather than a new top-level `shared/` directory.
+There is no existing precedent in this repo for a module living outside
+both `hooks/` and `skills/*/scripts/` that either side imports — grepping
+found no prior cross-boundary shared-constant mechanism. `hooks/lib/`
+already hosts several business-logic-free utility modules other packages
+reach into (`artifact_paths.py`, `stdin_json.py`, `minimal_yaml.py`), so a
+neutral, pure-data module fits the same convention; `change_shape.py`
+reaches it via the identical `sys.path.insert` pattern
+`hooks/pre_commit_review.py` already uses for its own `hooks/lib/` imports
+(see that module's top-of-file import block). This is a one-line documented
+choice, not an established repo-wide convention — revisit if a genuine
+`shared/` location emerges later.
+
+Stdlib only.
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath  # used by is_functional_config below
+
+# Documentation extensions (lower-cased). Byte-identical set between
+# `change_shape.py`'s `_DOC_EXTENSIONS` and
+# `pre_commit_doc_classifier.py`'s `_DOC_EXTENSIONS` prior to this
+# extraction.
+DOC_EXTENSIONS = frozenset({".md", ".mdx", ".markdown", ".rst", ".txt", ".adoc"})
+
+# Documentation root-file word list (lower-cased), identical set of 7 words
+# between both call sites. NOTE: the two callers apply DIFFERENT matching
+# semantics on top of this SAME word list, by deliberate design —
+# `change_shape.py` does a stem PREFIX match (`stem.startswith(word)`,
+# appropriate for its own lower-stakes lens-narrowing purpose);
+# `pre_commit_doc_classifier.py` does an EXACT match (`stem in
+# frozenset(DOC_ROOT_WORDS)`, required because it is the sole gate deciding
+# a zero-dispatch-evidence exemption — see that module's docstring for why
+# prefix matching was exploitable there). This module carries only the
+# shared words; each caller keeps its own matching logic.
+DOC_ROOT_WORDS = (
+    "readme",
+    "changelog",
+    "contributing",
+    "license",
+    "notice",
+    "authors",
+    "code_of_conduct",
+)
+
+# Functional-config filenames anywhere in the tree. Byte-identical set
+# between both call sites.
+FUNCTIONAL_CONFIG_NAMES = frozenset({"claude.md", "agents.md"})
+
+# Functional-config path segments COMMON to both call sites. `change_shape.py`
+# additionally treats "templates" as functional-config (its own
+# `_FUNCTIONAL_CONFIG_SEGMENTS` adds it on top of this core set);
+# `pre_commit_doc_classifier.py` deliberately does not (staying the strict
+# subset its docstring requires). That one-item divergence predates this
+# extraction and is preserved exactly as it was — not resolved — here; each
+# caller layers its own additions on top of this shared core.
+CORE_FUNCTIONAL_CONFIG_SEGMENTS = frozenset({".claude", "agents", "skills", "prompts", "knowledge"})
+
+# `change_shape.py`'s own "templates" addition, baked in here because
+# `select_lenses.py` wants the identical composed set — see `is_functional_config`.
+_FUNCTIONAL_CONFIG_SEGMENTS_WITH_TEMPLATES = CORE_FUNCTIONAL_CONFIG_SEGMENTS | {"templates"}
+
+
+def is_functional_config(file_path: str) -> bool:
+    """True when ``file_path`` drives agent/skill/command behavior and must
+    never be treated as inert documentation/config regardless of extension.
+    Shared by `change_shape.py` and `select_lenses.py` (#1923) — see this
+    module's docstring for why this one predicate is shared logic, not just
+    data, and why `pre_commit_doc_classifier.py` deliberately does not call
+    it."""
+    path = PurePosixPath(file_path)
+    if path.name.lower() in FUNCTIONAL_CONFIG_NAMES:
+        return True
+    return any(seg in _FUNCTIONAL_CONFIG_SEGMENTS_WITH_TEMPLATES for seg in path.parts)
+
+
+__all__ = (
+    "CORE_FUNCTIONAL_CONFIG_SEGMENTS",
+    "DOC_EXTENSIONS",
+    "DOC_ROOT_WORDS",
+    "FUNCTIONAL_CONFIG_NAMES",
+    "is_functional_config",
+)

package/hooks/lib/gh_pr_create_detect.py

@@ -0,0 +1,136 @@
+"""hooks/lib/gh_pr_create_detect.py — detect a `gh pr create` invocation
+(#1886).
+
+`hooks/pre_pr_review.py`'s trigger-point detector: a single quote-aware
+tokenizing pass over each shell-separator-delimited segment of the raw Bash
+command, looking for `gh pr create` as the segment's real command words
+(after skipping any leading `NAME=value` environment-variable prefixes and
+resolving a path-qualified `gh` — e.g. `/usr/local/bin/gh` — by basename).
+
+This is deliberately a MUCH lighter heuristic than
+`hooks/lib/pre_commit_detect.py`'s `is_git_commit_command` — that module
+went through five adversarial hardening rounds (`<shell> -c` unwrapping,
+command substitution, I/O redirection before the command word, `-C`/global
+option chaining, ...) specifically for `git commit`'s much larger and more
+security-sensitive command-shape surface (a missed detection there let a
+commit land with no review corroboration at all). `gh pr create` has a much
+narrower realistic invocation shape in practice, and the trigger point this
+module guards is a human/agent-driven "open a PR" action, not a background
+`git commit` that fires many times per session — so the cost/benefit of
+matching that same adversarial-hardening investment here is different.
+
+KNOWN RESIDUAL GAP, disclosed rather than silently accepted (mirrors this
+repo's own convention for `pre_commit_detect.py`'s own disclosed gaps): this
+detector does NOT unwrap `<shell> -c '...'`, command substitution
+(`$(...)`/backticks), `eval`/`xargs`, I/O redirection before the command
+word, or a `gh` alias/wrapper script — any of those can still reach `gh pr
+create` undetected. A future round of adversarial review (correctness-review
+/ security-review) should extend this the same way #1801 extended
+`pre_commit_detect.py`, if this trigger point proves to need it in practice.
+
+Stdlib-only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+
+# Bare shell separators — `;`, `&&`, `||`, `|`, and a bare newline — split one
+# Bash payload into independently-evaluated segments. Quote-aware: a
+# separator character INSIDE a quoted string is never a boundary.
+_SEPARATOR_RE = re.compile(r"(;|&&|\|\||\||\n)")
+
+_ENV_ASSIGNMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+
+
+def _split_on_separators(command: str) -> list[str]:
+    """Quote-aware split on `;`/`&&`/`||`/`|`/`&`/newline — a separator
+    INSIDE a single- or double-quoted string is never treated as a
+    boundary.
+
+    Two fixes (issue #1904 Bug 3 — this is the SOLE trigger point for the
+    entire review gate now that `pre_commit_review.py` is a no-op, so a
+    missed detection here is a complete, silent bypass):
+
+    1. Bare `&` (background) is a real shell separator — `true &
+       gh pr create --title x` used to stay one segment (with `true` as
+       `tokens[0]`), missing the `gh pr create` entirely. `&&` is checked
+       BEFORE bare `&` in the tuple below, so `&&` still matches as the
+       two-character operator it is; only a genuinely bare `&` falls
+       through to the new single-character case.
+    2. The backslash-escape exemption on a closing quote now applies ONLY
+       when the open quote is `"` (double quote). POSIX single quotes have
+       NO escape mechanism at all — `echo 'a\'` closes the quote at that
+       `'` in real bash regardless of the preceding backslash, so treating
+       it as still-open (the old, quote-character-agnostic check) let a
+       genuinely-closed single-quoted region swallow the rest of the
+       command, including a `;`-separated `gh pr create` that followed.
+    """
+    segments: list[str] = []
+    current: list[str] = []
+    quote: str | None = None
+    i = 0
+    while i < len(command):
+        ch = command[i]
+        if quote is not None:
+            current.append(ch)
+            if ch == quote and (
+                quote == "'" or i == 0 or command[i - 1] != "\\"
+            ):
+                quote = None
+            i += 1
+            continue
+        if ch in ("'", '"'):
+            quote = ch
+            current.append(ch)
+            i += 1
+            continue
+        matched = None
+        for sep in ("&&", "||", ";", "|", "\n", "&"):
+            if command.startswith(sep, i):
+                matched = sep
+                break
+        if matched is not None:
+            segments.append("".join(current))
+            current = []
+            i += len(matched)
+            continue
+        current.append(ch)
+        i += 1
+    segments.append("".join(current))
+    return segments
+
+
+def _real_command_tokens(segment: str) -> list[str] | None:
+    """Tokenize one segment and skip leading `NAME=value` env-assignment
+    prefixes, returning the remaining tokens (the command and its
+    arguments), or `None` if the segment doesn't tokenize (unbalanced
+    quoting)."""
+    try:
+        tokens = shlex.split(segment, posix=True)
+    except ValueError:
+        return None
+    i = 0
+    while i < len(tokens) and _ENV_ASSIGNMENT_RE.match(tokens[i]):
+        i += 1
+    return tokens[i:]
+
+
+def is_gh_pr_create_command(command: str) -> bool:
+    """True if any shell-separator-delimited segment of `command` invokes
+    `gh pr create` (a path-qualified `gh`, e.g. `/usr/local/bin/gh`, is
+    recognized by basename)."""
+    for segment in _split_on_separators(command):
+        tokens = _real_command_tokens(segment)
+        if not tokens:
+            continue
+        gh_token = tokens[0].replace("\\", "/").rsplit("/", 1)[-1]
+        if gh_token != "gh":
+            continue
+        if len(tokens) >= 3 and tokens[1] == "pr" and tokens[2] == "create":
+            return True
+    return False
+
+
+__all__ = ("is_gh_pr_create_command",)

package/hooks/lib/git_safe_diff.py

@@ -0,0 +1,123 @@
+"""hooks/lib/git_safe_diff.py — shared security-pinned `git diff --cached`
+flags (#1477, extracted from `pre_commit_review.py`'s `_staged_names()` and
+`review_gate_hash.py`'s `review_gate_hash()`).
+
+Both call sites need `git diff --cached` to see the FULL staged changeset —
+not a config-narrowed or driver-rewritten view of it. Prior to this module
+the two functions hand-duplicated the same security-critical flags, kept in
+sync only by comment convention (each function's own docstring cross-
+referenced the other's) — exactly the class of gap the #1461 fifth security
+re-review had to catch for `--ignore-submodules` on both call sites
+separately. A future flag fix applied to one call site and forgotten on the
+other is now structurally impossible: there is only one place these flags
+are written.
+
+`-c diff.relative=false`: without it, a repo/global `diff.relative=true`
+config silently scopes and relativizes `git diff` output to the
+invocation's cwd, truncating the result when either hook runs from a
+subdirectory.
+
+`--ignore-submodules=none`: the config-only form (`-c
+diff.ignoreSubmodules=none`) does NOT suffice — it is overridden by a
+per-submodule `submodule.<name>.ignore` (in `.git/config`) OR by an
+`ignore` key in a COMMITTED `.gitmodules` file, neither of which needs
+local git-config write access (a hostile PR can ship the latter). Only the
+command-line option beats both. Without it, a changeset consisting only of
+a submodule pointer bump (importing arbitrary third-party code) is either
+omitted from `_staged_names()`'s file list entirely, or hashed identically
+to no change at all by `review_gate_hash()`.
+
+`--no-color`/`--no-ext-diff`/`--no-textconv` are NOT included here — they
+only matter to a caller that reads the diff's rendered CONTENT
+(`review_gate_hash()`); `_staged_names()`'s `--name-only` output is
+unaffected by diff rendering or textconv drivers, so it never needed them.
+Each caller passes its own `extra_flags` for exactly this kind of
+caller-specific need; only the flags both call sites actually share live
+here.
+
+`target` (#1476): defaults to `"--cached"` (HEAD vs. index — every caller
+above needs this and none passed anything else, so the default preserves
+their exact original argv). A caller can pass a different comparison —
+`target=None` (bare `git diff` — index vs. working tree) or any other ref
+expression (e.g. `review_gate_hash.py`'s `branch_diff_gate_hash()`, which
+passes `f"{base_ref}...HEAD"`). Same shared safety flags either way — the
+vulnerability class (`diff.relative`, submodule-ignore config, external
+diff drivers) doesn't care which two trees are being compared.
+
+`review_gate_hash.py`'s `working_tree_gate_hash()` (`target="HEAD"`, added
+#1476 for `git commit -a`/pathspec-form-commit detection) was deleted in
+#1904 once `pre_commit_review.py` — its sole caller — was retired to a
+no-op by #1886's PR-time gate migration; `target`'s generality here is
+otherwise unchanged.
+
+Stdlib only.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+
+# `-c diff.relative=false` must precede the `diff` subcommand — see module
+# docstring.
+GIT_CONFIG_OVERRIDES = ("-c", "diff.relative=false")
+
+# Must come after the target and any caller-specific extra flags — see
+# module docstring for why the command-line form is required.
+GIT_IGNORE_SUBMODULES_FLAG = "--ignore-submodules=none"
+
+
+def run_safe_git_diff(
+    extra_flags: Sequence[str],
+    cwd: str | Path | None = None,
+    text: bool = False,
+    target: str | None = "--cached",
+    timeout: float | None = None,
+) -> subprocess.CompletedProcess:
+    """Run `git diff [target]` with the shared safety flags, plus
+    caller-specific `extra_flags` inserted between the target and the
+    trailing `--ignore-submodules=none` — preserves each existing caller's
+    original argv order exactly (`_staged_names()`:
+    `[..., "--cached", "--name-only", "--ignore-submodules=none"]`;
+    `review_gate_hash()`:
+    `[..., "--cached", "--no-color", "--no-ext-diff", "--no-textconv",
+    "--ignore-submodules=none"]`).
+
+    `target=None` omits the target argument entirely (bare `git diff` —
+    index vs. working tree); any other string (`"--cached"`, `"HEAD"`, ...)
+    is inserted as-is right after `diff`.
+
+    `timeout` (#1663): seconds to wait before `subprocess.run` raises
+    `TimeoutExpired`. Defaults to `None` (wait forever), preserving every
+    pre-existing caller's behavior exactly. Only `normalized_gate_hash()`
+    passes a value today — it is the one caller that asks git for
+    whole-file context (`--unified=100000`), so it is the one caller whose
+    runtime scales with repository content rather than with changeset size.
+    `TimeoutExpired` propagates to the caller for the same reason a launch
+    failure does: this helper builds and runs the safe argv, it does not
+    decide what a given caller should do about a slow git.
+
+    Raises on subprocess launch failure — callers keep their own
+    try/except around this call, since `_staged_names()` and
+    `review_gate_hash()` intentionally differ in how they handle that
+    failure (fail-closed `None` vs. a byte-parity empty-input hash); this
+    helper only builds and runs the safe argv, it does not decide how a
+    launch failure should be reported.
+    """
+    argv = ["git", *GIT_CONFIG_OVERRIDES, "diff"]
+    if target is not None:
+        argv.append(target)
+    argv.extend(extra_flags)
+    argv.append(GIT_IGNORE_SUBMODULES_FLAG)
+    return subprocess.run(
+        argv,
+        cwd=str(cwd) if cwd is not None else None,
+        capture_output=True,
+        check=False,
+        text=text,
+        timeout=timeout,
+    )
+
+
+__all__ = ("GIT_CONFIG_OVERRIDES", "GIT_IGNORE_SUBMODULES_FLAG", "run_safe_git_diff")

package/hooks/lib/instrument_log.py

@@ -0,0 +1,66 @@
+"""instrument_log — fail-open JSONL rows for benefit-measurement streams (#2201).
+
+The smallest logging addition that makes a number exist: each caller appends
+one compact row to a named ``.claude/metrics/<stream>.jsonl`` and nothing
+else changes — no stdout, no exit code, no control flow. Any failure (bad
+cwd, unwritable directory, disk full) is swallowed. Streams and row shapes
+are documented in ``knowledge/telemetry-schema.md``.
+
+Kept separate from ``boundary_events.py`` on purpose: a ``record`` row there
+is read by the review-gate corroboration path, so observational measurement
+rows must not share that stream.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+import artifact_paths
+import plugin_version
+
+#: Closed set of stream names this module may write.
+STREAMS = frozenset({
+    "subagent-stops",
+    "skill-injection",
+    "ledger-skips",
+    "checkpoint-aborts",
+})
+
+
+def append_row(stream: str, row: dict, cwd: str | Path | None = None,
+               session_id: str | None = None) -> bool:
+    """Append ``row`` (plus ``ts``/``plugin_version``/``session_id``) to
+    ``.claude/metrics/<stream>.jsonl``. Returns whether a row was written;
+    never raises."""
+    if stream not in STREAMS:
+        return False
+    try:
+        base = Path(cwd) if cwd else Path.cwd()
+        log = artifact_paths.resolve_file("metrics", f"{stream}.jsonl", base)
+        log.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "plugin_version": plugin_version.shipped_version(),
+            **row,
+        }
+        if session_id:
+            payload["session_id"] = session_id
+        line = json.dumps(payload, separators=(",", ":")) + "\n"
+        fd = os.open(log, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o644)
+        try:
+            os.write(fd, line.encode("utf-8"))
+        finally:
+            os.close(fd)
+        return True
+    except Exception:  # noqa: BLE001 — fail-open by design, see module docstring
+        return False

package/hooks/lib/iteration_journal_gate.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""iteration_journal_gate.py — hard per-iteration journal gate (#1168).
+
+`/autoship`'s per-issue loop and `/ship`'s per-phase loop are model-authored
+control flow inside a skill, not a tool call the PreToolUse/PostToolUse
+harness intercepts — there is no hook-registration point distinct from any
+other `Skill` invocation to gate specifically. This mirrors the same
+constraint `workflow_state.py` (#1166) already documents for its
+model-authored `record` append: enforcement lives in a library the skill's
+prose invokes via CLI before it may advance, not in `settings.json`.
+
+Two operations:
+    record  — append a structured decision entry (what was attempted, the
+              outcome, the next action) for the current round/iteration to
+              `.claude/metrics/iteration-journal.jsonl`. Fail-open: an append error
+              never raises into the calling skill.
+    check   — hard-block: exit 1 (and emit a `boundary-events.jsonl` "block"
+              record via `emit_boundary_event`) unless at least one entry
+              exists for the given `--round-id`. Exit 0 (allowed) otherwise.
+
+Complements, does not replace, `progress-guardian` (advisory, plan-step-keyed).
+This gate is per-iteration, hard-blocking, and scoped to `/autoship`/`/ship`.
+
+Stdlib only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+_LIB_DIR = Path(__file__).resolve().parent
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+import artifact_paths
+import plugin_version
+from atomic_state import append_line_locked
+from boundary_events import emit_boundary_event
+
+_LOG_NAME = "iteration-journal.jsonl"
+_DELAY_ENV_VAR = "DEV_TEAM_ITERATION_JOURNAL_TEST_DELAY_MS"
+
+
+def _isoformat_utc() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _log_path(cwd, migrate: bool = True) -> Path:
+    base = Path(cwd) if cwd else Path.cwd()
+    return artifact_paths.resolve_file("metrics", _LOG_NAME, base, migrate=migrate)
+
+
+def record_iteration_entry(
+    cwd,
+    round_id: str,
+    attempted: str,
+    outcome: str,
+    next_action: str,
+    session_id: str | None = None,
+) -> None:
+    """Append one compact JSON line recording this iteration's decision.
+
+    Fail-open: any error (bad `cwd`, unwritable `.claude/metrics/`, disk
+    full, etc.) is swallowed silently — an append failure must never crash
+    the autonomous loop calling this.
+
+    Args:
+        cwd: Directory whose `.claude/metrics/` subdirectory receives the
+            entry.
+        round_id: Identifier for the current round/iteration (e.g.
+            `/autoship`'s round_id, `/ship`'s issue identifier).
+        attempted: Short structured string — what was attempted this
+            iteration.
+        outcome: Short structured string — what happened.
+        next_action: Short structured string — what happens next.
+        session_id: Optional opaque session ID, enabling joins with
+            `boundary-events.jsonl` / `cost-metering.jsonl`.
+    """
+    try:
+        log = _log_path(cwd)
+        log.parent.mkdir(parents=True, exist_ok=True)
+
+        payload = {
+            "ts": _isoformat_utc(),
+            "round_id": round_id,
+            "attempted": attempted,
+            "outcome": outcome,
+            "next_action": next_action,
+            "plugin_version": plugin_version.shipped_version(),
+        }
+        if session_id:
+            payload["session_id"] = session_id
+
+        append_line_locked(
+            log, json.dumps(payload, separators=(",", ":")) + "\n", delay_env_var=_DELAY_ENV_VAR
+        )
+    except Exception:  # noqa: BLE001, S110 — fail-open by design, see module docstring
+        pass
+
+
+def _read_entries(log: Path) -> list:
+    if not log.is_file():
+        return []
+    entries = []
+    for line in log.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entries.append(json.loads(line))
+        except (json.JSONDecodeError, ValueError):
+            continue
+    return entries
+
+
+def check_iteration_journal(
+    round_id: str, cwd=None, log_path: str | None = None
+) -> tuple[bool, str]:
+    """Whether >=1 journal entry exists for `round_id`.
+
+    Returns:
+        `(True, "ok")` when a matching entry exists (advancement allowed).
+        `(False, "iteration-journal-missing")` otherwise (advancement
+        blocked).
+    """
+    log = Path(log_path) if log_path else _log_path(cwd, migrate=False)
+    for entry in _read_entries(log):
+        if entry.get("round_id") == round_id:
+            return True, "ok"
+    return False, "iteration-journal-missing"
+
+
+def cmd_record(args) -> int:
+    record_iteration_entry(
+        args.cwd,
+        args.round_id,
+        args.attempted,
+        args.outcome,
+        args.next_action,
+        args.session,
+    )
+    return 0
+
+
+def cmd_check(args) -> int:
+    allowed, reason = check_iteration_journal(args.round_id, args.cwd, args.log)
+    print(json.dumps({"allowed": allowed, "reason": reason}))
+    if allowed:
+        return 0
+
+    try:
+        emit_boundary_event(
+            args.cwd,
+            hook="iteration_journal_gate",
+            tool="Skill",
+            decision="block",
+            matched_rule="iteration-journal-missing",
+            session_id=args.session,
+        )
+    except Exception:  # noqa: BLE001, S110 — fail-open by design
+        pass
+    return 1
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("record", help="Append one iteration decision entry.")
+    p.add_argument("--cwd", default=None)
+    p.add_argument("--round-id", dest="round_id", required=True)
+    p.add_argument("--attempted", required=True)
+    p.add_argument("--outcome", required=True)
+    p.add_argument("--next-action", dest="next_action", required=True)
+    p.add_argument("--session", default=None)
+    p.set_defaults(func=cmd_record)
+
+    p = sub.add_parser(
+        "check",
+        help="Hard-block unless a journal entry exists for --round-id.",
+    )
+    p.add_argument("--cwd", default=None)
+    p.add_argument("--log", default=None)
+    p.add_argument("--round-id", dest="round_id", required=True)
+    p.add_argument("--session", default=None)
+    p.set_defaults(func=cmd_check)
+
+    parsed = ap.parse_args(argv)
+    return parsed.func(parsed)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())