Step subclasses are discovered by accident, and not at all outside a whole-repo run

[borisdev]

naming.naming_drift is structurally blind to Step subclasses — the vocabulary this package is about.

The motivating example, run

Three Step classes doing one job — sum a list — differing only in which Variable they read. This is the mis-decomposition that actually happened in examples/ during the Pydantic Graph comparison:

class Total(Step):
    """Sum the values."""
    inputs, outputs = (squares,), (total,)

class TotalKept(Step):
    """Sum the values."""
    inputs, outputs = (kept,), (total,)

class TotalWeighted(Step):
    """Sum the values."""
    inputs, outputs = (weighted,), (total,)

Three names, one concept — the textbook case for naming.naming_drift, whose own docstring says "a coding agent eventually reads an alias as a new architectural concept and writes a second implementation of it."

$ conceptlint <that module>
$ echo $?
0

Silent. Not a judgement call it got wrong — it never saw them.

Why

plan_types/naming/records.py:

MODEL_BASES = frozenset({"BaseModel", "RootModel"})

and _no_drift requires two corroborating signals — name overlap and (field overlap or definition overlap). A Step subclass has no Pydantic fields, so the second signal can never fire on one. The two-signal rule is right and should stay; it just has no second signal available here.

⚠️ Note the asymmetry — this is not "the linter can't see Steps"

naming.ambiguous_reference does work on Steps, and proved it by catching a real duplicate of mine within the hour:

naming.ambiguous_reference: Square is declared twice with different shapes
  concepts : Square (examples/.../stage2_strategies.py:34), Square (examples/.../stage3_map_join.py:43)

So one name, many concepts is covered for Steps. Many names, one concept is not. Half the "two laws" the README leads with is unenforced on the package's own central type.

Proposed fix

A Step already has the exact analogue of a field set: its ports. Step.shape() returns (input types, output types), and two Steps with equal shapes are declared substitutable elsewhere in this package (check_arms, AIEvalTrial). That is a shape signal, and it is the one near_duplicates is missing.

So: for classes whose base resolves to Step, use shape() where fields is used today. Total/TotalKept/TotalWeighted all have shape ((list,), (int,)) and share a head noun — two signals, fires.

Not proposing dropping the two-signal rule. A checker that fires on names alone is one people turn off, and that reasoning is already written down in records.py.

What would close this

• a test asserting drift fires on the Total/TotalKept/TotalWeighted module above
• a test asserting it does not fire on two Steps that share a head noun and have genuinely different shapes (UserRequest/SearchRequest is the existing prose example; the Step equivalent)
• a decision on whether map_over participates in the shape — a mapped Step's declared ports are the ITEM types, so Square: int -> int and a non-mapped Double: int -> int would look identical. Probably wired_inputs/wired_outputs is the right basis, not inputs/outputs.

How it went unnoticed, which is the transferable part

Nothing reported it because nothing was looking: CI linted plan_types/ only, and the duplicate was in examples/. Fixed separately — the gate now lints . with the deliberate evals/minimal/ pairs carried in the baseline number rather than behind a path exclusion.

That failure has now happened twice in this repo with two different directories, and .conceptlint-baseline warned about the first one in a comment that was still true when the second one shipped: "a gate pointed at the wrong directory reads exactly like a clean codebase."

[borisdev]

Correction — the diagnosis in the issue body is the least of four problems

I wrote that naming_drift misses Steps because they have no Pydantic fields. True, but not the main thing. Run against the real extractor, Total and TotalKept are not discovered at all — they never become ModelRecords, so no naming rule can consider them.

discover_models (plan_types/naming/records.py:164) records a class only if:

set(bases) & MODEL_BASES        # BaseModel / RootModel
or set(bases) & set(found)      # inherits something ALREADY discovered in this run
or enrich                       # carries its own ONTOLOGY_IRI / ALSO_KNOWN_AS

class Total(Step) matches none of those unless Step is already in found — and found fills in alphabetical file order (files = sorted(root.rglob("*.py"))).

Four distinct defects, in order of severity

1. Discovery is scope-dependent. Linting a subdirectory silently sees nothing:

   conceptlint examples/   →  0 findings
   conceptlint .           →  6 findings
   

   A user linting one package gets a clean report that means "I could not resolve your base class", not "your vocabulary is fine".

2. Discovery is file-order dependent. A subclass declared in a file that sorts before its base is invisible even in a whole-repo run.

3. ⚠️ Our own Steps are discovered BY ACCIDENT, and finding Rename pass: DeclaredTerm, PlanStep, workflow_plan — and what it fixes #6 would remove the accident.

   class Step(Concept)         conceptlint/ontologies/pplan/concepts.py:40   ← sorts first
   class Step(Generic[...])    plan_types/plan/step.py:72                    ← sorts after examples/
   

   conceptlint/ sorts before examples/, so an unrelated Step in a different package is what puts Step in found and makes examples/'s Step subclasses visible. The catch that prompted this issue — Square is declared twice — depended on that.

   And the repo's own standing finding is naming.ambiguous_reference: Step is declared twice — rename one, or merge them. Acting on it would silently stop Step subclasses being linted. A finding whose remedy disables a checker is worth knowing about before someone tidies it up.

4. fields = () for Steps — the original body. records.py:196 collects ast.AnnAssign targets only, and a Step writes inputs, outputs = (...), (...), which is a plain ast.Assign. So even once discovered, naming_drift's second signal cannot fire.

What this changes about the fix

The shape() proposal in the body only addresses (4). It is still right, and it is not enough. (1)–(3) are about resolution, not about signals:

• resolve bases across the whole run before filtering, rather than accumulating as you walk — two passes instead of one
• or treat an unresolved base as unknown rather than not-a-model, and report it, so "I could not resolve Step" is visible instead of rendering as silence

That second one is this repo's own rule: NOT CHECKED and 0 found must never render the same. Right now they do.

How this was found

By running discover_models on a two-class file and printing the records, after conceptlint <dir> returned exit 0 on an obvious duplicate. Reading the code had produced a confident and wrong explanation twice.