diff --git a/MILESTONE_12.md b/MILESTONE_12.md index c147d88..8d1ff43 100644 --- a/MILESTONE_12.md +++ b/MILESTONE_12.md @@ -1,6 +1,6 @@ # Milestone 12 — The Integrated Engineering Environment -**Status:** Proposed educational scope · **Version:** 0.1 · **Date:** 2026-10-23 +**Status:** Plan accepted through PR #25; Chapter 12 ready for review, publication pending · **Version:** 0.1 · **Date:** 2026-10-23 ## Objective and baseline diff --git a/README.md b/README.md index 0723474..c77eb60 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–11 connect engineering intent, executable experiments, qualified evidence and accountable review. Milestone 11 was published on 2026-10-23; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_12.md](MILESTONE_12.md) for the proposed integrated capstone. No agent runtime or governance integration is introduced. +A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1–11 connect engineering intent, executable experiments, qualified evidence and accountable review. Milestone 11 was published on 2026-10-23; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_12.md](MILESTONE_12.md) for the accepted integrated capstone scope. Chapter 12 is ready for review, with publication pending; see [Milestone 12 verification](docs/MILESTONE_12_VERIFICATION.md). No agent runtime or governance integration is introduced. ## Reproduce locally diff --git a/ROADMAP.md b/ROADMAP.md index 0d1ea38..a905249 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -103,9 +103,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/39982049116); [successful post-merge validation](https://github.com/And-Gu/executable-engineering-lab/actions/runs/39982049107). - Public eleven-entry Home/Learn, Chapter 10→11, source return, refresh, proposals, invalid-reference/restore/reset and keyboard reuse/quiz checks passed smoke review. See [Milestone 11 verification](docs/MILESTONE_11_VERIFICATION.md) for observations and limits. -## Milestone 12 — proposed +## Milestone 12 — Chapter 12 ready for review -[The Integrated Engineering Environment](MILESTONE_12.md) proposes an end-to-end capstone using existing V0 sources, calculations, checks and manual review. It completes the proposed learning sequence without claiming that future demonstrator capabilities V1–V4 have been implemented. +[The Integrated Engineering Environment](MILESTONE_12.md) connects existing V0 sources, calculations, checks and manual review in a capstone. Planning PR #25 is merged. The educational increment adds the lesson, source route, written handover/reasoning guide, repository instructions and shared twelfth Home/Learn entry. See [Milestone 12 verification](docs/MILESTONE_12_VERIFICATION.md). Publication remains pending review/merge and exact-revision CI/Pages/public checks. The twelve-lesson path is not yet fully published; future demonstrator capabilities V1–V4 remain unimplemented. ## Later learning increments diff --git a/docs/12-integrated-review.md b/docs/12-integrated-review.md new file mode 100644 index 0000000..a1f29b3 --- /dev/null +++ b/docs/12-integrated-review.md @@ -0,0 +1,52 @@ +# Capstone: an inspectable engineering handover + +Review the existing V0 radius-only proposal from operational question to a bounded next decision. No canonical edits, push, merge, publication or design approval are required. + +At an identified checkout: + +```sh +git rev-parse HEAD +git status --short +npm ci +npm run check +npm run evidence +npm run proposals +``` + +Record commands actually completed and their logs. If tsx CLI IPC is blocked by the environment, document substitution with `node --import tsx scripts/validate.ts` (or evidence.ts/proposals.ts); still run type checks, tests and Astro build. + +1. Inspect NEED-001, REQ-COV-001, SCN-001, manifest, model/evaluator and registered assertions. State the operational question and narrower V0 geometric claim. +2. Apply the [radius-only contract](07-task-review.md#written-task-contract). Inspect the actual radius fixture and analysis, keeping criterion and fixed inputs unchanged. +3. Compare the threshold fixture separately. A valid passing analysis does not justify changing the criterion under that task. Do not combine candidates and attribute either result to the combination. +4. Inspect actual records, not outcome labels alone: + +```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 +``` + +Reference generation is not assertion execution. Proposal analyses explicitly do not execute TEST-COV-001 against changed inputs. Canonical geometric FAIL remains expected; successful software tests preserve that finding. + +For historical inspection choose 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 event. A dirty flag does not snapshot every modified source, and today's sources may differ from historical definitions. + +## Written handover + +- Operational question and bounded modeled claim: +- Task boundary and evaluated definitions: +- Source revision, working-tree state and relevant differences: +- Actual commands/browser actions completed and logs/records inspected: +- Observation, criterion, numerical method and assumptions: +- Missing evidence, counterarguments and model limitations: +- Responsible next review and unresolved decision: + +This written aid is separate from generated engineering evidence. Use actual observations; do not invent missing provenance or record an approval. A published lesson, green software check or geometric PASS does not establish operational detection performance, suitability or optimality. + +The capstone closes the twelve-lesson sequence after release. It does not implement multiple sensors, dynamics, actual agents or governance integrations; those remain future capabilities with separate scope. diff --git a/docs/MILESTONE_12_VERIFICATION.md b/docs/MILESTONE_12_VERIFICATION.md new file mode 100644 index 0000000..b918cd6 --- /dev/null +++ b/docs/MILESTONE_12_VERIFICATION.md @@ -0,0 +1,39 @@ +# Milestone 12 educational increment — verification + +Checked 2026-10-23. Planning PR #25 is merged. Chapter 12 is ready for review, not published. This development record is separate from generated engineering evidence. + +## Scope and automated review + +- Main narrative: 817 words excluding headings, source route, exercise/workspace, handover guide and quiz. It starts with the operational question and ends with the intent/definition/evidence principle and explicit future capability boundary. +- Source route uses validated canonical IDs, criterion and model version. One unchanged ProposalWorkspace is embedded. Reasoning guide is labeled guidance, not an execution or approval record. The written handover is outside the page and persists nothing. +- No historical artifact is fetched, no additional model/calculation is introduced and no operational acceptance or implemented V1–V4 capability is claimed. No empty next chapter appears; remediation links lead to existing chapters. +- Existing canonical YAML, schemas, stable IDs, model/evaluator, assertions, workflows, dependencies and workspace code remain unchanged. +- `npm run check` passes: 86 tests across six files, zero Astro/TypeScript errors/warnings/hints, source/proposal validation and sixteen static routes. Final narrative addition was followed by the full check again. +- `npm run evidence` retains expected canonical 38.52% FAIL. Proposal generation yields radius 63.76%/50% PASS and threshold 38.52%/35% PASS, both unapproved analyses. Assertion execution remains distinct from generated evaluations. +- Built HTML inspection resolves 417 local links/assets/fragments with unique IDs. Generated fallback retains source context/baseline, disabled pre-initialization controls and native guide/quiz. Full JavaScript-disabled browser testing was not performed. +- No tests were added merely to mirror prose. + +## Static-preview browser smoke review + +Reviewed at port 4327 under `/executable-engineering-lab/`. + +| Check | Observation | +| --- | --- | +| Home/Learn | Twelve cards/entries; correct Chapter 12 path | +| Chapter 12→11→12 | Back/continuation resolve | +| Source view and return | Base-prefixed reference and Chapter 12 return resolve | +| Radius and threshold examples via Enter | Distinct expected shared-calculation outcomes | +| Broken reference | Analysis withheld and previous result removed | +| Restore/reset/reload | Canonical 38.52% FAIL returns | +| Handover guide and software-test/engineering-FAIL quiz via Enter | Native disclosures open with bounded reasoning | +| 375px and 1280px | Document width matches viewport; no document overflow; radius control works at mobile width | +| First Tab after reload | Skip-to-content receives focus | +| Browser errors | None observed during checked flows | + +Final text count and preview were inspected after rebuild. Screenshot: workspace outputs/chapter-12-preview.png. This is manual smoke review, not comprehensive accessibility/cross-browser certification. Older full exercises were not repeated; shared implementation remains unchanged. + +## Evidence and release limits + +Inspect generated reference/proposal records at the clean committed checkout for actual revision/dirty-state provenance. The capstone loads no historical CI artifact. Artifact expiry/sign-in, V0 numerical/physical limits and inability of a dirty flag to snapshot every modification remain explicit. + +Local checks support M12-EDU-01, TRC-01, EVD-01, UI-01 and REG-01 within these limits. M12-PUB-01 remains pending review/merge, exact main-revision validation/Pages success and public Home/Learn/Chapter 11→12/source-return/capstone/refresh checks. Curriculum publication is distinct from operational acceptance and future V1–V4 delivery. diff --git a/site/src/data/chapters.ts b/site/src/data/chapters.ts index 2b4c7f7..8295867 100644 --- a/site/src/data/chapters.ts +++ b/site/src/data/chapters.ts @@ -11,4 +11,5 @@ export const chapters = [ { 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.' }, + { path: '12-integrated-environment', title: 'The Integrated Engineering Environment', summary: 'Complete an end-to-end handover from operational intent through a controlled proposal to qualified evidence and the next review decision.' }, ] as const; diff --git a/site/src/pages/learn/11-engineering-knowledge.astro b/site/src/pages/learn/11-engineering-knowledge.astro index 96a9a7f..8aba9c0 100644 --- a/site/src/pages/learn/11-engineering-knowledge.astro +++ b/site/src/pages/learn/11-engineering-knowledge.astro @@ -83,7 +83,7 @@ const repo = 'https://github.com/And-Gu/executable-engineering-lab';

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.

