TrvthNvke

DeMoD LLC · maintained by ALH477

Git-enforced READMEs for DeMoD repositories. Every checkable sentence is a claim. CI, a pre-commit hook, and a Nix flake refuse drift. Agents edit through a dedicated MCP, not by freehand rewrite.

Published under GitHub user ALH477 for DeMoD LLC.

Current version: 0.4.0.

The README badge is docs/assets/trvthnvke-badge.svg, committed here rather than fetched from a shield service: no remote call, no embedded font, and every label pinned with textLength, so it renders identically on GitHub, in an offline Markdown preview and in a bare SVG viewer.

The mark is docs/assets/trvthnvke-emblem.svg — a radiation trefoil whose hub is a seal. At favicon size the check collapses to a dot and the trefoil still reads.

Install

The CLI entry is src/trvthnvke/cli.py.

It is exposed as the trvthnvke console script, wired to trvthnvke.cli:main.

This project was called truthgate before 0.4.0. The truthgate console script is kept as an alias onto the same trvthnvke.cli:main entry point, and .truthgate.toml / truthgate.toml are still accepted as policy filenames — new names win where both exist. tests/test_legacy_name.py exercises that fallback, so removing it fails the suite rather than silently breaking every repository written against the old name.

The agent server is src/trvthnvke/mcp_server.py.

Its stdio loop is run_stdio, a real function, not a promise.

PYTHONPATH=src python3 -m trvthnvke --help

From a checkout:

PYTHONPATH=src python3 -m trvthnvke --version

Related MCP server: flotilla-mcp

Usage

PYTHONPATH=src python3 -m trvthnvke extract --doc README.md

PYTHONPATH=src python3 -m trvthnvke schema

Structured edits (what the MCP applies):

[
  {
    "op": "upsert_claim",
    "id": "cli-module",
    "kind": "file_exists",
    "path": "src/trvthnvke/cli.py",
    "after_heading": "Install",
    "body": "The CLI entry is `src/trvthnvke/cli.py`."
  }
]

PYTHONPATH=src python3 -m trvthnvke edit --doc README.md --dry-run --ops '[{"op":"replace_claim_body","id":"version","body":"Current version: **0.4.0**."}]'

Flake

The dedicated flake is flake.nix. Other DeMoD trees import it; they do not vendor the Python package.

The package derivation lives in nix/package.nix.

The NixOS module is nix/module.nix (demod.trvthnvke.enable).

flake.nix names DeMoD LLC and ALH477.

Add the flake from GitHub user ALH477:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    trvthnvke.url = "github:ALH477/TrvthNvke";
  };

  outputs = { self, nixpkgs, flake-utils, trvthnvke }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ trvthnvke.overlays.default ];
        };
      in {
        devShells.default = pkgs.mkShell {
          packages = [ pkgs.trvthnvke ];
        };
        checks.readme = pkgs.runCommand "trvthnvke-readme" {
          nativeBuildInputs = [ pkgs.trvthnvke ];
          src = self;
        } ''
          cp -r "$src"/. .
          chmod -R u+w .
          trvthnvke verify --fail
          touch "$out"
        '';
      });
}

From a published checkout:

nix flake init -t github:ALH477/TrvthNvke
nix develop github:ALH477/TrvthNvke
nix run github:ALH477/TrvthNvke -- verify --fail
nix run github:ALH477/TrvthNvke#mcp

Path override while this tree is still local:

nix develop github:ALH477/your-repo --override-input trvthnvke path:../trvthnvke

NixOS / Oligarchy-style import:

{
  inputs.trvthnvke.url = "github:ALH477/TrvthNvke";
  outputs = { nixpkgs, trvthnvke, ... }: {
    nixosConfigurations.holdfast = nixpkgs.lib.nixosSystem {
      modules = [
        trvthnvke.nixosModules.default
        { demod.trvthnvke.enable = true; }
      ];
    };
  };
}

Outputs: packages.trvthnvke, overlays.default, apps.trvthnvke, apps.mcp, devShells.default, nixosModules.default, templates.default.

Example

Worked consumer tree: templates/consumer.

templates/consumer/flake.nix is the copy-paste import.

templates/consumer/flake.nix pins inputs.trvthnvke.url = "github:ALH477/TrvthNvke".

templates/consumer/README.md is already claim-gated.

PYTHONPATH=src python3 -m trvthnvke --root templates/consumer verify

What the example proves:

1. A DeMoD repo declares one flake input on ALH477.

2. The overlay puts trvthnvke on PATH inside nix develop.

3. checks.readme is a Nix gate equivalent to trvthnvke verify --fail.

4. The consumer README binds its own flake.nix so the import URL cannot silently change.

TruthMD

TruthMD is GitHub-flavored Markdown plus hidden claim directives. Rendered README stays normal Markdown.

Block claim (HTML comment, invisible on GitHub):

<!-- truth:claim
id: cli-module
kind: file_exists
path: src/trvthnvke/cli.py
severity: error
-->
The CLI entry is `src/trvthnvke/cli.py`.
<!-- truth:end -->

Fenced claim (the fence is the evidence):

```bash truth:id=help truth:kind=command truth:expect_exit=0
python3 -m trvthnvke --help
```

Mark example-only fences so CI does not try to execute them:

```python truth:ignore
print("documentation sample")
```

Claim kinds

file_contains matches a literal substring by default. Use regex: instead of pattern: to opt into Python re (256-char pattern cap, 2 MiB text cap, regex_timeout_sec timeout). Path-token coverage warnings scan every top-level directory of the repository unless coverage_dirs narrows the list.

Policy lives in .trvthnvke.toml.

This repository is gated by .trvthnvke.toml.

CI gates

Gates fail a commit or PR when any of these fire at error severity:

• claim verifier returns false

• required heading missing

• fenced block has neither truth:id nor truth:ignore

• malformed / duplicate / unclosed claim

• documented file missing

GitHub Actions workflow: .github/workflows/trvthnvke.yml.

Local hook template: hooks/pre-commit. Install with python3 -m trvthnvke install-hook.

Relative links that 404 become warnings (not merge blockers unless fail_on = "warning").

MCP

stdio MCP server for agents. No extra dependencies.

{
  "mcpServers": {
    "trvthnvke": {
      "command": "python3",
      "args": ["-m", "trvthnvke", "mcp"],
      "cwd": "/path/to/repo"
    }
  }
}

Tools:

Allowed edit ops: replace_claim_body, upsert_claim, remove_claim, replace_section, set_fence_meta.

Agents must not rewrite the whole README. They propose ops, verify, then apply.

Layout

Implementation lives under src/trvthnvke/ (parser, verifier, editor, MCP, CLI).

License

Apache-2.0. Copyright DeMoD LLC. See LICENSE.