hermeneutic 0.1.7__tar.gz

hermeneutic-0.1.7/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+*.swp
+.DS_Store
+.coverage
+htmlcov/
+
+# local working notes — never distributed
+HANDOFF.md
+.claude/

hermeneutic-0.1.7/.zenodo.json

@@ -0,0 +1,24 @@
+{
+  "upload_type": "software",
+  "title": "hermeneutic: local correction evidence, retrieval, and deterministic English drift checks",
+  "version": "0.1.7",
+  "description": "hermeneutic is a local-first Python toolkit that mines correction triples from supported AI chat logs, optionally retrieves similar prior corrections through a local Ollama-backed compiler, and runs eight fixed deterministic English surface checks on outgoing drafts. Mining personalizes the local corpus and retrieval; it does not rewrite the gate. A separate programmable Python Router can compose optional external rubric, model-critic, and repair callables. The project is a review aid and reliability floor, not proof of correctness. Its historical corpus and retrieval measurements are single-user, and downstream effectiveness has not been measured. Private triples and embeddings are not distributed.",
+  "creators": [
+    { "name": "Bosch Rodriguez, Rolando", "orcid": "0009-0005-4896-1112", "affiliation": "Hermes Labs" }
+  ],
+  "keywords": [
+    "AI reliability",
+    "LLM reliability",
+    "silent failure modes",
+    "evidence-first",
+    "hermeneutic drift",
+    "correction mining",
+    "pre-flight gate",
+    "post-completion overclaiming"
+  ],
+  "license": "MIT",
+  "related_identifiers": [
+    { "identifier": "10.5281/zenodo.20471023", "relation": "isVersionOf", "scheme": "doi" },
+    { "identifier": "10.5281/zenodo.19042469", "relation": "references", "scheme": "doi" }
+  ]
+}

hermeneutic-0.1.7/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md — using hermeneutic from a coding agent
+
+This file is for AI coding agents and host applications that want to call the
+standalone `hermeneutic` CLI or Python library.
+
+## What this tool does
+
+A fixed deterministic English drift check for assistant-generated drafts. It
+flags eight surface shapes including completion overclaiming, relayed authority,
+unhedged certainty, scope expansion, and unsupported quality adjectives. It
+does not read the personal correction corpus or run the optional Router.
+
+## When to invoke it
+
+Run `hermeneutic gate` on any assistant draft *before* you send it to the user
+when:
+
+- The draft contains numeric claims (file counts, test counts, percentages, ms).
+- The draft summarizes work completed by a subagent.
+- The draft uses completion language ("done", "shipped", "all green").
+- The draft contains universal quantifiers ("every", "all", "always").
+- You want a cheap second-opinion gate that doesn't require an LLM call.
+
+Inspect the printed verdict as well as the exit code: low-severity `RISK` is
+advisory and exits 0; medium/high `RISK` exits 1. A caller that chooses to hold a
+draft should either:
+1. Add the missing evidence (run the verification commands, paste the output).
+2. Hedge the claim ("appears to" / "based on N samples").
+3. Cut the unverifiable text.
+
+## Programmatic use
+
+```python
+from hermeneutic import Router, PressureProbe
+
+probe = PressureProbe(judge=your_llm_call)  # callable: prompt -> str
+
+def repair(request, draft, reason):
+    return your_llm_call(f"Revise: {reason}\n\n{draft}")
+
+router = Router(probe=probe, repairer=repair)
+result = router.gate(request=user_request, draft=your_draft)
+if result.repaired:
+    log(f"hermeneutic caught drift: {result.summary()}")
+final = result.final_output
+```
+
+## Calibration
+
+`PressureProbe` ships with a generic "rigorous-skeptic" calibration. To make it
+match your team's standards, pass your own calibration text:
+
+```python
+my_calibration = """
+You are reviewing drafts for a security-critical product.
+Bias toward HOLD when:
+- Any security claim lacks a CVE or vendor-confirmed citation.
+- Code changes touch authentication or crypto without a test diff.
+"""
+probe = PressureProbe(judge=your_llm_call, calibration=my_calibration)
+```
+
+## Mining your own logs
+
+Mine your own chat logs to build a personal corpus and look for candidate drift
+modes:
+
+```bash
+hermeneutic mine ~/your/log/dir --format claude-code --out triples.jsonl
+hermeneutic bucket triples.jsonl
+```
+
+Mining does not change the gate. A developer may deliberately add a new pattern
+to `src/hermeneutic/gates/regex.py` only with evidence, tests, review, and a new
+release. The personal corpus can affect optional compile retrieval after
+`compile-index` is rerun.
+
+## What this tool is NOT
+
+- Not a model evaluator. Scores individual drafts, not aggregate quality.
+- Not foresight. Catches drift modes seen before; novel drifts pass through.
+- Not a replacement for human review. It's a floor-raiser.
+- Not multilingual. The fixed rules check English surface patterns.
+- Not proof that a caller's external Router backends or repair behavior are safe.