+

We can now identify what belongs together and explain why a reuse decision needs evidence of its own applicability. Continue with Chapter 12: The Integrated Engineering Environment for 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/learn/12-integrated-environment.astro b/site/src/pages/learn/12-integrated-environment.astro new file mode 100644 index 0000000..ec3c97f --- /dev/null +++ b/site/src/pages/learn/12-integrated-environment.astro @@ -0,0 +1,109 @@ +--- +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 12

+

The Integrated Engineering Environment

+

Can another engineer follow this proposal from operational intent to a justified next decision?

+

Learning objective: hand over a bounded proposal with inspectable definitions, actual observations, qualified evidence and unresolved review decisions.

+

Prerequisite: Engineering Knowledge at Scale.

+

Capstone using existing V0 sources and calculations. This connected review path records no design approval and implements no future demonstrator capability.

+ +
+

Hand over a decision, not just a percentage

+

An operator needs to understand activity in a bounded industrial area. The team proposes a larger sensor footprint and asks you to review the radius-only change before handing it to another engineer. Your task is to explain what the result establishes, which work actually ran and what must still be decided. A passing number is useful, but cannot carry that handover alone.

+

Return to the original engineering question: what would count as enough coverage, and what would convince us? V0 answers a deliberately narrow version using an ideal circular footprint and a geometric area criterion. The criterion is a teaching assumption, not a derived operational target. Neither the original FAIL nor a later PASS measures real-world detection effectiveness.

