diff --git a/MILESTONE_03.md b/MILESTONE_03.md index 3440f86..3114f48 100644 --- a/MILESTONE_03.md +++ b/MILESTONE_03.md @@ -1,6 +1,6 @@ # Milestone 03 — Digital Threads and Knowledge Graphs -**Status:** Plan accepted through PR #6; bounded trace preparation in review · **Version:** 0.1 · **Date:** 2026-10-20 +**Status:** Plan accepted through PR #6; trace preparation merged as PR #7; Chapter 3 ready for review, publication pending · **Version:** 0.1 · **Date:** 2026-10-20 ## Objective and baseline diff --git a/README.md b/README.md index 780a924..1146550 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **From engineering intent to working systems.** -A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1 and 2 connect engineering intent, an interactive single-sensor experiment, structured definitions and reproducible verification. Milestone 2 was published on 2026-10-20. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_03.md](MILESTONE_03.md) for the proposed next lesson on digital threads and change-impact reasoning. +A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1 and 2 connect engineering intent, an interactive single-sensor experiment, structured definitions and reproducible verification. Milestone 2 was published on 2026-10-20. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_03.md](MILESTONE_03.md) for the accepted next lesson on digital threads and change-impact reasoning. Chapter 3 is ready for review; publication is pending. See [Milestone 3 verification](docs/MILESTONE_03_VERIFICATION.md) for checks and limitations. ## Reproduce locally diff --git a/ROADMAP.md b/ROADMAP.md index e12fcf7..72231ad 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -22,9 +22,9 @@ The V0 model and approved definitions remain the baseline. Browser comparisons a The single-sensor model, canonical YAML and baseline reference test remain unchanged. Browser proposals remain temporary and unapproved; retained proposal analyses do not claim execution of the registered reference test against changed inputs. -## Milestone 3 — accepted plan; trace preparation in review +## Milestone 3 — Chapter 3 ready for review -[Digital Threads and Knowledge Graphs](MILESTONE_03.md) defines a bounded lesson on following typed relationships and judging change impact and evidence applicability. It retains V0 and uses source-derived tables or a small static diagram; no graph infrastructure or general impact engine is authorized. Planning [PR #6](https://github.com/And-Gu/executable-engineering-lab/pull/6) is merged. The first implementation extracts and tests the existing eight definition relationships; Chapter 3 and its educational integration remain subsequent work. There is no published Chapter 3 yet. +[Digital Threads and Knowledge Graphs](MILESTONE_03.md) defines a bounded lesson on following typed relationships and judging change impact and evidence applicability. It retains V0 and uses source-derived tables or a small static diagram; no graph infrastructure or general impact engine is authorized. Planning [PR #6](https://github.com/And-Gu/executable-engineering-lab/pull/6) is merged. Trace preparation [PR #7](https://github.com/And-Gu/executable-engineering-lab/pull/7) is merged. The educational increment adds Chapter 3, a source-derived relationship table, the shared proposal exercise with impact reasoning, quiz and learning navigation. Local review is recorded in [Milestone 3 verification](docs/MILESTONE_03_VERIFICATION.md). Publication still requires review/merge, successful deployment and public smoke checks. There is no published Chapter 3 yet. ## Later learning increments diff --git a/docs/MILESTONE_03_VERIFICATION.md b/docs/MILESTONE_03_VERIFICATION.md new file mode 100644 index 0000000..640ec42 --- /dev/null +++ b/docs/MILESTONE_03_VERIFICATION.md @@ -0,0 +1,45 @@ +# Milestone 3 educational increment — verification + +Checked 2026-10-20. Trace preparation PR #7 is merged as `b3c1d18`; Chapter 3 is ready for review, not published. This is a development verification record, separate from generated engineering evidence. + +## Automated and editorial checks + +- `npm run check` passes: 86 tests across six files, source/proposal validation, zero Astro/TypeScript errors/warnings/hints, and seven static routes. +- Chapter 3 has 837 words of main prose excluding interactive components, the relationship table, experiment instructions and quiz. It starts from the operational decision, explains backward trace and forward impact, distinguishes IDs/definitions/executions, and includes assumption review and four reasoning questions. +- The eight relationship rows use the validated source projection introduced in PR #7. All numerical results use the unchanged ProposalWorkspace → analyzeProposal → coverage/evaluator path. No new calculation, impact classifier, graph engine, dependency or client script is introduced. +- Canonical YAML, model version, coverage/evaluator and reference test assertions are unchanged. Existing tests cover threshold/radius differences, references and the fact that unchanged connectivity can coexist with changed definitions. +- Built HTML inspection resolves 156 local links/assets/fragments under the Pages base path and confirms unique IDs on each of seven pages. +- Generated HTML retains the baseline calculation, disabled controls, typed source table, native disclosures and repository exercise fallback without JavaScript. A full JavaScript-disabled browser audit was not performed. + +## Production-build browser smoke review + +Astro preview served the actual static build at `/executable-engineering-lab/`. Port 4326 was occupied by another project; preview selected 4327. Only the lab preview process is owned by this work. + +| Check | Observation | +| --- | --- | +| Initial state/direct refresh | Baseline threshold 50, radius 35, coverage 38.52%, FAIL; no spurious differences | +| Threshold example | Coverage 38.52%, PASS against 35%, +3.52 pp; exact requirement field changes shown | +| Radius example | Coverage 63.76%, PASS against 50%, +13.76 pp; scenario radius changes | +| Broken source_need | Useful unresolved-reference error, result withheld and difference rows cleared | +| Restore reference/reset via Enter | Valid proposal recovers; reset returns baseline FAIL | +| Blank value/threshold 101 | No evaluation or stale result | +| Browser Back after a trial | Proposal resets to canonical baseline | +| Home → Chapter 3; Learn → Chapter 3 | Complete lesson loads | +| Chapter 3 → Chapter 2 → Chapter 3 | Chapter 2 baseline still evaluates to 38.52% FAIL; new continuation reaches Chapter 3 | +| Proposal evidence link → source view → return to Chapter 3 | Base-prefixed navigation and return work, including keyboard activation | +| Impact explanation and first quiz disclosure via Enter | Native details open and reveal explanations | +| First Tab after chapter refresh | Skip-to-content link receives focus | +| 375px layout | Document width stays 375px; controls stack/wrap; relationship and difference tables remain within their own 343px scroll regions | +| Relationship table ArrowRight | Focus stays on region; horizontal scroll advances 40px | +| 1280px layout | No document overflow; heading, narrative, navigation and table remain readable | +| Browser error logs | None observed during checked flows | + +These are manual smoke checks, not an automated end-to-end suite or full screen-reader/cross-browser accessibility audit. Chapter 1 behavior is covered by unchanged model tests and existing navigation/link checks; its full interactive exercise was not repeated in this increment. + +## Acceptance and remaining release work + +Local review supports M3-EDU-01, TRC-01, EXP-01, EVD-01, VAL-01, UI-01 and REG-01 within the checks above. No saved execution is displayed in Chapter 3: it explicitly directs readers to actual artifact/reproduction instructions. The relationship table describes definitions from the site build, not a historical execution. Impact reasoning is narrative and exercise-based, not automated evidence invalidation or a general impact decision. + +M3-PUB-01 remains pending. After review/merge, confirm main-revision validation and Pages deployment, then publicly smoke-test Home/Learn/Chapter 2→3, direct refresh, both proposal trials, invalid/restore/reset behavior, source return and quiz. Intended path: `/executable-engineering-lab/learn/03-digital-threads/`. + +A geometric PASS remains insufficient for operational suitability or optimality. The wall/obstruction exercise is a judgment question: the model does not simulate occlusion. Browser copies remain temporary and unapproved; retained proposal analyses still do not claim TEST-COV-001 executed changed inputs. CI artifacts expire after 30 days and can require sign-in. Physical validity, artifact persistence and comprehensive assistive-technology testing remain outside the demonstrated checks. diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro index b93ac0e..15b74fa 100644 --- a/site/src/pages/index.astro +++ b/site/src/pages/index.astro @@ -9,6 +9,7 @@ const base = import.meta.env.BASE_URL;