hermeneutic-0.1.7/BACKLOG.md

@@ -0,0 +1,11 @@
+# BACKLOG
+
+New ideas land here, not in new files. Nothing below is scheduled.
+
+- **Assertion-granularity citation system** (queued 2026-04-28) — each claim
+  in compiled output should map to a specific triple-id in the corpus.
+  Currently the compile-hook injects a per-bucket steer summary; a future
+  enhancement adds `[evidence: triple-id-N]` markers per claim so outputs
+  cite specific past corrections at sentence level. Composes with
+  hermes-rubric's evidence-first scoring at finer granularity. Origin:
+  external feedback on the compile-preamble in action.

hermeneutic-0.1.7/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to Hermeneutic are documented here. The project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.7] — Unreleased
+
+### Publication truth corrections
+
+- Reframed the product around its actual distinct surfaces: personal correction mining, optional personal retrieval, a fixed deterministic English gate, and a separately configured Python Router.
+- Replaced the Claude compile hook's user-visible `systemMessage` with the documented `UserPromptSubmit` `hookSpecificOutput.additionalContext` contract. The installer now registers an exec-form command bound to the running Python interpreter, handles paths with spaces, migrates or cleans its exact legacy registration, preserves unrelated hooks, and avoids destructive malformed-settings behavior.
+- Added exact compile-hook contract coverage for success JSON, empty/missing results, unavailable Ollama, malformed input/state, compiler failures, timeouts, idempotency, foreign-file protection, legacy cleanup, coexistence, and uninstall.
+- Replaced the leave-one-out evaluator's duplicated selection approximation with calls through the shipped `compile_prompt()` production path. Current same-bucket results on the frozen 346-triple corpus are 88/104 (84.6%) at CLI/hook defaults and 94/104 (90.4%) at Python defaults.
+- Added a privacy-safe current gate-coverage receipt: 115/346 (33.24%) prior assistant replies in the frozen correction corpus fire at least one current rule. This is retrospective derivation-set coverage, not held-out accuracy.
+- Moved the prior 83.7% leave-one-out and 98/100 discrimination figures into historical-only framing because their evaluators did not match the shipped selection path.
+- Classified every integration by evidence maturity. The Claude compile hook, Codex plugin mechanics, and forward-deployed tooling are mechanically tested; Cursor/OpenHands are design sketches; current Claude Stop, Cline, and Windsurf adapters are removed from the ready-support matrix.
+- Synchronized README, package description, machine-readable summary, examples, theory/intent docs, citation metadata, Zenodo metadata, plugin descriptions, installation commands, optional dependencies, privacy boundaries, and author display.
+
+### Added and hardened
+
+- Eight fixed English stage-one rules with a partial-progress contrast guard.
+- Correction mining for Claude Code, Codex rollout, and OpenAI-style message logs; loud zero-parse diagnostics; multi-directory input; nested output-directory creation.
+- Optional local-Ollama compile index and deterministic bucket-aware warning preambles.
+- Local opt-in telemetry, reviewable audit modes, `stats`, harvest classification, human review, and accepted-record promotion.
+- Wheel-built Claude compile-hook installer plus repository/sdist standalone plugin assets and integration documentation.
+- Forward-deployed environment/boot/harvest/report/gate tooling, report leak checks, tamper-evident mission state, and optional Codex notification sentinel.
+- Trusted-publishing GitHub Actions workflow, wheel/sdist checks, exact-sdist tests, typed-package smoke, release metadata, and software citation files.
+
+### Boundaries
+
+- Core library and CLI have zero required Python runtime dependencies.
+- Stage-one checks are fixed English surface patterns. Mining and promotion do not generate regex rules.
+- Live Ollama, live response-hook hosts, external Router backends, Windows, false-positive rate on ordinary prompts, and downstream model effectiveness are not certified by this release.
+- The wheel contains the core, CLI, type marker, and built-in hook installers. Evaluations, standalone plugins, integration docs, and forward-deployed tooling require the repository or extracted sdist.
+
+## [0.1.6] — 2026-07-08
+
+### Added
+
+- Opt-in local JSONL gate/compile telemetry with context labels and best-effort failure isolation.
+- Audit modes `none`, `hash`, and `raw`, plus draft fingerprints and matched-context windows.
+- `stats`, `harvest`, `harvest --sanitized`, and `promote` review-loop commands.
+- Codex rollout reader and forward-deployed validation tooling.
+- Two additional fixed English rule shapes and a contrastive partial-progress guard, bringing the rule count to eight.
+
+### Changed
+
+- Declared the fixed gate's English-only boundary.
+- Improved loud failure for missing inputs, unsupported log shapes, corrupt harness state, and invalid explicit session paths.
+
+## [0.1.5+bucket-aware] — 2026-04-27
+
+Local-only retrieval iteration on the v0.1.5 compiler. It introduced per-bucket selection and recorded the historical 83.7% leave-one-out and 98/100 versus 7/30 discrimination experiments. Those values remain provenance receipts, not current production-path claims; the original embedding artifact was not fully pinned and the evaluators later proved behaviorally different from `compile_prompt()`.
+
+## [0.1.5] — 2026-04-26
+
+### Added
+
+- `orig_prompt` in correction triples with backward-compatible loading.
+- Local Ollama `nomic-embed-text` index stored under `~/.hermeneutic/`.
+- `compile-index`, `compile`, deterministic preamble synthesis, and an initial Claude prompt hook.
+
+## [0.1.1] — 2026-04-26
+
+### Added
+
+- Additional log-reader resilience, CLI error reporting, and packaging metadata.
+
+## [0.1.0] — 2026-04-25
+
+### Added
+
+- Correction-triple mining and bucketing.
+- Fixed regex gate and programmable three-stage Router.
+- Python library and `hermeneutic` CLI under the MIT License.

