0028 Authoritative Invariant Encoding

Date: 2026-08-11

Status

Accepted.

Context

Harness already requires repository authority before externally observable policy changes. It did not give fresh consumers a direct route for turning an accepted architecture, reliability, security, or quality boundary into a mechanical check. It also did not ask onboarding to compare documented invariants with executable validation.

Without that route, agents may leave accepted rules as prose, invent policy from conventions, add a parallel validation framework, or overstate a local or CI check as merge enforcement.

Decision

1. The compact agent entrypoint routes invariant work to one installed pattern.
2. The workflow requires accepted authority first, the repository-native validation owner, the smallest mechanical check, actionable diagnostics, and both positive and negative proof.
3. Core installs $encode-invariant. Its trigger covers requests to enforce boundaries, prevent recurrence, add structural guards, or convert accepted rules into validation. Matching requests may invoke it implicitly; it cannot infer policy from conventions, code patterns, tests, defaults, or undocumented preferences.
4. $onboard-repository compares accepted invariants with executable checks in its read-only proposal pass. It reports unenforced rules and checks lacking authority without editing, executing, enabling, or removing guards.
5. Reports distinguish local validation, optional hooks, checked-in CI invocation, observed CI results, and external branch protection. None of these levels proves another.
6. The guidance remains implementation-neutral. It prescribes no application architecture, language, linter, hook, CI provider, merge policy, or branch protection and does not mutate external settings.

Alternatives Considered

1. Treat tests or conventions as policy. Rejected because executable and observed truth cannot resolve a missing normative choice.
2. Put the complete method in AGENTS.md. Rejected because every task would pay the context cost for specialized invariant work.
3. Create a universal validator. Rejected because consumer repositories own their languages, tools, validation commands, and enforcement topology.
4. Make onboarding silently repair gaps. Rejected because discovery remains read-only and cannot grant authority to mutate what it finds.

Consequences

• Fresh consumers can discover and apply one authority-gated invariant flow.
• Accepted prose can gain recurrence proof without a second validation system.
• Onboarding exposes documentation/check drift while preserving its read-only first pass.
• Agents must report unknown external enforcement rather than infer merge blocking from checked-in files.
• The core payload and release candidate grow by one pattern and one skill.