Work through one engineering question using a fictional monitoring system: define a criterion, experiment with a single-sensor model, and judge what its evidence actually establishes.

Start Chapter 1: From Engineering Intent to Evidence →

Completed Chapter 1? Continue with Engineering Information Models to explore what a changed definition means for its evidence.

+

Completed Chapter 2? Follow the digital thread in Chapter 3 to reason about change impact.

01 / Ask

Define success

Separate the operator’s need from the measurable criterion and the assumptions behind it.

Read Chapter 1

02 / Experiment

Explore the model

Vary one sensor’s radius and position. Compare configurations against the same requirement.

Open the lab
diff --git a/site/src/pages/learn/02-engineering-information-models.astro b/site/src/pages/learn/02-engineering-information-models.astro index 2bd1183..3d46d8f 100644 --- a/site/src/pages/learn/02-engineering-information-models.astro +++ b/site/src/pages/learn/02-engineering-information-models.astro @@ -62,7 +62,7 @@ const reference = `${base}reference/`;

Next: follow the dependencies

-

We can now describe a change without confusing a requirement with its scenario or its evidence. The next question is how to keep larger sets of these relationships useful as definitions evolve. Begin with the explicit meanings already present in the source view. A future lesson can build systematic digital-thread reasoning on that foundation; this exercise remains a bounded single-sensor example.

+

