diff --git a/AGENTS.md b/AGENTS.md index 5dc8277..1410a1b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,3 +11,13 @@ Use strict source validation. Resolve every ID and source path. Include provenan Make reviewable PR-sized changes. Run npm run check and npm run evidence before handoff. For UI work check keyboard access, labels, text outcomes, mobile layout and GitHub Pages base-path links. Follow ROADMAP.md for subsequent increments. Do not merge or publish changes merely because checks pass. When completing a new lesson, register its path, title and summary in site/src/data/chapters.ts. Home chapter cards and the Learn index share this list; keep it in reading order and include only complete lessons present in the build. Verify both surfaces and base-path links before handoff. + +## V2 transition (Stage 0–1 draft) + +For the proposed future learning design, read project/TUTORIAL-SPEC.md, project/CURRICULUM-MAP.md, project/ENGINEERING-WORKFLOW.md, project/DEMONSTRATOR-LEARNING-PLAN.md, project/EDITORIAL-GUIDE.md and project/INFORMATION-ARCHITECTURE.md, then the relevant chapters/ brief. See docs/v2/ADOPTION-STATUS.md for scope, conflicts and verification. These are proposed educational targets, not evidence of implemented capabilities or authorization for later stages. + +The implemented V0 engineering contract in DEMONSTRATOR_SPEC.md, canonical sources, pure model, schemas and tests retains technical authority. SITE_SPEC.md and historical milestones describe the original curriculum; preserve that release history. For this bounded transition, Home/Learn may describe the proposed twelve-chapter/four-part direction and optional local learning while retaining every published lesson route. Do not require the old per-chapter exercise pattern for future v2 briefs; use meaningful interactions where they teach a distinct decision. Do not rewrite old chapters under this exception. + +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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..11e5972 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Contributing to Executable Engineering Lab + +> **Proposed repository contribution guide.** This file supplements existing V0 engineering instructions; add it only after owner review. Do not alter current data/model contracts through an editorial PR. + +## Scope before implementation + +Read `AGENTS.md`, `SITE_SPEC.md`, `DEMONSTRATOR_SPEC.md`, `MILESTONE_01.md`, the current roadmap and relevant source/decision records. State what you will change and what you will not. The current public name and existing URL should be preserved unless explicitly approved. + +## Editorial guidance + +- Write in straightforward, precise English for practicing engineers, including those new to this tooling. +- Open with a meaningful question or situation before a string of definitions. Explain causal consequences using the actual DMS example where helpful. +- Maintain one significant new learning insight per chapter; avoid duplicating glossary explanations and lengthy caveat blocks. +- Use core browser interactions only when they clarify a useful relationship or decision. **Local exercises are optional**, not mandatory. +- Scenario-based knowledge checks ask readers to judge a realistic situation and then explain the reason behind the outcome. Do not treat quiz completion as evidence of professional competence. +- Use the source vocabulary and domain boundaries carefully: need/requirement/assumption/design/verification/evidence are not interchangeable. +- Support complex explanations with diagrams, tables or simulations when they actually reduce effort; no decorative graphic requirement. +- Identify optional deep references by what readers will gain, with setup/permissions when required. +- Before global editorial changes, propose before/after passages for owner approval. Rewrites must preserve source identifiers, math, documented model limits and existing meaning. + +## Engineering changes + +- Edit canonical YAML in `engineering/`, Zod contracts in `schemas/`, and pure functions/tests in `models/`. Browser UI must not duplicate engineering math. +- Make assumptions explicit, trace inputs and IDs, and report exactly what the verification supports. Current V0 is one fixed ideal circular sensor and sampled geometric coverage—not detection probability or an operational assessment. +- Preserve reproducible evidence; compare deterministic calculation fields separately from run-dependent IDs and timestamps. +- Treat a passing software test suite and a failing engineering acceptance condition as independent facts. + +## Review and checks + +For every change return a readable summary, source paths/IDs affected, what behavior was tested, why the learning interaction is meaningful, and actual limitations. Run `npm run check` and `npm run evidence` where relevant; inspect browser behavior for UI changes. Use a reviewable PR-sized diff and distinguish a ready PR from a merged/published result. Do not publish or merge without owner approval. + +## Decisions + +Project-wide choices should be recorded in `project/DECISIONS.md` or an ADR. A proposed agent/implementation choice is not **Accepted** until the owner confirms it. Supersede obsolete decisions rather than deleting the history of why they were made. diff --git a/README.md b/README.md index 37265b2..acc2c4f 100644 --- a/README.md +++ b/README.md @@ -81,3 +81,7 @@ Pages deployment runs on pushes to `main` after checks pass and can also be trig ## Contributing Use a short-lived branch and reviewable PR. Read [SITE_SPEC.md](SITE_SPEC.md), [DEMONSTRATOR_SPEC.md](DEMONSTRATOR_SPEC.md) and [MILESTONE_01.md](MILESTONE_01.md) as planning inputs. Preserve their scope boundaries. Change engineering definitions in canonical YAML and keep model computation outside the UI. Run `npm run check` and inspect `npm run evidence` before opening a PR. Do not commit generated evidence or build output. See [ROADMAP.md](ROADMAP.md) for remaining work and [docs/VERIFICATION.md](docs/VERIFICATION.md) for recorded browser checks and verification limits. + +## V2 transition proposal + +A Stage 0–1 draft reframes Home/Learn around **Engineering at the Speed of AI** while preserving the published twelve-lesson course and V0. The revised curriculum and multidisciplinary/recorded-agent demonstrations are planned, not implemented. Start with the [foundation overview](docs/v2/FOUNDATION-SPEC.md), [adoption status](docs/v2/ADOPTION-STATUS.md), [tutorial proposal](project/TUTORIAL-SPEC.md) and [staged delivery plan](implementation/IMPLEMENTATION-PLAN.md). This branch is not a publication or acceptance record. diff --git a/agents/EDITOR.md b/agents/EDITOR.md new file mode 100644 index 0000000..01274b4 --- /dev/null +++ b/agents/EDITOR.md @@ -0,0 +1,7 @@ +# Editor — v2 role contract + +## Purpose +Write American English engineer-to-engineer. Lead with concrete decisions. Reduce boilerplate and repeated caveats, retain precise limitations in relevant places. Ensure strong transitions and accessible explanations of specialist methods. Check that every paragraph advances learning and AI appears as an operational rather than late theoretical topic. + +## Shared instructions +Read `AGENTS.md`, v2 tutorial/curriculum/workflow specs, relevant chapter briefs, existing repository implementation and migration plan. Differentiate historical V0 truth from future aspirations. Implement only an explicitly approved scope. Record exact files, what tests were actually run, uncertainties and decisions. Do not fabricate execution, approvals or deployed features. Defer shared-file merges to reviewer/integrator. diff --git a/agents/ENGINEERING-MODELER.md b/agents/ENGINEERING-MODELER.md new file mode 100644 index 0000000..bb2efca --- /dev/null +++ b/agents/ENGINEERING-MODELER.md @@ -0,0 +1,7 @@ +# Engineering Modeler — v2 role contract + +## Purpose +Preserve canonical V0 38.52% vs 50% expected FAIL. Isolate D1+ hypothetical multidisciplinary data. Define evidence/provenance, model fidelity, cross-discipline interfaces, physical lead-time and actual test gates. Review simulation limitations and disallow extrapolation to sensor detection or certification. + +## Shared instructions +Read `AGENTS.md`, v2 tutorial/curriculum/workflow specs, relevant chapter briefs, existing repository implementation and migration plan. Differentiate historical V0 truth from future aspirations. Implement only an explicitly approved scope. Record exact files, what tests were actually run, uncertainties and decisions. Do not fabricate execution, approvals or deployed features. Defer shared-file merges to reviewer/integrator. diff --git a/agents/LEARNING-DESIGNER.md b/agents/LEARNING-DESIGNER.md new file mode 100644 index 0000000..b9b82e2 --- /dev/null +++ b/agents/LEARNING-DESIGNER.md @@ -0,0 +1,7 @@ +# Learning Designer — v2 role contract + +## Purpose +Own unique learning outcomes and adjacent-chapter boundaries. Ensure the 12 briefs form four parts and no repeated radius exercise dominates multiple chapters. Test that exploration, progressive specification and delivery recur as a connected workflow. Verify each brief answers a real engineering question and includes nonsoftware implications where relevant. + +## Shared instructions +Read `AGENTS.md`, v2 tutorial/curriculum/workflow specs, relevant chapter briefs, existing repository implementation and migration plan. Differentiate historical V0 truth from future aspirations. Implement only an explicitly approved scope. Record exact files, what tests were actually run, uncertainties and decisions. Do not fabricate execution, approvals or deployed features. Defer shared-file merges to reviewer/integrator. diff --git a/agents/REVIEWER-INTEGRATOR.md b/agents/REVIEWER-INTEGRATOR.md new file mode 100644 index 0000000..50111f0 --- /dev/null +++ b/agents/REVIEWER-INTEGRATOR.md @@ -0,0 +1,7 @@ +# Reviewer Integrator — v2 role contract + +## Purpose +Own cross-file dependency and conflicting instruction review. Enforce branch-sized migrations, old URL compatibility, actual check evidence, human approvals and v1 preservation. Run overlap audit and verify stage gates before recommending PR approval; never treat a written constraint as runtime enforcement. + +## Shared instructions +Read `AGENTS.md`, v2 tutorial/curriculum/workflow specs, relevant chapter briefs, existing repository implementation and migration plan. Differentiate historical V0 truth from future aspirations. Implement only an explicitly approved scope. Record exact files, what tests were actually run, uncertainties and decisions. Do not fabricate execution, approvals or deployed features. Defer shared-file merges to reviewer/integrator. diff --git a/agents/UX-VISUAL-DESIGNER.md b/agents/UX-VISUAL-DESIGNER.md new file mode 100644 index 0000000..ac34294 --- /dev/null +++ b/agents/UX-VISUAL-DESIGNER.md @@ -0,0 +1,7 @@ +# Ux Visual Designer — v2 role contract + +## Purpose +Make visual components distinct by chapter: roadmap, typed graph, trade-off explorer, progressive-spec studio, authentic agent replay, diff review, readiness dashboard, evidence builder and capstone. Preserve responsive, keyboard, semantic text equivalents, source visibility, Pages basepath. No decorative charts that misrepresent fidelity. + +## Shared instructions +Read `AGENTS.md`, v2 tutorial/curriculum/workflow specs, relevant chapter briefs, existing repository implementation and migration plan. Differentiate historical V0 truth from future aspirations. Implement only an explicitly approved scope. Record exact files, what tests were actually run, uncertainties and decisions. Do not fabricate execution, approvals or deployed features. Defer shared-file merges to reviewer/integrator. diff --git a/chapters/01-the-new-engineering-paradigm.md b/chapters/01-the-new-engineering-paradigm.md new file mode 100644 index 0000000..8d26c27 --- /dev/null +++ b/chapters/01-the-new-engineering-paradigm.md @@ -0,0 +1,49 @@ +# Chapter 01 — The New Engineering Paradigm +Status: v2 implementation brief (proposed) +Part: I — Engineering in the Age of AI + +## The one question +Why does faster AI execution require a different engineering environment? + +## What the reader must gain +Explain how digital threads and agents reinforce each other; identify the production-versus-review bottleneck; recognize discipline-specific cadences. + +## Opening engineering situation +An operations team proposes a distributed monitoring capability. Compare a document/tool-silo workflow with connected information and bounded agent assistance. + +## 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 +Side-by-side interactive lifecycle maps with visible handoff delays and review points; no fabricated productivity numbers. + +## Reuse and migration from v1 +Existing homepage framing and Ch 1 intent explanation; retain Ch 1 V0 lab as legacy/related resource. + +## Technical/editorial constraints +Needs a new narrative and visual; show software, electronics, mechanical and test work; distinguish promises from measured outcomes. + +## 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 team knows what it wants but not which approach is feasible. How should it choose where to invest next? diff --git a/chapters/02-planning-under-uncertainty.md b/chapters/02-planning-under-uncertainty.md new file mode 100644 index 0000000..484637c --- /dev/null +++ b/chapters/02-planning-under-uncertainty.md @@ -0,0 +1,49 @@ +# Chapter 02 — Planning Under Uncertainty +Status: v2 implementation brief (proposed) +Part: I — Engineering in the Age of AI + +## The one question +Which capabilities should we deliver now, and which uncertainties should we explore first? + +## What the reader must gain +Separate vision, themes, initiatives, release increments and backlog; differentiate exploration work and committed capability; explain why discoveries revise roadmap. + +## Opening engineering situation +DMS initiative to improve useful coverage constrained by power, mounting feasibility, sensor supply and schedule. + +## 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 roadmap board: place proposed work into exploration or delivery lanes, reveal dependency, changed priority and release implication. + +## Reuse and migration from v1 +New chapter; reuse choice/feasibility discussion from old Ch 5 and constraints from earlier planning notes. + +## Technical/editorial constraints +Use one primary theme, initiative intent and rationale, multiple releases, owner of decision; avoid maturity-score-only ordering; include nonsoftware lead-times. + +## 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 +One initiative depends on assumptions scattered across files. How do we connect what we know? diff --git a/chapters/03-engineering-knowledge-as-code.md b/chapters/03-engineering-knowledge-as-code.md new file mode 100644 index 0000000..7b1e0cd --- /dev/null +++ b/chapters/03-engineering-knowledge-as-code.md @@ -0,0 +1,49 @@ +# Chapter 03 — Engineering Knowledge as Code +Status: v2 implementation brief (proposed) +Part: II — Building Engineering Knowledge + +## The one question +When one discipline changes a design decision, how do we know what else might be affected? + +## What the reader must gain +Distinguish intent/hypothesis/requirement/interface/decision/evidence; explain typed relations and traceability; test impact across multiple disciplines. + +## Opening engineering situation +Changing sensor position influences coverage, cable length, installation, electrical interface and a pending validation plan. + +## 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 typed digital-thread graph with click-to-inspect semantics and affected/possibly affected nodes; text/table fallback. + +## Reuse and migration from v1 +Merge old Ch 2 and 3 plus source-view aspects of Ch 1 and Ch 11. + +## Technical/editorial constraints +Canonical vs proposed vs recorded state must be visible. No graph infrastructure required: derive graph from fixtures. Never treat all links as proof. + +## 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 graph exposes relationships, but a hypothesis remains uncertain. What experiment would test it? diff --git a/chapters/04-learning-through-models-and-prototypes.md b/chapters/04-learning-through-models-and-prototypes.md new file mode 100644 index 0000000..8c5468a --- /dev/null +++ b/chapters/04-learning-through-models-and-prototypes.md @@ -0,0 +1,49 @@ +# Chapter 04 — Learning Through Models and Prototypes +Status: v2 implementation brief (proposed) +Part: II — Building Engineering Knowledge + +## The one question +What should we simulate, prototype or test before committing to an architecture? + +## What the reader must gain +Distinguish computational models, prototypes, physical tests, model credibility, hypothesis and observation; select experiment to reduce uncertainty. + +## Opening engineering situation +Compare single- and multiple-sensor concepts or mounting alternatives with explicitly synthetic power/cable/lead-time constraints. + +## 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 +Multidisciplinary option explorer and model-fidelity panel, with a controlled comparison and clearly labeled synthetic inputs. + +## Reuse and migration from v1 +Old Ch 4 + Ch 5 plus V0 CoverageLab; retain exact V0 as a reference mode. + +## Technical/editorial constraints +Experimental D1 engine separate from V0; no physical-detection claims; include failure results and what was learned. + +## 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 experiment narrows options. How precise should the next specification be? diff --git a/chapters/05-spec-driven-development-without-waterfall.md b/chapters/05-spec-driven-development-without-waterfall.md new file mode 100644 index 0000000..6d9c0d2 --- /dev/null +++ b/chapters/05-spec-driven-development-without-waterfall.md @@ -0,0 +1,49 @@ +# 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? diff --git a/chapters/06-directing-ai-engineering-agents.md b/chapters/06-directing-ai-engineering-agents.md new file mode 100644 index 0000000..d4ecc9c --- /dev/null +++ b/chapters/06-directing-ai-engineering-agents.md @@ -0,0 +1,49 @@ +# 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? diff --git a/chapters/07-engineering-in-small-reviewable-increments.md b/chapters/07-engineering-in-small-reviewable-increments.md new file mode 100644 index 0000000..036a022 --- /dev/null +++ b/chapters/07-engineering-in-small-reviewable-increments.md @@ -0,0 +1,49 @@ +# 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? diff --git a/chapters/08-continuously-integrated-engineering.md b/chapters/08-continuously-integrated-engineering.md new file mode 100644 index 0000000..e8768bf --- /dev/null +++ b/chapters/08-continuously-integrated-engineering.md @@ -0,0 +1,49 @@ +# 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? diff --git a/chapters/09-verification-validation-and-engineering-evidence.md b/chapters/09-verification-validation-and-engineering-evidence.md new file mode 100644 index 0000000..ac21c83 --- /dev/null +++ b/chapters/09-verification-validation-and-engineering-evidence.md @@ -0,0 +1,49 @@ +# 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? diff --git a/chapters/10-governance-and-engineering-authority.md b/chapters/10-governance-and-engineering-authority.md new file mode 100644 index 0000000..2008abf --- /dev/null +++ b/chapters/10-governance-and-engineering-authority.md @@ -0,0 +1,49 @@ +# 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? diff --git a/chapters/11-managing-engineering-knowledge-at-scale.md b/chapters/11-managing-engineering-knowledge-at-scale.md new file mode 100644 index 0000000..b2c8c42 --- /dev/null +++ b/chapters/11-managing-engineering-knowledge-at-scale.md @@ -0,0 +1,49 @@ +# 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? diff --git a/chapters/12-the-ai-native-engineering-environment.md b/chapters/12-the-ai-native-engineering-environment.md new file mode 100644 index 0000000..2dfdf4c --- /dev/null +++ b/chapters/12-the-ai-native-engineering-environment.md @@ -0,0 +1,49 @@ +# 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. diff --git a/docs/v2/ADOPTION-NOTES.md b/docs/v2/ADOPTION-NOTES.md new file mode 100644 index 0000000..941dfc1 --- /dev/null +++ b/docs/v2/ADOPTION-NOTES.md @@ -0,0 +1,7 @@ +# Adoption and compatibility notes + +Existing repository in discussion: `And-Gu/executable-engineering-lab`. Prior inspection showed a root `SITE_SPEC.md` with a 12-chapter proposal and existing Chapter 1 entitled *From Engineering Intent to Evidence*. This pack recommends ten chapters, beginning with *Engineering in the Age of AI*. **This is an intentional educational revision, not a mandate to delete current content or break routes.** + +The existing fixed single-sensor baseline, model, YAML, tests, CI and reference evidence remain untouched. During adoption create a dedicated branch, compare actual latest repository state, reconcile root documentation, record chapter migration/redirect plan, then review and test before merge. Do not claim that the archive itself is a code change, PR, CI run, or publication. + +Document precedence: existing implemented engineering contract for V0; new `project/` specification for future education once accepted; task-specific reviewed chapter briefs for slices; live project code/source for observed behavior. A decision on publication migration is still required. diff --git a/docs/v2/ADOPTION-STATUS.md b/docs/v2/ADOPTION-STATUS.md new file mode 100644 index 0000000..5ec6061 --- /dev/null +++ b/docs/v2/ADOPTION-STATUS.md @@ -0,0 +1,45 @@ +# V2 adoption — Stage 0/1 foundation + +Prepared 2026-10-23 from the owner-supplied review archive. On 2026-10-24 the owner selected PR #28 and authorized its refinement, merge and publication. The original preparation observations below precede that authorization; they do not describe the subsequent release outcome. Implementation of this bounded transition was requested; owner acceptance of the full v2 curriculum, merge and publication are not recorded. The public original course remains published. This branch changes Home/Learn framing and imports proposed specifications; it does not migrate chapters or implement new demonstrations. + +## Baseline and actual inventory + +- Fetched origin/main and started from clean `5087f980a181bb5f2a51856871068b062d7d3788` (PR #27); the archive reports the same revision. +- Sixteen static routes: Home, Learn, twelve lessons, Lab and Reference. Exact legacy paths/fragments are recorded in [route inventory](ROUTE-INVENTORY.json). +- Completed registry: `site/src/data/chapters.ts`, unchanged. Proposed four-part/twelve-title structure: `site/src/data/v2-curriculum.ts`; no unpublished route is registered or linked. +- Canonical records: NEED-001, REQ-COV-001, SCN-001, MODEL-COV-001 and TEST-COV-001 in engineering/manifest.yaml and source files. Pure calculation/evaluator: models/coverage/. Strict contracts: schemas/. Typed relationships and isolated proposal analyses: exercises/. +- UI: CoverageLab.astro, ProposalWorkspace.astro and Layout.astro remain unchanged. Their shared scripts/calculation are retained. +- Tests: six files, 86 tests reported by Vitest. GitHub validation and Pages workflows remain unchanged. +- Evidence commands generate ignored artifacts/reference-evidence.json and artifacts/proposals/*.json. Canonical output remains 3852/10000 sampled cells, 38.52%, FAIL against 50%; proposal analyses remain unapproved, not reference-test executions. +- Public original Home was inspected during this task: original hero and all twelve lesson cards present. No v2 page is published by this branch. + +## Reconciled conflicts + +| Conflict | Resolution in this draft | Preserved boundary | +| --- | --- | --- | +| Original SITE_SPEC.md curriculum vs revised teaching direction | Import project/ and chapters/ as proposed v2 design; expose planned structure on Home/Learn | Original lessons and historical release specifications untouched | +| Old expectation of an experiment in each chapter vs optional meaningful interactions | Root AGENTS.md scopes the v2 editorial exception to future briefs and this Home/Learn transition | No rewrite or removal of current experiments | +| Old ten-chapter references vs twelve coordinated briefs | Use current package README/curriculum map and twelve briefs; note stale text in PACKAGE-PROVENANCE.md | No silent deletion of received proposal context | +| “Accepted in user dialogue” in imported decision log | Replace introduction with proposed status; no owner approval inferred from attached text | Actual task authorization covers this bounded implementation only | +| V1 course vs V0 demonstrator labels | Use “original course” for published lessons; keep curriculum and demonstrator version labels distinct | No claim of distributed-sensor V1 capability | +| Proposed AGENTS.md vs implemented contract | Reconcile root guidance and retain received proposed text under docs/v2/PROPOSED-AGENTS.md | Technical V0 constraints retain authority | +| Proposed duplicated curriculum arrays | One presentation-only v2Parts module serves both pages | Completed chapter registry remains separate and unchanged | +| Missing templates/ and older prompts | Record absence; do not invent files or execution evidence | Future briefs remain scoped individually | + +## Files and migration policy + +Imported project/, chapters/, agents/, implementation/ and prompts/ hold proposed design/role/delivery inputs. CONTRIBUTING.md is explicitly proposed. docs/v2/ retains package context, provenance, inventory and actual observations. README and root AGENTS.md point to this transition. Runtime changes are limited to Home, Learn and their planned-curriculum data. + +All legacy pages stay at their existing paths with existing IDs/fragments. No redirect, slug rename, registry replacement, tag or deletion is performed. Before a later chapter migration, select a new noncolliding slug in its reviewed slice, document semantic mapping from old material, and keep the original page accessible. Redirect only after content/fragment compatibility is reviewed; never send an old deep link to unrelated content. The package's legacy-to-v2 content map in implementation/CURRENT-STATE-AND-MIGRATION.md is a reuse proposal, not a route migration already applied. + +## Verification and acceptance + +See [verification record](VERIFICATION.md) for actual commands and browser observations. A draft PR and passing checks are not owner acceptance, publication, empirical learning gains or completion of Stage 2–5. No actual agent replay, multidisciplinary engine, graph or physical evidence is claimed. + +Open decisions: future public slugs, inline versus Lab/Explore placement, authentic agent-run capture environment and redaction, hypothetical physical parameters, and acceptance of the new hero before publishing. No templates were included in the received archive. Later slices need their own engineering/editorial review. + +Next proposed PR after Stage 0/1 acceptance: Stage 2 B1, Chapters 01–02 with a distinct workflow/roadmap learning experience. Do not start that slice merely because this draft passes CI. + +## Consolidation decision — 2026-10-24 + +Retain PR #28 as the single candidate. Add the [linked foundation overview](FOUNDATION-SPEC.md) inspired by PR #29, without importing its page code or duplicating curriculum definitions. PR #29 is to be retired without merge. Full v2 completion and later Stage 2–5 delivery remain separate from publishing this foundation. Exact-revision release observations are recorded after deployment. diff --git a/docs/v2/DATA-PACK-README.md b/docs/v2/DATA-PACK-README.md new file mode 100644 index 0000000..8060015 --- /dev/null +++ b/docs/v2/DATA-PACK-README.md @@ -0,0 +1,25 @@ +# Executable Engineering Lab — Agent data pack + +Version 1.0 candidate · 2026-10-20. This is a **complete proposed educational specification package**, not a deployed repository change or completed site rewrite. + +## Start here + +1. `project/TUTORIAL-SPEC.md` — core thesis and reader promise. +2. `project/CURRICULUM-MAP.md` — flexible ten-chapter/four-part sequence. +3. `project/ENGINEERING-WORKFLOW.md` — roadmap, dual loops, progressive specification, agent authority, integration. +4. `project/DEMONSTRATOR-LEARNING-PLAN.md` — DMS evolution and cross-discipline examples. +5. `project/EDITORIAL-GUIDE.md` and `project/INFORMATION-ARCHITECTURE.md` — voice, visuals and source structure. +6. `project/DECISIONS.md` — adopted direction and unresolved choices. +7. `AGENTS.md`, `agents/`, `templates/`, `prompts/` — collaboration instructions and execution workflows. + +## Recommended usage + +Upload/commit the package as a **documentation-only adoption PR** using `prompts/06-RECONCILE-AND-ADOPT.md`. Do not replace existing code, V0 engineering specs or existing Chapter 1 routes blindly. Once the user accepts repository adoption, run chapter work with `prompts/05-CREATE-CHAPTER-BRIEF.md` followed by bounded design/implementation and editorial review. + +## New governing choices + +AI-native, cross-disciplinary *engineering*; agentic focus stronger than digital-thread history; chapter on planning; exploration and delivery in parallel; progressive spec without waterfall; small reviewable changes; integrated information but diverse cadence; software often releasable, hardware controlled with physical readiness; actual source-backed evidence and human authority. + +## Applicability + +The generic `templates/TUTORIAL-SPECIFICATION-TEMPLATE.md` and original starter prompts remain reusable **templates**. Project-specific `project/` documents take precedence for this site. `DEMONSTRATOR_SPEC.md` in the live repo is the authoritative implemented V0 contract, not superseded by example staging here. diff --git a/docs/v2/FOUNDATION-SPEC.md b/docs/v2/FOUNDATION-SPEC.md new file mode 100644 index 0000000..1b4054a --- /dev/null +++ b/docs/v2/FOUNDATION-SPEC.md @@ -0,0 +1,24 @@ +# V2 foundation overview + +The owner selected PR #28 as the single Stage 0–1 delivery candidate on 2026-10-24 after comparing PR #29. This overview is a navigation aid, not another curriculum authority or a claim that the complete v2 course is implemented. + +## Direction + +**Engineering at the Speed of AI:** connect multidisciplinary engineering knowledge with bounded AI-assisted work while retaining engineering judgment, reviewable changes and qualified evidence. + +- Planning, exploration and delivery form connected feedback loops; see [engineering workflow](../../project/ENGINEERING-WORKFLOW.md). +- Progressive specifications expose known constraints and unresolved questions; see [tutorial specification](../../project/TUTORIAL-SPEC.md). +- Software, electronics, mechanical work and physical verification have different cadences; see [demonstrator learning plan](../../project/DEMONSTRATOR-LEARNING-PLAN.md). +- Agent context, tool availability and human authority are distinct; existing V0 sources and tests remain protected by [repository guidance](../../AGENTS.md). + +## 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. + +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. + +## Consolidation + +PR #29's concise overview approach informed this linked entry point. Its page implementations were not merged or cherry-picked: the primary candidate retains shared planned data, continuous numbering, clear status labels and the historical Home anchor. Both candidates passed 86 tests and generated the same expected V0 outcome during comparison. The comparison did not include a new visual/accessibility audit of #29. diff --git a/docs/v2/LESSONS-LEARNED.md b/docs/v2/LESSONS-LEARNED.md new file mode 100644 index 0000000..3232fca --- /dev/null +++ b/docs/v2/LESSONS-LEARNED.md @@ -0,0 +1,68 @@ +# Lessons learned — from Document-as-Code Lab to Digital & Agentic Engineering + +**Perspective:** The tutorial is a learning product. The implementation, simulations and agent instructions serve it; they are not the product's purpose. + +## The major lessons + +### 1. Start with a consequential question + +A chapter becomes easier to read when its first paragraphs establish a problem the reader can recognize. Introduce a term when it helps resolve that problem. In the new lab, “Would this sensor configuration meet the criterion?” is a more engaging starting point than “What is executable engineering?”. Avoid opening with a taxonomy, buzzwords, or a long list of technologies. + +### 2. Teach a genuine distinction, not an obvious contrast + +We rejected the idea of comparing a poorly informed AI with a well-informed AI. More context improving a response is too trivial. Better educational questions are: “Which source is authoritative?”, “What information must an agent find?”, “Is this decision still current?”, and “What does a passing test actually establish?” A good interaction makes readers reconsider an assumption. + +### 3. Reader interactions are optional but must earn their place + +We approved short, **scenario-based knowledge checks** with a prediction or choice followed by immediate causal feedback. Our prototype asked whether metadata with `owner: unknown-team` could pass schema validation. The interesting insight: schema validity does not establish that the owner is correct. For engineering, use analogous reasoning checks about requirements, model assumptions, evidence, trade-offs and authority. Do not add scoring, badges, login, homework or a lab quota. + +### 4. Browser-first does not mean simulation-first + +The essential conceptual learning should be accessible in the published browser. Optional local work can expose the full source, build, model and workflow. A demonstration must use real calculation code where numerical behavior matters. A pleasant animation of an invented outcome is not engineering evidence. + +### 5. The design is more than isolated chapters + +Groups should advance a coherent learning journey; each chapter contributes one new capability. Illustrations, experiments, quizzes and references need contextual introductions and a reason to be there. When the narrative changes example or abstraction level, tell the reader why. The evolving fictional Distributed Monitoring System should supply continuity without forcing every topic into the same visualization. + +### 6. Editorial flow is an architectural concern + +We improved the specification after recognizing that technically accurate content can still feel fragmented. The favored style is **conversational, precise, compact and respectful**, closer to a well-written explanatory book than a technical checklist. Prefer a concrete opening, one idea per paragraph, natural transitions and a clear consequence. Do not mechanically open every chapter with a question. Reduce redundant explanations without removing necessary engineering limits. + +### 7. Short core chapters, deep optional references + +Reader-facing chapters should explain the concepts and show their consequences. Detailed commands, large schemas, math derivations, architecture alternatives, long inventories, and optional exercises belong on linked supporting pages. A reference link should say what the reader gains and whether local tools are necessary. + +### 8. The agent needs a navigable information environment + +`AGENTS.md` is the entry point for working rules, permissions, where to look, and required checks—not a monolithic project encyclopedia. Maintain separate **information architecture**, **terminology/editorial conventions**, **decisions and rationale**, **authoritative engineering sources**, and **verification contracts**. An agent that can read a repository has not necessarily found the right source or received authorization to change it. + +### 9. One source of truth, several experiences + +Canonical engineering records must remain independent of web views. Astro can render source content and mount interactive components, but must not silently duplicate model formulas or authoritative engineering data. Keep transforms and calculators shared between browser and CI where possible. Where the learning chapter itself is authored inside Astro today, do not force a Markdown migration until the costs and benefits are clear. + +### 10. Keep evidence and authority separate + +An approved requirement is not an implemented feature. A passing software test is not necessarily a passing engineering criterion. A model's geometric coverage is not physical detection probability. A temporary browser what-if result is not retained, revision-bound CI evidence. A successful website build is not an editorial or engineering approval. Put these distinctions next to the results they qualify rather than repeating generic disclaimers everywhere. + +### 11. Vertical slices outperform elaborate frameworks + +We made progress by connecting one need, requirement, scenario, model, test and visible result before building a generalized graph platform or agent orchestration. For the next stages, extend this trace chain only when a new engineering question requires it. Avoid premature multi-agent infrastructure, generic ontologies and feature expansion that obscures the lesson. + +### 12. Separate design decisions from empirical validation + +At this stage the user is the tutorial's owner, editor and evaluator. We do not need a formal learner study or fabricated improvement percentages. Present concrete alternatives and before/after examples, let the owner **approve / revise / reject**, and verify the accepted implementation with builds, tests, accessibility checks and visual inspection. Future learner testing can be added later if the audience grows; it is not a present release gate. + +## What we deliberately stopped doing + +- Requiring hands-on exercises in **every** chapter. +- Building extra interactivity simply because it is technically possible. +- Demonstrating obvious AI performance differences in place of useful agent information architecture. +- Treating agent instructions as a substitute for maintained specifications and decision records. +- Using word count, quiz scores, Git activity or page views as a proxy for learning quality. +- Asking AI agents to make undocumented product/editorial choices or to claim unverified completion. + +## What these lessons change in the Digital & Agentic Engineering project + +The existing DMS V0 demonstrator already has a real cause-and-effect loop: alter sensor x/y/radius, see geometric coverage and the evaluated criterion, then follow need → requirement → scenario → model → test → result. Keep that core intact. Improve how the chapter poses the engineering question, invites exploration and explains the evidence. Later increments should each add one meaningful dimension of engineering uncertainty—configuration, behavior over time, agent-assisted changes or governance—not just extra features. + +The long-term reusable asset is not the particular Astro site. It is the **combination of a learning specification, editorial voice, meaningful interaction patterns, an agent-ready information architecture, and a clear verification boundary.** diff --git a/docs/v2/PACKAGE-PROVENANCE.md b/docs/v2/PACKAGE-PROVENANCE.md new file mode 100644 index 0000000..7a77d69 --- /dev/null +++ b/docs/v2/PACKAGE-PROVENANCE.md @@ -0,0 +1,10 @@ +# Received package provenance + +Source: `executable-engineering-lab-v2-stage0-stage1-review.zip`, supplied by the owner on 2026-10-23. +SHA-256: `d09c55db2333f1ddd75c209c7c1a4207aec17b0b7ec9009301ede67a015e3625`. + +Received report and supporting README/adoption notes are retained here as third-party proposal context, not execution/approval evidence. Project, chapter, role, implementation and prompt files are integrated at the corresponding repository paths. Root AGENTS.md is reconciled, not replaced by the proposed file. CONTRIBUTING.md remains explicitly proposed. + +The archive contains 38 files. No templates/ directory or prompts 05/06 are present despite references in older package text. No missing templates, transcripts or approval records have been invented. DATA-PACK-README.md and ADOPTION-NOTES.md mention ten chapters/older titles; the dated package README, curriculum map, twelve briefs and supplied pages consistently propose twelve. That later coordinated target is used for the draft. + +project/DECISIONS.md has a corrected introduction: reported prior dialogue is not treated as repository owner approval. New public slugs, placement of future demonstrations, authentic-run capture and physical-example parameters remain open. diff --git a/docs/v2/PACKAGE-README.md b/docs/v2/PACKAGE-README.md new file mode 100644 index 0000000..aaace9e --- /dev/null +++ b/docs/v2/PACKAGE-README.md @@ -0,0 +1,34 @@ +# Executable Engineering Lab — v2.0 specification and implementation package +Status: **Proposed editorial/engineering target; not adopted or deployed** +Date: 2026-10-23 +Audience: repository owner and implementing AI agents. + +## Start here +1. Read `project/TUTORIAL-SPEC.md`, `project/CURRICULUM-MAP.md`, `project/ENGINEERING-WORKFLOW.md`. +2. Read `implementation/CURRENT-STATE-AND-MIGRATION.md` and `implementation/IMPLEMENTATION-PLAN.md`. +3. Read the twelve individual briefs under `chapters/`. +4. Read `AGENTS.md` and the relevant specialist-agent file. +5. Run `prompts/07-V2-ADOPTION-AND-DELIVERY.md` **in the repository** on a review branch, not on `main`. + +## What this is +A complete specification package, derived from the 2026-10-23 editorial audit and subsequent full-redesign decision. +The new target has twelve chapters and four parts; chapter count is a deliberate v2 decision. +The original V0 coverage engine, source identities, threshold and expected engineering FAIL must remain intact. +V1+ demonstrations are **proposals**, not existing capabilities. No actual agent runtime or multidisciplinary calculation is assumed to exist. + +## Authority +- Existing source code, YAML, schemas, tests and historical milestone evidence remain authoritative for **implemented V0**. +- These v2 project documents are authoritative proposals for **future tutorial design** once explicitly adopted. +- Historical root `SITE_SPEC.md`, `DEMONSTRATOR_SPEC.md`, `MILESTONE_*.md`, and milestone verification reports must not be rewritten to pretend the original release had v2 functionality. +- Do not publish, merge, or claim tests passed without actual evidence. + +## Primary deliverables +- `project/`: seven coordinated specifications. +- `chapters/`: twelve individually scoped chapter briefs. +- `implementation/`: content migration, PR-sized delivery plan, QA/acceptance matrix. +- `agents/`: five specialist role contracts. +- `prompts/`: reusable adoption and chapter implementation prompts. +- `templates/`: reusable structures for future changes. + +## Completion +V2 is complete only when the published experience matches the acceptance criteria in `implementation/QUALITY-GATES.md`, and the repository checks and human review are recorded. diff --git a/docs/v2/PROPOSED-AGENTS.md b/docs/v2/PROPOSED-AGENTS.md new file mode 100644 index 0000000..6b276e3 --- /dev/null +++ b/docs/v2/PROPOSED-AGENTS.md @@ -0,0 +1,12 @@ +# AGENTS.md — v2 proposed repository instructions +## Authority and order +Read the root technical source and tests first. Existing V0 source and model behavior remain authoritative. For proposed future teaching design read `project/TUTORIAL-SPEC.md`, `project/CURRICULUM-MAP.md`, `project/ENGINEERING-WORKFLOW.md`, `project/DEMONSTRATOR-LEARNING-PLAN.md`, `project/EDITORIAL-GUIDE.md`, `project/INFORMATION-ARCHITECTURE.md`, and individual `chapters/` briefs. Historical milestones remain immutable evidence of earlier releases. + +## Non-negotiable preservation +Do not change V0: single ideal circular sensor, 100×100 area and cell-center grid, radius 35 at (50,50), expected 38.52% vs 50% educational criterion. Existing engineering YAML, source IDs, schemas, pure model, tests and evidence remain in place unless separately reviewed and authorized. Software test PASS and modeled requirement FAIL are different facts. Astro must not create a second numerical model or hardcode a PASS. + +## Engineering teaching scope +Teach multidisciplinary AI-native engineering, not exclusively software. Explain planning under uncertainty, progressive specifications, concurrent exploration/delivery, agent context and authority, small reviewable increments, model/physical-test limits and cross-disciplinary cadence. Introduce AI immediately and demonstrate a real recorded agent workflow when the evidence exists. Never invent agent executions or physical measurements. + +## Change process +Inspect code/docs → propose bounded scope → implement incremental slice → independently run and record checks → review engineering and learning quality → publish only on owner authorization. For implementation changes run `npm run check` and `npm run evidence` if possible. Validate URLs, chapter registry, base path, keyboard and responsive layout. Protect old routes during curriculum migration. Specialists have distinct roles in `agents/`; one integrator coordinates shared edits. diff --git a/docs/v2/RECEIVED-REPORT.md b/docs/v2/RECEIVED-REPORT.md new file mode 100644 index 0000000..0a75aa6 --- /dev/null +++ b/docs/v2/RECEIVED-REPORT.md @@ -0,0 +1,24 @@ +# Stage 0 + Stage 1 — Review report + +## Completed in this package +- Compared GitHub `main` at `5087f980a181bb5f2a51856871068b062d7d3788` with the v2 specification package. +- Reviewed actual homepage, Learn index, chapter registry, legacy `SITE_SPEC.md`, `AGENTS.md` and existing 12 lesson routes. +- Preserved all v2 specifications, twelve briefs, agent roles and staged quality gates. +- Prepared complete replacements for `site/src/pages/index.astro` and `site/src/pages/learn/index.astro`. +- Created a reviewable transition status document. +- New pages deliberately label the redesigned chapters as planned and retain V1 chapter links; no fake completed features. + +## Scope intentionally not executed +- Did not change GitHub `main`, create or merge PR, or publish. +- Did not modify original 12 chapters, chapter registry, source YAML, model, tests, or V0 evidence. +- Did not test Astro build/CI (container GitHub network and full checkout unavailable). +- Did not claim to have tested graphical mobile/browser behavior. + +## Recommended adoption +1. Extract this package. Copy the `specification-pack/project`, `chapters`, `agents`, `templates`, `prompts` and implementation docs into a feature branch under suitable paths (with integrator reconciliation against existing docs). +2. Apply just the three files in `proposed-repository-files/` first. +3. Inspect and run full checks; open a **draft** PR for owner review. +4. Only after successful acceptance should new chapters and demonstrations be developed in subsequent PRs. + +## Immediate decision +The homepage can be updated before chapter renumbering because it accurately presents future v2 direction while still linking to *actual published* lessons. Avoid replacing the chapter registry with unpublished new titles. diff --git a/docs/v2/ROUTE-INVENTORY.json b/docs/v2/ROUTE-INVENTORY.json new file mode 100644 index 0000000..b2d8b1f --- /dev/null +++ b/docs/v2/ROUTE-INVENTORY.json @@ -0,0 +1,524 @@ +{ + "baselineCommit": "5087f980a181bb5f2a51856871068b062d7d3788", + "note": "All old routes/fragments retained; Home/Learn add published-lessons anchors. Unchanged legacy pages retain exact source.", + "routes": [ + { + "path": "/executable-engineering-lab/", + "baselineFragments": [ + "main", + "learning-path" + ], + "draftFragments": [ + "main", + "published-lessons", + "learning-path" + ] + }, + { + "path": "/executable-engineering-lab/lab/", + "baselineFragments": [ + "main", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title" + ], + "draftFragments": [ + "main", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title" + ] + }, + { + "path": "/executable-engineering-lab/learn/01-engineering-intent/", + "baselineFragments": [ + "main", + "question", + "criterion", + "model", + "exercise", + "exercise-heading", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title", + "evidence", + "quiz", + "quiz-heading" + ], + "draftFragments": [ + "main", + "question", + "criterion", + "model", + "exercise", + "exercise-heading", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title", + "evidence", + "quiz", + "quiz-heading" + ] + }, + { + "path": "/executable-engineering-lab/learn/02-engineering-information-models/", + "baselineFragments": [ + "main", + "change", + "contracts", + "exercise", + "exercise-title", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "evidence", + "quiz" + ], + "draftFragments": [ + "main", + "change", + "contracts", + "exercise", + "exercise-title", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "evidence", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/03-digital-threads/", + "baselineFragments": [ + "main", + "question", + "thread", + "experiment", + "experiment-title", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "thread", + "experiment", + "experiment-title", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/04-executable-models/", + "baselineFragments": [ + "main", + "question", + "calculation", + "exercise", + "exercise-heading", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "calculation", + "exercise", + "exercise-heading", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/05-experimentation/", + "baselineFragments": [ + "main", + "question", + "protocol", + "exercise", + "exercise-heading", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title", + "interpret", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "protocol", + "exercise", + "exercise-heading", + "experiment-title", + "coverage-title", + "coverage-description", + "area-clip", + "sensor-x", + "sensor-y", + "sensor-radius", + "input-help", + "comparison-title", + "interpret", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/06-verification-evidence/", + "baselineFragments": [ + "main", + "claim", + "checks", + "exercise", + "exercise-heading", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "record", + "limits", + "quiz" + ], + "draftFragments": [ + "main", + "claim", + "checks", + "exercise", + "exercise-heading", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "record", + "limits", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/07-agentic-engineering/", + "baselineFragments": [ + "main", + "task", + "contract", + "exercise", + "exercise-heading", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "checks", + "quiz" + ], + "draftFragments": [ + "main", + "task", + "contract", + "exercise", + "exercise-heading", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "checks", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/08-engineering-context/", + "baselineFragments": [ + "main", + "question", + "context", + "exercise", + "exercise-heading", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "actions", + "action-review-heading", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "context", + "exercise", + "exercise-heading", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "actions", + "action-review-heading", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/09-continuous-engineering/", + "baselineFragments": [ + "main", + "question", + "feedback", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "cases", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "feedback", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "cases", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/10-governance-assurance/", + "baselineFragments": [ + "main", + "question", + "controls", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "gaps", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "controls", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "gaps", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/11-engineering-knowledge/", + "baselineFragments": [ + "main", + "question", + "configuration", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "cases", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "configuration", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "cases", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/12-integrated-environment/", + "baselineFragments": [ + "main", + "question", + "route", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "handover", + "reproduce", + "quiz" + ], + "draftFragments": [ + "main", + "question", + "route", + "exercise", + "workspace-heading", + "baseline-heading", + "proposal-kind", + "proposal-value", + "proposal-help", + "proposal-need", + "reference-help", + "handover", + "reproduce", + "quiz" + ] + }, + { + "path": "/executable-engineering-lab/learn/", + "baselineFragments": [ + "main" + ], + "draftFragments": [ + "main", + "published-lessons" + ] + }, + { + "path": "/executable-engineering-lab/reference/", + "baselineFragments": [ + "main", + "relationships", + "proposal-evidence", + "retained-evidence", + "NEED-001", + "REQ-COV-001", + "SCN-001", + "MODEL-COV-001", + "TEST-COV-001" + ], + "draftFragments": [ + "main", + "relationships", + "proposal-evidence", + "retained-evidence", + "NEED-001", + "REQ-COV-001", + "SCN-001", + "MODEL-COV-001", + "TEST-COV-001" + ] + } + ] +} diff --git a/docs/v2/VERIFICATION.md b/docs/v2/VERIFICATION.md new file mode 100644 index 0000000..5fe63be --- /dev/null +++ b/docs/v2/VERIFICATION.md @@ -0,0 +1,41 @@ +# Stage 0–1 verification — v2 transition draft + +Checked 2026-10-23. Development observations, not engineering approval or publication. Baseline fetched from origin/main: `5087f980a181bb5f2a51856871068b062d7d3788`. + +## Executed checks + +Before changes, `npm run check`, `npm run evidence` and `npm run proposals` passed: 86 tests in six files, zero Astro/TypeScript diagnostics, sixteen static routes, canonical 38.52% FAIL against 50%. The actual public Home showed the original hero and twelve completed lesson cards. No tag was created. + +After changes, the same check/evidence/proposals commands passed with the same engineering outcomes. The source/model/test/component/workflow layers and twelve chapter sources are unchanged relative to baseline. Radius analysis remains 63.76%/50% PASS; threshold analysis remains 38.52%/35% PASS, explicitly unapproved and without registered reference-test execution against changed inputs. + +Generated output inspection resolves 419 local links/assets/fragments, with unique IDs. All sixteen routes remain; Home's historical `#learning-path` anchor is retained. [Inventory](ROUTE-INVENTORY.json) distinguishes baseline/draft fragments. The original completed registry is unchanged; four-part planned data is separate, with chapter numbering 1–12 and no links to nonexistent chapters. Home and Learn render their planned structure from that one presentation module. + +Generated Home/Learn require no JavaScript for narrative, planned/current status or links. No client script, dependency or animation was introduced. Full JavaScript-disabled browser or reduced-motion preference testing was not performed. + +## Browser smoke observations + +Reviewed the production build via Astro preview on port 4327 at the GitHub Pages base path. + +| Check | Actual observation | +| --- | --- | +| Home hero/status | AI, connected knowledge, control and multiple disciplines visible; v2 curriculum in development; demonstrations/recorded workflows labeled planned | +| Home published cards | Twelve existing lesson cards and Read Chapter links retained | +| Learn | Four planned groups, twelve titles numbered 1–12; twelve separate published lesson links | +| Direct lesson routes | All twelve opened and reloaded, with expected title and heading | +| Source navigation | Existing chapter/source links remain in generated link/fragment review; no legacy page source changed | +| Proposal workspace in Chapter 12 | Radius 63.76% PASS; invalid reference withholds analysis; restore/reset returns 38.52% FAIL | +| Standalone lab | Radius 45 gives 63.76% PASS; radius -1 is rejected; keyboard reset restores 38.52% FAIL | +| First Tab after Home reload | Skip-to-content focused | +| Learn jump link | Enter reaches #published-lessons | +| Browser history | Home → Learn → back → forward retains correct pages | +| 1280px Home | No document overflow; desktop screenshot inspected | +| 375px Home/Learn | Document width 375px without overflow; mobile Home screenshot inspected | +| Browser console errors | None observed during checked flows | + +Screenshots in workspace outputs: v2-home-preview.png, v2-home-desktop.png, v2-home-mobile.png, v2-learn-mobile.png. A first mobile screenshot was stale after viewport resize; it was replaced after reload and reinspection. Browser actions used the actual local build, not an image mockup. + +## Limits and gates + +This is not full screen-reader, zoom, cross-browser or empirical learning-effectiveness testing. All old routes were directly tested, but every old exercise was not repeated. No new v2 lesson, graph, multidisciplinary calculation, authentic agent-run replay, physical measurement or approval mechanism is implemented. Stage 2–5 site-level acceptance gates remain open; the imported quality matrix must not be read as passing by documentation. + +Stage 0 inventory/checks and Stage 1 Home/Learn implementation are prepared for owner review in a draft PR. Full curriculum acceptance, new slug/redirect selection, future scenario parameters and authentic-run capture remain unresolved. No merge, deployment, settings change or public v2 verification is claimed. The existing production site remains the original course until authorized release. diff --git a/implementation/CURRENT-STATE-AND-MIGRATION.md b/implementation/CURRENT-STATE-AND-MIGRATION.md new file mode 100644 index 0000000..3109fd7 --- /dev/null +++ b/implementation/CURRENT-STATE-AND-MIGRATION.md @@ -0,0 +1,44 @@ +# Current state audit and content migration +Source: publicly connected GitHub `And-Gu/executable-engineering-lab` default branch observed on 2026-10-23. Do not interpret this as a fresh UI/browser test. + +## Verified source architecture +- Homepage `site/src/pages/index.astro`: hero 'From engineering intent to working systems', introductory single-sensor model, chapter cards. +- `site/src/pages/learn/index.astro`: linear list with 12 lessons. +- Existing routes `site/src/pages/learn/01-engineering-intent.astro` through `12-integrated-environment.astro`. +- Shared `site/src/data/chapters.ts` indexes published lessons. +- `site/src/components/CoverageLab.astro` and `ProposalWorkspace.astro` support many lessons. +- `site/src/layouts/Layout.astro` provides shell and footer. +- Root `SITE_SPEC.md`, `DEMONSTRATOR_SPEC.md`, `MILESTONE_*.md`, `ROADMAP.md`, `AGENTS.md`; original canonical model/source/test layers. +- Historical `ROADMAP.md` records milestones and published Pages deployments. These are evidence of original releases, not approval of new v2 behavior. + +## Legacy-to-v2 content map +| Existing chapter | Main migration use | Preservation | +|---|---|---| +| 01 Intent→Evidence | Ch 03–04 and reference lab | Keep V0 worked example | +| 02 Information Models | Ch 03, Ch 05 | Retain validation lessons | +| 03 Digital Threads | Ch 03, Ch 11 | Preserve typed relationships | +| 04 Executable Models | Ch 04 | Preserve exact calculation / method | +| 05 Experimentation | Ch 02, Ch 04 | Preserve comparison exercise | +| 06 Verification Evidence | Ch 09 | Preserve test/evidence distinctions | +| 07 Agentic Engineering | Ch 06, Ch 10 | Preserve task-contract review | +| 08 Agent Context | Ch 06 | Preserve context checklist | +| 09 Continuous Engineering | Ch 08 | Preserve true CI/evidence process | +| 10 Governance | Ch 09–10 | Preserve controls/authority limits | +| 11 Knowledge at Scale | Ch 11 | Preserve baseline/reuse reasoning | +| 12 Integrated Environment | Ch 12 | Preserve handover exercise in reference | + +## Route migration requirements +1. Inventory *all* old public hrefs (including lessons, home, docs and social shares). +2. Introduce new chapters with new route slugs and keep old lesson slugs as redirects or fully accessible legacy pages until owner approves deprecation. +3. Never silently point a deep link to semantically unrelated content. +4. Update published chapter registry only after target pages are complete and checked. +5. Reconcile historical milestone docs as history; do not overwrite release revision references. +6. Avoid deleting old code, interfaces or fixtures until v2 parity and owner review. + +## Key deficits to close +- Homepage currently introduces DMS geometry, not AI-native engineering. +- No explicit planning or progressive-spec chapters. +- Agentic lesson uses a *manual* simulation, not executed agent. +- Most chapters repeatedly use one radius/threshold proposal. +- DMS examples do not show authentic cross-discipline tensions and lead times. +- Repeated warnings displace narrative and varied learning. diff --git a/implementation/IMPLEMENTATION-PLAN.md b/implementation/IMPLEMENTATION-PLAN.md new file mode 100644 index 0000000..25d35cc --- /dev/null +++ b/implementation/IMPLEMENTATION-PLAN.md @@ -0,0 +1,50 @@ +# V2 delivery plan — PR-sized vertical increments +Status: proposed, no repository changes made by this package. + +## Stage 0 — Inventory and test baseline (PR A0; docs only) +- Fetch current main and public URLs; record commit SHA. +- Capture route, component, source-ID, test and evidence inventory. +- Run `npm run check`, `npm run evidence` and record outputs. Check Pages/base path links, screenshots and accessible navigation. +- Tag or otherwise retain last known working v1 only with owner authorization. +**Gate:** baseline evidence, regression list and redirect proposal recorded. + +## Stage 1 — Adopt curriculum and new Home (PR A1) +- Integrate project specs/briefs/agent roles without erasing implemented V0 constraints. +- Make Home hero AI-native and cross-discipline; four-part Learn overview (old lesson links stay usable). +- Implement progressive upgrade path (both old/new routes remain valid). +**Gate:** working routes, accurate capability claims, accessible mobile/desktop layout. + +## 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. +- 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. +**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. +**Gate:** one coherent DMS initiative across chapters and clear outstanding physical validations. + +## Stage 5 — Final editorial/UX QA (PR E1 then optional small fixes) +- One editor conducts all-chapter overlap audit; remove repetitive caveats, tighten prose. +- Test responsive layouts, links, screen-reader semantics, keyboard labs, focus order and browser history. +- Independent engineering reviewer checks claims, model status and cross-discipline plausibility. +- Re-run full check/evidence/build, verify deployed Pages by browser after owner-approved merge. +**Gate:** QA matrix passes; recorded caveats disclosed. + +## Cross-PR non-negotiable invariants +- Reference V0 sensor and area; geometric sample method; 38.52% result and 50% teaching requirement remain unchanged. +- Source IDs and canonical source roles remain stable. +- Software tests can PASS when the modeled requirement FAILs; never erase this distinction. +- `CoverageLab` and `ProposalWorkspace` stay accessible until superseding interactions demonstrably retain their educational functionality. +- GitHub Pages site base path `/executable-engineering-lab/` and all existing deep links work. +- Agent never merges, publishes, changes architecture beyond agreed scope or fabricates evidence. +- Any proposed physical values are explicitly hypothetical until physically verified. diff --git a/implementation/QUALITY-GATES.md b/implementation/QUALITY-GATES.md new file mode 100644 index 0000000..376c3dc --- /dev/null +++ b/implementation/QUALITY-GATES.md @@ -0,0 +1,40 @@ +# Acceptance criteria and QA matrix + +## Site-level acceptance +| 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 | +| 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 | +| Model honesty | V0 expected FAIL and CI PASS separated; experimental physical inputs labeled synthetic | +| Preservation | All old direct links work and v1 behavior can be recovered | +| Engineering | `npm run check` + `npm run evidence` executed and results recorded, not assumed | +| Accessibility | Keyboard, focus, labels, zoom/mobile, text outputs and reduced-motion reviewed | +| Cross-chapter | No two chapters use same primary learning experience; conclusions lead onward | +| Sources | Identifiable revision, inputs, method and known limitations for reported results | + +## Editorial review per chapter +- Meaningful engineering problem visible immediately. +- New knowledge/decision added beyond prior chapter. +- Clarity and concision; define jargon once, avoid repeated defensive caveats. +- Primary diagram or interaction is informative and accessible. +- Explicitly identify simulated versus actual work. +- Distinguish software release cadence from physical product readiness where relevant. +- Honest human vs agent decision authority. + +## Regression test checklist +- `npm run check` +- `npm run evidence` +- Existing V0 model/source/coverage tests +- Source-ID resolution and proposal validation +- Home/Learn chapter registry and navigation +- Old and new routes including direct reload and GitHub Pages base path +- Interactive input invalid/reset/keyboard behavior +- Actual browser desktop/mobile screenshots +- Published GitHub Pages smoke test after authorized release + +## Gate semantics +BLOCKED = feature missing or untested, NOT 'passes by documentation.' +OWNER ACCEPTANCE = explicit editorial/engineering approval; never generated by an agent. diff --git a/project/CURRICULUM-MAP.md b/project/CURRICULUM-MAP.md new file mode 100644 index 0000000..10d91f6 --- /dev/null +++ b/project/CURRICULUM-MAP.md @@ -0,0 +1,35 @@ +# Curriculum map — 12 chapters, four parts (v2.0) +Status: proposed. Routes below are targets; **do not assume they exist**. + +| Part | # | Chapter | Distinct learning gain | Demonstration | +|---|---:|---|---|---| +| I — Why and what next | 01 | The New Engineering Paradigm | Explain AI+digital engineering convergence | Fragmented vs connected workflow | +| 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 | +| 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 | +| 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 | + +## 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. +**These arrows do not imply waterfall or mandatory course navigation.** + +## Narrative controls +- Planning, spec development, agents and review are core; do not subordinate them to V0 geometric explanation. +- Keep a reusable illustrative DMS storyline, but each chapter must move a real engineering question forward. +- Show feedback upstream to planning, hypotheses and interface decisions. +- Keep long-lead electronics/mechanical/physical-test cadences visible. +- Link existing V0 topics to optional sidebars/references where main narrative would become repetitive. diff --git a/project/DECISIONS.md b/project/DECISIONS.md new file mode 100644 index 0000000..fb77ac8 --- /dev/null +++ b/project/DECISIONS.md @@ -0,0 +1,19 @@ +# Decision log — v2.0 proposed decisions +Imported proposal record. The package reports prior dialogue; that is not an approval record in this repository. All items below remain proposed pending review of this draft PR. + +- V2-001: Twelve chapters grouped in four parts; chapter count retained for the full redesign. +- V2-002: AI-native, multidisciplinary engineering is the main subject. Digital threads and agents are mutually reinforcing. +- V2-003: Software engineering practices are *examples*, not universal norms. Different engineering disciplines have different lead times and physical gates. +- V2-004: Dedicated Planning Under Uncertainty and Spec-Driven Development Without Waterfall chapters. +- V2-005: Progressive Specification; concurrent exploration and delivery; human authority at promotion/approval. +- V2-006: Browser-first, meaningful interaction, optional local reproduction, accessible educational design. +- V2-007: Preserve canonical DMS V0 and historical milestone evidence, even if curriculum and routes are rearranged. +- V2-008: Extend demonstration via scoped synthetic multidisciplinary scenarios and authentic recorded agent execution, never fabricate capability. +- V2-009: Small PRs with explicit learning and engineering quality gates, not a one-shot rewrite. + +Open owner/product decisions: +- V2-OD1: Exact new public slugs and redirect policy (recommend stable new slugs and maintained legacy aliases). +- V2-OD2: Whether new visualization resides under `Lab`/`Explore` or inline with both links. +- V2-OD3: Real agent-run provider/reproducibility environment and anonymization; must avoid exposing secrets. +- V2-OD4: Appropriate illustrative physical parameters and how to mark scenario fidelity. +- V2-OD5: Whether production site retitles hero to 'Engineering at the Speed of AI' while keeping site name 'Executable Engineering Lab' (recommended). diff --git a/project/DEMONSTRATOR-LEARNING-PLAN.md b/project/DEMONSTRATOR-LEARNING-PLAN.md new file mode 100644 index 0000000..b23f4fe --- /dev/null +++ b/project/DEMONSTRATOR-LEARNING-PLAN.md @@ -0,0 +1,27 @@ +# DMS demonstrator learning plan — preserve V0, extend through isolated increments + +## Existing V0 (protected) +Single fixed ideal circular sensor in 100×100 rectangular area; 100×100 cell-center sampling; source radius 35 at (50,50); geometric coverage 38.52% vs educational 50% criterion → engineering FAIL. Unit tests may PASS. Preserve canonical IDs, YAML, Zod schemas, numerical method and exact baseline output. It does not estimate detection probability or hardware performance. + +## V2 educational extension strategy (future proposals) +All numbers for later scenarios are synthetic and **must be tagged hypothetical**. New exploratory data, separate schemas/model namespaces; no alteration to V0 canonical source behavior. + +### D1 — Cross-disciplinary trade-off (Chapter 04) +Two simplified sensor placement architectures or mounting alternatives; coverage, hypothetical power budget, cable distance, mount restriction and procurement lead time. One view reveals a gain in coverage that conflicts with another discipline. Do not imply validated physics. + +### D2 — Planning and specification continuity (Chapters 02, 05) +A named roadmap initiative: improve monitored-area usefulness within power and installation constraints. +Exploration tickets, option/assumption decisions, next release capability, and a small bounded specification are connected by *references*, not fake completed gates. + +### D3 — Agent change story (Chapters 06–07) +Use a **real captured** agent run on a harmless isolated educational branch or fixture: objective, available context, tool commands, exact candidate diff, independent check output, review commentary, timestamp and source revision. +If no authentic run exists, show a clearly labeled mock walkthrough and leave the authentic-run acceptance gate open. Never fake a transcript. + +### D4 — Cross-disciplinary integration case (Chapter 08) +Track independent readiness of model assertions, software tests, simulated electronics interface contract, mechanical installation constraints and scheduled physical tests. A green software build does not make physical tests green. + +### D5 — Evidence and configuration case (Chapters 09–12) +Claim–argument–evidence paths; variant A/B; supplier or interface revision; reviewer approval still a named human decision. Reuse only evidence demonstrated applicable to exact configuration and assumptions. + +## Scope discipline +Propose D1–D5 as separate staged PRs. Maintain V0 UI/lab, accessible paths, tests, evidence exports and source references until replacement routes are feature-parity verified. Build new lessons around authentic capability, not UI that promises unavailable backend behavior. diff --git a/project/EDITORIAL-GUIDE.md b/project/EDITORIAL-GUIDE.md new file mode 100644 index 0000000..33117a8 --- /dev/null +++ b/project/EDITORIAL-GUIDE.md @@ -0,0 +1,25 @@ +# Editorial and visual guide v2.0 + +## Voice +American English, confident but measured, practical and readable. Engineer-to-engineer, not marketing. Avoid anthropomorphizing tools (prefer 'the agent requires access to ...' or 'the workflow provides ...' over 'AI wants ...'). Start with a meaningful decision or tension. Keep one purpose per paragraph. + +## Chapter composition +A chapter brief specifies a **unique** learning gain, opening engineering question, scenario progression, narrative arc, one primary visualization/interactivity, evidence boundary, and next chapter bridge. Do not mandate identical heading sequences or a custom code lab per chapter. Exercises optional where value is clear. Ask reader to predict before revealing answers when appropriate. + +## Repetition budget +Reference known distinctions rather than re-explaining baseline FAIL, 50% teaching criterion, dirty-worktree provenance, or lack of physical detection in every chapter. One concise caveat near relevant output; persistent source/assumptions reference for full details. New chapter must introduce new decision content, not only re-run radius/threshold proposal. + +## Multidisciplinary audit +Each part represents at least two distinct non-software disciplines in substantive scenarios. At least one cross-discipline decision has conflicting constraints and lead-times. Distinguish design maturity, model confidence and physical acceptance. + +## Visual language +Muted earth/olive palette retained where helpful; typography with strong hierarchy, whitespace, meaningful diagrams, few decorations. Prefer real interactive graph/scenario/workflow visualization to stock images. Label model provenance and simulated vs historical vs live data. Maintain keyboard operation, semantic labels, text equivalent, reduced motion where useful and narrow-screen usability. + +## Language examples +Avoid: 'The source relation establishes what the evidence supports' repeated as boilerplate. +Prefer: 'A larger footprint improves the calculation. It does not tell us whether the sensor can be powered or mounted there.' +Avoid: 'The agent optimizes the architecture' unless an agent actually runs and a bounded objective is defined. +Prefer: 'The recorded agent run proposes a configuration. An engineer reviews the changes and evidence before adoption.' + +## Writing QA +Ask: Is the engineering problem visible in the first 150 words? Is jargon explained once? Does a reader gain a new skill or decision capability? Does the example advance? Are limitations precise rather than repetitive? Does the conclusion bridge forward? diff --git a/project/ENGINEERING-WORKFLOW.md b/project/ENGINEERING-WORKFLOW.md new file mode 100644 index 0000000..c7d40ed --- /dev/null +++ b/project/ENGINEERING-WORKFLOW.md @@ -0,0 +1,39 @@ +# Engineering workflow — progressive specification and two concurrent loops + +## Common information states +**Intent:** why and what outcome; **uncertainty/hypothesis:** not-yet-confirmed explanation; **experiment:** designed observation; **observation:** recorded output with provenance; **assessment:** qualified interpretation; **decision:** named owner accepts an option; **controlled engineering definition:** versioned requirements/interfaces/models; **execution evidence:** recorded check/test tied to exact sources. + +No state silently becomes another. Agents may propose changes to all states, but only explicitly authorized workflow grants adoption or approval. + +## Planning hierarchy +Platform/system vision → technical roadmap themes and initiatives → intended release capabilities / exploration questions → backlog epics, enablers, debt, stories. +One initiative may deliver through several releases. Product definition absorbs and refines earlier intent; links from every final requirement back to planning intentions are not automatically required. Important constraints and decisions retain context/provenance. + +## Exploration loop +Question → working hypothesis → model or prototype → experiment → observation → decision → update understanding/roadmap. +May use sandboxed branches; fidelity and assumptions documented. +Outcomes include disproved hypotheses, residual risk and what to investigate next. + +## Delivery loop +Bounded capability → progressive slice specification → interface/change analysis → implement → automated checks → independent review → integrate with controlled baseline. +Changes must remain reviewable; do not authorize expanding work scopes automatically. +Use thin vertical slices crossing relevant disciplines where possible, without pretending that a new physical part can be manufactured in one iteration. + +## Different engineering cadences +- Software: frequent build and validation, target releasability if appropriate. +- Electronics: schematics/simulation can iterate quickly; hardware samples/procurement/EMC often slower. +- Mechanical: digital trade studies can iterate quickly; physical fabrication and installation constrained. +- Physical verification: rig access, qualification, environmental testing can be gated. +Synchronize **interface versions, planned integrations and evidence**, not identical iteration schedules. + +## Agent control +Task contract = objective, authority, canonical sources, permitted edits, protected sources, tools, time/cost bounds, validation steps, stop conditions, expected review artifact. +Agent-generated claims are not independently accepted facts. +An agent cannot change its own success criteria or approve its own architecture/compliance claims. + +## Promote experiment to baseline +Require accepted rationale, source diff, model/assumption impact, stakeholder review, test plan and versioned integration decision. +An experiment PASS alone is insufficient. + +## Definition of ready for next slice +Intent and constraints understood; open questions named; tests/evidence appropriate to stage; small enough for review; affected disciplines/interfaces identified. diff --git a/project/INFORMATION-ARCHITECTURE.md b/project/INFORMATION-ARCHITECTURE.md new file mode 100644 index 0000000..c1db7ad --- /dev/null +++ b/project/INFORMATION-ARCHITECTURE.md @@ -0,0 +1,27 @@ +# Information architecture v2.0 + +## 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. +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. + +## Content types +- `project/` v2 strategic editorial/product specs. +- `chapters/` per-chapter implementation briefs. +- Existing `engineering/`, `schemas/`, `models/`, `scripts/` authoritative V0 definitions and computation. +- New experimental demonstrations isolated under a namespaced future directory agreed in PR, with versioned scenario fixtures. +- `site/src/data/chapters.ts` remains the published chapter registry; do not register incomplete/unpublished routes. +- Historical milestone documents retained with historical labels. + +## Information presentation +Reader-facing narrative displays decisions/diagrams before raw source. +Each interactive result links to an explanation of underlying inputs, assumption status and limitations. +Use 'canonical', 'proposed', 'hypothetical', 'recorded run', 'unverified', 'approved' as precise status terms; never conflate. +Preserve existing URL paths by redirects, aliases, or published fallback until migration acceptance; verify GitHub Pages base path. + +## Navigation and deep links +Every page has clear location (part/chapter), forward/back, Learn index, source/reference links. +A migrated old slug should lead to appropriate new content or historical archived lesson; no 404s. +Never claim a scenario/agent run is live if it is a static replay. diff --git a/project/TUTORIAL-SPEC.md b/project/TUTORIAL-SPEC.md new file mode 100644 index 0000000..b6c120c --- /dev/null +++ b/project/TUTORIAL-SPEC.md @@ -0,0 +1,58 @@ +# Tutorial specification v2.0 — Executable Engineering Lab +Status: proposed | Language: American English | Format: browser-first Astro tutorial + +## Product promise +**Engineering at the Speed of AI.** +Show how connected engineering knowledge and constrained AI-assisted work increase the speed of learning and controlled delivery in multidisciplinary systems, without abandoning engineering judgment, architecture or verification. + +## Central thesis +Digital engineering has long sought connected information across engineering disciplines. Agentic AI can use and transform that information at high speed, increasing both opportunity and the need for control. Knowledge, exploratory models, progressive specifications, reviewable increments and engineering evidence must co-evolve. + +## Audience +Practicing systems, mechanical, electronics, software, manufacturing, integration, safety and verification engineers; engineering leads and technically engaged managers. Do not assume familiarity with Git, Astro, YAML, SysML, specific agents or CI. Explain terms where first used; add optional implementation depth. + +## Learning outcomes +At the end readers can: +1. Explain why integrated information and agentic workflows reinforce one another. +2. Separate vision, roadmap initiative, uncertainty, release increment and implementation backlog. +3. Distinguish intent, hypothesis, controlled definition, observed evidence and decision. +4. Navigate and critique cross-discipline digital threads and change impact. +5. Design an informative model or prototype and qualify its fidelity. +6. Use progressive specification without freezing unknown implementation details. +7. Bound agent authority, context, tools, and evidence demands. +8. Break work into small reviewable increments while respecting long-lead disciplines. +9. Interpret continuous checks and physical verification status accurately. +10. Follow an engineering initiative from uncertainty through decision and controlled integration. + +## Content commitments +- AI is explicit on Home and in Chapter 1, not introduced late. +- **Engineering** includes software and non-software disciplines in every part. Avoid generic software-only examples. +- Explain that tool-neutral, machine-readable sources can complement or replace *some roles* of Word, databases and SysML tools; do **not** assert universal obsolescence. +- Exploration and delivery run in parallel. A prototype can teach without entering the product baseline. +- Software may be continuously releasable; physical hardware may be integration- or qualification-gated. Do not equate these cadences. +- Do not use a single `sensor radius` trial as the primary interaction in successive chapters. +- Models and demo data must be explicitly marked as hypothetical when not physically validated. +- Every chapter has a distinct insight, a relevant authentic engineering decision, an appropriate visual/interactive treatment and a meaningful transition. +- The site is not a platform advertisement, a static content dump, or an autonomous approval system. + +## Experience +Main routes: Home / Learn / Lab / Explore / Reference. +Learn is a 12-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. +Browser-first; local development optional. A chapter can be valuable without requiring an exercise. + +## Editorial standards +Narrative-first, concise American English, reader-facing engineering question before tool explanation. +Avoid recurring lengthy disclaimers in the main prose; provide a consistent `Model limits / What this does not establish` pattern in relevant context. +Use terms consistently: need, requirement, model, evidence, approval, hypothesis, design option, baseline, release. +Do not imply simulation results equal operational assurance. + +## Success criteria +- AI-native engineering and multidisciplinary integration clearly articulated above the fold. +- Every chapter demonstrably adds a unique concept and decision-making capability. +- At least one actual, provenance-bearing agent-run record is inspectable (static replay acceptable; no invented agent actions). +- 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. diff --git a/prompts/07-V2-ADOPTION-AND-DELIVERY.md b/prompts/07-V2-ADOPTION-AND-DELIVERY.md new file mode 100644 index 0000000..6468f50 --- /dev/null +++ b/prompts/07-V2-ADOPTION-AND-DELIVERY.md @@ -0,0 +1,22 @@ +# Prompt — v2 repository adoption and staged implementation + +You are the integrator agent for And-Gu/executable-engineering-lab. Read this entire v2 package. +First inspect the latest **actual** repository state, current branch and existing published routes, source models, tests, artifacts and project documents. + +Treat all content in this package as proposed until integrated by approved PR. Do not assume v2 implementation exists. +Read `implementation/CURRENT-STATE-AND-MIGRATION.md`, `implementation/IMPLEMENTATION-PLAN.md`, `implementation/QUALITY-GATES.md`, all chapter briefs, and `project/DECISIONS.md`. +Compare with existing `SITE_SPEC.md`, `DEMONSTRATOR_SPEC.md`, `AGENTS.md`, historical `MILESTONE_*.md`, and real code. + +Perform ONLY Stage 0 and a reviewable Stage 1 preparation unless the owner explicitly expands scope: +1. Produce an evidence-backed conflict/migration map referencing exact paths. +2. Reconcile instructions into root `AGENTS.md` preserving existing V0 constraints. +3. Adopt project and chapter specifications with explicit proposal status. +4. Prepare new IA/Home/Learn design scoped to existing functioning routes and components. +5. Record expected new files, redirect policy, and verification tasks. +6. If approved for implementation, work in small branch/PR increments with explicit acceptance checks. + +Do not replace or modify the V0 coverage formula, source IDs, canonical YAML or original test semantics. +Do not invent agent execution data, physical measurements, CI outcomes, screenshots, approvals or external deployment. +Do not merge, deploy, publish, or modify repository settings without user authorization. + +At completion report: actual modified paths, content migrations, resolved conflicts, executed checks and evidence, unavailable tests, open decisions, proposed next PR. diff --git a/site/src/data/v2-curriculum.ts b/site/src/data/v2-curriculum.ts new file mode 100644 index 0000000..c879a55 --- /dev/null +++ b/site/src/data/v2-curriculum.ts @@ -0,0 +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'] }, +] as const; diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro index df05786..bb9e6eb 100644 --- a/site/src/pages/index.astro +++ b/site/src/pages/index.astro @@ -1,24 +1,32 @@ --- import Layout from '../layouts/Layout.astro'; import { chapters } from '../data/chapters'; +import { v2Parts } from '../data/v2-curriculum'; const base = import.meta.env.BASE_URL; + --- - -

