Mechanics: Sharpend the term Mechanics and added few

Author: Alwin Mark

doc/06_mechanics/README.md

@@ -1,198 +1,226 @@
 # Mechanics
 
-Mechanics are the **structural reinforcements**
-that turn organizational capabilities into lived reality.
+This directory contains the **canonical mechanics of Protopipe**.
 
-They are neither abstract principles
-nor concrete tool implementations.
+Mechanics are the structural core of Protopipe.
+They encode **non-negotiable consequences** that shorten feedback,
+reduce systemic risk, and make certain forms of work unavoidable
+while making others impossible or costly.
 
-Mechanics exist to make
-culture, feedback loops, and responsibility
-**operational and unavoidable**.
+Mechanics are **not solutions**, **not patterns**, and **not best practices**.
+They are enforced trade-offs.
 
 ---
 
-## What Mechanics Are
+## What a Mechanic Is
 
-Mechanics are repeatable, structural means
-that enforce desired behavior in everyday work.
+A mechanic exists to enforce a structural consequence.
 
-They answer the question:
+A mechanic:
 
-> **How do we make the right behavior  
-> the easiest behavior — by design?**
+- shortens feedback loops
+- removes options instead of adding features
+- encodes a deliberate trade-off
+- forces behavior through structure, not discipline
+- hurts a little — by design
 
-Mechanics operate at the intersection of:
-- architecture
-- process
-- feedback
-- organizational design
+If a rule can be ignored without consequence,
+it is not a mechanic.
 
-They are simple to explain,
-but difficult to implement holistically.
+---
+
+## The Core Principle
+
+> **Mechanics shorten feedback by enforcing consequences.**  
+> They do not describe solutions.  
+> They remove options.
+
+This principle is the foundation for all mechanics in Protopipe.
 
 ---
 
-## What Mechanics Are Not
+## Dependency Direction (Non-Negotiable)
+
+Mechanics sit in a strict dependency chain:
 
-Mechanics are **not**:
+```
+Problem
+↓
+Use-Case
+↓
+Mechanic
+↓
+Implementation
+```
 
-- features
-- tools
-- platforms
-- frameworks
-- methodologies
 
-Tools may implement mechanics.
-Frameworks may describe them.
-But neither defines them.
+- Problems describe tensions and pain.
+- Use-Cases describe desired, observable outcomes.
+- Mechanics enforce structural consequences.
+- Implementations are replaceable realizations.
 
-A mechanic exists
-even if the underlying tooling changes.
+**Noesis ends at the Mechanic.**  
+Implementations must never flow back.
 
 ---
 
-## Why Mechanics Matter
+## Naming Convention (Mandatory)
 
-Most organizational change fails
-not because of missing intent,
-but because behavior is optional.
+The **name of a mechanic is part of the mechanic**.
+It expresses the enforced trade-off explicitly.
 
-Culture is declared.
-Feedback is discussed.
-Responsibility is assigned.
+All mechanics **must** use **one of the following three naming forms**.
+No other forms are allowed.
 
-But nothing in the system
-*forces* these concepts to matter.
+### 1. `X over Y` — Explicit Trade-off
 
-Mechanics close this gap.
+Use this form when a mechanic enforces a clear preference
+between two competing approaches.
 
-They embed:
-- feedback into delivery
-- responsibility into boundaries
-- learning into execution
-- steering into daily work
+**Meaning**  
+X is structurally preferred.  
+Y is still possible, but discouraged or costly.
 
-Without relying on discipline or heroics.
+**Examples**
 
----
+- *Composability over Convenience*
+- *Observation over Orchestration*
+- *Eventual Consistency over Global Process Engines*
 
-## Mechanics and Culture
+---
 
-Culture does not scale through values.
-It scales through constraints and feedback.
+### 2. `X by Default, Y by Exception` — Default with Justification
 
-Mechanics are the **technical expression of culture**.
+Use this form when a behavior is allowed,
+but only with explicit justification.
 
-They determine:
-- whether problems surface early or late
-- whether learning is optional or mandatory
-- whether responsibility is visible or diffused
-- whether decisions are revisited based on evidence
+**Meaning**  
+X is the assumed baseline.  
+Y requires conscious, explicit reasoning.
 
-If a mechanic contradicts the culture,
-the mechanic wins.
+**Examples**
 
-Always.
+- *Eventual Consistency by Default, Atomicity by Exception*
+- *Open Source by Default, Closed Source by Justification*
 
 ---
 
-## Mechanics and Feedback Cycles
+### 3. `No X without Y` — Hard Constraint
 
-The strongest impact of mechanics
-is on feedback speed and quality.
+Use this form when a behavior must never occur
+unless a prerequisite is fulfilled.
 
