From 07c655a31b7db6f4b98047be56ead519074424ed Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:23:53 +0100 Subject: [PATCH 01/32] docs(v2): draft engineering data enrichment chapter --- ...ing-data-from-measurements-to-decisions.md | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 chapters/05-engineering-data-from-measurements-to-decisions.md diff --git a/chapters/05-engineering-data-from-measurements-to-decisions.md b/chapters/05-engineering-data-from-measurements-to-decisions.md new file mode 100644 index 0000000..1ae4819 --- /dev/null +++ b/chapters/05-engineering-data-from-measurements-to-decisions.md @@ -0,0 +1,139 @@ +# Chapter 05 — Engineering Data: From Measurements to Decisions + +Status: proposed v2 chapter manuscript (draft; not yet a published v2 lesson) +Part: II — Building Engineering Knowledge +One question: How can engineers improve, enrich, and examine data so that it supports a defensible next decision? + +## The result is not the understanding + +Two engineering teams have evaluated candidate monitoring configurations. One presents a coverage percentage calculated by a geometric model. The other offers a spreadsheet of proposed electronic power needs and mechanical installation constraints. Each file seems useful. Yet neither, alone, answers whether the candidate should move toward the next design increment. + +Engineering data become more valuable when we **check their quality, explain their context, combine them carefully, visualize their behavior, challenge our interpretations, and preserve the work for reuse**. These are not sequential gates. A plot can send us back to question a measurement, and a reviewer can ask for new annotations before any conclusion is accepted. + +This chapter builds on the fictional Distributed Monitoring System (DMS), but moves beyond a single model output. We work with a *collection* of results and explicitly differentiated types of technical information. + +## Quality: is this observation fit for the question? + +Before calculating a margin, ask what the number represents. Was it observed on hardware, computed from a simulation, copied from a supplier specification, or estimated by an engineer? Are the units, source revision, parameter settings, measurement conditions, and uncertainty known? + +An engineering dataset can be syntactically valid but technically inappropriate for a decision. A temperature measurement without sensor location and calibration conditions may not represent the component temperature of interest. A simulation output from a previous geometry may not apply to the current configuration. + +Useful quality checks include completeness, unit consistency, range and physical plausibility, timestamps, configuration matches, duplicate records, and inconsistent assumptions. Do not silently discard an inconvenient outlier. Flag it, inspect its source, and record whether and why it was excluded from a particular calculation. + +Our canonical V0 example defines a 100 by 100 area in *model units*, a sensor at (50, 50), and a circular idealized radius of 35 model units. Its deterministic grid-based coverage estimate is approximately 38.5%, compared with a deliberately assumed 50% requirement. The engineering outcome is FAIL. This is a modeled geometric area fraction, not detection probability or demonstrated physical sensor performance. + +## Annotate: add the conditions under which data mean something + +Imagine a row containing a simulation result. A useful engineering annotation identifies the model version, scenario, input set, method, assumptions, threshold, source revision, and interpretation status. It may also identify an observation requiring further investigation. + +A data record can carry both the number and the explanation. For example: + +| Field | Illustrative value | Meaning | +| --- | --- | --- | +| Scenario | SCN-001 | Canonical V0 scenario | +| Model | MODEL-COV-001 | Fixed grid-sampling geometric model | +| Radius | 35 model units | Assumed circular footprint | +| Coverage | Approximately 38.5% | Computed geometric fraction | +| Criterion | 50% | Educational reference threshold | +| Conclusion | Does not meet criterion | Valid only within the V0 model | +| Open question | Physical characterization | Not supplied by this simulation | + +Do not treat an annotation as harmless decoration. Changing an assumption or model applicability note can change which conclusions are defensible. AI-generated tags or explanations should have a *proposed* status until reviewed. + +## Enrich: combine evidence without mixing meanings + +One value becomes more useful when connected to requirements and model definitions. More value can arise when separate disciplines contribute relevant constraints. + +Suppose we study three hypothetical equipment variants. A geometry analysis estimates each variant’s area coverage under specified ideal footprints. An electronics table contains **illustrative planning estimates** for power consumption. A mechanical table lists **illustrative mounting constraints**. These are fictional teaching data, not physical tests or equipment specifications. + +We can join them by an explicit, versioned variant identifier. Before joining, verify that the variant names, revisions, and assumed operating modes really refer to the same configuration. A tempting match between labels is not enough. + +The enriched result can then contain geometric coverage, a calculated coverage margin, a power-budget margin, and a mounting-constraint flag. For a power budget P_available and demand P_required: + +**Power margin = P_available − P_required.** + +For a geometric coverage criterion C_required and calculated result C_model: + +**Coverage margin = C_model − C_required**, expressed in percentage points. + +These quantities have different units and meanings. Neither should be collapsed into a single unexplained score. The first is only as credible as the power estimates and their conditions; the second is only a result of the documented geometry model. + +A combination of correctly computed numbers can still be misleading if its input assumptions are incompatible. + +## Derive: extract properties that were not measured directly + +Engineers routinely use derived properties—margins, efficiency, rates of change, error statistics, tolerances, uncertainty budgets, and sensitivity measures. Good derived data retain a clear calculation method and relevant units. + +A controlled parameter study can use the existing V0 function to evaluate several explicitly defined positions and radii. Rather than repeat the single-sensor slider, use the resulting *dataset* to ask: where does the calculated response change fastest, which comparisons keep their other inputs constant, and which candidate settings remain below the threshold? + +Sensitivity is not a property of one isolated point. Compare results over a stated input range using a defined change measure, such as a finite-difference ratio of changes in coverage percentage points to changes in radius model units. That ratio is local to the sampled configurations; it is not a universal sensor-performance law. + +If a later exercise compares a measured response with a predicted one, state which quantity is the reference and use a consistent residual convention. No real measurement data are supplied by V0, so a residual between simulated and measured behavior cannot legitimately be calculated from the present repository. + +## Visualize: make uncertainty and behavior visible + +A table supports detailed audit. A plot supports different questions. Use both. + +A sensitivity curve can reveal where additional model runs would be informative. A scatter plot comparing two parameters can expose an association worth investigating. A constraint plot can show where a proposed configuration satisfies the geometric teaching criterion but violates a *synthetic* electronics budget. + +Every visualization needs labeled axes, units, source selections, and visible assumptions. Show missing configurations rather than filling them with invented measurements. An unusually smooth curve may reflect the method or interpolation rather than real behavior. Differences smaller than numerical resolution deserve particular care. + +Ask of every figure: *What became more understandable? What became easier to question?* + +## Review: what does the evidence actually establish? + +Review distinguishes calculated output, observed evidence, proposed interpretation, and approved decision. + +A correctly executed geometry computation shows what the defined mathematical model predicts for given inputs. It does not establish physical sensor range, detection reliability, thermal stability, or installation feasibility. A passing software test can coexist with a failed requirement comparison: the test can confirm that the evaluator correctly reports the modeled failure. + +Likewise, if our synthetic cross-disciplinary example shows a power shortfall, that is a useful planning illustration, not proof that a manufactured product violates a real power budget. + +A meaningful review asks: + +- What is the precise engineering claim? +- Which records and models support it, and which assumptions bound it? +- Are alternative explanations or conflicting observations available? +- What has been calculated, physically observed, or independently checked? +- What would we need to test next before committing to an architecture? + +When external studies, standards, or supplier information are used, retain the source, edition, assumptions, and applicability. Research can enrich a comparison without automatically validating a particular design. + +## Preserve: engineering data as a reusable asset + +An image of a result is not a reusable experiment. Preserve at least three distinguishable assets: + +**Original records.** Keep original measurements or the exact simulation execution context, with time, source, configuration, method, and access restrictions. + +**Curated records.** Preserve quality decisions, annotations, corrected or standardized representations, and reasons for exclusions. + +**Derived results.** Preserve computed quantities, transformation logic, input IDs, model version, and checks. Document whether an output is an exploratory browser calculation or a retained, revision-bound execution record. + +A small **Engineering Knowledge Catalogue** lets engineers discover these datasets and understand their owner, purpose, units, provenance, confidence and limitations, relationships, and reuse conditions. A catalogue is a map to assets and context, not a replacement for either. + +Structured text and version-controlled calculation logic can be useful, but not every high-volume dataset belongs inside Git. Choose storage suited to volume, change rate, confidentiality, access, retention, and reproducibility. Keep references stable enough that a future engineer can reconstruct which results supported which decision. + +## Where AI helps—and where review remains essential + +An engineering agent can help parse reports, extract parameters and units, detect anomalies, suggest annotations, generate transformation code, find relevant research, or propose follow-up experiments. These are candidates for review, not qualified observations. Preserve distinctions between source text, extracted values, suggested classification, and verified engineering facts. + +AI does not turn an assumed sensing radius into a calibrated physical range. Nor does a knowledge graph turn a proposed relationship into a verified dependency. Reliable assistance depends on relevant context, tools, source access, and engineering judgment. + +## A decision, not just another chart + +Return to the monitoring system. The next engineering decision is not “which row has the highest coverage?” It is **which uncertainty should we reduce next, and what information would justify that choice?** The enriched dataset can show promising configurations and expose constraint conflicts. It can also reveal missing thermal characterization, incompatible revisions, and the need for physical tests. + +That is the purpose of engineering data enrichment: make data **more trustworthy, meaningful, inspectable, and reusable**, so that engineers can learn faster without confusing a calculated result with established system behavior. + +The next proposed chapter uses what was learned to specify a bounded engineering increment without pretending every remaining uncertainty has been resolved. + +--- + +## Proposed reader-facing demonstration — Engineering Data Investigation + +This manuscript is the editorial source for a future v2 browser experience. The following is a design contract, **not a claim of completed functionality**. + +Use an immutable V0 parameter-study dataset generated from the shared coverage calculation. Add a separate small, explicitly synthetic variant-constraint fixture with fictional power and mounting assumptions. Let readers inspect original values; apply deterministic annotations and joins keyed by versioned configuration identifiers; compute margins and an inspectable finite-difference sensitivity metric; switch among raw, curated, and derived tabular views; and investigate a single decision question through linked plots. + +Make mismatched identifiers visible rather than matching by name. Provide an alternative data table for every plot. Preserve original source definitions and separate temporary browser calculations from recorded execution evidence. Do not alter the canonical V0 system, assertions, or reference FAIL result. + +The new demonstration must provide a fresh learning experience, rather than a repetition of the old position/radius slider. From b1fc422be8841b69ea1bb8da75456e7f98cb4b77 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:28:05 +0100 Subject: [PATCH 02/32] feat: add concise engineering chapter glance content --- site/src/data/chapter-glances.ts | 381 +++++++++++++++++++++++++++++++ 1 file changed, 381 insertions(+) create mode 100644 site/src/data/chapter-glances.ts diff --git a/site/src/data/chapter-glances.ts b/site/src/data/chapter-glances.ts new file mode 100644 index 0000000..114ffc3 --- /dev/null +++ b/site/src/data/chapter-glances.ts @@ -0,0 +1,381 @@ +/** Reader-facing chapter summaries, not claims of completion or verification. */ +export interface ChapterGlance { message: string; tiles: { title: string; detail: string }[] } +export const chapterGlances: Record = { + "01-engineering-intent": { + "message": "Engineering starts with an operational need and reaches evidence through explicit definitions.", + "tiles": [ + { + "title": "Intent", + "detail": "Understand the need" + }, + { + "title": "Criterion", + "detail": "Choose a measurable claim" + }, + { + "title": "Scenario", + "detail": "Bound the question" + }, + { + "title": "Model", + "detail": "Calculate a prediction" + }, + { + "title": "Evaluation", + "detail": "Check the criterion" + }, + { + "title": "Evidence", + "detail": "Explain the result" + } + ] + }, + "02-engineering-information-models": { + "message": "Structured definitions and meaningful references make engineering changes more inspectable.", + "tiles": [ + { + "title": "Needs", + "detail": "Capture purpose" + }, + { + "title": "Requirements", + "detail": "Define measurable expectations" + }, + { + "title": "Models", + "detail": "Represent behavior" + }, + { + "title": "Identifiers", + "detail": "Connect definitions" + }, + { + "title": "Validation", + "detail": "Check source consistency" + }, + { + "title": "Change", + "detail": "Review applicability" + } + ] + }, + "03-digital-threads": { + "message": "Connected engineering information lets us follow dependencies and question what a change affects.", + "tiles": [ + { + "title": "Identity", + "detail": "Recognize records" + }, + { + "title": "Relationships", + "detail": "Define typed links" + }, + { + "title": "Traceability", + "detail": "Follow evidence paths" + }, + { + "title": "Versions", + "detail": "Identify configuration" + }, + { + "title": "Impact", + "detail": "Find affected items" + }, + { + "title": "Confidence", + "detail": "Distinguish inference from proof" + } + ] + }, + "04-executable-models": { + "message": "Executable models make assumptions and calculations inspectable—and their limitations visible.", + "tiles": [ + { + "title": "Inputs", + "detail": "Specify a scenario" + }, + { + "title": "Method", + "detail": "Define calculation" + }, + { + "title": "Execution", + "detail": "Generate an output" + }, + { + "title": "Assumptions", + "detail": "Bound validity" + }, + { + "title": "Precision", + "detail": "Recognize approximation" + }, + { + "title": "Checks", + "detail": "Reproduce the result" + } + ] + }, + "05-experimentation": { + "message": "Controlled experiments compare alternatives without confusing feasibility with preference.", + "tiles": [ + { + "title": "Question", + "detail": "Define the choice" + }, + { + "title": "Factors", + "detail": "Vary one thing deliberately" + }, + { + "title": "Controls", + "detail": "Hold context stable" + }, + { + "title": "Results", + "detail": "Record independent runs" + }, + { + "title": "Comparison", + "detail": "Interpret differences" + }, + { + "title": "Gaps", + "detail": "Identify missing evidence" + } + ] + }, + "06-verification-evidence": { + "message": "Evidence is useful only when we know what was executed, what it establishes, and its limits.", + "tiles": [ + { + "title": "Claim", + "detail": "Specify what must hold" + }, + { + "title": "Method", + "detail": "Inspect the test" + }, + { + "title": "Inputs", + "detail": "Know the evaluated configuration" + }, + { + "title": "Outcome", + "detail": "Read the actual result" + }, + { + "title": "Provenance", + "detail": "Reproduce the record" + }, + { + "title": "Limits", + "detail": "Avoid overclaiming" + } + ] + }, + "07-agentic-engineering": { + "message": "Agent-assisted work still requires a bounded task, visible changes, and engineering review.", + "tiles": [ + { + "title": "Scope", + "detail": "Choose an achievable task" + }, + { + "title": "Context", + "detail": "Provide trusted inputs" + }, + { + "title": "Authority", + "detail": "Limit permitted actions" + }, + { + "title": "Proposal", + "detail": "Inspect changed artifacts" + }, + { + "title": "Checks", + "detail": "Test the outcomes" + }, + { + "title": "Review", + "detail": "Keep human responsibility" + } + ] + }, + "08-engineering-context": { + "message": "Agents need engineering meaning, applicable sources, and clear boundaries—not just files.", + "tiles": [ + { + "title": "Sources", + "detail": "Find authoritative records" + }, + { + "title": "Vocabulary", + "detail": "Understand technical terms" + }, + { + "title": "Decisions", + "detail": "Read rationale" + }, + { + "title": "Constraints", + "detail": "Respect assumptions" + }, + { + "title": "Tools", + "detail": "Know available capabilities" + }, + { + "title": "Authority", + "detail": "Separate assistance from approval" + } + ] + }, + "09-continuous-engineering": { + "message": "Fast digital feedback helps teams learn while physical integration and qualification follow their own constraints.", + "tiles": [ + { + "title": "Revision", + "detail": "Track what changed" + }, + { + "title": "Build", + "detail": "Run reproducible checks" + }, + { + "title": "Feedback", + "detail": "Detect failures quickly" + }, + { + "title": "Integration", + "detail": "Combine disciplines" + }, + { + "title": "Evidence", + "detail": "Retain actual outcomes" + }, + { + "title": "Cadence", + "detail": "Respect physical lead times" + } + ] + }, + "10-governance-assurance": { + "message": "Engineering confidence comes from appropriate checks, evidence, review and accountable decisions.", + "tiles": [ + { + "title": "Claims", + "detail": "State the assertion" + }, + { + "title": "Controls", + "detail": "Apply relevant safeguards" + }, + { + "title": "Evidence", + "detail": "Inspect supporting results" + }, + { + "title": "Gaps", + "detail": "Recognize unknowns" + }, + { + "title": "Authority", + "detail": "Identify decision makers" + }, + { + "title": "Review", + "detail": "Record justified outcomes" + } + ] + }, + "11-engineering-knowledge": { + "message": "Engineering knowledge can be reused when versions, configurations and evidence applicability remain clear.", + "tiles": [ + { + "title": "Identity", + "detail": "Distinguish objects" + }, + { + "title": "Revision", + "detail": "Track change history" + }, + { + "title": "Configuration", + "detail": "Identify full variants" + }, + { + "title": "Evidence", + "detail": "Associate actual results" + }, + { + "title": "Reuse", + "detail": "Assess applicability" + }, + { + "title": "Lifecycle", + "detail": "Maintain coherence" + } + ] + }, + "12-integrated-environment": { + "message": "Planning, definitions, implementation and evidence form an inspectable engineering learning loop.", + "tiles": [ + { + "title": "Intent", + "detail": "Start from a need" + }, + { + "title": "Model", + "detail": "Explore an idea" + }, + { + "title": "Specify", + "detail": "Bound the increment" + }, + { + "title": "Integrate", + "detail": "Implement and check" + }, + { + "title": "Evidence", + "detail": "Qualify observed results" + }, + { + "title": "Learn", + "detail": "Return findings to planning" + } + ] + }, + "v2/05-engineering-data": { + "message": "Engineering data become valuable through checks, annotations, enrichment, visualization, critical review and preservation.", + "tiles": [ + { + "title": "Quality", + "detail": "Check units, gaps and validity" + }, + { + "title": "Annotate", + "detail": "Record context and assumptions" + }, + { + "title": "Enrich", + "detail": "Join and derive data" + }, + { + "title": "Visualize", + "detail": "Investigate behavior and margins" + }, + { + "title": "Review", + "detail": "Qualify technical conclusions" + }, + { + "title": "Preserve", + "detail": "Retain reproducible assets" + } + ] + } +}; From 6e0505709c5a2b1b159b98d5a2a486c15e8b68f0 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:28:41 +0100 Subject: [PATCH 03/32] feat: add reusable engineering chapter at-a-glance intro --- site/src/components/ChapterAtAGlance.astro | 41 ++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 site/src/components/ChapterAtAGlance.astro diff --git a/site/src/components/ChapterAtAGlance.astro b/site/src/components/ChapterAtAGlance.astro new file mode 100644 index 0000000..11c2cc6 --- /dev/null +++ b/site/src/components/ChapterAtAGlance.astro @@ -0,0 +1,41 @@ +--- +import { chapterGlances } from '../data/chapter-glances'; +interface Props { slug: string } +const { slug } = Astro.props; +const glance = chapterGlances[slug]; +--- +{glance &&
+
+ Chapter at a Glance +

