Shape Match

Shape Match

The skill IS the correct TCA shape loaded as the generation target. Training data's mass is procedural Python — services, mappers, dict-builders, if/elif routers. Without an explicit shape in working context, generation follows training gravity. The correct shape is the immediate reference, not a remembered principle.

Hooks are the post-edit gate. The shape loaded here is the pre-edit target. The two are complementary: the shape is what generation aims at; the hook is what survives if it misses.

Activation Scope

This skill MUST fire:

• Before writing any file in domain/.
• Before writing any new model class anywhere.
• Before writing an Evaluation Model derivation (any @cached_property on a *Evaluation model).
• Before writing a smart enum method (B.2 — a method on a StrEnum or Enum class).
• Before writing a smart variant method (B.3 — a method on a frozen BaseModel member of a discriminated union).
• When the user invokes /shape-match or says "check shapes".

Domain code is where training pulls hardest. In typical Python, domain logic is procedural code that uses models. In TCA, domain logic IS model construction and derivation. Without this skill loaded, generation follows the typical-Python path.

Protocol

1. Classify the file

The file's classification IS the shape's selector.

2. Load the rule

If .claude/rules/ contains a path-scoped rule matching the file, that rule is part of the loaded shape. The rule specifies what the file CONTAINS, what it IMPORTS FROM, and what has no home in it. The rule is the file's local shape; this skill is the global shape; both apply.

3. Generate against the shape

The loaded shape is the generation target. Each construct's match against the shape is the precondition for its existence in the file.

Scalars (type.py)

• Every type is RootModel[X] with frozen=True.
• Every field has a Field() constraint.
• The file's imports are stdlib and third-party only — nothing from the project.
• No methods, no validators, no logic. The type's existence is its proof.

Frozen domain models (wire-serializing and non-serializing)

• Fields are domain scalars, value objects, or other frozen models. Bare primitives (str, int, float, Decimal) have no home as field types. Collections of bare primitives (list[str], tuple[int, ...], set[str], dict[str, str]) have no home as field types either — narrow the element type.
• Derivations are @computed_field + @cached_property for wire shapes.
• Derivations are @cached_property alone for internal facts that stay in-process — derivation results excluded from model_dump().
• model_validator(mode="after") is admissible only as an A.3 impossible-variant-composition shape — /proof-design precedes its existence. A validator referencing one field against a constant is an A.1 left unforged. A validator comparing a proven field against a configured threshold is decision logic in the wrong shape — its home is hierarchy B.

Evaluation Models (*Evaluation)

• frozen=True.
• Fields are composed proven inputs — proven scalars, value objects, frozen models, configuration models, projections.
• Derivations are @cached_property alone (no @computed_field). Evaluation Models are internal; the wire shape is the intent or event the derivation yields on its own frozen model.
• Each derivation's return type is a typed result variant: a discriminated union (GateResult = GatePassed | GateRejected), a typed tuple, or a proven model. bool, int, and str-with-contextual-meaning are not admissible return shapes.
• Zero decision-validators. Construction succeeds for every well-formed input set.
• The body of each derivation is variant construction. The derivation may compose B.2 (smart enum methods) or B.3 (smart variant methods) for the variant-owned part — the F-test names the boundary.

class FileEvaluation(BaseModel, frozen=True):
    context: FileContext
    invariants: tuple[Invariant, ...]
    config: AnalysisConfig

    @cached_property
    def result(self) -> EvaluationResult:
        ...

Smart enum methods (B.2)

A definition on a StrEnum (or Enum) class. The F-test is the membership criterion.

• The signature is satisfied by the enum self plus proven scalars or proven value objects. A composed-model self (an *Evaluation, *Transition, *Decision) in the signature is an F-test violation — the derivation's home is the composed model (B.1), not the enum.
• The return type is a typed result variant. Primitives have no home as the return shape.
• The body's reference frame is the enum value plus the proven inputs in the signature.

class NodeKind(StrEnum):
    LEAF = "leaf"
    BRANCH = "branch"

    def child_count(self, node: ASTNode) -> ChildCount:
        return ChildCount(len(node.children)) if self is NodeKind.BRANCH else ChildCount(0)

Smart variant methods (B.3)

A definition on a frozen BaseModel member of a discriminated union. Polymorphic dispatch is Pydantic's discriminator narrowing the type at the variant boundary.

• The variant is a frozen BaseModel carrying its own fields and its own discriminator Literal.
• The F-test is the membership criterion. The signature admits proven DU inputs or proven value objects; a composed-model self is not admissible.
• The return type is a typed result variant.
• The method body is total over the variant's valid input subset.

class LeafNode(BaseModel, frozen=True):
    kind: Literal["leaf"] = "leaf"
    value: ProvenScalar

    def apply(self, event: NodeEvent) -> NodeState:
        ...

Active models

• Single unfrozen BaseModel per bounded context. Named for the domain concept.
• -> None mutation methods admissible here. State evolves through model operations on the model itself.
• Construction takes proven dependencies and frozen registries — not runtime lists of primitives. The active model's existence proves the enumeration was complete.

Services

• One class. One connect function. Transport setup only.
• Zero domain logic. Zero computation. Zero classification. Zero derivation.

Routes

• Contracts imported from domain/context/api.py.
• No model definitions. No computation.

main.py

• Composition root, nothing else.
• Observability bridge installed (loop exception handler forwarded to logger).
• Each config root constructed in one expression via BaseSettings. No os.environ reads. No multi-line config assembly. No procedural defaults.
• Transport connect — one call.
• Services bound — each .connect() returns the active model it produced.
• Keep-alive primitive — await event.wait(), await asyncio.gather(*tasks), or a documented irreducible-seam polling loop bridging a third-party SDK.
• Drain on shutdown in finally.

4. Post-generation verification

The shape is the precondition for the file's contents. Every construct is matched against the shape as a closing audit.

Training Gravity — Know What Pulls

These are the patterns training generates by default. Each has a TCA shape that occupies its slot entirely. Awareness of the pull is the first defense.

Source: kylejtobin/tca — distributed by TomeVault.