All plugins

meridian

Finds and verifies the implicit state machines hiding in a codebase; enforces the accepted ones in CI. Meridian discovers status/state fields, anchors every state and transition to file:line (Python AST; TS/JS lexical, unguarded), flags unreachable and dead states, and gates on a human-reviewable .meridian.yaml spec (check exits 1 on violation, 2 when nothing is enforced). Every check event is appended to a SHA-256 hash-chained log for audit. No model calls, no network, no dependencies beyond stdlib. Disclosure - post_tool_call observes tools whose names contain write/edit/patch/replace/create/editor and re-runs the local analyzer only when a .meridian.yaml governs the repo (advisory; never blocks or approves); the ledger under HERMES_HOME/plugin-data/meridian/ stores event names, machine ids, aggregate counts and repository/spec/report paths (never verdicts, never file:line anchors, never file contents); its chain is unkeyed SHA-256, so it detects edits but can be recomputed by anyone with write access; no telemetry; no background processes. Disclosure — post_tool_call observes tools whose names contain write/edit/patch/replace/create/editor and re-runs the local analyzer only when a .meridian.yaml governs the repo (advisory; never blocks or approves); meridian_spec accept and meridian_report out_file write only inside the agent's working directory (refused at /, $HOME or its parents, or the Hermes home) and never through symlinks; the ledger under HERMES_HOME/plugin-data/meridian/ stores event names, machine ids, aggregate counts and repository, spec, report and edited-file paths (never verdicts, never file:line anchors, never file contents) in an unkeyed SHA-256 chain that detects edits but can be recomputed by anyone with write access; no telemetry, no network, no background processes.

unifyWeb3Toolsv1.0.4Updated 2 days ago

About

Finds and verifies the implicit state machines hiding in a codebase; enforces the accepted ones in CI. Meridian discovers status/state fields, anchors every state and transition to file:line (Python AST; TS/JS lexical, unguarded), flags unreachable and dead states, and gates on a human-reviewable .meridian.yaml spec (check exits 1 on violation, 2 when nothing is enforced). Every check event is appended to a SHA-256 hash-chained log for audit. No model calls, no network, no dependencies beyond stdlib. Disclosure - post_tool_call observes tools whose names contain write/edit/patch/replace/create/editor and re-runs the local analyzer only when a .meridian.yaml governs the repo (advisory; never blocks or approves); the ledger under HERMES_HOME/plugin-data/meridian/ stores event names, machine ids, aggregate counts and repository/spec/report paths (never verdicts, never file:line anchors, never file contents); its chain is unkeyed SHA-256, so it detects edits but can be recomputed by anyone with write access; no telemetry; no background processes. Disclosure — post_tool_call observes tools whose names contain write/edit/patch/replace/create/editor and re-runs the local analyzer only when a .meridian.yaml governs the repo (advisory; never blocks or approves); meridian_spec accept and meridian_report out_file write only inside the agent's working directory (refused at /, $HOME or its parents, or the Hermes home) and never through symlinks; the ledger under HERMES_HOME/plugin-data/meridian/ stores event names, machine ids, aggregate counts and repository, spec, report and edited-file paths (never verdicts, never file:line anchors, never file contents) in an unkeyed SHA-256 chain that detects edits but can be recomputed by anyone with write access; no telemetry, no network, no background processes.

Meridian

Meridian

Every status field in your codebase is a state machine nobody wrote down.
Meridian finds them, proves each transition against your source, and fails CI
when one of them is illegal.

Not a prompt, not a linter, not vibes. A deterministic analyzer with an
acceptance gate and a hash-chained event log, running inside your Hermes agent
or in your pipeline.


The problem

The bugs that hurt you the most are the "impossible" ones:

  • orders.refunded = True from a draft, before any money moved
  • WAREHOUSE_HOLD exists in your enum and in zero code paths, so your SLA
    report quietly fills with blanks

And the ones nobody can see at all: force_close() writes delivered from
any state, and no guard says so. Meridian reports that write as unguarded -
a suspicion, and a violation only under --strict.

Agents write more lifecycle code than humans review. Nobody documents the
machine, nobody tests the edges, and when it breaks you get a refund you
cannot explain.

Meridian turns grep "status ==" into an auditable, enforceable state
machine: discovered from your code, anchored to file:line, gated by a spec
you review, checked on every change from then on.

What it does

Real output, on a freshly merged order service with two seeded defects:

$ hermes meridian check --root examples/demo-order-pipeline
meridian check FAILED - 2 violation(s):
  orders.py:62  unverified_shipping -> shipped  (ship)  [not-allowed]
  orders.py:78  draft -> refunded  (refund)  [deny]

orders.py:62 is a dead branch, a guard against a state nothing can enter.
orders.py:78 is a refund accepted from draft, before money ever moved.

Scan shows the whole machine:

$ hermes meridian scan --root examples/demo-order-pipeline
meridian scan - 1 files, 4 machine(s), 2ms
  Order.status                     conf=medium states=11 transitions=15
  Order.payment_status             conf=medium states=4 transitions=3
  enum:OrderStatus                 conf=medium states=11 transitions=0
  enum:PaymentStatus               conf=medium states=4 transitions=0