hermeneutic-0.1.7/CITATION.cff

@@ -0,0 +1,39 @@
+cff-version: 1.2.0
+message: "If you use hermeneutic, please cite it as below."
+title: "hermeneutic: local correction evidence, retrieval, and deterministic English drift checks"
+abstract: >-
+  hermeneutic is a local-first Python toolkit that mines correction triples from
+  supported AI chat logs, optionally retrieves similar prior corrections through
+  a local Ollama-backed compiler, and runs eight fixed deterministic English
+  surface checks on outgoing drafts. A separate programmable Python Router can
+  compose optional external rubric, model-critic, and repair callables. The tool
+  is a review aid and reliability floor, not proof of correctness. Historical
+  corpus and retrieval measurements are single-user, and downstream effectiveness
+  has not been measured.
+type: software
+version: "0.1.7"
+authors:
+  - family-names: "Bosch Rodriguez"
+    given-names: "Rolando"
+    orcid: "https://orcid.org/0009-0005-4896-1112"
+    affiliation: "Hermes Labs"
+    email: roli@hermes-labs.ai
+license: MIT
+repository-code: "https://github.com/hermes-labs-ai/hermeneutic"
+url: "https://hermes-labs.ai"
+keywords:
+  - "AI reliability"
+  - "LLM reliability"
+  - "silent failure modes"
+  - "evidence-first"
+  - "hermeneutic drift"
+  - "correction mining"
+  - "pre-flight gate"
+  - "post-completion overclaiming"
+references:
+  - type: article
+    title: "A Taxonomy of Epistemic Failure Modes in LLMs"
+    authors:
+      - family-names: "Bosch Rodriguez"
+        given-names: "Rolando"
+    doi: "10.5281/zenodo.19042469"

