Placemats
Understand the architecture through its governing distinctions.
These reference maps explain the relationships behind the engineering canon. They are editorial navigation aids derived from the source bundle, not additional normative specifications. Use the underlying principles, declaration trees, and check scripts as the authority.
Five Artifact Kinds
Principles, checks, lenses, skills, surfaces
Principles define what must hold. Checks are deterministic, standalone scripts that report specific violations. Lenses collect review disciplines and the checks that enforce them. Skills are on-demand agent procedures. Surfaces expose a shared internal API over transports. These categories have different responsibilities and should not be collapsed into one generic idea of a framework or methodology.
Two Axes of Verification
Construction and conformance
Two independent questions
Construction: Is the implementation built correctly? This includes import direction, forbidden cycles, and required structural boundaries. Construction can pass even when the wrong capability was built.
Conformance: Does the implementation match an independently authored specification? This requires two-way closure: every declared element must exist, and every existing element must be declared. The first catches omissions; the second catches unauthorized additions.
Independence is essential
A specification regenerated from the implementation it evaluates cannot detect drift. The expected structure must be independently authored or preserved as a stable baseline. Otherwise the comparison is circular: it proves only that the implementation agrees with itself.
How checks report
Checks are deterministic and return 0 when clean or complete, 1 when findings are reported, and 2 when the check cannot run. A failed or skipped check must not appear as a pass. Findings should identify concrete defects rather than persuasive opinions. The repository owner decides whether to accept the result and ship.
These axes are complementary, not interchangeable. Tests and linters can demonstrate aspects of construction without proving conformance to what was intended.
The Three-Layer Boundary
Surfaces → API → library
Surfaces translate and render. The API coordinates the operation and is the shared entry point. The library implements the work. Dependencies flow down from surfaces through API to library; peer API submodules are kept independent. A feature vertical can co-locate its library, API, and surface adapters without dissolving these dependency rules.
State & Delivery
Release, control, and accumulated state
State is classified by its persistence contract rather than by a convenient folder name. Some state ships with a release and admits no runtime writer; some changes only through an administrator's deliberate act; some is accumulated by the running system. Packaging, configuration, upgrade, and deployment should honor those distinctions so generated or operational state does not masquerade as committed source.