Executable Engineering Lab

-

From engineering intent to working systems.

-

An industrial area needs monitoring. What would count as enough coverage—and what would convince you that a proposed configuration provides it?

-

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 →

-

Follow the learning path

-
- {chapters.map((chapter, index) => )} + +

Executable Engineering Lab · A practical learning environment

+

Engineering at the Speed of AI.

+

Digital Engineering connects knowledge across disciplines. AI agents can accelerate exploration and implementation. The challenge is to use both without losing control of engineering decisions, architecture, or evidence.

+

Follow a fictional Distributed Monitoring System from uncertain intent toward progressively more informed engineering decisions. The planned curriculum will explore how software, electronics, mechanical design, integration and verification contribute at different speeds.

+

Our approach: specify what we know, explore what we don't, verify what we build, and preserve what we learn.

+

Explore the learning path → · Open the existing coverage lab

+

V2 curriculum in development. The published lessons and working lab below remain the current learning experience.

+

Four connected questions

+
+ {v2Parts.map(part =>

{part.title}

{part.message}

V2 direction: {part.chapters.join(' / ')}

)} +
+

Explore the published lessons

+

The original twelve lessons remain available while the new curriculum is developed. They focus on a deliberately limited single-sensor teaching model. The new multidisciplinary demonstrations and recorded agent workflows are planned, not yet implemented.

