From efcf2328ea02a4387cf6424c349b9209987878f7 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson Date: Fri, 23 Oct 2026 17:49:03 +0200 Subject: [PATCH] Complete Chapter 11 configuration and evidence reuse lesson --- MILESTONE_11.md | 2 +- README.md | 2 +- ROADMAP.md | 4 +- docs/11-reuse-review.md | 51 +++++++++ docs/MILESTONE_11_VERIFICATION.md | 39 +++++++ site/src/data/chapters.ts | 1 + .../pages/learn/10-governance-assurance.astro | 2 +- .../learn/11-engineering-knowledge.astro | 104 ++++++++++++++++++ site/src/pages/reference.astro | 1 + 9 files changed, 201 insertions(+), 5 deletions(-) create mode 100644 docs/11-reuse-review.md create mode 100644 docs/MILESTONE_11_VERIFICATION.md create mode 100644 site/src/pages/learn/11-engineering-knowledge.astro diff --git a/MILESTONE_11.md b/MILESTONE_11.md index 071364f..0b861bf 100644 --- a/MILESTONE_11.md +++ b/MILESTONE_11.md @@ -1,6 +1,6 @@ # Milestone 11 — Engineering Knowledge at Scale -**Status:** Proposed educational scope · **Version:** 0.1 · **Date:** 2026-10-23 +**Status:** Plan accepted through PR #23; Chapter 11 ready for review, publication pending · **Version:** 0.1 · **Date:** 2026-10-23 ## Objective and baseline diff --git a/README.md b/README.md index aab88e1..9ba390f 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–10 connect engineering intent, executable experiments, qualified evidence and accountable review. Milestone 10 was published on 2026-10-23; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_11.md](MILESTONE_11.md) for the proposed configuration and reuse lesson. No agent runtime or governance integration is introduced. +A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1–10 connect engineering intent, executable experiments, qualified evidence and accountable review. Milestone 10 was published on 2026-10-23; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_11.md](MILESTONE_11.md) for the accepted configuration and reuse scope. Chapter 11 is ready for review, with publication pending; see [Milestone 11 verification](docs/MILESTONE_11_VERIFICATION.md). No agent runtime or governance integration is introduced. ## Reproduce locally diff --git a/ROADMAP.md b/ROADMAP.md index 09935e3..cd3c109 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -94,9 +94,9 @@ The single-sensor model, canonical YAML and baseline reference test remain uncha - [Successful Pages deployment](https://github.com/And-Gu/executable-engineering-lab/actions/runs/39909203982); [successful post-merge validation](https://github.com/And-Gu/executable-engineering-lab/actions/runs/39909203929). - Public ten-entry Home/Learn, Chapter 9→10, source return, refresh, proposals, invalid-reference/restore/reset and keyboard gap/quiz checks passed smoke review. See [Milestone 10 verification](docs/MILESTONE_10_VERIFICATION.md) for observations and limits. -## Milestone 11 — proposed +## Milestone 11 — Chapter 11 ready for review -[Engineering Knowledge at Scale](MILESTONE_11.md) proposes a configuration and evidence-reuse lesson using existing V0 sources and isolated proposals. No configuration platform or new modeling capability is introduced. +[Engineering Knowledge at Scale](MILESTONE_11.md) teaches configuration and evidence reuse using existing V0 sources and isolated proposals. Planning PR #23 is merged. The educational increment adds the complete lesson, source-role table, manual reuse cases, repository review template and shared eleventh Home/Learn entry. No configuration platform or new modeling capability is introduced. See [Milestone 11 verification](docs/MILESTONE_11_VERIFICATION.md). Publication remains pending review/merge and exact-revision CI/Pages/public checks. ## Later learning increments diff --git a/docs/11-reuse-review.md b/docs/11-reuse-review.md new file mode 100644 index 0000000..adf13c9 --- /dev/null +++ b/docs/11-reuse-review.md @@ -0,0 +1,51 @@ +# Review configuration and evidence reuse + +Use the current V0 sources and existing isolated proposal fixtures. This manual review creates no approved baseline and requires no canonical edits, push or publication. + +At an identified checkout: + +```sh +git rev-parse HEAD +git status --short +npm ci +npm run check +npm run evidence +npm run proposals +``` + +Record actual command outcomes. If the environment blocks tsx CLI IPC, the same script can be invoked with `node --import tsx scripts/validate.ts` (or evidence.ts/proposals.ts); document substitutions and still run type checks, tests and Astro build. + +Follow need, requirement, scenario and manifest source fields, then inspect actual records: + +```sh +node --input-type=module <<'JS' +import { readFileSync } from 'node:fs'; +for (const path of ['artifacts/reference-evidence.json', + 'artifacts/proposals/PROPOSAL-RADIUS-45.json', + 'artifacts/proposals/PROPOSAL-THRESHOLD-35.json']) { + const r = JSON.parse(readFileSync(path, 'utf8')); + console.log({ path, definition: r.definition, calculation: r.calculation, + verification: r.verification, execution: r.execution }); +} +JS +``` + +Compare proposed definitions and exact differences independently. Do not combine the radius candidate's geometry with the threshold candidate's criterion and claim either saved result covers the combination. Shared implementation does not imply unchanged evidence applicability. + +A source commit identifies committed state; a dirty-state flag does not snapshot all modifications. Review actual relevant differences and embedded inputs before attributing a result to HEAD. Stable source IDs and model version alone do not identify the evaluated configuration. + +Reference generation does not execute assertions; proposal analyses explicitly do not execute TEST-COV-001 against changed inputs. Inspect separate command logs for actual assertion execution. The canonical geometric FAIL remains expected. + +For historical evidence, select an actual [validation run](https://github.com/And-Gu/executable-engineering-lab/actions/workflows/validate.yml), inspect revision, completed steps and available records. Artifacts expire after 30 days and may require sign-in. State unavailable evidence; local reproduction is a new execution. Current source views do not establish historical definitions. + +## Written reuse review + +- Intended claim and configuration: +- Source revision, dirty state and relevant uncommitted differences: +- Material being reused: implementation, definition or execution result: +- Actual candidate differences and source relationships affected: +- Evidence and logs actually inspected; unavailable information: +- Applicability reasoning: inputs, criterion, method, assumptions and claim: +- Required new checks and unresolved engineering review: + +This template is a manual teaching aid separate from generated engineering evidence. Coherent definitions, traceability and successful tests do not establish operational suitability or an approved product configuration. diff --git a/docs/MILESTONE_11_VERIFICATION.md b/docs/MILESTONE_11_VERIFICATION.md new file mode 100644 index 0000000..794566f --- /dev/null +++ b/docs/MILESTONE_11_VERIFICATION.md @@ -0,0 +1,39 @@ +# Milestone 11 educational increment — verification + +Checked 2026-10-23. Planning PR #23 is merged. Chapter 11 is ready for review, not published. This development record is separate from generated engineering evidence. + +## Scope and automated review + +- Main prose: 816 words excluding headings, table, exercise/workspace and quiz. Configuration/baseline are explicit local teaching terms; no formal process conformance or industrial-scale performance is claimed. +- Source-role table reads validated canonical identifiers, criterion, geometry and model version. It distinguishes stable identity, revision, method, execution and working-tree state. No historical source or CI artifact is loaded by the page. +- Existing V0, YAML, model/evaluator, schemas, assertions, workflows, dependencies and workspace implementation remain unchanged. Reuse cases are explicitly hypothetical; no combined candidate, historical run or approval is invented. +- `npm run check` passes: 86 tests across six files, zero Astro/TypeScript errors/warnings/hints, engineering/proposal validation and fifteen static routes. +- `npm run evidence` retains canonical 38.52% FAIL. Proposal generation produces radius 63.76%/50% PASS and threshold 38.52%/35% PASS, both unapproved analyses. Record generation remains separate from assertion execution. +- Built HTML inspection resolves 382 local links/assets/fragments and confirms unique IDs per page. Static fallback includes baseline/context, disabled pre-initialization controls and native disclosures. Full JavaScript-disabled browser testing was not performed. +- No implementation-mirroring prose tests were added. + +## Static-preview browser smoke review + +Reviewed at port 4327 under `/executable-engineering-lab/`. + +| Check | Observation | +| --- | --- | +| Home/Learn | Eleven cards/entries and correct Chapter 11 path | +| Chapter 11→10→11 | Back/continuation resolve | +| Source view and return | Correct base-prefixed reference and Chapter 11 return | +| Radius and threshold examples via Enter | Distinct expected shared-calculation outcomes | +| Broken reference | Analysis withheld; previous result removed | +| Restore/reset/reload | Canonical 38.52% FAIL returns | +| Dirty-checkout case and implementation/evidence quiz via Enter | Native explanations open with qualified reuse reasoning | +| 375px | Document width 375px; source table in its own 343px region with 481px content; ArrowRight scrolls it | +| 1280px | No document overflow | +| First Tab after reload | Skip-to-content receives focus | +| Browser errors | None observed during checked flows | + +Screenshot: workspace outputs/chapter-11-preview.png. These checks are manual smoke review, not comprehensive accessibility/cross-browser certification. Older full exercises were not repeated; shared implementation is unchanged. + +## Evidence and remaining work + +Generated reference/proposal records are inspected at the committed checkout for actual revision and dirty-state provenance. The written reuse template is a manual review aid, not an approved baseline or new engineering evidence format. A dirty-state flag does not snapshot every uncommitted modification; the lesson explicitly retains that limitation. + +Local observations support M11-EDU-01, SRC-01, EVD-01, UI-01 and REG-01 within these limits. M11-PUB-01 remains pending review/merge, successful exact main-revision validation/Pages and public Home/Learn/Chapter 10→11/source-return/proposal/disclosure/refresh checks. V0 physical/numerical limits and historical artifact expiry/sign-in remain. No operational suitability or universal evidence applicability is claimed. diff --git a/site/src/data/chapters.ts b/site/src/data/chapters.ts index 75b2cd2..2b4c7f7 100644 --- a/site/src/data/chapters.ts +++ b/site/src/data/chapters.ts @@ -10,4 +10,5 @@ export const chapters = [ { path: '08-engineering-context', title: 'Agents and Engineering Context', summary: 'Assemble relevant source context, separate content from authority, and review proposed actions.' }, { path: '09-continuous-engineering', title: 'Continuous Engineering', summary: 'Follow revision-bound checks, interpret automated feedback, and identify the engineering decisions still open.' }, { path: '10-governance-assurance', title: 'Governance and Assurance', summary: 'Connect bounded claims to actual checks and evidence, identify gaps, and retain accountable review decisions.' }, + { path: '11-engineering-knowledge', title: 'Engineering Knowledge at Scale', summary: 'Identify coherent configurations, distinguish identity from revision, and review evidence applicability before reuse.' }, ] as const; diff --git a/site/src/pages/learn/10-governance-assurance.astro b/site/src/pages/learn/10-governance-assurance.astro index c33a64e..53ce236 100644 --- a/site/src/pages/learn/10-governance-assurance.astro +++ b/site/src/pages/learn/10-governance-assurance.astro @@ -81,7 +81,7 @@ const repo = 'https://github.com/And-Gu/executable-engineering-lab';

