Type Hunter

Type Hunter

Audit code for type structure debt — one shape declared twice by hand, a type parameter that every instantiation binds to the same type, a constraint that hides what the body does with T, a conditional type where an intersection would do, a constant group with no named type, an alias where a distinct type was meant, an exported struct promoting Lock and Unlock to every importer. Goal: every type is declared once, no more generic than its uses, and built with the simplest construct that types every existing use at equal precision.

Supports Go, Python, TypeScript via per-language reference files.

Not covered (owned by other hunters): primitives standing in for domain concepts where no named construct exists yet, values travelling together with no type, a file accumulating unrelated types (→ smell-hunter); package organization, canonical import paths, and any hand-written mirror of a generated, ORM, SDK, or protobuf type, mapper included (→ boundary-hunter); optionality, unguarded narrowing, any / Any as a value type, exhaustiveness, as const / satisfies adoption for a value with no parallel declaration, validation of external input into an enum, never-checked zero sentinels (→ invariant-hunter); repeated logic and repeated runtime values, abstractions with one call site, runtime control flow, reinvented runtime primitives (→ simplicity-hunter); a struct embedding an interface it implements only partly, interface width (→ solid-hunter); test design and the structure of fixture or mock types (→ test-hunter; see Test-code scope); documentation restating types (→ slop-hunter); content validation at trust boundaries (→ security-hunter). Where ownership is contested, the category's Ownership: note in What to Hunt is authoritative.

When to Use

• Reducing type duplication across modules or packages after rapid growth
• Simplifying over-engineered generics or type-level logic
• Reviewing constant groups, enums, and aliases for the construct they are built with
• Cleaning up type definitions after prototyping
• Reviewing Go struct embedding before a package is exported or published

Quick Reference

Full rules in What to Hunt; every finding must also clear Not-a-finding and the category's evidence bar. Category names are canonical: the heading here, in What to Hunt, and in the report are identical. Six categories are universal (with per-language applicability, see Applicability); Embedding Antipatterns is Go-only and Reinvented Utility Types is TypeScript-only.

Hunter names are unsuffixed end-state names. Until consolidation completes, live skills are language-suffixed (boundary-hunter-go, test-hunter-py, security-hunter-ts, and so on).

Core Principles

1. Declare once; consolidate. Two hand-written declarations of one shape are a maintenance trap: a change to one must be replicated in the other. The finding names the concept, maps every member, and names the consolidation path — a derivation that preserves the shape, or deleting one copy and using the other. Where the language offers neither for the variant at hand, there is no finding; "keep in sync" is not an Action.

2. Generics must vary. A type parameter every instantiation binds to the same concrete type is indirection, not abstraction. The evidence is the enumerated instantiation set, tests marked and never counted as variation.

3. Constraints document intent. [T any], <T>, an unbounded TypeVar say nothing. The constraint should state what the body does with T; a body that compares, indexes, calls methods, type-switches, or bridges with an assertion has outgrown its constraint. A body that treats T as opaque has not, however many callers pass one shape — that is the generics-must-vary question.

4. Simplest construct at equal precision. A conditional type, a recursive type, an @overload tower, a ParamSpec, a hand-rolled mapped type earns its place only where a simpler form loses precision on some existing use. The replacement must accept the same inputs, reject the same inputs, and yield the same or a narrower result on every enumerated use. If any use needs the power, no finding.

5. Structure, not enforcement. This skill asks whether a type is declared once, no more generic than its uses, and built with the right construct. Whether the code guarantees an invariant — optionality, narrowing, bypasses, exhaustiveness — is invariant-hunter's question. Whether a primitive should become a domain type is smell-hunter's.

6. Consumers pay; counts nominate. An enum built with the wrong construct is a finding when a consumer pays for it — an untyped constant accepted where an int is, a formatted type with no String(), a .value comparison. Style alone is not a defect. Occurrence counts, member counts, and parameter counts nominate candidates and never decide a finding.

7. Respect the language. Go's small named types, consumer-defined interfaces, and composition are the language working as designed; Go has no derivation from a runtime value and no type-level constructs beyond constraints. TypeScript's structural typing makes plain aliases interchangeable, so alias mechanics are not judged there. Python's consolidation paths are weaker than TypeScript's; the reference names the ones that exist. Never recommend a type-level solution the language cannot express.