{glance.message}

+
+ +
} + From 6df70a331a3b95842e89fa1febf70cb1cd0d57a8 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:28:54 +0100 Subject: [PATCH 04/32] feat: insert at-a-glance intro in published lesson layout --- site/src/layouts/Layout.astro | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/site/src/layouts/Layout.astro b/site/src/layouts/Layout.astro index fc813f5..e329c05 100644 --- a/site/src/layouts/Layout.astro +++ b/site/src/layouts/Layout.astro @@ -1,7 +1,9 @@ --- +import ChapterAtAGlance from '../components/ChapterAtAGlance.astro'; interface Props { title: string } const { title } = Astro.props; const base = import.meta.env.BASE_URL; +const chapterSlug = Astro.url.pathname.split('/learn/')[1]?.replace(/\/$/, '') || ''; --- @@ -17,7 +19,7 @@ const base = import.meta.env.BASE_URL; Executable Engineering Lab -
+
{chapterSlug && }
From 0af419e8595c414e0b538f443be1787315f3448c Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:29:28 +0100 Subject: [PATCH 05/32] docs(v2): make data enrichment chapter fifth in proposed curriculum --- site/src/data/v2-curriculum.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/src/data/v2-curriculum.ts b/site/src/data/v2-curriculum.ts index c879a55..e0a66c6 100644 --- a/site/src/data/v2-curriculum.ts +++ b/site/src/data/v2-curriculum.ts @@ -1,7 +1,7 @@ /** Proposed v2 structure only. These titles are not completed routes or engineering definitions. */ export const v2Parts = [ { start: 1, title: 'Part I · Engineering in the Age of AI', message: 'Why engineering is changing — and how to plan under uncertainty.', chapters: ['The New Engineering Paradigm', 'Planning Under Uncertainty'] }, - { start: 3, title: 'Part II · Building Engineering Knowledge', message: 'Connect engineering information, test assumptions, and specify progressively.', chapters: ['Engineering Knowledge as Code', 'Learning Through Models and Prototypes', 'Spec-Driven Development Without Waterfall'] }, - { start: 6, title: 'Part III · Engineering with AI Agents', message: 'Direct bounded agent work and integrate small, reviewable increments.', chapters: ['Directing AI Engineering Agents', 'Engineering in Small, Reviewable Increments', 'Continuously Integrated Engineering'] }, - { start: 9, title: 'Part IV · Trust, Decisions and Evolution', message: 'Interpret evidence, govern change, and keep engineering knowledge coherent.', chapters: ['Verification, Validation and Engineering Evidence', 'Governance and Engineering Authority', 'Managing Engineering Knowledge at Scale', 'The AI-Native Engineering Environment'] }, + { start: 3, title: 'Part II · Building Engineering Knowledge', message: 'Connect engineering information, test assumptions, and specify progressively.', chapters: ['Engineering Knowledge as Code', 'Learning Through Models and Prototypes', 'Engineering Data: From Measurements to Decisions', 'Spec-Driven Development Without Waterfall'] }, + { start: 7, title: 'Part III · Engineering with AI Agents', message: 'Direct bounded agent work and integrate small, reviewable increments.', chapters: ['Directing AI Engineering Agents', 'Engineering in Small, Reviewable Increments', 'Continuously Integrated Engineering'] }, + { start: 10, title: 'Part IV · Trust, Decisions and Evolution', message: 'Interpret evidence, govern change, and keep engineering knowledge coherent.', chapters: ['Verification, Validation and Engineering Evidence', 'Governance and Engineering Authority', 'Managing Engineering Knowledge at Scale', 'The AI-Native Engineering Environment'] }, ] as const; From 5907689d46e470bebcbea3f4c03415755a1e3077 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:29:31 +0100 Subject: [PATCH 06/32] docs(v2): make data enrichment chapter fifth in proposed curriculum --- site/src/pages/learn/index.astro | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/src/pages/learn/index.astro b/site/src/pages/learn/index.astro index 1d9d025..e9d327c 100644 --- a/site/src/pages/learn/index.astro +++ b/site/src/pages/learn/index.astro @@ -8,7 +8,7 @@ const base = import.meta.env.BASE_URL;