Next: preserve meaning through evolution

-

We can now state a bounded claim, inspect its support and identify unresolved responsibility. The next question is how to preserve those meanings when definitions are configured, reused and changed across a growing body of engineering knowledge.

+

We can now state a bounded claim, inspect its support and identify unresolved responsibility. Continue with Chapter 11: Engineering Knowledge at Scale to preserve those meanings when definitions are configured, reused and changed across a growing body of engineering knowledge.

← Chapter 9 · Learning path · Inspect engineering sources →

diff --git a/site/src/pages/learn/11-engineering-knowledge.astro b/site/src/pages/learn/11-engineering-knowledge.astro new file mode 100644 index 0000000..96a9a7f --- /dev/null +++ b/site/src/pages/learn/11-engineering-knowledge.astro @@ -0,0 +1,104 @@ +--- +import Layout from '../../layouts/Layout.astro'; +import ProposalWorkspace from '../../components/ProposalWorkspace.astro'; +import { loadSources } from '../../../../scripts/sources'; +const { need, requirement, scenario, manifest } = loadSources(); +const base = import.meta.env.BASE_URL; +const reference = `${base}reference/`; +const repo = 'https://github.com/And-Gu/executable-engineering-lab'; +--- + +
+

Learn / Chapter 11

+

Engineering Knowledge at Scale