8. Scans nominate; reading decides. rg 'iota', rg 'TypeVar\(', rg 'enum\s+\w+' find every group. Nothing is a finding until the canonical declaration, every instantiation, every promoted-member consumer, and every site of a copy to be deleted have been read.

Terms

• Type structure debt — the skill's question: is this type declared once, no more generic than its uses, built with the simplest construct that types every existing use at equal precision? Not "does the code enforce this invariant" (invariant-hunter) and not "is this primitive a missing domain type" (smell-hunter).
• Declaration vs value — the simplicity/type ownership test. Repeated logic or runtime values across functions is simplicity-hunter's Duplication. Two type declarations of one shape — interface, type alias, struct, dataclass, TypedDict, Pydantic model, enum, union — are this skill's Duplicated Type Declarations, whatever the language. A hand-written union parallel to a runtime array is a declaration duplicating a value: here, in a language that can derive the union from the value (TypeScript); elsewhere Not a finding.
• Source kind — where the canonical declaration lives: sibling type (the other hand-written declaration), runtime value (as const array or object), schema (Zod, io-ts, Valibot, ArkType, TypeBox, Pydantic, msgspec — whatever the project already has). Named in the report's Source cell. A generated or external type (.pb.go, OpenAPI client, Prisma, ORM model, SDK type) is never a source kind here — see Cross-layer mirror.
• Consolidation path — the concrete fix a Duplicated Type Declarations finding must name; one of two. (a) A type-level derivation that preserves the shape: TypeScript Pick / Omit / Partial / Readonly / intersection, (typeof arr)[number], the installed schema library's inference type in the right role; Go embedding a shared struct where the outer type should carry its method set, otherwise an explicit field where the wire or storage shape allows it; Python inheritance of TypedDict, dataclass, or Pydantic model, Required / NotRequired for omittable-key variants. (b) Delete and use: one copy is deleted and the other used directly, which requires that every former site of the deleted copy accepts the surviving one. A finding requires one of the two. Where neither exists for the variant at hand, the duplicate is Not a finding — not a Low with "keep in sync". Pydantic can build optional variants at runtime; that produces no static field types and is not a path here.
• Cross-layer mirror — a hand-written declaration mirroring a generated, ORM, SDK, or protobuf type, with or without a mapper and whatever the mapper does. boundary-hunter's External Type Leaks and Missing Abstraction Over Externals own that relationship, mapper quality included; never duplication here, because the only "fix" this skill could name puts the external type where boundary-hunter says it must not go. Duplication is between two hand-written declarations whose consolidation path exists.
• Instantiation — one concrete binding of a type parameter, found project-wide by reading call sites and declarations, not by regex: TypeScript and Python infer arguments without writing them, Go writes them rarely at call sites. Test-file instantiations are recorded and marked (test) but never counted as variation.
• Closed consumer set — invariant-hunter's per-symbol rule, reused for every usage-based narrowing (Generics That Never Vary, Over-Powered Type Constructs, Embedding Antipatterns' used-subset argument). In application code the repository is the world and export alone is no limit. A symbol that a library publishes for consumers outside the tree, whose instantiations or callers therefore cannot be enumerated, is withdrawn and recorded as a Scope Limitation line. No repository-wide classification; the question is asked per exported symbol, read from how the package is published and used.
• Existence vs construct — the smell/type ownership test for enums and aliases. No named construct yet (raw string compared, bare str parameter) → smell-hunter's Primitive Obsession, whose reference names the remedy. A constant group, enum, or alias exists and is built with the wrong construct → here. Because this skill fires only where a construct exists, it never contradicts smell-hunter's remedy on the same site. TypeScript aliases are the exception: smell-typescript's brand-or-withdraw rule keeps the alias question there.
• Equal precision — the bar every "simpler form" must clear (Over-Powered Type Constructs, Reinvented Utility Types, and Duplicated Type Declarations' derivation): on every enumerated use the replacement accepts the same inputs, rejects the same inputs, and produces the same or a narrower result. A & B is not DeepMerge<A, B> when a member exists in both with different types (the intersection yields never); int | str is not an @overload tower that maps int → int and str → str.
• Within-skill precedence — one finding per site. On one type parameter, Generics That Never Vary wins (removing the parameter retires the constraint question); otherwise Over-Powered Type Constructs beats Loose Type Parameter Constraints. A Literal beside an Enum is Duplicated Type Declarations, cross-referenced from Enum Construct Mechanics, never both.
• Target scope and context — findings anchor in the manifest; the canonical declaration, every instantiation, every consumer of a promoted method, every site of a copy to be deleted, and test files are read wherever they live.

Not a finding on these grounds alone

Conditionals, not category exemptions — each states what does not justify a finding and, where one exists, what would:

• Separate request and response types at an API boundary that differ by validation, serialization tags, or consumer. Is Duplicated Type Declarations when both are hand-written, live in one layer serving one boundary, and a consolidation path at equal precision exists.
• Any hand-written type mirroring a generated, ORM, SDK, or protobuf type, with or without a mapper, whatever the mapper does. boundary-hunter's, always.
• Two types sharing some members, each with its own. Not duplicates. Members that travel together as parameters with no type at all are smell-hunter's Data Clumps.
• A duplicate with no consolidation path in this language (a Python patch type with every field optional over a dataclass or model; a Pydantic model beside a TypedDict where neither can be deleted; a Go or Python union parallel to a runtime sequence; a Go DTO where embedding leaks methods and a field changes the wire shape). No finding at any severity.
• An exported symbol whose consumer set cannot be closed inside the tree (a library's published generic, struct, or embedded surface). Withdrawn with a Scope Limitation line; the same symbol unexported, or in application code, is judged.
• A generic whose second instantiation is a test. Still Generics That Never Vary; the test is cited and the Action says how it survives. A second production instantiation withdraws the finding.
• [T any] / <T> / an unbounded TypeVar where the body treats T as opaque (stores, returns, passes through). The constraint matches the use, however many callers pass one shape — that question is Generics That Never Vary. Is Loose Type Parameter Constraints when the body compares, indexes, calls methods, type-switches, or bridges with an assertion.
• A type-level construct one existing use needs. Library types, framework constraints, and serialization boundaries may need conditional or recursive types; if any enumerated use requires the power, or the simpler form loses precision on any use, no finding.
• A hand-rolled utility with different semantics from the built-in (DeepPartial, a non-distributive Exclude, a Pick that errors on missing keys). Not reinvention.
• Raw strings compared with no constant group — smell-hunter's Primitive Obsession; this skill needs an existing construct.
• A bare str / string parameter for an identifier with no alias declared — smell-hunter's. Is Alias vs Named Type Mechanics when two aliases of the primitive exist and are mixed at a site.
• A Python class X(str, Enum) by itself; a Go named constant type with no String() that is never formatted, logged, or serialized; gaps or manual values inside an iota block. No consumer pays; no finding.
• A TypeScript enum with reverse mapping in use, bitwise flags, or non-TS consumers named in the code or its serialization; a const enum as such. Not Enum Construct Mechanics; the Action's risk clause exists for the borderline.
• A Go type X = Y alias with a deprecation or migration comment, or during a visible rename (both names in live use). Not a finding.
• A method-less Go named type, over a primitive or a composite. Not a finding.
• A sync.Mutex embedded in an unexported struct, or held as an unexported field. Not Embedding Antipatterns — a deliberately narrower line than the current linter view (see the Go reference).
• Embedding that promotes exactly what the consumers call (an io.Reader embed on a type whose consumers read). The language working as designed.
• as const on a config object with no parallel declared type — invariant-hunter's adoption finding, not duplication.
• A pattern in a test file — never a finding; test files are out of scope, not exempt (see Test-code scope).

What to Hunt

Categories are named, not numbered. Cross-references use category names (e.g. "→ Enum Construct Mechanics").

Duplicated Type Declarations

One shape declared twice by hand, where one declaration could follow the other, a runtime value, or a schema.

Signals — every one of them nominates; none is a threshold:

• Two interfaces, structs, dataclasses, TypedDicts, or models with matching member names and types in different files
• Create / update / summary / patch variants hand-listed from an entity; a readonly variant added field by field
• An as const array or object beside a hand-written union (TypeScript)
• A schema beside a manual type of the same shape
• Parallel const blocks or enums for one value set; a Literal beside an Enum
• The same complex inline type expression (nested generic, long Callable, Go func type) repeated at independent sites

Evidence bar: name the concept both declare; map every member of the derived declaration onto the source (subset, superset, or a modifier change: optional, readonly, nullable) — the Overlap cell says mapped/total; name the consolidation path (derive or delete-and-use) at equal precision, with every former site of a copy to be deleted read; show neither copy is a generated or external type. For a repeated inline expression: the independent sites, and that naming it once reduces concepts.

Action: derive from the source with the named mechanism — the utility type, (typeof arr)[number], the schema library's inference type in the right role, inheritance, Required / NotRequired — or delete the copy and use the survivor. For repeated inline expressions: name it once — an alias; a callable Protocol only when keyword arguments or overloads need it. In Go: embed only where the outer type should carry the method set, an explicit field where the wire or storage shape allows it, delete-and-use where one struct stands in for the other at every site; when none fits, withdraw.

Ownership: the declaration-vs-value test (see Terms). simplicity-hunter keeps repeated logic and repeated runtime values, and its own rule "duplication derivable from an existing source of truth" for values; two declared types of one shape, a declared union beside a runtime array, and a manual type beside a schema are here. Values travelling together with no type are smell-hunter's Data Clumps. Any cross-layer mirror is boundary-hunter's, mapper included (see Terms). as const recommended to make a value the derivation source of a declared union is this category's Action; as const / satisfies for a value with no parallel declaration stays invariant-hunter's Runtime Checks Promotable to Types. A Literal beside an Enum is reported here and cross-referenced from Enum Construct Mechanics.

Generics That Never Vary

A type parameter bound to one concrete type across every instantiation.

Signals:

• Cache[T] always Cache[User]; Store<T> with one instantiation
• Generic[T] where T appears in one field; a parameter used in one position only (return only; one field only)
• "Future-proofing" parameters with no second instantiation
• A generic function whose single call site fixes the type

Evidence bar: list every instantiation project-wide (call sites and declarations, inferred included), tests marked (test); show one concrete production type; the consumer set is closed inside the tree, else withdrawn with a Limitation line. A parameter used in one position only is the same finding when its instantiations agree.

Action: remove the parameter; use the concrete type. Reintroduce with the second instantiation. Where a test instantiates a fake, the Action says how the test survives (a fake of the production type).

Ownership: a value-level abstraction — wrapper, manager, factory, interface with no live seam — is simplicity-hunter's Unnecessary Abstractions; a type parameter with one instantiation is here. On one parameter this category takes precedence over Loose Type Parameter Constraints: removing the parameter retires the constraint question.

Loose Type Parameter Constraints

A constraint that does not express what the body does with T.

Signals:

• [T any] with comparable or method use inside; switch any(v).(type) inside func F[T any]
• <T> / <T extends unknown> / <T extends any> used as an object
• TypeVar("T") where only int | str is passed (constraints) or a base class is assumed (bound=); PEP 695 [T] with the same defects
• TypeScript only: a parameter receiving array or object literals whose tuple or literal types a downstream consumer re-narrows, and no const modifier

Evidence bar: name the operation the body performs on T that the constraint does not permit, or the bridge that makes it compile (any(v).(fmt.Stringer), (x as any)[k], cast); state the tightest constraint every existing instantiation satisfies. Go form: a generic body that type-switches on T — the constraint is any and the body enumerates types. TypeScript const form: the re-narrowing consumer, and that the parameter type is an array or object (a scalar T extends string already preserves the literal).

Action: tighten to the stated constraint. Go type switch: concrete functions, an interface, or a union constraint. TypeScript: add const to the parameter (TS 5.0+, read from the lockfile).

Ownership: any / Any as a constraint is here; any / Any as a value type is invariant-hunter's Type-System Bypasses (Go any / interface{} as a value type is nobody's, as invariant-hunter recorded). Precedence for the overlap: a bypass inside a generic body ((o as any)[k], cast(T, x), any(v).(X)) that a tightened constraint removes is one Loose Type Parameter Constraints finding here; invariant-hunter does not score the same cast. An opaque body is never Loose (see Not-a-finding).

Over-Powered Type Constructs (Python, TypeScript)

A type-level construct more powerful than any existing use needs.

Signals:

• TypeScript: a conditional type nested deep; recursion where a flat union suffices; mapped as remapping where Pick suffices; type-level string arithmetic a runtime function replaces; template-literal metaprogramming
• Python: ParamSpec / Concatenate decorator typing for one decorated signature where a Protocol suffices; @overload towers with one input→output mapping
• Many type parameters (nomination only)

Evidence bar: name the simpler construct and show it types every enumerated instantiation at equal precision; if any use needs the power, no finding. Parameter count nominates only.

Action: replace with the simpler construct. Where the power is needed (library types, framework constraints, serialization boundaries), no finding.

Ownership: type-level only; simplicity-hunter's Complex Control Flow and Reinvented Primitives are runtime code. Template literal overuse is here; a template literal type missing for a structured string domain is smell-hunter's Primitive Obsession. On one type parameter, Generics That Never Vary wins first; otherwise this category beats Loose Type Parameter Constraints. Not applicable to Go, which has no type-level constructs beyond constraints — the Go type-switch form is Loose Type Parameter Constraints.

Enum Construct Mechanics

An existing constant group or enum built with the wrong construct, with a consumer that pays for it.

Signals:

• Go: an iota group with no named type (untyped constants accepted anywhere an int is); a named constant type formatted, logged, or serialized (%v, %d, fmt.Sprint, JSON) with no String()
• TypeScript: an enum whose members are only ever compared or serialized (a union suffices; supporting evidence: value imports of the enum across modules that a type-only union would erase); a numeric enum for unordered non-flag values that is serialized; enum members compared to raw literals with ===; a single-member enum
• Python: members compared by .value against raw strings; a single-member Enum; a Literal[...] parallel to an Enum (reported as Duplicated Type Declarations, cross-referenced)

Evidence bar: anchor at the group; name the defect and the consumer that pays for it — the site that accepts the untyped constant, the formatting site with no String(), the comparison, the serialization.

Action: Go: a named type, a String() method (stringer as vocabulary, never run). TypeScript: a string-literal union, or an as const object with the union derived from it, with the serialization / non-TS-consumer risk named where the value crosses a boundary and erasableSyntaxOnly named where the project sets it. Python: member comparison (StrEnum as vocabulary at 3.11+); drop the single member.

Ownership: the existence-vs-construct test (see Terms). smell-hunter owns raw values compared with no constant group and names the remedy per language; this category owns the construct of an existing group and states no Enum-vs-Literal preference for Python beyond the mechanical markers. Validation of external input into an enum is invariant-hunter's (unguarded type claim at a trust boundary) or security-hunter's (content); a zero sentinel never checked is invariant-hunter's Zero-Value Traps. Value imports of an enum across modules are supporting evidence here, never a standalone finding and not boundary-hunter's.

Alias vs Named Type Mechanics (Go, Python)

An alias where a distinct type was meant.

Signals:

• Go: type X = Y with no migration or compatibility comment and no second name in live use
• Python: two aliases of one primitive (UserId: TypeAlias = str, OrderId: TypeAlias = str) with a site where one is passed where the other is declared — the mixing the alias was meant to prevent

Evidence bar: Go: the alias, and the absence of a migration comment and of a second live name. Python: both aliases and the mixing site.

Action: Go: a named type for distinction, or delete the alias. Python: NewType.

Ownership: identity types with no alias at all are smell-hunter's Primitive Obsession — this category needs an existing alias. Not applicable to TypeScript: structural typing makes plain aliases interchangeable, and smell-typescript's brand-or-withdraw rule keeps the alias question there.

Embedding Antipatterns (Go)

An embedding that promotes API surface the outer type's consumers should not have. Defined in full in references/type-go.md; summarized here so the category set is complete in one place.

Evidence bar: (1) sync.Mutex / sync.RWMutex embedded (not a field) in an exported struct — Lock / Unlock callable by every importer; (2) an embedded type whose promoted methods conflict with the outer type's own or exceed what any consumer in the repository calls — enumerate the promoted set and the used subset; consumer set closed, else withdrawn.

Action: an unexported field; delegate the used methods explicitly.

Ownership: a struct embedding an interface it implements only partly, leaving the embed nil, is solid-hunter's Broken Substitution however the panic is reached. Interface width is solid-hunter's Fat Interfaces; this category judges a struct's promoted method set.

Reinvented Utility Types (TypeScript)

A hand-rolled type equal to a built-in utility. Defined in full in references/type-typescript.md; summarized here.

Evidence bar: the built-in named; the project's TypeScript version (lockfile) supports it (gate 1); exact semantic parity including homomorphic modifier preservation (gate 3) — DeepPartial is not Partial, a distributive variant is not Exclude unless the built-in is also distributive there; net concept reduction (gate 6). simplicity-hunter's gates 2, 4, 5 are moot at type level.

Action: replace with the built-in.

Ownership: simplicity-typescript's primitive list has no utility types; unclaimed, kept here.

Within-skill precedence

One finding per site (see Terms). On one type parameter: Generics That Never Vary first — removing the parameter retires every constraint question; otherwise Over-Powered Type Constructs beats Loose Type Parameter Constraints. A Literal beside an Enum is Duplicated Type Declarations, cross-referenced from Enum Construct Mechanics. The Evidence cell of whichever is reported names the other reading in one clause.

Applicability

Six categories are universal in definition; each language reference declares them applicable or not, with the reason. A language with no reference is not supported — its files are excluded, never implicitly audited.

Language-only categories: Embedding Antipatterns (Go), Reinvented Utility Types (TypeScript). Python has none.

Test-code scope

Test files are excluded from findings — the deviation invariant-hunter and solid-hunter record. Test paths per language: Go *_test.go; Python test_*.py, *_test.py, tests/, conftest.py; TypeScript *.test.*, *.spec.*, *.e2e.*, __tests__/. The exclusion is by path: a production helper under tests/ is not audited.

Recorded gap: the design of a fixture type, a mock's generic helper, or a test-local duplicate of a production shape has no owner. test-hunter owns setup duplication, over-mocking, and coverage, not type structure inside tests; recorded here the way invariant-hunter recorded test-file suppressions, resolved at test-hunter's unification.

Test files are read as context:

• A test instantiation of a generic is listed in the Instantiations cell and marked (test); it never counts as variation and never withdraws a finding, and the Action says how the test survives the specialization.
• A test double that is the only second implementor of an embedded interface is recorded the same way.

Test evidence never raises Severity. Cite the test file in the Evidence cell; anchor the finding at the production declaration.

Severity and Impact

Every finding carries both, per the sibling definitions. They answer different questions and routinely diverge.

Severity — behavioral risk if left as-is:

• Critical — never available. Type structure debt is not itself a production defect. A drifted duplicate that is already producing wrong behavior names the divergence in Evidence and reports at High; the runtime defect is not scored here and this skill does not route it.
• High — a Duplicated Type Declarations finding whose copies have already diverged for the same concept with both copies live (a member present in one, absent or differently typed in the other, both consumed); an exported struct promoting Lock / Unlock to importers.
• Medium — the default for a finding that clears its bar.
• Low — a missing String() on a formatted constant type; an alias cleanup; a loose constraint on a generic with a single caller; a reinvented utility; a single-member enum.

A candidate that fails its evidence bar or matches a Not-a-finding conditional produces no finding at any severity. Severity is never a confidence scale: an uncertain finding — an instantiation set that could not be closed, a consolidation path not verified at every site — is withdrawn with a Limitation line, never downgraded.

Impact — how much the change is worth: contextual, never derived from occurrence count. A duplicated entity type every handler imports is High impact at Medium severity; a phantom parameter on an internal helper is Low.

• High — substantial reduction on a type read or changed often
• Medium — clear improvement on a moderately reached surface
• Low — clears the evidence bar but touches a small, rarely hit surface

Recommendations group by Severity (High → Medium → Low), then by Impact within each group.

Audit Workflow

Phase 1: Gain Context

1. Resolve the raw manifest. Scope may be:

   • Diff: files changed relative to the base branch — committed, staged, unstaged, untracked
   • Path: specific files, folders, or packages
   • Codebase: the entire project (default when unspecified; set SCOPE=.)

   Party mode: when the orchestrator supplies a scope snapshot, treat scope.txt as a file manifest only (one path per line). Read run metadata (base SHA, surface kind, counts) from scope-meta.txt when present. Use the manifest verbatim; do not re-resolve. The resolution below is for standalone runs only.

   For diff mode, resolve fail-closed:

   BASE=$(git symbolic-ref -q refs/remotes/origin/HEAD | sed 's@^refs/remotes/@@')
   git rev-parse -q --verify "$BASE^{commit}" >/dev/null 2>&1 || BASE=
   if [ -z "$BASE" ]; then
     for b in origin/main origin/master main master; do
       git rev-parse -q --verify "$b^{commit}" >/dev/null && BASE=$b && break
     done
   fi
   # BASE still empty: STOP and ask for an explicit base. Do not continue.
   MB=$(git merge-base "$BASE" HEAD) || exit 1                        # STOP: no merge base
   CHANGED=$(git diff --name-only --diff-filter=d "$MB") || exit 1    # STOP: diff failed
   UNTRACKED=$(git ls-files --others --exclude-standard) || exit 1    # STOP: ls-files failed
   DELETED=$(git diff --name-only --diff-filter=D "$MB") || exit 1    # STOP: diff failed
   SCOPE=$(printf '%s\n%s\n' "$CHANGED" "$UNTRACKED" | sed '/^$/d' | sort -u)
   

   Every command that supplies audit data is checked; only the base-discovery probes may fail, because failure there means "try the next candidate". One diff from the merge base to the working tree covers committed, staged, and unstaged changes. A file that existed at the merge base and is gone from the working tree lands in $DELETED; a file added after the merge base and deleted again appears nowhere. A failed command is never an empty scope.

   If $SCOPE is empty, run no scans: write the report with "Audit completed: 0 findings — empty diff scope", listing $DELETED under "Deleted in diff" if non-empty, and stop. If the resolved surface exceeds the context budget, report the file count and ask to narrow or chunk.

   Record provenance. Capture git rev-parse --short HEAD and whether the working tree is dirty (git status --porcelain -- $SCOPE); both go in the report's Scope section. On a dirty tree, line numbers match no commit — state that findings must be re-located by symbol name.

   The raw manifest is immutable and language-independent. Do not redefine it on a mixed scope — silently narrowing breaks the party guarantee that all hunters audit the same surface.

   Whitespace in paths is unsupported. The newline-delimited manifest plus -- $SCOPE shell expansion word-splits on spaces; whitespace paths are a declared limitation.

2. Detect languages from manifest extensions alone:

   • .go → go
   • .py, .pyi → python
   • .ts, .tsx, .mts, .cts → typescript

   Supported languages are Go, Python, and TypeScript. Every other extension — .js, .jsx, .mjs, .cjs included — is excluded, not audited: without a reference there is no consolidation-path vocabulary, no eligibility rule, no scan set, no version gate. Record excluded — no reference for .<ext>: {count} files in Scope, naming each extension.

3. Load language references. For every detected language, read references/type-<lang>.md from the directory this SKILL.md was read from (e.g. references/type-go.md). Fail closed: if a required reference cannot be read, stop and report; do not continue with the universal categories only.

4. Derive per-language eligible subsets by applying each reference's generated-code and vendoring rules plus the test-path exclusion to that language's files. These subsets are then immutable. Record in Scope: raw manifest count, each per-language eligible subset, exclusions with the test paths listed, and References loaded: {go, python, typescript as present}.

   Drop from eligibility only: vendored trees, lockfiles, Markdown-only inputs, test paths, and generated files identified by each reference's authoritative in-file marker — never by filename guessing.

   If nothing eligible remains: write Audit completed: 0 findings — no eligible source in scope and stop before

…(truncated)