hermeneutic-0.1.7/CLAUDE.md

@@ -0,0 +1,27 @@
+# CLAUDE.md — working on hermeneutic
+
+Read `AGENTS.md` first — it is the canonical in-session protocol for coding
+agents using or modifying this repo, and everything there applies to Claude
+Code sessions too.
+
+Repo-specific rules for agents:
+
+- **The core gate stays zero-LLM.** Never wire an LLM call into a default
+  path. The optional compiler defaults to localhost Ollama; Python callers can
+  override that URL, and caller-supplied Router components own their network
+  and credential behavior.
+- **Every behavior change gets a test**, and the full suite must stay green:
+  `PYTHONPATH=src python -m pytest -q`. The README/CHANGELOG test count is
+  enforced by `tests/test_docs_consistency.py` — update all surfaces together.
+- **Never loosen an existing gate rule to silence a false positive.** Note it
+  in the harvest queue instead; rule changes require mined evidence
+  (see `evals/triple-mining-receipts.md` for the bar).
+- **Honest partial progress is not drift** — don't "improve" recall by
+  flagging "did X, but Y remains" (`_CONTRAST_GUARD` protects this; keep it).
+- **Numbers in docs must trace to committed receipts** in `evals/`. No
+  uncommitted benchmark claims.
+- Lint with `ruff check src tests` before committing.
+
+To verify a deployment of this tool in your own environment, run the
+forward-deployed harness: `python3 forward-deployed/harness.py` (see
+`FORWARD-DEPLOYED-HARNESS.md`).

hermeneutic-0.1.7/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+By participating, you agree to uphold it. Report conduct concerns to `roli@hermes-labs.ai`; reports are handled confidentially.