+

Which definitions belong together, and when can their evidence be reused?

+

Learning objective: identify a coherent configuration, distinguish identity from revision, and review evidence applicability before reuse.

+

Prerequisite: Governance and Assurance.

+

Manual configuration and reuse review using the small V0 demonstrator. This lesson adds no configuration platform, approved product baseline or scale benchmark.

+ +
+

The same identifier is not the same configuration

+

A colleague finds a passing result and attaches it to a new monitoring proposal. The requirement ID matches, so they assume the result is reusable. Before accepting that reasoning, ask which criterion, geometry and method produced the result. A stable name lets us follow a definition through change; it does not say that its meaning or evaluated inputs stayed unchanged.

+

The problem becomes harder as more people reuse sources and results. We can practice the necessary reasoning with this small demonstrator: identify the definitions that belong together, inspect their differences and qualify the evidence attached to them. More records would increase the review burden, but no large dataset or infrastructure is needed to expose the mistake.

+

Here, configuration means an identified, coherent set of definitions used for a particular analysis. Baseline means the named starting set for comparison. These local teaching terms do not designate an approved product baseline. The canonical sources remain the reference for this lesson; temporary proposals are separate candidates, not replacements for those sources.

+
+
+

Identify the set, not just one member

+

Start with the need, criterion and scenario, then the model and test registration. The need supplies intent; the other records define what the calculation and checks mean. Their typed relationships provide a route through the sources. Follow the actual relationship fields rather than assuming every arrow denotes the same dependency.

