HEE-LINT(1) HEE Tools HEE-LINT(1)
NAME
hee-lint - fast lint gate for HEE-object YAML
SYNOPSIS
hee-lint [--mode warn|error]
hee-lint help | --help | -h
DESCRIPTION
Scans TRACKED *.yml/*.yaml. Two gates:
1. GOVERNANCE OBJECTS (fail-closed). A file that lives under contracts/,
hee/contracts/, blueprints/ or plans/ -- OR is named *.contract.yaml,
*.blueprint.yaml or *.plan.yaml -- MUST be a HEE object: it must carry
`apiVersion: hee/v1`, a top-level `kind:` matching its convention
(contract->Contract, blueprint->Blueprint|BlueprintDoctrine, plan->Plan),
and a top-level `spec:`. This closes the blind spot where a contract that
simply omitted the envelope was classified "not a HEE object" and passed
silently -- the malformation was what hid it. Derived/sample/archive trees
(tests/, */fixtures/, */examples/, */templates/, docs/history/) are exempt.
2. ENVELOPE OBJECTS. Any other file declaring `apiVersion: hee/v1` is checked;
everything else is ignored, so this is safe to run across a mixed repo.
Checks (both gates): metadata present and parseable, metadata.annotations present,
a null inuid's inuid_null_reason is in the sanctioned enum (bootstrap / test /
fixture / example / soa_pending; SSoT: the kind-registry's allowed_null_reasons),
metadata.annotations.inuid present, a null inuid accompanied by
inuid_null_reason, and -- when the object declares
inuid_derivation: sha256(inuid_seed) -- that the recorded inuid actually
reproduces from its own seed. An identity hash that does not derive from
the seed it names is a determinism claim the object cannot support.
OPTIONS
--mode warn report findings, exit 0 -- non-blocking (default)
--mode error report findings, exit 2 if any
ENVIRONMENT
HEE_LINT_SKIP git pathspecs to exclude, space-separated, e.g.
':!viz-dashboard/public/*' -- a rendered surface holding
copies of objects it does not own is derived, not a source,
and declaring that is the repo's job.
EXIT STATUS
0 OK clean, OR any findings under --mode warn
2 CRITICAL findings under --mode error
3 UNKNOWN cannot run -- not in a git repo, or an unrecognized option
--mode warn ALWAYS exits 0. That is deliberate, not an oversight: warn
mode's own name promises a non-blocking report, and it previously exited 1
on any finding, silently gating commits on pre-existing unrelated failures
(real incident, 2026-08-24). Only --mode error blocks.
Documented as measured, not as it "should" be -- this help IS the published
man page, so an aspirational exit table would publish a lie.
EXAMPLES
$ hee lint --mode warn tests/fixtures # ci
--mode warn reports findings without failing (exit 0), so it proves the
linter runs over the fixtures deterministically. --mode error exits 2 on a
finding and is left unmarked (it depends on what is under the path).
HEE-LINT(1)