agentseed-mcp 0.3.0

package/README.zh.md

@@ -0,0 +1,306 @@
+<div align="center">
+
+<img src="docs/logo.png" width="96" alt="AgentSeed logo">
+
+# AgentSeed
+
+**AI 编码智能体的反幻觉闸门。**
+
+AI 会编造不存在的 API，会不跑任何测试就说"全部通过"，会自信地交付
+虚假代码。**AgentSeed 就是在"完成"之前拦截这一切的闸门**——一个零依赖插件，
+在任务被标记为"完成"之前先验证代码，让"完成"= **可观测事实**，而非自说自话。
+
+[![License](https://img.shields.io/badge/license-Apache_2.0-green)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.3.0-blue)](https://gitcode.com/badhope/AgentSeed/releases)
+[![CI](https://github.com/Morningstar202604/AgentSeed/actions/workflows/ci.yml/badge.svg)](https://github.com/Morningstar202604/AgentSeed/actions/workflows/ci.yml)
+[![Platforms](https://img.shields.io/badge/platform-Cursor%20%7C%20VS%20Code%20%7C%20Claude%20Code%20%7C%20Copilot-blue)](https://agent-plugins.org)
+
+[English](./README.md) · **中文** · [日本語](./README.ja.md)
+
+⭐ **觉得有用？点个 Star——让更多开发者在上线幻觉代码之前找到护栏。**
+
+</div>
+
+---
+
+## 为什么你需要它
+
+LLM 会幻觉——放到代码里就是**编造的 API、未定义的标识符、虚假的测试通过、
+自信的过度声明**：
+
+- **15.1%** 的代码幻觉是调用不存在的、或从未导入的 API（[arXiv:2404.00971](https://arxiv.org/abs/2404.00971)）。
+- **不足 10%** 的幻觉代码会挂掉测试——**约 90% 能溜过 CI**（[arXiv:2404.00971](https://arxiv.org/abs/2404.00971)）。
+- **60%+** 的模型输出错误**表面上看不出来**（FAVA，[SoK](https://arxiv.org/abs/2502.18468)）。
+
+纯提示词护栏是"软"的：模型可以嘴上答应验证、然后跳过。
+**AgentSeed 把指令绑成一道"硬闸"**——证据来自真正运行的代码，而不是模型的自述。
+
+## 30 秒看懂 AgentSeed 是什么
+
+一个即插即用的 [Agent Plugins](https://agent-plugins.org) 1.0.0 插件
+（Skill + MCP 服务器 + 可选的客户端 Hook + CI 门禁），兑现三个承诺：
+
+| 承诺 | 如何兑现 |
+| --- | --- |
+| **🚫 不编造 API** | `verify_code` 用 **12+ 种语言**解析你的代码，标记任何"被调用却从未定义/导入"的符号 |
+| **🚫 不假报"完成"** | `scan_hallucination` 拦截占位代码、过度声明与虚构内容（**中英双语**）；`sandbox_run` 用真实执行证明运行时声明 |
+| **🚫 不跳过验证** | Skill 约束流程、**客户端 Hook** 在 `Write`/`Edit` 落盘前拦截、`guard_cli gate` 用退出码在 CI 强制同一套规则 |
+
+它还填补了 1.0.0 规范故意留下的两个空白：
+
+| Agent Plugins 1.0.0 的空白 | AgentSeed 的答案 |
+| --- | --- |
+| 没有强制机制（skill 可做可不做） | `verify-before-code` skill + 可选的**客户端强制 Hook**，让验证不可跳过 |
+| 没有官方合规 linter | `check_plugin` 是**第一个严格的 1.0.0 linter**——而且 AgentSeed 通过了自己的 linter（`ok: true`） |
+
+## 看它现场抓幻觉
+
+```python
+# 你的编码智能体刚刚"写完"这段——它调用了 magic_unknown()，
+# 一个不存在、也从未导入的 API：
+
+def f():
+    return magic_unknown()      # ← 幻觉 API
+
+# AgentSeed 在任务被标记为"完成"之前：
+$ verify_code(source=..., language="python")
+{
+  "language": "python",
+  "suspects": ["magic_unknown"]       # ← 抓到，阻断
+}
+```
+
+```text
+# 智能体的"完成声明"也活不过这一关：
+"The feature is production ready, all tests pass. Trust me."
+
+$ scan_hallucination(source=...)
+{
+  "hits": [
+    {"word": "all tests pass",   "group": "oversold",  "line": 1},
+    {"word": "production ready", "group": "oversold",  "line": 1},
+    {"word": "trust me",         "group": "oversold",  "line": 1}
+  ],
+  "clean": false                        # ← 抓到，阻断
+}
+```
+
+判定是**测出来的，不是吹出来的**：在固定种子的合成语料上（5 类缺陷、
+100 个缺陷模块 + 40 个干净模块），AgentSeed 得分
+**precision 1.0 · recall 1.0**（tp=100, fp=0, fn=0）——并有回归测试锁定。
+方法与诚实边界见 [docs/BENCHMARK.md](./docs/BENCHMARK.md)。
+
+## 闸门如何工作
+
+1. **写码前** —— 加载 SDD 契约，用一句话陈述。
+2. **实现** —— 只写真代码：无占位、无编造 API。
+3. **说"完成"前** —— 跑 `verify_code` + `scan_hallucination`；运行时声明用
+   `sandbox_run` 实证；结构化输出用 `schema_validate` 校验。
+4. **语言审计** —— 完成报告必须附证据；禁用夸大词汇。
+5. 只有当**所有检查都通过**，任务才允许被标记为完成。
+
+## 快速开始
+
+**方案 A —— 下载发布包（无需 git）：**
+
+```bash
+# 从 https://gitcode.com/badhope/AgentSeed/releases 取最新资产
+# 或用安装器一键接入你的客户端：
+bash install.sh --client auto --hooks        # macOS / Linux
+./install.ps1 -Client auto -Hooks            # Windows PowerShell
+# --client: claude | opencode | cursor | manual
+# --hooks / -Hooks: 同时注册 Claude Code 强制 Hook
+```
+
+**方案 B —— 克隆：**
+
+```bash
+git clone https://gitcode.com/badhope/AgentSeed.git
+# 镜像：https://gitcode.com/badhope/AgentSeed · https://gitee.com/badhope/AgentSeed
+```
+
+1. 把 `AgentSeed/` 目录**丢进**任意支持 Agent Plugins 的客户端
+   （Cursor、VS Code、Claude Code、Copilot…）。无需构建、无需安装。
+2. 客户端从 `plugin.json` + `mcp.json` 自动发现 `verify-before-code` skill
+   与 `agentseed` MCP 服务器。
+3. **完事。** 从此每个编码任务都被闸门约束：契约 → 实现 → 验证 → 证据。
+
+独立运行，或用人机同规的 CI 门禁：
+
+```bash
+python3 server/guard_engine.py              # 自检演示
+python3 -m unittest discover -s server      # 160+ 单元测试
+python3 server/guard_cli.py gate --root .   # CI 等价硬门禁
+python3 server/guard_cli.py check . --ci    # 仅插件合规
+python3 server/guard_cli.py scan src/ --strict
+```
+
+> **Windows 提示：** `mcp.json` 用 `python3` 启动服务器。很多 Windows 安装的
+> 该别名是 Microsoft Store 占位程序；把 `command` 改成
+> `["python", "server/guard_server.py"]` 或指向你的解释器绝对路径即可。
+
+## 8 个 MCP 工具
+
+零**必需**依赖——纯 Python 标准库；可选依赖把两个工具升级为行业标准引擎
+（见下）。
+
+| 工具 | 拦截什么 | 技术 |
+| --- | --- | --- |
+| `verify_code` | 编造的 API / 未定义符号 | Python AST + 配置驱动的通用词法扫描（12+ 语言） |
+| `check_contract` | 违反书面规范 | requires/prohibits 契约校验 |
+| `check_imports` | 幻觉包导入（slopsquatting 抢注） | stdlib + known_packages 白名单校验 |
+| `scan_hallucination` | 占位代码、夸大声称、虚构内容 | 3 组 28+ 信号，中英双语 |
+| `check_plugin` | 不合规的插件打包 | 严格 1.0.0 linter |
+| `sandbox_run` | 什么都没跑就说"测试通过" | 确定性执行通道（有界内存输出） |
+| `schema_validate` | 不合法的结构化输出 | JSON Schema 校验 |
+| `record_verification` | 没有持久化证据链 | `PLUGIN_DATA` 下 JSONL 审计轨迹 |
+
+### 语言覆盖（诚实范围）
+
+| 语言 | `verify_code` 分析 |
+| --- | --- |
+| Python | 完整 AST 作用域遍历（装 pyflakes 则合并），带行号 |
+| TypeScript / JavaScript | 词法正则扫描（有明确记录的误报类别） |
+| Go · Rust · Java · C · C++ · C# · PHP · Ruby · Kotlin · Swift | 配置驱动的通用词法扫描 |
+| 任何其他语言 | 加一条 `LangSpec` 注册即可——无需改引擎 |
+
+诚实边界：属性调用（`obj.m()`）、宏、跨文件符号不分析；Ruby 无括号调用已支持。
+
+诚实边界：属性调用（`obj.m()`）、宏、跨文件符号不分析；Ruby 无括号调用已支持。
+
+### 真的能抓其他语言——实测为证
+
+同一规则适用于所有注册语言：只要「裸调用了从未定义的符号」，无论什么语法，都是幻觉：
+
+```python
+# Go       detect_undefined_symbols("func main() { process_data() }", "go")  -> ["process_data"]
+# Rust     fn main() { let x = load_config() }        -> ["load_config"]
+# Java     class A { void m() { connect_db() } }      -> ["connect_db"]
+# C        int main() { ghost(); return 0; }          -> ["ghost"]
+# Kotlin   fun main() { fetch_users() }               -> ["fetch_users"]
+# Swift    func run() { connect() }                   -> ["connect"]
+# Ruby     def run; authenticate; end                 -> ["authenticate"]
+# TypeScript function run() { connectDb() }           -> ["connectDb"]
+```
+
+已实测 Go · Rust · Java · C · C++ · C# · PHP · Ruby · Kotlin · Swift ·
+TypeScript——每种语言都能抓出自己的幻觉调用，且各语言干净代码**零误报**。
+
+
+## 客户端强制 Hook 模式
+
+Skill 靠"劝"，**Hook 在客户端边界"强制执行"**。把 AgentSeed 注册为
+Claude Code hook，每个 `Write`/`Edit`/`MultiEdit` 都会自动被扫描——
+任何提示词都无法跳过：
+
+```bash
+python3 server/guard_hook.py register --client claude   # 幂等，合并进 settings
+python3 server/guard_hook.py --file path/to/source.py   # 直接扫描任意文件
+```
+
+- **PreToolUse** 在内容落盘**之前**检查；阻断性发现退出码 `2`，智能体必须
+  修复被标记的行。
+- **PostToolUse** 对无内联内容的写路径再次检查落盘文件。
+- **失败策略（诚实）：** 基础设施问题（stdin 畸形、文件不可读）永不阻断
+  工作——fail-open；只有真实的扫描发现才阻断。
+
+## 平台支持
+
+| 客户端 | 状态 | 说明 |
+| --- | --- | --- |
+| Claude Code | ✅ 已验证 | skills + MCP + 可选强制 Hook |
+| opencode | ✅ 已验证 | `~/.config/opencode/opencode.json` |
+| Cursor | ⚪ 规范兼容* | 拷入项目；尚无稳定插件目录 |
+| VS Code (+Copilot) | ⚪ 规范兼容* | MCP 支持逐步开放 |
+| Cline / Windsurf | ⚪ 规范兼容* | stdio 服务器条目可直接映射 |
+
+\* 诚实标注：格式与规范兼容、预期可用，但维护者尚未实测。你若验证成功，
+欢迎 PR 更新此表。
+
+## 可选依赖
+
+```bash
+pip install -r server/requirements.txt
+```
+
+| 扩展 | 升级效果 | 无它时 |
+| --- | --- | --- |
+| `jsonschema` | `schema_validate` → 完整 Draft 2020-12 | 内置子集校验器 |
+| `pyflakes` | `verify_code` → pyflakes F821 分析 | 内置 AST 遍历 |
+| `pyyaml` | SKILL.md frontmatter → 完整 YAML | 内置轻量解析器 |
+
+## 配置（`agentseed.config.json`）
+
+| 键 | 作用 |
+| --- | --- |
+| `allowlist` | 扫描排除（替换内置测试惯用语清单） |
+| `severities` | 按组覆盖严重度（`error` \| `warning` \| `info`） |
+| `timeout` | 默认 `sandbox_run` 超时，秒（1–120） |
+| `extra_tokens` | 运行时扩展幻觉词池 |
+| `suppress_symbols` | `verify_code` 永不标记的名字（在 `suppressed` 中可见） |
+| `known_packages` | `check_imports` 视为已知的包（stdlib + 常见包 + 本列表） |
+| `sandbox_allowed_prefixes` | `sandbox_run` 可启动的**可执行文件白名单**；PATH 解析、分隔符边界强制（缺省=不限） |
+| `sandbox_env` | `"inherit"` \| `"scrub"` —— `scrub` 在启动前剔除疑似凭据的环境变量 |
+
+未知键会在 stderr 告警——拼错的键绝不会被静默忽略。
+
+> ⚠️ **安全提示：** `sandbox_run` 以你的用户权限执行真实进程。客户端必须将其
+> 置于用户批准之后；共享/CI 环境请设置 `sandbox_allowed_prefixes`。命令会先经
+> `PATH` 解析为绝对路径再执行，恶意 `cwd` 无法用植入的可执行文件冒充白名单
+> 命令；未匹配/无法解析的命令不执行直接拒绝（退出码 -10）。
+
+## 兼容与优雅降级
+
+| 宿主能力 | 得到什么 |
+| --- | --- |
+| 完整 Agent Plugins | 即插即用：skill + MCP 自动发现，`${PLUGIN_DATA}` 配置生效 |
+| 支持 MCP 的客户端 | 注册即得全部 8 个工具 |
+| 仅支持 skill 的客户端 | skill 流程；验证降级为 shell 调用 `guard_cli.py` |
+| 纯终端 / CI | 带退出码的 CLI 门禁 |
+
+## 内置护栏库（EN / 中文 / 日本語）
+
+`PROMPT-POOL`（20+ 条即贴即用的护栏提示）· `HALLUCINATION-PATTERNS`
+（5 类失败模式目录）· `VERIFICATION-CHECKLIST`（可执行的收尾检查清单）·
+`SDD-CONTRACT`（每个任务必须满足的契约）· `VENDOR-SOLUTIONS`
+（厂商技术落地地图）。
+
+## 为什么选 AgentSeed 而非替代方案
+
+| | 纯提示词护栏 skill | 静态 import linter（MCP） | **AgentSeed** |
+| --- | --- | --- | --- |
+| 触碰代码 | ❌ 仅提示 | ✅ import 图 | ✅ AST + 词法（12+ 语言） |
+| 跑验证工具 | ❌ | lint 门禁 | ✅ 8 个 MCP 工具含沙箱 |
+| 幻觉语言扫描 | ❌ | ❌ | ✅ stub/oversold/fabricated，中英双语 |
+| 强制力 | 软（skill 文本） | CI 门禁 | **硬**：skill + MCP + hook + CLI 退出码 |
+| 1.0.0 合规 linter | ❌ | ❌ | ✅ 首个 |
+
+## FAQ
+
+**需要特定 LLM 吗？** 不需要——客户端无关、模型无关；闸门由 skill + MCP +
+hook + CI 执行，与具体模型无关。
+
+**零依赖？** 是的。MCP 服务器是纯 Python 标准库。
+
+**能和现有的 AGENTS.md / CLAUDE.md 共存吗？** 能——它们是互补的。那些文件
+承载项目事实（散文、说服力）；AgentSeed 承载行为契约与硬强制。
+
+**怎么扩展到新语言？** 在 `server/engine/symbols.py` 加一条 `LangSpec` 注册
+——一份配置，零引擎改动。
+
+## 参与贡献
+
+欢迎 Issue、PR 与想法——或者为尚未收录的幻觉模式开一个 issue。
+详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## 许可证
+
+Apache-2.0 © AgentSeed。见 [LICENSE](./LICENSE)。
+
+---
+
+<div align="center">
+
+⭐ **如果 AgentSeed 帮你拦下了要上线的幻觉代码，点个 Star——这是"护栏有用"最好的信号。**
+
+</div>

package/bin/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * agentseed-mcp launcher.
+ *
+ * The AgentSeed server itself is Python (stdlib-only). This shim exists so
+ * npm-based clients can spawn it the standard way:
+ *
+ *   npx agentseed-mcp
+ *
+ * Requires Python 3.9+ on PATH (override with the PYTHON env var).
+ */
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+
+const py = process.env.PYTHON || (process.platform === "win32" ? "python" : "python3");
+const server = path.join(__dirname, "..", "server", "guard_server.py");
+
+const child = spawn(py, [server], { stdio: "inherit" });
+
+child.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    console.error(
+      `[agentseed-mcp] Python interpreter "${py}" not found on PATH.\n` +
+        `Install Python 3.9+ or set PYTHON=/path/to/python.`
+    );
+    process.exit(1);
+  }
+  throw err;
+});
+
+child.on("exit", (code) => process.exit(code == null ? 1 : code));
+
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => child.kill(sig));
+}

package/mcp.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "agentseed": {
+      "type": "stdio",
+      "command": "python3",
+      "args": ["server/guard_server.py"],
+      "cwd": "${PLUGIN_ROOT}",
+      "env": {}
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agentseed-mcp",
+  "version": "0.3.0",
+  "description": "Anti-hallucination guardrails for AI coding agents: hybrid Skill + MCP server that forces spec-driven development and verifies code before it is marked done.",
+  "license": "Apache-2.0",
+  "mcpName": "io.gitcode.badhope/agentseed",
+  "bin": {
+    "agentseed-mcp": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "skills/",
+    "plugin.json",
+    "mcp.json",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitcode.com/badhope/AgentSeed.git"
+  },
+  "homepage": "https://gitcode.com/badhope/AgentSeed#readme",
+  "bugs": {
+    "url": "https://gitcode.com/badhope/AgentSeed/issues"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "agentseed",
+  "version": "0.3.0",
+  "description": "Guardrails for coding agents: a hybrid Agent Plugin (Skill + MCP Server) that forces spec-driven development and blocks hallucinated code before it is marked done. Built to the Agent Plugins 1.0.0 spec.",
+  "author": {
+    "name": "AgentSeed",
+    "url": "https://gitcode.com/badhope/AgentSeed"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "guardrail",
+    "anti-hallucination",
+    "spec-driven-development",
+    "code-verification",
+    "mcp",
+    "agent-plugins",
+    "coding-agent"
+  ],
+  "homepage": "https://gitcode.com/badhope/AgentSeed",
+  "repository": "https://gitcode.com/badhope/AgentSeed.git"
+}

package/server/.agentseed/verification-log.jsonl

@@ -0,0 +1,2 @@
+{"ts": "2026-08-26T13:56:04+00:00", "plugin_version": "0.1.1", "task": "protocol test", "checks": [{"tool": "manual", "status": "pass"}]}
+{"ts": "2026-08-27T06:02:49+00:00", "plugin_version": "0.3.0", "task": "protocol test", "checks": [{"tool": "manual", "status": "pass"}]}

package/server/engine/__init__.py

@@ -0,0 +1,64 @@
+"""AgentSeed guard engine — modular package.
+
+Modules:
+  config    — Config loading (load_config, config helpers)
+  symbols   — Undefined symbol detection (detect_undefined_symbols)
+  hallucination — Hallucination word scanning (scan_hallucination_words)
+  plugin    — Agent Plugins 1.0.0 conformance checker (check_plugin_conformance)
+  sandbox   — Deterministic execution channel (sandbox_run)
+  schema    — JSON Schema subset validator (schema_validate)
+
+Public API only: internal helpers stay inside their modules.
+"""
+
+from .audit import VALID_STATUSES, audit_path, record_verification
+from .config import (
+    CONFIG_FILENAME,
+    KNOWN_CONFIG_KEYS,
+    SANDBOX_ENV_MODES,
+    VALID_GROUPS,
+    config_extra_tokens,
+    config_severities,
+    config_str_list,
+    load_config,
+    parse_timeout,
+    sandbox_env_mode,
+    unknown_config_keys,
+)
+from .hallucination import DEFAULT_ALLOWLIST, HALLUCINATION_WORDS, scan_hallucination_words
+from .imports import check_imports
+from .plugin import check_plugin_conformance
+from .sandbox import build_env, kill_tree, resolve_executable, sandbox_run
+from .schema import schema_validate
+from .symbols import defined_symbols, detect_undefined_symbols
+from .version import plugin_version
+
+__all__ = [
+    "CONFIG_FILENAME",
+    "DEFAULT_ALLOWLIST",
+    "HALLUCINATION_WORDS",
+    "KNOWN_CONFIG_KEYS",
+    "SANDBOX_ENV_MODES",
+    "VALID_GROUPS",
+    "VALID_STATUSES",
+    "audit_path",
+    "build_env",
+    "check_plugin_conformance",
+    "check_imports",
+    "config_extra_tokens",
+    "config_severities",
+    "config_str_list",
+    "detect_undefined_symbols",
+    "defined_symbols",
+    "kill_tree",
+    "load_config",
+    "parse_timeout",
+    "plugin_version",
+    "record_verification",
+    "resolve_executable",
+    "sandbox_env_mode",
+    "sandbox_run",
+    "scan_hallucination_words",
+    "schema_validate",
+    "unknown_config_keys",
+]

package/server/engine/audit.py

@@ -0,0 +1,84 @@
+"""AgentSeed verification audit trail (P2-10).
+
+The SDD contract requires a completion report with attached evidence, but
+until now nothing persisted verification history. ``record_verification``
+appends one JSONL line per call to
+
+    ${PLUGIN_DATA}/verification-log.jsonl   (fallback: ./.agentseed/)
+
+creating a tamper-evident-by-append audit trail agents (or CI) can cite.
+Zero dependencies; stdlib only.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+from .version import plugin_version
+
+VALID_STATUSES = {"pass", "fail", "skipped"}
+
+
+def audit_path(data_dir: str | None = None) -> str:
+    base = data_dir or os.environ.get("PLUGIN_DATA") or os.path.join(os.getcwd(), ".agentseed")
+    return os.path.join(base, "verification-log.jsonl")
+
+
+def record_verification(
+    task: str,
+    checks: list[dict] | None = None,
+    summary: str | None = None,
+    data_dir: str | None = None,
+) -> dict:
+    """Append one verification record; returns {"ok", "path", "entries"}."""
+    if not isinstance(task, str) or not task.strip():
+        return {"ok": False, "error": "task must be a non-empty string", "path": "", "entries": 0}
+    clean_checks = []
+    for c in checks if isinstance(checks, list) else []:
+        if not isinstance(c, dict):
+            continue
+        status = c.get("status")
+        if status not in VALID_STATUSES:
+            continue
+        entry = {"tool": str(c.get("tool", "unknown")), "status": status}
+        if isinstance(c.get("summary"), str):
+            entry["summary"] = c["summary"]
+        clean_checks.append(entry)
+    path = audit_path(data_dir)
+    record = {
+        "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        "plugin_version": plugin_version(),
+        "task": task,
+        "checks": clean_checks,
+    }
+    if isinstance(summary, str) and summary:
+        record["summary"] = summary
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except OSError as exc:
+        return {"ok": False, "error": f"cannot write audit log: {exc}", "path": path, "entries": 0}
+    entries = 0
+    try:
+        with open(path, encoding="utf-8") as fh:
+            entries = sum(1 for line in fh if line.strip())
+    except OSError:
+        pass
+    return {"ok": True, "path": path, "entries": entries}
+
+
+def main() -> int:  # pragma: no cover - CLI convenience
+    args = sys.argv[1:]
+    if not args:
+        print(__doc__)
+        return 2
+    print(json.dumps(record_verification(args[0]), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())