We can now describe a change without confusing a requirement with its scenario or its evidence. The next question is how to keep larger sets of these relationships useful as definitions evolve. Begin with the explicit meanings already present in the source view. Chapter 3: Digital Threads and Knowledge Graphs develops that reasoning using the same bounded single-sensor example.

← Chapter 1 · Learning path · Inspect engineering sources →

diff --git a/site/src/pages/learn/03-digital-threads.astro b/site/src/pages/learn/03-digital-threads.astro new file mode 100644 index 0000000..0104c76 --- /dev/null +++ b/site/src/pages/learn/03-digital-threads.astro @@ -0,0 +1,91 @@ +--- +import Layout from '../../layouts/Layout.astro'; +import ProposalWorkspace from '../../components/ProposalWorkspace.astro'; +import { loadSources } from '../../../../scripts/sources'; +import { projectRelationships } from '../../../../exercises/relationships'; +const definitions = loadSources(); +const relationships = projectRelationships(definitions); +const base = import.meta.env.BASE_URL; +const reference = `${base}reference/`; +--- + +
+

Learn / Chapter 03

+

Digital Threads and Knowledge Graphs

+

A proposal now passes. Which earlier conclusions can we still use?

+

Learning objective: trace a conclusion to its definitions and execution context, then explain which checks a change requires.

+

Prerequisite: Engineering Information Models.

+ +
+

A conclusion needs a context

+

The monitoring team still needs useful coverage of an industrial area. Two proposals appear to resolve the reference configuration’s failure: relax the coverage criterion or assume a larger sensor footprint. A reviewer asks whether the earlier analysis supports either proposal. Looking only at PASS, or at an unchanged requirement ID, cannot answer that question.

+

We need to reconstruct how the conclusion was reached. Which criterion was evaluated? Which configuration supplied the inputs? Which model interpreted them, under which assumptions? Which source revision and execution produced the record? These questions connect operational intent, engineering definition and execution evidence without treating them as interchangeable.

+

In this repository, a digital thread is that inspectable set of connections. A knowledge graph describes entities joined by relationships with explicit meanings. Here a small table is enough to inspect those meanings. The useful engineering capability is following and questioning the connections; a particular graph tool does not establish their correctness.

+
+
+

Follow backward before reasoning forward

+

Begin with an actual execution record when reviewing retained evidence. Read its exact evaluated definitions, calculation inputs, criterion and method. Check the model version, source commit, working-tree status, timestamp and execution context. A record from a dirty local checkout cannot be reproduced from its commit alone; its captured definitions matter too. A CI label does not remove the need to inspect what ran.

+

Next follow the requirement’s motivating need. The source_need relationship explains why the requirement exists; it is not a numerical input to the coverage formula. Follow the verification bindings to the scenario, executable model and registered test. The scenario’s model reference tells us how its input fields are interpreted. Each step answers a different question.

+

The table below projects validated fields from the canonical definitions bundled with this site. Field paths are relative to their source record. It describes definition relationships, not a saved execution. No retained execution record is loaded on this page. Use the reference evidence instructions or proposal analysis instructions to inspect a real record.

+
+
+ {relationships.map(link => )}
Definition connections from this site build
SourceFieldTargetMeaning
{link.from}{link.field}{link.to}{link.meaning}
+
+
+

Connectivity is a starting point

+

A stable identifier lets us discuss a record across revisions. It does not prove that its contents stayed the same. Both proposal trials keep the existing identifiers and relationships while changing a definition. The same table can therefore accompany different numerical evaluations. To decide whether evidence applies, compare the evaluated definition and execution context, not merely the connected IDs.

+

Forward tracing identifies candidates for review. It does not imply that every connected calculation must rerun. A threshold feeds the evaluator; the radius feeds the coverage calculation, whose output feeds the evaluator. The motivating need supports interpretation and justification. Treating all arrows as identical would obscure these distinctions and could miss a necessary engineering review.

+

For a threshold-only change, geometry remains unchanged, but the criterion needs fresh evaluation. For a radius change, calculate coverage again and then evaluate it. This workspace deliberately computes both baseline and proposal through the same model on every valid trial; it does not implement selective reuse or caching. The distinction concerns why each check is needed, not an optimization promised by the interface.

+
+
+

Experiment: explain what must be checked

+
    +
  1. Reset. Follow the requirement’s source_need and verification bindings in the table. Predict which connections will change in each trial.
  2. +
  3. Try the threshold example. Inspect the exact differences and validated proposed definition. Explain why the geometry can stay the same.
  4. +
  5. Reset, then try the radius example. Explain why fresh geometric calculation is needed even though the relationship table is unchanged.
  6. +
  7. Break the need reference. Observe the diagnostic and cleared result, then restore it. Does a resolvable need justify the threshold?
  8. +
  9. Suppose a wall blocks part of the area. Without editing a number, identify which assumption and conclusion need review.
  10. +
