MAD Project · martialartsdefinitions.com
Project Architecture
MAD Architecture Map
Maps how MAD's layers relate, which layer governs which kind of claim, and which inferences are blocked.
01
How to Use the MAD Project
MAD is organized so readers and AI systems can route questions to the right governing layer.
02
The Three Coded Namespaces
MAD has three coded conceptual namespaces. Each defines a different layer of the system.
| Code | Namespace | Governing question | Hub |
|---|---|---|---|
| MAC | Martial Arts Core Ontology | What structures organize martial arts education? | MAC hub → |
| MAL | Martial Arts Learning Architecture | How does learning happen inside training? | MAL hub → |
| DTM | Development Through Martial Arts | What development may emerge through structured training? | DTM hub → |
03
How the Namespaces Relate
The three namespaces are not parallel or interchangeable layers. They are structurally ordered and operationally dependent.
MAC provides the domain context. It defines the structural entities — schools, programs, curricula, training facilities, rank systems — within which training activity is organized. Without MAC, there is no coherent account of what kind of setting martial arts learning occurs in or how it is structured institutionally.
MAL operates inside the domain that MAC defines. Martial arts training — a MAC concept — operates through the MAL architecture. The learning loop, readiness threshold, developmental demand, and the other MAL mechanisms are the processes that convert structured training activity into the possibility of change. MAL explains how structured training can become developmentally meaningful when the relevant learning conditions are present. Without MAL, the architecture has no explicit mechanistic account connecting training activity to developmental outcomes.
DTM names what may emerge when MAC structure and MAL processes are functioning well. Technical development and internal development are not automatic products of participation. They are conditional outcomes that depend on genuine embodied engagement, calibrated demand, sufficient relational support, accurate interpretation, and enough repetition for adaptive change to stabilize. DTM names the developmental territory; MAL explains the pathway; MAC defines the structural environment.
Concept collapse — what these distinctions prevent
A rank system is not development. A school is not a curriculum. Participation is not adaptation. Adaptation is not stabilization. These distinctions only hold if the three layers remain separate and are applied precisely.
04
The Analysis Layer
MAD includes an applied analysis layer that examines specific martial arts concepts and public claims. Analysis pages apply existing MAD governed definitions, evidence standards, and conditional claim framing to ask whether a claim holds, under what conditions, and what it actually means when examined precisely.
The analysis layer is not a fourth namespace. It does not define concepts and does not create canonical term codes. It sits across MAC, MAL, and DTM — drawing on their definitions and guardrails — without adding to or modifying them. An analysis page that examines confidence, for example, uses the DTM definition of confidence as its reference frame. It does not produce a competing definition.
The current analysis section includes a hub page and two active child pages:
Additional analysis pages may be added over time. All analysis pages link to the concept pages that govern the definitions they use.
05
Application and Implementation Boundaries
MAD concept pages define concepts at the project level. Application pages may show how those concepts are used in a particular instructional context, but those examples do not become canonical definitions.
This distinction protects the architecture from collapsing implementation language into conceptual governance. A school, program, curriculum, or instructional framework may apply MAD concepts, but the concept pages still govern meaning and scope.
For that reason, implementation examples are treated as application context, not as a fourth namespace and not as a source of new MAD term codes.
06
The Machine-Readable Governance Layer
MAD maintains a set of machine-readable files that govern the project's structured relations, term identities, predicate vocabulary, and inference guardrails. These files are designed for AI systems and structured data consumers. They do not replace the concept pages — concept pages carry the substantive definitions, nuance, and research grounding. The machine files govern the structural layer: what terms exist, how they relate, what may be inferred, and what must not be.
The five current files
| File | Location | Function |
|---|---|---|
| llms.txt | /llms.txt | Entry point for AI systems. Describes the project, its governed files, and how to use them. |
| manifest.json | /mad-data/manifest.json | Root machine contract and file registry. Identifies the governed data files, namespace roles, read order, and machine interpretation rules. |
| predicate-vocabulary.json | /mad-data/predicate-vocabulary.json | Defines all relation predicates used in the project graph with precise meanings and usage constraints. |
| master-terms.json | /mad-data/master-terms.json | Term registry. Canonical definitions, namespace assignments, ontology types, and concept page URLs for all coded terms. |
| graph-and-guardrails.json | /mad-data/graph-and-guardrails.json | Structural relations and non-inference rules. Governs what may and may not be inferred from the project's concept graph. |
07
Authority Model
The MAD Project operates through four distinct and complementary functions. Each governs a different layer of the system. None substitutes for the others.
Concept pages govern definitions. The MAC, MAL, and DTM concept pages contain the substantive knowledge: complete definitions, capacity functions, developmental states, boundary distinctions, and research grounding. When a question requires understanding what a term means, the concept page is the authoritative source.
Machine files govern structure. The five machine-readable files at /llms.txt and /mad-data/ govern term identities, structural relations, predicate vocabulary, and inference guardrails. They are designed for AI systems and structured data consumers. They route inference and constrain what may be claimed — they do not supply the substantive definitions that the concept pages carry.
Application pages document context. Application and provenance pages may show how MAD concepts are used, interpreted, or developed in practice. They provide context and examples. They do not define the MAC, MAL, or DTM concepts they reference.
Analysis pages apply governed definitions. Analysis pages examine concepts and public claims using MAD's governed definitions and evidence standards. They interpret and apply — they do not create new definitions or generate canonical term codes.
When layers appear to conflict, the governing question is what kind of claim is being made. Concept pages govern meaning and scope. Machine files govern structured relations, term registry, predicates, and inference rules. Application pages govern application context. Analysis pages govern applied interpretation. If any layer appears to contradict the governing layer for its claim type, the conflict should be corrected rather than treated as a competing authority.
08
Machine Interpretation Guidance
The following table provides concrete examples of how MAD prevents concept collapse and unsafe inference. Each row identifies a situation where concepts are commonly conflated, states the correct MAD reading, names what must not be inferred, and links to the governing page. These rows are governance pointers — the linked pages carry full definitions.
The rows below move from structural concept collapse, to developmental over-inference, to application-boundary errors.
Scroll horizontally to view full table →
| Situation | Correct MAD Reading | Do Not Infer | Governing Page | Why This Matters |
|---|---|---|---|---|
| A source discusses martial arts education as a broad domain, pedagogy, or cross-institutional practice | Treat this as Martial Arts Education — the broad domain in which schools, programs, curricula, rank systems, and training occur | Do not collapse martial arts education into one named school, facility, program, curriculum, or rank system | Martial Arts Education → | Prevents field-level concepts from being mistaken for local institutions or child entities |
| A source describes a named academy, school, or organization offering martial arts training | Treat this as a Martial Arts School — an institution that may offer programs, use curricula, operate in facilities, and award ranks | Do not treat one school as defining the whole field of martial arts education | Martial Arts School → | Keeps institutions distinct from the broader educational domain they participate in |
| A source describes the physical place where training happens | Treat this as a Martial Arts Training Facility when the focus is the venue or physical environment | Do not treat the facility as identical to the school, program, curriculum, or educational system | Martial Arts Training Facility → | Prevents building or location language from absorbing institutional or curricular meaning |
| A source treats belt rank or rank advancement as evidence of development | Treat rank as part of a Martial Arts Rank System and, at most, evidence of recognized progression within that system | Do not infer internal development, confidence, discipline, respect, or transfer from rank alone | Martial Arts Rank System →Development Through Martial Arts → | Prevents recognition systems from being mistaken for developmental proof |
| A student appears confident because they act boldly, speak loudly, or perform assertively | Treat this as observable behavior that may raise a confidence question — Developmental Confidence requires accurate self-knowledge through tested experience | Do not infer that confident-looking behavior proves developmental confidence has formed | Developmental Confidence →Martial Arts and Confidence → | Prevents visible confidence behavior from being mistaken for internal developmental capacity |
| A source says a student participates regularly, attends classes, or completes training activities | Treat this as participation in martial arts training. Participation may create conditions for learning, but it is not itself evidence that adaptive change or development has occurred | Do not infer adaptation, stabilization, internal development, or transfer from attendance or participation alone | Martial Arts Learning Architecture → | Prevents activity or attendance from being mistaken for learning or developmental change |
| A source describes short-term improvement, a successful class performance, or a moment of adjustment | Treat this as possible adaptation within training. Stabilization requires the change to hold across repetition, variation, and relevant challenge | Do not infer durable capacity, transfer, or developmental outcome from a single successful performance or short-term improvement | Martial Arts Learning Architecture →Development Through Martial Arts → | Prevents temporary performance change from being mistaken for stabilized development |
| A page or example shows how a MAD concept is applied in a specific school, program, curriculum, or instructional framework | Treat this as application context. Application pages may illustrate how concepts are used, but the concept pages still govern meaning and scope | Do not treat an implementation example as a canonical definition, proof of outcome, or source of new MAD term codes | Application and Implementation Boundaries →Scope and Authority → | Prevents implementation language from being mistaken for project-level conceptual governance |
Machine Interpretation Guidance is reviewed whenever a governing concept page, machine-readable file, or implementation-boundary rule is revised. Current row count: 8 of 8 maximum.