+

This final exercise connects the sources and review activities already available. Integrated means another engineer can follow the reasoning across them without losing their roles. It does not mean the repository has become an operational monitoring platform, an agent system or an automated acceptance authority.

+
+
+

Follow the sources in the order the question needs

+

Begin with intent, then the criterion and scenario. Inspect the model's method and assumptions before interpreting its output. Read the registered assertions separately from the generated analysis. Finally identify the execution context supporting the observation. Each step answers a different question; a trace link makes it inspectable, not automatically sufficient.

+

The route below reads current identifiers from validated canonical sources. It does not load an older execution or prove which definitions a historical run used. For retained evidence, inspect its embedded inputs, criterion, model version and provenance, then resolve surrounding sources at that revision.

+
+
    +
  1. {need.id}: intent — why the operator needs monitoring.
  2. +
  3. {requirement.id}: criterion — {requirement.threshold_percent}% geometric coverage under stated assumptions.
  4. +
  5. {scenario.id}: reference inputs — area, center and radius defining the starting configuration.
  6. +
  7. {manifest.model.id}: method — model version {manifest.model.version}, numerical contract and limitations.
  8. +
  9. {manifest.test.id}: assertions — canonical behavior checked by the registered test.
  10. +
  11. Reference evaluation and unapproved proposal analyses — actual record inspection instructions, separate from test execution.
  12. +
+
+

Keep one change and one claim together

+

Apply the existing radius-only task. Preserve the criterion and other fixed inputs, inspect the exact radius difference and evaluate that candidate. The shared pure model and evaluator supply the calculation; the presentation supplies controls and explanation. Reusing that implementation keeps browser and automated calculations aligned without making every execution the same evidence.

+

The threshold example asks a different question. It changes the criterion's meaning while retaining the same geometry. Its valid data and possible PASS do not justify the requirement change or fit the radius-only assignment. Keep the candidates separate: combining their definitions would create a configuration whose result neither separate trial establishes.

+

Invalid definitions and insufficient justification also need separate responses. A broken reference blocks the current analysis. A valid radius proposal can still lack evidence about terrain, physical detection or operational usefulness. Correcting a structural error enables analysis; it cannot remove the model's omissions or authorize acceptance.

+
+
+

Review the handover as its next reader

+

Before completing the exercise, imagine receiving your own report without this page beside it. Could you identify the evaluated candidate, find the actual observation and explain why it supports the stated claim? Could you distinguish an unavailable record from a failed criterion? If either answer requires guessing, revise the handover. Its purpose is to preserve enough meaning for another engineer to inspect and challenge the reasoning, including the decision deliberately left open.

+
+
+

Capstone: inspect, experiment and explain

