From 9165b59171a0e6c93b8785b3280ce7ade66fae60 Mon Sep 17 00:00:00 2001 From: Jeremy Anderson Date: Thu, 2 Jul 2026 18:40:20 -0400 Subject: [PATCH] second draft of openengineer fixed --- CHARTER.md | 23 ++++++ CONTRIBUTING.md | 35 ++++++++ LICENSE | 21 +++++ README.md | 31 +++++++ ROADMAP.md | 69 ++++++++++++++++ examples/antikythera.md | 26 ++++++ examples/biomedical-implant-context.md | 34 ++++++++ examples/bridge-survey.md | 31 +++++++ examples/clockwork.md | 24 ++++++ examples/software-auth-context.md | 34 ++++++++ examples/weaving.md | 26 ++++++ laws/communication-principles.md | 27 ++++++ laws/engineering-laws.md | 72 ++++++++++++++++ reference/editorial-principles.md | 97 ++++++++++++++++++++++ reference/patterns.md | 41 +++++++++ reference/vocabulary.md | 28 +++++++ rfc/rfc-0000.md | 20 +++++ rfc/rfc-0001.md | 28 +++++++ rfc/rfc-0002.md | 28 +++++++ rfc/rfc-0003.md | 28 +++++++ rfc/rfc-0004.md | 28 +++++++ rfc/rfc-0005.md | 28 +++++++ rfc/rfc-0006.md | 28 +++++++ spec/oe-0000-charter.md | 92 +++++++++++++++++++++ spec/oe-0001-foundation.md | 79 ++++++++++++++++++ spec/oe-0002-core-vocabulary.md | 78 ++++++++++++++++++ spec/oe-0003-engineering-context.md | 69 ++++++++++++++++ spec/oe-0004-observation.md | 62 ++++++++++++++ spec/oe-0005-survey.md | 40 +++++++++ spec/oe-0006-understanding.md | 40 +++++++++ spec/oe-0007-verification.md | 40 +++++++++ spec/oe-0008-decisions.md | 34 ++++++++ spec/oe-0009-stewardship.md | 41 +++++++++ spec/oe-0010-inheritance.md | 38 +++++++++ spec/oe-0011-amendment.md | 61 ++++++++++++++ whatremains.txt | 110 +++++++++++++++++++++++++ 36 files changed, 1591 insertions(+) create mode 100755 CHARTER.md create mode 100755 CONTRIBUTING.md create mode 100755 LICENSE create mode 100755 README.md create mode 100755 ROADMAP.md create mode 100755 examples/antikythera.md create mode 100644 examples/biomedical-implant-context.md create mode 100755 examples/bridge-survey.md create mode 100755 examples/clockwork.md create mode 100644 examples/software-auth-context.md create mode 100755 examples/weaving.md create mode 100755 laws/communication-principles.md create mode 100755 laws/engineering-laws.md create mode 100755 reference/editorial-principles.md create mode 100755 reference/patterns.md create mode 100755 reference/vocabulary.md create mode 100755 rfc/rfc-0000.md create mode 100755 rfc/rfc-0001.md create mode 100755 rfc/rfc-0002.md create mode 100755 rfc/rfc-0003.md create mode 100755 rfc/rfc-0004.md create mode 100755 rfc/rfc-0005.md create mode 100755 rfc/rfc-0006.md create mode 100755 spec/oe-0000-charter.md create mode 100755 spec/oe-0001-foundation.md create mode 100755 spec/oe-0002-core-vocabulary.md create mode 100755 spec/oe-0003-engineering-context.md create mode 100755 spec/oe-0004-observation.md create mode 100755 spec/oe-0005-survey.md create mode 100755 spec/oe-0006-understanding.md create mode 100755 spec/oe-0007-verification.md create mode 100755 spec/oe-0008-decisions.md create mode 100755 spec/oe-0009-stewardship.md create mode 100755 spec/oe-0010-inheritance.md create mode 100644 spec/oe-0011-amendment.md create mode 100755 whatremains.txt diff --git a/CHARTER.md b/CHARTER.md new file mode 100755 index 0000000..b91fc3c --- /dev/null +++ b/CHARTER.md @@ -0,0 +1,23 @@ +# Open Engineer Charter + +**The authoritative charter is `spec/oe-0000-charter.md`.** + +This file provides a brief summary for repository navigation. + +## Purpose + +Open Engineer is an open standard for preserving engineering context. + +## Quick Navigation + +| Resource | Location | Purpose | +|---|---|---| +| Charter | `spec/oe-0000-charter.md` | Purpose, scope, governance, status lifecycle, versioning | +| Specification | `spec/` | OE-0000 through OE-0011 | +| Editorial Rules | `reference/editorial-principles.md` | **Sole authoritative source** for all editorial principles | +| Engineering Laws | `laws/engineering-laws.md` | Binding constraints on all content | +| Communication Principles | `laws/communication-principles.md` | Communication style (subordinate to editorial principles and laws) | +| Vocabulary Index | `reference/vocabulary.md` | Quick-access term index | +| Patterns | `reference/patterns.md` | Structural and conceptual patterns | +| Roadmap | `ROADMAP.md` | Current phase and planned work | +| Contributing | `CONTRIBUTING.md` | How to contribute | \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100755 index 0000000..bb4848b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# Contributing to Open Engineer + +## Current Phase: The Bedrock Phase + +Contributions follow a strict workflow. All editorial rules are defined in `reference/editorial-principles.md`. This document does not duplicate them. + +## How to Contribute + +### 1. Read the Dependency Tree + +The specification is linear (OE-0000 through OE-0011). Do not skip ahead. Do not jump between documents without understanding the dependency chain. See `ROADMAP.md` for the full tree. + +### 2. Follow the Editorial Gate + +All proposed additions must pass the four-question framework and, for refinements, the five-question RC2 gate. See `reference/editorial-principles.md` for the complete rules. + +### 3. Apply the Enduring Concept Test + +Every new term must pass the test defined in `reference/editorial-principles.md` (Section 5) and Law 5 (`laws/engineering-laws.md`). + +### 4. Check for Duplication + +Before proposing anything, verify it does not already exist under a different name in OE-0002 (Core Vocabulary) or elsewhere in the specification. + +## Workflow + +Observe -> Draft -> Review -> Accept -> Freeze (RC) -> Reference + +See OE-0000 for the document status lifecycle and OE-0011 for the full change workflow. + +## Key Constraints + +- Do not redefine earlier layers in the dependency tree — only extend them. +- Do not duplicate editorial rules — reference `reference/editorial-principles.md`. +- Do not introduce technology-anchored terms — use enduring concepts (Law 5). \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100755 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 100755 index 0000000..7da099e --- /dev/null +++ b/README.md @@ -0,0 +1,31 @@ +# 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? + +An open standard that applies to any discipline in which practitioners make decisions under constraints, observe outcomes, and transmit results to subsequent practitioners. + +## Repository Structure + +| Directory | Responsibility | +|---|---| +| `spec/` | Defines the standard (OE-0000 through OE-0011) | +| `reference/` | Explains and indexes (vocabulary, patterns, editorial principles) | +| `examples/` | Illustrates core concepts through worked examples | +| `laws/` | Binding constraints on all content | +| `rfc/` | Proposals for changes to the standard | + +The spec defines. The reference explains. The examples illustrate. The laws constrain. No overlap. + +## Entry Points + +- **New to the project?** Start with `spec/oe-0000-charter.md` +- **Contributing?** Read `CONTRIBUTING.md`, then `reference/editorial-principles.md` +- **Looking up a term?** Check `reference/vocabulary.md` + +## License + +See `LICENSE`. \ No newline at end of file diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100755 index 0000000..12e686d --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,69 @@ +# Roadmap + +## Current Phase: The Bedrock Phase + +Every sentence accepted during this phase is intended to support everything built above it. The specification leads. Everything else follows. + +--- + +## RC2 Objective + +Reduce ambiguity without reducing meaning. + +RC2 is compression, not expansion. Every refinement should either eliminate ambiguity or strengthen traceability. + +--- + +## RC2 Exit Criteria + +RC2 is complete when: + +1. Every top-level directory has exactly one responsibility. +2. Every canonical term has one definition (in OE-0002). +3. Every definition survives the Enduring Concept test (Law 5). +4. Every example passes the Self-Fading Example principle. +5. Every implementation derives from a specification rather than inventing one. +6. An independent reviewer can reconstruct the architecture without speaking to the project authors. + +--- + +## 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) + -> Amendment (OE-0011) +``` + +Nothing later may redefine an earlier layer. Only extend it. + +## Change Workflow + +``` +Observe -> Draft -> Review -> Accept -> Freeze (RC) -> Reference +``` + +Document status lifecycle: Draft -> Proposed -> RC -> Accepted -> Deprecated (defined in OE-0000). + +--- + +## Future Phases + +- **Implementation Phase** — Interchange formats, context record tooling, presentation layers +- **Integration Phase** — Context record systems for specific engineering domains +- **Community Phase** — Open contributions, discipline-specific extensions + +--- + +## Constitutional Governance + +OE-0011 (Amendment) defines a two-tier amendment process. Technical content follows the standard change workflow. Governance content (Laws, Editorial Principles, Status Lifecycle) requires additional constraints including independent review. See OE-0011 for details. \ No newline at end of file diff --git a/examples/antikythera.md b/examples/antikythera.md new file mode 100755 index 0000000..7cf45bb --- /dev/null +++ b/examples/antikythera.md @@ -0,0 +1,26 @@ +# Example: Antikythera Mechanism + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Thread integrity failure (OE-0001). The cost of lost context (OE-0003). + +## The Observation + +The Antikythera mechanism, built circa 100-200 BCE, contained over 30 gears and could predict astronomical positions and eclipses. The engineering knowledge required to design and build it was lost. Comparable complexity in geared mechanisms did not reappear for over a millennium. + +**Sources:** Freeth, T. et al. (2021). "A Model of the Cosmos in the ancient Greek Antikythera Mechanism." *Scientific Reports*, 11, 5823. de Solla Price, D. (1974). "Gears from the Greeks: The Antikythera Mechanism — A Calendar Computer from ca. 80 B.C." *Transactions of the American Philosophical Society*, 64(7). + +## Engineering Translation + +When the thread breaks — when the reasoning, constraints, and verification behind an engineering artifact are no longer accessible — the accumulated understanding is lost. Recovery requires re-derivation from first principles, which is costly, slow, and may produce different (not necessarily better) results. + +## Context Record Gap + +The Antikythera mechanism is a case where no context record was preserved (or none has survived). What remains is the artifact itself, not the reasoning that produced it. Modern analysis can reverse-engineer function, but the engineering context — why these specific gear ratios, why this arrangement, what alternatives were considered — is largely irrecoverable. + +## Self-Fading Assessment + +This example transports the reader from the abstract concept of "thread integrity" to a concrete historical case where thread failure had measurable consequences. Once the reader understands that lost context equals lost engineering time, the example has served its purpose. \ No newline at end of file diff --git a/examples/biomedical-implant-context.md b/examples/biomedical-implant-context.md new file mode 100644 index 0000000..8619e35 --- /dev/null +++ b/examples/biomedical-implant-context.md @@ -0,0 +1,34 @@ +# Example: Hip Implant Material Selection (Biomedical Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) in biomedical engineering, including cross-discipline constraints and regulatory considerations. + +## The Observation + +A patient cohort (n=340) receiving cobalt-chrome (CoCr) hip implant bearings showed serum cobalt ion elevation above 1.0 ppb in 8.2% of patients at 5-year follow-up, with 2.1% requiring revision surgery for adverse local tissue reaction (ALTR). + +## Engineering Translation + +Material selection in biomedical engineering involves constraints from multiple domains: materials science, biology, regulatory requirements, and patient outcomes. The reasoning behind a material choice must be preserved because a future engineer may need to evaluate whether the material is still appropriate as new evidence emerges or as the patient population changes. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Select ceramic-on-ceramic (CoC) bearing surfaces for total hip arthroplasty in patients under 65 with expected activity level above the 75th percentile for age group | +| **Observation** | (1) Serum metal ion data from CoCr revision study (internal, 2023, n=340). (2) Published registry data: Australian NJRR 2022 report shows 15-year implant survival of 94.2% for CoC vs. 91.7% for CoCr in patients under 65. (3) Corroborated observation: multiple independent biomechanical studies confirm that ceramic wear debris generates a less severe inflammatory response than metallic wear debris. | +| **Alternatives** | (A) CoCr-on-CoCr — rejected for high-activity patients due to metal ion elevation risk (Observation 1). (B) Ceramic-on-polyethylene (CoP) — rejected for patients under 65 with high activity due to polyethylene wear rates at 15+ year horizon. (C) Oxinium-on-polyethylene — considered but insufficient long-term registry data for patients under 65 at current follow-up horizon. | +| **Constraints** | FDA 510(k) clearance required for bearing combination. Must demonstrate 15-year survivorship probability above 90% per registry criteria. Must not generate wear debris exceeding osteolytic threshold. Patient age and activity level restrict material options differently than geriatric population. | +| **Reasoning** | CoC provides the lowest wear rate of available bearing options (approximately 0.001 mm/year vs. 0.05 mm/year for CoP). For patients under 65 with high activity, the cumulative wear volume over a 20+ year implant life makes wear rate the dominant failure mode. The ceramic fracture risk (approximately 0.02% at 10 years with modern delta-ceramic) is acceptable given the patient population's life expectancy. The trade-off is acceptable: higher ceramic fracture risk at implantation, lower long-term wear-related revision risk. | +| **Verification** | (1) Finite element analysis of contact stress distribution confirmed peak Hertzian stress below ceramic fracture toughness threshold. (2) Simulator testing (ISO 14242-1) at 10 million cycles showed volumetric wear of 0.8 mm3 (below osteolytic threshold of 50 mm3). (3) Registry correlation: 5-year clinical data from three independent registries (AU, UK, NZ) confirm survival probability consistent with lab predictions. | +| **Lineage** | Builds on material selection framework established in CR-BIO-2019-003 (geriatric population bearing selection). Extends that framework to high-activity younger patients using updated registry data. | +| **Assumptions** | Ceramic fracture toughness will not degrade below threshold in vivo over 20+ year horizon. Patient activity level remains above 75th percentile. No novel ceramic manufacturing defects at scale. Regulatory pathway for CoC in this specific patient subpopulation remains available. | +| **Open Questions** | At what activity level does CoC's advantage over CoP become statistically insignificant? Should patients with known ceramic sensitivity be excluded from CoC consideration? | + +## Self-Fading Assessment + +This example transports the reader from the abstract context record structure to a concrete biomedical engineering decision involving multi-domain constraints. Once the reader understands how the same eight-field structure captures reasoning in a fundamentally different engineering discipline, the example has served its purpose. \ No newline at end of file diff --git a/examples/bridge-survey.md b/examples/bridge-survey.md new file mode 100755 index 0000000..0aa1d69 --- /dev/null +++ b/examples/bridge-survey.md @@ -0,0 +1,31 @@ +# Example: Bridge Engineering + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Engineering context preservation (OE-0003), the context record structure, and verification. + +## The Observation + +A bridge designed without a preserved context record — one that records only the final design but not the reasoning, alternatives, constraints, and verification — creates risk for future engineers who must maintain, modify, or load-rate the bridge. + +## Context Record Applied + +A well-preserved bridge engineering context record would contain: + +| Field | Example Content | +|---|---| +| **Decision** | Use a truss design with a 40m span | +| **Observation** | Site survey showed 40m crossing required; bedrock at 12m depth | +| **Alternatives** | Cable-stayed (rejected: higher maintenance cost), arch (rejected: insufficient abutment capacity) | +| **Constraints** | Maximum load 40 tonnes; environmental: tidal zone; economic: prefabrication required | +| **Reasoning** | Truss allows prefabrication, meets load requirements, and can be erected in tidal window | +| **Verification** | Load testing to 1.5x design load; finite element analysis corroborated by physical test | +| **Lineage** | Builds on standard truss design from [prior project reference] | +| **Assumptions** | Steel grade S355 available; corrosion protection maintains for 50-year design life | + +## Self-Fading Assessment + +This example transports the reader from the abstract context record structure (OE-0003) to a concrete instance. Once the reader understands how each field maps to a real engineering decision, the example has served its purpose. \ No newline at end of file diff --git a/examples/clockwork.md b/examples/clockwork.md new file mode 100755 index 0000000..15924cf --- /dev/null +++ b/examples/clockwork.md @@ -0,0 +1,24 @@ +# Example: Clockwork + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Structure carries meaning (OE-0001). Observation-verification loop (OE-0007). + +## The Observation + +A clock is not a collection of gears. It is a specific arrangement of gears that produces the measurement of time. Each component has no inherent relationship to time — the relationship emerges only through precise arrangement. + +## Engineering Translation + +System behavior is a property of arrangement, not of components. This principle is observable across engineering: the same transistors can produce a amplifier or a logic gate depending on arrangement; the same structural members can produce a frame or a truss depending on connection patterns. + +## The Verification Loop + +Clockwork also demonstrates the verification loop: a clock's design is a model (understanding). The test is whether it keeps accurate time (verification against reality). If it does not, the engineer returns to observation (where is the error?) and refines the model (spiral re-evaluation). + +## Self-Fading Assessment + +This example transports the reader from the abstract principle of emergent behavior to a concrete, familiar mechanism. Once the reader grasps that arrangement creates function, the example has served its purpose. \ No newline at end of file diff --git a/examples/software-auth-context.md b/examples/software-auth-context.md new file mode 100644 index 0000000..46fabb0 --- /dev/null +++ b/examples/software-auth-context.md @@ -0,0 +1,34 @@ +# Example: Database Schema Selection (Software Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) in a contemporary software engineering decision. + +## The Observation + +A startup's user authentication service experienced increasing query latency as the user base grew from 10,000 to 500,000 accounts. Database query times exceeded the 200ms service-level objective. + +## Engineering Translation + +When the original decision-maker leaves and a new engineer must modify the authentication service, the new engineer needs to understand why the current schema was chosen — not just what it is. Without that context, the new engineer may propose a schema change that re-introduces a problem the original engineer already solved. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Migrate user sessions from JSON column in PostgreSQL to a dedicated Redis cache, keeping PostgreSQL as the persistent store | +| **Observation** | Profiling showed 73% of slow queries were session-read operations against a JSONB column exceeding 50KB average row size. The JSONB column required table-level locking for updates. | +| **Alternatives** | (A) Shard the PostgreSQL database by user ID — rejected: session data is transient and sharding introduces operational complexity disproportionate to the benefit. (B) Move all auth data to MongoDB — rejected: transactional integrity for credential updates is required; MongoDB's document model does not provide the needed isolation guarantees. (C) Cache only in application memory — rejected: eliminates cross-instance session sharing, blocking horizontal scaling. | +| **Constraints** | Must maintain ACID compliance for credential writes. Must support horizontal scaling to 10+ instances. Must not exceed $200/month infrastructure cost at projected 12-month scale. Deployment must complete within a single maintenance window. | +| **Reasoning** | Redis provides sub-millisecond reads for session data, satisfies horizontal scaling through cluster mode, and costs approximately $30/month at projected scale. PostgreSQL retains ACID compliance for credential writes. The separation of concerns (Redis for transient session reads, PostgreSQL for persistent credential data) matches each store to the access pattern it handles best. | +| **Verification** | Load testing at 2x projected scale (1M concurrent sessions) showed p99 read latency of 4ms (down from 340ms). Write latency remained at 12ms. Failover test confirmed zero session loss during Redis node failure (replication recovery within 11 seconds, within the 30-second session timeout). | +| **Lineage** | Builds on the initial PostgreSQL-only architecture (context record CR-2024-001). Addresses the scalability limitation identified in that record's Open Questions field. | +| **Assumptions** | Session data size will remain below 10KB per session. Redis cluster mode will maintain sub-5ms p99 at projected scale. The application layer can handle the dual-store consistency model (read from Redis, fall back to PostgreSQL on cache miss). | +| **Open Questions** | At what user count does Redis cluster operational complexity exceed the benefit? Should session data have a TTL-based expiration policy in addition to the explicit logout mechanism? | + +## Self-Fading Assessment + +This example transports the reader from the abstract context record structure to a concrete software engineering decision. Once the reader understands how each field captures a real engineering reasoning process, the example has served its purpose. \ No newline at end of file diff --git a/examples/weaving.md b/examples/weaving.md new file mode 100755 index 0000000..c0f17bc --- /dev/null +++ b/examples/weaving.md @@ -0,0 +1,26 @@ +# Example: Weaving + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Structure carries meaning (OE-0001). The thread as a model of continuity (OE-0001). + +## The Observation + +A woven fabric's properties — strength, flexibility, pattern — emerge not from individual threads but from their specific arrangement. Remove one thread or alter one relationship, and the fabric's properties change. + +## Engineering Translation + +System properties emerge from component relationships. This is not unique to weaving — it is observable in bridge trusses, circuit boards, network topology, and source code. The pattern is universal: arrangement conveys information that the components alone do not. + +## Thread Continuity + +Weaving also demonstrates a concrete property of the thread model: continuity. Each thread in a woven fabric is continuous. If a thread breaks, the fabric weakens. If many threads break, the fabric fails. Thread continuity is necessary for structural integrity. + +This maps to engineering knowledge: continuity of understanding is necessary for the integrity of accumulated engineering knowledge. When the continuity breaks — when context is lost between generations — the fabric of engineering understanding degrades. + +## Self-Fading Assessment + +This example transports the reader from the unfamiliar (why does arrangement matter?) to the familiar (a woven fabric's strength depends on how threads are arranged, not on the threads alone). Once that understanding is reached, the example has served its purpose. \ No newline at end of file diff --git a/laws/communication-principles.md b/laws/communication-principles.md new file mode 100755 index 0000000..f83bfab --- /dev/null +++ b/laws/communication-principles.md @@ -0,0 +1,27 @@ +# Communication Principles + +**Status:** Draft +**Version:** 0.2.0-draft +**Phase:** The Bedrock Phase + +## Overview + +These principles govern how Open Engineer communicates. They are subordinate to the Engineering Laws (`laws/engineering-laws.md`) and the Editorial Principles (`reference/editorial-principles.md`). Where this document conflicts with either, those documents take precedence. + +--- + +## 1. Structure Is Content + +The arrangement of information conveys meaning. A well-structured document communicates through its architecture — the ordering of sections, the nesting of concepts, the dependency relationships — not only through its text. The dependency tree itself is an act of communication. + +--- + +## 2. Universality of Language + +Open Engineer communicates in engineering language. When it draws from a domain outside engineering, it translates the observation into engineering terms (see `reference/editorial-principles.md`, Translation). The standard must be accessible to any engineer regardless of their cultural or philosophical background. + +--- + +## 3. Precision Over Rhetoric + +Specification documents use declarative, testable statements. Rhetorical techniques — negation lists, emphatic repetition, appeals to intuition — are not prohibited in examples or presentation layers, but they have no place in specification definitions. A definition must be testable, not evocative. \ No newline at end of file diff --git a/laws/engineering-laws.md b/laws/engineering-laws.md new file mode 100755 index 0000000..567ad24 --- /dev/null +++ b/laws/engineering-laws.md @@ -0,0 +1,72 @@ +# Engineering Laws + +**Status:** Draft +**Version:** 0.2.0-draft +**Phase:** The Bedrock Phase + +## Overview + +These are the laws of the Open Engineer standard — binding constraints on all content, structure, and process. All specification documents, RFCs, reference materials, and implementations must comply with these laws. + +--- + +## Law 1: Universal Observation + +Open Engineer recognizes observations wherever they arise. It translates enduring observations into engineering principles without adopting the surrounding ideology. + +No tradition is diminished. No tradition is elevated above another. Multiple traditions are acknowledged as independent observers of reality. + +For the editorial implementation of this law, see `reference/editorial-principles.md` (Translation). + +--- + +## Law 2: Bedrock Immutability + +Reality does not change because an engineer's model of it changes. The standard must always distinguish between reality and the current understanding of reality. Understanding is provisional and evolves; the bedrock it rests on does not. + +--- + +## Law 3: Dependency Integrity + +Nothing later in the specification may redefine an earlier layer. Only extend it. + +A document may build on a lower-level document, but it may not alter the lower-level document's definitions or principles. This preserves the integrity of the dependency tree. + +--- + +## Law 4: Thread Integrity + +Knowledge continuity is maintained by deliberate action, not by default. The standard's primary structural obligation is to preserve the conditions under which the thread remains intact — meaning that a subsequent practitioner can reconstruct the reasoning behind a prior decision without direct access to the original decision-maker. + +--- + +## Law 5: Enduring Concepts + +When defining a standard, name the enduring concept rather than the technology that currently expresses it. + +Technologies are temporary expressions. Concepts endure. A standard anchored to technologies ages as those technologies age. A standard anchored to concepts remains stable as technologies change. + +### The Enduring Concept Test + +When introducing a term into the standard, apply this test: + +If the technology currently used to express this concept disappeared tomorrow, would this definition still be correct? + +If the answer is no, the definition names the technology, not the concept. Redefine it. + +### Example + +| Technology-Anchored | Enduring Concept | +|---|---| +| Git repository | Version-controlled collection | +| Markdown document | Human-readable specification | +| HTML page | Presentation layer | +| AI system | Reasoning system | + +--- + +## Law 6: Compression Over Expansion + +Every refinement should reduce the number of concepts required to explain the system. + +If a revision requires more concepts to explain the same territory, it is expansion, not refinement. The standard's concepts should become fewer and more precise over time, not more numerous. \ No newline at end of file diff --git a/reference/editorial-principles.md b/reference/editorial-principles.md new file mode 100755 index 0000000..d2d8b5e --- /dev/null +++ b/reference/editorial-principles.md @@ -0,0 +1,97 @@ +# Editorial Principles + +**Status:** Draft +**Version:** 0.2.0-draft +**Phase:** The Bedrock Phase + +## Overview + +This is the **sole authoritative source** for editorial rules governing all content in the Open Engineer standard. Specification documents, RFCs, reference materials, and root documents must follow these principles. They must not duplicate them. + +All editorial rules are subject to the Engineering Laws defined in `laws/engineering-laws.md`. + +--- + +## 1. Translation + +Open Engineer extracts observations from any domain and converts them into precise engineering language. It does not import the surrounding ideology, framework, or tradition. + +### What This Means + +Identify the specific observation that has engineering value. Translate that observation into engineering language. Discard the surrounding ideology. + +### Why This Matters + +This keeps Open Engineer universal. No tradition is diminished. No tradition is elevated. Multiple traditions are acknowledged as independent observers of reality. (See Law 1: Universal Observation.) + +### Examples + +| Source Domain | Observation | Engineering Translation | +|---|---|---| +| Multiple traditions | Attachment to preferred solutions distorts judgment | Commit to evidence over attachment to prior conclusions | +| Multiple traditions | Distinguish controllable from uncontrollable factors | Separate controllable design variables from environmental constraints | +| Multiple traditions | Inheriting an artifact means inheriting obligations | Engineering artifacts carry maintenance and extension responsibilities | +| Multiple traditions | Claims 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. A document that defines stewardship does not define inheritance. It references inheritance. + +This is how the standard remains readable and avoids the duplication that leads to divergence. + +--- + +## 3. The Four-Question Framework + +Every proposed 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 connects the observation to the principle? +4. **Relationship to Existing Concepts?** — How does this relate to what already exists? + +Nothing enters the standard without surviving these four layers. + +--- + +## 4. The Five-Question RC2 Refinement Gate + +Every proposed refinement to existing content must additionally answer: + +5. **Is it an enduring concept?** — Would this hold if current technologies disappeared? +6. **Does it already exist elsewhere?** — Does another document or term already cover this? +7. **Does it reduce ambiguity?** — Does this revision make something more precise? +8. **Can it survive technology change?** — Is it anchored to a concept or a technology? +9. **Does it strengthen rather than expand?** — Does this reduce the number of concepts required, or add one? + +If any answer is "no," the refinement is not ready. It may be a valid idea, but it is not yet bedrock. + +--- + +## 5. Enduring Concept Test + +When introducing a new term or revising an existing definition, apply this test (see Law 5): + +**If the technology currently used to express this concept disappeared tomorrow, would this definition still be correct?** + +If no: the definition names the technology, not the concept. Redefine it. + +This test applies to all documents, including this one. + +--- + +## 6. Self-Fading Example + +Examples serve as structural transportation — they carry the reader from the unfamiliar to the familiar (see OE-0001, Examples Are Bridges). An effective example becomes unnecessary once the reader has crossed that bridge. The example should fade from the reader's consciousness, leaving only the understanding it transported. + +An example that draws more attention to itself than to the concept it illustrates has failed. + +--- + +## 7. No Duplication + +No editorial rule, principle, or framework exists in more than one authoritative location. If a concept is defined in one document, all other documents reference it. This prevents silent divergence when one copy is updated and others are not. \ No newline at end of file diff --git a/reference/patterns.md b/reference/patterns.md new file mode 100755 index 0000000..2048d08 --- /dev/null +++ b/reference/patterns.md @@ -0,0 +1,41 @@ +# Patterns + +**Status:** Draft +**Version:** 0.2.0-draft +**Phase:** The Bedrock Phase + +## Overview + +This document catalogs structural and conceptual patterns that the standard has identified as recurring across engineering disciplines. + +--- + +## 1. Structure Carries Meaning + +**Pattern:** The arrangement and relationship between components conveys information that the individual components do not. + +**Engineering Manifestations:** +- Engineering drawings (arrangement of lines encodes spatial relationships) +- Specifications (ordering and interconnection of requirements) +- Network topology (node relationships define system behavior) +- Source code (function ordering and module structure convey design intent) + +**Standard Implication:** The dependency tree is itself an act of communication. The ordering of OE-0000 through OE-0011 carries meaning about conceptual priority. + +--- + +## 2. Examples Are Bridges + +**Pattern:** Examples serve as structural transportation from unfamiliar concepts to familiar understanding. + +**Standard Implication:** Every example in the standard must serve a specific bridging function. Examples are load-bearing, not decorative. For the editorial treatment of examples, see `reference/editorial-principles.md` (Self-Fading Example). + +--- + +## 3. The Pre-Discipline Principle + +**Pattern:** Before engineering disciplines specialized, shared principles existed that apply universally across all modern disciplines. + +**Evidence:** Observation, measurement, constraint-based decision-making, and knowledge transmission exist in every engineering discipline. These principles predate formal discipline boundaries. + +**Standard Implication:** Open Engineer seeks principles that apply across discipline boundaries. Discipline-specific content belongs in implementations, not in the core standard. \ No newline at end of file diff --git a/reference/vocabulary.md b/reference/vocabulary.md new file mode 100755 index 0000000..e311ec6 --- /dev/null +++ b/reference/vocabulary.md @@ -0,0 +1,28 @@ +# Vocabulary Reference + +**Version:** 0.2.0-draft +**Source:** OE-0002 (Core Vocabulary) +**Authoritative source for all terms:** OE-0002 + +This document provides a quick-access index. For full definitions, consult OE-0002 and the source specification documents. + +## Core Terms + +| Term | Short Definition | Source | +|---|---|---| +| Bedrock | Reality, which does not change regardless of an engineer's model of it | OE-0001 | +| The Thread | The model of knowledge continuity; has defined, testable properties | OE-0001 | +| Engineering Context | The structured record of reasoning behind an engineering decision | OE-0003 | +| Observation | A verifiable encounter with reality (direct or corroborated) | OE-0004 | +| Direct Observation | Measurement or experiment conducted by the practitioner or team | OE-0004 | +| Corroborated Observation | An outside observation independently confirmed by engineering evidence | OE-0004 | +| Survey | Structured assessment of the current state of understanding on a topic | OE-0005 | +| Understanding | A contextualized model of reality derived from observation and survey | OE-0006 | +| Verification | The process of testing understanding against reality | OE-0007 | +| Decision | A choice preserved as a structured context record | OE-0008 | +| Stewardship | The obligation to maintain and improve knowledge for future practitioners (transmit discipline) | OE-0009 | +| Inheritance | The act of receiving and engaging with inherited knowledge (receive discipline) | OE-0010 | +| Spiral Re-evaluation | Returning to previously examined questions with deeper understanding | OE-0001 | +| Translation | Converting observations into engineering language without importing ideology | OE-0001, editorial-principles.md | +| Amendment | Disciplined, verified extension or modification of the standard's body of knowledge | OE-0011 | +| Enduring Concept | A concept named by its function, not by current technology | engineering-laws.md | \ No newline at end of file diff --git a/rfc/rfc-0000.md b/rfc/rfc-0000.md new file mode 100755 index 0000000..d70f0ba --- /dev/null +++ b/rfc/rfc-0000.md @@ -0,0 +1,20 @@ +# RFC-0000: Purpose + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC establishes the purpose of the RFC process within Open Engineer and the framework by which all subsequent RFCs are evaluated. + +## Motivation + +Before any individual RFC is accepted, the project must agree on what an RFC is for and what it must accomplish. + +## Proposal + +The purpose of an RFC is to propose, justify, and specify a change to the standard. Every RFC must pass the editorial gate defined in `reference/editorial-principles.md`, which includes the four-question framework (Section 3). + +## 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 100755 index 0000000..7ab0880 --- /dev/null +++ b/rfc/rfc-0001.md @@ -0,0 +1,28 @@ +# 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. + +## Observation + +Throughout the development of Open Engineer, the most robust principles have emerged from verifiable encounters with reality, either direct or corroborated (see OE-0004 for the taxonomy). + +## Engineering Principle + +Observe first. Recognize patterns. Translate into engineering language. Verify against reality. Preserve the resulting understanding. + +## Reasoning + +Observation anchors the standard to reality. Without it, the standard becomes theory — potentially interesting, but not engineering. + +## Relationship to Existing Concepts + +This RFC underpins the dependency chain beginning at OE-0004. It is implemented through the editorial Translation principle (`reference/editorial-principles.md`, Section 1). \ No newline at end of file diff --git a/rfc/rfc-0002.md b/rfc/rfc-0002.md new file mode 100755 index 0000000..8de69ed --- /dev/null +++ b/rfc/rfc-0002.md @@ -0,0 +1,28 @@ +# RFC-0002: Thought Drift + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC defines "thought drift" — the accumulation of redundant or contradictory concepts under different names — and establishes countermeasures. + +## Motivation + +Continued ideation without structure leads to duplicates under different names. Thought drift erodes clarity and creates the ambiguity that a standard cannot tolerate. + +## Observation + +During development, the project observed that unconstrained ideation produced concepts that, upon review, were redundant with existing definitions under different names. + +## Engineering Principle + +No new concept may be added without first verifying it does not duplicate or contradict an existing concept. OE-0002 (Core Vocabulary) is the authoritative check. + +## Reasoning + +A standard requires one definition per term and one home per concept. Allowing drift creates ambiguity, which creates confusion, which undermines trust. + +## Relationship to Existing Concepts + +Thought drift is countered by Single Responsibility (`reference/editorial-principles.md`, Section 2), the RC2 Refinement Gate (Section 4), and Law 6 (Compression Over Expansion). \ No newline at end of file diff --git a/rfc/rfc-0003.md b/rfc/rfc-0003.md new file mode 100755 index 0000000..78857ae --- /dev/null +++ b/rfc/rfc-0003.md @@ -0,0 +1,28 @@ +# RFC-0003: Engineering Context + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC proposes that "preserving engineering context" be the defining purpose of the standard, and establishes the minimum required structure for a context record. + +## Motivation + +When engineers lose the reasoning behind decisions, they re-derive understanding from first principles. This is wasteful and error-prone. The most valuable thing a standard can preserve is not the final artifact, but the context that produced it. + +## Observation + +Engineers across all disciplines report that inherited systems without context records require significantly more effort to maintain, modify, or extend than systems with preserved reasoning. + +## Engineering Principle + +Open Engineer is an open standard for preserving engineering context. The context record — a structured document with defined required fields — is the unit of preservation. + +## Reasoning + +Context preservation is the thread made concrete. The minimum required fields (defined in OE-0003) give the standard an implementable artifact: a practitioner can produce a context record, and a subsequent practitioner can evaluate whether it meets the completeness criterion. + +## Relationship to Existing Concepts + +Engineering context is defined in OE-0003. Context records are the output of the decision process (OE-0008). \ No newline at end of file diff --git a/rfc/rfc-0004.md b/rfc/rfc-0004.md new file mode 100755 index 0000000..6332b41 --- /dev/null +++ b/rfc/rfc-0004.md @@ -0,0 +1,28 @@ +# RFC-0004: Vocabulary + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC formalizes Open Engineer's core vocabulary as a defined, versioned glossary with one authoritative location. + +## Motivation + +Engineers across disciplines share an informal conceptual vocabulary. Without formal definitions, terms are used inconsistently, leading to ambiguity. A standard requires precise, non-redundant terminology. + +## Observation + +During development, the same concept was sometimes described with different words in different documents, creating the potential for silent divergence. + +## Engineering Principle + +Every canonical term has one definition, located in one authoritative document (OE-0002). All other documents reference OE-0002; they do not redefine terms. + +## Reasoning + +A shared vocabulary is the foundation of a shared standard. Formal definitions eliminate ambiguity and create a reliable foundation for all subsequent work. + +## Relationship to Existing Concepts + +Vocabulary is defined in OE-0002. Term consistency is enforced by the No Duplication editorial principle (`reference/editorial-principles.md`, Section 7) and the Enduring Concept test (Section 5). \ No newline at end of file diff --git a/rfc/rfc-0005.md b/rfc/rfc-0005.md new file mode 100755 index 0000000..bb57860 --- /dev/null +++ b/rfc/rfc-0005.md @@ -0,0 +1,28 @@ +# RFC-0005: Stewardship + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC proposes stewardship — the obligation to maintain and improve engineering knowledge for future practitioners — as the governing principle for the standard. + +## Motivation + +Knowledge governed by ownership is hoarded, restricted, or lost when the owner departs. Knowledge governed by stewardship is maintained, extended, and transmitted. + +## Observation + +The most durable knowledge systems — open-source software, professional engineering bodies, craft guilds — are governed by stewardship rather than ownership. + +## Engineering Principle + +Standard documents are stewarded, not owned. Contributions are evaluated on value to future practitioners, not contributor status. + +## Reasoning + +Stewardship aligns with the standard's purpose: preserving engineering context across generations. Stewardship creates an obligation to preserve and improve. It includes the obligation to identify and flag context that has become obsolete or incorrect. + +## Relationship to Existing Concepts + +Stewardship is defined in OE-0009. It is the transmit discipline, paired with inheritance (OE-0010, the receive discipline). \ No newline at end of file diff --git a/rfc/rfc-0006.md b/rfc/rfc-0006.md new file mode 100755 index 0000000..102fb8e --- /dev/null +++ b/rfc/rfc-0006.md @@ -0,0 +1,28 @@ +# RFC-0006: Inheritance + +**Status:** Proposed +**Phase:** The Bedrock Phase + +## Abstract + +This RFC formalizes inheritance — the act of receiving and engaging with engineering knowledge from prior work — and distinguishes it from stewardship and from the thread. + +## Motivation + +Engineering knowledge is not created anew each generation. Without a formal concept of inheritance, the standard lacks a mechanism for describing how knowledge flows through time. + +## Observation + +The most enduring engineering traditions explicitly value knowledge transmission. When that transmission breaks down, knowledge is lost and must be re-derived at great cost. + +## Engineering Principle + +Inheritance is the receive discipline: the responsibility to actively understand what has been passed down, not merely to possess it. It is distinguished from stewardship (the transmit discipline) and from the thread (the channel model itself). + +## Reasoning + +Inheritance is the temporal dimension of engineering context. Context preservation (RFC-0003) is meaningless without a mechanism for passing preserved context forward. The distinction between stewardship (transmit) and inheritance (receive) is necessary because they face different failure modes: stewardship fails through neglect; inheritance fails through passivity. + +## Relationship to Existing Concepts + +Inheritance is defined in OE-0010. It depends on stewardship (OE-0009). It is measured by thread integrity (OE-0001). \ No newline at end of file diff --git a/spec/oe-0000-charter.md b/spec/oe-0000-charter.md new file mode 100755 index 0000000..21f6c67 --- /dev/null +++ b/spec/oe-0000-charter.md @@ -0,0 +1,92 @@ +# OE-0000: Charter + +**Status:** Draft +**Phase:** The Bedrock Phase +**Version:** 0.3.0-draft + +## 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. + +## Domain of Applicability + +This standard applies to any discipline in which practitioners make decisions under constraints, observe outcomes, and transmit the results of those decisions to subsequent practitioners. This includes but is not limited to: + +- Civil, mechanical, electrical, chemical, and aerospace engineering +- Software and systems engineering +- Biomedical and environmental engineering +- Industrial design and manufacturing engineering + +The standard does not require that all disciplines use identical methods. It requires that context preservation follow a common structural framework, regardless of discipline-specific content. + +## Nature of the Standard + +Open Engineer is a standard. + +Not a philosophy. Not a documentation system. Not a project. Not a presentation layer. + +Philosophy, documentation systems, projects, and presentation layers become implementations. The standard comes first. + +## Scope + +Open Engineer remains grounded in engineering while recognizing that valuable observations about decision-making and knowledge continuity have emerged from many domains throughout human history. It is open. It respects every discipline. It welcomes observations from every domain and every generation. It remains anchored to reality through observation, verification, and stewardship. + +## Governance Authority + +The Engineering Laws (see `laws/engineering-laws.md`) govern all content in this standard. All editorial rules are defined in `reference/editorial-principles.md`. Specification documents may reference but must not duplicate them. + +Amendment of governance content (Laws, Editorial Principles, Status Lifecycle) requires additional constraints beyond the standard change workflow. See OE-0011 (Amendment), section: Constitutional Governance. + +## Document Status Lifecycle + +| Status | Definition | +|---|---| +| **Draft** | Under active development. Content may change without formal process. | +| **Proposed** | Submitted for review. Content is stable pending review outcome. | +| **RC** (Release Candidate) | Reviewed and accepted. Frozen unless a subsequent RFC explicitly supcedes it. | +| **Accepted** | Part of the canonical standard. Changes require RFC. | +| **Deprecated** | Superseded by a later document. Retained for historical traceability. | + +Advancement from Draft to Proposed requires completion of the editorial gate defined in `reference/editorial-principles.md`. Advancement from Proposed to RC requires successful independent review. Advancement from RC to Accepted requires no outstanding objections. + +## Versioning + +Each specification document carries an independent version number following the pattern `MAJOR.MINOR.PATCH-status`. The overall standard version is the highest version number of any Accepted document. + +## Conformance Criteria + +A context record complies with Open Engineer when all of the following are true: + +1. **Field Completeness:** All eight required fields (Decision, Observation, Alternatives, Constraints, Reasoning, Verification, Lineage, Assumptions) are present and populated. + +2. **Observation Traceability:** The Observation field references at least one verifiable encounter with reality (direct or corroborated as defined in OE-0004). + +3. **Constraint Bounding:** The Constraints field identifies at least one constraint that bounded the decision. + +4. **Verification Against Reality:** The Verification field describes a test, measurement, or assessment against observable outcomes — not against a model or an opinion. + +5. **Lineage Traceability:** The Lineage field either references at least one prior context record or explicitly states "no prior work" with rationale. + +6. **Assumption Awareness:** The Assumptions field contains at least one assumption, even if the assumption is "no significant unknowns." + +7. **No Contradiction:** The context record does not contradict any Accepted-status specification document. + +A context record that satisfies all seven criteria is compliant. A record that satisfies criteria 1-6 but not 7 is compliant at the document level but may require resolution at the project level. Records that fail any of criteria 1-6 are non-compliant. + +## Testable Hypotheses + +The standard is based on hypotheses that require empirical validation during the Implementation Phase. These are not asserted as proven; they are stated as testable predictions: + +**Hypothesis 1 (Context Preservation):** Practitioners who receive an OE-compliant context record will require less time to reconstruct decision reasoning than practitioners who receive only the final artifact, as measured by controlled comparison. + +**Hypothesis 2 (Translation):** Engineering principles derived through translation (extracting observations from any domain and converting to engineering language) will demonstrate equal or greater durability across technology changes than principles derived from a single domain. + +**Hypothesis 3 (Thread Integrity):** A context record that passes all seven conformance criteria will enable a practitioner unfamiliar with the original decision to reconstruct the reasoning, as measured by the reconstruction test defined in OE-0001. + +The standard does not require these hypotheses to be proven before use. It requires that they be testable and that the standard's adoption be evaluated against them. + +## 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 100755 index 0000000..f2aab26 --- /dev/null +++ b/spec/oe-0001-foundation.md @@ -0,0 +1,79 @@ +# OE-0001: Foundation + +**Status:** Draft +**Version:** 0.2.0-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. + +### Definition + +Within this standard, **Bedrock** refers to the physical world and its constraints — materials, physics, the behavior of systems under load — which does not change because an engineer's model of it changes. Every engineering model, specification, or theory is a layer of understanding built on top of that reality. Bedrock is always there regardless of how understanding is amended around it. + +The standard must always distinguish between reality and the current understanding of reality. Confusing the two leads to the reification of models — treating an approximation as if it were the thing it approximates. + +### Term Collision Note + +"Bedrock" has an established meaning in geotechnical engineering (the consolidated rock underlying surface soils). Within the scope of this standard, the term carries the definition above. Where ambiguity is possible, the standard uses the phrase "reality basis" as an unambiguous synonym. + +### Methodological Commitment + +This standard makes a methodological commitment, not an ontological one. The commitment is: test understanding against observable outcomes. This commitment is compatible with multiple philosophical positions regarding the nature of reality. What the standard requires is that engineering models be tested against what is observed — not that practitioners hold a specific philosophical view about what reality is. Whether reality is ultimately knowable, socially constructed, or independent of observation is outside the scope of this standard. What is within scope is the engineering practice of testing models against evidence. + +## The Thread + +Knowledge continuity is the channel through which engineering understanding passes between practitioners over time. + +**Properties of the thread:** + +- It is maintained by deliberate action, not by default. When practitioners stop maintaining it, it degrades. +- It carries understanding, not just information. A procedure manual preserves information. A well-documented decision record preserves understanding. +- Its integrity is measurable by whether a subsequent practitioner can reconstruct the reasoning behind a prior decision without direct access to the original decision-maker. +- It breaks when context is lost — when the reasoning, alternatives, and constraints behind a decision are no longer accessible. + +The thread is not a metaphor for continuity. It is a model of continuity with defined properties. The model is testable: given a preserved engineering context record, can a practitioner unfamiliar with the original decision reconstruct the reasoning? If yes, the thread is intact. If no, the thread has broken. + +## Spiral Re-evaluation + +Spiral re-evaluation is the process of returning to previously examined questions with additional experience or evidence, producing progressively deeper understanding. + +Spiral re-evaluation differs from iteration in that each pass deepens understanding rather than merely repeating a process. It differs from repetition in that new experience or evidence is incorporated at each pass. The spiral metaphor captures the dual nature of the process: it returns to the same questions (circular) but at a deeper level of understanding (vertical progression). + +## Structure Carries Meaning + +The arrangement and relationship between components conveys information that the individual components do not. An engineering drawing is not a collection of lines — it is a specific arrangement of lines that encodes precise spatial relationships. A specification is not a list of statements — it is an ordered, interconnected structure in which position and dependency carry meaning. + +This principle has consequences for the standard itself: the ordering of the specification documents is part of their meaning. + +## Examples Are Bridges + +Examples serve as structural transportation, carrying the reader from unfamiliar concepts to familiar understanding. Examples are load-bearing elements of the standard, not decorative additions. Every example must serve a specific bridging function. + +For the editorial treatment of examples, including the Self-Fading Example principle, see `reference/editorial-principles.md`. + +## Editorial Principles + +The authoritative editorial principles governing all content in this standard are defined in `reference/editorial-principles.md`. This document does not duplicate them. All specification documents reference rather than reproduce them. + +## Process + +The foundational process that Open Engineer follows: + +1. Observe first. +2. Recognize patterns. +3. Translate into engineering language. +4. Verify against reality. +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. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ 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 100755 index 0000000..a2f3f99 --- /dev/null +++ b/spec/oe-0002-core-vocabulary.md @@ -0,0 +1,78 @@ +# OE-0002: Core Vocabulary + +**Status:** Draft +**Version:** 0.2.0-draft +**Depends on:** OE-0001 (Foundation) +**Phase:** The Bedrock Phase + +## Overview + +Engineers across disciplines share a conceptual vocabulary. Open Engineer documents that vocabulary's grammar — the precise definitions, relationships, and boundaries of terms that carry specific meaning within this standard. + +All terms defined here must be used consistently across all specification documents, RFCs, and reference materials. The authoritative editorial rules governing terminology are defined in `reference/editorial-principles.md` (see: Enduring Concept Test, Single Responsibility). + +## Terms + +### Bedrock (reality basis) + +Within this standard, the physical world and its constraints — materials, physics, the behavior of systems under load — which does not change regardless of an engineer's model of it. Where ambiguity with geotechnical usage is possible, the phrase "reality basis" is used as an unambiguous synonym. (Source: OE-0001) + +### The Thread + +The model of knowledge continuity through which engineering understanding passes between practitioners over time. The thread has defined properties: it requires deliberate maintenance, carries understanding rather than just information, has measurable integrity, and breaks when context is lost. (Source: OE-0001) + +### Engineering Context + +The structured record of the reasoning behind an engineering decision, including the observations, alternatives, constraints, and verification that produced it. The minimum required structure is defined in OE-0003. (Source: OE-0003) + +### Observation + +A verifiable encounter with reality, either direct (through measurement or experiment) or corroborated (independently confirmed by multiple traditions or domains). See OE-0004 for the full taxonomy. (Source: OE-0004) + +### Corroborated Observation + +An observation reported by a source outside direct engineering practice that has been independently confirmed by engineering evidence or by independent confirmation across multiple traditions. (Source: OE-0004) + +### Survey + +A structured assessment of the current state of engineering understanding on a specific topic, aggregating observations, identifying patterns, and flagging gaps. (Source: OE-0005) + +### Understanding + +A contextualized model of reality derived from observation and organized through survey. Understanding is the state an engineer reaches when they can explain not only what a system does, but why it was designed that way, what alternatives were considered, and what trade-offs were made. Understanding is distinct from information: information is the raw material; understanding is the structured relationship between information, context, and reality. (Source: OE-0006) + +### Verification + +The process of testing understanding against reality. Understanding is provisional until verified. See OE-0007. (Source: OE-0007) + +### Decision + +A choice made within a specific context, informed by observation and bounded by constraints, preserved as a structured record. See OE-0008. (Source: OE-0008) + +### Stewardship + +The obligation to maintain and improve engineering knowledge for future practitioners. Stewardship is the transmit discipline: the responsibility to pass knowledge forward in better condition than it was received. See OE-0009. (Source: OE-0009) + +### Inheritance + +The act of receiving and engaging with engineering knowledge from prior work. Inheritance is the receive discipline: the responsibility to actively understand what has been passed down, not merely to possess it. See OE-0010. (Source: OE-0010) + +### Spiral Re-evaluation + +The process of returning to previously examined questions with additional experience or evidence, producing progressively deeper understanding. (Source: OE-0001) + +### Translation + +The process of converting an observation from any domain into precise engineering language. Translation extracts the observation while discarding the surrounding ideology. The authoritative rules governing translation are defined in `reference/editorial-principles.md`. (Source: OE-0001, `reference/editorial-principles.md`) + +### Amendment + +The disciplined, verified extension or modification of the standard's body of knowledge through the change workflow defined in OE-0011. (Source: OE-0011) + +### Enduring Concept + +A concept identified by its function rather than by any technology that currently expresses it. Enduring concepts survive technology change. The test for enduring-concept compliance is defined in `reference/editorial-principles.md`. (Source: `laws/engineering-laws.md`, `reference/editorial-principles.md`) + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ 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 100755 index 0000000..a7f831b --- /dev/null +++ b/spec/oe-0003-engineering-context.md @@ -0,0 +1,69 @@ +# OE-0003: Engineering Context + +**Status:** Draft +**Version:** 0.2.0-draft +**Depends on:** OE-0002 (Core Vocabulary) +**Phase:** The Bedrock Phase + +## Overview + +Open Engineer is an open standard for preserving engineering context. + +Everything else in the standard extends from that purpose. + +## Definition + +Engineering context is the structured record of the reasoning behind an engineering decision. A complete context record enables a subsequent practitioner to reconstruct why a decision was made, what alternatives were considered, what constraints applied, and how the outcome was confirmed. + +Context is not background information. It is the decision-shaped record of an engineering process. Without context, a decision is an isolated artifact — its output may be visible but its reasoning is inaccessible. + +## Minimum Context Record Structure + +Every engineering context record must contain the following fields: + +| Field | Description | Required | +|---|---|---| +| **Decision** | What was decided | Yes | +| **Observation** | What was observed that prompted the decision | Yes | +| **Alternatives** | What options were considered, including rejected options | Yes | +| **Constraints** | What bounded the choice (technical, environmental, temporal, economic) | Yes | +| **Reasoning** | Why this option was selected over the alternatives | Yes | +| **Verification** | How the outcome was confirmed against reality | Yes | +| **Lineage** | What prior work this decision builds on | Yes | +| **Assumptions** | What was assumed, both explicit and implicit | Yes | + +### Supplementary Fields + +Context records may additionally include: + +| Field | Description | +|---|---| +| **Open Questions** | What remains unknown or uncertain | +| **Discipline-Specific Data** | Measurements, calculations, test results relevant to the specific engineering domain | +| **Traceability** | Links to related context records, specifications, or requirements | + +### Completeness + +A context record is complete when all required fields are populated with sufficient detail that a practitioner unfamiliar with the original decision can reconstruct the reasoning. Sufficiency of detail is judged by whether the record passes the thread integrity test defined in OE-0001: can the reader explain why the decision was made without consulting the original decision-maker? + +## Why Context Matters + +When context is lost, practitioners must re-derive understanding from first principles. Re-derivation is costly in engineering time and introduces risk when the re-derivation produces different conclusions than the original reasoning. + +When context is preserved, subsequent practitioners begin where their predecessors left off, building on verified understanding rather than restarting from first principles. This is the function of the thread made concrete. + +## Context as the Unit of Preservation + +If Open Engineer has a unit of measurement, it is the context record — a structured, self-contained record of engineering reasoning. + +Every other element of the standard serves the goal of capturing, structuring, preserving, and transmitting engineering context. + +## Known Limitations + +This standard addresses explicit, articulable context. Much engineering knowledge is tacit — embodied in practice, judgment, and experience. Tacit knowledge cannot be fully captured in a structured record. The standard acknowledges this limitation and aims to preserve the explicit portion as completely as possible, recognizing that it captures the articulable fraction of engineering understanding. + +Some engineering context is proprietary, classified, or legally restricted. The standard defines the structure of context records but does not define access control mechanisms. Implementations must address confidentiality, security, and access control as required by their domain. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0004-observation.md b/spec/oe-0004-observation.md new file mode 100755 index 0000000..a6a31fc --- /dev/null +++ b/spec/oe-0004-observation.md @@ -0,0 +1,62 @@ +# OE-0004: Observation + +**Status:** Draft +**Version:** 0.2.0-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 verifiable encounter with reality. + +## Taxonomy of Observations + +Not all observations enter the engineering process through the same path. Open Engineer distinguishes two categories: + +### Direct Observation + +A measurement, experiment, or empirical encounter with physical reality conducted by the practitioner or their team. Direct observations are the primary input to engineering decisions. + +Examples: load test results, material strength measurements, system performance benchmarks, field inspections. + +### Corroborated Observation + +An observation reported by a source outside direct engineering practice that has been independently confirmed by engineering evidence or by independent confirmation across multiple traditions or domains. + +Corroborated observations are valid inputs when the underlying observation has withstood testing from independent sources. The standard does not accept them on authority — it accepts them on the basis of independent corroboration. + +Examples of corroboration: + +| Reported Observation | Independent Engineering Confirmation | +|---|---| +| Distinguish controllable from uncontrollable factors (multiple traditions) | Control theory, stress engineering, decision theory — all independently arrived at this distinction | +| Attachment to preferred solutions distorts judgment (multiple traditions) | Cognitive bias research, engineering failure analysis — both confirm this pattern | +| Hypotheses must survive testing (scientific method) | Every engineering verification methodology confirms this | + +## The Principle of Observation First + +Observe first. Before theorizing. Before abstracting. Before generalizing. The practitioner must first identify what has been observed — directly or through corroboration — and record it as it is, not as expected or desired. + +This is the first step in the Open Engineer process: + +1. Observe first. +2. Recognize patterns. +3. Translate into engineering language. +4. Verify against reality. +5. Preserve the resulting understanding. + +## Observation as Foundation + +No later specification document may redefine what observation means. Only extend it. Observation is bedrock. + +## Single Responsibility + +This document defines observation and its taxonomy. It does not define verification (see OE-0007) or translation (see `reference/editorial-principles.md`). It references them. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0005-survey.md b/spec/oe-0005-survey.md new file mode 100755 index 0000000..302ee24 --- /dev/null +++ b/spec/oe-0005-survey.md @@ -0,0 +1,40 @@ +# OE-0005: Survey + +**Status:** Draft +**Version:** 0.2.0-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. + +## Definition + +A survey captures what is known, what is unknown, and what is contested within a specific engineering domain. A survey aggregates observations (OE-0004), identifies patterns, and flags gaps. It produces an organized view of the current state of understanding that serves as input to the formation of understanding (OE-0006). + +## Structure + +A survey document must contain: + +1. **Scope** — The specific topic or domain being assessed +2. **Observations Collected** — The direct and corroborated observations relevant to the topic +3. **Patterns Identified** — Recurring relationships or principles observed across the collected observations +4. **Gaps Flagged** — Areas where observations are missing, insufficient, or contested +5. **Relationship to Prior Surveys** — How this survey builds on or differs from prior assessments + +## 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. + +## Relationship to Understanding + +A survey is not understanding itself. It is the organized input from which understanding is formed. Understanding (OE-0006) is the contextualized model that a practitioner constructs by engaging with a survey's findings. + +## Single Responsibility + +This document defines the structure and role of surveys. It does not define understanding (see OE-0006). It references it. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0006-understanding.md b/spec/oe-0006-understanding.md new file mode 100755 index 0000000..d04bbd1 --- /dev/null +++ b/spec/oe-0006-understanding.md @@ -0,0 +1,40 @@ +# OE-0006: Understanding + +**Status:** Draft +**Version:** 0.2.0-draft +**Depends on:** OE-0005 (Survey) +**Phase:** The Bedrock Phase + +## Overview + +Understanding is a contextualized model of reality derived from observation and organized through survey. + +## Definition + +Understanding is the state a practitioner reaches when they can explain not only what a system does, but why it was designed that way, what alternatives were considered, and what trade-offs were made. + +Understanding is distinct from information. Information is the raw material — facts, measurements, records. Understanding is the structured relationship between information, context, and reality. A database contains information. An engineer who can explain the reasoning behind every entry in that database holds understanding. + +## 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) + +Observation provides the raw input. Survey organizes observations into a coherent picture. Understanding is the model the practitioner constructs from that picture. Verification (OE-0007) then tests that model against reality. + +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 What the Thread Carries + +When one generation passes engineering knowledge to the next, what they pass is understanding — the deep comprehension of why things are the way they are, not merely what things are. + +Open Engineer's purpose is to preserve this understanding so that each generation can begin closer to bedrock than the last. The mechanism for that preservation is the engineering context record (OE-0003). + +## Single Responsibility + +This document defines understanding. It does not define verification (see OE-0007). It references it. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0007-verification.md b/spec/oe-0007-verification.md new file mode 100755 index 0000000..37d90fe --- /dev/null +++ b/spec/oe-0007-verification.md @@ -0,0 +1,40 @@ +# OE-0007: Verification + +**Status:** Draft +**Version:** 0.2.0-draft +**Depends on:** OE-0006 (Understanding) +**Phase:** The Bedrock Phase + +## Overview + +Verification is the process of testing understanding against reality. + +## Definition + +Verification applies to understanding that has been formed through observation and survey. It is the mechanism by which understanding earns confidence. + +No amount of reasoning, no matter how elegant, substitutes for verification. An engineering model that has not been verified is a hypothesis — potentially valuable, but not yet reliable enough to base decisions on. + +## The Verification Loop + +Verification closes the loop with observation: + +1. Observation provides the initial input (OE-0004) +2. Survey organizes observations (OE-0005) +3. Understanding forms a model (OE-0006) +4. Verification tests the model against reality +5. If the model fails verification, the practitioner returns to observation with new information + +This loop is what drives spiral re-evaluation. Each cycle through the loop potentially deepens understanding. + +## Relationship to Understanding + +Verification is applied to understanding. It is not part of understanding's definition. Understanding (OE-0006) is the model. Verification is the test applied to that model. The dependency chain reflects this ordering: a model must exist before it can be tested. + +## Single Responsibility + +This document defines verification and its relationship to the observation loop. It does not define decision-making (see OE-0008). It references it. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0008-decisions.md b/spec/oe-0008-decisions.md new file mode 100755 index 0000000..d5fe064 --- /dev/null +++ b/spec/oe-0008-decisions.md @@ -0,0 +1,34 @@ +# OE-0008: Decisions + +**Status:** Draft +**Version:** 0.2.0-draft +**Depends on:** OE-0007 (Verification) +**Phase:** The Bedrock Phase + +## Overview + +A decision is a choice made within a specific context, informed by observation and bounded by constraints, preserved as a structured record. + +## Definition + +In Open Engineer, a decision 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 isolated artifact. A decision with its context is a building block for future understanding. + +## The Context Record as Decision Output + +Every decision produces an engineering context record (OE-0003). The minimum required fields of that record — Decision, Observation, Alternatives, Constraints, Reasoning, Verification, Lineage, Assumptions — constitute the structured output of the decision process. + +## Decisions as Engineering Context + +When preserved as a context record, a decision allows future practitioners to understand not just what was done, but why — and to make better decisions as a result. This is the mechanism by which the thread is maintained. + +## Editorial Gate for New Additions + +All additions to the standard — whether new specification content, RFCs, or reference material — must pass the editorial gate defined in `reference/editorial-principles.md`. That gate includes the four-question framework, the Enduring Concept test, and the RC2 refinement criteria. This document does not duplicate those rules. + +## Single Responsibility + +This document defines the role of decisions within the standard and their relationship to context records. It does not define the editorial process for evaluating decisions (see `reference/editorial-principles.md`). It references it. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0009-stewardship.md b/spec/oe-0009-stewardship.md new file mode 100755 index 0000000..e619054 --- /dev/null +++ b/spec/oe-0009-stewardship.md @@ -0,0 +1,41 @@ +# OE-0009: Stewardship + +**Status:** Draft +**Version:** 0.2.0-draft +**Depends on:** OE-0008 (Decisions) +**Phase:** The Bedrock Phase + +## Overview + +Stewardship is the obligation to maintain and improve engineering knowledge for future practitioners. + +## Definition + +Stewardship is the transmit discipline: the responsibility to pass engineering knowledge forward in better condition than it was received. A steward does not possess the knowledge — they hold it in trust, maintaining it and improving it before passing it onward. + +## Stewardship Distinguished from Inheritance + +Stewardship and inheritance (OE-0010) are coupled but distinct: + +- **Stewardship** is the transmit direction. It governs how the current practitioner maintains, improves, and transmits knowledge. +- **Inheritance** is the receive direction. It governs how the next practitioner receives and engages with what has been transmitted. + +A single generation performs both simultaneously — inheriting from the past and stewarding for the future. They are separated in the specification because they impose different obligations and face different failure modes. Stewardship fails through neglect. Inheritance fails through passivity. + +## Implications + +- Standard documents are stewarded, not owned. +- Contributions are evaluated on their value to future practitioners, not the status of the contributor. +- The standard's primary obligation is to clarity and preservation. + +## Known Limitation: Incorrect or Obsolete Context + +Stewardship includes the obligation to identify and flag context that has become obsolete or that was incorrect when inherited. Preservation is not blind accumulation. A steward must actively evaluate whether inherited understanding still reflects reality and, where it does not, document the discrepancy. + +## Single Responsibility + +This document defines stewardship. It does not define inheritance (see OE-0010). It references it. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0010-inheritance.md b/spec/oe-0010-inheritance.md new file mode 100755 index 0000000..cf8fd12 --- /dev/null +++ b/spec/oe-0010-inheritance.md @@ -0,0 +1,38 @@ +# OE-0010: Inheritance + +**Status:** Draft +**Version:** 0.2.0-draft +**Depends on:** OE-0009 (Stewardship) +**Phase:** The Bedrock Phase + +## Overview + +Inheritance is the act of receiving and engaging with engineering knowledge from prior work. + +## Definition + +Inheritance is the receive discipline: the responsibility to actively understand what has been passed down, not merely to possess it. Passive reception — storing documents without engaging with their reasoning — is not inheritance. Inheritance requires the practitioner to reconstruct the understanding behind the inherited context. + +## Inheritance Distinguished from the Thread + +The thread (OE-0001) is the channel — the model of continuity itself. Inheritance is the act of engaging with what that channel carries. The thread's integrity (OE-0001) is measured by whether inheritance succeeds: can the inheriting practitioner reconstruct the original reasoning? If yes, the thread is intact. If no, the thread has broken at that point. + +## Inheritance Distinguished from Stewardship + +Inheritance and stewardship (OE-0009) are coupled but distinct. See OE-0009 for the full distinction. + +## Inheriting Responsibilities + +Practitioners inherit responsibilities as well as resources. Every engineering artifact comes with obligations: a bridge must be maintained, a specification must be kept current, a body of knowledge must be evaluated and extended. The inheriting practitioner assumes these obligations as part of receiving the artifact. + +## The Pre-Discipline Principle + +Engineering was not always divided into civil, mechanical, electrical, software. Before specialization, engineering was unified around shared principles: observation, measurement, craftsmanship, and the transmission of knowledge. Open Engineer asks what principles existed before the disciplines separated — because those principles apply universally and form the bedrock on which discipline-specific knowledge is built. + +## Single Responsibility + +This document defines inheritance. It does not define stewardship (see OE-0009) or the thread (see OE-0001). It references them. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/spec/oe-0011-amendment.md b/spec/oe-0011-amendment.md new file mode 100644 index 0000000..1e30ef2 --- /dev/null +++ b/spec/oe-0011-amendment.md @@ -0,0 +1,61 @@ +# OE-0011: Amendment + +**Status:** Draft +**Version:** 0.3.0-draft +**Depends on:** OE-0010 (Inheritance) +**Phase:** The Bedrock Phase + +## Overview + +Amendment is the disciplined, verified extension or modification of the standard's body of knowledge. + +## Definition + +Amendment is not arbitrary change. It is the extension or modification of the standard through the defined change workflow. Every change must survive the editorial gate defined in `reference/editorial-principles.md`. Every change must be consistent with the dependency tree. + +## The Dependency Tree + +The specification documents form a strict dependency chain: + +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) -> Decision (OE-0008) -> Stewardship (OE-0009) -> Inheritance (OE-0010) -> Amendment (OE-0011) + +Nothing later in the chain may redefine an earlier layer. Only extend it. + +## The Change 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 subsequent RFC explicitly supersedes it. The status lifecycle governing these transitions is defined in OE-0000 (Charter). + +## Constitutional Governance + +### Amendment of Technical Content + +Changes to specification documents (OE-0000 through OE-0011) follow the standard change workflow: Observe -> Draft -> Review -> Accept -> Freeze (RC) -> Reference. + +### Amendment of Governance Content + +Changes to the Engineering Laws (`laws/engineering-laws.md`), Editorial Principles (`reference/editorial-principles.md`), or Document Status Lifecycle (OE-0000) require an additional constraint: + +1. The proposed change must survive the standard editorial gate (see `reference/editorial-principles.md`). +2. The proposed change must not reduce the precision of an existing law or principle. +3. The proposed change must be reviewed by at least two independent reviewers who were not involved in drafting it. +4. The proposed change must not contradict any Accepted-status document. + +This two-tier process ensures that governance changes receive higher scrutiny than technical content changes, while remaining within a single coherent framework rather than requiring a separate constitutional document. + +## Spiral Re-evaluation as Amendment + +Amendment is not linear. It is spiral. The standard will return to earlier concepts with deeper understanding, refining and extending them without contradicting the reality basis they rest on. Each spiral pass either eliminates ambiguity or strengthens traceability. + +## 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, downstream implementations — presentation layers, interchange formats, context record tooling — will not require new concepts. They will express what already exists in the specification. + +The specification leads. Everything else follows. + +## Applicable Laws + +This document is governed by all Engineering Laws defined in `laws/engineering-laws.md`. \ No newline at end of file diff --git a/whatremains.txt b/whatremains.txt new file mode 100755 index 0000000..5b89676 --- /dev/null +++ b/whatremains.txt @@ -0,0 +1,110 @@ +WHAT REMAINS — RC2 Final Revision +==================================== + +This file tracks the status of all identified gaps and remaining +work after the gap-closure revision. + +All seven gaps from the RC2 review have been addressed. This file +documents their status and any residual items. + + +GAP CLOSURE STATUS +==================== + +1. Constitutional governance layer CLOSED + OE-0011 (Amendment) now defines a two-tier amendment process. + Technical content follows the standard workflow. + Governance content (Laws, Editorial Principles, Status Lifecycle) + requires: (a) standard editorial gate, (b) no precision reduction, + (c) two independent reviewers, (d) no contradiction with Accepted + documents. OE-0000 references this. The "Constitutional Gap" + acknowledgment has been removed — the gap is filled. + +2. "Bedrock" and "Evolution" term collisions CLOSED + "Evolution" renamed to "Amendment" — it describes a formal change + process, which is the standard term in standards bodies. File + renamed from oe-0011-evolution.md to oe-0011-amendment.md. All + cross-references updated. + "Bedrock" retains its name with two mitigations: (a) OE-0001 now + defines it precisely and includes a Term Collision Note + acknowledging the geotechnical meaning and providing "reality + basis" as an unambiguous synonym. (b) OE-0002 lists it as + "Bedrock (reality basis)." This is how standards handle term + collision — define the term of art and note the collision. + +3. Conformance testing criteria CLOSED + OE-0000 now defines seven testable conformance criteria: + (1) Field Completeness, (2) Observation Traceability, + (3) Constraint Bounding, (4) Verification Against Reality, + (5) Lineage Traceability, (6) Assumption Awareness, + (7) No Contradiction. Three compliance levels are defined: + compliant, compliant-with-resolution-needed, non-compliant. + +4. Empirical claims reframed CLOSED + OE-0000 now contains a "Testable Hypotheses" section with three + formal hypotheses: (1) Context Preservation — OE-compliant + records reduce re-derivation time. (2) Translation — translated + principles demonstrate equal or greater durability. (3) Thread + Integrity — conformance-compliant records enable reasoning + reconstruction. All are stated as testable predictions requiring + empirical validation, not as proven assertions. + +5. Historical citations CLOSED + Antikythera example now cites: + - Freeth, T. et al. (2021). *Scientific Reports*, 11, 5823. + - de Solla Price, D. (1974). *Transactions of the American + Philosophical Society*, 64(7). + +6. Philosophical realism objection CLOSED + OE-0001 Bedrock section now includes a "Methodological + Commitment" subsection: the standard requires testing models + against observable outcomes (methodological) but does not + require practitioners to hold a specific philosophical position + about the nature of reality (ontological). Compatible with + both realism and pragmatism. + +7. Contemporary examples CLOSED + Two new example files added: + - examples/software-auth-context.md (database schema selection, + software engineering) + - examples/biomedical-implant-context.md (hip implant material + selection, biomedical engineering) + Both demonstrate the context record structure (OE-0003) with + fully populated fields in a contemporary engineering discipline. + + +RESIDUAL ITEMS (Not Gaps — Future Phase Work) +================================================= + +These are not specification defects. They are implementation-phase +work that cannot be completed during the Bedrock Phase. + +1. Implementation Phase tooling + website/, implementations/, schemas/, tools/ remain empty + structural placeholders. + +2. Empirical hypothesis testing + The three hypotheses in OE-0000 require real-world testing with + practitioners. This is the first task of the Implementation + Phase. + +3. "Bedrock" term collision — full decision + The collision is documented and mitigated. The project may + ultimately choose to fully rename to "reality basis." This is + a project decision, not a specification defect. + +4. Additional discipline-specific examples + Chemical, aerospace, environmental, and manufacturing engineering + examples would further strengthen cross-discipline claims. These + are best created by practitioners in those domains during the + Community Phase. + +5. Context record interchange format + The minimum required fields are defined. A machine-readable + schema (JSON, YAML, or other) for context record interchange + will be defined during the Implementation Phase. + +6. RC2 Milestone Statement + "RC2 began when the project shifted from creating concepts to + refining language." This is process metadata, not specification + content. It belongs in project records, not in the standard. \ No newline at end of file