hrns

Portable repository audit and document-gate CLI for source, docs, config, and project hygiene checks.

This package started as the reusable audit harness extracted from Agent-Zero. The primary implementation is a Go CLI that runs from a consumer repository root and executes packaged checks against that repository.

Requirements

• macOS or Linux
• Go is optional for source installs; npm installs download the native binary from GitHub Releases

Install

npm install -g @hgwk/hrns

Or install from source with Go:

go install github.com/hgwk/hrns/cmd/hrns@latest

Make sure $(go env GOPATH)/bin is on your $PATH. macOS/Linux:

export PATH="$(go env GOPATH)/bin:$PATH"

Quick Start

From another project:

cd /path/to/project
hrns version
hrns init --docs
hrns list
hrns list --json
hrns explain verify-line-count
hrns audit
hrns audit --with-ldgr

For local development and manual installs, use this shared convention:

install -m 0755 hrns ~/.local/bin/hrns

If another PATH directory must expose hrns, prefer a symlink back to ~/.local/bin/hrns instead of copying multiple binaries.

Local development in this repository:

go run ./cmd/hrns version
go run ./cmd/hrns list
go run ./cmd/hrns list --json
go run ./cmd/hrns explain verify-line-count
go run ./cmd/hrns audit
go run ./cmd/hrns audit --all
go run ./cmd/hrns audit --with-ldgr
go run ./cmd/hrns audit --target ../other-repo
npm run list:json
npm run audit:ldgr

Companion Suite

• cduo doctor checks pair-agent runtime setup and project hook readiness.
• ldgr verify checks ledger lifecycle, audit, worklog, and Git evidence.
• hrns audit checks repository structure, docs, config, and code guardrails.

Configuration

Create hrns.config.json with:

hrns init
hrns init --profile go

hrns init detects the current repository shape and writes roots for the directories and files that actually exist, such as src, tests, migrations, docs, package.json, and TypeScript config files. Use --profile node, --profile next, --profile go, or --profile rust when the repository shape should be selected explicitly.

Create a JSON document proposal template with:

hrns init --docs

hrns init also injects a short AGENTS.md / CLAUDE.md prelude and creates the home-local instruction body:

hrns init

Use --no-instructions only when a repository intentionally does not want hrns agent guide pointers. Use hrns init --home <path> to override the guide directory for isolated automation.

The CLI also reads package.json#hrns. hrns.config.json wins over package.json#hrns.

Useful keys:

{
  "auditSets": {
    "default": ["verify-line-count"],
    "all": ["verify-line-count", "verify-docs-duplication"]
  },
  "lineAudit": {
    "maxLines": 300,
    "roots": ["cmd", "internal", "scripts", "packages", "infra"],
    "extensions": [".go", ".ts", ".tsx", ".mjs", ".js", ".rs", ".sql"]
  },
  "env": {
    "example": ".env.example",
    "roots": ["packages", "scripts"],
    "requiredPrefixes": ["APP_", "OPENAI_"],
    "ignored": ["PATH", "NODE_ENV", "CI"]
  },
  "docsDuplication": {
    "mode": "fail",
    "roots": ["docs", "README.md"],
    "threshold": 0.72
  },
  "docsProposal": {
    "mode": "fail",
    "roots": ["docs", "README.md"],
    "proposalPath": ".hrns/doc-proposal.json",
    "threshold": 0.52,
    "titleThreshold": 0.45
  },
  "forbiddenReferences": {
    "mode": "warn",
    "roots": ["docs", "apps", "packages"],
    "rules": [{ "pattern": "legacy-api", "message": "use the current API surface" }],
    "allowPaths": ["^docs/archive/"]
  },
  "structureRatchet": {
    "mode": "fail",
    "files": [
      {
        "path": "apps/api/src/routes/users.ts",
        "maxLines": 120,
        "metrics": [{ "name": "raw fetch", "pattern": "\\bfetch\\s*\\(", "max": 0 }]
      }
    ]
  }
}

mode may be fail, warn, or off. hrns does not own task state, lessons, tickets, or worklogs; use ldgr for that layer.

Instruction injection matches cduo/ldgr prelude behavior. The actual rules live in ~/.hrns/audit-guide.md, and root policy files get only a top-of-file absolute @.../.hrns/audit-guide.md pointer. AGENTS.md and CLAUDE.md are both ensured by default; existing body content is preserved below the pointer. Set HRNS_HOME or pass hrns init --home <path> to override the home-local directory in tests or isolated environments.