+

The table reads current identifiers and values from validated canonical sources at build time. It identifies their roles, not a historical execution. To interpret an older record, inspect its evaluated definitions and resolve surrounding sources at the recorded revision. A source link to main can later show a different state.

+
+
+ + + + + + +
Members of the current reference context
SourceRoleWhat else must be identified?
{need.id}Intent motivating the criterionIts wording and revision, not only its ID
{requirement.id}Criterion: {requirement.threshold_percent}%Statement, basis and evaluated scenario/model links
{scenario.id}Area {scenario.area.width} × {scenario.area.height}; center ({scenario.sensor.x}, {scenario.sensor.y}); radius {scenario.sensor.radius} model unitsExact inputs used by the candidate
{manifest.model.id}Model version {manifest.model.version}Implementation revision, method and assumptions
{manifest.test.id}Registered canonical assertionsActual assertion execution, separate from analysis generation
+
+
+

Identity, revision and execution answer different questions

+

A requirement ID identifies the record. A source commit identifies committed repository state. The model version labels the model, while execution metadata identifies a particular run and its context. None of these alone identifies every evaluated input. A branch name can move; a model version does not describe the scenario or threshold.

+

A dirty checkout adds another qualification: HEAD alone does not identify its uncommitted changes. Generated records report working-tree state and embed evaluated definitions, but that flag is not a complete snapshot of every modified source. Record the actual differences needed for reproduction and do not attribute the whole working tree to the commit alone.

+

Coherence also requires meaning, not just matching references. A source bundle can contain resolvable IDs while combining a criterion from one candidate with inputs from another. Validation detects the contracts it implements; it cannot decide that this combination was intended, justified or covered by a historical result.

+

Reuse implementation deliberately

+

The browser and automated checks reuse one pure coverage function and evaluator. That avoids separately maintained formulas. It does not transfer the outcome of one execution to every consumer of that implementation. A new input still needs its own calculation, and a broader claim still needs evidence that the model can address it.

+

Evidence reuse is therefore a separate review question. Compare evaluated inputs, criterion, method, assumptions and intended claim. An unchanged number may have a different meaning after a threshold change. An unchanged criterion may have a different outcome after a geometry change. A shared function supports consistent computation, not universal applicability of its earlier results.