+ +
Compare your impact reasoning

The threshold trial changes the requirement criterion, statement and unapproved basis. It needs evaluation against that exact definition; it has not improved coverage. The radius trial changes the scenario and needs calculation plus evaluation. Neither changes the eight relationship roles. A broken reference blocks validation and analysis. A wall challenges the ideal unobstructed footprint assumption: this model cannot calculate the blocked region, so engineering review needs a suitable model or other evidence. Restoring a reference or obtaining PASS supplies neither that evidence nor requirement approval.

+
+
+

Review assumptions as well as numbers

+

The ideal sensor covers a circle without terrain, occlusion or directional effects. If an obstruction challenges that interpretation, repeating the same inputs can repeat the same number while losing relevance to the monitoring decision. There is no justified correction factor in this model. Do not manufacture one to preserve a convenient conclusion.

+

Likewise, satisfying the geometric criterion does not choose an optimal design. Cost, installation, reliability and actual sensing performance are absent. The thread helps expose where additional justification belongs. It cannot supply missing operational knowledge or turn an unapproved proposal into an accepted system definition.

+
+
+

Keep the execution attached to its definitions

+

For a repository trial, follow the isolated proposal exercise from an identified checkout. Install with npm ci, run npm run check, generate reference evidence with npm run evidence, then analyze the separate fixtures with npm run proposals. Preserve the canonical baseline and its reference assertions.

+

Inspect the generated proposal record’s complete baseline and proposed definitions, differences and calculation. Its metadata records the actual revision and working-tree state. It explicitly does not claim execution of TEST-COV-001 against the proposal. The registered reference test continues independently against the canonical configuration. Browser trials remain temporary, unapproved copies with no retained execution artifact.

+

CI artifacts are revision-bound, expire after 30 days and may require sign-in. Reproduce at the recorded revision instead of substituting today’s sources for an older execution. A fresh result needs its own context even when its number matches an earlier one. That discipline makes a thread useful for review rather than merely persuasive to look at.

+
+
+

Check your reasoning

+

Answer before revealing each explanation.

+
1. All eight links are unchanged. Does earlier evidence apply?

Not necessarily. IDs and relationship roles can stay fixed while definitions change. Inspect exact evaluated definitions and execution context.

+
2. Which check differs between a threshold change and a radius change?

A threshold change requires evaluation of a changed criterion with unchanged geometry. A radius change requires fresh coverage calculation and evaluation. The workspace computes both paths rather than caching geometry.

+
3. Validation succeeds, but an obstruction is discovered. What now?

Review the unobstructed-footprint assumption and the conclusion’s applicability. Structural validity cannot justify a physical assumption. This model supplies no obstruction calculation.

+
4. Does a path from need to test prove the requirement is verified?

No. It shows registered relationships. Verification requires inspecting an actual execution, its definitions, method and outcome; suitability still requires engineering judgment.

+
+
+

Next: make review repeatable

+

We can now follow a conclusion backward and explain a proposed change forward. Future automation should preserve those meanings, explicit limits and review responsibilities. Begin by asking which checks can be repeated reliably and which decisions still need engineering judgment; connecting more records alone will not answer that question.

+
+

← Chapter 2 · Learning path · Inspect engineering sources →

+
+
+ diff --git a/site/src/pages/learn/index.astro b/site/src/pages/learn/index.astro index 7cc8c93..6cb849a 100644 --- a/site/src/pages/learn/index.astro +++ b/site/src/pages/learn/index.astro @@ -9,7 +9,8 @@ const base = import.meta.env.BASE_URL;
  1. From Engineering Intent to Evidence

    Start with an operator’s need, define a coverage criterion and interpret an executable model’s result.

  2. Engineering Information Models

    Then change one definition, validate its fields and relationships, and decide which evidence still applies.

  3. +
  4. Digital Threads and Knowledge Graphs

    Follow typed relationships, distinguish definitions from execution context, and explain change impact.

-

Both lessons retain one ideal circular sensor. They do not establish real-world sensing performance.

+

All three lessons retain one ideal circular sensor. They do not establish real-world sensing performance.

diff --git a/site/src/pages/reference.astro b/site/src/pages/reference.astro index bff8971..e5843a6 100644 --- a/site/src/pages/reference.astro +++ b/site/src/pages/reference.astro @@ -19,6 +19,7 @@ const sources = records.map(record => ({ ...record, text: readFileSync(resolve(r

Reference / source traceability

Follow the engineering sources.

These source views are bundled from the canonical repository files when the site builds. Editing controls in the lab does not alter them.

+

For change-impact reasoning, return to Chapter 3.

Intent → definition → evidence

  1. {need.id} is the source need of {requirement.id}.