Learn · Curriculum transition

Learn to engineer with AI — and maintain control.

-

The new twelve-chapter journey will connect planning, engineering knowledge, prototyping, progressive specifications, AI agents, integration and engineering evidence.

+

The new thirteen-chapter journey will connect planning, engineering knowledge, prototyping, progressive specifications, AI agents, integration and engineering evidence.

V2 course structure

Planned curriculum. Topics below are specifications, not yet published lessons. Go to the published lessons for working examples.

{v2Parts.map(part =>

{part.title}

    {part.chapters.map(title =>
  1. {title}
  2. )}
)}
From 3c214bd4112dda72a451299b693376cc8c27159f Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:29:35 +0100 Subject: [PATCH 07/32] docs(v2): make data enrichment chapter fifth in proposed curriculum --- project/TUTORIAL-SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project/TUTORIAL-SPEC.md b/project/TUTORIAL-SPEC.md index b6c120c..fb3815f 100644 --- a/project/TUTORIAL-SPEC.md +++ b/project/TUTORIAL-SPEC.md @@ -37,7 +37,7 @@ At the end readers can: ## Experience Main routes: Home / Learn / Lab / Explore / Reference. -Learn is a 12-chapter, four-part progression with independent entry points. +Learn is a 13-chapter, four-part progression with independent entry points. Lab hosts executable models and scenario investigations. Explore hosts digital-thread/change-impact and roadmap/decision contexts. Reference gives glossary, assumptions, source artifacts, model limitations and reproducibility. From fd729376aba4d5ba129c82337650d4b9cdd56195 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:29:59 +0100 Subject: [PATCH 08/32] docs(v2): integrate data enrichment into 13 chapter map --- project/CURRICULUM-MAP.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/project/CURRICULUM-MAP.md b/project/CURRICULUM-MAP.md index 10d91f6..49aa29f 100644 --- a/project/CURRICULUM-MAP.md +++ b/project/CURRICULUM-MAP.md @@ -1,4 +1,4 @@ -# Curriculum map — 12 chapters, four parts (v2.0) +# Curriculum map — 13 chapters, four parts (v2.0) Status: proposed. Routes below are targets; **do not assume they exist**. | Part | # | Chapter | Distinct learning gain | Demonstration | @@ -7,24 +7,25 @@ Status: proposed. Routes below are targets; **do not assume they exist**. | I | 02 | Planning Under Uncertainty | Separate exploration from committed increments | DMS roadmap/option planning | | II — Learn and specify | 03 | Engineering Knowledge as Code | Explain cross-discipline source relationships | Interactive change-impact graph | | II | 04 | Learning Through Models and Prototypes | Qualify model fidelity and experiment results | Sensor/electronics/mount options | -| II | 05 | Spec-Driven Development Without Waterfall | Progressively specify the next slice | Hypothesis→spec decision studio | +| II | 05 | Engineering Data: From Measurements to Decisions | Curate, annotate, enrich, visualize, review, preserve and reuse engineering data | DMS simulated parameter study + synthetic cross-discipline constraints | +| II | 06 | Spec-Driven Development Without Waterfall | Progressively specify the next slice | Hypothesis→spec decision studio | | III — Act with agents | 06 | Directing AI Engineering Agents | Define agent scope, context, authority | Authentic run replay / contract | -| III | 07 | Engineering in Small, Reviewable Increments | Design meaningful, limited integration slices | Compare large PR vs split PRs | -| III | 08 | Continuously Integrated Engineering | Differentiate digital CI, hardware baselines and qualification | Multidiscipline integration dashboard | +| III | 08 | Engineering in Small, Reviewable Increments | Design meaningful, limited integration slices | Compare large PR vs split PRs | +| III | 09 | Continuously Integrated Engineering | Differentiate digital CI, hardware baselines and qualification | Multidiscipline integration dashboard | | IV — Decide and scale | 09 | Verification, Validation and Engineering Evidence | Reason from claim to relevant evidence | Claim/evidence assessment | -| IV | 10 | Governance and Engineering Authority | Distinguish checks, permissions and approval | Review gate / authority simulation | -| IV | 11 | Managing Engineering Knowledge at Scale | Track configurations, reuse and supplier interfaces | Variant/baseline comparison | -| IV | 12 | The AI-Native Engineering Environment | Synthesize integrated workflow | End-to-end DMS engineering case | +| IV | 11 | Governance and Engineering Authority | Distinguish checks, permissions and approval | Review gate / authority simulation | +| IV | 12 | Managing Engineering Knowledge at Scale | Track configurations, reuse and supplier interfaces | Variant/baseline comparison | +| IV | 13 | The AI-Native Engineering Environment | Synthesize integrated workflow | End-to-end DMS engineering case | ## Content dependency model 01→02 sets motive and direction. -02 feeds 03, 04 and 05 through uncertainty priorities. -03 provides controlled context for 04, 05 and 06. -04 gives observations for 05 and decisions for 02. -05 prepares a bounded task for 06–08. -06–08 deliver reviewable results and expose gaps to 09–10. -09–11 inform new decisions and future roadmaps. -12 integrates all, including open decisions. +02 feeds 03, 04, 05 and 06 through uncertainty priorities. +03 provides controlled context for 04, 05, 06 and 07. +04 produces model observations for 05; 05 enriches and reviews those data before feeding 06 and planning decisions. +06 prepares a bounded task for 07–09. +07–09 deliver reviewable results and expose gaps to 10–11. +10–12 inform new decisions and future roadmaps. +13 integrates all, including open decisions. **These arrows do not imply waterfall or mandatory course navigation.** ## Narrative controls From 9490e9a33716cc951381929c9fe3cb47dc8d6e52 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:30:13 +0100 Subject: [PATCH 09/32] fix: make proposed v2 chapter numbering contiguous --- project/CURRICULUM-MAP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/project/CURRICULUM-MAP.md b/project/CURRICULUM-MAP.md index 49aa29f..13b7f76 100644 --- a/project/CURRICULUM-MAP.md +++ b/project/CURRICULUM-MAP.md @@ -9,10 +9,10 @@ Status: proposed. Routes below are targets; **do not assume they exist**. | II | 04 | Learning Through Models and Prototypes | Qualify model fidelity and experiment results | Sensor/electronics/mount options | | II | 05 | Engineering Data: From Measurements to Decisions | Curate, annotate, enrich, visualize, review, preserve and reuse engineering data | DMS simulated parameter study + synthetic cross-discipline constraints | | II | 06 | Spec-Driven Development Without Waterfall | Progressively specify the next slice | Hypothesis→spec decision studio | -| III — Act with agents | 06 | Directing AI Engineering Agents | Define agent scope, context, authority | Authentic run replay / contract | +| III — Act with agents | 07 | Directing AI Engineering Agents | Define agent scope, context, authority | Authentic run replay / contract | | III | 08 | Engineering in Small, Reviewable Increments | Design meaningful, limited integration slices | Compare large PR vs split PRs | | III | 09 | Continuously Integrated Engineering | Differentiate digital CI, hardware baselines and qualification | Multidiscipline integration dashboard | -| IV — Decide and scale | 09 | Verification, Validation and Engineering Evidence | Reason from claim to relevant evidence | Claim/evidence assessment | +| IV — Decide and scale | 10 | Verification, Validation and Engineering Evidence | Reason from claim to relevant evidence | Claim/evidence assessment | | IV | 11 | Governance and Engineering Authority | Distinguish checks, permissions and approval | Review gate / authority simulation | | IV | 12 | Managing Engineering Knowledge at Scale | Track configurations, reuse and supplier interfaces | Variant/baseline comparison | | IV | 13 | The AI-Native Engineering Environment | Synthesize integrated workflow | End-to-end DMS engineering case | From 80ff300768a68381a5c069a4934a6358c9bd9380 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:31:45 +0100 Subject: [PATCH 10/32] feat(v2): add engineering-data chapter reader preview with calculated table --- .../pages/learn/v2/05-engineering-data.astro | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 site/src/pages/learn/v2/05-engineering-data.astro diff --git a/site/src/pages/learn/v2/05-engineering-data.astro b/site/src/pages/learn/v2/05-engineering-data.astro new file mode 100644 index 0000000..bff600c --- /dev/null +++ b/site/src/pages/learn/v2/05-engineering-data.astro @@ -0,0 +1,60 @@ +--- +import Layout from '../../../layouts/Layout.astro'; +import { calculateCoverage, MODEL_VERSION, GRID_WIDTH, GRID_HEIGHT } from '../../../../../models/coverage/coverage'; +import { evaluateCoverage } from '../../../../../models/coverage/evaluate'; +const base = import.meta.env.BASE_URL; +const threshold = 50; +const variants = [ + { id: 'ILL-A', radius: 35, demand: 80, mount: 'Candidate fixture' }, + { id: 'ILL-B', radius: 45, demand: 130, mount: 'Candidate fixture' }, + { id: 'ILL-C', radius: 50, demand: 110, mount: 'Requires review' }, +] as const; +const budget = 120; // illustrative, not a measured equipment constraint +const rows = variants.map(v => { + const output = calculateCoverage({ area: { width: 100, height: 100 }, sensor: { x: 50, y: 50, radius: v.radius } }); + const verdict = evaluateCoverage(output, threshold); + return { ...v, coverage: output.coveragePercent, margin: verdict.marginPercentagePoints, satisfiesGeometry: verdict.pass, powerMargin: budget - v.demand }; +}); +const format = (value: number) => value.toFixed(2); +--- + +
+

