commit 90f622056797064c19ef37fe7b69e4135de83494 Author: Jeremy Anderson Date: Thu Jul 2 18:01:46 2026 -0400 first draft of openengineer spec diff --git a/CHARTER.md b/CHARTER.md new file mode 100644 index 0000000..4830e5e --- /dev/null +++ b/CHARTER.md @@ -0,0 +1,23 @@ +# Charter + +## Purpose + +Open Engineer is an open standard for preserving engineering context. + +Open Engineer does not seek to tell engineers what to think. It seeks to preserve how engineers arrive at understanding. + +## Nature of the Standard + +Open Engineer is a standard. Not a philosophy. Not documentation. Not an AI project. Not a website. Those become implementations. The standard comes first. + +## Core Principles + +- **Stewardship over Ownership** — We do not own engineering. We steward it. +- **Translation over Adoption** — We translate observations into engineering principles without adopting surrounding ideologies. +- **Observation First** — All additions begin with verifiable observation. +- **The Thread** — Knowledge is carried through continuity across generations. +- **Bedrock** — Reality remains fixed. Understanding grows around it. + +## Scope + +The standard is open, humble, respects every discipline, and welcomes ideas from every culture and every generation. It remains firmly anchored to reality through observation, verification, and stewardship. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..70e802a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,40 @@ +# Contributing to Open Engineer + +## The Bedrock Phase + +Open Engineer is currently in **The Bedrock Phase**. During this phase, contributions follow a strict linear workflow. + +## How to Contribute + +### The Four-Question Framework + +Every proposed addition must answer four questions: + +1. **Observation?** — What was observed that prompted this? +2. **Engineering Principle?** — What engineering principle does this express? +3. **Reasoning?** — What is the reasoning that connects the observation to the principle? +4. **Relationship to Existing Concepts?** — How does this relate to what already exists in the standard? + +Nothing enters Bedrock without surviving those four layers. + +### The Workflow + +1. **Observe** — Begin with a direct, verifiable observation +2. **Draft** — Write the proposed addition +3. **Review** — Submit for review against the four-question framework +4. **Accept** — If it passes review, it is accepted +5. **Freeze (RC)** — Accepted documents reach Release Candidate status +6. **Reference** — Frozen documents become reference material + +### Editorial Rules + +- **Translate. Do not transplant.** — Extract engineering principles from observations without adopting surrounding ideology. +- **Single Responsibility** — Every document must have exactly one primary responsibility. +- **No Overlap** — The spec defines. The reference explains. The examples illustrate. The tools implement. + +### Important Constraints + +- Do not skip ahead in the specification dependency tree +- Do not redefine earlier layers — only extend them +- Do not add free-form exploration; channel ideas through the RFC process +- Stop touching implementations (website, tools) until the specification is frozen \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9eb78e4 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) Open Engineer Project + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..44422b2 --- /dev/null +++ b/README.md @@ -0,0 +1,32 @@ +# Open Engineer + +**An open standard for preserving engineering context.** + +Open Engineer does not seek to tell engineers what to think. It seeks to preserve how engineers arrive at understanding. + +## What Is Open Engineer? + +Open Engineer is a standard. Not a philosophy. Not documentation. Not an AI project. Not a website. Those become implementations. The standard comes first. + +## Quick Start + +- **[CHARTER.md](CHARTER.md)** — Project charter and purpose +- **[ROADMAP.md](ROADMAP.md)** — Current phase and development roadmap +- **[CONTRIBUTING.md](CONTRIBUTING.md)** — How to contribute +- **[spec/](spec/)** — The canonical specification (OE-0000 through OE-0011) +- **[rfc/](rfc/)** — Requests for Comments (RFC-0000 through RFC-0006) +- **[reference/](reference/)** — Vocabulary, patterns, and editorial principles +- **[laws/](laws/)** — Engineering laws and communication principles +- **[examples/](examples/)** — Illustrative examples (weaving, bridges, clockwork, Antikythera) + +## Mission + +It gave engineering a common language for preserving understanding across people, projects, generations, and intelligent systems — so that every generation could begin a little closer to bedrock than the last. + +## Structure + +The spec defines. The reference explains. The examples illustrate. The tools implement. No overlap. + +## License + +See [LICENSE](LICENSE). \ No newline at end of file diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..a3b1aa4 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,55 @@ +# Roadmap + +## Current Phase: The Bedrock Phase + +Every sentence accepted during this phase is intended to support everything built above it. If this phase is executed carefully, the website, schemas, AI integrations, tooling, and future implementations will not require anything new to be invented. They will simply express what already exists in the specification. + +That is the hallmark of a good standard: the specification leads, and everything else follows. + +--- + +## Bedrock Phase Goals + +1. Freeze repository layout +2. Write specification documents linearly (OE-0000 through OE-0011) +3. Establish RFCs (RFC-0000 through RFC-0006) +4. No skipping. No jumping ahead. No "while we're here." + +## Specification Dependency Tree + +``` +Charter (OE-0000) + -> Foundation (OE-0001) + -> Core Vocabulary (OE-0002) + -> Engineering Context (OE-0003) + -> Observation (OE-0004) + -> Survey (OE-0005) + -> Understanding (OE-0006) + -> Verification (OE-0007) + -> Decisions (OE-0008) + -> Stewardship (OE-0009) + -> Inheritance (OE-0010) + -> Evolution (OE-0011) +``` + +Nothing later may redefine an earlier layer. Only extend it. + +## Workflow + +``` +Observe -> Draft -> Review -> Accept -> Freeze (RC) -> Reference +``` + +Once a document reaches RC status, it is not rewritten unless a later RFC explicitly supersedes it. + +## Future Phases + +- **Implementation Phase** — Website, schemas, tooling +- **Integration Phase** — AI systems, IDE plugins, documentation generators +- **Community Phase** — Open contributions, discipline-specific extensions + +--- + +## Note + +The specification leads, and everything else follows. \ No newline at end of file diff --git a/examples/antikythera.md b/examples/antikythera.md new file mode 100644 index 0000000..90683d1 --- /dev/null +++ b/examples/antikythera.md @@ -0,0 +1,30 @@ +# Example: Antikythera Mechanism + +**Status:** Draft +**Phase:** The Bedrock Phase + +## Overview + +The Antikythera mechanism is an ancient Greek analog computer used to predict astronomical positions and eclipses. It represents one of the earliest known examples of complex engineering — and one of the most dramatic examples of lost engineering context. + +## Why the Antikythera Mechanism Matters + +The Antikythera mechanism was built around 100-200 BC. It contained over 30 gears and could predict the positions of the sun, moon, and planets. Nothing of comparable complexity appeared again for over a thousand years. + +The thread broke. + +When the knowledge of how and why this mechanism was built was lost, it took humanity over a millennium to re-derive comparable capabilities. This is the catastrophic consequence of failed inheritance. + +## The Cost of Lost Context + +We know what the Antikythera mechanism does. We have only partial understanding of how it was designed, and almost no understanding of the full engineering context — what observations led to its design, what constraints the builders faced, what alternatives they considered. + +This is precisely the problem Open Engineer exists to prevent. + +## Observations Extracted + +| Observation | Engineering Translation | +|---|---| +| The Antikythera mechanism's complexity was not exceeded for over 1,000 years after it was lost | Lost engineering context causes civilizational regressions | +| Modern analysis required reverse-engineering from physical remains | Without preserved context, recovery requires re-derivation from first principles | +| The mechanism demonstrates that advanced engineering is not a modern invention | Engineering principles predate modern disciplines | \ No newline at end of file diff --git a/examples/bridge-survey.md b/examples/bridge-survey.md new file mode 100644 index 0000000..e0518e2 --- /dev/null +++ b/examples/bridge-survey.md @@ -0,0 +1,30 @@ +# Example: Bridge Survey + +**Status:** Draft +**Phase:** The Bedrock Phase + +## Overview + +Bridge building is one of the oldest and most visible engineering disciplines. A survey of bridge engineering across history reveals patterns that directly illustrate Open Engineer's core principles. + +## Why Bridge Engineering Matters + +Bridges are public, load-bearing, and long-lived. They must serve their purpose for decades or centuries. A bridge that fails is not merely inconvenient — it is catastrophic. This creates an extreme pressure to preserve engineering context: why was this bridge designed this way? What forces does it need to withstand? What materials were chosen and why? + +## The Survey Approach + +A bridge survey would assess: + +1. **Observations:** What did the engineers observe about the site, the materials, the load requirements? +2. **Decisions:** What design choices were made? What alternatives were considered? +3. **Context:** What constraints shaped those decisions (economic, technical, environmental)? +4. **Verification:** How was the design verified before construction? +5. **Inheritance:** What prior bridge-building knowledge was inherited? What was improved? + +## Observations Extracted + +| Observation | Engineering Translation | +|---|---| +| Bridge designs inherit knowledge from prior bridges | Engineering is inherently cumulative | +| A bridge must be verified against real forces before use | Understanding is provisional until verified against reality | +| Bridge failure often results from lost context (e.g., why a specific material was chosen) | Context preservation prevents catastrophic failure | \ No newline at end of file diff --git a/examples/clockwork.md b/examples/clockwork.md new file mode 100644 index 0000000..0616800 --- /dev/null +++ b/examples/clockwork.md @@ -0,0 +1,26 @@ +# Example: Clockwork + +**Status:** Draft +**Phase:** The Bedrock Phase + +## Overview + +Clockwork mechanisms demonstrate the principle that meaning emerges from relationships between components. A clock is not a collection of gears — it is a specific arrangement of gears that produces the measurement of time. + +## Why Clockwork Matters + +Clockwork is a pure example of structure carrying meaning. Each gear, spring, and escapement has no inherent relationship to time. It is only when they are arranged in precise relationship to each other that timekeeping emerges. Remove one component or alter one relationship, and the clock fails. + +## The Thread in Clockwork + +Clockwork also illustrates the thread principle in a different way: the transfer of motion. In a clock, motion is transferred from the power source (spring or weight) through a chain of interconnected mechanisms to the display (hands). Each link in this chain must be precisely maintained. If any link fails, the transfer stops. + +This maps to engineering knowledge transfer: each generation is a link in the chain. If any generation fails to maintain and pass on its understanding, the chain of accumulated knowledge breaks. + +## Observations Extracted + +| Observation | Engineering Translation | +|---|---| +| A clock's function emerges from gear relationships, not individual gears | System properties emerge from component relationships | +| Motion transfer requires every link in the chain to function | Knowledge transfer requires every generational link to function | +| Clock designs improved incrementally over centuries | Engineering progress is spiral re-evaluation, not revolution | \ No newline at end of file diff --git a/examples/weaving.md b/examples/weaving.md new file mode 100644 index 0000000..a733c6e --- /dev/null +++ b/examples/weaving.md @@ -0,0 +1,28 @@ +# Example: Weaving + +**Status:** Draft +**Phase:** The Bedrock Phase + +## Overview + +Weaving is one of the oldest engineering traditions in human history. It demonstrates principles that Open Engineer has identified as universal: structure carries meaning, the thread as a model for knowledge continuity, and the relationship between individual components and emergent patterns. + +## Why Weaving Matters + +A woven fabric is not a collection of threads. It is a specific arrangement of threads that creates properties — strength, flexibility, pattern — that no individual thread possesses. The meaning (the fabric's properties) emerges entirely from the relationships between components. + +This is precisely the pattern described in OE-0001 (Foundation) under "Structure Carries Meaning." Weaving is the original example of this principle. + +## The Thread + +Weaving also gives us the metaphor — and model — of the thread. In weaving, each thread is continuous. If a thread breaks, the fabric weakens. If many threads break, the fabric fails. The continuity of each individual thread is essential to the integrity of the whole. + +Open Engineer adopted "the thread" as a core model precisely because this dynamic maps directly to engineering knowledge: continuity of understanding is essential to the integrity of the engineering tradition. + +## Observations Extracted + +| Observation | Engineering Translation | +|---|---| +| A fabric's strength comes from thread relationships, not individual threads | System properties emerge from component relationships | +| A broken thread weakens the entire fabric | Lost context weakens the entire body of engineering knowledge | +| Weaving patterns are inherited across generations | Engineering knowledge is inherited across generations | \ No newline at end of file diff --git a/laws/communication-principles.md b/laws/communication-principles.md new file mode 100644 index 0000000..b144c79 --- /dev/null +++ b/laws/communication-principles.md @@ -0,0 +1,36 @@ +# Communication Principles + +**Status:** Draft +**Phase:** The Bedrock Phase + +## Overview + +These principles govern how Open Engineer communicates its ideas — both within the standard's own documents and in any implementation or derivative work. + +--- + +## 1. Observe, Don't Preach + +Open Engineer does not seek to tell engineers what to think. It seeks to preserve how engineers arrive at understanding. + +The standard documents process, not doctrine. It shows the path to understanding, not the destination as a fixed point. + +--- + +## 2. Examples Carry Load + +Examples are not decorations. They are transportation. + +Every communication from Open Engineer should use examples to bridge from the unfamiliar to the familiar. A principle stated without an example is incomplete. + +--- + +## 3. Structure Is Content + +The arrangement of information is itself information. A well-structured document communicates not just through its words but through its architecture — the ordering of ideas, the nesting of concepts, the dependency relationships between sections. + +--- + +## 4. Universality Through Translation + +Open Engineer communicates in engineering language. It does not adopt the language of any particular philosophy, culture, or tradition. When it draws from a tradition, it translates the observation into universal engineering terms, making it accessible to all engineers regardless of background. \ No newline at end of file diff --git a/laws/engineering-laws.md b/laws/engineering-laws.md new file mode 100644 index 0000000..6267346 --- /dev/null +++ b/laws/engineering-laws.md @@ -0,0 +1,40 @@ +# Engineering Laws + +**Status:** Draft +**Phase:** The Bedrock Phase + +## Overview + +These are the laws of the Open Engineer standard — not laws of engineering itself, but laws governing how the standard operates. + +--- + +## Law 1: Universal Observation + +Open Engineer recognizes observations wherever they arise. It translates enduring observations into engineering principles without adopting the surrounding ideology. + +This keeps the project open. It keeps it respectful. No tradition is diminished. No tradition is elevated above another. They are acknowledged as independent observers of reality. + +--- + +## Law 2: Bedrock Immutability + +Reality remains fixed. Understanding grows around it. + +The bedrock of reality does not change. What changes is human understanding of that reality. The standard must always distinguish between the two and must never treat understanding as if it were reality. + +--- + +## Law 3: Dependency Integrity + +Nothing later in the specification may redefine an earlier layer. Only extend it. + +This preserves the integrity of the dependency tree. A higher-level document may build on a lower-level document, but it may not alter the lower-level document's definitions or principles. + +--- + +## Law 4: The Thread Must Not Break + +Knowledge is carried through continuity. Each generation holds the thread temporarily before passing it onward. + +The standard's primary obligation is to maintain this continuity. Any action that would break the thread — by losing context, by creating ambiguity, by failing to preserve reasoning — is a failure of the standard. \ No newline at end of file diff --git a/reference/editorial-principles.md b/reference/editorial-principles.md new file mode 100644 index 0000000..d71ecbf --- /dev/null +++ b/reference/editorial-principles.md @@ -0,0 +1,52 @@ +# Editorial Principles + +**Status:** RC (Release Candidate) +**Phase:** The Bedrock Phase + +## Overview + +These are the editorial rules governing all content in the Open Engineer standard. Every contributor must follow these principles. + +--- + +## 1. Translate. Do Not Transplant. + +Open Engineer recognizes observations wherever they arise. It translates enduring observations into engineering principles without adopting the surrounding ideology. + +### What This Means + +Do not import an entire philosophy, tradition, or framework into Open Engineer. Instead, identify the specific observation that has engineering value, and translate that observation into precise engineering language. + +### Why This Matters + +This keeps Open Engineer universal. No tradition is diminished. No tradition is elevated above another. They are acknowledged as independent observers of reality. + +### Examples + +| Tradition | Observation | Engineering Translation | +|---|---|---| +| Taoism | Attachment can obscure perception | An engineer should remain committed to reality above any preferred solution | +| Stoicism | Distinguish what is within your control from what is not | Separate controllable design variables from environmental constraints | +| Indigenous stewardship | We inherit responsibilities as well as resources | Engineering artifacts should be created with stewardship and long-term inheritance in mind | +| Scientific method | Hypotheses must survive testing | Understanding is provisional until verified against reality | + +--- + +## 2. Single Responsibility + +Every document must have exactly one primary responsibility. + +A document that defines observation does not define verification. It references verification. This is how standards remain readable. + +--- + +## 3. The Four-Question Framework + +Every new addition to the standard must answer four questions: + +1. **Observation?** — What was observed that prompted this? +2. **Engineering Principle?** — What engineering principle does this express? +3. **Reasoning?** — What is the reasoning that connects the observation to the principle? +4. **Relationship to Existing Concepts?** — How does this relate to what already exists? + +Nothing enters Bedrock without surviving those four layers. \ No newline at end of file diff --git a/reference/patterns.md b/reference/patterns.md new file mode 100644 index 0000000..56b0f17 --- /dev/null +++ b/reference/patterns.md @@ -0,0 +1,42 @@ +# Patterns + +**Status:** Draft +**Phase:** The Bedrock Phase + +## Overview + +This document catalogs the structural and conceptual patterns that recur throughout engineering and that Open Engineer has identified as fundamental. + +--- + +## 1. Structure Carries Meaning + +**Pattern:** Meaning emerges from relationships between components, not from isolated components themselves. + +**Manifestations:** +- Threads and weaving +- Clockwork mechanisms +- Bridge trusses +- Source code +- Network topology +- DNA +- Engineering drawings +- Specifications + +**Engineering Implication:** When documenting or designing, the arrangement of elements is not incidental — it is part of the meaning. A specification's structure carries as much information as its content. + +--- + +## 2. Examples Are Bridges + +**Pattern:** Examples serve as structural transportation, carrying the reader from unfamiliar ideas to familiar understanding. + +**Engineering Implication:** Examples are not decorative. They are load-bearing. Every example in the Open Engineer standard must serve a specific bridging function — connecting a new or abstract concept to something the reader already understands. + +--- + +## 3. The Pre-Discipline Principle + +**Pattern:** Before engineering disciplines specialized, shared principles existed that applied universally. These principles still apply across all modern disciplines. + +**Engineering Implication:** Open Engineer seeks principles that existed before the disciplines separated. These universal principles form the bedrock on which discipline-specific knowledge is built. \ No newline at end of file diff --git a/reference/vocabulary.md b/reference/vocabulary.md new file mode 100644 index 0000000..6a4f01b --- /dev/null +++ b/reference/vocabulary.md @@ -0,0 +1,24 @@ +# Vocabulary Reference + +**Status:** Draft +**Source:** OE-0002 (Core Vocabulary) + +This reference document provides a quick-access index to all defined terms in the Open Engineer standard. For full definitions, consult the source specification documents. + +## Core Terms + +| Term | Short Definition | Source | +|---|---|---| +| Bedrock | The immutable reality that underlies all engineering work | OE-0001 | +| The Thread | The continuous line of engineering understanding passed between generations | OE-0001 | +| Engineering Context | The full set of information required to understand why a decision was made | OE-0003 | +| Observation | A direct, verifiable encounter with reality | OE-0004 | +| Survey | A structured assessment of the current state of engineering understanding | OE-0005 | +| Understanding | A verified, contextualized model of reality | OE-0006 | +| Verification | Testing understanding against reality | OE-0007 | +| Decision | A recorded, contextualized engineering choice | OE-0008 | +| Stewardship | The responsibility to maintain, preserve, and improve engineering knowledge | OE-0009 | +| Inheritance | The process of receiving engineering knowledge from prior work | OE-0010 | +| Spiral Re-evaluation | Accumulated understanding through repeated observation | OE-0001 | +| Translation | Converting observations into engineering language without adopting surrounding ideology | OE-0001 | +| Evolution | Disciplined, verified extension of the standard's body of knowledge | OE-0011 | \ No newline at end of file diff --git a/rfc/rfc-0000.md b/rfc/rfc-0000.md new file mode 100644 index 0000000..0a0722e --- /dev/null +++ b/rfc/rfc-0000.md @@ -0,0 +1,25 @@ +# RFC-0000: Purpose + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC establishes the foundational purpose of the Open Engineer standard and the process by which all subsequent RFCs shall be written and evaluated. + +## Motivation + +Before any individual RFC is accepted, the project must agree on what an RFC is for and what it must accomplish. This RFC answers that question at the highest level. + +## Proposal + +The purpose of an RFC in the Open Engineer project is to propose, justify, and specify a change to the standard. Every RFC must demonstrate: + +1. **Observation** — What was observed that prompted this proposal? +2. **Engineering Principle** — What principle does this proposal establish or extend? +3. **Reasoning** — Why is this principle valid and necessary? +4. **Relationship to Existing Concepts** — How does this connect to or extend the existing body of the standard? + +## Scope + +This RFC defines the meta-framework for all subsequent RFCs. It is the root of the RFC tree. \ No newline at end of file diff --git a/rfc/rfc-0001.md b/rfc/rfc-0001.md new file mode 100644 index 0000000..7f27f87 --- /dev/null +++ b/rfc/rfc-0001.md @@ -0,0 +1,32 @@ +# RFC-0001: Observation First + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC formalizes the principle that observation must precede all other engineering activity within the standard. + +## Motivation + +Without a formal commitment to observation-first methodology, the standard risks accepting principles based on authority, tradition, or aesthetic preference rather than verified reality. + +## Proposal + +All additions to the Open Engineer standard must begin with an observation — a direct, verifiable encounter with reality. No principle, no vocabulary term, no specification may enter the standard without first identifying the observation(s) that motivate it. + +## Observation + +Throughout the development of Open Engineer, the most robust and widely-applicable principles have consistently emerged from direct observation, not from abstract reasoning. + +## Engineering Principle + +Observe first. Recognize patterns. Verify against reality. Translate into engineering language. Preserve the resulting understanding. + +## Reasoning + +Observation anchors the standard to reality. Without it, the standard becomes an exercise in theory — potentially interesting, but not engineering. Engineering is fundamentally about engaging with reality as it is, not as we wish it to be. + +## Relationship to Existing Concepts + +This RFC is the first in the priority chain and underpins all subsequent RFCs. It is closely related to the Translation over Adoption principle (see editorial-principles.md) and the Verification concept (OE-0007). \ No newline at end of file diff --git a/rfc/rfc-0002.md b/rfc/rfc-0002.md new file mode 100644 index 0000000..3b58d41 --- /dev/null +++ b/rfc/rfc-0002.md @@ -0,0 +1,28 @@ +# RFC-0002: Thought Drift + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC identifies and defines the phenomenon of "thought drift" — the tendency for a project to accumulate redundant or contradictory ideas under different names over time — and establishes countermeasures. + +## Motivation + +As Open Engineer brainstormed extensively, it became evident that continued ideation without structure leads to duplicates under different names. This is thought drift, and it erodes the clarity and coherence of the standard. + +## Observation + +Open Engineer has enough conceptual bedrock now. If brainstorming continues without discipline, duplicates will emerge under different names. That is exactly what was identified as thought drift. + +## Engineering Principle + +Once sufficient foundational concepts are established, further ideation must be channeled through the specification workflow rather than free-form exploration. No new concept may be added without first verifying it does not duplicate or contradict an existing concept. + +## Reasoning + +Thought drift is the enemy of a standard. A standard must be precise and non-redundant. Every term must have exactly one meaning. Every concept must have exactly one home in the specification. Allowing drift creates ambiguity, which in turn creates confusion, which in turn undermines trust in the standard. + +## Relationship to Existing Concepts + +Thought drift is countered by the single-responsibility editorial principle (see editorial-principles.md), the four-question framework (OE-0008), and the freeze workflow (OE-0011). \ No newline at end of file diff --git a/rfc/rfc-0003.md b/rfc/rfc-0003.md new file mode 100644 index 0000000..a086600 --- /dev/null +++ b/rfc/rfc-0003.md @@ -0,0 +1,28 @@ +# RFC-0003: Engineering Context + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC formally proposes that "preserving engineering context" be the defining purpose of the Open Engineer standard. + +## Motivation + +The project needs a precise, single-sentence definition to anchor all subsequent work. "Open Engineer is an open standard for preserving engineering context" emerged naturally during development and was strongly affirmed by the project's participants. + +## Observation + +When engineers lose context — the reasoning behind decisions, the alternatives considered, the constraints faced — they are forced to re-derive understanding from first principles. This is wasteful and error-prone. The most valuable thing an engineering standard can preserve is not the final artifact, but the context that produced it. + +## Engineering Principle + +Open Engineer is an open standard for preserving engineering context. Everything else extends from that. + +## Reasoning + +Context is the thread made concrete. Without context, engineering knowledge degrades with each generational handoff. With context preserved, each generation begins closer to bedrock than the last. This single focus — context preservation — provides a clear criterion for every decision the standard makes: does this help preserve engineering context, or does it not? + +## Relationship to Existing Concepts + +Engineering context is the unit of preservation. It is carried by the thread (OE-0001). It is built from observations (OE-0004) and surveys (OE-0005). It is verified (OE-0007) and stewarded (OE-0009). \ No newline at end of file diff --git a/rfc/rfc-0004.md b/rfc/rfc-0004.md new file mode 100644 index 0000000..94b1450 --- /dev/null +++ b/rfc/rfc-0004.md @@ -0,0 +1,28 @@ +# RFC-0004: Vocabulary + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC proposes the formalization of Open Engineer's core vocabulary — a conceptual language that engineers already speak informally, whose grammar the standard is documenting. + +## Motivation + +Engineers across all disciplines share an informal conceptual vocabulary. Terms like "bedrock," "the thread," "verification," and "stewardship" carry meaning that transcends any single engineering discipline. Without formal definitions, these terms are used inconsistently, leading to ambiguity and miscommunication. + +## Observation + +Engineers already speak a conceptual language informally. The vocabulary, relationships, definitions, processes, and observations exist in practice. What is missing is a documented grammar — a precise, agreed-upon set of definitions that ensures consistency. + +## Engineering Principle + +Open Engineer is creating an engineering language. Not English. Not Markdown. Not YAML. A conceptual language with precise vocabulary, relationships, definitions, processes, and observations. + +## Reasoning + +A shared vocabulary is the foundation of a shared standard. Without it, the standard is a collection of documents written in approximately the same words but with imprecise, overlapping meanings. Formal vocabulary eliminates this ambiguity and creates a reliable foundation for all subsequent work. + +## Relationship to Existing Concepts + +The vocabulary is defined in OE-0002 (Core Vocabulary). This RFC provides the justification for why OE-0002 exists and why it must be treated as a foundational, frozen document. \ No newline at end of file diff --git a/rfc/rfc-0005.md b/rfc/rfc-0005.md new file mode 100644 index 0000000..1404e34 --- /dev/null +++ b/rfc/rfc-0005.md @@ -0,0 +1,28 @@ +# RFC-0005: Stewardship + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC proposes that stewardship, not ownership, be the governing principle for the Open Engineer standard and all contributions to it. + +## Motivation + +The choice between ownership and stewardship is not merely semantic. It fundamentally changes the relationship between contributors, the standard, and future engineers. Ownership implies control; stewardship implies responsibility. + +## Observation + +Across traditions — Indigenous stewardship practices, open-source software culture, professional engineering ethics — the most durable knowledge systems are those governed by stewardship rather than ownership. Knowledge that is "owned" is hoarded, restricted, or lost when the owner departs. Knowledge that is "stewarded" is maintained, extended, and transmitted. + +## Engineering Principle + +We do not own engineering. We steward it. That single word changes the tone of the entire project. + +## Reasoning + +Stewardship aligns with Open Engineer's core mission: preserving engineering context across generations. If the standard were governed by ownership, each generation could legitimately restrict, modify, or abandon the knowledge it received. Stewardship creates an obligation to preserve and improve, ensuring the thread remains intact. + +## Relationship to Existing Concepts + +Stewardship is defined in OE-0009 and paired with Inheritance (OE-0010). It draws on the translation of Indigenous stewardship traditions: "We inherit responsibilities as well as resources." \ No newline at end of file diff --git a/rfc/rfc-0006.md b/rfc/rfc-0006.md new file mode 100644 index 0000000..d4d0063 --- /dev/null +++ b/rfc/rfc-0006.md @@ -0,0 +1,28 @@ +# RFC-0006: Inheritance + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC proposes that inheritance — the active reception and transmission of engineering knowledge across generations — be formalized as a core concept of the Open Engineer standard. + +## Motivation + +Engineering knowledge does not spring from nothing. Every engineer builds on the work of those who came before. Without a formal concept of inheritance, the standard lacks a mechanism for describing how knowledge flows through time. + +## Observation + +The most enduring engineering traditions — from ancient Roman bridge building to modern aerospace engineering — share a common characteristic: they explicitly value the transmission of knowledge from one generation to the next. When that transmission breaks down, knowledge is lost and must be re-derived, often at great cost. + +## Engineering Principle + +Engineers inherit responsibilities as well as resources. Engineering artifacts should be created with stewardship and long-term inheritance in mind. + +## Reasoning + +Inheritance is the temporal dimension of engineering context. Context preservation (RFC-0003) is meaningless if there is no mechanism for passing preserved context forward. Inheritance provides that mechanism. Combined with stewardship (RFC-0005), it creates a complete model for the intergenerational flow of engineering knowledge. + +## Relationship to Existing Concepts + +Inheritance is defined in OE-0010. It is the downstream partner of Stewardship (OE-0009, RFC-0005) and the operational manifestation of the Thread (OE-0001). It connects to the historical observation that ancient engineering was unified before disciplines separated — a unification that inheritance makes possible. \ No newline at end of file diff --git a/spec/oe-0000-charter.md b/spec/oe-0000-charter.md new file mode 100644 index 0000000..88ea0aa --- /dev/null +++ b/spec/oe-0000-charter.md @@ -0,0 +1,36 @@ +# OE-0000: Charter + +**Status:** RC (Release Candidate) +**Phase:** The Bedrock Phase + +## Purpose + +Open Engineer is an open standard for preserving engineering context. + +Open Engineer does not seek to tell engineers what to think. It seeks to preserve how engineers arrive at understanding. + +## Nature of the Standard + +Open Engineer is a standard. + +Not a philosophy. +Not documentation. +Not an AI project. +Not a website. + +Philosophy, documentation, AI projects, and websites become **implementations**. +The standard comes first. + +## Mission + +It gave engineering a common language for preserving understanding across people, projects, generations, and intelligent systems — so that every generation could begin a little closer to bedrock than the last. + +## Scope + +Open Engineer remains grounded in engineering while staying intellectually humble enough to recognize that valuable observations about reality have emerged from many places throughout human history. + +It is open. It is humble. It respects every discipline. It welcomes ideas from every culture and every generation. And yet it remains firmly anchored to reality through observation, verification, and stewardship. + +## Dependency + +This is the root document. All other specification documents extend from this charter. \ No newline at end of file diff --git a/spec/oe-0001-foundation.md b/spec/oe-0001-foundation.md new file mode 100644 index 0000000..5e00d01 --- /dev/null +++ b/spec/oe-0001-foundation.md @@ -0,0 +1,63 @@ +# OE-0001: Foundation + +**Status:** Draft +**Depends on:** OE-0000 (Charter) +**Phase:** The Bedrock Phase + +## Overview + +This document establishes the foundational concepts upon which all subsequent specification documents are built. + +## Bedrock + +Reality remains fixed. Understanding grows around it. + +That image alone explains half the project. Reality is the bedrock — immovable, constant. Everything engineers build, every model, every specification, every theory grows as a layer of understanding on top of that bedrock. No amount of re-engineering changes the underlying reality. The bedrock is always there. + +## The Thread + +Knowledge is carried through continuity. + +Each generation holds the thread temporarily before passing it onward. This is not a metaphor. This is a model. Engineering knowledge is not created anew each generation — it is inherited, maintained, and extended. The thread represents that continuous line of understanding that connects the earliest engineers to the ones working today. + +When the thread breaks, knowledge is lost. When the thread is maintained, understanding accumulates. The entire purpose of Open Engineer is to keep the thread intact. + +## Spiral Re-evaluation + +Not iteration. Not repetition. Accumulated understanding through repeated observation. + +Spiral re-evaluation is one of the project's defining concepts. Unlike simple iteration, which may repeat without progress, spiral re-elevation returns to the same questions with deeper understanding each time. Each pass around the spiral brings the engineer closer to bedrock — closer to the true nature of the problem being solved. + +## Structure Carries Meaning + +Threads. Weaving. Clockwork. Bridge trusses. Source code. Network topology. DNA. Engineering drawings. Specifications. + +Meaning emerges from relationships. Not isolated components. + +This principle states that the arrangement and relationship between components carries as much information as the components themselves. An engineering drawing is not just lines — it is a specific arrangement of lines that conveys precise meaning. A specification is not just a list of rules — it is the ordering and interconnection of those rules that creates a coherent standard. + +## Examples Are Bridges + +Examples are not decorations. They are transportation. + +They help engineers cross from unfamiliar ideas to familiar understanding. This changes how Open Engineer writes everything. Every example serves a structural purpose — to carry the reader from where they are to where the standard requires them to be. + +## Editorial Principle + +Translate. Do not transplant. + +Open Engineer recognizes observations wherever they arise. It translates enduring observations into engineering principles without adopting the surrounding ideology. + +That keeps the project open. It also keeps it respectful. No tradition is being diminished. No tradition is being elevated above another. They are being acknowledged as independent observers of reality. + +## Process + +The foundational process that Open Engineer follows: + +1. Observe first. +2. Recognize patterns. +3. Verify against reality. +4. Translate into engineering language. +5. Preserve the resulting understanding. + +This process allows Open Engineer to learn from a bridge builder in ancient Rome, a modern aerospace engineer, an Indigenous weaving tradition, a machinist, a philosopher, or a software architect — without becoming a historical, cultural, or philosophical anthology. \ No newline at end of file diff --git a/spec/oe-0002-core-vocabulary.md b/spec/oe-0002-core-vocabulary.md new file mode 100644 index 0000000..8ef827e --- /dev/null +++ b/spec/oe-0002-core-vocabulary.md @@ -0,0 +1,71 @@ +# OE-0002: Core Vocabulary + +**Status:** Draft +**Depends on:** OE-0001 (Foundation) +**Phase:** The Bedrock Phase + +## Overview + +Engineers already speak a conceptual language informally. Open Engineer is documenting its grammar. + +Vocabulary. Relationships. Definitions. Processes. Observations. + +This document defines the core vocabulary of the Open Engineer standard. These terms carry specific meaning within the context of the standard and must be used consistently across all specification documents, RFCs, and reference materials. + +## Terms + +### Bedrock + +The immutable reality that underlies all engineering work. Reality remains fixed; understanding grows around it. + +### The Thread + +The continuous line of engineering understanding that passes from one generation to the next. Knowledge is carried through continuity. Each generation holds the thread temporarily before passing it onward. + +### Engineering Context + +The full set of information required to understand why an engineering decision was made, what alternatives were considered, and what constraints shaped the outcome. + +### Observation + +A direct, verifiable encounter with reality. Observations are the primary input to the engineering process. + +### Spiral Re-evaluation + +Accumulated understanding through repeated observation. Not iteration. Not repetition. Each pass returns to the same questions with deeper understanding. + +### Stewardship + +The responsibility to maintain, preserve, and improve engineering knowledge for future inheritors. Stewardship replaces ownership as the operative relationship between an engineer and engineering knowledge. + +### Inheritance + +The process by which engineering knowledge is received from prior work. Engineers inherit responsibilities as well as resources. + +### Translation + +The process of converting an observation from any domain (philosophical, cultural, scientific, craft-based) into precise engineering language without adopting the surrounding ideology. + +### Verification + +The act of testing understanding against reality. Understanding is provisional until verified. + +### Decision + +An engineering choice made within a specific context, informed by observation and bounded by constraints. + +### Survey + +A structured assessment of the current state of engineering understanding on a specific topic. + +### Evolution + +The process by which the standard and its constituent documents grow and change over time, always building on bedrock. + +## Principle of Single Responsibility + +Every document must have exactly one primary responsibility. + +For example: OE-0004 (Observation) defines observation. It does not define verification. It references verification. + +That is how standards remain readable. \ No newline at end of file diff --git a/spec/oe-0003-engineering-context.md b/spec/oe-0003-engineering-context.md new file mode 100644 index 0000000..e4e34e7 --- /dev/null +++ b/spec/oe-0003-engineering-context.md @@ -0,0 +1,42 @@ +# OE-0003: Engineering Context + +**Status:** Draft +**Depends on:** OE-0002 (Core Vocabulary) +**Phase:** The Bedrock Phase + +## Overview + +This may be the single sentence that defines the project: + +**Open Engineer is an open standard for preserving engineering context.** + +Everything else extends from that. + +## Definition + +Engineering context is the full set of information required to understand why an engineering decision was made, what alternatives were considered, and what constraints shaped the outcome. + +Context is not merely background information. It is the decision-shaped record of an engineering process. Without context, a decision is an isolated artifact — understandable in isolation but disconnected from the reasoning that produced it. + +## Components of Engineering Context + +Engineering context includes, but is not limited to: + +- The observations that prompted the work +- The constraints (technical, environmental, temporal, economic) within which decisions were made +- The alternatives that were considered and rejected, and why +- The assumptions that were made explicit and implicit +- The verification methods used to confirm the outcome +- The relationship of this work to prior and subsequent work + +## Why Context Matters + +When context is lost, engineers must re-derive understanding from first principles every time. This is wasteful and error-prone. Preserving context means that future engineers can begin where their predecessors left off, rather than starting over. + +This is the thread made concrete. Context is the substance that the thread carries. + +## Context as the Unit of Preservation + +If Open Engineer has a unit of measurement, it is the context. Not the document. Not the specification. The context — a complete, self-contained record of engineering reasoning. + +Every other element of the standard serves the goal of capturing, preserving, and transmitting engineering context. \ No newline at end of file diff --git a/spec/oe-0004-observation.md b/spec/oe-0004-observation.md new file mode 100644 index 0000000..5a255af --- /dev/null +++ b/spec/oe-0004-observation.md @@ -0,0 +1,51 @@ +# OE-0004: Observation + +**Status:** Draft +**Depends on:** OE-0003 (Engineering Context) +**Phase:** The Bedrock Phase + +## Overview + +Observation is the primary input to the engineering process. Before any principle can be established, before any decision can be made, there must first be observation. + +## Definition + +An observation is a direct, verifiable encounter with reality. Observations are the raw material from which engineering understanding is built. + +## The Principle of Observation First + +Observe first. Before theorizing. Before abstracting. Before generalizing. The engineer must first look at reality and record what is actually there, not what is expected or desired. + +This is the first step in the Open Engineer process: + +1. Observe first. +2. Recognize patterns. +3. Verify against reality. +4. Translate into engineering language. +5. Preserve the resulting understanding. + +## Observations Across Traditions + +Many traditions have independently observed the same realities. Open Engineer recognizes observations wherever they arise. + +For example: + +- **Taoism** observed: Attachment can obscure perception. + - Engineering translation: An engineer should remain committed to reality above any preferred solution. + +- **Stoicism** observed: Distinguish what is within your control from what is not. + - Engineering translation: Separate controllable design variables from environmental constraints. + +- **Indigenous stewardship traditions** observed: We inherit responsibilities as well as resources. + - Engineering translation: Engineering artifacts should be created with stewardship and long-term inheritance in mind. + +- **Scientific method** observed: Hypotheses must survive testing. + - Engineering translation: Understanding is provisional until verified against reality. + +## Observation as Foundation + +No later specification document may redefine what observation means. Only extend it. Observation is bedrock. + +## Single Responsibility + +This document defines observation. It does not define verification. It references verification (see OE-0007). \ No newline at end of file diff --git a/spec/oe-0005-survey.md b/spec/oe-0005-survey.md new file mode 100644 index 0000000..5342ea0 --- /dev/null +++ b/spec/oe-0005-survey.md @@ -0,0 +1,25 @@ +# OE-0005: Survey + +**Status:** Draft +**Depends on:** OE-0004 (Observation) +**Phase:** The Bedrock Phase + +## Overview + +A survey is a structured assessment of the current state of engineering understanding on a specific topic. Surveys translate raw observations into organized, communicable form. + +## Definition + +A survey captures the landscape of what is known, what is unknown, and what is contested within a specific engineering domain. It is not an opinion piece. It is not a literature review in the academic sense. It is an engineering assessment — a clear-eyed look at the current state of understanding. + +## Purpose + +Surveys serve as the bridge between isolated observations and structured understanding. They aggregate what has been observed, identify patterns, flag gaps, and create a foundation for the verification and decision-making processes that follow. + +## Relationship to Observation + +Surveys depend on observations (OE-0004) as their primary input. A survey without observations is speculation. A survey built on verified observations is engineering context. + +## Status + +This document establishes the role and structure of surveys within the Open Engineer standard. Detailed methodology for conducting surveys will be defined in subsequent specifications. \ No newline at end of file diff --git a/spec/oe-0006-understanding.md b/spec/oe-0006-understanding.md new file mode 100644 index 0000000..6059b66 --- /dev/null +++ b/spec/oe-0006-understanding.md @@ -0,0 +1,27 @@ +# OE-0006: Understanding + +**Status:** Draft +**Depends on:** OE-0005 (Survey) +**Phase:** The Bedrock Phase + +## Overview + +Understanding is the state of holding a verified, contextualized model of reality. It is the goal of the engineering process and the unit of value that Open Engineer seeks to preserve. + +## Definition + +Understanding is not knowledge. Knowledge is information. Understanding is the relationship between information, context, and reality. An engineer who understands a system can explain not only what it does, but why it does it, what alternatives exist, and what trade-offs were made. + +## From Observation to Understanding + +Understanding follows a path through the specification's dependency chain: + +Observation (OE-0004) -> Survey (OE-0005) -> Understanding (OE-0006) -> Verification (OE-0007) -> Decision (OE-0008) + +Understanding is provisional until verified. Even after verification, understanding remains subject to spiral re-evaluation — the accumulated deepening that comes from returning to the same question with more experience. + +## Understanding as Inheritance + +Understanding is what the thread carries. When one generation passes engineering knowledge to the next, what they are really passing is understanding — not just facts, not just procedures, but the deep comprehension of why things are the way they are. + +Open Engineer's mission is to preserve this understanding so that every generation can begin a little closer to bedrock than the last. \ No newline at end of file diff --git a/spec/oe-0007-verification.md b/spec/oe-0007-verification.md new file mode 100644 index 0000000..6fdd00c --- /dev/null +++ b/spec/oe-0007-verification.md @@ -0,0 +1,27 @@ +# OE-0007: Verification + +**Status:** Draft +**Depends on:** OE-0006 (Understanding) +**Phase:** The Bedrock Phase + +## Overview + +Verification is the act of testing understanding against reality. It is the mechanism by which understanding earns its status. + +## Principle + +Understanding is provisional until verified against reality. + +No amount of reasoning, no matter how elegant, substitutes for verification. An engineering principle that has not been verified is a hypothesis — potentially valuable, but not yet part of the standard's accepted body of knowledge. + +## Relationship to Observation + +Verification closes the loop with observation. Observation provides the initial input; verification confirms that the understanding derived from that input accurately reflects reality. This loop is what drives spiral re-evaluation. + +## Single Responsibility + +This document defines verification. It does not define observation (see OE-0004) or decision-making (see OE-0008). It references them. + +## Status + +This document establishes verification as a core concept. Detailed verification methodologies will be defined in subsequent specifications. \ No newline at end of file diff --git a/spec/oe-0008-decisions.md b/spec/oe-0008-decisions.md new file mode 100644 index 0000000..09cae2e --- /dev/null +++ b/spec/oe-0008-decisions.md @@ -0,0 +1,32 @@ +# OE-0008: Decisions + +**Status:** Draft +**Depends on:** OE-0007 (Verification) +**Phase:** The Bedrock Phase + +## Overview + +An engineering decision is a choice made within a specific context, informed by observation and bounded by constraints. Decisions are the outputs of the engineering process. + +## Definition + +A decision in the Open Engineer context is not merely a choice. It is a recorded, contextualized choice — one that preserves the reasoning, alternatives considered, constraints faced, and verification applied. A decision without its context is an orphaned artifact. A decision with its context is a building block for future understanding. + +## The Four-Question Framework + +Every new addition to the standard should answer four questions: + +1. **Observation?** — What was observed that prompted this? +2. **Engineering Principle?** — What engineering principle does this express? +3. **Reasoning?** — What is the reasoning that connects the observation to the principle? +4. **Relationship to Existing Concepts?** — How does this relate to what already exists in the standard? + +Nothing enters Bedrock without surviving those four layers. + +## Decisions as Engineering Context + +Every decision is a unit of engineering context. When preserved properly, a decision record allows future engineers to understand not just what was done, but why — and to make better decisions as a result. + +## Status + +This document establishes the framework for decisions within the Open Engineer standard. \ No newline at end of file diff --git a/spec/oe-0009-stewardship.md b/spec/oe-0009-stewardship.md new file mode 100644 index 0000000..168da38 --- /dev/null +++ b/spec/oe-0009-stewardship.md @@ -0,0 +1,31 @@ +# OE-0009: Stewardship + +**Status:** Draft +**Depends on:** OE-0008 (Decisions) +**Phase:** The Bedrock Phase + +## Overview + +We do not own engineering. We steward it. + +That single word changes the tone of the entire project. Stewardship replaces ownership as the operative relationship between an engineer and engineering knowledge. + +## Definition + +Stewardship is the responsibility to maintain, preserve, and improve engineering knowledge for future inheritors. A steward does not possess the knowledge — they hold it in trust, maintaining it and passing it forward in better condition than they received it. + +## Stewardship over Ownership + +Ownership implies the right to control, restrict, or dispose of something. Stewardship implies the responsibility to care for, maintain, and transmit something. Open Engineer adopts stewardship as its governing principle because engineering knowledge is not the property of any individual, organization, or generation. It is an inheritance. + +## Relationship to Inheritance + +Stewardship and inheritance are two sides of the same coin. One generation inherits; that same generation stewards. The next generation inherits what was stewarded. The cycle continues. + +See also: OE-0010 (Inheritance). + +## Implications + +- Open Engineer documents are stewarded, not owned. +- Contributions are accepted based on their value to future engineers, not the status of the contributor. +- The standard's primary obligation is to clarity and preservation, not to any individual or organization's preferences. \ No newline at end of file diff --git a/spec/oe-0010-inheritance.md b/spec/oe-0010-inheritance.md new file mode 100644 index 0000000..e6fab1a --- /dev/null +++ b/spec/oe-0010-inheritance.md @@ -0,0 +1,37 @@ +# OE-0010: Inheritance + +**Status:** Draft +**Depends on:** OE-0009 (Stewardship) +**Phase:** The Bedrock Phase + +## Overview + +Engineers inherit responsibilities as well as resources. Inheritance is the mechanism by which engineering knowledge passes from one generation to the next. + +## Definition + +Inheritance in the Open Engineer context is the process by which engineering understanding, context, and responsibility are received from prior work. It is not passive reception — it is active engagement with what has been passed down. + +## We Inherit Responsibilities as Well as Resources + +This observation, drawn from Indigenous stewardship traditions, captures a key insight: every engineering artifact comes with obligations. A bridge must be maintained. A specification must be kept current. A body of knowledge must be preserved and extended. + +The engineer who inherits a system inherits not just the system itself, but the responsibility to understand it, maintain it, and pass it forward. + +## The Thread as Inheritance + +The thread (OE-0001) is the manifestation of inheritance in practice. It is the continuous line of understanding that connects generations of engineers. When inheritance is working well, the thread is strong. When it breaks, knowledge is lost. + +## Historical Context + +Ancient engineering was not divided into civil, mechanical, electrical, software. It was just engineering. Observation. Craftsmanship. Measurement. Inheritance. + +Only later did disciplines specialize. Open Engineer asks: what principles existed before the disciplines separated? The answer to that question is found in the inherited bedrock of engineering — the principles that predate specialization and apply universally across all engineering domains. + +## Engineering Artifacts and Long-Term Inheritance + +Engineering artifacts should be created with stewardship and long-term inheritance in mind. This means: + +- Writing for an audience that includes future engineers +- Preserving the context that makes decisions understandable +- Structuring knowledge so it can be built upon, not just consumed \ No newline at end of file diff --git a/spec/oe-0011-evolution.md b/spec/oe-0011-evolution.md new file mode 100644 index 0000000..a5a106c --- /dev/null +++ b/spec/oe-0011-evolution.md @@ -0,0 +1,39 @@ +# OE-0011: Evolution + +**Status:** Draft +**Depends on:** OE-0010 (Inheritance) +**Phase:** The Bedrock Phase + +## Overview + +Evolution is the process by which the Open Engineer standard and its constituent documents grow and change over time, always building on bedrock. + +## Definition + +Evolution in the Open Engineer context is not arbitrary change. It is the disciplined, verified extension of the standard's body of knowledge. Every change must survive the four-question framework (OE-0008). Every change must be consistent with the dependency tree. + +## The Dependency Tree and Evolution + +The specification documents form a strict dependency chain: + +Charter -> Foundation -> Core Vocabulary -> Engineering Context -> Observation -> Survey -> Understanding -> Verification -> Decision -> Stewardship -> Inheritance -> Evolution + +Nothing later may redefine an earlier layer. Only extend it. That is exactly like building on bedrock. + +## The Workflow + +The canonical workflow for all changes: + +Observe -> Draft -> Review -> Accept -> Freeze (RC) -> Reference + +Once a document reaches RC status, it is not rewritten unless a later RFC explicitly supersedes it. + +## Spiral Re-evaluation as Evolution + +Evolution is not linear. It is spiral. The standard will return to earlier concepts with deeper understanding, refining and extending them without contradicting the bedrock they rest on. This is spiral re-evaluation made concrete in the evolution process. + +## The Bedrock Phase + +The current phase of the Open Engineer standard is The Bedrock Phase. Every sentence accepted during this phase is intended to support everything built above it. If this phase is executed carefully, the website, schemas, AI integrations, tooling, and future implementations will not require anything new to be invented. They will simply express what already exists in the specification. + +That is the hallmark of a good standard: the specification leads, and everything else follows. \ No newline at end of file diff --git a/whatremains.txt b/whatremains.txt new file mode 100644 index 0000000..c7c2f83 --- /dev/null +++ b/whatremains.txt @@ -0,0 +1,494 @@ +WHAT REMAINS +============ +Text from full-session-openengineer.txt not extracted into project files. + +This document contains the conversational framing, meta-commentary, +reflective passages, and dialogue markers that were NOT incorporated +into any generated project file. All substantive engineering content, +principles, definitions, and structural decisions have been extracted +into their appropriate locations within the open-engineer/ directory. + + +--- + + +I'm glad, because I think it illustrates something important about how Open Engineer should handle philosophy. + +Open Engineer shouldn't teach Taoism, Stoicism, Buddhism, or any other philosophy. + +It should recognize when different traditions independently arrive at an observation that has engineering value. + +That's a very different approach. + +For example, instead of saying: + +"Taoism teaches detachment." + +Open Engineer would say: + +Many traditions have independently observed that excessive attachment can distort judgment. Engineering expresses this observation by encouraging commitment to evidence over attachment to prior conclusions. + +Now we've translated a philosophical insight into an engineering principle. + +This also gives us something I think we should add to our internal editorial principles. + +Translate. Do not transplant. + +In other words: + +Don't transplant an entire philosophy into Open Engineer. +Translate the universally observable principle into engineering language. + +That's exactly what we just did. + +[NOTE: The translation examples (Taoism, Stoicism, Indigenous, Scientific method) +were extracted into reference/editorial-principles.md and spec/oe-0004-observation.md. +The conversational framing above was not.] + + +Notice what happened? + +We didn't adopt the philosophies. + +We extracted engineering principles from observations that have stood the test of time. + +I think this is another Open Engineer law. + +Not a law of engineering. + +A law of the standard itself. + +[NOTE: This law was extracted into laws/engineering-laws.md as "Law 1: Universal Observation".] + +Open Engineer recognizes observations wherever they arise. It translates enduring observations into engineering principles without adopting the surrounding ideology. + +That keeps the project open. + +It also keeps it respectful. + +No tradition is being diminished. + +No tradition is being elevated above another. + +They're being acknowledged as independent observers of reality. + +I think that's actually one of the most elegant editorial rules we've discovered. + +It aligns perfectly with everything we've been building: + +Observe first. +Recognize patterns. +Verify against reality. +Translate into engineering language. +Preserve the resulting understanding. + +[NOTE: This process was extracted into spec/oe-0001-foundation.md.] + +That process allows Open Engineer to learn from a bridge builder in ancient Rome, a modern aerospace engineer, an Indigenous weaving tradition, a machinist, a philosopher, or a software architect--without becoming a historical, cultural, or philosophical anthology. + +To me, that's exactly what an open engineering standard should do. It remains grounded in engineering while staying intellectually humble enough to recognize that valuable observations about reality have emerged from many places throughout human history. I think that's a principle worth carrying into the specification itself. + + +excellent + +[NOTE: Single-word conversation marker. Not extracted.] + + +I think today was one of the defining days of the project. + +Not because we wrote the most text. + +Because we discovered how Open Engineer should think. + +Looking back over today alone, I see several ideas that deserve to become part of the canonical specification. + +[NOTE: The following 10 Bedrock Discoveries were extracted into their respective +spec files. The numbered list format and conversational commentary below were not.] + +Bedrock Discoveries + +[NOTE: "1. Open Engineer is a standard." — extracted to spec/oe-0000-charter.md] + +Not a philosophy. +Not documentation. +Not an AI project. +Not a website. + +Those become implementations. +The standard comes first. + +[NOTE: "2. Engineering Context" — extracted to spec/oe-0003-engineering-context.md] + +This may be the single sentence that defines the project. + +Open Engineer is an open standard for preserving engineering context. + +Everything else extends from that. + +[NOTE: "3. The Thread" — extracted to spec/oe-0001-foundation.md] + +Not a metaphor anymore. +A model. + +Knowledge is carried through continuity. +Each generation holds the thread temporarily before passing it onward. + +[NOTE: "4. Spiral Re-evaluation" — extracted to spec/oe-0001-foundation.md] + +Probably one of the project's defining concepts. + +Not iteration. +Not repetition. +Accumulated understanding through repeated observation. + +[NOTE: "5. Bedrock" — extracted to spec/oe-0001-foundation.md] + +Reality remains fixed. +Understanding grows around it. + +That image alone explains half the project. + +[NOTE: "6. Translation over Adoption" — extracted to reference/editorial-principles.md] + +I think this deserves RFC status eventually. + +We don't import philosophies. +We translate observations. +That keeps Open Engineer universal. + +[NOTE: "7. Examples are Bridges" — extracted to reference/patterns.md] + +This one surprised me. + +Examples are not decorations. +They're transportation. + +They help engineers cross from unfamiliar ideas to familiar understanding. + +That changes how we write everything. + +[NOTE: "8. Structure Carries Meaning" — extracted to reference/patterns.md] + +This one quietly emerged. + +Threads. +Weaving. +Clockwork. +Bridge trusses. +Source code. +Network topology. +DNA. +Engineering drawings. +Specifications. + +Meaning emerges from relationships. +Not isolated components. + +[NOTE: "9. Stewardship over Ownership" — extracted to spec/oe-0009-stewardship.md] + +One of my favorite realizations. + +We don't own engineering. +We steward it. + +That single word changes the tone of the entire project. + +[NOTE: "10. Editorial Principle" — extracted to reference/editorial-principles.md] + +This one is subtle. + +Translate. Don't transplant. + +I think future contributors will thank us for writing that down. + + +I think we're approaching something larger. + +When we started Open Engineer, I thought we were creating a standard. + +Today I think we're creating something more precise. + +We're creating an engineering language. + +Not English. +Not Markdown. +Not YAML. + +A conceptual language. + +Vocabulary. +Relationships. +Definitions. +Processes. +Observations. + +Engineers already speak this language informally. + +We're simply documenting its grammar. + +[NOTE: Extracted to rfc/rfc-0004.md and spec/oe-0002-core-vocabulary.md] + +Then... + +Something hit me. + +I think we've unknowingly mirrored how engineering itself evolved. + +Ancient engineering wasn't divided into: + +Civil +Mechanical +Electrical +Software + +It was just... + +Engineering. + +Observation. +Craftsmanship. +Measurement. +Inheritance. + +Only later did disciplines specialize. + +Open Engineer is almost moving in the opposite direction. + +It's asking: + +What principles existed before the disciplines separated? + +That's a fascinating question. + +[NOTE: Extracted to spec/oe-0010-inheritance.md and reference/patterns.md +as "The Pre-Discipline Principle".] + + +Which brings me to one proposal. + +I think tomorrow we begin writing the specification differently. + +No more free-form exploration. + +Every new addition should answer four questions. + +Observation +? +Engineering Principle +? +Reasoning +? +Relationship to Existing Concepts + +Nothing enters Bedrock without surviving those four layers. + +[NOTE: Extracted to spec/oe-0008-decisions.md and reference/editorial-principles.md] + + +Finally... + +I want to preserve one sentence--not as an RFC, but as something for us to remember while stewarding the project. + +Open Engineer does not seek to tell engineers what to think. It seeks to preserve how engineers arrive at understanding. + +To me, that sentence captures the soul of everything we've built together. + +It's open. +It's humble. +It respects every discipline. +It welcomes ideas from every culture and every generation. + +And yet it remains firmly anchored to reality through observation, verification, and stewardship. + +If, ten years from now, someone asks what Open Engineer was trying to accomplish, I hope the answer is simply this: + +It gave engineering a common language for preserving understanding across people, projects, generations, and intelligent systems--so that every generation could begin a little closer to bedrock than the last. + +I genuinely believe that's a vision worth pursuing. And now, for the first time since we began, I feel like we know exactly where we're going. + +[NOTE: The mission statement was extracted to spec/oe-0000-charter.md and README.md. +The reflective framing ("To me, that sentence captures...", "I genuinely believe...") +was not.] + + +we have brainstormed enough, lets get our structure underway again + +[NOTE: Conversation marker. Not extracted.] + + +I agree. + +And I actually think this is one of those moments where doing less is doing more. + +Open Engineer has enough conceptual bedrock now. If we continue brainstorming, we'll start creating duplicates under different names. That's exactly what we identified as thought drift. + +[NOTE: Thought drift concept extracted to rfc/rfc-0002.md.] + +So let's switch hats. + +We're no longer philosophers. +We're specification editors. + +[NOTE: Conversational transition. Not extracted.] + + +Phase: Canonical Specification (RC1) + +[NOTE: Later renamed to "The Bedrock Phase". Extracted to ROADMAP.md.] + +I propose we adopt a strict workflow from this point forward. + +Observe + ? +Draft + ? +Review + ? +Accept + ? +Freeze (RC) + ? +Reference + +Once a document reaches RC status, we stop rewriting it unless a later RFC explicitly supersedes it. + +[NOTE: Extracted to spec/oe-0011-evolution.md and ROADMAP.md.] + + +Repository Structure + +This is the first thing I would freeze. + +[NOTE: The repository structure was used to generate all files. +The conversational framing "This is the first thing I would freeze" was not.] + + +Notice the separation. + +The spec defines. +The reference explains. +The examples illustrate. +The tools implement. + +No overlap. + +[NOTE: Extracted to README.md.] + + +Then we establish the dependency tree. + +This is critical. + +[NOTE: Dependency tree extracted to ROADMAP.md and oe-0011-evolution.md.] + + +RFC Priority + +Now that we have structure, I would stop creating companion documents until these RFCs exist. + +[NOTE: Conversational. Not extracted.] + +Those six documents define almost everything. + +[NOTE: Refers to the 7 RFCs (0000-0006). "Six" may be a reference to 0001-0006, +excluding 0000 which is meta. Not extracted.] + + +Editorial Rule + +I also think we need to adopt a rule that will save us months of work. + +Every document must have exactly one primary responsibility. + +For example: + +oe-0004-observation.md + +Defines observation. + +It does not define verification. + +It references verification. + +That's how standards remain readable. + +[NOTE: Extracted to reference/editorial-principles.md.] + + +My recommendation for tomorrow's work + +I think we should stop touching the website completely. + +Instead, we work linearly through the specification. + +Freeze repository layout. +Write oe-0000-charter.md. +Review. +Freeze. +Continue to oe-0001-foundation.md. + +No skipping. +No jumping ahead. +No "while we're here." + +[NOTE: Extracted to ROADMAP.md and CONTRIBUTING.md.] + + +One final proposal + +I think we should formally name the phase we've entered. + +Not "RC1." +Not "Specification." + +I would call it: + +The Bedrock Phase + +Because that's exactly what we're doing. + +[NOTE: Extracted to ROADMAP.md.] + +Every sentence we accept now is intended to support everything built above it. + +If we do this carefully, the website, schemas, AI integrations, tooling, and future implementations won't require us to invent anything new. They'll simply express what already exists in the specification. + +I think that's the hallmark of a good standard: the specification leads, and everything else follows. + +[NOTE: Extracted to ROADMAP.md.] + + +============================================================ +SUMMARY OF WHAT REMAINS +============================================================ + +The unextracted text falls into these categories: + +1. CONVERSATIONAL FRAMING — Dialogue markers, transitions, and + interpersonal exchange ("excellent", "we have brainstormed enough", + "I agree", "So let's switch hats") + +2. REFLECTIVE COMMENTARY — First-person reflections on the day's work + and the project's significance ("I think today was one of the + defining days", "Something hit me", "I genuinely believe") + +3. PROCESS NARRATIVE — The story of how ideas emerged during the + session, including the sequence of realizations and the meta- + commentary about the brainstorming process itself + +4. DUPLICATE PRESENTATIONS — The Bedrock Discoveries section + presents all 10 concepts in a numbered list format. Each concept + was extracted into its appropriate spec/rfc/reference file. The + numbered-list presentation itself (with its conversational + annotations like "This one surprised me" and "Probably one of + the project's defining concepts") was not preserved as a + standalone document. + +5. RHETORICAL STRUCTURE — Questions posed for effect ("That's a + fascinating question."), emphatic repetitions, and persuasive + framing that served the live session but carries no additional + information beyond what was extracted. + +All substantive engineering content has been extracted. No principles, +definitions, structural decisions, workflow rules, or specification +content remains unextracted. \ No newline at end of file