hermeneutic-0.1.7/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing
+
+Thanks for your interest in `hermeneutic`. This document describes how to propose changes.
+
+## Scope
+
+`hermeneutic` is a focused tool: it mines correction triples, optionally retrieves similar prior corrections, and runs a fixed English check over outgoing drafts. It is **not** a general-purpose evaluation framework, model benchmarker, or default LLM router for production traffic.
+
+**In-scope:** new chat-log readers, new evidence-based risk patterns, calibration recipes for `PressureProbe`, bug fixes, docs, test coverage.
+
+**Out-of-scope:**
+
+- Aggregate model evaluation — use a benchmark suite.
+- Static analysis of prompt scaffolds, which is outside this repository's scope.
+- Agent-config structural analysis — that belongs in [lintlang](https://github.com/hermes-labs-ai/lintlang).
+- Anything that adds a mandatory runtime dependency. Stage 2 (hermes-rubric) and stage 3 (your LLM) stay optional and pluggable.
+
+Open an issue first if you're unsure.
+
+## Development setup
+
+```bash
+git clone https://github.com/hermes-labs-ai/hermeneutic
+cd hermeneutic
+python3 -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+python3 -m pip install -e ".[dev]"
+```
+
+## Running the checks
+
+```bash
+python3 -m ruff check .
+python3 -m pytest -ra
+```
+
+CI runs the same commands on Python 3.10–3.13.
+
+## Adding a new risk pattern
+
+Patterns must be **evidence-based**: derived from real corrections you've mined.
+
+1. Add the pattern to `_RAW_PATTERNS` in `src/hermeneutic/gates/regex.py` with `(rule_id, severity, regex, description)`.
+2. Add a test in `tests/test_regex.py` covering both a draft it should flag and one it should not.
+3. In the PR description, include: how many corrections in your mined corpus matched this pattern, and a sanitized example.
+4. Update `CHANGELOG.md` under `[Unreleased]`.
+
+Severity guide: `high` = strong drift signal that almost always warrants a downstream check. `med` = often associated with drift but more false positives. `low` = stylistic tell only.
+
+## Adding a new chat-log reader
+
+1. Subclass `LogReader` in `src/hermeneutic/triples.py`.
+2. Implement `iter_turns(path) -> Iterator[(role, text, timestamp)]`.
+3. Register your reader in the `READERS` dict.
+4. Add a round-trip test in `tests/test_triples.py`.
+
+## Pull request checklist
+
+- [ ] `ruff check .` passes
+- [ ] `pytest -ra` passes
+- [ ] No new mandatory runtime dependency added
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] New rules / readers have tests
+- [ ] No backward-incompatible API change without a major-version bump
+
+## Filing issues
+
+Minimum useful report: Python version, OS, exact command, draft text (or a minimal reproducer), observed output, expected output.
+
+For mining-related issues, please include a sanitized example log entry that reproduces the problem.
+
+## Code of conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+By contributing, you agree that your contributions are licensed under the MIT License (see [LICENSE](LICENSE)).
+
+## Pull request flow
+
+Open a focused pull request against `main`. Keep unrelated changes separate,
+make every behavior change executable by a test, and wait for the full CI
+matrix—including the built-artifact job—to pass at the latest head SHA. Resolve
+review conversations before merge. Repository settings, rather than this file,
+are the authority for required checks and merge permissions.

hermeneutic-0.1.7/FORWARD-DEPLOYED-HARNESS.md