-Good mechanics:
-- shorten feedback loops
-- localize feedback to the point of change
-- make cause and effect observable
-- reduce the need for coordination and escalation
+**Meaning**  
+X is forbidden unless Y is present.
 
-Poor or missing mechanics result in:
-- late feedback
-- global impact
-- defensive behavior
-- political decision-making
+**Examples**
 
-Feedback is not a reporting problem.
-It is a structural one.
+- *No Process Step without Testable Outcome*
+- *No Cross-Context Read without Event-Carried State*
+- *No Release without Observable Feedback*
 
 ---
 
-## Position in the Protopipe Layer Model
+### Naming Guidance (Important)
+
+- If the name does **not** clearly express loss or constraint,
+  it is not a valid mechanic name.
+- If the name sounds comfortable or neutral,
+  it is likely a pattern or guideline — not a mechanic.
+- The name should make the trade-off obvious
+  even without reading the document.
 
-Mechanics sit **below the narrative layer**
-and **above concrete implementations**.
+If the name does not “hurt” a little,
+rework it.
+
+---
 
-The overall layering is:
+## Mechanics vs. Patterns vs. Features
 
-1. **Problems**  
-   Systemic blockers that prevent learning and delivery.
+To avoid dilution, the following distinctions apply:
 
-2. **Use-Cases**  
-   Observable outcomes once problems are addressed.
+- **Mechanic**  
+  Enforces a consequence. Removes options.
 
-3. **Capabilities (APDP)**  
-   Organizational abilities required to sustain these outcomes.
+- **Pattern**  
+  Suggests a recurring solution. Optional.
 
-4. **Mechanics**  
-   Structural reinforcements that make these capabilities real.
+- **Feature**  
+  Describes functionality or capability.
 
-5. **Implementations**  
-   Concrete technical realizations (tools, platforms, code).
+Only mechanics belong in this directory.
 
-Mechanics translate **capabilities into system behavior**.
+Patterns, features, tools, and implementations
+must live elsewhere (e.g. `dist/`, reference implementations).
 
 ---
 
-## Why Mechanics Are Hard
 
-Mechanics are difficult because they:
+## Reference Implementations (Dogfooding)
+
+Every mechanic **may** provide a reference implementation.
+
+Reference implementations are:
+
+- explicitly **non-canonical**
+- intentionally minimal
+- used to **experience the enforced constraints in practice**
+- a means to apply the “eat your own dogfood” principle
+
+Their purpose is **not** to prove technical correctness,
+completeness, or scalability.
+
+Their sole purpose is to validate the **consequence** of a mechanic:
+
+- Are options actually removed?
+- Is the constraint felt in daily work?
+- Does feedback become shorter or clearer?
+- Is the trade-off tolerable?
+
+A mechanic candidate **must not** be promoted to approved status
+unless its constraints have been experienced
+through a reference implementation.
+
+Dogfooding is **necessary, but not sufficient**.
+
+If a reference implementation fails,
+this does **not** automatically invalidate the mechanic.
+However, the mechanic **must be questioned**.
 
-- cut across team and system boundaries
-- expose hidden assumptions
-- change power and responsibility distribution
-- require consistent application
-- cannot be “half implemented”
+Implementation must never justify the mechanic.
+The mechanic must justify the implementation.
 
-They often fail
-not due to technical complexity,
-but due to organizational resistance.
 
 ---
 
-## How to Read This Section
+## Candidate vs. Approved Mechanics
 
-Each mechanic described here:
+Not every good idea is immediately canonical.
 
-- links back to one or more APDP capabilities
-- explains the behavioral effect it enforces
-- avoids prescribing specific tools
-- highlights trade-offs and failure modes
+Mechanics may exist in two states:
 
-This section is **product knowledge**, not narrative.
+- **Candidates**  
+  Under evaluation, consolidation, or refactoring
 
-It is intended for:
-- architects
-- senior engineers
-- technical leadership
-- presales and solution design
+- **Approved**  
+  Stable, invariant, and accepted as canonical
 
-Not for pitching.
+Candidates are expected to change.
+Approved mechanics are expected to endure.
 
 ---
 
-## Summary
+## Final Rule
 
-Mechanics are the **leverage point** of Protopipe.
+If a mechanic does not:
 
-They make culture executable.
-They make feedback unavoidable.
-They make responsibility structural.
+- shorten feedback
+- enforce a trade-off
+- remove options
+- create visible consequences
 
-Without mechanics,
-capabilities remain aspirational.
+then it does not belong here.
 
-With mechanics,
-behavior changes — even under pressure.
+Be strict.
+Protopipe gains strength through constraint.