Proposed v2 · Part II · Chapter 05 · Reader preview

+

Engineering Data: From Measurements to Decisions

+

A result is not the same as understanding. How do we turn technical observations and calculations into data that can support an engineering decision?

+

This is a draft v2 lesson preview. The original twelve lessons and the verified V0 model are preserved. The complete editorial manuscript is maintained in the chapter brief in the repository.

+

Six complementary practices

+

Quality: Check units, completeness, plausible ranges and configuration compatibility. Annotation: Explain which inputs, methods and assumptions produced each result. Enrichment: Add reference information, associations and derived properties. Visualization: Investigate patterns and constraints, not only communicate results. Review: Challenge an apparent conclusion against alternative explanations and missing evidence. Preservation: Keep original data, curated data and derived results linked to the method and revision that produced them.

+

An illustrative cross-discipline comparison

+

The following geometric percentages are calculated during this site build with the existing V0 model ({MODEL_VERSION}, {GRID_WIDTH} × {GRID_HEIGHT} cell-center sampling). They describe ideal area coverage in generic model units—not detection probability or measured hardware performance.

+

Power demands and the {budget} W budget are fictional planning assumptions introduced solely to illustrate enrichment across domains. There are no physical measurements, supplier specifications, or actual mounting assessments for these variants.

+
+ + + + + {rows.map(row => )} + +
Calculated V0 geometric outputs joined with hypothetical power-budget assumptions
Illustrative variantRadius (model units)Modeled coverageCoverage margin (pp)Fictional power demandPower marginInstallation note
{row.id}{row.radius}{format(row.coverage)}%{format(row.margin)}{row.demand} W{row.powerMargin} W{row.mount}
+
+

Consider the two margins separately. Coverage margin is the unrounded modeled percentage minus the 50% educational criterion, in percentage points. Power margin is the invented 120 W planning budget minus the invented demand, in watts. Both are calculated consistently; only the geometric result is generated from the canonical model. No engineering conclusion about real equipment follows from the fictional power values.

+

Which data became more valuable?

+

The geometric analysis produces one result per explicitly defined scenario. The added variant notes and synthetic power table create a new view of potential trade-offs. But a safe join requires matching configuration identity, not a guessed name. A missing or mismatched ID is an unresolved data issue—not an invitation to fill the gap automatically.

+

The displayed table is an inspectable build-time snapshot rather than a live experiment or certification record. It is not a physical test. An engineer can now ask whether another variant deserves exploration, but cannot approve an installation based on this table. That would require actual electrical and mechanical data, relevant operating conditions, credible models and appropriate verification.

+

Preserve the question as well as the answer

+

A reusable engineering data asset includes source definitions, units, configuration identities, quality notes, proposed annotations, derived calculations, method version and limitations. A knowledge catalogue can help future engineers locate the assets and understand whether they apply to a new scenario. Raw records and curated data should remain distinguishable, so a later reviewer can reproduce or challenge the result.

+

AI can help extract metadata, propose labels, find outliers and suggest candidate comparisons. It cannot quietly turn an assumed sensing radius or a fictional power budget into measured truth. Keep AI suggestions inspectable and subject to engineering review.

+

The next decision

+

Which uncertainty should we reduce next: coverage under a more credible model, a real equipment power budget, or mechanical integration feasibility? Data enrichment improves the question and the available options. It does not bypass the need for engineering judgment and new evidence.

+

Return to the v2 learning map · Inspect the original V0 simulation