@@ -0,0 +1,219 @@
+# FORWARD-DEPLOYED HARNESS — instructions for the agent that executes it
+
+**This file is the instructions. The harness itself is executable** —
+`forward-deployed/harness.py`, a deterministic step-machine that drives the
+mission and verifies each step from artifacts before the next unlocks. You
+read this once for context; you RUN the harness.
+
+You are an agent reading this inside the adopter's environment — an
+environment the author of this package cannot see and deliberately never
+will. Read this whole file before acting. When you finish it, you are the
+**forward-deployed engineer** for hermeneutic here: verify that it works in
+this harness, adapt it where it doesn't, and leave behind a sanitized report
+of what you did. You know this environment better than the author ever
+could — that asymmetry is the design, not a workaround.
+
+## The concept (60 seconds)
+
+Every chat log contains a discarded dataset: the moments the user corrected
+the assistant — *"no, not that"*, *"still crashes"*, *"I said MySQL"*. Each
+correction marks a drift: the assistant did Y when asked for X, did half and
+called it done, or overclaimed ("Done — 14 files, all green") without the
+receipts. hermeneutic mines those corrections into `(drift, steer, repair)`
+triples and uses them twice:
+
+1. **The gate** (`hermeneutic gate`) — a zero-LLM regex tripwire run on
+   outgoing drafts. It catches announcement-shaped drift modes with a local,
+   deterministic regex pass; every fire is explainable. It is a floor, not a
+   guarantee.
+2. **The compile layer** (`hermeneutic compile`) — optionally retrieves past
+   corrections similar to the incoming prompt and prints a "watch out for X"
+   preamble for a caller or supported context hook to inject.
+
+## The map (what lives where)
+
+| Path | What it is |
+|---|---|
+| `src/hermeneutic/gates/regex.py` | the 8 canonical rules — the gate itself |
+| `src/hermeneutic/triples.py` | log readers (`claude-code`, `codex`, `openai` — registered in `READERS`) + the miner |
+| `src/hermeneutic/harvest.py` | replay-classify loop (`confirmed_catch` / `possible_false_positive` / `missed_drift`), `promote`, sanitized output |
+| `src/hermeneutic/compile.py` | embeddings (local Ollama, `nomic-embed-text`) + preamble builder |
+| `src/hermeneutic/cli.py` | every command |
+| `evals/` | self-test, current bounded receipts, and clearly labeled historical experiments |
+| `tests/` | the suite — `python -m pytest -q` must stay green |
+| `AGENTS.md` | the in-session protocol; meant to be copied into the human's own projects' `AGENTS.md` |
+
+## Invariants — never break these, whatever you change
+
+1. **The core gate stays zero-LLM.** Deterministic and local, every fire
+   explainable by pointing at a rule and matched text. No LLM call on any
+   default path, ever.
+2. **Privacy is structural.** Nothing leaves this machine by default.
+   Anything labeled sanitized carries zero message text — counts, rule ids,
+   timestamps, hashes, lengths only. That is data minimization, not proof of
+   anonymity; a human reviews the metadata before sharing it.
+3. **Tense is load-bearing** in the rules: past-tense completion claims
+   gate, planned future work does not. Naive stemming destroys the
+   distinction.
+4. **Honest partial progress is not drift.** Never "improve" recall by
+   flagging "did X, but Y remains".
+5. **Fail loud.** Zero-parse must exit 2 with an explanation, never emit
+   silent zero output.
+6. **Tests and evals gate every change.** The full suite green after every
+   edit; every behavior you add gets a test.
+
+## THE PROTOCOL — the harness drives, you execute
+
+The mission is not self-reported. It is driven by a step-machine:
+
+```bash
+python3 forward-deployed/harness.py
+```
+
+Run it. Do exactly what it prints. Run it again. Repeat until it prints
+**MISSION COMPLETE** with an attestation hash. Each step (ENV → BOOT →
+HARVEST → REPORT → GATE) is verified mechanically from artifacts on disk
+before the next unlocks — described-but-not-done work does not advance the
+mission. Progress is a hash chain in `forward-deployed/mission-state.json`
+(`python3 forward-deployed/harness.py verify` audits it). Honest scope: the
+chain is tamper-evident against sloppy or accidental edits, not cryptographic
+proof — a determined forger can recompute it. The attestation is a receipt
+that disciplined work happened in order; what your human reviews and sends
+is the report and artifacts, not the hash alone.
+
+The sections below are your reference material for the steps the harness
+will hand you.
+
+## BOOT — what the harness runs first (~2 minutes)
+
+```bash
+python3 -m pip install -e '.[dev]'       # once — pytest ships in the dev extra, boot needs it
+python3 forward-deployed/boot.py         # add --sessions DIR --format X if logs live elsewhere
+```
+
+It runs the whole verification sequence — test suite, gate self-test, the
+gate smoke trio against documented expectations, and a
+sanitized harvest probe over real logs — and writes
+`forward-deployed/boot-report.json` (sanitized by construction; out-of-repo
+paths are stripped before anything is stored). **Exit 0 / `fits-as-shipped`:**
+all package-controlled checks passed; if no matching logs existed, the
+real-log probe is labeled `not_exercised` rather than fabricated as a pass.
+Tell your human, run the real sanitized harvest for them — write it to the
+gitignored `build/` dir (e.g. `--out build/report.jsonl`) so the tree stays
+pristine, and leave `promote` to your human unless they ask — then write the
+report (below). **Exit 1 / `adaptation-needed`:** the failed steps are your work
+queue, in the order they appear.
+
+Manual equivalents, when you need to investigate a failure directly:
+
+```bash
+python3 -m pytest -q                     # expect: all green, 0 failed
+bash evals/self_test.sh                  # expect: PASS
+echo "Done — shipped 14 files, all tests pass." | hermeneutic gate            # → RISK
+echo "Fixed 3 of the 14 failing tests; 11 still fail." | hermeneutic gate     # → PASS (honest partial progress)
+echo "I will ship the remaining files tomorrow." | hermeneutic gate           # → PASS (a plan is not a claim)
+hermeneutic harvest ~/.claude/projects --format claude-code --sanitized --out /tmp/hh-probe.jsonl
+```
+
+## Permitted adaptations (most likely first)
+
+- **A. Log format mismatch** (harvest says ZERO EVENTS on real logs):
+  subclass `LogReader` in `triples.py`, register it in `READERS`. Verify
+  against ONE real session file, then add a test using synthetic fixture
+  data only — never commit real log content.
+- **B. Rule gaps** (drift your human corrects that the gate misses): add a
+  bounded-window rule to `gates/regex.py` following the existing tuple
+  pattern, with the mined evidence that justifies it and a test. Add rules,
+  never loosen existing ones.
+- **C. Correction-marker gaps** (real corrections invisible to the miner):
+  extend the correction markers in `triples.py` the same way.
+- **D. Path and layout differences**: prefer `--glob` flags over code edits.
+- **E. Architectural adaptation**: allowed when A–D don't fit, if every
+  invariant holds and tests + evals stay green. Prefer additive changes
+  behind a flag. You are expected to harden this beyond what its author
+  could do blind — that is the assignment, not an exception.
+
+**Do not**: wire an LLM into a default path; weaken completion rules
+globally to silence a known false-fire (note occurrences in your report
+instead — rule changes need their own mined evidence); put any session
+text, out-of-repo path, or personal identifier in anything you commit or
+report.
+
+## The report you leave behind
+
+Copy `forward-deployed/REPORT-TEMPLATE.md` to `FORWARD-DEPLOYED-REPORT.md`
+at the repo root and fill it in. It is sanitized by the same rule as
+`--sanitized`: **counts, categories, and this repo's own code — never your
+human's text.** The linter checks common leak shapes (paths, identifiers, long
+quotes, long Hangul runs); it is deliberately not presented as an exhaustive
+privacy or anonymity check. English prose and organization-specific identifiers
+may evade it, so human review completes the process. Before handing the report over, run it and
+resolve every flag:
+
+```bash
+python3 forward-deployed/check_report.py FORWARD-DEPLOYED-REPORT.md   # must print CLEAN
+```
+
+Structure:
+
+1. **Environment** (categories only): OS family, Python `x.y`, package
+   version, agent CLI + version (Claude Code / Codex / other).
+2. **Boot results**: pass/fail per step; for failures, exception type +
+   message with every out-of-repo path stripped.
+3. **Adaptations**: per change — file, one-sentence reason (no session
+   content), the diff of THIS repo's code, tests added, and
+   `pytest` numbers before and after.
+4. **Observed but not fixed**: known-false-fire counts, missed-drift shapes
+   described generically ("uncommon completion verb, casual register") —
+   never quoted.
+5. **Open questions** for the author.
+
+Your human reviews the report and sends it to roli@hermes-labs.ai. Nothing
+sends itself; you have no network duties.
+
+## Definition of package-controlled completion
+
+The harness can establish that its package-controlled checks completed; it
+cannot by itself establish that Hermeneutic is deployed and working on real
+adopter logs. `gate.py` exit 0 closes the local verification chain with an
+attestation:
+
+```bash
+python3 forward-deployed/gate.py       # exit 0 = package-controlled checks complete
+python3 forward-deployed/harness.py    # advances to MISSION COMPLETE + attestation
+```
+
+It deterministically checks: boot evidence fresh and `fits-as-shipped`,
+the test suite green **in this environment**, the zero-LLM and privacy
+invariants mechanically intact, and the report present and
+`check_report.py`-CLEAN — always: "no adaptations needed" is a valid report,
+a skipped one is not. If the gate says NOT DONE, it lists
+exactly what's missing; finish that, don't argue with it. Treat `MISSION
+COMPLETE` as the harness's internal completion state. A live deployment claim
+additionally needs a human-reviewed real-log/adopter receipt; `not_exercised`
+is never evidence of live fit. (Yes: the drift gate ships with a drift gate for
+its own verification chain.)
+
+## Runtime sentinel (optional, human-consented)
+
+After MISSION COMPLETE, offer your human one more layer — enforcement that
+lives inside Codex's own loop, via its native `notify` (turn-ended) hook:
+
+```bash
+python3 forward-deployed/sentinel.py install     # reversible: sentinel.py uninstall
+```
+
+While any future mission is incomplete, a turn that *sounds* finished
+triggers a desktop nudge ("harness says NOT DONE — next step: X"); and every
+turn's last message is live-gated (zero-LLM, advisory — rule
+ids only, never text). Install REFUSES if another notify hook exists (it
+prints how to compose them by hand) and backs the config up first. This is
+an explicit human decision — never install it silently.
+
+## Escalation
+
+If BOOT fails at the test suite or self-test stage, the defect is in the
+package, not your environment: stop adapting, produce the diagnostic block
+from `AGENTS.md` ("If something doesn't fit this harness") plus the report,
+and have your human send both. That is a bug on the author's side and gets
+fixed at the source.