This is the shared guide-pointer convention used by cduo, ldgr, and hrns: the home-local guide holds the long body, while root policy files only carry the absolute @... pointer and any project-local rules below it.

Audit Sets

Stable audits are intended to work across normal TypeScript/JavaScript repositories with little or no configuration:

• verify-line-count
• verify-docs-symbol-sync
• verify-sensitive-config-placeholders
• verify-no-orphan-fixtures
• verify-duplicate-helpers
• verify-thin-barrel-modules

Configurable audits are copied in, but still need project-shape options before they should be treated as universally portable:

• verify-env-example-symbol-sync
• verify-agent-instruction-drift
• verify-docs-duplication
• verify-doc-proposal
• verify-json-duplicate-keys
• verify-forbidden-references
• verify-magic-numbers
• verify-structure-ratchet
• verify-no-placeholder-routes
• verify-scope-drift
• verify-speculative-abstractions
• verify-regression-evidence
• verify-main-diff-scope
• verify-stop-rule
• verify-elegance-review

hrns list shows each audit as active, inactive, or needs config. Use hrns list --json for scripts and dashboards. The JSON output is schema-versioned. The formal contract lives in schemas/list.schema.json:

{
  "schema_version": 1,
  "stable_count": 6,
  "configurable_count": 15,
  "default_count": 6,
  "stable": [],
  "configurable": [],
  "default": []
}

hrns explain <audit-name> prints what the audit checks, which config keys it uses, its current status, and what a failure means.

Ledger validation is delegated to ldgr verify; hrns does not duplicate ledger state-model rules. Run hrns audit --with-ldgr when a repository should pass both repository guardrails and ldgr's ledger verification in one command. The repository must already be initialized with ldgr init; otherwise the ldgr portion correctly fails because no ledger state exists. Project-local runtime preflights, such as Agent-Zero watchdog checks, should live in that project's own runbook rather than in hrns. Upstream drift checks are project-specific and should be configured outside the portable default audit set.

verify-docs-duplication is the guard for agents that keep creating near-duplicate Markdown files. Set it to fail once a project has a settled documentation taxonomy.

The structural guardrails are config-driven:

• verify-json-duplicate-keys finds duplicate keys in JSON files before the parser silently keeps the last value.
• verify-forbidden-references blocks configured legacy names, docs, imports, or surfaces outside allowlisted paths.
• verify-magic-numbers warns on inline numeric policy values that should move to named constants.
• verify-structure-ratchet enforces per-file line and regex-count budgets.
• verify-no-placeholder-routes catches stable route files that still return placeholder, coming-soon, or not-implemented responses.
• verify-scope-drift compares changed files with active ldgr claim paths.
• verify-speculative-abstractions flags new single-use Manager/Factory/etc. surfaces that are likely premature.
• verify-regression-evidence warns when a bugfix-looking diff has no changed regression test.

For prevention before a new Markdown file exists, use the JSON proposal gate:

hrns docs:index
hrns docs:check .hrns/doc-proposal.json

docs:check compares the proposal's title, purpose, summary, and content against existing Markdown. If it overlaps, the proposal must switch to "decision": "update_existing" and set target to the existing document path. That turns "make another similar doc" into "patch the source of truth".

Pattern-only harness files are preserved under their original source paths:

• packages/e2e/helpers/servers.ts
• packages/desktop/test/desktop-wire-smoke.ts
• packages/desktop/test/desktop-wire-smoke-matrix.ts

Packaging Direction

Keep runnable generic checks in the Go CLI under cmd/hrns and internal/hrns. Checks should read the target repository from the current working directory.

Primary distribution is the Go module plus GitHub Release tarballs named hrns_<version>_<os>_<arch>.tar.gz. The npm package downloads the matching release binary during postinstall; its shell wrapper falls back to go run only when the native binary is absent, which is mainly useful for local source development.

Project-specific defaults belong in hrns.config.json or package.json#hrns instead of being hard-coded in each verifier.

Release Flow

• GitHub repository: hgwk/hrns
• npm package: @hgwk/hrns
• GitHub Releases hosts platform-specific Go binaries
• .github/workflows/release.yml builds and publishes binaries on version tags
• The npm package is published from GitHub Actions through npm Trusted Publishing (OIDC), not a long-lived NPM_TOKEN
• The npm package is a thin wrapper that downloads the appropriate binary from GitHub Releases on install
• Release tags must match internal/hrns/cli.go and package.json
• npm Trusted Publisher configuration:
  • Publisher: GitHub Actions
  • Organization or user: hgwk
  • Repository: hrns
  • Workflow filename: release.yml
  • Environment name: empty