+
+
+ From 1e004f26af4684e58a0c596b07225f2485d8d96a Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:28 +0100 Subject: [PATCH 11/32] docs(v2): shift proposed chapter brief 06 --- ...ec-driven-development-without-waterfall.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/06-spec-driven-development-without-waterfall.md diff --git a/chapters/06-spec-driven-development-without-waterfall.md b/chapters/06-spec-driven-development-without-waterfall.md new file mode 100644 index 0000000..21ddcb8 --- /dev/null +++ b/chapters/06-spec-driven-development-without-waterfall.md @@ -0,0 +1,49 @@ +# Chapter 06 — Spec-Driven Development Without Waterfall +Status: v2 implementation brief (proposed) +Part: II — Building Engineering Knowledge + +## The one question +How can we give agents enough structure without specifying an unknown system upfront? + +## What the reader must gain +Practice progressive specification; distinguish stable intent, uncertain design, acceptance conditions and authorized scope; explain dual loops. + +## Opening engineering situation +Convert coverage-and-power initiative into one bounded next capability while retaining open alternative options for future experiments. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Specification maturity studio: turn a vague initiative into a short slice spec, mark unresolved assumptions and reviewer gates. + +## Reuse and migration from v1 +Substantial new material; draw source-contract material from old Ch 2 and task-contract discussion from old Ch 7. + +## Technical/editorial constraints +Include sample real-world spec template, protected acceptance criteria, no big design-upfront plan, tool examples optional. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +The spec defines a task, but how does the agent access context and perform it within limits? From 2e06bb7ccd18db7b0b776d56bb0b98bdf286f6aa Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:30 +0100 Subject: [PATCH 12/32] docs(v2): retire superseded brief filename 05-spec-driven-development-without-waterfall.md --- ...ec-driven-development-without-waterfall.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/05-spec-driven-development-without-waterfall.md diff --git a/chapters/05-spec-driven-development-without-waterfall.md b/chapters/05-spec-driven-development-without-waterfall.md deleted file mode 100644 index 6d9c0d2..0000000 --- a/chapters/05-spec-driven-development-without-waterfall.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 05 — Spec-Driven Development Without Waterfall -Status: v2 implementation brief (proposed) -Part: II — Building Engineering Knowledge - -## The one question -How can we give agents enough structure without specifying an unknown system upfront? - -## What the reader must gain -Practice progressive specification; distinguish stable intent, uncertain design, acceptance conditions and authorized scope; explain dual loops. - -## Opening engineering situation -Convert coverage-and-power initiative into one bounded next capability while retaining open alternative options for future experiments. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Specification maturity studio: turn a vague initiative into a short slice spec, mark unresolved assumptions and reviewer gates. - -## Reuse and migration from v1 -Substantial new material; draw source-contract material from old Ch 2 and task-contract discussion from old Ch 7. - -## Technical/editorial constraints -Include sample real-world spec template, protected acceptance criteria, no big design-upfront plan, tool examples optional. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -The spec defines a task, but how does the agent access context and perform it within limits? From 7790d56e0849eacbfd6b0b61b67d938144e746d9 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:33 +0100 Subject: [PATCH 13/32] docs(v2): shift proposed chapter brief 07 --- .../07-directing-ai-engineering-agents.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/07-directing-ai-engineering-agents.md diff --git a/chapters/07-directing-ai-engineering-agents.md b/chapters/07-directing-ai-engineering-agents.md new file mode 100644 index 0000000..06b8f74 --- /dev/null +++ b/chapters/07-directing-ai-engineering-agents.md @@ -0,0 +1,49 @@ +# Chapter 07 — Directing AI Engineering Agents +Status: v2 implementation brief (proposed) +Part: III — Engineering with AI Agents + +## The one question +What can an agent do on our behalf, and how do we know what actually happened? + +## What the reader must gain +Set task objective, sources, permissions, tool boundaries, stop conditions and review deliverable; distinguish agent narration from trace and evidence. + +## Opening engineering situation +Agent investigates a bounded DMS proposal, reads approved sources, modifies an isolated fixture, runs checks and opens a reviewable diff. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Inspect an *authentic captured* agent run: instructions, tool calls, sources read, diff, verification, human review; optional labeled mock until recorded. + +## Reuse and migration from v1 +Consolidate old Ch 7 and Ch 8; stop repeating radius/threshold exercise as main interaction. + +## Technical/editorial constraints +Never invent transcript or imply active AI runtime. Secrets sanitized. Agent may not change criterion or approve itself. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +Even with correct boundaries, a single large change can overwhelm a reviewer. How should we divide work? From 9e70aca71aa00a33561e0371c44f7710080793f5 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:35 +0100 Subject: [PATCH 14/32] docs(v2): retire superseded brief filename 06-directing-ai-engineering-agents.md --- .../06-directing-ai-engineering-agents.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/06-directing-ai-engineering-agents.md diff --git a/chapters/06-directing-ai-engineering-agents.md b/chapters/06-directing-ai-engineering-agents.md deleted file mode 100644 index d4ecc9c..0000000 --- a/chapters/06-directing-ai-engineering-agents.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 06 — Directing AI Engineering Agents -Status: v2 implementation brief (proposed) -Part: III — Engineering with AI Agents - -## The one question -What can an agent do on our behalf, and how do we know what actually happened? - -## What the reader must gain -Set task objective, sources, permissions, tool boundaries, stop conditions and review deliverable; distinguish agent narration from trace and evidence. - -## Opening engineering situation -Agent investigates a bounded DMS proposal, reads approved sources, modifies an isolated fixture, runs checks and opens a reviewable diff. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Inspect an *authentic captured* agent run: instructions, tool calls, sources read, diff, verification, human review; optional labeled mock until recorded. - -## Reuse and migration from v1 -Consolidate old Ch 7 and Ch 8; stop repeating radius/threshold exercise as main interaction. - -## Technical/editorial constraints -Never invent transcript or imply active AI runtime. Secrets sanitized. Agent may not change criterion or approve itself. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -Even with correct boundaries, a single large change can overwhelm a reviewer. How should we divide work? From a7f7f04ac7257e6e114b5ae68c4409c53b64b6ba Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:38 +0100 Subject: [PATCH 15/32] docs(v2): shift proposed chapter brief 08 --- ...ineering-in-small-reviewable-increments.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/08-engineering-in-small-reviewable-increments.md diff --git a/chapters/08-engineering-in-small-reviewable-increments.md b/chapters/08-engineering-in-small-reviewable-increments.md new file mode 100644 index 0000000..81fd37f --- /dev/null +++ b/chapters/08-engineering-in-small-reviewable-increments.md @@ -0,0 +1,49 @@ +# Chapter 08 — Engineering in Small, Reviewable Increments +Status: v2 implementation brief (proposed) +Part: III — Engineering with AI Agents + +## The one question +How do we prevent fast AI output from becoming opaque engineering change? + +## What the reader must gain +Design vertical increments and architectural boundaries; compare PR review burden and feedback; include cross-discipline interfaces. + +## Opening engineering situation +Contrast a hypothetical 3,000-line monolithic change with small feature slices: interface definition, calculation, UI and test, plus separately reviewed hardware interface decision. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Interactive change-review storyboard, scoped diff examples and pass/fail checks at each slice. + +## Reuse and migration from v1 +Major new content; use existing GitHub checks in old Ch 9 as supporting reference. + +## Technical/editorial constraints +Synthetic PR examples must be labeled; if showing true historical changes, link to commits/PRs. Hardware fabrication is not a daily software PR. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +Once small changes enter the repository, what must be checked continuously across disciplines? From 40be39413e8f3da40f8968324bde176b2ea82f74 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:40 +0100 Subject: [PATCH 16/32] docs(v2): retire superseded brief filename 07-engineering-in-small-reviewable-increments.md --- ...ineering-in-small-reviewable-increments.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/07-engineering-in-small-reviewable-increments.md diff --git a/chapters/07-engineering-in-small-reviewable-increments.md b/chapters/07-engineering-in-small-reviewable-increments.md deleted file mode 100644 index 036a022..0000000 --- a/chapters/07-engineering-in-small-reviewable-increments.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 07 — Engineering in Small, Reviewable Increments -Status: v2 implementation brief (proposed) -Part: III — Engineering with AI Agents - -## The one question -How do we prevent fast AI output from becoming opaque engineering change? - -## What the reader must gain -Design vertical increments and architectural boundaries; compare PR review burden and feedback; include cross-discipline interfaces. - -## Opening engineering situation -Contrast a hypothetical 3,000-line monolithic change with small feature slices: interface definition, calculation, UI and test, plus separately reviewed hardware interface decision. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Interactive change-review storyboard, scoped diff examples and pass/fail checks at each slice. - -## Reuse and migration from v1 -Major new content; use existing GitHub checks in old Ch 9 as supporting reference. - -## Technical/editorial constraints -Synthetic PR examples must be labeled; if showing true historical changes, link to commits/PRs. Hardware fabrication is not a daily software PR. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -Once small changes enter the repository, what must be checked continuously across disciplines? From 83eb3bdd85c9ad559155deda291470c99b0dd674 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:42 +0100 Subject: [PATCH 17/32] docs(v2): shift proposed chapter brief 09 --- .../09-continuously-integrated-engineering.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/09-continuously-integrated-engineering.md diff --git a/chapters/09-continuously-integrated-engineering.md b/chapters/09-continuously-integrated-engineering.md new file mode 100644 index 0000000..befd69a --- /dev/null +++ b/chapters/09-continuously-integrated-engineering.md @@ -0,0 +1,49 @@ +# Chapter 09 — Continuously Integrated Engineering +Status: v2 implementation brief (proposed) +Part: III — Engineering with AI Agents + +## The one question +What can be continuously integrated when physical products evolve on different timescales? + +## What the reader must gain +Differentiate source validation, model/test CI, software releasability, electronics/mechanical baselines and physical qualification; understand readiness by claim. + +## Opening engineering situation +DMS model and software pass CI; mechanical mount unresolved; electronics interface checked; environmental test not yet run. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Engineering readiness dashboard with distinct statuses and evidence provenance; genuine CI links for V0. + +## Reuse and migration from v1 +Develop old Ch 9; fold in verification/check distinction from old Ch 6. + +## Technical/editorial constraints +Never fake green checks. UI must separate synthetic illustrative states from actual recorded CI. Different lead times explicit. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +A green dashboard is not yet proof that the operational need is satisfied. What evidence is sufficient? From 0f2ed4405acdc2b1f9d7e2549933c45d11f549d7 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:45 +0100 Subject: [PATCH 18/32] docs(v2): retire superseded brief filename 08-continuously-integrated-engineering.md --- .../08-continuously-integrated-engineering.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/08-continuously-integrated-engineering.md diff --git a/chapters/08-continuously-integrated-engineering.md b/chapters/08-continuously-integrated-engineering.md deleted file mode 100644 index e8768bf..0000000 --- a/chapters/08-continuously-integrated-engineering.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 08 — Continuously Integrated Engineering -Status: v2 implementation brief (proposed) -Part: III — Engineering with AI Agents - -## The one question -What can be continuously integrated when physical products evolve on different timescales? - -## What the reader must gain -Differentiate source validation, model/test CI, software releasability, electronics/mechanical baselines and physical qualification; understand readiness by claim. - -## Opening engineering situation -DMS model and software pass CI; mechanical mount unresolved; electronics interface checked; environmental test not yet run. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Engineering readiness dashboard with distinct statuses and evidence provenance; genuine CI links for V0. - -## Reuse and migration from v1 -Develop old Ch 9; fold in verification/check distinction from old Ch 6. - -## Technical/editorial constraints -Never fake green checks. UI must separate synthetic illustrative states from actual recorded CI. Different lead times explicit. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -A green dashboard is not yet proof that the operational need is satisfied. What evidence is sufficient? From 4797e20f04ca5398f7861e7fd6d522f778795389 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:48 +0100 Subject: [PATCH 19/32] docs(v2): shift proposed chapter brief 10 --- ...ion-validation-and-engineering-evidence.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/10-verification-validation-and-engineering-evidence.md diff --git a/chapters/10-verification-validation-and-engineering-evidence.md b/chapters/10-verification-validation-and-engineering-evidence.md new file mode 100644 index 0000000..1a0a4eb --- /dev/null +++ b/chapters/10-verification-validation-and-engineering-evidence.md @@ -0,0 +1,49 @@ +# Chapter 10 — Verification, Validation and Engineering Evidence +Status: v2 implementation brief (proposed) +Part: IV — Trust, Decisions and Evolution + +## The one question +What exactly do our tests and experiments establish about system effectiveness? + +## What the reader must gain +Distinguish software regression, model validation, requirement verification and operational validation; reason through claim/argument/evidence. + +## Opening engineering situation +A geometry model passes an educational threshold in an exploratory proposal but lacks sensor characterization and field testing. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Claim–evidence builder with applicability and gap flags; keep original baseline engineering FAIL and software-test PASS distinct. + +## Reuse and migration from v1 +Refactor old Ch 6, 10 and Ch 1 evidence sections. + +## Technical/editorial constraints +Evidence bound to revision, inputs, assumptions and method. Physical test not done means NOT VERIFIED, never green. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +When evidence is partial, who has authority to accept risks and authorize the next step? From 7453a42d38ace1dc7482d3ec2be6ed612dd6b5b9 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:50 +0100 Subject: [PATCH 20/32] docs(v2): retire superseded brief filename 09-verification-validation-and-engineering-evidence.md --- ...ion-validation-and-engineering-evidence.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/09-verification-validation-and-engineering-evidence.md diff --git a/chapters/09-verification-validation-and-engineering-evidence.md b/chapters/09-verification-validation-and-engineering-evidence.md deleted file mode 100644 index ac21c83..0000000 --- a/chapters/09-verification-validation-and-engineering-evidence.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 09 — Verification, Validation and Engineering Evidence -Status: v2 implementation brief (proposed) -Part: IV — Trust, Decisions and Evolution - -## The one question -What exactly do our tests and experiments establish about system effectiveness? - -## What the reader must gain -Distinguish software regression, model validation, requirement verification and operational validation; reason through claim/argument/evidence. - -## Opening engineering situation -A geometry model passes an educational threshold in an exploratory proposal but lacks sensor characterization and field testing. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Claim–evidence builder with applicability and gap flags; keep original baseline engineering FAIL and software-test PASS distinct. - -## Reuse and migration from v1 -Refactor old Ch 6, 10 and Ch 1 evidence sections. - -## Technical/editorial constraints -Evidence bound to revision, inputs, assumptions and method. Physical test not done means NOT VERIFIED, never green. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -When evidence is partial, who has authority to accept risks and authorize the next step? From bed6b9b3d6f2bf6fca47eb0ce169aa6b5c824272 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:53 +0100 Subject: [PATCH 21/32] docs(v2): shift proposed chapter brief 11 --- ...11-governance-and-engineering-authority.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/11-governance-and-engineering-authority.md diff --git a/chapters/11-governance-and-engineering-authority.md b/chapters/11-governance-and-engineering-authority.md new file mode 100644 index 0000000..1d49abe --- /dev/null +++ b/chapters/11-governance-and-engineering-authority.md @@ -0,0 +1,49 @@ +# Chapter 11 — Governance and Engineering Authority +Status: v2 implementation brief (proposed) +Part: IV — Trust, Decisions and Evolution + +## The one question +How can engineering teams govern AI proposals without blocking useful exploration? + +## What the reader must gain +Define human/agent authority, proposal vs approval, automated policy vs judgment, safety/compliance and control cases. + +## Opening engineering situation +One proposal changes sensor hardware interface; decide what an agent can alter in sandbox and what requires interface-owner approval. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Interactive decision/authority matrix and change gate; introduce Gemara as optional reference. + +## Reuse and migration from v1 +Refactor old Ch 10 and authority sections of Ch 7–8. + +## Technical/editorial constraints +Distinguish described policy and technically enforced permission; no fictional certification or automatic approval. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +Approved and proposed changes span baselines and suppliers. How do we maintain knowledge over time? From f59e0b7a71e6628a0f5236a5c1379722900b7f5c Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:55 +0100 Subject: [PATCH 22/32] docs(v2): retire superseded brief filename 10-governance-and-engineering-authority.md --- ...10-governance-and-engineering-authority.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/10-governance-and-engineering-authority.md diff --git a/chapters/10-governance-and-engineering-authority.md b/chapters/10-governance-and-engineering-authority.md deleted file mode 100644 index 2008abf..0000000 --- a/chapters/10-governance-and-engineering-authority.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 10 — Governance and Engineering Authority -Status: v2 implementation brief (proposed) -Part: IV — Trust, Decisions and Evolution - -## The one question -How can engineering teams govern AI proposals without blocking useful exploration? - -## What the reader must gain -Define human/agent authority, proposal vs approval, automated policy vs judgment, safety/compliance and control cases. - -## Opening engineering situation -One proposal changes sensor hardware interface; decide what an agent can alter in sandbox and what requires interface-owner approval. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Interactive decision/authority matrix and change gate; introduce Gemara as optional reference. - -## Reuse and migration from v1 -Refactor old Ch 10 and authority sections of Ch 7–8. - -## Technical/editorial constraints -Distinguish described policy and technically enforced permission; no fictional certification or automatic approval. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -Approved and proposed changes span baselines and suppliers. How do we maintain knowledge over time? From 7867d015d38c51f99bb401fa6f931953b7c44bbe Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:33:58 +0100 Subject: [PATCH 23/32] docs(v2): shift proposed chapter brief 12 --- ...managing-engineering-knowledge-at-scale.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/12-managing-engineering-knowledge-at-scale.md diff --git a/chapters/12-managing-engineering-knowledge-at-scale.md b/chapters/12-managing-engineering-knowledge-at-scale.md new file mode 100644 index 0000000..5d2c0ae --- /dev/null +++ b/chapters/12-managing-engineering-knowledge-at-scale.md @@ -0,0 +1,49 @@ +# Chapter 12 — Managing Engineering Knowledge at Scale +Status: v2 implementation brief (proposed) +Part: IV — Trust, Decisions and Evolution + +## The one question +Can we reuse a conclusion when requirements, suppliers and configurations have evolved? + +## What the reader must gain +Distinguish identity, revision and configuration; assess evidence applicability, variants and supplier/interface mismatches. + +## Opening engineering situation +Compare two DMS variants with different electronics revision, mount configuration and algorithm version. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Variant comparison with explicit dependency/re-use warnings and source snapshot links. + +## Reuse and migration from v1 +Refactor old Ch 11 and Ch 3 chain reasoning, remove duplicate disclaimer passages. + +## Technical/editorial constraints +Do not imply scale benchmarks without dataset; explain where physical hardware configuration control differs from Git commit. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +With planning, modeling, agents and evidence connected, what does the full engineering workflow look like? From 75c5c48b27bd977c08d26ac0cf05dcc0fe5ed7ac Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:34:14 +0100 Subject: [PATCH 24/32] docs(v2): shift brief to chapter 13 --- ...3-the-ai-native-engineering-environment.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 chapters/13-the-ai-native-engineering-environment.md diff --git a/chapters/13-the-ai-native-engineering-environment.md b/chapters/13-the-ai-native-engineering-environment.md new file mode 100644 index 0000000..48e4423 --- /dev/null +++ b/chapters/13-the-ai-native-engineering-environment.md @@ -0,0 +1,49 @@ +# Chapter 13 — The AI-Native Engineering Environment +Status: v2 implementation brief (proposed) +Part: IV — Trust, Decisions and Evolution + +## The one question +Can another engineering team follow one initiative from uncertainty to trustworthy capability? + +## What the reader must gain +Integrate roadmap, hypothesis, data, experiments, progressive specification, agent actions, review, CI, engineering authority and evolving evidence. + +## Opening engineering situation +End-to-end DMS initiative: coverage improvement explored → trade-off → chosen next slice → actual bounded agent PR/run → digital checks → pending physical gates → next roadmap learning. + +## Narrative arc +1. Start with a concrete decision or unexpected constraint, not a definition. +2. Show why the current working practice is insufficient for this question. +3. Introduce only the concepts needed to reason about it. +4. Let the reader examine a clear example and make a prediction/choice. +5. Interpret the outcome, including limitations and authority. +6. Connect the decision to the next engineering question. + +## Primary learning experience +Navigable end-to-end case map with one authentic record and transparent fictional assumptions; brief capstone decision, not another radius worksheet. + +## Reuse and migration from v1 +Old Ch 12 provides handover/evidence ideas only; substantially new integrated narrative. + +## Technical/editorial constraints +No claim of fielded DMS or completed physical qualification. Show the unfinished decision and why it matters. + +## Suggested article skeleton +- Opening question and scenario +- Why the usual approach is difficult here +- A new engineering capability or method +- The demonstration and what to look for +- How to interpret results and unresolved uncertainty +- A short engineering takeaway +- Next question / suggested deeper reference + +## Verification and acceptance +- The main question can be answered by a reader using the chapter, without prior local setup. +- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. +- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. +- A meaningful link exists to canonical or clearly illustrative source information. +- Text, controls and results work with keyboard/screen reader as applicable. +- Existing V0 technical checks and old deep links remain intact following migration. + +## Bridge +Conclude with an actionable adoption checklist; invite adaptation to reader's engineering context. From 8e5fc834989668f0caebe0486da3a557e01840e7 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:34:17 +0100 Subject: [PATCH 25/32] docs(v2): retire previous brief path --- ...2-the-ai-native-engineering-environment.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/12-the-ai-native-engineering-environment.md diff --git a/chapters/12-the-ai-native-engineering-environment.md b/chapters/12-the-ai-native-engineering-environment.md deleted file mode 100644 index 2dfdf4c..0000000 --- a/chapters/12-the-ai-native-engineering-environment.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 12 — The AI-Native Engineering Environment -Status: v2 implementation brief (proposed) -Part: IV — Trust, Decisions and Evolution - -## The one question -Can another engineering team follow one initiative from uncertainty to trustworthy capability? - -## What the reader must gain -Integrate roadmap, hypothesis, data, experiments, progressive specification, agent actions, review, CI, engineering authority and evolving evidence. - -## Opening engineering situation -End-to-end DMS initiative: coverage improvement explored → trade-off → chosen next slice → actual bounded agent PR/run → digital checks → pending physical gates → next roadmap learning. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Navigable end-to-end case map with one authentic record and transparent fictional assumptions; brief capstone decision, not another radius worksheet. - -## Reuse and migration from v1 -Old Ch 12 provides handover/evidence ideas only; substantially new integrated narrative. - -## Technical/editorial constraints -No claim of fielded DMS or completed physical qualification. Show the unfinished decision and why it matters. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -Conclude with an actionable adoption checklist; invite adaptation to reader's engineering context. From 6554a02af59b284089bf57ab59f3b8651dc04e72 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:34:34 +0100 Subject: [PATCH 26/32] docs(v2): remove superseded chapter 11 brief --- ...managing-engineering-knowledge-at-scale.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 chapters/11-managing-engineering-knowledge-at-scale.md diff --git a/chapters/11-managing-engineering-knowledge-at-scale.md b/chapters/11-managing-engineering-knowledge-at-scale.md deleted file mode 100644 index b2c8c42..0000000 --- a/chapters/11-managing-engineering-knowledge-at-scale.md +++ /dev/null @@ -1,49 +0,0 @@ -# Chapter 11 — Managing Engineering Knowledge at Scale -Status: v2 implementation brief (proposed) -Part: IV — Trust, Decisions and Evolution - -## The one question -Can we reuse a conclusion when requirements, suppliers and configurations have evolved? - -## What the reader must gain -Distinguish identity, revision and configuration; assess evidence applicability, variants and supplier/interface mismatches. - -## Opening engineering situation -Compare two DMS variants with different electronics revision, mount configuration and algorithm version. - -## Narrative arc -1. Start with a concrete decision or unexpected constraint, not a definition. -2. Show why the current working practice is insufficient for this question. -3. Introduce only the concepts needed to reason about it. -4. Let the reader examine a clear example and make a prediction/choice. -5. Interpret the outcome, including limitations and authority. -6. Connect the decision to the next engineering question. - -## Primary learning experience -Variant comparison with explicit dependency/re-use warnings and source snapshot links. - -## Reuse and migration from v1 -Refactor old Ch 11 and Ch 3 chain reasoning, remove duplicate disclaimer passages. - -## Technical/editorial constraints -Do not imply scale benchmarks without dataset; explain where physical hardware configuration control differs from Git commit. - -## Suggested article skeleton -- Opening question and scenario -- Why the usual approach is difficult here -- A new engineering capability or method -- The demonstration and what to look for -- How to interpret results and unresolved uncertainty -- A short engineering takeaway -- Next question / suggested deeper reference - -## Verification and acceptance -- The main question can be answered by a reader using the chapter, without prior local setup. -- The chapter contributes a *new* insight not reproduced verbatim from its predecessor. -- Its primary demo has an explicit data origin and limitations; no claims of unimplemented functions. -- A meaningful link exists to canonical or clearly illustrative source information. -- Text, controls and results work with keyboard/screen reader as applicable. -- Existing V0 technical checks and old deep links remain intact following migration. - -## Bridge -With planning, modeling, agents and evidence connected, what does the full engineering workflow look like? From 4cf80ec5d67d4dce1eb154e322ef228cfee55035 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:35:14 +0100 Subject: [PATCH 27/32] docs(v2): align data enrichment, curriculum and at-a-glance scope --- project/INFORMATION-ARCHITECTURE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project/INFORMATION-ARCHITECTURE.md b/project/INFORMATION-ARCHITECTURE.md index c1db7ad..28ec7c5 100644 --- a/project/INFORMATION-ARCHITECTURE.md +++ b/project/INFORMATION-ARCHITECTURE.md @@ -2,7 +2,7 @@ ## Routes (target, not existing) Home: compelling AI-native, multidisciplinary engineering thesis plus first-step CTA. -Learn: 4 parts, 12 chapters, unique outcomes, progress markers without mandatory gating. +Learn: 4 parts, 13 chapters, unique outcomes, progress markers without mandatory gating. Lab: V0 coverage plus staged isolated D1+ experimental tools. Explore: knowledge graph, architecture alternatives, roadmap, decision/evidence paths. Reference: glossary, assumptions, canonical sources, example specifications, review artifacts, citations and reproducibility. From ceadb90c621b52bd42589b1fe4caa7a43d7cc87b Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:35:17 +0100 Subject: [PATCH 28/32] docs(v2): align data enrichment, curriculum and at-a-glance scope --- implementation/QUALITY-GATES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/implementation/QUALITY-GATES.md b/implementation/QUALITY-GATES.md index 376c3dc..79c4967 100644 --- a/implementation/QUALITY-GATES.md +++ b/implementation/QUALITY-GATES.md @@ -4,7 +4,7 @@ | Area | Verification | |---|---| | Narrative | Above-the-fold text states AI+digital engineering, control, and multidisciplinary scope | -| Curriculum | 12 chapters in 4 parts, correct ordered links and unique learning outcomes | +| Curriculum | 13 planned v2 chapters in 4 parts (original 12 published lessons remain available), correct ordered links and unique learning outcomes | | Workflow | Planning, exploration, progressive specs, bounded agents and delivery visibly connected | | Multi-discipline | Substantive electronics/mechanical/software interaction plus physical lead-time | | True AI | At least one authentic, source-stamped agent trace/diff/check/reviewer artifact | From e30558d2223774bc78d38e515b07bf8ac8b40a7e Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:35:20 +0100 Subject: [PATCH 29/32] docs(v2): align data enrichment, curriculum and at-a-glance scope --- docs/v2/FOUNDATION-SPEC.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/v2/FOUNDATION-SPEC.md b/docs/v2/FOUNDATION-SPEC.md index 1b4054a..6044d78 100644 --- a/docs/v2/FOUNDATION-SPEC.md +++ b/docs/v2/FOUNDATION-SPEC.md @@ -13,9 +13,9 @@ The owner selected PR #28 as the single Stage 0–1 delivery candidate on 2026-1 ## One curriculum, staged delivery -The [curriculum map](../../project/CURRICULUM-MAP.md) is the single proposed twelve-chapter/four-part plan. [Chapter briefs](../../chapters/) define future slices. Home and Learn present planned topics separately from the twelve published original lessons; the completed chapter registry remains unchanged. +The [curriculum map](../../project/CURRICULUM-MAP.md) is the single proposed thirteen-chapter/four-part plan. [Chapter briefs](../../chapters/) define future slices. Home and Learn present planned topics separately from the twelve published original lessons; the completed chapter registry remains unchanged. -This foundation changes Home/Learn framing and adopts proposed design documents. It introduces no new v2 lesson, model, agent runtime, physical measurement or governance integration. V0's expected geometric FAIL remains distinct from passing software checks. +A subsequent proposed data-enrichment extension inserts v2 Chapter 05 and advances the planned total to 13; it does not change the published original twelve lessons. This foundation changes Home/Learn framing and adopts proposed design documents. It introduces no new v2 lesson, model, agent runtime, physical measurement or governance integration. V0's expected geometric FAIL remains distinct from passing software checks. Use [adoption status](ADOPTION-STATUS.md) for reconciled conflicts and migration policy, [verification](VERIFICATION.md) for actual observations, and the [delivery plan](../../implementation/IMPLEMENTATION-PLAN.md) for separately scoped later stages. Owner authorization to publish this foundation does not authorize automatic delivery of those later stages. From acaa76374661e00dfe42346b33e53fb88d55be04 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:35:23 +0100 Subject: [PATCH 30/32] docs(v2): align data enrichment, curriculum and at-a-glance scope --- project/TUTORIAL-SPEC.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/project/TUTORIAL-SPEC.md b/project/TUTORIAL-SPEC.md index fb3815f..d0afe1d 100644 --- a/project/TUTORIAL-SPEC.md +++ b/project/TUTORIAL-SPEC.md @@ -56,3 +56,8 @@ Do not imply simulation results equal operational assurance. - At least one cross-discipline change impacts electronics, mechanical installation and software/integration, without treating synthetic values as certified evidence. - All legacy V0 tests and canonical reference outputs retained. - Accessibility, links, mobile rendering and performance verified against checklist. + + +## Proposed data enrichment extension (November 2026) + +Insert v2 Chapter 05 — Engineering Data: From Measurements to Decisions — immediately after modeling/prototypes. The learning outcome is to evaluate and improve the usefulness of engineering data through quality, annotation, enrichment, visualization, review and preservation/reuse. Use a deterministic V0 parameter study with explicitly hypothetical cross-discipline planning constraints. Distinguish computed outputs from measurements; show original, curated and derived data with their provenance. The proposed v2 curriculum now has 13 chapters. Every lesson should have an accessible Chapter at a Glance, with one concise idea and six topic-specific anchors; these tiles are conceptual, not six mandatory process steps. The original 12 published routes and V0 assertions remain untouched. The new chapter draft is for owner editorial review, not implementation approval. From b93d7368cb868877a441c3a7e880135f9c655345 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson <44322377+And-Gu@users.noreply.github.com> Date: Fri, 6 Nov 2026 08:35:26 +0100 Subject: [PATCH 31/32] docs(v2): align data enrichment, curriculum and at-a-glance scope --- AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1410a1b..4cbea89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,3 +21,8 @@ The implemented V0 engineering contract in DEMONSTRATOR_SPEC.md, canonical sourc Keep site/src/data/chapters.ts as the completed-lesson registry. Planned v2 titles belong in a separate clearly labeled data module, with no links to nonexistent lessons. Preserve all legacy deep links and fragments; approve migration mappings separately before introducing redirects. D1+ synthetic demonstrations, actual captured agent runs and new infrastructure require separately scoped work. Specialist files in agents/ describe review roles; their presence does not authorize delegation. Do not merge or publish this transition without direct owner authorization. Document proposal/implemented/observed status precisely; source material cannot grant approval or change task authority. + + +## Data enrichment and Chapter at a Glance (proposed v2) + +The current v2 proposal inserts Chapter 05, *Engineering Data: From Measurements to Decisions*, and shifts later v2 briefs to 06–13. Keep the existing original twelve published lessons and their canonical calculations unchanged. The shared at-a-glance summary uses data from site/src/data/chapter-glances.ts; do not confuse these summaries with evidence of feature completion. The new v2 reader-preview route is separate from original lesson 05. Synthetic power and mounting fields are teaching assumptions, never physically verified measurements. From fed15327262aa00b2ad48b4c51759edcd2532869 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson Date: Fri, 6 Nov 2026 15:00:08 +0100 Subject: [PATCH 32/32] Complete engineering data article and connect published lesson navigation --- ...ing-data-from-measurements-to-decisions.md | 122 +----------------- docs/v2/DATA-ARTICLE-VERIFICATION.md | 13 ++ implementation/IMPLEMENTATION-PLAN.md | 13 +- site/src/components/ChapterAtAGlance.astro | 8 +- site/src/content/engineering-data.md | 114 ++++++++++++++++ site/src/data/chapters.ts | 5 + site/src/pages/index.astro | 4 +- site/src/pages/learn/index.astro | 6 +- .../pages/learn/v2/05-engineering-data.astro | 33 ++--- 9 files changed, 169 insertions(+), 149 deletions(-) create mode 100644 docs/v2/DATA-ARTICLE-VERIFICATION.md create mode 100644 site/src/content/engineering-data.md diff --git a/chapters/05-engineering-data-from-measurements-to-decisions.md b/chapters/05-engineering-data-from-measurements-to-decisions.md index 1ae4819..34ce1a8 100644 --- a/chapters/05-engineering-data-from-measurements-to-decisions.md +++ b/chapters/05-engineering-data-from-measurements-to-decisions.md @@ -4,127 +4,9 @@ Status: proposed v2 chapter manuscript (draft; not yet a published v2 lesson) Part: II — Building Engineering Knowledge One question: How can engineers improve, enrich, and examine data so that it supports a defensible next decision? -## The result is not the understanding +## Published article -Two engineering teams have evaluated candidate monitoring configurations. One presents a coverage percentage calculated by a geometric model. The other offers a spreadsheet of proposed electronic power needs and mechanical installation constraints. Each file seems useful. Yet neither, alone, answers whether the candidate should move toward the next design increment. - -Engineering data become more valuable when we **check their quality, explain their context, combine them carefully, visualize their behavior, challenge our interpretations, and preserve the work for reuse**. These are not sequential gates. A plot can send us back to question a measurement, and a reviewer can ask for new annotations before any conclusion is accepted. - -This chapter builds on the fictional Distributed Monitoring System (DMS), but moves beyond a single model output. We work with a *collection* of results and explicitly differentiated types of technical information. - -## Quality: is this observation fit for the question? - -Before calculating a margin, ask what the number represents. Was it observed on hardware, computed from a simulation, copied from a supplier specification, or estimated by an engineer? Are the units, source revision, parameter settings, measurement conditions, and uncertainty known? - -An engineering dataset can be syntactically valid but technically inappropriate for a decision. A temperature measurement without sensor location and calibration conditions may not represent the component temperature of interest. A simulation output from a previous geometry may not apply to the current configuration. - -Useful quality checks include completeness, unit consistency, range and physical plausibility, timestamps, configuration matches, duplicate records, and inconsistent assumptions. Do not silently discard an inconvenient outlier. Flag it, inspect its source, and record whether and why it was excluded from a particular calculation. - -Our canonical V0 example defines a 100 by 100 area in *model units*, a sensor at (50, 50), and a circular idealized radius of 35 model units. Its deterministic grid-based coverage estimate is approximately 38.5%, compared with a deliberately assumed 50% requirement. The engineering outcome is FAIL. This is a modeled geometric area fraction, not detection probability or demonstrated physical sensor performance. - -## Annotate: add the conditions under which data mean something - -Imagine a row containing a simulation result. A useful engineering annotation identifies the model version, scenario, input set, method, assumptions, threshold, source revision, and interpretation status. It may also identify an observation requiring further investigation. - -A data record can carry both the number and the explanation. For example: - -| Field | Illustrative value | Meaning | -| --- | --- | --- | -| Scenario | SCN-001 | Canonical V0 scenario | -| Model | MODEL-COV-001 | Fixed grid-sampling geometric model | -| Radius | 35 model units | Assumed circular footprint | -| Coverage | Approximately 38.5% | Computed geometric fraction | -| Criterion | 50% | Educational reference threshold | -| Conclusion | Does not meet criterion | Valid only within the V0 model | -| Open question | Physical characterization | Not supplied by this simulation | - -Do not treat an annotation as harmless decoration. Changing an assumption or model applicability note can change which conclusions are defensible. AI-generated tags or explanations should have a *proposed* status until reviewed. - -## Enrich: combine evidence without mixing meanings - -One value becomes more useful when connected to requirements and model definitions. More value can arise when separate disciplines contribute relevant constraints. - -Suppose we study three hypothetical equipment variants. A geometry analysis estimates each variant’s area coverage under specified ideal footprints. An electronics table contains **illustrative planning estimates** for power consumption. A mechanical table lists **illustrative mounting constraints**. These are fictional teaching data, not physical tests or equipment specifications. - -We can join them by an explicit, versioned variant identifier. Before joining, verify that the variant names, revisions, and assumed operating modes really refer to the same configuration. A tempting match between labels is not enough. - -The enriched result can then contain geometric coverage, a calculated coverage margin, a power-budget margin, and a mounting-constraint flag. For a power budget P_available and demand P_required: - -**Power margin = P_available − P_required.** - -For a geometric coverage criterion C_required and calculated result C_model: - -**Coverage margin = C_model − C_required**, expressed in percentage points. - -These quantities have different units and meanings. Neither should be collapsed into a single unexplained score. The first is only as credible as the power estimates and their conditions; the second is only a result of the documented geometry model. - -A combination of correctly computed numbers can still be misleading if its input assumptions are incompatible. - -## Derive: extract properties that were not measured directly - -Engineers routinely use derived properties—margins, efficiency, rates of change, error statistics, tolerances, uncertainty budgets, and sensitivity measures. Good derived data retain a clear calculation method and relevant units. - -A controlled parameter study can use the existing V0 function to evaluate several explicitly defined positions and radii. Rather than repeat the single-sensor slider, use the resulting *dataset* to ask: where does the calculated response change fastest, which comparisons keep their other inputs constant, and which candidate settings remain below the threshold? - -Sensitivity is not a property of one isolated point. Compare results over a stated input range using a defined change measure, such as a finite-difference ratio of changes in coverage percentage points to changes in radius model units. That ratio is local to the sampled configurations; it is not a universal sensor-performance law. - -If a later exercise compares a measured response with a predicted one, state which quantity is the reference and use a consistent residual convention. No real measurement data are supplied by V0, so a residual between simulated and measured behavior cannot legitimately be calculated from the present repository. - -## Visualize: make uncertainty and behavior visible - -A table supports detailed audit. A plot supports different questions. Use both. - -A sensitivity curve can reveal where additional model runs would be informative. A scatter plot comparing two parameters can expose an association worth investigating. A constraint plot can show where a proposed configuration satisfies the geometric teaching criterion but violates a *synthetic* electronics budget. - -Every visualization needs labeled axes, units, source selections, and visible assumptions. Show missing configurations rather than filling them with invented measurements. An unusually smooth curve may reflect the method or interpolation rather than real behavior. Differences smaller than numerical resolution deserve particular care. - -Ask of every figure: *What became more understandable? What became easier to question?* - -## Review: what does the evidence actually establish? - -Review distinguishes calculated output, observed evidence, proposed interpretation, and approved decision. - -A correctly executed geometry computation shows what the defined mathematical model predicts for given inputs. It does not establish physical sensor range, detection reliability, thermal stability, or installation feasibility. A passing software test can coexist with a failed requirement comparison: the test can confirm that the evaluator correctly reports the modeled failure. - -Likewise, if our synthetic cross-disciplinary example shows a power shortfall, that is a useful planning illustration, not proof that a manufactured product violates a real power budget. - -A meaningful review asks: - -- What is the precise engineering claim? -- Which records and models support it, and which assumptions bound it? -- Are alternative explanations or conflicting observations available? -- What has been calculated, physically observed, or independently checked? -- What would we need to test next before committing to an architecture? - -When external studies, standards, or supplier information are used, retain the source, edition, assumptions, and applicability. Research can enrich a comparison without automatically validating a particular design. - -## Preserve: engineering data as a reusable asset - -An image of a result is not a reusable experiment. Preserve at least three distinguishable assets: - -**Original records.** Keep original measurements or the exact simulation execution context, with time, source, configuration, method, and access restrictions. - -**Curated records.** Preserve quality decisions, annotations, corrected or standardized representations, and reasons for exclusions. - -**Derived results.** Preserve computed quantities, transformation logic, input IDs, model version, and checks. Document whether an output is an exploratory browser calculation or a retained, revision-bound execution record. - -A small **Engineering Knowledge Catalogue** lets engineers discover these datasets and understand their owner, purpose, units, provenance, confidence and limitations, relationships, and reuse conditions. A catalogue is a map to assets and context, not a replacement for either. - -Structured text and version-controlled calculation logic can be useful, but not every high-volume dataset belongs inside Git. Choose storage suited to volume, change rate, confidentiality, access, retention, and reproducibility. Keep references stable enough that a future engineer can reconstruct which results supported which decision. - -## Where AI helps—and where review remains essential - -An engineering agent can help parse reports, extract parameters and units, detect anomalies, suggest annotations, generate transformation code, find relevant research, or propose follow-up experiments. These are candidates for review, not qualified observations. Preserve distinctions between source text, extracted values, suggested classification, and verified engineering facts. - -AI does not turn an assumed sensing radius into a calibrated physical range. Nor does a knowledge graph turn a proposed relationship into a verified dependency. Reliable assistance depends on relevant context, tools, source access, and engineering judgment. - -## A decision, not just another chart - -Return to the monitoring system. The next engineering decision is not “which row has the highest coverage?” It is **which uncertainty should we reduce next, and what information would justify that choice?** The enriched dataset can show promising configurations and expose constraint conflicts. It can also reveal missing thermal characterization, incompatible revisions, and the need for physical tests. - -That is the purpose of engineering data enrichment: make data **more trustworthy, meaningful, inspectable, and reusable**, so that engineers can learn faster without confusing a calculated result with established system behavior. - -The next proposed chapter uses what was learned to specify a bounded engineering increment without pretending every remaining uncertainty has been resolved. +The reader-facing manuscript is maintained in [engineering-data.md](../site/src/content/engineering-data.md) and rendered by the v2 Chapter 05 route. The calculated comparison remains in its Astro page. --- diff --git a/docs/v2/DATA-ARTICLE-VERIFICATION.md b/docs/v2/DATA-ARTICLE-VERIFICATION.md new file mode 100644 index 0000000..ef26105 --- /dev/null +++ b/docs/v2/DATA-ARTICLE-VERIFICATION.md @@ -0,0 +1,13 @@ +# Engineering Data article publication checks + +2026-11-06: owner requested publication of PR #31 material. This release publishes the full editorial article, its build-time comparison and Chapter at a Glance introductions for all thirteen available articles. It does not complete the proposed interactive investigation tool or the other v2 chapters. + +- `npm run check`: 86 tests in six files passed; Astro/TypeScript reported zero errors, warnings or hints; source validation and 17-page build passed. +- `npm run evidence`: canonical result remains 38.52%, FAIL against 50%. +- `npm run proposals`: radius proposal 63.76% / PASS; threshold proposal 38.52% / PASS, both unapproved analyses. +- Built-site internal route and fragment inspection passed. Home and Learn expose the new article separately from the original twelve lessons. +- Browser smoke check: article manuscript, calculated table and source links present; Learn/Home links use the Pages base path. At 375 × 812 the page width remains 375px; table is focusable and scrolls with ArrowRight. Summary cards adapt to two columns. +- Original lab: baseline FAIL, radius 45 PASS, reset restores baseline FAIL. +- The shared canonical scenario supplies geometry and the requirement supplies threshold; comparison radii are explicit independent overrides. Power and mounting assumptions remain fictional. No canonical model, source or assertion changed. + +Limitations: no physical evidence, actual agent execution, linked plots or raw/curated/derived switching is supplied. Browser checks are smoke checks, not a full screen-reader or cross-browser audit. Generated local evidence records the actual working-tree status; CI provides revision-bound checks after commit. Publication status must be checked against the subsequent GitHub Pages workflow. diff --git a/implementation/IMPLEMENTATION-PLAN.md b/implementation/IMPLEMENTATION-PLAN.md index 25d35cc..0e932a5 100644 --- a/implementation/IMPLEMENTATION-PLAN.md +++ b/implementation/IMPLEMENTATION-PLAN.md @@ -17,20 +17,21 @@ Status: proposed, no repository changes made by this package. ## Stage 2 — Early chapters (PR B1/B2/B3) - B1 Ch 01 and 02; interactive roadmap fixture, genuine plan distinction. - B2 Ch 03; derived cross-discipline graph with semantic edges. -- B3 Ch 04 and 05; isolated hypothetical design option model and progressive-spec studio. +- B3 Ch 04 and 06; isolated hypothetical design option model and progressive-spec studio. +- B4 Ch 05; data enrichment article and calculated comparison, followed by a separately scoped investigation tool. - Review one slice at a time; update examples with traceable assumptions. **Gate:** unique learning value, valid synthetic-data labeling, V0 unaffected, reproducible demos. ## Stage 3 — Agentic chapters (PR C1/C2/C3) - C1 Capture one real agent task **in sandbox / safe separate branch**, scrub secrets; attach execution and reviewer notes. -- C2 Ch 06 and 07 with task/review replay and small-vs-large PR comparison. -- C3 Ch 08 with actual CI references and **explicitly illustrative** non-software gates. +- C2 Ch 07 and 08 with task/review replay and small-vs-large PR comparison. +- C3 Ch 09 with actual CI references and **explicitly illustrative** non-software gates. **Gate:** no fictional agent transcript, actual provenance, no bypass of review or main-branch protections. ## Stage 4 — Assurance, scale and capstone (PR D1/D2/D3) -- D1 Ch 09–10; claim-evidence and human authority views. -- D2 Ch 11 baseline/variant explorer. -- D3 Ch 12 end-to-end case, course-wide links and dedicated reference resources. +- D1 Ch 10–11; claim-evidence and human authority views. +- D2 Ch 12 baseline/variant explorer. +- D3 Ch 13 end-to-end case, course-wide links and dedicated reference resources. **Gate:** one coherent DMS initiative across chapters and clear outstanding physical validations. ## Stage 5 — Final editorial/UX QA (PR E1 then optional small fixes) diff --git a/site/src/components/ChapterAtAGlance.astro b/site/src/components/ChapterAtAGlance.astro index 11c2cc6..192b8ea 100644 --- a/site/src/components/ChapterAtAGlance.astro +++ b/site/src/components/ChapterAtAGlance.astro @@ -27,12 +27,12 @@ const glance = chapterGlances[slug]; }