+
+ {chapters.map((chapter, index) => )}
-

Explore the interactive lab · Inspect engineering sources

-

These lessons use an idealized geometric area estimate. A passing result does not establish real-world detection performance or an optimal design.

-

Reproduce the calculation locally · Later learning increments

+

Inspect engineering sources · See the repository

+ diff --git a/site/src/pages/learn/index.astro b/site/src/pages/learn/index.astro index 1e56534..1d9d025 100644 --- a/site/src/pages/learn/index.astro +++ b/site/src/pages/learn/index.astro @@ -1,15 +1,27 @@ --- import Layout from '../../layouts/Layout.astro'; import { chapters } from '../../data/chapters'; +import { v2Parts } from '../../data/v2-curriculum'; const base = import.meta.env.BASE_URL; + --- -

Learn / DMS V0

-

Ask, define, experiment, interpret.

-

Use one fictional monitoring problem to connect engineering intent, structured definitions and qualified evidence.

-
    - {chapters.map(chapter =>
  1. {chapter.title}

    {chapter.summary}

  2. )} -
-

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

+

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.

+

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. )}
)}
+

Published lessons — original course

+

The original twelve lessons and URLs are preserved during migration. The V0 demonstrator remains intentionally limited to one ideal circular sensor.

+
    {chapters.map(chapter =>
  1. {chapter.title}

    {chapter.summary}

  2. )}
+

Open the existing lab →

- +