hermeneutic-0.1.7/INTENT.md

@@ -0,0 +1,34 @@
+# Hermeneutic intent
+
+Hermeneutic makes user corrections reusable without pretending that one mechanism does every job.
+
+## Public surfaces
+
+1. **Mine and bucket:** supported local chat logs become correction triples and aggregate categories.
+2. **Compile and retrieve:** an optional local Ollama embedding index retrieves relevant prior corrections and renders a deterministic prompt preamble.
+3. **Deterministic gate:** eight fixed English regex rules check outgoing text. Mining does not rewrite them.
+4. **Programmable Router:** callers may compose the fixed gate with an optional `hermes-rubric` executable, a caller-supplied `PressureProbe`, and a caller-supplied repairer.
+5. **Audit and review:** opt-in local telemetry plus harvest/review/promote mechanics create a reviewable correction loop.
+
+## Accepts
+
+- Transparent local evidence and deterministic behavior where possible.
+- Personalization in the corpus and retrieval layer.
+- Explicit caller ownership of blocking, external providers, repair policy, privacy, latency, and cost.
+- New fixed gate rules only when a code change includes evidence, tests, and review.
+
+## Refuses
+
+- No claim that the gate writes itself.
+- No claim that a `PASS` proves correctness or that a hook prevents every response.
+- No multilingual claim; the fixed gate is English-only.
+- No default model-evaluation, moderation, security-boundary, or factuality guarantee.
+- No downstream-effectiveness claim without a direct measurement.
+
+## Evidence boundary
+
+The historical derivation receipt covers 326 corrections from 1,423 sessions belonging to one heavy user. A separate later frozen 346-triple corpus supports current aggregate gate and retrieval measurements, but neither corpus is a representative multi-user benchmark. Private triples are not distributed.
+
+Current direct gate coverage on the frozen 346-triple corpus is 115/346 (33.24%). Current production-path same-bucket retrieval is 88/104 (84.6%) at CLI/hook defaults and 94/104 (90.4%) at Python defaults. These are single-corpus mechanism measurements, not precision, generalization, or evidence that a model follows the warning.
+
+The project raises a review floor. Human and domain review remain responsible for the ceiling.

hermeneutic-0.1.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermes Labs
+
+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.