+
    +
  1. Write the operator's question in one sentence. Follow the source route and state the narrower claim V0 can address.
  2. +
  3. Read the radius-only contract. Try the radius example below and inspect exact differences and the proposed definition.
  4. +
  5. Write the observed result with its criterion and assumptions. Identify it as a temporary browser calculation, not retained CI evidence.
  6. +
  7. Reset and try the threshold example. Explain the changed claim and why it is outside this task. Break a reference, observe withholding, then restore/reset.
  8. +
  9. Inspect an actual generated record through the repository route. Record revision, working-tree state and commands actually completed.
  10. +
  11. Complete the written handover below before revealing the reasoning guide.
  12. +
+ +
+
+

Say what actually executed

+

Browser exploration changes a temporary copy and runs the shared calculation. Software assertions check expected behavior, including the canonical geometric FAIL. Reference generation calculates and evaluates canonical inputs but does not invoke those assertions. Proposal generation produces separate unapproved analyses and explicitly does not execute the registered reference test against changed inputs.

+

Review is another activity: it connects observations to a bounded claim and names gaps. Publication makes the learning material available; it is not sensor-design acceptance. A successful build or deployed chapter cannot stand in for a missing analysis record, responsible review or physical validation.

+

Attach each execution claim to actual logs or records. Check source commit, dirty status, evaluated definitions, method and timestamp. A dirty flag alone does not snapshot every source modification. If an artifact is unavailable, state that limitation. Local reproduction is a new execution, not reconstruction of an original event or approval.

+
+
+

Write a short engineering handover

+

Write outside the page; nothing is saved here. Use actual observations, not the reasoning guide as an execution record.

+
    +
  1. Operational question and bounded modeled claim.
  2. +
  3. Task boundary, source revision/working-tree state and evaluated definitions.
  4. +
  5. Actual candidate difference and commands or browser actions completed.
  6. +
  7. Observed outcome, criterion, method and evidence actually inspected.
  8. +
  9. Assumptions, unavailable evidence and counterarguments.
  10. +
  11. Responsible next review and unresolved decision.
  12. +
+
Reasoning guide: what a defensible handover contains

This is guidance, not a completed execution report. State the radius-only geometric claim under the unchanged criterion; copy actual values only from your observed calculation or record. Identify canonical versus proposed definitions, and distinguish browser calculation, assertion logs and generated analyses. Name missing operational support and the responsible next review. Leave acceptance unresolved; do not infer it from PASS or fill missing provenance with invented facts.

+
+
+

Let another engineer reproduce the reasoning

+

Use the repository capstone instructions from an identified checkout. Run existing checks and record generation, inspect actual outputs and compare them with your written claim. No canonical edits, push or publication are needed. The handover is a review aid separate from generated engineering evidence.

+

No historical CI record is loaded by this lesson. The baseline is calculated at build time, and browser edits disappear on reset or reload. Retained CI artifacts expire after 30 days and may require sign-in. A reader can reproduce the calculation while still being unable to inspect an original artifact; report both facts without treating them as equivalent.

+
+
+

Check the whole argument

+
1. What is missing from a handover containing only PASS?

The claim, evaluated definitions, criterion, method, assumptions, execution context and remaining decision. Inspect actual support rather than guessing it.

+
2. Why can green tests preserve an engineering FAIL?

The assertions can correctly check the expected canonical outcome. Software correctness and satisfaction of the modeled criterion answer different questions.

+
3. Does the threshold proposal resolve the radius-only assignment?

No. It changes the criterion and requires a different engineering justification and authority, even if the calculation passes.

+
4. What remains after a reproducible geometric PASS?

Operational suitability and omitted physical behavior remain unverified. Identify required evidence and responsible review; reproducibility alone does not approve the design.

+
+
+

Carry the distinctions into the next engineering problem

+

The principle is now practical: preserve intent, definition and evidence as distinct but connected parts of a reviewable decision. Another engineer should be able to inspect what changed, reproduce the bounded calculation and challenge the conclusion without guessing which sources or assumptions supplied its meaning.

+

This chapter closes the proposed twelve-lesson learning sequence. Multiple sensors, dynamics, actual agents and governance integrations remain separate, unimplemented demonstrator capabilities in the roadmap. Further work should start from a new engineering question and explicit scope, while retaining the same discipline about claims and evidence.

+
+

Revisit intent and evidence, verification, review responsibility or evidence reuse where your handover needs stronger reasoning.

+

← Chapter 11 · Learning path · Inspect engineering sources →

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

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.

+

For the integrated handover exercise, return to Chapter 12.

Intent → definition → evidence

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