Herald

Field	Value
Revision	3
Created	2026-05-15
Last modified	2026-05-20
Status	active
Status summary	Updated spec links to V3 (active) + archive/ for V1/V2; repo-layout block reflects current docs/specs/mvp/ tree.
Issues	none
Issues summary	—
Fixed	spec-path references updated to specification.V3.md path
Fixed summary	aligned README with the V1→V2→V3 supersession chain
Continuation	—

Table of contents

• Status
• Mission
• Deployment model
• Governance — Helix Constitution inheritance
• Repository layout
• Quickstart for developers and agents
  • 1. Place a copy of the Helix Constitution alongside Herald
  • 2. Verify the inheritance contract
  • 3. Read the inherited rules
• Operator setup guides
  • Messengers
  • LLM / agent dispatchers
  • Credentials master guide
• Mirror & push convention
• License
• Contact / contribution

Ingesting system events and reliably fanning them out to multiple notification channels so every alert reaches the right destination without confusion.

---

Status

Herald is pre-implementation (2026-05-15). The repository currently contains:

• This README.
• The current specification at docs/specs/mvp/specification.V3.md — comprehensive (~3900 lines): project-integration contract, inbound processing pipeline, LLM/agent dispatch with Claude Code, tri-stage reply protocol, versioned reports, multi-format outbound attachments, nine refined flavors. V1 and V2 preserved in docs/specs/mvp/archive/ for traceability.
• Project-specific Constitution + operator/agent guides under docs/guides/.
• Mirror declarations at upstreams/ — one shell script per host that exports UPSTREAMABLE_REPOSITORY.
• The inheritance gate + paired mutation meta-test at tests/.
• .gitignore tuned for Go (*.test, go.work*, coverage.*) and .DS_Store.

There is no go.mod, no Go source code, and no build tooling yet. Intended language is Go; standard cmd/ + internal/ layout will be used when scaffolding starts.

Mission

Herald sits between systems that emit events and humans/services that want to be told about them. It guarantees:

• Every event is delivered to every configured channel for its category.
• Duplicate suppression and routing are explicit, not accidental.
• Delivery failures on one channel never block delivery to other channels.

Deployment model

Herald is designed to be consumed as a git submodule of a larger project (the "consuming project"). The consuming project provides:

• The Helix Constitution submodule at its own <consuming-project>/constitution/.
• Its own CI / build orchestration that drives Herald.
• Any project-wide configuration (credentials, deployment targets, channel registries).

Herald therefore does not carry its own copy of the constitution. See docs/guides/CONSTITUTION_INHERITANCE.md for the full rationale and the discovery contract that lets Herald locate the constitution at runtime from any nested depth.

Governance — Helix Constitution inheritance

Herald inherits unconditionally from the Helix Universal Constitution. Inheritance is enforced by a paired gate + mutation meta-test under tests/ (see below). Herald-specific extensions live in docs/guides/HERALD_CONSTITUTION.md; there are currently no overrides of any universal clause.

Key invariants Herald inherits from the constitution:

• No bluffing — every PASS carries positive evidence (§11.4).
• Mutation-paired gates — every new gate has a paired mutation proving it catches regressions (§1.1).
• No guessing language — likely, probably, maybe, seems, appears are forbidden when reporting causes (§11.4.6).
• Credentials never tracked — .env git-ignored, runtime-load only (§11.4.10).
• Multi-upstream push — every commit fans out to GitHub + GitLab + GitFlic + GitVerse (§2.1).
• Hardlinked backup before destructive ops (§9).

The constitution lives at https://github.com/HelixDevelopment/HelixConstitution and is mirrored to GitLab, GitFlic, and GitVerse.

Repository layout

Herald/
├── README.md                                  # this file
├── CLAUDE.md                                  # guidance for Claude Code agents
├── AGENTS.md                                  # guidance for generic CLI agents
├── LICENSE
├── .gitignore
├── docs/
│   ├── guides/
│   │   ├── HERALD_CONSTITUTION.md             # Herald's project constitution (extends Helix)
│   │   └── CONSTITUTION_INHERITANCE.md        # operator/agent guide for the inheritance contract
│   └── specs/
│       └── mvp/
│           ├── specification.V3.md           # active spec (operator-product)
│           └── archive/
│               ├── specification.V1.md       # historical, superseded
│               └── specification.V2.md       # historical, superseded
├── upstreams/                                 # Herald's mirror declarations
│   ├── GitHub.sh
│   ├── GitLab.sh
│   ├── GitFlic.sh
│   └── GitVerse.sh
└── tests/
    ├── test_constitution_inheritance.sh       # inheritance gate
    └── test_constitution_inheritance_meta.sh  # paired mutation meta-test (§1.1)

Quickstart for developers and agents

1. Place a copy of the Helix Constitution alongside Herald

If you cloned Herald standalone (not as a submodule of a larger project), put a clone of the constitution next to Herald (not inside it — see §104 of the Herald Constitution):

git clone git@github.com:HelixDevelopment/HelixConstitution.git \
    $(dirname "$PWD")/constitution