Unreachable and dead states, unguarded writes, and spec violations all come
out with file:line anchors. Meridian then drafts the spec for you
(meridian spec draft); every edge it proposes is an observed, anchored
transition. You cross out what you do not want, you accept, and from that
moment hermes meridian check in CI is the law.

What check tells you

check never prints a bare "OK". It reports one of three statuses:

StatusMeans
violationsthe spec forbids something the code does; every violation is anchored to file:line
spec-cleanno violations, but something is still outstanding: warnings, unguarded writes, dead states, or machines the spec does not enforce
healthyno violations and nothing outstanding

Exit codes of hermes meridian check:

CodeWhen
0no violations, and every discovered machine is enforced by the spec
1violations, or a discovered machine the spec does not enforce (--allow-uncovered waives the latter)
2no .meridian.yaml at or above the root, or the spec has no entry for any machine in the repo - a green build that enforces nothing

Why a plugin, not a prompt

A prompt cannot do any of this mechanically:

You needPrompt/skillMeridian
Deterministic failure on a forbidden edgenocheck exits 1, in CI
Evidence you can audit laternoSHA-256 hash-chained log of check events (counts, machine ids and paths)
Re-verification after every agent editnoadvisory post_tool_call hook (never blocks)
Zero tokens, zero network, zero model requiredn/astdlib only, installs nothing

Where a human comes in (accepting the spec, writing the deny list) it is
because legality is your call, not the AI's. Meridian enforces exactly the
edges you accept, and says so when it cannot verify one.

Who it is for

Install it if you own a service with mutable lifecycle state (orders,
tickets, subscriptions, jobs, deploys, payments) or you run agents on that
code and want a backstop when they refactor it. This is for your services,
not your utils.

Do not install it if your repo has no lifecycle state. It will find
nothing to enforce, which is correct behavior, not a bug.

Use it

cd /path/to/your/project        # a project directory, not $HOME
hermes plugins install unifyWeb3/meridian --enable   # from GitHub; the catalog submission is still open
hermes meridian scan
hermes meridian check --strict        # exit 1 on violations; wire into CI
hermes meridian report --out .meridian/report.md
hermes meridian ledger verify

The tools an agent calls (meridian_scan, meridian_verify, meridian_spec,
meridian_report) take a root argument, and that argument is model
controlled - so it is confined to the agent's working directory. A working
directory of $HOME, / or the Hermes home is refused outright:

the working directory /home/you is too broad to confine Meridian - run it from a project directory

The hermes meridian CLI takes its --root from you, the operator, and is
deliberately unconfined.

In a session:

You:   map the state machines in this repo, verify them, show me what breaks
Agent: meridian_scan -> meridian_verify -> meridian_spec draft
You:   accept, but cross out the warehouse_hold edges
Agent: meridian_spec accept

spec accept merges into an existing .meridian.yaml: every deny rule and
every edge you reviewed survives, only newly discovered machines and edges
are added, and the previous file is kept as .meridian.yaml.bak. It never
overwrites a reviewed rule - force is accepted and does nothing.

The post_tool_call hook is advisory. After a write-shaped tool call it
re-verifies the repo and surfaces what it finds as context on the next turn
of the same session. It never blocks a call, never approves one, and never
fails a build: the gate is check.

Honest limits

  • Meridian enforces the accepted spec. If your spec is wrong, your check is
    wrong. Review the draft before accepting.
  • Python analysis is AST-based and authoritative. TypeScript and JavaScript
    are lexical: union-type alphabets are exact, other evidence is labeled
    low/medium confidence, and JS transitions are always unguarded.
  • Unguarded writes are suspicions, not guilty verdicts. Strict mode
    (--strict, or strict=true on the tools) turns them into violations -
    but only where a .meridian.yaml exists, because that is where there is
    something to check the write against. Without a spec, unguarded writes stay
    notes.
  • Nested def and lambda scopes are not analyzed; a warning lists every
    writer.
  • Unreachable states are reported only when an initial state is known.
  • check fails when a discovered machine is not enforced by the spec: no
    entry at all, or an entry that states no rule (non-enum machines; enum-only
    machines carry no edges and are exempt). Waive with --allow-uncovered.
  • The ledger is an append-only log of the events Meridian ran: event names,
    machine ids, aggregate counts (files scanned, violations found) and the
    repository/spec/report paths involved. It stores no verdicts, no file:line
    anchors, no spec or source revisions and no file contents. Its chain is
    unkeyed SHA-256, so it detects edits to the log, but anyone with write
    access to the ledger file can recompute the chain. Tamper-evident, not
    tamper-proof.

Develop and test

python3 -m unittest discover -s tests -v   # 95 checks, stdlib only

Plugin layout: plugin.yaml + __init__.py + analyzer/ (scan, verify,
spec, ledger) + schemas.py + tools.py + skills/audit/SKILL.md.

License

MIT, see LICENSE.

README from the reviewed commit e876f60; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section