init

2026-02-05 01:51:29 +01:00 · 2026-02-05 01:51:29 +01:00 · 41481636d8
commit 41481636d8
12 changed files with 2126 additions and 0 deletions
--- a/rules/index.md
+++ b/rules/index.md
@ -0,0 +1,21 @@
+# Rules
+
+The ABC Pattern is defined and enforced through two complementary rule families:
+
+* [Normative Rules](normative.md)
+* [Validation Rules](validation.md)
+
+Together, these rule sets establish the semantic, structural, and mechanical
+guarantees that make ABC architectures predictable, verifiable, and safe for
+automated reasoning and transformation.
+
+Although closely related, the two rule families serve distinct purposes:
+
+**Normative Rules** define the semantic contract of the ABC Pattern. They
+specify what MUST, SHOULD, or MAY be true in any ABC‑compliant architecture,
+independent of implementation language, cloud provider, or IaC tool.
+
+**Validation Rules** define the mechanical checks required to verify that an ABC
+architecture conforms to the Normative Rules and the ABC Schema. Where Normative
+Rules describe what must be true, Validation Rules describe how to detect
+violations.
--- a/rules/normative.md
+++ b/rules/normative.md
@ -0,0 +1,273 @@
+# Normative Rules
+
+The ABC Pattern is defined by a set of Normative Rules that establish the
+structural, behavioral, and data‑flow guarantees of the architecture. These
+rules are the foundation that makes ABC:
+
+* predictable
+* composable
+* verifiable
+* agent‑friendly
+* implementation‑agnostic
+
+Normative Rules describe what MUST or SHOULD be true in any ABC‑compliant
+architecture, regardless of the underlying cloud provider, IaC tool, or
+programming language. They are not suggestions or stylistic preferences; they
+are the semantic constraints that ensure ABC constructs behave consistently and
+safely.
+
+Each rule is assigned a canonical identifier of the form:
+
+```default
+ABC-R#
+```
+
+This identifier is stable, unique, and referenced throughout:
+
+* the ABC Schema
+* validation rules
+* implementation profiles (e.g., CDKTS, Terraform)
+* agent guidance
+* tooling and linters
+
+## Hierarchy Rules
+
+These define the allowed structure of an ABC architecture, including the roles
+and relationships of ApplicationStacks, Logical Units, and Resource Groups.
+
+### ABC‑R1 (MUST)
+
+An Application Stack (ABC‑C1) MUST contain one or more Logical Units (ABC‑C2).
+
+### ABC‑R2 (MUST)
+
+A Logical Unit (ABC‑C2) MUST contain one or more Resource Groups (ABC‑C3).
+
+### ABC‑R3 (MUST)
+
+Every Construct (ABC‑C0) MUST have exactly one parent, except the Application
+Stack (ABC‑C1), which has none.
+
+### ABC‑R4 (MUST)
+
+Constructs MUST form a strict tree hierarchy with no cycles.
+
+### ABC‑R5 (SHOULD)
+
+Logical Units (ABC‑C2) SHOULD represent coherent functional domains.
+
+### ABC‑R6 (MAY)
+
+Resource Groups (ABC‑C3) MAY be nested further if the implementation framework
+supports sub‑constructs, provided all other rules remain satisfied.
+
+## Relationship Rules
+
+Specify how constructs relate to one another, including parent‑child
+constraints, allowed dependencies, and prohibited lateral references.
+
+### ABC‑R10 (MUST)
+
+A Resource Group (ABC‑C3) MUST NOT reference another Resource Group directly.
+
+### ABC‑R11 (MUST)
+
+A Logical Unit (ABC‑C2) MUST NOT reference another Logical Unit directly.
+
+### ABC‑R12 (MUST)
+
+A Construct (ABC‑C0) MUST NOT access parent state except through Capturing Down
+(ABC‑F1).
+
+### ABC‑R13 (MUST)
+
+A Construct (ABC‑C0) MUST NOT access sibling state under any circumstances.
+
+### ABC‑R14 (MUST)
+
+All cross‑domain communication MUST be mediated by the parent construct.
+
+### ABC‑R15 (SHOULD)
+
+Constructs SHOULD minimize the number of outputs they expose to reduce coupling.
+
+### ABC‑R16 (MAY)
+
+A parent MAY aggregate outputs from multiple children before re‑exposing them.
+
+## Interface Rules
+
+Define the semantics of Input and Output Contracts, including immutability,
+explicitness, and the boundaries they enforce.
+
+### ABC‑R20 (MUST)
+
+Every Construct (ABC‑C0) MUST define an Input Contract (ABC‑C4).
+
+### ABC‑R21 (MUST)
+
+Every Construct (ABC‑C0) MUST define an Output Contract (ABC‑C5), even if empty.
+
+### ABC‑R22 (MUST)
+
+A Construct MUST NOT depend on any value not present in its Input Contract.
+
+### ABC‑R23 (MUST)
+
+A Construct MUST NOT expose any value not present in its Output Contract.
+
+### ABC‑R24 (MUST)
+
+Input Contracts MUST be immutable after instantiation.
+
+### ABC‑R25 (SHOULD)
+
+Output Contracts SHOULD be minimal and stable across versions.
+
+### ABC‑R26 (MAY)
+
+A Construct MAY expose composite outputs if they simplify parent‑level wiring.
+
+## Instantiation Rules
+
+Specify how constructs are created, how inputs are provided, and how
+instantiation must avoid side effects or hidden dependencies.
+
+### ABC‑R30 (MUST)
+
+A Construct (ABC‑C0) MUST be instantiated exclusively through its Instantiation
+Interface (ABC‑C6).
+
+### ABC‑R31 (MUST)
+
+Instantiation MUST be top‑down: parents instantiate children; children MUST NOT
+instantiate parents or siblings.
+
+### ABC‑R32 (MUST)
+
+The Instantiation Interface MUST accept only the Input Contract (ABC‑C4) and no
+additional parameters.
+
+### ABC‑R33 (MUST)
+
+Instantiation MUST NOT produce side effects beyond constructing the child.
+
+### ABC‑R34 (SHOULD)
+
+Instantiation Interfaces SHOULD remain stable across minor revisions.
+
+### ABC‑R35 (MAY)
+
+Constructs MAY provide optional parameters in the Input Contract if defaults are
+well‑defined.
+
+## Data Flow Rules
+
+Formalize the two fundamental ABC data‑flow mechanisms:
+
+* Capturing Down (parent → child)
+* Bubbling Up (child → parent)
+
+These rules ensure that all communication flows through the parent construct,
+eliminating ambiguity and hidden coupling.
+
+### ABC‑R40 (MUST)
+
+All downward data flow MUST occur through Capturing Down (ABC‑F1).
+
+### ABC‑R41 (MUST)
+
+All upward data flow MUST occur through Bubbling Up (ABC‑F2).
+
+### ABC‑R42 (MUST)
+
+A Construct MUST NOT read values from its parent except those explicitly passed
+via Capturing Down.
+
+### ABC‑R43 (MUST)
+
+A Construct MUST NOT write values to its parent except through Bubbling Up.
+
+### ABC‑R44 (MUST)
+
+Parents MUST mediate all routing of outputs between children.
+
+### ABC‑R45 (SHOULD)
+
+Parents SHOULD avoid passing unnecessary outputs downward to reduce coupling.
+
+### ABC‑R46 (MAY)
+
+Parents MAY transform outputs before passing them down.
+
+## Encapsulation & Testability Rules
+
+Ensure that constructs remain isolated, testable, and free from cross‑cutting
+concerns. These rules prevent leakage of internal details and enforce strict
+boundaries.
+
+### ABC‑R50 (MUST)
+
+Constructs MUST encapsulate all internal implementation details.
+
+### ABC‑R51 (MUST)
+
+Constructs MUST be instantiable in isolation using mock Input Contracts.
+
+### ABC‑R52 (SHOULD)
+
+Constructs SHOULD avoid exposing internal resource identifiers unless required.
+
+### ABC‑R53 (SHOULD)
+
+Constructs SHOULD minimize internal state to simplify testing.
+
+### ABC‑R54 (MAY)
+
+Constructs MAY provide diagnostic outputs if they do not violate encapsulation.
+
+## Evolution & Change Management Rules
+
+Define how ABC architectures evolve safely over time, including versioning,
+contract stability, and backward‑compatible changes.
+
+### ABC‑R60 (MUST)
+
+If a child’s Output Contract changes, the parent MUST adapt explicitly.
+
+### ABC‑R61 (MUST)
+
+Breaking changes to Input Contracts MUST be versioned or documented.
+
+### ABC‑R62 (SHOULD)
+
+Constructs SHOULD maintain backward compatibility where feasible.
+
+### ABC‑R63 (SHOULD)
+
+Parents SHOULD validate child outputs before routing them.
+
+### ABC‑R64 (MAY)
+
+Constructs MAY deprecate fields gradually before removal.
+
+## Optional Flexibility Rules
+
+Provide non‑mandatory guidance that enhances clarity, maintainability, or
+ergonomics without affecting correctness. These rules are advisory and may be
+adopted at the discretion of the implementation or team.
+
+### ABC‑R70 (MAY)
+
+Logical Units MAY be composed dynamically if the framework supports it, provided
+all other rules remain satisfied.
+
+### ABC‑R71 (MAY)
+
+Resource Groups MAY be reused across Logical Units if instantiated
+independently.
+
+### ABC‑R72 (MAY)
+
+The Application Stack MAY expose a composite Output Contract aggregating all
+Logical Unit outputs.
--- a/rules/validation.md
+++ b/rules/validation.md
@ -0,0 +1,155 @@
+# Validation Rules
+
+The ABC Validation Rules define the mechanical checks required to verify that an
+ABC architecture conforms to the ABC Schema and the normative rules of the
+specification. These rules are intended for:
+
+* automated validators
+* linters
+* compilers
+* agent‑driven code generation
+* CI/CD enforcement
+
+Validation Rules are **not** conceptual rules; they are operational constraints
+that ensure an ABC description is structurally correct and unambiguous.
+
+Validation Rules follow the canonical identifier format:
+
+```default
+ABC-VALID-R#
+```
+
+They are grouped into:
+
+* Structural Validation
+* Contract Validation
+* Data‑Flow Validation
+* Hierarchy Validation
+* Profile‑Specific Validation (optional)
+
+## Structural Validation Rules
+
+These rules ensure the ABC hierarchy is well‑formed.
+
+### ABC-VALID-R1 (MUST)
+
+Every construct MUST have exactly one parent, except the ApplicationStack which
+MUST have none.
+
+### ABC-VALID-R2 (MUST)
+
+The hierarchy MUST follow the pattern:
+`ApplicationStack → LogicalUnit → ResourceGroup`.
+
+### ABC-VALID-R3 (MUST)
+
+Construct trees MUST NOT contain cycles.
+
+### ABC-VALID-R4 (MUST)
+
+Construct IDs MUST be unique within the architecture.
+
+### ABC-VALID-R5 (MUST)
+
+Construct types MUST be one of:
+ApplicationStack, LogicalUnit, ResourceGroup.
+
+### ABC-VALID-R6 (MUST)
+
+ResourceGroups MUST NOT have children.
+
+### ABC-VALID-R7 (MUST)
+
+LogicalUnits MUST NOT have parents that are not ApplicationStacks.
+
+### ABC-VALID-R8 (MUST)
+
+ResourceGroups MUST NOT have parents that are not LogicalUnits.
+
+## Contract Validation Rules
+
+These rules ensure Input/Output Contracts are well‑defined and consistent.
+
+### ABC-VALID-R10 (MUST)
+
+Every construct MUST define both an InputContract and an OutputContract.
+
+### ABC-VALID-R11 (MUST)
+
+InputContracts MUST be immutable after instantiation.
+
+### ABC-VALID-R12 (MUST)
+
+Constructs MUST NOT reference values not present in their InputContract.
+
+### ABC-VALID-R13 (MUST)
+
+Constructs MUST NOT expose outputs not declared in their OutputContract.
+
+### ABC-VALID-R14 (SHOULD)
+
+OutputContracts SHOULD be minimal and stable across versions.
+
+### ABC-VALID-R15 (MUST)
+
+InputContracts MUST NOT reference parent or sibling constructs directly.
+
+### ABC-VALID-R16 (MUST)
+
+OutputContracts MUST NOT expose internal implementation details (e.g., resource
+objects).
+
+## Data‑Flow Validation Rules
+
+These rules enforce Capturing Down and Bubbling Up.
+
+### ABC-VALID-R20 (MUST)
+
+All downward references MUST originate from:
+
+* parent.InputContract
+* parent.OutputContract
+
+### ABC-VALID-R21 (MUST)
+
+All upward references MUST originate from:
+
+* child.OutputContract
+
+### ABC-VALID-R22 (MUST)
+
+No lateral data flow is permitted between siblings.
+
+### ABC-VALID-R23 (MUST)
+
+Constructs MUST NOT read values from grandparents or ancestors except through
+parent‑mediated Capturing Down.
+
+### ABC-VALID-R24 (MUST)
+
+Constructs MUST NOT write values to ancestors except through Bubbling Up.
+
+### ABC-VALID-R25 (MUST)
+
+Constructs MUST NOT read or write values from siblings or cousins.
+
+## Instantiation Validation Rules
+
+These rules ensure constructs are instantiated correctly.
+
+### ABC-VALID-R30 (MUST)
+
+Constructs MUST be instantiated using the Instantiation Interface:
+(scope, id, inputs).
+
+### ABC-VALID-R31 (MUST)
+
+Instantiation MUST NOT accept parameters outside the InputContract.
+
+### ABC-VALID-R32 (MUST)
+
+Instantiation MUST NOT produce side effects beyond constructing children.
+
+### ABC-VALID-R33 (MUST)
+
+Constructs MUST NOT mutate their InputContract after instantiation.