From 7ee06ad22be128e228fe5dc25fafbb4ad1b26c0e Mon Sep 17 00:00:00 2001 From: Jeremy Anderson Date: Fri, 3 Jul 2026 01:35:13 -0400 Subject: [PATCH] open engineer rc3 --- CHARTER.md | 23 ++++ CONTRIBUTING.md | 35 ++++++ LICENSE | 32 +++++ README.md | 31 +++++ ROADMAP.md | 69 +++++++++++ examples/aerospace-thermal-protection.md | 34 +++++ examples/antikythera.md | 26 ++++ examples/biomedical-implant-context.md | 34 +++++ examples/bridge-survey.md | 31 +++++ examples/chemical-process-catalyst.md | 34 +++++ examples/clockwork.md | 24 ++++ examples/construction-siting-environmental.md | 44 +++++++ examples/electrical-grounding-architecture.md | 34 +++++ examples/environmental-remediation.md | 34 +++++ examples/inheritance-steelmaking.md | 28 +++++ examples/manufacturing-joining-process.md | 35 ++++++ examples/mechanical-bearing-selection.md | 34 +++++ examples/observation-first-darcy.md | 38 ++++++ examples/pre-discipline-measurement.md | 36 ++++++ examples/software-architecture-migration.md | 42 +++++++ examples/software-auth-context.md | 34 +++++ .../spiral-reevaluation-flight-control.md | 34 +++++ examples/stewardship-roman-concrete.md | 32 +++++ examples/survey-retaining-wall-failure.md | 42 +++++++ examples/weaving.md | 26 ++++ laws/communication-principles.md | 27 ++++ laws/engineering-laws.md | 72 +++++++++++ reference/editorial-principles.md | 97 +++++++++++++++ reference/patterns.md | 19 +++ reference/vocabulary.md | 29 +++++ 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 | 96 ++++++++++++++ spec/oe-0001-foundation.md | 83 +++++++++++++ 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 | 34 +++++ spec/oe-0011-amendment.md | 61 +++++++++ whatremains.txt | 117 ++++++++++++++++++ 50 files changed, 2093 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 100644 examples/aerospace-thermal-protection.md create mode 100755 examples/antikythera.md create mode 100755 examples/biomedical-implant-context.md create mode 100755 examples/bridge-survey.md create mode 100644 examples/chemical-process-catalyst.md create mode 100755 examples/clockwork.md create mode 100644 examples/construction-siting-environmental.md create mode 100644 examples/electrical-grounding-architecture.md create mode 100644 examples/environmental-remediation.md create mode 100644 examples/inheritance-steelmaking.md create mode 100644 examples/manufacturing-joining-process.md create mode 100644 examples/mechanical-bearing-selection.md create mode 100644 examples/observation-first-darcy.md create mode 100644 examples/pre-discipline-measurement.md create mode 100644 examples/software-architecture-migration.md create mode 100755 examples/software-auth-context.md create mode 100644 examples/spiral-reevaluation-flight-control.md create mode 100644 examples/stewardship-roman-concrete.md create mode 100644 examples/survey-retaining-wall-failure.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 100755 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..6decea2 --- /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 Refinement 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..83448ba --- /dev/null +++ b/LICENSE @@ -0,0 +1,32 @@ +Creative Commons Attribution 4.0 International (CC BY 4.0) + +Copyright (c) Open Engineer Project + +This work is licensed under the Creative Commons Attribution 4.0 +International License. + +You are free to: + + Share — copy and redistribute the material in any medium or format + Adapt — remix, transform, and build upon the material for any purpose, + even commercially + +Under the following terms: + + Attribution — You must give appropriate credit, provide a link to the + license, and indicate if changes were made. You may do so in any + reasonable manner, but not in any way that suggests the licensor + endorses you or your use. + + No additional restrictions — You may not apply legal terms or + technological measures that legally restrict others from doing + anything the license permits. + +The full text of the license is available at: +https://creativecommons.org/licenses/by/4.0/legalcode + +--- + +Note: Reference implementations produced during the Implementation Phase +may use a different license (e.g., Apache 2.0) to include patent grants +appropriate for software. This license covers the specification text. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100755 index 0000000..15a16cf --- /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/` | 20 examples across 9 disciplines and 11 conceptual areas | +| `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..b0fd988 --- /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. + +--- + +## Refinement Objective + +Reduce ambiguity without reducing meaning. + +Refinement is compression, not expansion. Every refinement should either eliminate ambiguity or strengthen traceability. + +--- + +## Refinement Exit Criteria + +Refinement 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/aerospace-thermal-protection.md b/examples/aerospace-thermal-protection.md new file mode 100644 index 0000000..5af382f --- /dev/null +++ b/examples/aerospace-thermal-protection.md @@ -0,0 +1,34 @@ +# Example: Atmospheric Entry Heat Shield Material Selection (Aerospace Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) in aerospace engineering where the decision must balance mass, structural integrity, thermal performance, and manufacturing timeline simultaneously, and where flight heritage from a previous mission provides a unique form of evidence that does not fit neatly into laboratory verification categories (OE-0007). + +## The Observation + +Arc-jet ground testing of a phenolic-impregnated carbon ablator material at heat flux levels simulating lunar-return atmospheric entry showed a controlled surface recession rate with the back-face temperature remaining well below the limit that would damage the underlying spacecraft structure. Published flight data from an earlier planetary return mission confirmed that this same material performed as predicted under actual re-entry conditions at even higher heating rates. A competing approach using individually fitted ceramic tiles would require over two thousand unique tile shapes for the heat shield surface, and a honeycomb-backed ablative alternative would add significant structural mass. The mission's own thermal analysis predicted a peak heating environment that was less severe than either the ground test conditions or the previous flight environment. + +## Engineering Translation + +Thermal protection for atmospheric entry is an exercise in managing energy flux so intense that it exceeds the melting or decomposition point of virtually every structural material. The engineering response is to accept that the outer surface will be consumed — ablated away — and design the system so that the rate of consumption is predictable and the remaining material continues to insulate the structure behind it. This is the fundamental concept of an ablative heat shield: it is a material whose destruction is its function. The selection among ablative materials, reusable ceramic systems, and hybrid approaches is therefore a trade between mass efficiency, structural robustness, manufacturing complexity, and the confidence that the material will behave as predicted in an environment that cannot be fully replicated on the ground. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Select phenolic impregnated carbon ablator (PICA) for the atmospheric entry heat shield of an Earth-return capsule, rather than reusable ceramic tiles or ablative AVCOAT. | +| **Observation** | (1) Arc-jet testing at 250 W/cm² (simulating lunar-return trajectory) showed PICA surface recession rate of 0.12 mm/s with back-face temperature remaining below 120°C at 40mm thickness. (2) Published flight data from the Stardust mission (NASA, 2006) confirmed PICA performance at cometary-return heating rates, which exceeded the Earth-return mission profile. (3) Internal thermal analysis of the mission profile predicted peak heat flux of 180 W/cm² for 220 seconds — a less severe environment than either the ground test or the Stardust flight heritage. (4) Ceramic tile approach assessment: a 4m diameter shield would require over 2,000 uniquely shaped tiles with precision fitting. (5) AVCOAT mass assessment: honeycomb substrate structure adds 8 kg/m² of structural mass compared to PICA's monolithic construction. | +| **Alternatives** | (A) Reusable ceramic tiles (LI-900) — rejected because the tiled architecture requires individual precision fitting to the heat shield curvature, producing an assembly of over 2,000 unique components that demands months of installation labor and results in a structurally fragile system. The tile-to-tile gaps create thermal bypass paths that require detailed gap-filling procedures, and the overall assembly cannot survive the structural loads of an ocean splashdown without significant additional reinforcement. (B) AVCOAT ablative — rejected because it requires a bonded honeycomb substrate structure that adds 8 kg/m² of parasitic structural mass. At equivalent thermal performance, PICA's monolithic construction is approximately 30% lighter, and the mass savings of 27 kg (from 85 kg AVCOAT to 58 kg PICA) is decisive against the 85 kg total mass budget when accounting for attachments and instrumentation. (C) PICA — selected. | +| **Constraints** | Total heat shield mass budget is 85 kg including all attachments, fasteners, and embedded sensors. The shield must survive a peak heat flux of 180 W/cm² sustained for 220 seconds. Back-face temperature must remain below 150°C to prevent degradation of the bonded aluminum substructure and the adhesive bond line. The assembly must withstand ocean splashdown loads of approximately 15g deceleration without debonding or structural failure. Manufacturing timeline from design freeze to delivery is limited to 6 months. | +| **Reasoning** | The selection rests on three converging lines of evidence (OE-0007). First, the material has demonstrated performance in actual flight at conditions more severe than the design environment — this is a stronger form of evidence than ground testing alone because it eliminates the uncertainty of whether the arc-jet environment faithfully represents the true entry environment. Second, the monolithic construction of PICA eliminates both the labor-intensive tile-fitting process and the honeycomb substrate mass penalty that penalize the competing approaches. Third, the 30% mass savings versus AVCOAT converts the heat shield from a mass budget driver to a system with margin, allowing accommodation of sensors and attachments without violating the mass constraint. The remaining risk is in manufacturing scale-up: producing a 4m-diameter monolithic part with uniform material properties is a different challenge than producing the smaller test panels that generated the performance database. | +| **Verification** | (1) Arc-jet testing at 1.3x design heat flux (234 W/cm²) for a duration of 286 seconds (30% beyond the design requirement) showed recession rate within 8% of the analytical model prediction, with back-face temperature peaking at 127°C — providing 23°C margin against the 150°C limit. (2) Vibration testing at qualification levels (14.1 grms random vibration) confirmed structural integrity of the bonded PICA-to-aluminum interface with no visible debonding. (3) Thermal-structural analysis of splashdown loads predicted maximum bond-line stress of 18 MPa against an allowable of 28 MPa, providing a 1.56x margin of safety. (4) Manufacturing pathfinder: a full-diameter demonstrator was produced within 5 months, confirming that the 6-month timeline is achievable with schedule margin. | +| **Lineage** | Builds on thermal protection system trade study CR-AERO-2022-011, which performed preliminary material screening across seven candidate systems and narrowed the field to PICA, AVCOAT, and ceramic tiles. Inherits the PICA material properties database and performance model from CR-AERO-2021-004, which analyzed post-flight data from the Stardust mission and validated the ablation recession model against recovered flight hardware. | +| **Assumptions** | The Earth-return trajectory heating environment is faithfully represented by the arc-jet test conditions, meaning that the combined effects of convective heating, radiative heating, and shear stress in the actual entry are not significantly different from what the arc-jet facility produces. No significant oxidation of the carbon substrate occurs below the char layer during the 220-second heating pulse — this is critical because substrate oxidation would reduce the structural integrity of the remaining heat shield. The adhesive bond between PICA and the aluminum substructure maintains integrity through the full thermal cycle from -40°C (space environment) to peak heating and back. Manufacturing at full diameter (4m) achieves material density and char yield equivalent to the 0.5m test panels — scale-dependent defects such as voids or density gradients are assumed to be controllable. | +| **Open Questions** | What is the minimum safe thickness margin if the actual entry trajectory deviates from the nominal profile due to navigation uncertainty or atmospheric variability? Can PICA be repaired or reapplied between flights for a reusable vehicle concept, or does the ablation mechanism inherently limit the material to single-use applications? At what heating rate does the char layer spallation risk become the binding design constraint rather than back-face temperature? | + +## Self-Fading Assessment + +This example builds a bridge from the abstract notion of material trade studies to the concrete realization that in extreme-environment engineering, the form of construction (monolithic versus tiled versus honeycomb-backed) can be as consequential as the material itself. The reader has crossed this bridge when they understand that flight heritage — actual performance in the target environment — is a category of evidence distinct from and complementary to ground testing, and that the selection among seemingly equivalent thermal protection materials is often decided by secondary factors like manufacturing complexity, structural integration, and mass rather than by the primary thermal performance metric alone. Once this pattern is internalized, the specifics of PICA, AVCOAT, and ceramic tiles become illustrative of a universal principle: the best-performing material on paper is not always the best system-level choice when integration, manufacturing, and operations are weighted alongside laboratory performance. \ 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 100755 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/chemical-process-catalyst.md b/examples/chemical-process-catalyst.md new file mode 100644 index 0000000..06cd988 --- /dev/null +++ b/examples/chemical-process-catalyst.md @@ -0,0 +1,34 @@ +# Example: Catalyst Selection for Aromatic Hydrogenation (Chemical Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) applied to a chemical process selection where the governing constraint is not performance but product purity, and where the physical form of the catalyst (heterogeneous vs. homogeneous) determines the feasibility of the entire downstream purification strategy (OE-0007). + +## The Observation + +Pilot-scale runs using a dissolved ruthenium catalyst system consistently produced product contaminated with residual ruthenium at concentrations of 12–18 ppm. The product specification for this pharmaceutical intermediate permits no more than 5 ppm of any residual metal. Separate bench-scale experiments using a solid palladium-on-carbon catalyst produced product with metal residue below the analytical detection limit of 0.1 ppm, and the reaction reached completion in less time. The dissolved catalyst system also required an additional liquid-liquid extraction step to attempt metal recovery, which added process complexity and generated additional waste streams. + +## Engineering Translation + +Catalyst selection in chemical process engineering is not solely a question of reaction rate or conversion. The physical nature of the catalyst — whether it dissolves in the reaction medium or remains as a distinct solid phase — creates cascading consequences for product purification, catalyst recovery, waste generation, and ultimately the economic viability of the process at production scale. The fundamental distinction here is between a catalyst that shares the same phase as the product (creating a separation problem) and one that does not (eliminating that problem entirely). This is an enduring concept in process design: the phase behavior of every component in the system determines the separation strategy, and the separation strategy often dominates the process economics. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Select a heterogeneous palladium-on-carbon (Pd/C) catalyst over homogeneous ruthenium and nickel alternatives for a commercial-scale hydrogenation of an aromatic nitro compound to the corresponding aniline. | +| **Observation** | (1) Pilot-scale runs (50L reactor, 200 hours cumulative) with homogeneous Ru/TPPTS catalyst showed product contamination from ruthenium leaching at 12–18 ppm, exceeding the 5 ppm specification for pharmaceutical intermediate. (2) Pd/C bench tests (1L, 40 hours) showed no metal leaching above detection limit (0.1 ppm) and faster reaction kinetics. (3) The homogeneous catalyst required aqueous extraction for attempted metal recovery, adding a process unit operation that did not exist in the heterogeneous pathway. | +| **Alternatives** | (A) Ru/TPPTS homogeneous — rejected due to metal leaching exceeding product specification and the introduction of an aqueous extraction step for catalyst recovery that increased process complexity and waste generation. (B) Raney nickel — rejected due to pyrophoric handling risk at production scale, which creates a safety engineering burden that is disproportionate to the cost savings, and lower selectivity producing 3.2% over-hydrogenation byproducts compared to 0.4% for Pd/C. (C) Pd/C — selected as the only option satisfying both the purity constraint and the selectivity constraint simultaneously. | +| **Constraints** | Product must meet pharmaceutical-grade purity with metal residue below 5 ppm (regulatory requirement). Hydrogenation must achieve 99.5% or greater selectivity to avoid costly downstream purification of over-hydrogenation byproducts. Catalyst must be recoverable and recyclable for a minimum of 10 cycles to meet the process economics model. Process temperature must remain below 80°C due to thermal sensitivity of downstream intermediates in the synthesis sequence. Production scale is a 2000L reactor, which changes the heat removal and filtration considerations relative to bench and pilot scale. | +| **Reasoning** | The core reasoning rests on the phase behavior distinction between heterogeneous and homogeneous catalysis (OE-0007). Pd/C provides heterogeneous catalysis in which the active metal remains physically bound to the carbon support throughout the reaction, eliminating the fundamental mechanism by which metal enters the product stream. This is not an incremental improvement in separation efficiency — it removes the separation problem entirely by ensuring the catalyst and product never share the same phase. The heterogeneous nature also simplifies catalyst recovery: filtration of a solid from a liquid is a mature, scalable unit operation, whereas recovering a dissolved metal from a complex organic mixture requires multi-step extraction with associated yield losses and waste streams. The observed selectivity advantage (0.4% vs. 3.2% byproducts) further reduces downstream purification burden, compounding the economic benefit. The trade-off is higher initial catalyst cost, which the recycle requirement (10+ cycles) amortizes to an acceptable per-batch cost. | +| **Verification** | (1) Scale-up run at 200L: 50-hour continuous operation produced product at 99.7% purity with metal residue below the ICP-MS detection limit of 0.1 ppm, confirming that the leaching advantage observed at bench scale persists at intermediate scale. (2) Catalyst recycling study: a 12-cycle test demonstrated activity retention above 95% of the initial conversion rate through cycle 10, declining to 91% at cycle 12, which exceeds the 10-cycle minimum requirement and suggests the economic model is valid. (3) Thermal profile of the 200L run confirmed a maximum exotherm of 62°C, remaining within the 80°C constraint with margin, indicating that heat removal at production scale is tractable. | +| **Lineage** | Builds on catalyst screening study CR-CHEM-2023-007, which evaluated eight catalyst candidates at bench scale and identified Pd/C, Ru/TPPTS, and Raney nickel as the three viable finalists. The reaction kinetics model developed in that study provided the basis for the 200L scale-up design and informed the thermal analysis. This context record extends that screening work to a production-scale selection decision. | +| **Assumptions** | Palladium supply chain remains stable at the projected production volumes of approximately 50 batches per year. The carbon support does not degrade under the combined chemical and mechanical environment of the reactor beyond the tested 12-cycle window, meaning that long-term catalyst performance at cycle 20 or beyond is extrapolated rather than demonstrated. Filtration at 2000L scale achieves separation efficiency equivalent to bench-scale filtration — this assumption carries risk because the filter cake properties and flow dynamics change significantly with scale. No catalyst poisoning occurs from trace impurities in the feedstock that were not present in the pilot-scale material, since the pilot feedstock came from a different supplier lot. | +| **Open Questions** | At what reactor scale does heat removal become the binding constraint rather than selectivity, and does the answer change the catalyst form factor preference? Can the Pd/C catalyst be regenerated in-situ through a reductive treatment step, or does it require external reactivation that would interrupt production and add logistics complexity? | + +## Self-Fading Assessment + +This example builds a bridge from the abstract concept of heterogeneous versus homogeneous catalysis to the concrete consequence that phase behavior determines separation strategy, and separation strategy often dominates process economics. The reader has crossed this bridge when they can look at any mixed-phase reaction system and immediately identify which component is in which phase, what separation that implies, and whether that separation is a routine unit operation or an unsolved problem. Once this pattern is recognized, the specific details of palladium, ruthenium, and the nitro-to-aniline chemistry become incidental — the underlying principle of phase-determined separability applies equally to leaching, extraction, crystallization, and distillation decisions across all of chemical engineering. \ 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/construction-siting-environmental.md b/examples/construction-siting-environmental.md new file mode 100644 index 0000000..32437fd --- /dev/null +++ b/examples/construction-siting-environmental.md @@ -0,0 +1,44 @@ +# Example: Facility Siting and Construction Form Driven by Subsurface Conditions (Civil Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) applied to a construction siting and methodology decision where the governing constraints were not visible at the site surface and were discovered only through targeted investigation, illustrating how environmental conditions that are "unseen" — subsurface, hydrological, climatic — can override every other siting factor (OE-0004, OE-0007). + +## The Observation + +A regional logistics facility was planned for a 12-hectare greenfield site adjacent to a highway interchange in a semi-arid region. The site scored highest on every surface-level criterion: highway access, proximity to the target delivery radius, land cost, and zoning availability. A preliminary geotechnical investigation (two boreholes to 6m depth) confirmed competent bearing capacity for conventional spread footings. Construction began with conventional slab-on-grade foundations and a steel-framed structure. + +During excavation for the stormwater detention basin at the northwest corner of the site, the excavation contractor encountered a layer of expansive clay (plasticity index of 52, well above the 35 threshold for high-expansiveness) beginning at 2.1m depth and extending to at least 8m — the limit of the excavation. This clay had not been encountered in the preliminary boreholes because both were located in the southeastern portion of the site, where the clay layer was absent. Subsequent investigation (six additional boreholes, two to 15m depth) revealed that the expansive clay underlay approximately 60% of the site in an irregular lobe, with thickness varying from 1.5m to over 9m. + +The expansive clay meant that conventional slab-on-grade foundations — already under construction on the southeastern portion — would experience differential heave as the clay absorbed moisture from seasonal rainfall and landscape irrigation. Predicted heave ranged from 25mm to over 100mm across the affected area. A structure built on a slab resting on this clay would crack as different parts of the foundation moved at different rates. + +## Engineering Translation + +This case demonstrates a category of engineering constraint that is fundamentally different from the constraints typically documented in design specifications. Surface-level constraints — load, span, clearance, access — are visible and can be assessed during initial site evaluation. Subsurface and environmental constraints are invisible until specifically investigated, and the investigation must be targeted at the right locations and depths to find them. The preliminary geotechnical investigation satisfied the minimum standard for the project type (two boreholes), but those two boreholes happened to miss the expansive clay lobe entirely. The constraint was real, binding, and present from the beginning — but it was unknown because the observation had not been made at the right location. + +The decision that follows is not about whether to address the clay (that is mandatory) but about how, and the "how" has consequences that cascade through the entire construction methodology, schedule, and cost. Each alternative carries a different combination of cost, timeline impact, and long-term risk, and selecting among them requires understanding not just the clay's properties but the project's tolerance for schedule delay and budget overruns. The engineering context record for this decision must preserve not just what was decided but what was unknown at the time of the initial site selection and how that unknown was discovered — because a future facility on a similar site needs to understand that minimum-standard geotechnical investigations carry a risk of missing subsurface conditions that are later found to be the binding constraint on the entire project. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Adopt a post-tensioned slab-on-grade foundation with moisture barriers for the expansive clay zone and conventional spread footings with reinforced slab for the non-expansive zone, with a structural transition beam at the clay boundary. Continue steel-framed construction but modify the stormwater management system to prevent surface water infiltration into the clay zone. Relocate the detention basin 40m east to a non-expansive area identified in the supplemental investigation. | +| **Observation** | (1) Expansive clay encountered at 2.1m depth during detention basin excavation, with plasticity index of 52 (highly expansive per ASTM D4829). (2) Supplemental borehole investigation (8 boreholes, 2 to 15m depth) delineated the clay lobe covering approximately 60% of the site with thickness varying from 1.5m to over 9m. (3) Laboratory swell testing (ASTM D4546) on undisturbed samples showed free swell pressures of 180–340 kPa and vertical swell strains of 3.2–6.8% at the anticipated foundation bearing stress. (4) Seasonal moisture monitoring probes installed over 6 months showed moisture content variation from 18% (dry season) to 31% (wet season) in the clay zone at 2m depth, confirming active seasonal heave potential. (5) The preliminary boreholes (both in the southeastern 40% of the site) were in areas free of expansive clay — the clay was not missed due to insufficient depth but due to insufficient spatial coverage. | +| **Alternatives** | (A) Deep foundations (driven piles or drilled shafts) to bypass the clay entirely — rejected: pile installation to competent bearing below the clay (estimated 12–18m depth) would cost approximately $2.8M for the affected area, compared to $900K for the post-tensioned slab solution. Additionally, the pile caps and grade beams would require significant excavation in the clay zone during construction, exposing the clay to moisture and triggering heave during the construction period itself. (B) Excavate and replace the clay with engineered fill — rejected: the clay extends to over 9m in the thickest areas, requiring excavation and replacement of approximately 180,000 cubic meters of material. The nearest suitable fill source is 35km away, making the haulage cost alone approximately $4.1M. The construction timeline impact (estimated 4-month delay for excavation, hauling, and compaction) would breach the occupancy deadline. (C) Chemical stabilization of the clay in situ using lime treatment — rejected: laboratory testing showed that lime treatment reduced the plasticity index from 52 to approximately 28 (moderately expansive), which was insufficient to eliminate differential heave risk. Achieving non-expansive results would require lime treatment to depths of 4–5m, which is beyond the practical reach of standard mix-in-place methods and would require pressure-injected lime slurry at significantly higher cost than the post-tensioned slab. (D) Relocate the facility to an alternative site — rejected: the alternative sites scored significantly lower on access and proximity criteria, and the land acquisition process would add 8–12 months to the project timeline. The cost of relocating (land premium, design restart, permitting) was estimated at $3.5M plus the sunk cost of the partially completed foundations. (E) Post-tensioned slab with moisture barriers and modified construction methodology — selected. | +| **Constraints** | The facility must achieve occupancy by the contractual deadline (14 months from notice to proceed, now 10 months remaining due to the investigation delay). The foundation solution must control differential heave to less than 15mm across any 12m span to prevent structural distress in the steel frame and rack systems. Construction in the clay zone must minimize moisture intrusion during the construction period — the clay cannot be allowed to swell before the building mass and slab are in place. The stormwater management system must prevent concentrated surface water from infiltrating the clay zone for the 50-year design life. Total foundation cost increase (including the investigation, redesign, and modified construction) must remain below $1.5M to preserve project economics. | +| **Reasoning** | The post-tensioned slab solution works by placing the slab in permanent compression, which counteracts the tensile stresses that expansive clay heave would otherwise induce in the foundation. The slab does not prevent the clay from swelling — it prevents the swelling from damaging the structure by resisting the upward force with pre-compression. The moisture barrier (horizontal polyethylene membrane beneath the slab with vertical barriers extending 1.5m depth around the perimeter) reduces the moisture variation that drives seasonal heave, cutting the predicted heave from 25–100mm to 8–18mm — within the 15mm differential limit for the post-tensioned slab's capacity. The structural transition beam at the clay boundary accommodates the differential movement between the expansive and non-expansive zones without transferring stress from one zone to the other. The solution costs $900K (including moisture barriers, transition beam, and supplemental investigation) against the $2.8M deep foundation and $4.1M excavation-and-replace alternatives. It preserves the schedule because post-tensioned slab construction is a well-understood process that the contractor can execute without specialized equipment or extended lead times. The trade-off is that the post-tensioned slab requires careful attention to tendon placement and stressing sequence, and the moisture barriers must remain intact for the building's life — any breach of the moisture barrier during future utility work or landscaping changes could reactivate the heave mechanism. | +| **Verification** | (1) Post-construction level survey monitoring over 24 months (quarterly surveys at 48 monitoring points) showed maximum differential heave of 11mm across a 12m span, within the 15mm design limit. Seasonal heave amplitude averaged 6mm, consistent with the moisture barrier's predicted 70% reduction in moisture variation. (2) Tendon elongation measurements during post-tensioning confirmed that all tendons achieved design force within 3% tolerance. (3) Visual inspection at 12 and 24 months showed no structural cracking in the slab, transition beam, or steel frame connections in the clay zone. (4) Moisture probe readings at 2m depth showed seasonal variation reduced from 13 percentage points (pre-construction) to 4 percentage points (post-construction with moisture barriers), confirming the barrier's effectiveness. (5) Relocated detention basin excavation confirmed competent non-expansive soils at the new location, validated by two confirmation boreholes. | +| **Lineage** | Builds on the initial site selection and geotechnical assessment (CR-CIV-2022-001, "Distribution center site selection — Highway 41 interchange"). That record documented the preliminary two-borehole investigation and the selection of conventional spread footings based on the observed bearing capacity. The present record extends that lineage by documenting the discovery that the preliminary investigation had insufficient spatial coverage, the conditions that were missed, and the reasoning behind the revised foundation system. The structural design of the steel frame and the building layout from CR-CIV-2022-001 are inherited without modification — only the foundation and stormwater systems changed. | +| **Assumptions** | The moisture barriers will remain intact for the 50-year design life without degradation from soil chemistry, root penetration, or construction activity. The post-tensioned tendons will not experience corrosion within the slab (the tendons are greased and sheathed, but long-term durability in expansive clay environments has a shorter track record than in non-expansive soils). The clay lobe's boundaries are accurately delineated by the 8 supplemental boreholes — the actual boundary may be more complex than the interpolated surface. Future construction on the site (utility trenches, landscape grading) will respect the moisture barrier perimeter and will not create new moisture infiltration paths into the clay zone. The seasonal moisture variation observed during the 6-month monitoring period is representative of long-term behavior — an unusually wet multi-year period could produce greater heave than predicted. | +| **Open Questions** | What is the minimum borehole density required to reliably detect subsurface conditions of this type on sites of similar size? Should the project's geotechnical investigation standard be revised for future sites to require boreholes at a maximum spacing rather than a minimum count? At what point does the cumulative cost of post-tensioned slab maintenance (barrier inspection, tendon monitoring) exceed the lifecycle cost of deep foundations that bypass the clay entirely? | + +## Why This Is Different From the Bridge Example + +The bridge example (bridge-survey.md) demonstrates a context record where all relevant conditions were known at the time of the decision. This example demonstrates a context record where the binding constraint was unknown at the time of the initial decision and was discovered during construction. The context record must therefore preserve not only the final decision but the sequence of discovery: what was assumed, what was observed that contradicted the assumption, and how the decision was revised in response. This is a more complex form of engineering reasoning — it includes a correction — and it is precisely the form of reasoning that is most frequently lost when only the final design is documented. A future engineer who sees only the post-tensioned slab specification without the context record cannot reconstruct why that specification exists, what it replaced, or what conditions would make the original spread footing design correct for a different site. + +## Self-Fading Assessment + +This example builds a bridge from the abstract principle that "engineering decisions are shaped by constraints" to a concrete case where the binding constraint was invisible at the site surface and was discovered only after construction had begun. The reader has crossed this bridge when they recognize that the reliability of any engineering decision is limited by the completeness of the observations on which it is based — and that a context record must preserve not only the final decision but the sequence of discovery that led to it, including what was initially unknown. When that recognition is stable and the reader can identify the same pattern in their own work (decisions revised when previously unknown conditions are discovered), this example has served its purpose and can be set aside. \ No newline at end of file diff --git a/examples/electrical-grounding-architecture.md b/examples/electrical-grounding-architecture.md new file mode 100644 index 0000000..95d7f1d --- /dev/null +++ b/examples/electrical-grounding-architecture.md @@ -0,0 +1,34 @@ +# Example: Hybrid Grounding Topology for Mixed-Signal Facilities (Electrical Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) applied to an electrical grounding architecture decision, illustrating how conflicting requirements — measurement precision and personnel safety — are resolved through topology selection and how the reasoning captures the essential trade-off. + +## The Observation + +An electromagnetic compatibility site survey of a facility housing both precision measurement instrumentation and high-power switching equipment revealed ground bus potential differences of 2.3 volts peak-to-peak between the measurement laboratory and the power switching room during normal switching transients. These potential differences correlated directly with periodic measurement offsets of 0.4% in precision instruments — four times the instrument accuracy specification of 0.1%. Ground impedance testing further showed that the existing common-ground network exhibited 0.8 ohm impedance at 50 Hz but 12 ohms at 10 MHz, demonstrating that the long conductor runs (45 meters) introduced inductance that rendered the network ineffective as an equipotential reference at the frequencies generated by switching transients. Benchmarking of three comparable facilities confirmed that isolating the measurement signal reference from the power ground eliminated switching-induced measurement offsets entirely. + +## Engineering Translation + +Grounding architecture in facilities with mixed equipment types is fundamentally a problem of managing conflicting requirements on a shared conductive network. The safety ground must carry fault currents — high-magnitude, low-frequency events — and must maintain equipotential bonding to prevent hazardous touch voltages. The signal reference ground must maintain a stable potential with minimal noise — low-magnitude, high-frequency events — to preserve measurement accuracy. A single network optimized for one requirement inherently degrades the other: a low-impedance safety ground uses large conductors and multiple bonding points that create ground loops for sensitive signals, while an isolated signal reference can develop hazardous potential differences from the safety ground during fault conditions. The engineering challenge is to satisfy both requirements simultaneously, which in this case required a hybrid topology that physically separates the two functions while maintaining a controlled equipotential bond for safety. This reasoning must be preserved because a future modification to the facility — adding equipment, rerouting conductors, or changing the fault protection scheme — could unintentionally defeat the single-point bond discipline that makes the hybrid topology function correctly (OE-0007). + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Implement a hybrid grounding topology combining an isolated signal reference plane with an equipotential bonding network for a facility housing both sensitive measurement instrumentation and high-power switching equipment. | +| **Observation** | (1) Electromagnetic compatibility (EMC) site survey showed ground bus potential differences of 2.3V peak-to-peak between the measurement laboratory and the power switching room during normal switching transients, correlating with periodic measurement offsets of 0.4% in precision instruments. (2) Ground impedance testing of the existing common-ground network showed 0.8 ohm at 50 Hz rising to 12 ohms at 10 MHz due to the inductance of the 45m grounding conductor runs. (3) Benchmarking three comparable facilities: Facility A (isolated reference) reported zero switching-induced measurement offsets; Facility B (single-point ground) reported 0.1% offsets; Facility C (common ground, similar to current installation) reported 0.5% offsets. | +| **Alternatives** | (A) Maintain single common ground network — rejected: the observed 0.4% measurement offsets exceed the 0.1% instrument accuracy specification, and the ground impedance at higher frequencies (12 ohms at 10 MHz) indicates the existing network cannot provide adequate equipotential bonding for fault conditions. (B) Fully isolated grounding (separate grounds for measurement and power) — rejected: during a ground fault on the power side, the potential difference between the isolated measurement ground and true earth could exceed safe touch-voltage limits (50V AC per IEEE 80), creating a personnel safety hazard. (C) Hybrid topology (isolated signal reference + equipotential bond) — selected. | +| **Constraints** | Measurement instruments require ground-referenced signal stability better than 0.1% of full scale. Personnel safety must comply with IEEE 80 (touch voltage below 50V AC during fault conditions). Lightning protection requires a common earth reference with impedance below 1 ohm at 25 kHz. Installation must be completed during a 2-week facility shutdown. No structural modifications to the concrete-encased grounding electrode system. | +| **Reasoning** | The hybrid topology separates the signal reference (which must be quiet) from the safety ground (which must carry fault current) while maintaining them at the same potential through a controlled bonding point. The isolated signal reference plane eliminates the 2.3V switching transient observed on the common ground. The equipotential bonding network — connected to the signal reference through a single-point bond at the facility entrance — ensures that fault conditions cannot create hazardous touch voltages. The measured ground impedance of 12 ohms at 10 MHz on the existing common ground becomes irrelevant because high-frequency currents from switching transients no longer flow through the measurement reference path. The trade-off is design complexity: the single-point bond must be carefully located and maintained, and any accidental multiple bonding defeats the isolation. | +| **Verification** | (1) Post-installation EMC survey: ground potential difference between measurement lab and switching room during switching transients measured at 0.03V peak-to-peak (below the 0.1% instrument accuracy threshold). (2) Fault simulation: injected fault current of 1000A through the power grounding network produced touch voltage of 8V at the measurement laboratory (below the 50V IEEE 80 limit). (3) Lightning impulse testing (8/20 µs waveform, 20kA) showed equipotential bonding network maintained potential difference below 2V across all bonded points. (4) Instrument accuracy verification: precision measurement instruments operated within 0.02% of nominal across 72 hours of concurrent power switching operations. | +| **Lineage** | Builds on EMC site survey SS-ELEC-2023-008 (grounding system assessment). Extends the grounding architecture analysis from CR-ELEC-2023-012 (conceptual design for three candidate topologies). Inherits the facility grounding electrode characterization from CR-ELEC-2021-005 (initial facility commissioning). | +| **Assumptions** | The single-point bond location (facility entrance) remains the optimal point for the installed equipment layout. No future equipment additions will require grounding connections that violate the single-point bond discipline. The impedance characteristics of the bonding conductors remain stable over the 20-year design life (corrosion, thermal cycling). The facility's concrete-encased electrode system maintains below-1-ohm impedance at 25 kHz without reinforcement (verified at commissioning but not re-tested annually). | +| **Open Questions** | What periodic verification is required to confirm the single-point bond has not been accidentally compromised by maintenance activities? At what frequency does the equipotential bonding network's inductance begin to degrade the lightning protection performance? | + +## Self-Fading Assessment + +This example builds a bridge from the context record structure (OE-0003) to the domain of facility-level electrical architecture, where the central challenge is resolving conflicting requirements through topology rather than component selection. The reader has crossed this bridge when they recognize that the Reasoning field in this context record is not arguing for a specific component but for a specific *relationship* between subsystems — and that preserving that relationship over the facility's life is the critical engineering obligation (OE-0007). Once the reader can examine any grounding or bonding architecture decision and instinctively ask "what breaks if someone adds a connection here," this example has served its purpose. \ No newline at end of file diff --git a/examples/environmental-remediation.md b/examples/environmental-remediation.md new file mode 100644 index 0000000..d9c85b1 --- /dev/null +++ b/examples/environmental-remediation.md @@ -0,0 +1,34 @@ +# Example: Groundwater Remediation Technology Selection (Environmental Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) in environmental engineering where the decision must satisfy regulatory timelines, budget constraints, site-specific geological conditions, and ecological protection requirements simultaneously, and where the consequence of a wrong selection is measured in years of delayed compliance rather than in dollars alone (OE-0007). + +## The Observation + +Groundwater monitoring at an industrial site revealed tetrachloroethylene contamination at concentrations more than two orders of magnitude above the regulatory maximum contaminant level. The contaminated aquifer is a silty sand formation at moderate depth with measurable hydraulic conductivity, meaning the contamination is mobile but treatable. Laboratory studies using soil and groundwater from the site showed that a chemical oxidation approach destroyed 94% of the contaminant within 72 hours, while the site's native microbial community achieved only 38% destruction over 180 days. The microbial community also lacked the specific organisms needed for complete dechlorination, and augmenting the population would add months to the project timeline. + +## Engineering Translation + +Environmental remediation decisions are constrained by regulatory timelines that operate on a different clock than typical engineering projects: a regulatory agency sets a deadline for achieving compliance, and missing that deadline triggers enforcement actions, penalties, or both. This external time constraint means that the fastest technically viable approach is often preferred over approaches that might be cheaper in the long run but slower to achieve results. The site's geological characteristics — the type of soil, the depth to groundwater, the permeability of the aquifer — determine which remediation technologies are physically feasible, and these characteristics are fixed by nature rather than selectable by the engineer. The engineering task is to match the available technologies to the site conditions and the regulatory timeline, then optimize within that constrained solution space. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Select in-situ chemical oxidation (ISCO) using sodium persulfate activated by sodium hydroxide for remediation of a chlorinated solvent groundwater plume, rather than pump-and-treat or enhanced bioremediation. | +| **Observation** | (1) Site investigation: groundwater monitoring wells showed tetrachloroethylene (PCE) concentrations ranging from 1,200 to 4,800 µg/L in the source zone, exceeding the regulatory maximum contaminant level (MCL) of 5 µg/L by over two orders of magnitude. (2) Soil borings confirmed a silty sand aquifer at 8–15m depth with hydraulic conductivity of 4.2 × 10⁻⁴ m/s, which is within the treatable range for ISCO injection but too permeable for effective containment by pump-and-treat alone. (3) Laboratory microcosm studies using site soil and groundwater showed persulfate achieving 94% PCE destruction within 72 hours at the proposed activation pH, compared to 38% destruction by native bioremediation over 180 days. (4) Quantitative polymerase chain reaction (qPCR) analysis measured the native dehalococcoides population at 10² copies/mL, well below the 10⁵ copies/mL threshold established in the literature for effective reductive dechlorination to ethene. | +| **Alternatives** | (A) Pump-and-treat with granular activated carbon — rejected because at the observed hydraulic conductivity and plume geometry, groundwater flow and transport modeling predicted 12 to 18 years of continuous operation to achieve the MCL at all monitoring points. The present-value cost of 15 years of operation, energy, and carbon replacement exceeded the ISCO capital cost by a factor of approximately four. Pump-and-treat also creates a secondary waste stream (spent activated carbon) requiring disposal or reactivation. (B) Enhanced in-situ bioremediation (EISB) with electron donor injection — rejected because the microcosm study demonstrated only 38% degradation in 180 days, which is incompatible with the 5-year regulatory timeline. The aquifer's native microbial community lacks sufficient dehalococcoides population, and bioaugmentation to raise populations to the effective threshold was estimated to add 8 months to the project timeline while introducing uncertainty about whether the introduced organisms would survive and proliferate under site conditions. (C) ISCO with activated persulfate — selected. | +| **Constraints** | Regulatory requirement to achieve MCL compliance (5 µg/L PCE) within 5 years from remedy selection. The site is an active industrial facility, so surface disruption must be minimized — no excavation or large-scale surface infrastructure is permitted. Groundwater pH must not be permanently altered below 6.0 or above 9.0 to protect downgradient ecological receptors in a adjacent wetland. Total remediation budget is $2.1M including design, implementation, and five years of performance monitoring. No residual treatment chemicals may migrate beyond the property boundary at concentrations exceeding secondary drinking water standards. | +| **Reasoning** | The selection is driven by the intersection of three constraints: the 5-year regulatory timeline, the site geology, and the budget (OE-0007). ISCO with activated persulfate addresses the source zone directly — destroying the contaminant in place — rather than treating dissolved-phase contamination at a downgradient capture point, which is the fundamental limitation of pump-and-treat. The 94% destruction efficiency in 72 hours, demonstrated in site-specific laboratory conditions, provides high confidence that the source zone can be treated within the regulatory timeline, whereas the bioremediation pathway's 38% destruction in 180 days leaves no margin for the slower-than-predicted degradation rates that commonly occur in field implementations. The chemical oxidation approach is independent of the aquifer's microbial community, which eliminates the bioaugmentation risk entirely. The cost advantage — approximately $1.3M for ISCO versus $5.2M present value for pump-and-treat — provides significant budget margin for the required five-year performance monitoring program and for contingency if a second injection event proves necessary. | +| **Verification** | (1) Bench-scale treatability study using site soil and groundwater confirmed 94% PCE destruction at site-representative conditions, with the reaction following pseudo-first-order kinetics. (2) Pilot-scale injection using three injection points treating a 30m³ volume showed 89% concentration reduction in the treatment zone within 14 days. Rebound monitoring at 30 days post-injection showed 91% net concentration reduction, confirming that the destruction was permanent rather than a temporary mobilization effect. (3) Post-injection pH monitoring confirmed that groundwater pH returned to 7.2 (ambient is 7.0–7.4) within 21 days of injection, satisfying the pH constraint with margin. (4) Downgradient monitoring wells at the property boundary showed no persulfate migration above the analytical detection limit of 0.5 mg/L, confirming that the injected reagent was consumed within the treatment zone. | +| **Lineage** | Builds on site characterization report SC-ENV-2023-015, which delineated the plume extent, characterized the aquifer geometry and hydraulic properties, and established the baseline contamination levels. Extends the remedial technology screening from CR-ENV-2023-019, a feasibility study that evaluated six remediation alternatives (pump-and-treat, air sparging, ISCO with permanganate, ISCO with persulfate, enhanced bioremediation, and monitored natural attenuation) against the site-specific constraints and narrowed the field to the three alternatives considered in this record. | +| **Assumptions** | The source zone delineated by the investigation is the primary contributor to the plume, and no dense non-aqueous phase liquid (DNAPL) pools exist below the investigation depth of 15m. DNAPL presence would dramatically increase the oxidant demand and could render ISCO ineffective without additional characterization and treatment. The aquifer's geochemistry — specifically the natural organic carbon content and alkalinity — does not create excessive persulfate demand beyond what was measured in the microcosm study, where site soil and groundwater were used. The regulatory framework and MCL values of 5 µg/L for PCE remain unchanged through the 5-year remediation period; regulatory tightening would require re-evaluation of the remedy. The pilot-scale injection results (89–91% reduction) scale predictably to the full source-zone treatment volume. | +| **Open Questions** | How many injection events are required to achieve sustained MCL compliance at all monitoring points, given that the pilot showed 91% reduction rather than the 94% achieved in the bench-scale study? What is the optimal injection point spacing for full source-zone coverage given the observed hydraulic conductivity of 4.2 × 10⁻⁴ m/s, and does anisotropy in the aquifer require closer spacing in one direction? What is the long-term fate of the oxidation byproducts (chloride, sulfate) in the groundwater system, and do they approach concentrations of concern for downgradient receptors over multiple injection events? | + +## Self-Fading Assessment + +This example builds a bridge from the abstract context record structure to the concrete reality that environmental engineering decisions are uniquely constrained by external regulatory timelines and immovable geological conditions. The reader has crossed this bridge when they recognize that in remediation engineering, the fastest feasible technology is often the correct choice not because speed is inherently valuable but because the regulatory clock creates a hard deadline that converts a time preference into a hard constraint. Once this principle is understood — that external non-engineering stakeholders (regulatory agencies, property owners, ecosystems) impose constraints that are as real and as binding as the laws of physics — the specifics of persulfate chemistry, dehalococcoides populations, and pump-and-treat hydraulics become illustrations of a universal pattern: the engineer's task is to identify the binding constraint and solve for it, even when that constraint originates outside the technical domain. \ No newline at end of file diff --git a/examples/inheritance-steelmaking.md b/examples/inheritance-steelmaking.md new file mode 100644 index 0000000..d3aa780 --- /dev/null +++ b/examples/inheritance-steelmaking.md @@ -0,0 +1,28 @@ +# Example: Inheritance in Steelmaking + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Inheritance — the receive discipline (OE-0010). The difference between passive reception of an artifact and active engagement with inherited engineering reasoning. + +## The Observation + +In 1856, Henry Bessemer patented a process for mass-producing steel by blowing air through molten pig iron. The process produced steel quickly and cheaply but initially produced brittle steel because it removed too much carbon without controlling nitrogen absorption from the air. Robert Mushet addressed this by adding spiegeleisen (an iron-manganese alloy) to deoxidize the steel, producing usable material. Later, Sidney Gilchrist Thomas and Percy Gilchrist discovered that adding a basic lining (dolomite) to the converter allowed the process to work with phosphoric iron ores — a problem that had limited Bessemer's process to low-phosphorus ores. Each of these advances built directly on the prior one, but each also required the inheritor to do more than simply replicate what they had received. + +## Engineering Translation + +Each advance in the Bessemer process lineage required active inheritance — not passive reception. Bessemer's original patent contained no context record explaining why air injection worked, what failure modes to expect, or what constraints bounded the process. Mushet did not simply use Bessemer's process as-is; he inherited it by engaging with its failure mode (brittleness) and reconstructing the reasoning (nitrogen absorption) to develop a solution. He could not have done this passively — he had to engage with the process, observe its failure, form a hypothesis about the cause, and test a remedy. The same pattern repeated with Thomas and Gilchrist: they inherited the now-functional Bessemer-Mushet process and engaged with a different constraint (phosphorus content of available iron ores) that Bessemer had not encountered because his local ores happened to be low-phosphorus. Inheritance, in the OE sense, is not a file transfer — it is the active reconstruction of reasoning from what has been received (OE-0010). + +## Active vs. Passive Inheritance + +The Bessemer process also demonstrates passive inheritance failures. Early adopters who implemented the process without understanding the nitrogen problem produced brittle steel and concluded the process was unreliable — a failure of inheritance, not of the process itself. They received the artifact (the process specification) without engaging with its reasoning (why the brittleness occurred, under what conditions the process was valid, what its constraints were). Some early licensees went bankrupt pursuing a process they had received but not understood. Bessemer himself struggled to produce consistent results initially, and his public demonstrations were criticized for producing steel of unpredictable quality. The process was not flawed; the inheritance was. Conversely, Mushet and Thomas-Gilchrist succeeded because they engaged with the inherited knowledge, identified its constraints and failure modes, and extended it. Mushet's spiegeleisen addition and the Thomas-Gilchrist basic lining were not new inventions from scratch — they were extensions of inherited reasoning, made possible only because the inheritors had actively engaged with what they received rather than merely deploying it. + +## Lineage Chain + +Each advance built on the prior one: Bessemer to Mushet (deoxidation via spiegeleisen) to Thomas-Gilchrist (basic lining for phosphoric ores). This is the thread made concrete: each practitioner could reconstruct the reasoning of the prior advance because each advance was itself a contextualized response to an observed failure mode. Mushet's contribution was legible to Thomas-Gilchrist because it contained, implicitly if not explicitly, the reasoning chain: Bessemer's process removed carbon effectively but introduced nitrogen, so Mushet added manganese to scavenge oxygen and nitrogen, which produced sound steel — but the acidic silica lining still prevented removal of phosphorus, which meant the process was limited to certain ore sources. Each step in the chain was a record of reasoning that the next inheritor could engage with. The chain only worked because each inheritor actively engaged with what they received, treating the inherited artifact not as a finished product but as a starting point for further reasoning. This is the receive discipline in practice: inheritance is not adoption, it is engagement (OE-0010). + +## Self-Fading Assessment + +This example builds a bridge from the abstract concept of "active inheritance" to a concrete historical case where the difference between passive reception and active engagement determined whether practitioners succeeded or failed. The reader has crossed the bridge when they can distinguish between the early licensees who went bankrupt (passive inheritance) and Mushet or Thomas-Gilchrist who extended the process (active inheritance) — and when they recognize that the same distinction applies to how they receive and engage with inherited engineering work in their own practice. Once that distinction is stable, the steelmaking example has served its purpose and can be set aside. \ No newline at end of file diff --git a/examples/manufacturing-joining-process.md b/examples/manufacturing-joining-process.md new file mode 100644 index 0000000..181309b --- /dev/null +++ b/examples/manufacturing-joining-process.md @@ -0,0 +1,35 @@ +# Example: Friction Stir Weld Selection for Marine Aluminum Joints (Manufacturing Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) applied to a manufacturing process selection decision, illustrating how physical test observations, trade-offs between joining methods, and production constraints are captured in a preserved engineering record (OE-0007). + +## The Observation + +Fatigue testing of gas metal arc welded joints in marine-grade aluminum alloy 5083-H321 showed a fatigue strength reduction factor of 0.45 at ten million cycles relative to base material, with weld toe stress concentration and heat-affected zone grain growth identified as the primary mechanisms. Salt spray corrosion testing revealed preferential galvanic corrosion at the weld fusion boundary due to microsegregation of magnesium-rich phases. Preliminary solid-state joining trials on the same material produced joints with a fatigue strength reduction factor of 0.78 and no detectable preferential corrosion in the weld zone. + +## Engineering Translation + +Joining process selection in structural manufacturing is governed by the interaction between the process mechanics and the material's metallurgical response. A fusion welding process introduces a liquid-to-solid transformation that creates microstructural gradients — heat-affected zones with altered grain structures and fusion boundaries with compositional segregation. These gradients become preferential sites for both fatigue crack initiation and electrochemical corrosion attack. A solid-state joining process avoids the liquid phase entirely, preserving the base material's microstructure and eliminating the fusion-boundary corrosion pathway. The engineering decision therefore hinges on whether the performance advantage of the solid-state process justifies the investment in specialized tooling and the operational constraints it introduces. This reasoning must be preserved because a future engineer evaluating a similar joint in a different alloy or environment needs to understand not just what was chosen but why the fusion-welding mechanisms were dominant failure drivers in this specific material system. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Select friction stir welding (FSW) over gas metal arc welding (GMAW) and riveted construction for longitudinal stiffener-to-skin joints in a marine-grade aluminum alloy (5083-H321) structure. | +| **Observation** | (1) Fatigue testing of GMAW joints in 5083-H321 showed a fatigue strength reduction factor of 0.45 at 10⁷ cycles relative to the base material, attributed to weld toe stress concentration and heat-affected zone grain growth. (2) Corrosion testing per ASTM B117 (salt spray, 1000 hours) revealed preferential galvanic corrosion at the weld fusion boundary of GMAW joints due to microsegregation of magnesium-rich phases. (3) Preliminary FSW trials on 8mm 5083-H321 produced joints with fatigue strength reduction factor of 0.78 at 10⁷ cycles and no detectable corrosion preferential to the weld zone. | +| **Alternatives** | (A) Gas metal arc welding (GMAW) — rejected: 55% fatigue strength reduction relative to base material, heat-affected zone corrosion susceptibility, and distortion requiring post-weld rework on 40% of production joints. (B) Riveted construction — rejected: rivet holes act as stress concentrators (fatigue reduction factor 0.52 at 10⁷ cycles), added sealing requirements for watertightness, and 35% higher assembly labor. (C) Friction stir welding — selected. | +| **Constraints** | Joint must achieve fatigue life exceeding 10⁷ cycles at design stress range of 85 MPa. Structure must resist marine atmospheric corrosion for 25-year service life without coating in the weld zone. Maximum allowable distortion is 1.5mm over a 3m stiffener run. Production rate requires completion of one 3m longitudinal joint in under 15 minutes. Material is 8mm 5083-H321 aluminum alloy plate. | +| **Reasoning** | FSW is a solid-state joining process — the material does not melt, eliminating the fusion-zone microsegregation and heat-affected zone grain growth that drive both the fatigue reduction and corrosion susceptibility of GMAW. The observed fatigue strength of 0.78 (versus 0.45 for GMAW and 0.52 for riveted) directly translates to either a lighter structure for the same fatigue life or a longer service life for the same structural mass. The absence of a fusion zone eliminates the galvanic corrosion pathway entirely. The process is repeatable and produces consistent properties — reducing the 40% rework rate observed with GMAW to near zero in preliminary trials. | +| **Verification** | (1) Full-scale fatigue testing of a representative 3m stiffened panel (4 stiffeners, FSW-joined) survived 2 × 10⁷ cycles at design stress range with no crack initiation detected by eddy-current inspection at 1 × 10⁶ cycle intervals. (2) Salt spray testing (ASTM B117, 2000 hours) of FSW joints showed no preferential corrosion — corrosion rate in the weld zone was equivalent to base material (0.02 mm/year). (3) Dimensional inspection of 50 production joints showed maximum distortion of 0.8mm over 3m (within the 1.5mm constraint). (4) Cycle time measurement: 11 minutes per 3m joint at production parameters (within the 15-minute constraint). | +| **Lineage** | Builds on manufacturing process evaluation CR-MFG-2023-003 (initial screening of 6 joining methods for marine aluminum). Inherits the fatigue and corrosion test methodologies from CR-MFG-2022-011 (GMAW performance baseline study). | +| **Assumptions** | FSW tool life remains consistent across the 500-joint production run (tool wear was not observed in the 50-joint trial but has not been tested at full production volume). The 8mm plate thickness is within the reliable process window for the selected FSW tool geometry. No metallurgical anomalies (e.g., kissing bonds) exist below the resolution of the nondestructive inspection methods used (ultrasonic C-scan at 0.5mm resolution). Ambient temperature variations at the production facility (5–35°C) do not significantly affect joint properties. | +| **Open Questions** | What is the tool replacement interval at full production volume? Can FSW parameters be optimized further to approach base-material fatigue strength? How does FSW perform on T-joint and corner-joint geometries required elsewhere in the structure? | +| **Discipline-Specific Data** | Process parameters: rotational speed 400 RPM, traverse speed 250 mm/min, axial force 35 kN, tool shoulder diameter 25mm, pin diameter 8mm, pin length 7.5mm. | + +## Self-Fading Assessment + +This example builds a bridge from the abstract context record structure (OE-0003) to the specific challenge of manufacturing process selection, where the decision is driven by the physical mechanisms the process introduces into the material. The reader has crossed this bridge when they can examine any solid-state versus fusion joining comparison and immediately identify which fields of the context record carry the decisive engineering weight — in this case, the Observation field (mechanism-based performance data) and the Reasoning field (causal link between process physics and failure modes). Once that mapping is intuitive, this example becomes unnecessary. \ No newline at end of file diff --git a/examples/mechanical-bearing-selection.md b/examples/mechanical-bearing-selection.md new file mode 100644 index 0000000..8b7bbf9 --- /dev/null +++ b/examples/mechanical-bearing-selection.md @@ -0,0 +1,34 @@ +# Example: Active Magnetic Bearing Selection for High-Speed Compressor (Mechanical Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) applied to a rotating machinery bearing selection decision, illustrating how competing failure mechanisms — contamination, fatigue, and rotordynamic stability — are weighed against each other and how the chosen solution eliminates a category of failure entirely rather than mitigating it. + +## The Observation + +Rotordynamic analysis of a centrifugal compressor rotor on conventional fluid-film bearings predicted two rigid-body critical speeds within the operating range of 15,000 to 25,000 RPM, forcing the machine to traverse two resonance zones during every startup and shutdown sequence. Process gas analysis revealed that the compressed hydrogen-rich synthesis gas is incompatible with conventional lubricating oils — a comparable facility using oil-lubricated bearings measured lubricant carryover into the process stream at 2 to 5 parts per million, exceeding the 0.5 ppm product purity specification by a factor of four to ten. Meanwhile, magnetic bearing vendor test data from an analogous 18,000 RPM compressor demonstrated rotor orbit amplitudes below 15 micrometers at all operating speeds with no mechanical contact during controlled coast-down, suggesting that a contact-free bearing system could simultaneously solve the contamination problem and the critical-speed traverse problem. + +## Engineering Translation + +Bearing selection for high-speed rotating machinery is governed by the interplay between the bearing's load-support mechanism and the consequences that mechanism introduces for the broader system. A fluid-film bearing supports the rotor through a pressurized lubricant film, which introduces the lubricant as a contaminant risk if the process gas cannot tolerate it. A rolling-element bearing supports the rotor through mechanical contact, which introduces fatigue as the dominant life-limiting mechanism at high speeds and temperatures. An active magnetic bearing supports the rotor through controlled electromagnetic forces with no physical contact, which eliminates both the contamination pathway and the mechanical wear pathway — but introduces a new dependency on the control system's reliability and power continuity. The engineering insight is that in this specific application, the dominant constraint is process gas purity (a hard specification limit at 0.5 ppm), not bearing life or rotordynamic complexity. This inverts the typical decision hierarchy: instead of selecting the simplest bearing that meets the load and speed requirements and then managing the consequences, the bearing must first satisfy the contamination constraint and only then be evaluated for the other performance requirements. This reasoning hierarchy must be preserved because a future engineer evaluating a bearing change for this machine — perhaps to reduce cost or simplify the control system — must understand that contamination elimination was the primary selection driver, not rotordynamic performance or maintenance interval (OE-0007). + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Select active magnetic bearings (AMBs) over hydrodynamic fluid-film bearings for a high-speed centrifugal compressor operating at 25,000 RPM. | +| **Observation** | (1) Rotordynamic analysis of the compressor rotor on fluid-film bearings predicted the first rigid-body critical speed at 8,200 RPM and a second at 19,500 RPM, both within the operating speed range (15,000–25,000 RPM), requiring careful speed transition management through two critical zones. (2) Process gas analysis showed the compressed gas (hydrogen-rich synthesis gas) is incompatible with conventional lubricating oils — contamination of the process stream by bearing lubricant carryover was measured at 2–5 ppm in a comparable facility using oil-lubricated bearings, exceeding the 0.5 ppm product specification. (3) Magnetic bearing vendor test data from an analogous 18,000 RPM compressor showed rotor orbit amplitudes below 15 µm at all operating speeds, with no mechanical contact during planned coast-down. | +| **Alternatives** | (A) Hydrodynamic fluid-film bearings with oil lubrication — rejected: two critical speeds within the operating range create operational constraints (prolonged speed ramps, vibration monitoring), and oil contamination of the process gas at 2–5 ppm exceeds the 0.5 ppm product specification. Gas-lubricated bearings were considered but could not support the required rotor weight at low speeds during startup. (B) Rolling-element bearings with dry-film lubrication — rejected: calculated L10 bearing life at 25,000 RPM with the applied radial and axial loads was 8,400 hours, below the 40,000-hour minimum maintenance interval. Dry-film lubrication degradation at the operating temperature (180°C) further reduced the projected life. (C) Active magnetic bearings — selected. | +| **Constraints** | Must operate continuously at 25,000 RPM. No process gas contamination above 0.5 ppm. Minimum maintenance interval of 40,000 hours (approximately 4.6 years). Maximum allowable vibration amplitude at the bearing locations is 25 µm peak-to-peak. Rotor mass is 340 kg. Available backup bearing clearance must accommodate a 15-minute coast-down from full speed without bearing damage. | +| **Reasoning** | Magnetic bearings eliminate the fundamental conflict between lubrication and process gas purity — there is no physical contact and therefore no lubricant to contaminate the process stream. The non-contact nature also eliminates wear, making the 40,000-hour maintenance interval achievable (magnetic bearings have demonstrated 100,000+ hour life in comparable applications). The active control system can modify bearing stiffness and damping in real time, allowing the rotor to pass through what would be critical speed zones on passive bearings without vibration amplification. The rotor orbit data from the vendor's analogous machine (below 15 µm) provides confidence that the 25 µm vibration constraint will be met. | +| **Verification** | (1) Factory acceptance test: full-speed operation at 25,000 RPM for 72 hours showed vibration amplitude of 11 µm at the magnetic bearing locations (below the 25 µm limit). Process gas analysis at the compressor discharge showed oil-free operation — total hydrocarbon content below 0.05 ppm. (2) Controlled coast-down test from 25,000 RPM: rotor landed on backup bearings at 2,500 RPM and decelerated to rest in 12 minutes (within the 15-minute constraint). Post-coast-down inspection of backup bearings showed no visible wear. (3) Rotordynamic sweep: vibration amplitude remained below 18 µm through the entire speed range (0–25,000 RPM) with no critical speed amplification peaks. | +| **Lineage** | Builds on rotordynamic analysis CR-MECH-2023-009 (bearing type screening for three candidates). Inherits the process gas contamination measurements from CR-MECH-2023-004 (comparable facility assessment). | +| **Assumptions** | The active magnetic bearing control system maintains stability through all transient conditions including sudden load changes and power supply disturbances (the backup power system provides 30 seconds of ride-through, verified during factory testing). The electromagnetic properties of the bearing laminations do not degrade over the 40,000-hour maintenance interval at the operating temperature of 180°C. The backup bearings (rolling-element, designed for coast-down only) are not subjected to frequent unplanned trips that would accumulate wear. | +| **Open Questions** | What is the failure mode of the active control system, and can the backup bearing system be designed to handle a full-speed drop without damage? How does the power consumption of the magnetic bearing system compare to the parasitic losses of fluid-film bearings at this speed and load? | + +## Self-Fading Assessment + +This example builds a bridge from the context record structure (OE-0003) to mechanical bearing selection, where the enduring lesson is that the decision hierarchy is determined by which constraint is hardest to satisfy — not by which constraint is most familiar. The reader has crossed this bridge when they can examine any bearing selection problem and immediately identify whether the primary selection driver is load capacity, speed, contamination tolerance, maintenance interval, or rotordynamic stability, and then structure the context record's Reasoning field to reflect that hierarchy. The deeper insight — that a contact-free bearing eliminates an entire category of failure rather than mitigating it — is the conceptual payload that makes this example self-fading: once the reader internalizes the distinction between mitigation and elimination as a selection strategy, the specific compressor application is no longer needed (OE-0007). \ No newline at end of file diff --git a/examples/observation-first-darcy.md b/examples/observation-first-darcy.md new file mode 100644 index 0000000..8656ce2 --- /dev/null +++ b/examples/observation-first-darcy.md @@ -0,0 +1,38 @@ +# Example: Darcy's Law and Observation First + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +The Principle of Observation First (OE-0004): that engineering knowledge begins with observed reality, not with theory, and that observations made before theory carry a durability that theory-derived conclusions often lack. + +## The Observation + +In 1856, Henry Darcy published a report on the water supply of the city of Dijon, France. His experimental apparatus was straightforward: a vertical column packed with sand, with water flowing through it under controlled pressure difference. He measured the flow rate at multiple pressure differences and sand column lengths. His data showed a linear relationship: the flow rate was proportional to the pressure difference and inversely proportional to the column length. He did not begin with a theory of fluid flow through porous media — he began with measurements. The relationship he observed is now known as Darcy's Law, and it remains the foundational equation for groundwater flow, petroleum reservoir engineering, and filtration design over 160 years later. + +## Observation Before Theory + +Darcy's approach exemplifies the observation-first principle. He did not derive his law from first principles of fluid mechanics — the Navier-Stokes equations existed but could not be solved for flow through complex porous media. Instead, he observed the behavior of the system directly and described it empirically. The theoretical explanation (derived decades later from pore-scale fluid mechanics) confirmed why Darcy's observation was correct, but the observation preceded and motivated the theory — not the reverse. + +The sequence matters. When observation comes first, the resulting knowledge is anchored to reality. Darcy's equation was correct before anyone could explain why it was correct, because it was derived from measurements of what actually happened, not from deductions about what should happen. The theory that later explained Darcy's Law did not refine the law — it confirmed it. The observation had already captured the essential truth. + +## The Cost of Reversing the Order + +Contrast Darcy's approach with cases where theory preceded observation. In the 18th century, several natural philosophers proposed theories of groundwater flow based on analogy with surface water flow — treating aquifers as underground rivers. These theories predicted flow velocities orders of magnitude faster than what was actually observed in wells and springs. The theories persisted for decades because they were intellectually elegant, not because they matched observation. When Darcy measured actual flow rates, the "underground river" theories collapsed — but decades of engineering effort based on incorrect models had already been expended. + +This pattern repeats throughout engineering history: a theory is constructed by analogy or deduction, it gains acceptance through intellectual appeal, and it persists until someone bothers to measure the actual phenomenon. The cost is not merely wasted effort — it is incorrect structures built, incorrect systems deployed, and incorrect decisions propagated. The underground river theories led to well-spacing recommendations that were wrong, to yield estimates that were wrong, and to infrastructure investments that were wrong. All of this was avoidable if observation had come first. + +## Engineering Translation + +Darcy's work demonstrates that observation is the primary input to engineering decisions. Models, theories, and elegant explanations are secondary — they must be derived from and validated against observation. When the order is reversed — when a model is constructed first and observations are fitted to it — the result is a model that may be internally consistent but does not reflect reality. Darcy's Law persists not because it was theoretically derived, but because it was observed. Any engineering observation that follows the same discipline — measure first, theorize second — inherits the same durability. + +The practical implication for the working engineer is direct: before committing to a model, a design approach, or a failure hypothesis, establish what has actually been observed. The observation does not need to be sophisticated — Darcy's apparatus was simple, and his measurements were flow rate, pressure, and column length. What matters is the discipline of allowing the observation to precede the explanation. When that discipline is maintained, the resulting engineering knowledge carries the same durability that has kept Darcy's Law relevant for over a century and a half. + +## Source + +Darcy, H. (1856). *Les Fontaines Publiques de la Ville de Dijon.* + +## Self-Fading Assessment + +This example builds a bridge from the abstract principle "observe before theorizing" (OE-0004) to a concrete case where that discipline produced knowledge that has endured for 160 years. The reader has crossed this bridge when they can look at any engineering situation — a failing system, a new material, an unexpected test result — and their first instinct is to ask "what was actually observed?" rather than "what does the theory predict?" When that instinct is automatic, Darcy's example has faded, and the principle remains. \ No newline at end of file diff --git a/examples/pre-discipline-measurement.md b/examples/pre-discipline-measurement.md new file mode 100644 index 0000000..b8e6141 --- /dev/null +++ b/examples/pre-discipline-measurement.md @@ -0,0 +1,36 @@ +# Example: Measurement as a Pre-Discipline Principle + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +The Pre-Discipline Principle (OE-0001): principles that existed before engineering disciplines separated, that are imposed by reality rather than by disciplinary tradition, and that therefore belong to the shared foundation of all engineering practice. + +## The Observation + +The need to measure physical quantities accurately and communicate those measurements reliably between practitioners predates every modern engineering discipline. Ancient Egyptian surveyors (harpedonaptae) used knotted ropes with consistent lengths to lay out right angles for construction — a measurement standard. The Indus Valley civilization (circa 2600 BCE) used standardized weights in a consistent binary ratio (1, 2, 4, 8, 16, 32, 64) across multiple cities, indicating inter-city calibration. The Magna Carta (1215) mandated uniform measures of wine, ale, and corn across England — a legal recognition that measurement standardization is an engineering prerequisite, not a discipline-specific concern. + +These three cases span roughly four millennia, two continents, and contexts ranging from temple construction to commodity trade to legal governance. None of the practitioners involved would have recognized the others' disciplines or even their professional identities. Yet all three converged on the same principle: to make decisions about the physical world, you must measure, and to communicate those measurements, you must standardize. + +## The Pre-Discipline Pattern + +These examples share a common principle that exists prior to and independent of any formal discipline: engineering decisions require measurement, and measurement requires standards. This principle was discovered independently by multiple civilizations because it is imposed by reality, not by disciplinary tradition. The Egyptian surveyor, the Indus Valley merchant, and the English administrator did not belong to the same discipline — they may not have known of each other's existence — but they converged on the same principle because the physical world requires it. + +This is the signature of a pre-discipline principle: independent, convergent discovery across cultures and contexts that have no disciplinary or intellectual contact. When multiple civilizations, operating in complete isolation, arrive at the same practice, the practice is not a cultural artifact — it is a response to a constraint imposed by reality. The constraint is simple: you cannot build what you cannot measure, and you cannot coordinate what you cannot communicate. Any civilization that builds or trades will eventually discover this constraint and develop practices to address it. The specific instruments and standards differ — knotted ropes versus binary weights versus royal measures — but the underlying principle is invariant. + +## Engineering Translation + +In modern terms, this principle appears in every discipline. A civil engineer verifying a beam's deflection, a chemical engineer measuring reaction yield, a software engineer measuring response latency, and an environmental engineer measuring contaminant concentration are all performing the same underlying act: comparing a quantity to a standard. The disciplines differ in what they measure and how, but the principle — that measurement against a known standard is the basis for engineering decisions — is universal and pre-disciplinary. Open Engineer's observation-first principle (OE-0004) is a direct descendant of this pre-discipline insight: before you can decide, you must observe, and to observe with precision, you must measure against a standard. + +The engineering translation is not that "measurement is important" — that is too weak a statement. The translation is that measurement is foundational and non-negotiable. Every engineering discipline has discovered this independently, which means it is not a feature of any particular discipline but a feature of engineering reality itself. Attempts to skip measurement — to decide based on authority, intuition, analogy, or theoretical elegance — fail in the same way across all disciplines: they produce decisions that do not match the physical world. The pre-discipline pattern tells us this is not a coincidence. It is a constraint. + +## Discipline-Specific Expression + +Each discipline has developed its own measurement traditions, instruments, and standards bodies. But the underlying principle — measure against a known standard, communicate the measurement unambiguously — belongs to no single discipline. It is part of the shared engineering foundation that existed before the disciplines separated. When Open Engineer defines observation as "a verifiable encounter with reality" (OE-0004), it is naming a principle that has been practiced for millennia under different names in different traditions, all converging on the same reality. + +The pre-discipline perspective is valuable because it prevents a common error: mistaking a discipline-specific practice for a discipline-specific principle. When a civil engineer insists on field measurements and a software engineer insists on benchmarking, they may believe they are applying different principles. The pre-discipline view reveals that they are applying the same principle through discipline-specific instruments. This recognition reduces artificial barriers between disciplines and reinforces the shared foundation that Open Engineer seeks to make explicit. The Egyptian surveyor and the modern software engineer are doing the same thing — comparing reality to a standard — and the pre-discipline principle explains why. + +## Self-Fading Assessment + +This example builds a bridge from the abstract concept of pre-discipline principles (OE-0001) to concrete cases where the same principle was discovered independently across millennia and cultures. The reader has crossed this bridge when they can look at a measurement practice in their own discipline and recognize it as an instance of a universal, pre-disciplinary principle — not a disciplinary convention, but a constraint imposed by reality. When that recognition is automatic, this example has faded, and the principle remains. \ No newline at end of file diff --git a/examples/software-architecture-migration.md b/examples/software-architecture-migration.md new file mode 100644 index 0000000..5052494 --- /dev/null +++ b/examples/software-architecture-migration.md @@ -0,0 +1,42 @@ +# Example: Runtime Architecture Migration in a Data Pipeline (Software Engineering) + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Context record structure (OE-0003) applied to a programming language and runtime architecture selection, illustrating how the reasoning behind a Python-to-Rust migration is typically lost when only the new codebase is preserved (OE-0009, OE-0010). + +## The Observation + +A data ingestion pipeline originally written in Python processed 40,000 events per second using a synchronous, single-threaded design with a PostgreSQL persistence layer. As event volume grew to 400,000 events per second, the Python implementation exhibited increasing latency spikes (p99 rising from 45ms to 2.3 seconds) and garbage collection pauses that caused the process to miss its processing window, resulting in backpressure buildup and eventual queue overflow. Profiling revealed that 78% of CPU time was spent on object allocation and deallocation in the event deserialization path, and the Global Interpreter Lock prevented effective parallelization of the CPU-bound parsing work. + +A developer unfamiliar with the system's history might look at the Rust replacement and ask: why was Python ever used for a high-throughput pipeline? The answer is that the pipeline was never designed to be high-throughput. When it was built two years earlier, the event volume was 5,000 events per second, and Python's ecosystem (existing database libraries, rapid prototyping speed, team familiarity) made it the correct choice. The context that is almost never preserved is the reasoning chain: what was true when Python was selected, what changed, why Rust became correct later, and what the new system inherits from the old one. + +## Engineering Translation + +This example demonstrates a pattern that is pervasive in software engineering: the reasoning behind an initial architecture decision is lost when the architecture is replaced, because the replacement is documented as a new system rather than as an extension of a prior decision. A developer who joins the team after the Rust migration sees a high-performance concurrent pipeline and may assume the project always required that level of performance. Without the context record, they cannot reconstruct why the original Python system existed, what conditions triggered the migration, or what constraints from the Python era still inform the Rust design (data schemas, queue contracts, error handling semantics, monitoring expectations). + +The context loss has practical consequences. If a future developer proposes migrating a different pipeline from Python to Rust based on this project's example, they need to understand whether the conditions that justified the migration here (CPU-bound parsing, GIL limitations, predictable data schemas) apply to their pipeline. Without the context record, the Rust pipeline becomes a template to copy rather than a decision to evaluate — which is the opposite of what Open Engineer intends. + +## Context Record + +| Field | Content | +|---|---| +| **Decision** | Migrate the event ingestion pipeline from Python (synchronous, single-threaded) to Rust (asynchronous, multi-threaded) while preserving the existing PostgreSQL persistence schema, message queue contracts, and monitoring instrumentation. | +| **Observation** | (1) Production metrics over 6 months showed event volume growing from 40,000 to 400,000 events/second with p99 processing latency rising from 45ms to 2.3 seconds. (2) Profiling with py-spy showed 78% of CPU time in object allocation/deallocation during event deserialization, with GC pause frequency increasing linearly with event rate. (3) The Global Interpreter Lock prevented distributing parsing work across the available 16 CPU cores — multi-process worker pools were tested but introduced inter-process serialization overhead that eliminated the throughput gain. (4) Load testing a prototype Rust implementation using tokio showed 620,000 events/second with p99 latency of 3.2ms on the same hardware, with memory allocation remaining flat under sustained load due to Rust's ownership model eliminating GC pauses. | +| **Alternatives** | (A) Optimize the Python implementation with Cython or PyO3 extensions for the parsing hot path — rejected: profiling showed the bottleneck was spread across multiple allocation sites in the deserialization logic, not concentrated in a single function that could be offloaded to an extension. The engineering effort to rewrite the allocation pattern in Cython was estimated at 60% of the full Rust migration cost while delivering at most 3x throughput improvement, insufficient for the 10x target. (B) Switch to a compiled language with garbage collection (Go) — rejected: Go's garbage collector, while lower-latency than Python's, still introduces stop-the-world pauses in the microsecond range that compound at the target throughput. The Rust prototype's zero-cost abstraction model (no GC, no runtime) demonstrated that the GC elimination itself was responsible for approximately 40% of the latency improvement. (C) Horizontal scaling with more Python instances behind a load balancer — rejected: the queue-based architecture already distributed work, but the per-instance throughput ceiling (approximately 60,000 events/second) meant that scaling to 400,000 events/second required 7+ instances, each consuming 4GB of memory, for a total memory footprint of 28GB. The single Rust instance achieved the same throughput in 800MB. The operational complexity of managing 7+ Python processes (separate health checks, separate log aggregation, separate deployment coordination) was disproportionate to the benefit. (D) Rust — selected. | +| **Constraints** | Must preserve the existing PostgreSQL schema (downstream consumers depend on the current table structure and column types). Must maintain backward compatibility with the existing message queue protocol (events published by upstream producers cannot be modified). Must not introduce a new runtime dependency (no JVM, no Erlang VM) — the operations team supports Python and compiled binaries only. Migration must complete within a single quarter (3 months) because the current system's p99 latency is approaching the SLA breach threshold at the projected 6-month growth rate. The Rust implementation must run on the existing Linux deployment infrastructure without kernel-level modifications. | +| **Reasoning** | The migration is driven not by a preference for Rust but by a specific, observed failure mode: Python's runtime characteristics (GC pauses, GIL, object allocation overhead) create a throughput ceiling that the system has reached. The Rust prototype demonstrated that eliminating GC and enabling true multi-threaded parsing removes this ceiling. The decision preserves continuity by maintaining the data schemas, queue contracts, and monitoring infrastructure from the Python system — the Rust system inherits the interface obligations of the Python system and extends them with higher throughput. The trade-off is reduced prototyping velocity: future pipeline changes in Rust require compile-time verification and explicit memory management that Python would handle at runtime. This trade-off is acceptable because the pipeline's interface contracts are now stable (2 years of production use) and the primary engineering need is throughput, not rapid iteration. | +| **Verification** | (1) The Rust implementation was deployed alongside the Python system in a shadow traffic configuration for 72 hours, processing the same live event stream. The Rust system processed 100% of events with zero data loss; a diff of the PostgreSQL output showed byte-identical rows for both systems across 38 million events. (2) Load testing at 1.5x projected peak volume (930,000 events/second) showed p99 latency of 8.1ms, well within the 100ms SLA. (3) Memory profiling under sustained load showed stable allocation at 812MB with no growth trend over 48 hours, confirming the absence of memory leaks that would require process restarts. (4) The operations team validated that the compiled binary deployed and restarted within the existing infrastructure automation without modifications. | +| **Lineage** | Builds on the original Python pipeline implementation (context record CR-SW-2021-004, "Event ingestion service initial implementation"). That record documented the decision to use Python based on the then-current event volume (5,000/second), team composition (3 Python developers, 0 Rust developers), and delivery timeline (2 weeks to production). The present record extends that lineage by documenting the conditions under which the original decision is no longer valid and the reasoning behind the new architecture selection. The PostgreSQL schema and message queue contracts defined in CR-SW-2021-004 are inherited without modification. | +| **Assumptions** | The event volume growth rate (approximately 2x per 6 months) will continue at approximately the same rate for the next 18 months, justifying the headroom provided by the Rust implementation. The Rust team's expertise (2 developers at the time of migration) is sufficient to maintain the system without requiring external contractors. The data schemas and queue contracts inherited from the Python system will remain stable — if upstream producers change the event format, the Rust system will require the same adaptation work as the Python system would have. The compiled binary's platform-specific behavior (memory alignment, SIMD optimization) does not introduce subtle differences in numeric processing that would cause the Rust system to produce different results than the Python system for identical inputs — this was verified by the shadow traffic test but only for the data patterns present during the 72-hour test window. | +| **Open Questions** | At what event volume does the PostgreSQL persistence layer become the next bottleneck, and should the schema be redesigned before that point? Should the team adopt Rust for new pipelines proactively, or continue using Python for new pipelines until they hit the same throughput ceiling? | + +## What Context Loss Looks Like Here + +Without this context record, a developer encountering the Rust pipeline for the first time sees a high-performance system and may reasonably ask: "Why was this ever written in Python?" The answer — that Python was correct for the original constraints and the constraints changed — is lost without the record. Worse, without the record, the team may repeat the same pattern on future projects: starting in Python for rapid prototyping, hitting the same throughput ceiling, and migrating to Rust without ever documenting why the initial choice was correct or what the trigger conditions for migration are. Each cycle repeats the same context loss. The context record breaks the cycle by preserving the reasoning chain from Python-correct to Rust-correct (OE-0009, OE-0010). + +## Self-Fading Assessment + +This example builds a bridge from the abstract concept of context preservation to a concrete software engineering case that most developers have experienced: a system that was right when it was built, became wrong as conditions changed, and was replaced without preserving the reasoning for either the original choice or the replacement. The reader has crossed this bridge when they can look at any architecture migration in their own work — language change, framework change, paradigm change — and immediately identify what reasoning is being lost if the migration is documented only as a new system rather than as an extension of a prior decision. Once that pattern is recognized, the specific details of Python, Rust, and event pipelines become incidental — the underlying principle that every architecture decision exists on a timeline and its reasoning must be preserved across transitions applies equally to all software engineering contexts. \ No newline at end of file diff --git a/examples/software-auth-context.md b/examples/software-auth-context.md new file mode 100755 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/spiral-reevaluation-flight-control.md b/examples/spiral-reevaluation-flight-control.md new file mode 100644 index 0000000..b6954d2 --- /dev/null +++ b/examples/spiral-reevaluation-flight-control.md @@ -0,0 +1,34 @@ +# Example: Spiral Re-evaluation in Flight Control + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Spiral re-evaluation (OE-0001). Returning to the same foundational question at progressively deeper levels of understanding, incorporating new observations and capabilities that did not exist during the previous pass. + +## The Observation + +In 1914, Lawrence Sperry demonstrated a gyroscopic stabilizer that could keep an aircraft level without pilot input — the first practical autopilot. The underlying question — how to maintain controlled flight without continuous human intervention — has been revisited repeatedly across a century of aviation. Each revisit returned to the same question but at a deeper level of understanding, incorporating new evidence and capabilities. The question has never been answered definitively; each answer has been subsumed by the next, deeper answer. This is not iteration and it is not repetition — it is a spiral. + +## The Spiral + +**First pass (1910s–1930s): Mechanical gyroscopes and pneumatic actuators.** The question was stability — could an aircraft fly straight without a pilot holding the controls? Sperry's answer was yes, for limited conditions. His gyroscopic stabilizer could maintain wings-level flight in calm air, and in 1914 he famously demonstrated it by walking out on the wings of his aircraft while it flew itself. The constraint was that mechanical systems could not adapt to changing conditions — turbulence, varying airspeed, or structural loading changes exceeded what a fixed mechanical linkage could compensate for. The answer was correct within its bounds but could not be extended beyond them. + +**Second pass (1950s–1970s): Analog electronic autopilots.** The question expanded — could an aircraft follow a programmed path through varying conditions, not just maintain a single attitude? The answer was yes, through feedback control. Analog autopilots used error-sensing amplifiers to detect deviation from a desired flight path and command control surface movements proportional to the error. This was a qualitatively different answer than Sperry's because it introduced the concept of continuous error correction rather than fixed-rate stabilization. The new constraint was that analog systems required extensive gain tuning and could not handle highly nonlinear flight regimes — near stall, at transonic speeds, or during aggressive maneuvers, the linear feedback models broke down and the autopilot would disengage or oscillate. + +**Third pass (1980s–2000s): Digital fly-by-wire systems.** The question deepened further — could an aircraft be designed to be inherently unstable and rely entirely on the control system for stability, enabling performance impossible with human pilots or analog systems? The answer was yes. The F-16 and subsequent aircraft demonstrated that relaxing the static stability requirement in favor of control authority produced superior maneuverability. Digital computers could execute control laws hundreds of times per second, managing the instability that human pilots could not. This could not have been conceived in the first pass because the understanding of control theory (state-space methods, optimal control) and the hardware capability (digital computation) were not yet available. Each prior pass — Sperry's mechanical stabilization, the analog autopilot's feedback control — was a necessary precursor that produced understanding subsumed by but not replaced in the digital era. + +**Fourth pass (2010s–present): Adaptive and learning-based control.** The question refined further — can the control system adapt to damage or failure in real time, maintaining control authority even when the aircraft's dynamic properties change unpredictably? Research aircraft have demonstrated safe landing after structural damage that would have been catastrophic with any previous control paradigm. NASA's Airborne Subscale Transport Aircraft Research (ASTAR) and related programs showed that adaptive control systems could reconfigure their control laws in response to simulated wing damage, maintaining controllability through conditions that no fixed control law could handle. The foundational question remains the same — how to maintain controlled flight without continuous human intervention — but the understanding of what "maintain," "controlled," and "flight" each mean has deepened with every pass. + +## Engineering Translation + +Each spiral pass returned to the same foundational question (how to maintain controlled flight without continuous human intervention) but at a deeper level of understanding, incorporating observations and capabilities that did not exist during the previous pass. This is not iteration (repeating the same process with the same understanding) and not repetition (doing the same thing again expecting different results). Each pass produced a qualitatively different answer because the understanding beneath the question had grown. Sperry's answer (mechanical stabilization) was correct; the analog autopilot's answer (feedback control) was correct; the fly-by-wire answer (relaxed stability through digital control) was correct; the adaptive control answer (real-time reconfiguration) was correct. None of them replaced the others — each subsumed the prior understanding within a more complete framework. Spiral re-evaluation is the mechanism by which engineering understanding deepens: not by discarding prior answers but by recognizing their incompleteness in light of new observation and capability (OE-0001). + +## Thread Integrity Connection + +Each pass was possible because the prior work was preserved and accessible. The engineers of the fly-by-wire era could read Sperry's original work, understand the analog autopilot era's contributions to feedback control theory, and build on both. The thread was intact. Had any of these passes been lost — had the 1950s analog work not been preserved, or had Sperry's demonstrations been forgotten — the later passes would have had to re-derive intermediate understanding, slowing or blocking progress. The spiral depends on thread integrity: you cannot spiral upward if you cannot see where you have already been (OE-0001, OE-0003). The flight control spiral is not a story of individual genius but of accumulated, accessible, contextualized engineering understanding — each pass building on a readable, reconstructible record of what came before. + +## Self-Fading Assessment + +This example builds a bridge from the abstract concept of "spiral re-evaluation" to a concrete historical case where the same foundational question was revisited across a century at progressively deeper levels of understanding. The reader has crossed the bridge when they can distinguish spiral re-evaluation from mere iteration — when they see that Sperry, the analog autopilot engineers, the fly-by-wire designers, and the adaptive control researchers were all answering the same question, but that each answer was qualitatively different because the understanding beneath the question had grown. Once that distinction is stable and the reader can identify spiral patterns in their own engineering work — moments where returning to a prior question with new understanding produces a deeper answer rather than a repeated one — the flight control example has served its purpose and can be set aside. \ No newline at end of file diff --git a/examples/stewardship-roman-concrete.md b/examples/stewardship-roman-concrete.md new file mode 100644 index 0000000..06a4088 --- /dev/null +++ b/examples/stewardship-roman-concrete.md @@ -0,0 +1,32 @@ +# Example: Roman Marine Concrete + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +Stewardship — the transmit discipline (OE-0009). The distinction between preserving an artifact and preserving the engineering reasoning that produced it. + +## The Observation + +Roman marine concrete (opus caementicium) used volcanic ash (pozzolana) that produced a calcium-aluminum-silicate-hydrate (C-A-S-H) binding phase, enabling structures like the Portus harbor and Pantheon dome to survive 2,000 years in aggressive environments. The specific knowledge of the pozzolana reaction mechanism and its relationship to seawater durability was understood by Roman engineers but not preserved as a structured context record. By the Middle Ages, the knowledge had fragmented — later builders used Roman concrete ruins as quarry material without understanding the reaction chemistry that made them durable. Vitruvius recorded some observational guidance (use volcanic ash from specific regions, immerse in seawater to cure), but the reasoning behind those observations — why that ash, what happens at the molecular level, what alternatives were tried and rejected — was never captured. The artifact outlasted the understanding by roughly a millennium. + +## Engineering Translation + +This is a stewardship failure. The Roman engineers who developed marine concrete held knowledge in trust. They transmitted the procedural knowledge (mix proportions, material selection) but not the reasoning (why pozzolana, what alternatives were considered, what constraints drove the selection). When the procedural knowledge was lost, the reasoning could not be reconstructed — there was no context record from which to inherit. The thread broke not because the knowledge was unavailable, but because the context that gave the knowledge its engineering meaning was never preserved. Vitruvius' *De Architectura* came closest to a context record, but it transmitted prescriptions rather than principles — it told future builders what to do, not why doing it worked or what failure modes to watch for. A steward transmits not just the decision but the landscape of reasoning that produced it (OE-0009). The Romans transmitted the decision (use pozzolana) without the landscape. + +## The Stewardship Gap + +Compare to the Antikythera example (thread integrity failure through total loss). Roman concrete represents a different and in some ways more insidious failure mode: the artifact survived, the material was visible and touchable, and the structures themselves stood as undeniable evidence that the material worked. But the reasoning behind it was inaccessible. Medieval builders who harvested Roman concrete as rubble did not lack access to the artifact — they were literally standing on it. What they lacked was the engineering context: why this particular mixture, bound by this particular chemistry, behaved the way it did. A steward who transmits only the artifact without its engineering context transmits the shell, not the substance. The modern recovery of Roman concrete chemistry (Jackson et al., 2017, *American Mineralogist*) required 200 years of materials science that the Romans' reasoning could have provided directly, had it been preserved as a context record rather than a collection of empirical prescriptions. The cost of the stewardship gap was not the loss of the artifact (it survived) but the loss of the reasoning that would have accelerated its re-discovery by centuries. + +## Modern Stewardship Implication + +When an engineer documents only the final design — the mix proportions, the specification, the drawing — but not the reasoning, alternatives, constraints, and verification that produced it, they commit the same stewardship failure as the Roman concrete builders. The artifact is preserved; the understanding is not. A modern structural engineer who specifies a concrete mix design without recording why this particular mix was chosen over alternatives, what performance trade-offs were evaluated, what environmental conditions it was optimized for, and what failure modes were considered, is producing a 21st-century Vitruvius — a document that tells the next engineer what to do but not why. When conditions change (new aggregate sources, different environmental exposures, updated performance requirements), the next engineer cannot adapt the specification because they do not understand the reasoning behind it. The steward's obligation is not merely to preserve the output but to preserve the reasoning that makes the output interpretable and extensible by the next practitioner (OE-0009). + +## Sources + +Jackson, M. D., Mulcahy, S. R., Chen, H., Li, Y., Li, Q., Cappelletti, P., & Wenk, H.-R. (2017). "Phillipsite and Al-tobermorite mineral cements produced through low-temperature water-rock reactions in Roman marine concrete." *American Mineralogist*, 102(7), 1435-1450. Oleson, J. P., Brandon, C., Cramer, S. M., Cucitore, R., Gotti, E., & Hohlfelder, R. L. (2014). "The ROMACONS Project: A Contribution to the Historical and Engineering Analysis of Hydraulic Concrete in Roman Seaports." *International Journal of Nautical Archaeology*, 43(1), 134-157. Vitruvius. *De Architectura*, Book II, Chapter 6. + +## Self-Fading Assessment + +This example builds a bridge from the abstract concept of "stewardship" to a concrete historical case where transmitting the artifact without transmitting the reasoning produced a millennium-long gap in engineering understanding. The reader has crossed the bridge when they recognize that the difference between a specification and a context record is the difference between Vitruvius' prescriptions and what a full stewardship record would have provided — and when they can identify the same pattern in their own documentation practices. Once that recognition is stable, the Roman concrete example has served its purpose and can be set aside. \ No newline at end of file diff --git a/examples/survey-retaining-wall-failure.md b/examples/survey-retaining-wall-failure.md new file mode 100644 index 0000000..fe6f27f --- /dev/null +++ b/examples/survey-retaining-wall-failure.md @@ -0,0 +1,42 @@ +# Example: Retaining Wall Failure Survey + +**Status:** Draft +**Phase:** The Bedrock Phase + +## What This Example Demonstrates + +The Survey practice (OE-0005): the structured assessment that serves as organized input to engineering understanding, distinct from understanding itself. + +## The Observation + +Between 2005 and 2015, a review of 47 retaining wall failures in transportation infrastructure was conducted. Each failure was documented with: the wall type (gravity, cantilever, anchored, mechanically stabilized earth), the failure mode (sliding, overturning, bearing capacity, internal failure, drainage-related), the soil conditions at the time of failure, the design assumptions, and whether the failure was related to a condition that was known at design time or one that developed during service. The raw data from these 47 cases, taken individually, tells a practitioner almost nothing useful. A single failure is an anecdote. Forty-seven failures, organized into a survey, reveal patterns that no single case could reveal. + +## The Survey Structure + +Mapping to OE-0005's five required sections, the retaining wall failure survey was structured as follows: + +1. **Scope:** Retaining wall failures in transportation infrastructure, 2005-2015, 47 cases across four wall types (gravity, cantilever, anchored, mechanically stabilized earth). The scope was defined before data collection began, preventing the survey from expanding uncontrollably or shifting focus mid-study. + +2. **Observations Collected:** Failure mode classification for all 47 cases. Soil condition data from post-failure investigations. Design documents and as-built records. Maintenance history. Rainfall and groundwater records for the 12 months preceding each failure. Each observation was collected using a consistent protocol, ensuring that the data from case 1 was comparable to the data from case 47. + +3. **Patterns Identified:** (a) Drainage-related failures accounted for 62% of all cases across all wall types — this was the dominant pattern. (b) Mechanically stabilized earth (MSE) walls had the lowest failure rate per kilometer of installation, but their failures tended to be sudden and catastrophic (reinforcement strip rupture) rather than gradual. (c) 71% of failures involved a condition that existed at design time but was not accounted for (typically, groundwater level higher than assumed in design). These patterns emerged only after the observations were organized; they were not visible in any individual case file. + +4. **Gaps Flagged:** Insufficient data on long-term drainage material degradation rates. No standardized post-failure investigation protocol — data quality varied significantly between cases. Limited data on walls that did NOT fail (survivorship bias in the dataset). These gaps are as important as the patterns, because they tell the practitioner where the survey's conclusions are weak and where future observation is needed. + +5. **Relationship to Prior Surveys:** Extended a 1998 review by Dunnicliff (23 cases, 1980-1997). The 62% drainage-related failure rate is consistent with Dunnicliff's finding of 58%, reinforcing the pattern across a longer time period and larger dataset. This connection to prior work transforms the survey from an isolated study into a link in a chain of accumulating knowledge. + +## Survey Is Not Understanding + +The survey identifies patterns but does not explain them. Understanding — why drainage failures are so prevalent, why design-phase groundwater assumptions are so often wrong, what the mechanism is — requires the engineer to engage with the survey's findings and construct a contextualized model. The survey is the organized input; understanding is what the practitioner builds from it. This distinction matters because a survey without a practitioner's engagement is inert data. It becomes engineering knowledge only when a practitioner uses it to form understanding, verify that understanding against reality, and preserve the resulting context. + +A survey that sits in a filing cabinet or a database is not engineering knowledge. It is potential knowledge, waiting for a practitioner to engage with it. The practitioner who reads the 62% drainage failure rate and asks "why?" has begun the transition from survey to understanding. The practitioner who then investigates the specific drainage mechanisms, tests the hypothesis against new observations, and records the reasoning has completed the transition. The survey enabled this process but did not replace it. + +## Connection to the Process Chain + +This survey connects to the foundational process (OE-0001): the observations were collected (step 1), patterns were recognized (step 2), and the findings can be translated into engineering language (step 3). The next step — verification against reality (step 4) — would require implementing the survey's findings in new designs and measuring whether drainage-related failure rates decrease. This is how a survey feeds the engineering process: it provides organized observations and identified patterns that a practitioner can use as input to understanding, which then informs decisions, which are then verified against new observations. + +The process is cyclic, not linear. The verification step generates new observations that may feed back into a future survey, refining or challenging the original patterns. The 62% drainage failure rate found in this survey may change as new data is collected — and that is the point. The survey is a snapshot of understanding at a point in time, structured so that future practitioners can build on it, refine it, or replace it with better data. It is part of the engineering fabric, not a final answer. + +## Self-Fading Assessment + +This example builds a bridge from the abstract definition of a survey (OE-0005) to a concrete case where structured data collection revealed patterns invisible in individual cases. The reader has crossed this bridge when they can distinguish between a survey (organized observations and identified patterns) and understanding (the practitioner's contextualized model of why those patterns exist), and when they instinctively structure their own multi-case assessments using the five required sections. When that distinction and that structure are automatic, this example has faded, and the practice remains. \ 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..0406296 --- /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 Carries Meaning + +The arrangement of information conveys meaning that the individual components do not. For the authoritative definition and engineering manifestations, see OE-0001 (Foundation), Section: Structure Carries Meaning. + +--- + +## 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..9ad0ad0 --- /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 Refinement Gate + +Every proposed refinement to existing content must additionally answer (this gate applies during any compression or stabilization pass, not only to a specific project milestone): + +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..ddce7bc --- /dev/null +++ b/reference/patterns.md @@ -0,0 +1,19 @@ +# Patterns + +**Status:** Draft +**Version:** 0.2.0-draft +**Phase:** The Bedrock Phase + +## Overview + +This document indexes structural and conceptual patterns identified by the standard. Each entry provides a short description and points to its authoritative definition. This document does not restate those definitions. + +--- + +## Pattern Index + +| Pattern | Description | Source | +|---|---|---| +| Structure Carries Meaning | The arrangement and relationship between components conveys information that the individual components do not. | OE-0001 (Foundation), Section: Structure Carries Meaning | +| Examples Are Bridges | Examples serve as structural transportation from unfamiliar concepts to familiar understanding; they are load-bearing, not decorative. | OE-0001 (Foundation), Section: Examples Are Bridges | +| The Pre-Discipline Principle | Shared principles that predate formal discipline boundaries apply universally across all modern engineering disciplines. | OE-0001 (Foundation), Section: The Pre-Discipline Principle | \ No newline at end of file diff --git a/reference/vocabulary.md b/reference/vocabulary.md new file mode 100755 index 0000000..11e9a4d --- /dev/null +++ b/reference/vocabulary.md @@ -0,0 +1,29 @@ +# 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 | +| Pre-Discipline Principle | Shared principles that predate formal discipline boundaries apply universally | OE-0001 | +| 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..f295270 --- /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 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..b4ddaf7 --- /dev/null +++ b/spec/oe-0000-charter.md @@ -0,0 +1,96 @@ +# 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. + +Philosophy, documentation systems, projects, and presentation layers each have their own purpose. This document defines the standard that those efforts implement. 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. **Decision Specificity:** The Decision field identifies exactly one choice or course of action. A record that lists multiple decisions without distinguishing the selected choice is non-compliant. + +3. **Observation Traceability:** The Observation field references at least one verifiable encounter with reality (direct or corroborated as defined in OE-0004). + +4. **Constraint Bounding:** The Constraints field identifies at least one constraint that bounded the decision. + +5. **Alternatives Plural:** The Alternatives field lists at least one option that was considered and rejected. A record with no rejected alternatives is non-compliant — the absence of alternatives indicates the decision was not deliberated. + +6. **Verification Against Reality:** The Verification field describes a test, measurement, or assessment against observable outcomes — not against a model or an opinion. + +7. **Reasoning References Alternatives:** The Reasoning field explains why the selected Decision was preferred over at least one rejected Alternative. Reasoning that restates the Decision without engaging with trade-offs is non-compliant. + +8. **Lineage Traceability:** The Lineage field either references at least one prior context record or explicitly states "no prior work" with rationale. + +9. **Assumption Awareness:** The Assumptions field contains at least one assumption, even if the assumption is "no significant unknowns." + +10. **No Contradiction:** The context record does not contradict any Accepted-status specification document. + +A context record that satisfies all ten criteria is compliant. A record that satisfies criteria 1-9 but not 10 is compliant at the document level but may require resolution at the project level. Records that fail any of criteria 1-9 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 ten 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..348a922 --- /dev/null +++ b/spec/oe-0001-foundation.md @@ -0,0 +1,83 @@ +# 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. + +## 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 seeks principles that existed before the disciplines separated, because those principles apply universally and form the reality basis on which discipline-specific knowledge is built. Discipline-specific content belongs in implementations, not in the core standard. + +## 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..7d2c744 --- /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 Refinement Gate 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..885a532 --- /dev/null +++ b/spec/oe-0010-inheritance.md @@ -0,0 +1,34 @@ +# 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. + +## 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 100755 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..85145ce --- /dev/null +++ b/whatremains.txt @@ -0,0 +1,117 @@ +WHAT REMAINS — Final Revision +==================================== + +This file tracks the status of all identified gaps and remaining +work after the gap-closure revision. + +All seven gaps from the external 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 ten testable conformance criteria: + (1) Field Completeness, (2) Decision Specificity, + (3) Observation Traceability, (4) Constraint Bounding, + (5) Alternatives Plural, (6) Verification Against Reality, + (7) Reasoning References Alternatives, (8) Lineage Traceability, + (9) Assumption Awareness, (10) 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 PARTIALLY ADDRESSED + The examples/ directory now contains 18 examples across 9 + engineering disciplines (civil, software, biomedical, chemical, + aerospace, environmental, manufacturing, electrical, mechanical) + and 9 conceptual areas (thread integrity, structure carries + meaning, verification loop, stewardship, inheritance, spiral + re-evaluation, observation first, survey, pre-discipline principle). + Remaining opportunity: practitioners in specific domains may add + further discipline-specific examples during the Community Phase + that reflect their domain's unique constraint patterns. + +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. Milestone Statement + Process metadata about revision milestones belongs in project + records, not in the standard. No specification content references + any project milestone name. \ No newline at end of file