This is only needed for standalone work. When Herald is consumed as a submodule of a larger project, that project already provides <parent>/constitution/.

2. Verify the inheritance contract

bash tests/test_constitution_inheritance.sh        # gate (7 invariants)
bash tests/test_constitution_inheritance_meta.sh   # paired §1.1 mutation proof

Both MUST exit 0. The gate prints PASS … / FAIL … per invariant and a summary line. The meta-test prints ✓ META-TEST PASS when the gate correctly fails on a mutated constitution.

If I1 fails (constitution not found), follow the message — clone the constitution alongside Herald.

3. Read the inherited rules

In this order, read fully before submitting any change:

1. <discovered-constitution>/CLAUDE.md + Constitution.md — universal Helix rules.
2. <discovered-constitution>/AGENTS.md — anti-bluff, no-guessing, paired mutations.
3. This README — Herald overview.
4. CLAUDE.md / AGENTS.md — Herald-specific guidance.
5. docs/guides/HERALD_CONSTITUTION.md — Herald's articles §101–§106.
6. docs/guides/CONSTITUTION_INHERITANCE.md — the discovery contract and gate semantics.
7. docs/specs/mvp/specification.V3.md — current spec (active). Historical V1/V2 in docs/specs/mvp/archive/.

Operator setup guides

Every supported messenger and every supported LLM / agent dispatcher has its own step-by-step setup guide under docs/guides/. Live ones are detailed end-to-end (obtain credentials → set env vars → verify integration tests → troubleshooting). Planned ones are placeholder stubs that reserve the env-var names so your .env stays stable as features land.

Messengers

Channel	Status	Guide
Telegram	LIVE (HRD-011 code complete; awaiting live evidence)	docs/guides/messengers/TELEGRAM.md
Slack	Planned (V2)	docs/guides/messengers/SLACK.md
Email (SMTP + Resend)	Planned (V2)	docs/guides/messengers/EMAIL.md
Max	Planned (V2)	docs/guides/messengers/MAX.md
Microsoft Teams	Planned (V3)	docs/guides/messengers/TEAMS.md
Lark / Feishu	Planned (later)	docs/guides/messengers/LARK.md
Discord	Planned (later)	docs/guides/messengers/DISCORD.md
WhatsApp Business	Planned (later)	docs/guides/messengers/WHATSAPP.md
Viber	Planned (later)	docs/guides/messengers/VIBER.md

LLM / agent dispatchers

Dispatcher	Status	Guide
Claude Code	LIVE (HRD-012 Fixed — live E18 evidence captured)	docs/guides/dispatchers/CLAUDE_CODE.md
OpenCode	Planned	docs/guides/dispatchers/OPENCODE.md
Aider	Planned	docs/guides/dispatchers/AIDER.md
Gemini	Planned	docs/guides/dispatchers/GEMINI.md
Cursor	Planned	docs/guides/dispatchers/CURSOR.md
Anthropic Managed Agent	Planned	docs/guides/dispatchers/ANTHROPIC.md

Credentials master guide

docs/guides/OPERATOR_CREDENTIALS.md is the umbrella reference covering:

• The 12-factor resolution order (CLI flag > shell exports > .env > defaults)
• How to set credentials via ~/.bashrc / ~/.zshrc (shell-export path) AND .env (project-local path) — both supported per spec V3 §3.3
• Pre-commit secrets audit checklist (.env not tracked; no obvious-format secrets; .env.example only has placeholders)
• Quickstart-compose vs native pherald operating modes
• Troubleshooting (SQLSTATE 28P01, "DSN not set", SKIP-with-reason logic per §11.4.3, …)

Per Universal Constitution §11.4.10: .env files MUST NEVER be committed. The repo's .gitignore already covers .env. The committed quickstart/.env.example is the only credentials-file that lives in git, and it contains only placeholder values.

Mirror & push convention

Herald is mirrored to four hosts. The origin remote is fan-out: one fetch URL + four push URLs. A single git push origin main propagates to every mirror in one operation.

Remote name	URL
github	git@github.com:vasic-digital/Herald.git
gitlab	git@gitlab.com:vasic-digital/herald.git
gitflic	git@gitflic.ru:vasic-digital/herald.git
gitverse	git@gitverse.ru:vasic-digital/Herald.git
origin	(fetch from github; push fans out to all four)

Each entry under upstreams/ is a shell script that exports a single UPSTREAMABLE_REPOSITORY=… URL and is meant to be sourced, not executed for its output. Capitalization matches each host's brand (GitFlic, GitVerse); do not normalize to lowercase or collapse into one file — external mirror-push tooling keys on the per-file split.

If you ever need to rebuild the fan-out configuration, the constitution submodule ships install_upstreams.sh that consumes Upstreams/*.sh declarations and configures git remotes accordingly; the same pattern can be adapted for Herald.

License

LICENSE — see file for terms.

Contact / contribution

Substantive contributions land via PRs on GitHub; mirrors are read-only for external consumers. Inheritance rules and the gate apply to every PR.