What Shape Is

Shape is a typed architecture conformance language. It describes the semantic shape of a system in files that reviewers can read and a checker can evaluate.

It is not a programming language in the usual sense. Shape files do not execute application logic, compile TypeScript, or infer arbitrary behavior from source code. They make claims explicit:

• this resource is append-only
• this component owns that resource
• this function emits these effects
• this implementation path is governed by a component shape
• this refactor-sensitive function has recorded design context
• this change set updates the Shape model when architecture behavior changes

The contract is simple:

LLM-authored semantic model
+ human-reviewed shape files
+ deterministic checker
+ CI enforcement

Source of truth

.shape files are the source of architectural truth. Application code can be messy, implicit, or spread across many files; Shape gives the codebase a compact review surface.

The checker judges the claims in .shape files. Optional source analyzers can point out suspicious omissions, but analyzer hints do not replace the declared model.

Core workflow

1. An architecture model lives under shape/**/*.shape.
2. PRs update that model when source behavior changes the contract.
3. Reviewers inspect the source evidence attached to effects.
4. Reviewers inspect any rationale, memory, or reevaluation attached to refactor-sensitive functions.
5. CI runs shp check, shp coverage, format checks, tests, and type checks.
6. Diagnostics explain the causal path behind each rejection.

Product boundary

Shape is useful when the architecture question can be represented as a checkable claim. It is not a proof assistant, a replacement for tests, or a replacement for code review.

The useful boundary is: humans and LLMs write claims; humans review claims; the checker rejects incoherent claims.