+
+
+

Review a proposed reuse

+
    +
  1. Inspect the reference context above. Identify what its build-time source view can tell you and what historical context it cannot supply.
  2. +
  3. Try the radius proposal. Inspect its exact field difference and proposed definition. Reset before trying the threshold proposal.
  4. +
  5. Explain why unchanged coverage in the threshold example does not preserve the evaluation's meaning. Keep both candidates separate.
  6. +
  7. Break a reference, observe withheld analysis, then restore/reset. Explain why passing structural checks would still leave an applicability review.
  8. +
+ +
+
+

Make change impact inspectable

+

Begin a reuse decision with the actual difference. A radius-only proposal changes scenario geometry while retaining the criterion. The threshold proposal changes criterion fields while preserving that geometry. Neither is the unmodified canonical configuration, and their separate results must not be combined into a third candidate that nobody evaluated.

+

Follow affected source relationships to identify what needs checking again. A broken need reference blocks analysis; a valid changed criterion may still lack an engineering basis. Existing canonical assertions do not claim reference-test execution against every proposal. Use the actual command logs and record semantics rather than interpreting the test ID as universal verification.

+

Leave the next engineer a reviewable handover: the intended claim, identified definitions, actual differences, evidence inspected and unresolved questions. This is more useful than a list of unexplained links. State whether evidence is unavailable or outside scope, and identify the next check or responsible review instead of silently carrying forward a selected PASS.

+
+
+

Review hypothetical reuse cases

+

These are designed cases, not reports of actual corrupted bundles or executions.

+
An old PASS has the same ID but a different criterion

Compare the evaluated criterion and inputs. The ID alone does not establish applicability; inspect or rerun the relevant evaluation and justify the intended claim.

+
A bundle mixes definitions from different revisions

Identify the intended configuration and actual differences. Resolvable IDs do not prove that this combination was evaluated. Do not invent a combined result.

+
A dirty checkout is attributed only to HEAD

HEAD identifies committed state. Inspect uncommitted differences and actual record inputs; a dirty-state flag alone cannot reconstruct all changed sources.

+
The same model is reused for a new scenario

Reuse the implementation, validate new inputs and execute the relevant calculation/checks. Review assumptions and evidence applicability; the old result does not automatically verify the new scenario.

+
+
+

Inspect actual records before reusing their conclusions

+

Follow the repository reuse review to inspect canonical and proposed definitions, differences, calculations and provenance at an identified checkout. Keep assertion execution, reference evaluation generation and proposal analysis distinct. The written template records reasoning, not an approved baseline or a new engineering evidence format.

+

No historical CI record is loaded here. Browser proposals are temporary; retained artifacts expire after 30 days and may require sign-in. Local reproduction is a new execution. Even a coherent configuration and successful checks cannot establish physical detection, operational suitability or an optimal design under V0's omitted behavior.

+
+
+

Check your reasoning

+
1. Does an unchanged ID establish unchanged meaning?

No. Inspect the definition and revision, including criterion, inputs and relationships.

+
2. Is shared implementation the same as reusable evidence?

No. A shared function computes consistently; evidence applicability depends on the evaluated configuration, method, assumptions and claim.

+
3. Does a dirty-state flag fully identify an execution's sources?

No. It warns that HEAD alone is insufficient. Inspect the actual inputs and relevant uncommitted differences.

+
4. Can two passing candidates be combined without another evaluation?

No. Their separate results do not establish a result for an unevaluated combination.

+
+
+

Next: connect the whole review

+

We can now identify what belongs together and explain why a reuse decision needs evidence of its own applicability. The next step is an integrated exercise connecting operational intent, definitions, execution, evidence interpretation and responsible review without losing those distinctions.

+
+

← Chapter 10 · Learning path · Inspect engineering sources →

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

For source context and action authority, return to Chapter 8.

For automated feedback and evidence applicability, return to Chapter 9.

For bounded claims, evidence gaps and review responsibility, return to Chapter 10.

+

For configurations and evidence reuse, return to Chapter 11.

Intent → definition → evidence

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