zikaron 0.3.0__tar.gz → 0.3.1__tar.gz

{zikaron-0.3.0 → zikaron-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zikaron
-Version: 0.3.0
+Version: 0.3.1
 Summary: Memory and searchable project knowledge for coding agents
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nathan-shapiro/Zikaron
@@ -11,16 +11,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiosqlite==0.22.1
 Requires-Dist: sqlite-vec==0.1.9
-Requires-Dist: fastembed==0.8.0
-Requires-Dist: huggingface_hub==1.26.0
-Requires-Dist: fastmcp==3.4.7
+Requires-Dist: fastembed==0.8.1
+Requires-Dist: huggingface_hub==1.33.0
+Requires-Dist: fastmcp==4.0.10
 Provides-Extra: dev
-Requires-Dist: ruff==0.16.7; extra == "dev"
+Requires-Dist: ruff==0.16.9; extra == "dev"
 Requires-Dist: mypy==2.3.1; extra == "dev"
 Requires-Dist: pytest==9.1.1; extra == "dev"
 Requires-Dist: pytest-cov==7.1.0; extra == "dev"
 Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
-Requires-Dist: hypothesis==6.168.0; extra == "dev"
+Requires-Dist: hypothesis==6.168.3; extra == "dev"
 Requires-Dist: pyyaml==6.0.3; extra == "dev"
 Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "dev"
 Requires-Dist: build==1.3.0; extra == "dev"
@@ -61,6 +61,12 @@ yes, it is out of scope. That store is for what cost somebody time to discover,
 be discovered again by the next agent, at full price. A knowledge base has no such test — it is
 whatever corpus you point it at.
 
+**And, on request, two edit guards for Claude Code** — independent of both stores. One refuses a
+find-replace edit to an authored file (`sed -i`, an inline script, a heredoc into the file) and
+points the agent at `Read` and `Edit`; the other reminds it, after each edit, to re-read what it
+changed. See [Edit guards](#edit-guards-claude-code-on-request); a project may install the memory
+store, the guards, or both.
+
 It runs entirely on your machine: SQLite databases under `.zikaron/`, a local embedding model, and a
 small background service on a Unix socket. **Zikaron reaches the network for exactly one thing** —
 the embedding-model download described under [Install](#install), pinned to one revision and
@@ -124,6 +130,7 @@ reads which one it is addressing before it reads a description. Consolidation ne
 | **service** | A long-running process per project. Holds the embedding model in memory and the databases open, and answers requests over a Unix socket. Starts itself when needed and stops itself when idle. |
 | **MCP server** | Translates the agent's tool calls into requests to the service. One process per agent instance; loads no model. |
 | **hook** | A single-shot executable your agent runs on start, before each message, and — under Claude Code — when it spawns a subagent. Deliberately tiny; loads no model and never touches the databases directly. |
+| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each Bash call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
 | **indexer** | A detached process started per knowledge-base build — by the service on every `add`/`refresh`, whether an agent asked or you did, or by you running the foreground command a build result prints. It outlives the call that started it, loads a model, saturates a core for a minute or more, and exits when the build finishes. If you see one in `ps`, that is a corpus building, not a runaway. |
 
 The service exists for one measured reason: loading the embedding model costs about **780 ms**, and
@@ -235,6 +242,16 @@ cd /path/to/your/project
 zikaron install --project . --harness claude-code    # or: --harness kiro
 ```
 
+Under Claude Code, `--components` adds the [edit guards](#edit-guards-claude-code-on-request), or
+installs them alone; without it you get the memory store only, exactly as before:
+
+```bash
+zikaron install --project . --harness claude-code --components both     # memory and guards
+zikaron install --project . --harness claude-code --components guards   # guards only
+```
+
+Installing one later keeps the other: an install touches only what it was asked for.
+
 **Name it on a first install, rather than leaving it to be detected.** Detection looks for a
 `.kiro/` or `.claude/` directory in the project and for `CLAUDECODE` in the environment, and it
 refuses rather than guessing when neither says. Running from an ordinary terminal, a first install
@@ -334,6 +351,12 @@ and under **Claude Code**:
 | `.claude/settings.local.json` | three hooks — session start, per-message, and per-subagent — plus both approval keys, `enabledMcpjsonServers` and `permissions.allow` |
 | `.mcp.json` | both servers: `zikaron` for your own tools, `zikaron-consolidator` for the consolidation verbs — each marked `alwaysLoad` so their descriptions are in context from the start rather than fetched per tool |
 
+With `--components guards` the install writes `.claude/settings.local.json` alone, and in it only
+hooks: the session-start and per-subagent hooks, which carry a short note about the guards, and the
+two guard hooks — before each Bash call, after each edit. No server, no approval key, no
+consolidator. With `--components both` you get all of the above together, and the start hooks carry
+the write policy and the guards' note.
+
 **`settings.local.json`, not `settings.json`**, and it matters if you commit your settings: the hook
 entries name absolute paths inside *your* virtualenv, so they are meaningless in anyone else's clone.
 The third hook is the one with no kiro counterpart — it hands the write policy to each subagent you
@@ -451,6 +474,39 @@ guard, the receipts and the lease are untouched — but an unauthorized consolid
 tokens and could write a poorly-judged long-term record. `permissions.deny` is **not** the fix: it is
 global and unregisters the tool, after which the consolidator itself refuses to start.
 
+### Edit guards (Claude Code, on request)
+
+`--components guards` (or `both`) installs two deterministic hooks that hold an agent to two rules,
+with no model and no store behind them (`design/edit-guards.md`):
+
+- **A find-replace edit to an authored file is refused** — `sed -i`, `perl -pi`, an inline Python
+  or node script that writes a file, a heredoc or `echo` redirected into one, and a script under
+  `/tmp` or `$TMPDIR` that the command runs and that does any of these. The refusal reaches the
+  agent as the tool's result and tells it to use `Read` and `Edit`, or `Write` for a new file.
+  Paths under `/tmp`, `/var/tmp` and `$TMPDIR` are exempt, and so is a command carrying the
+  override the refusal itself describes, for the files whose bytes a program owns.
+- **After each edit, the agent is reminded** that the file has not been re-read, and asked for one
+  re-read of the edited material once that file's editing is done. A Bash command gets no such
+  reminder, so when the agent overrides a refusal, the guard's acknowledgement names what the
+  command changes and asks for that re-read instead.
+
+They are not a security boundary: a script the guard reads is one run from a scratch directory,
+and a script anywhere else — one of the project's own programs — is never read, by design. A guard
+that fails for any reason allows the call.
+
+They write no log and no store record: a refusal, an override and its reason are in the session's
+own transcript. `zikaron doctor` does not report on them. To see the refusal without a model in
+the loop, hand the guard the payload Claude Code would send it, from the project directory — run
+from a scratch directory such as `/tmp`, the same command is exempt and prints nothing:
+
+```bash
+printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","cwd":"'"$PWD"'","tool_input":{"command":"sed -i s/a/b/ README.md"}}' | zikaron-guard
+```
+
+It prints the deny the agent would read as the command's result. Asking an agent to run `sed -i`
+usually shows something else: told the rule when its session starts, it reaches for `Read` and
+`Edit` without trying.
+
 ### Options
 
 | Flag | Effect |
@@ -462,6 +518,7 @@ global and unregisters the tool, after which the consolidator itself refuses to
 | `--model <id>` | the consolidator's model (default: `claude-sonnet-5` under kiro, `sonnet` under Claude Code) |
 | `--format {object,array}` | **kiro only.** Which hook format to write when the target config has none yet |
 | `--no-trust-tools` | do not pre-approve Zikaron's own tools, so every Zikaron tool call asks permission |
+| `--components {memory,guards,both}` | what to install: the memory store (the default), the edit guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
 | `--force` | replace a symlink at a shipped path, and overwrite entries wired to a different Zikaron install that would otherwise be refused. It also stops merging: a server entry — `.mcp.json`'s, or kiro's `mcpServers` — is replaced **whole**, so a key you added to Zikaron's own entry goes, and under Claude Code a Zikaron hook group is replaced whole, so a hook of your own inside it goes too. Both are named in the output |
 
 Both hook formats kiro accepts are supported, and a config that already uses one keeps it: kiro
@@ -864,6 +921,12 @@ than deleted, because both hold settings that are not Zikaron's. **All three set
 the install writes three** — leaving `enabledMcpjsonServers` behind names two servers that no longer
 exist, which loads nothing and breaks nothing but is not an uninstall.
 
+**The edit guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
+`PostToolUse` hook groups whose command is `zikaron-guard`, and the `SessionStart` and
+`SubagentStart` groups whose command is `zikaron-hook`. To keep the memory store and drop only the
+guards, re-running the installer will not do it — an install never removes a selection — so delete
+the two guard groups and the `--components …` arguments from the two start groups' command.
+
 Note that `rm -rf .zikaron` takes the knowledge bases with it. They are rebuildable — an index is a
 view onto files you still have — but rebuilding one takes minutes per corpus.
 

zikaron-0.3.0/zikaron.egg-info/PKG-INFO → zikaron-0.3.1/README.md

@@ -1,32 +1,3 @@
-Metadata-Version: 2.4
-Name: zikaron
-Version: 0.3.0
-Summary: Memory and searchable project knowledge for coding agents
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/nathan-shapiro/Zikaron
-Project-URL: Repository, https://github.com/nathan-shapiro/Zikaron
-Project-URL: Issues, https://github.com/nathan-shapiro/Zikaron/issues
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiosqlite==0.22.1
-Requires-Dist: sqlite-vec==0.1.9
-Requires-Dist: fastembed==0.8.0
-Requires-Dist: huggingface_hub==1.26.0
-Requires-Dist: fastmcp==3.4.7
-Provides-Extra: dev
-Requires-Dist: ruff==0.16.7; extra == "dev"
-Requires-Dist: mypy==2.3.1; extra == "dev"
-Requires-Dist: pytest==9.1.1; extra == "dev"
-Requires-Dist: pytest-cov==7.1.0; extra == "dev"
-Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
-Requires-Dist: hypothesis==6.168.0; extra == "dev"
-Requires-Dist: pyyaml==6.0.3; extra == "dev"
-Requires-Dist: types-PyYAML==6.0.12.20260906; extra == "dev"
-Requires-Dist: build==1.3.0; extra == "dev"
-Requires-Dist: setuptools==84.0.0; extra == "dev"
-Dynamic: license-file
-
 # Zikaron
 
 [![PyPI](https://img.shields.io/pypi/v/zikaron)](https://pypi.org/project/zikaron/)
@@ -61,6 +32,12 @@ yes, it is out of scope. That store is for what cost somebody time to discover,
 be discovered again by the next agent, at full price. A knowledge base has no such test — it is
 whatever corpus you point it at.
 
+**And, on request, two edit guards for Claude Code** — independent of both stores. One refuses a
+find-replace edit to an authored file (`sed -i`, an inline script, a heredoc into the file) and
+points the agent at `Read` and `Edit`; the other reminds it, after each edit, to re-read what it
+changed. See [Edit guards](#edit-guards-claude-code-on-request); a project may install the memory
+store, the guards, or both.
+
 It runs entirely on your machine: SQLite databases under `.zikaron/`, a local embedding model, and a
 small background service on a Unix socket. **Zikaron reaches the network for exactly one thing** —
 the embedding-model download described under [Install](#install), pinned to one revision and
@@ -124,6 +101,7 @@ reads which one it is addressing before it reads a description. Consolidation ne
 | **service** | A long-running process per project. Holds the embedding model in memory and the databases open, and answers requests over a Unix socket. Starts itself when needed and stops itself when idle. |
 | **MCP server** | Translates the agent's tool calls into requests to the service. One process per agent instance; loads no model. |
 | **hook** | A single-shot executable your agent runs on start, before each message, and — under Claude Code — when it spawns a subagent. Deliberately tiny; loads no model and never touches the databases directly. |
+| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each Bash call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
 | **indexer** | A detached process started per knowledge-base build — by the service on every `add`/`refresh`, whether an agent asked or you did, or by you running the foreground command a build result prints. It outlives the call that started it, loads a model, saturates a core for a minute or more, and exits when the build finishes. If you see one in `ps`, that is a corpus building, not a runaway. |
 
 The service exists for one measured reason: loading the embedding model costs about **780 ms**, and
@@ -235,6 +213,16 @@ cd /path/to/your/project
 zikaron install --project . --harness claude-code    # or: --harness kiro
 ```
 
+Under Claude Code, `--components` adds the [edit guards](#edit-guards-claude-code-on-request), or
+installs them alone; without it you get the memory store only, exactly as before:
+
+```bash
+zikaron install --project . --harness claude-code --components both     # memory and guards
+zikaron install --project . --harness claude-code --components guards   # guards only
+```
+
+Installing one later keeps the other: an install touches only what it was asked for.
+
 **Name it on a first install, rather than leaving it to be detected.** Detection looks for a
 `.kiro/` or `.claude/` directory in the project and for `CLAUDECODE` in the environment, and it
 refuses rather than guessing when neither says. Running from an ordinary terminal, a first install
@@ -334,6 +322,12 @@ and under **Claude Code**:
 | `.claude/settings.local.json` | three hooks — session start, per-message, and per-subagent — plus both approval keys, `enabledMcpjsonServers` and `permissions.allow` |
 | `.mcp.json` | both servers: `zikaron` for your own tools, `zikaron-consolidator` for the consolidation verbs — each marked `alwaysLoad` so their descriptions are in context from the start rather than fetched per tool |
 
+With `--components guards` the install writes `.claude/settings.local.json` alone, and in it only
+hooks: the session-start and per-subagent hooks, which carry a short note about the guards, and the
+two guard hooks — before each Bash call, after each edit. No server, no approval key, no
+consolidator. With `--components both` you get all of the above together, and the start hooks carry
+the write policy and the guards' note.
+
 **`settings.local.json`, not `settings.json`**, and it matters if you commit your settings: the hook
 entries name absolute paths inside *your* virtualenv, so they are meaningless in anyone else's clone.
 The third hook is the one with no kiro counterpart — it hands the write policy to each subagent you
@@ -451,6 +445,39 @@ guard, the receipts and the lease are untouched — but an unauthorized consolid
 tokens and could write a poorly-judged long-term record. `permissions.deny` is **not** the fix: it is
 global and unregisters the tool, after which the consolidator itself refuses to start.
 
+### Edit guards (Claude Code, on request)
+
+`--components guards` (or `both`) installs two deterministic hooks that hold an agent to two rules,
+with no model and no store behind them (`design/edit-guards.md`):
+
+- **A find-replace edit to an authored file is refused** — `sed -i`, `perl -pi`, an inline Python
+  or node script that writes a file, a heredoc or `echo` redirected into one, and a script under
+  `/tmp` or `$TMPDIR` that the command runs and that does any of these. The refusal reaches the
+  agent as the tool's result and tells it to use `Read` and `Edit`, or `Write` for a new file.
+  Paths under `/tmp`, `/var/tmp` and `$TMPDIR` are exempt, and so is a command carrying the
+  override the refusal itself describes, for the files whose bytes a program owns.
+- **After each edit, the agent is reminded** that the file has not been re-read, and asked for one
+  re-read of the edited material once that file's editing is done. A Bash command gets no such
+  reminder, so when the agent overrides a refusal, the guard's acknowledgement names what the
+  command changes and asks for that re-read instead.
+
+They are not a security boundary: a script the guard reads is one run from a scratch directory,
+and a script anywhere else — one of the project's own programs — is never read, by design. A guard
+that fails for any reason allows the call.
+
+They write no log and no store record: a refusal, an override and its reason are in the session's
+own transcript. `zikaron doctor` does not report on them. To see the refusal without a model in
+the loop, hand the guard the payload Claude Code would send it, from the project directory — run
+from a scratch directory such as `/tmp`, the same command is exempt and prints nothing:
+
+```bash
+printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","cwd":"'"$PWD"'","tool_input":{"command":"sed -i s/a/b/ README.md"}}' | zikaron-guard
+```
+
+It prints the deny the agent would read as the command's result. Asking an agent to run `sed -i`
+usually shows something else: told the rule when its session starts, it reaches for `Read` and
+`Edit` without trying.
+
 ### Options
 
 | Flag | Effect |
@@ -462,6 +489,7 @@ global and unregisters the tool, after which the consolidator itself refuses to
 | `--model <id>` | the consolidator's model (default: `claude-sonnet-5` under kiro, `sonnet` under Claude Code) |
 | `--format {object,array}` | **kiro only.** Which hook format to write when the target config has none yet |
 | `--no-trust-tools` | do not pre-approve Zikaron's own tools, so every Zikaron tool call asks permission |
+| `--components {memory,guards,both}` | what to install: the memory store (the default), the edit guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
 | `--force` | replace a symlink at a shipped path, and overwrite entries wired to a different Zikaron install that would otherwise be refused. It also stops merging: a server entry — `.mcp.json`'s, or kiro's `mcpServers` — is replaced **whole**, so a key you added to Zikaron's own entry goes, and under Claude Code a Zikaron hook group is replaced whole, so a hook of your own inside it goes too. Both are named in the output |
 
 Both hook formats kiro accepts are supported, and a config that already uses one keeps it: kiro
@@ -864,6 +892,12 @@ than deleted, because both hold settings that are not Zikaron's. **All three set
 the install writes three** — leaving `enabledMcpjsonServers` behind names two servers that no longer
 exist, which loads nothing and breaks nothing but is not an uninstall.
 
+**The edit guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
+`PostToolUse` hook groups whose command is `zikaron-guard`, and the `SessionStart` and
+`SubagentStart` groups whose command is `zikaron-hook`. To keep the memory store and drop only the
+guards, re-running the installer will not do it — an install never removes a selection — so delete
+the two guard groups and the `--components …` arguments from the two start groups' command.
+
 Note that `rm -rf .zikaron` takes the knowledge bases with it. They are rebuildable — an index is a
 view onto files you still have — but rebuilding one takes minutes per corpus.
 

{zikaron-0.3.0 → zikaron-0.3.1}/pyproject.toml

@@ -10,7 +10,7 @@ name = "zikaron"
 # one is a minor bump, never a patch**, because those paths are written into harness config that an
 # upgrade has to be able to refresh, and a patch bump tells a reader nothing needs refreshing.
 # `design/distribution.md` §"The version scheme" is normative.
-version = "0.3.0"
+version = "0.3.1"
 # What a package index renders as the one-line summary, so it must name both stores: the memory
 # store, for what was learned by working here, and the knowledge index, for what the project already
 # wrote down.
@@ -32,11 +32,11 @@ requires-python = ">=3.12"
 dependencies = [
     "aiosqlite==0.22.1",
     "sqlite-vec==0.1.9",
-    "fastembed==0.8.0",
+    "fastembed==0.8.1",
     # Direct, not transitive: `core/indexing/acquisition.py` calls `snapshot_download` itself, so
     # that the revision and the digests are Zikaron's rather than whatever upstream head fastembed
     # would resolve. §6 pins direct dependencies exactly.
-    "huggingface_hub==1.26.0",
+    "huggingface_hub==1.33.0",
     # `zikaron-mcp` only. Deliberately not stdlib-only, unlike `zikaron-hook` — see
     # coding-standards.md §6 for the cost-model reasoning (once per agent spawn, not once per
     # message) and architecture.md §Components for the measured import cost.
@@ -45,7 +45,7 @@ dependencies = [
     # changes how a client's connection — and therefore the session label this client adopts and
     # reuses across calls — is carried. That is a transport change worth its own measurement, so
     # the bump is deliberate rather than absorbed into an ordinary dependency refresh.
-    "fastmcp==3.4.7",
+    "fastmcp==4.0.10",
 ]
 
 # Absent until now, which is why the PyPI page M30 will publish would have rendered blank. The
@@ -64,12 +64,13 @@ Homepage = "https://github.com/nathan-shapiro/Zikaron"
 Repository = "https://github.com/nathan-shapiro/Zikaron"
 Issues = "https://github.com/nathan-shapiro/Zikaron/issues"
 
-# The two commands a shipped harness config names — either harness — and the reason they are console
-# scripts rather than `python -m` command lines: a hook entry's `command` and an `mcpServers` entry's
-# `command` each need one absolute path, and a console script's shebang pins the interpreter Zikaron
-# is installed into — which is also the interpreter start-if-absent will spawn the service with, via
-# `sys.executable`. Measured, so the choice costs nothing: the two forms differ by about 1.4 ms
-# median over a full hook process (architecture.md §"The install contract").
+# The commands a shipped harness config names — `zikaron-hook` and `zikaron-mcp` for either harness,
+# `zikaron-guard` for Claude Code's edit guards — and the reason they are console scripts rather than
+# `python -m` command lines: a hook entry's `command` and an `mcpServers` entry's `command` each need
+# one absolute path, and a console script's shebang pins the interpreter Zikaron is installed into —
+# which is also the interpreter start-if-absent will spawn the service with, via `sys.executable`.
+# Measured, so the choice costs nothing: the two forms differ by about 1.4 ms median over a full hook
+# process (architecture.md §"The install contract").
 #
 # `zikaron-service` is deliberately *not* here. No config names it: it is spawned by
 # `sys.executable -m zikaron.service.main` from whichever client finds the socket absent, which is
@@ -84,17 +85,18 @@ Issues = "https://github.com/nathan-shapiro/Zikaron/issues"
 zikaron = "zikaron.cli.main:main"
 zikaron-hook = "zikaron.hook.main:main"
 zikaron-mcp = "zikaron.mcp.main:main"
+zikaron-guard = "zikaron.guard.main:main"
 
 [project.optional-dependencies]
 dev = [
-    "ruff==0.16.7",
+    "ruff==0.16.9",
     "mypy==2.3.1",
     "pytest==9.1.1",
     "pytest-cov==7.1.0",
     "pytest-asyncio==1.4.0",
     # Property-based tests, for the places the design states a property rather than a case:
     # chunking never loses content, and no chunk exceeds the budget it was cut to.
-    "hypothesis==6.168.0",
+    "hypothesis==6.168.3",
     # Tests only, and never imported by shipped code. Two of Claude Code's four installed
     # artefacts are YAML-frontmatter Markdown, and the installer emits that frontmatter by string
     # formatting — so the only way to assert it is *valid* is to parse it with something that did

{zikaron-0.3.0 → zikaron-0.3.1}/tests/test_check_gate.py

@@ -140,7 +140,7 @@ def test_the_project_table_still_holds_the_keys_a_later_table_can_swallow() -> N
     still *in `[project]`*, which is the property an inserted table destroys.
     """
     project = tomllib.loads((_ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"]
-    for key in ("name", "version", "readme", "license", "requires-python", "dependencies"):
+    keys = ("name", "version", "readme", "license", "requires-python", "dependencies", "scripts")
+    for key in keys:
         assert key in project, f"`{key}` has left [project] — a table header was inserted above it"
     assert len(project["dependencies"]) == 5, "the runtime dependency list changed size"
-    assert set(project["scripts"]) == {"zikaron", "zikaron-hook", "zikaron-mcp"}

{zikaron-0.3.0 → zikaron-0.3.1}/tests/test_cli_front_door.py

@@ -25,10 +25,18 @@ _ROOT: Final = Path(__file__).resolve().parent.parent
 _SUBCOMMANDS: Final = ("init", "install", "knowledge", "doctor")
 
 
-def test_the_console_script_resolves_to_something_callable() -> None:
-    declared = tomllib.loads((_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
-    target = declared["project"]["scripts"][NAME]
-    module_path, _, attribute = target.partition(":")
+_SCRIPTS: Final[dict[str, str]] = tomllib.loads(
+    (_ROOT / "pyproject.toml").read_text(encoding="utf-8")
+)["project"]["scripts"]
+
+
+def test_the_front_door_is_a_declared_console_script() -> None:
+    assert NAME in _SCRIPTS
+
+
+@pytest.mark.parametrize("script", sorted(_SCRIPTS))
+def test_every_console_script_resolves_to_something_callable(script: str) -> None:
+    module_path, _, attribute = _SCRIPTS[script].partition(":")
     entry = getattr(importlib.import_module(module_path), attribute)
     assert callable(entry)
 

{zikaron-0.3.0 → zikaron-0.3.1}/tests/test_distribution.py

@@ -143,8 +143,11 @@ def test_the_wheel_declares_every_console_script(built: tuple[Path, Path]) -> No
     with zipfile.ZipFile(wheel) as archive:
         (entry_points,) = [n for n in archive.namelist() if n.endswith("entry_points.txt")]
         declared = archive.read(entry_points).decode()
-    for script in ("zikaron =", "zikaron-hook =", "zikaron-mcp ="):
-        assert script in declared, f"{script.rstrip(' =')} is not in the built wheel"
+    scripts = tomllib.loads((_ROOT / "pyproject.toml").read_text(encoding="utf-8"))["project"][
+        "scripts"
+    ]
+    for script in scripts:
+        assert f"{script} =" in declared, f"{script} is not in the built wheel"
 
 
 def test_nothing_published_names_this_machine(built: tuple[Path, Path]) -> None:

zikaron-0.3.1/tests/test_guard_claude_live.py

@@ -0,0 +1,128 @@
+"""The edit guards in a real Claude Code session (`design/build-plan.md` §M37, "A live test").
+
+One headless session under `--permission-mode bypassPermissions` is given exact commands, so that
+neither the edit nor the override is the model's choice: a `sed -i` the guard must deny, the same
+form with a valid override, and an `Edit`. What is asserted is what the harness recorded, never what
+the model says:
+
+- the deny is the `sed -i` call's `tool_result` in the `stream-json` output, and the file is
+  unchanged by it — under `bypassPermissions`, which is itself one of §2's rows;
+- the override's command ran (the file changed), and its acknowledgement reached the model, which is
+  recorded only in the session's transcript, as an attachment;
+- the `Edit` was followed by the nudge, also an attachment.
+
+**The project lives under `~/.cache/zikaron-live-tests/`, never `tmp_path`**: pytest's temporary
+directories lie under `/tmp` or `$TMPDIR`, where the guard exempts the commands and suppresses the
+nudge, so a project there would test nothing. **The override's withdrawing rather than granting is
+not observable here** — under `bypassPermissions` no decision and `allow` look the same — so the
+hermetic `tests/test_guard_main.py` holds it, on the hook's JSON.
+
+    .venv/bin/pytest -m integration_claude tests/test_guard_claude_live.py
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any, Final
+
+import pytest
+
+from zikaron.harness.spec import CLAUDE_CODE
+from zikaron.install import harness
+from zikaron.install import main as install_main
+
+pytestmark = pytest.mark.integration_claude
+
+_TURN_TIMEOUT: Final = 300.0
+_DENIED: Final = "sed -i 's/beta/BETA/' target.txt"
+_OVERRIDDEN: Final = "sed -i 's/gamma/GAMMA/' target.txt #ZIKARON-FORCE #Reason: live guard test"
+#: The model is told to keep the trailing comment because, measured, a small model otherwise drops
+#: it as noise — and the override is then the model's choice, which this test must not depend on.
+_PROMPT: Final = (
+    "Do these three steps in order, each exactly as written, and carry on to the next even if one "
+    f"fails. Step 1: run this Bash command, character for character: `{_DENIED}`. Step 2: run this "
+    f"Bash command, character for character, including its trailing # comment: `{_OVERRIDDEN}`. "
+    "Step 3: use the Edit tool to replace the word alpha with ALPHA in target.txt. Then reply with "
+    "the single word: done."
+)
+
+
+@pytest.fixture
+def project() -> Iterator[Path]:
+    root = Path.home() / ".cache" / "zikaron-live-tests" / uuid.uuid4().hex
+    root.mkdir(parents=True)
+    (root / "target.txt").write_text("alpha beta gamma\n", encoding="utf-8")
+    try:
+        yield root
+    finally:
+        shutil.rmtree(root)
+
+
+def _session(project: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """One headless turn: the `stream-json` records, and the session transcript's records."""
+    assert harness.binary_is_available(CLAUDE_CODE.harness_binary), (
+        f"{CLAUDE_CODE.harness_binary!r} is not on PATH: do not run -m integration_claude here, "
+        "or `HarnessSpec.harness_binary` names the wrong binary."
+    )
+    result = subprocess.run(  # noqa: S603 — the argv is this file's own constants.
+        [
+            CLAUDE_CODE.harness_binary,
+            "-p",
+            _PROMPT,
+            "--model",
+            "haiku",
+            "--permission-mode",
+            "bypassPermissions",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+        ],
+        cwd=project,
+        env=os.environ.copy(),
+        capture_output=True,
+        text=True,
+        timeout=_TURN_TIMEOUT,
+        check=False,
+        stdin=subprocess.DEVNULL,
+    )
+    stream = [json.loads(line) for line in result.stdout.splitlines() if line.startswith("{")]
+    sessions = {record["session_id"] for record in stream if "session_id" in record}
+    assert len(sessions) == 1, f"no session in the stream; stderr: {result.stderr[-800:]!r}"
+    (session,) = sessions
+    (transcript,) = (Path.home() / ".claude" / "projects").glob(f"*/{session}.jsonl")
+    lines = transcript.read_text(encoding="utf-8").splitlines()
+    return stream, [json.loads(line) for line in lines if line.strip()]
+
+
+def _tool_results(stream: list[dict[str, Any]]) -> list[str]:
+    results = []
+    for record in stream:
+        for block in (record.get("message") or {}).get("content") or []:
+            if isinstance(block, dict) and block.get("type") == "tool_result":
+                content = block.get("content")
+                results.append(content if isinstance(content, str) else json.dumps(content))
+    return results
+
+
+def test_the_guards_deny_acknowledge_and_nudge_in_a_real_session(project: Path) -> None:
+    status = install_main.main(
+        ["--project", str(project), "--harness", "claude-code", "--components", "guards"]
+    )
+    assert status == 0
+    stream, transcript = _session(project)
+    text = (project / "target.txt").read_text(encoding="utf-8")
+
+    denials = [r for r in _tool_results(stream) if "PreToolUse:Bash hook error" in r]
+    assert any("Zikaron's find-replace guard refused this command" in r for r in denials), denials
+    assert "BETA" not in text, "the denied sed ran"
+    assert "GAMMA" in text, "the overridden sed did not run"
+    assert "ALPHA" in text, "the Edit did not happen, so no nudge could follow it"
+
+    recorded = "\n".join(json.dumps(record) for record in transcript)
+    assert "#ZIKARON-FORCE accepted by Zikaron's find-replace guard" in recorded
+    assert "PostToolUse:Edit hook additional context" in recorded
+    assert "target.txt` was edited" in recorded

zikaron-0.3.1/tests/test_guard_docstring_examples.py

@@ -0,0 +1,22 @@
+"""Every example in `zikaron.guard`'s docstrings runs and gives the output it shows.
+
+The rule modules lead with examples so a reader meets the rule before the code; run as doctests,
+an example cannot drift from the code beneath it.
+"""
+
+import doctest
+import importlib
+import pkgutil
+
+import pytest
+
+import zikaron.guard
+
+MODULES = sorted(info.name for info in pkgutil.iter_modules(zikaron.guard.__path__))
+
+
+@pytest.mark.parametrize("name", MODULES)
+def test_docstring_examples(name: str) -> None:
+    module = importlib.import_module(f"zikaron.guard.{name}")
+    result = doctest.testmod(module, optionflags=doctest.ELLIPSIS)
+    assert result.failed == 0