Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
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)