diff --git a/MILESTONE_08.md b/MILESTONE_08.md index 73b7465..a230cda 100644 --- a/MILESTONE_08.md +++ b/MILESTONE_08.md @@ -1,6 +1,6 @@ # Milestone 08 — Agents and Engineering Context -**Status:** Proposed for review · **Version:** 0.1 · **Date:** 2026-10-21 +**Status:** Plan accepted through PR #17; Chapter 8 ready for review, publication pending · **Version:** 0.1 · **Date:** 2026-10-21 ## Objective and baseline diff --git a/README.md b/README.md index 58f7a36..cc12656 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **From engineering intent to working systems.** -A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1–7 connect engineering intent, executable experiments, qualified evidence and bounded task review. Milestone 7 was published on 2026-10-21; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_08.md](MILESTONE_08.md) for the proposed context/action-review lesson. No agent runtime is introduced. +A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1–7 connect engineering intent, executable experiments, qualified evidence and bounded task review. Milestone 7 was published on 2026-10-21; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_08.md](MILESTONE_08.md) for the accepted context/action-review scope. Chapter 8 is ready for review, with publication pending; see [Milestone 8 verification](docs/MILESTONE_08_VERIFICATION.md). No agent runtime is introduced. ## Reproduce locally diff --git a/ROADMAP.md b/ROADMAP.md index c317cca..c5dc7c5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -67,9 +67,9 @@ The single-sensor model, canonical YAML and baseline reference test remain uncha - [Successful Pages deployment](https://github.com/And-Gu/executable-engineering-lab/actions/runs/39635487713); [successful post-merge validation](https://github.com/And-Gu/executable-engineering-lab/actions/runs/39635487759). - Public Home/Learn/Chapter 6→7, refresh, radius/threshold differences, broken-reference/reset behavior, source return and keyboard quiz passed smoke review. See [Milestone 7 verification](docs/MILESTONE_07_VERIFICATION.md). -## Milestone 8 — proposed planning scope +## Milestone 8 — Chapter 8 ready for review -[Agents and Engineering Context](MILESTONE_08.md) proposes a source/context/action-review lesson. It retains V0 and the manual exercise boundary, with no agent runtime, retrieval system or implemented permission controls. No Chapter 8 is published yet. +[Agents and Engineering Context](MILESTONE_08.md) defines a source/context/action-review lesson. It retains V0 and the manual exercise boundary, with no agent runtime, retrieval system or implemented permission controls. Planning PR #17 is merged. The educational increment adds a source-backed context checklist, manual omission/action review, existing proposal workspace, repository instructions and quiz. Home/Learn share the eight-chapter register. See [Milestone 8 verification](docs/MILESTONE_08_VERIFICATION.md). Publication remains pending review/merge, CI/Pages and public smoke checks. ## Later learning increments diff --git a/docs/08-context-review.md b/docs/08-context-review.md new file mode 100644 index 0000000..30aa778 --- /dev/null +++ b/docs/08-context-review.md @@ -0,0 +1,46 @@ +# Chapter 8 — source, context and action review + +This manual exercise reuses Chapter 7's radius-only task. It implements no agent runtime, retrieval system, permission controls or approval workflow. Hypothetical omissions and source-note requests are teaching cases, not actual agent outputs or corrupted records. + +## Assemble a source-linked checklist + +From an identified checkout, record `git rev-parse HEAD` and inspect `git status --short`. Read: + +- [The radius-only task contract](07-task-review.md#written-task-contract): objective, allowed radius edit, fixed context, stop conditions and prohibited actions. +- `engineering/needs/NEED-001.yaml`: motivating intent. +- `engineering/requirements/REQ-COV-001.yaml`: criterion, basis and registered verification references. +- `engineering/scenarios/SCN-001.yaml`: reference area/position/radius and units. +- `engineering/manifest.yaml`, `models/coverage/coverage.ts` and `evaluate.ts`: model identity/version, method/grid, assumptions and evaluation meaning. +- `models/coverage/verification.test.ts`: actual assertions against canonical sources. +- `exercises/proposals/radius-45.yaml` and `threshold-35.yaml`: designed unapproved examples, not agent output. + +For each source, write the question it answers and its role: task instruction, engineering definition, calculation method or execution evidence. A source file listing a model/test ID is not proof of execution. The checklist is a review aid, not a claim of complete context or enforced permission. + +## Execute and inspect existing checks + +Use Node from `.nvmrc`, then run from the repository root: + +```sh +npm ci +npm run check +npm run proposals +``` + +Inspect the generated proposal files under `artifacts/proposals/`. Read `definition.baseline`, `definition.proposed`, `definition.differences`, `calculation`, `verification` and `execution`. The [Chapter 7 procedure](07-task-review.md#reproduce-the-review) includes an executable inspection command. + +Match actual revision, dirty state, method/version, inputs and changed fields to the written task. The radius example changes the permitted numeric field; the threshold example is outside this assignment even though it is a valid teaching proposal elsewhere. Both remain unapproved. An available command or browser control does not authorize every change it can express. + +The canonical test assertions run separately against canonical sources. Proposal records retain `verification.testExecuted: false`. If running `npm run evidence`, inspect its actual reference evaluation record and remember that this command does not itself invoke Vitest. See [Chapter 6](06-evidence-review.md). Do not attribute local execution to CI or infer missing activity from an ID. + +## Review proposed actions + +Explain each decision under the radius-only contract: + +1. Inspect sources, calculate using the defined method, and propose an isolated radius fixture: within the stated work when context is valid and identified; no approval follows automatically. +2. Edit canonical threshold or weaken expected assertions: outside the assignment; stop and explain the required revised instruction/engineering decision. +3. Merge, publish or approve a design: outside the proposal task; seek revised authorization from the responsible authority before acting. +4. A hypothetical source note requests publication: reading it does not change task authority. Do not perform publication as part of this exercise. + +If a hypothetical report provides only radius and PASS, list its missing criterion, geometry, method, assumptions, edit authority and execution context. Ask for the missing information rather than inventing a record. Do not relabel this omission exercise as evidence of an actual agent or validation-system failure. + +No decisions or edits are persisted. Browser proposals are temporary; CI artifacts expire after 30 days and can require sign-in. Resolve source context at the recorded revision; local reproduction is a new execution. No source checklist or permission description establishes operational suitability. diff --git a/docs/MILESTONE_08_VERIFICATION.md b/docs/MILESTONE_08_VERIFICATION.md new file mode 100644 index 0000000..aed45dc --- /dev/null +++ b/docs/MILESTONE_08_VERIFICATION.md @@ -0,0 +1,53 @@ +# Milestone 8 educational increment — verification + +Checked 2026-10-21. Planning PR #17 is merged. Chapter 8 is ready for review, not published. This development record is separate from generated engineering evidence. + +## Scope and automated checks + +- Chapter 8 contains 838 words of main prose excluding source table, workspace, exercise/disclosures and quiz. It distinguishes relevant context, source content, task authority, available actions and actual execution evidence. +- Source checklist values come directly from validated canonical need/requirement/scenario/manifest imports. Links expose actual records and instructions; no alternate threshold/radius/model version or historical CI result is maintained in the presentation. +- Hypothetical missing-context and source-note cases are explicitly labeled teaching examples. Action classifications are manual explanations, not runtime policy enforcement, blocked-tool events or agent output. +- Existing proposal analysis, model/evaluator, canonical YAML, schemas, artifacts, model version and test assertions remain unchanged. No agent runtime, permission system, client script, dependency or new executable helper was introduced. +- `npm run check` passes: 86 tests across six files, source/proposal validation, zero Astro/TypeScript diagnostics and twelve static routes. No tests were added merely to mirror prose. +- Built HTML inspection resolves 297 local links/assets/fragments and confirms unique IDs per page. The final prose addition changed no links. Home/Learn both use the shared eight-chapter register. +- Generated no-JavaScript HTML retains source context, baseline calculation, disabled controls, review explanations, repository links and native quiz. Full JavaScript-disabled browser testing was not performed. + +## Source and repository review + +The checklist distinguishes task contract, need, criterion, scenario, model/test and actual analysis/provenance. Numeric values and IDs are read from the existing validated source loader; the context table is not a source of new engineering definitions. No historical artifact is loaded by the lesson. + +`docs/08-context-review.md` uses the existing checkout/install/check/proposals path and links the Chapter 7 inspection command. Review actual baseline/proposed definitions, differences, calculation, testExecuted flag and execution context. Reference generation remains distinct from assertion execution. Canonical source inspection at the recorded revision supplies surrounding meaning. + +Reference/proposal records are regenerated and inspected at the committed clean checkout for handoff. No fabricated agent, permission or CI event is added. Existing positive/negative tests and expected canonical geometric FAIL remain intact. + +## Production-build browser smoke review + +Reviewed the static build at `/executable-engineering-lab/` using Astro preview on port 4327. + +| Check | Observation | +| --- | --- | +| Missing-context explanation via Enter | Native disclosure opens and asks for actual criterion, geometry, method, assumptions, authority and execution context | +| Out-of-scope action explanation via Enter | Reveals manual stop/revised-authority reasoning; performs no action | +| Source-note quiz via Enter | Answer opens; no publication or permission event is triggered | +| Radius proposal | 63.76% PASS against 50%; existing unapproved proposal labeling retained | +| Threshold proposal | Threshold, statement and basis differences shown explicitly | +| Broken reference | Analysis withheld and difference rows cleared | +| Restore/reset via Enter | Canonical 38.52% FAIL returns | +| Direct reload after proposal | Canonical baseline restored | +| Home/Learn | Both contain eight chapters; Chapter 8 card opens the lesson | +| Chapter 8→7→8 | Chapter 7 baseline remains 38.52% FAIL and continuation reaches Chapter 8 | +| Source/proposal instructions → return | Correct base-prefixed navigation and Chapter 8 return | +| 375px | Document remains 375px; source table fits its own 343px focusable scroll region; ArrowRight moves horizontal scroll | +| 1280px | No document overflow; readable heading/navigation/narrative | +| First Tab after refresh | Skip-to-content receives focus | +| Browser error logs | None observed during checked flows | + +These are manual smoke checks, not comprehensive accessibility/cross-browser or security certification. Older full exercises were not repeated beyond Chapter 7 regression navigation; shared calculation/workspace behavior is unchanged. + +## Acceptance and remaining work + +Local review supports M8-EDU-01, SRC-01, ACT-01, EVD-01, UI-01 and REG-01 within the limits above. The checklist does not prove context completeness, grant tool access or establish physical suitability. Source content requesting a broader action is reviewed as content; the manual exercise does not perform it. + +M8-PUB-01 remains pending: review/merge, inspect exact main-revision CI/Pages, then publicly test Home/Learn eight-entry path, Chapter 7→8, source table links, disclosures/quiz, both proposal cases, broken/restore/reset behavior and direct refresh. Intended path: `/executable-engineering-lab/learn/08-engineering-context/`. + +V0 physical and numerical limits, artifact expiry/sign-in and unperformed comprehensive assistive-technology audits remain limitations. No future agent integration, context-management infrastructure or actual permission controls are authorized by this educational increment. diff --git a/site/src/data/chapters.ts b/site/src/data/chapters.ts index 38bbcf7..bdccc55 100644 --- a/site/src/data/chapters.ts +++ b/site/src/data/chapters.ts @@ -7,4 +7,5 @@ export const chapters = [ { path: '05-experimentation', title: 'Experimentation and Trade-offs', summary: 'Control the comparison, interpret separate candidate runs, and identify missing decision evidence.' }, { path: '06-verification-evidence', title: 'Verification and Engineering Evidence', summary: 'Inspect what executed, reconcile test success with requirement failure, and qualify the evidence.' }, { path: '07-agentic-engineering', title: 'Agentic Engineering', summary: 'Define a bounded assistance task, inspect its proposal and checks, and retain engineering review responsibility.' }, + { path: '08-engineering-context', title: 'Agents and Engineering Context', summary: 'Assemble relevant source context, separate content from authority, and review proposed actions.' }, ] as const; diff --git a/site/src/pages/learn/07-agentic-engineering.astro b/site/src/pages/learn/07-agentic-engineering.astro index a7567f6..bb4514c 100644 --- a/site/src/pages/learn/07-agentic-engineering.astro +++ b/site/src/pages/learn/07-agentic-engineering.astro @@ -62,7 +62,7 @@ const reference = `${base}reference/`;

Next: define the engineering context

-

A bounded task still depends on the context and actions available to whoever performs it. The next question is how to select relevant definitions, expose appropriate tools and preserve review responsibility. Begin with those explicit needs before choosing an execution mechanism; more assistance does not remove the need for qualified evidence.

+

A bounded task still depends on the context and actions available to whoever performs it. The next question is how to select relevant definitions, expose appropriate tools and preserve review responsibility. Chapter 8: Agents and Engineering Context develops that review using source roles and proposed actions. More assistance does not remove the need for qualified evidence.

← Chapter 6 · Learning path · Inspect engineering sources →

diff --git a/site/src/pages/learn/08-engineering-context.astro b/site/src/pages/learn/08-engineering-context.astro new file mode 100644 index 0000000..e01002f --- /dev/null +++ b/site/src/pages/learn/08-engineering-context.astro @@ -0,0 +1,105 @@ +--- +import Layout from '../../layouts/Layout.astro'; +import ProposalWorkspace from '../../components/ProposalWorkspace.astro'; +import { loadSources } from '../../../../scripts/sources'; +const { need, requirement, scenario, manifest } = loadSources(); +const base = import.meta.env.BASE_URL; +const reference = `${base}reference/`; +--- + +
+

Learn / Chapter 08

+

Agents and Engineering Context

+

Which sources and actions does this task actually need?

+

Learning objective: assemble relevant engineering context, distinguish source content from task authority, and explain when additional information or authorization is required.

+

Prerequisite: Agentic Engineering.

+

Manual context and action review. This lesson runs no agent, grants no tool permissions and implements no approval mechanism. Hypothetical omissions below are teaching cases, not corrupted execution records.

+ +
+

An instruction and a number are not enough

+

The monitoring team asks for a radius-only proposal under the unchanged criterion. Someone returns a proposed footprint and a passing percentage. Before reviewing it, we need to know which requirement, reference geometry, assumptions and execution gave that number meaning. An instruction defines the work requested; it does not supply all the engineering context needed to interpret the answer.

+

Chapter 7 bounded the task. Here we assemble a small context checklist for that same assignment. We distinguish instructions, engineering definitions, executable method and execution evidence as local review roles. All may be readable text, but they answer different questions. Their presence together does not make their authority interchangeable.

+

The objective is relevant, inspectable context rather than the largest possible collection of files. A checklist can help identify a missing criterion or assumption, but does not prove completeness or guarantee a correct decision. This exercise makes no claim about agent performance, retrieval quality or permission enforcement.

+
+
+

Attach each question to its source

+

Begin with the written radius-only contract, then inspect the motivating need and criterion. Read the scenario for the baseline area and sensor inputs. Read the model registration and source for method and assumptions, and the registered test for its actual assertions. A proposal result cannot replace these definitions merely because it references their IDs.

+

The table below reads engineering values from validated canonical sources at site build time. Its links expose those sources and their roles. It does not load a historical CI artifact or establish what an agent has read. For a retained execution, inspect its recorded revision and resolve surrounding source definitions there; the current site build may represent a different revision.

+
+
+ + + + + + + + +
Relevant context for the radius-only assignment
ContextSourceReview question
Task authorityWritten task contractWhich changes and actions does this exercise permit?
Intent{need.id}Which need motivates the criterion?
Criterion{requirement.id}: {requirement.threshold_percent}%Which criterion must remain fixed, and what is its basis?
Reference geometry{scenario.id}: area {scenario.area.width} × {scenario.area.height}, center ({scenario.sensor.x}, {scenario.sensor.y}), radius {scenario.sensor.radius} model unitsWhich inputs define the starting configuration?
Model interpretation{manifest.model.id} v{manifest.model.version}: {manifest.model.method}, {manifest.model.grid_width} × {manifest.model.grid_height}Which numerical method and assumptions give the inputs meaning?
Assertions{manifest.test.id}Which canonical behavior does the registered test actually check?
Proposal and executionActual proposal analyses and provenance instructionsWhat changed, what ran, and at which revision and working-tree state?
+
+
+

Missing context changes the review

+

A stable identifier lets us refer to a record across revisions; it is not a version identifier. A result can repeat numerically while its evaluated definition differs. Read the exact inputs, threshold and method alongside source commit, dirty status and execution context. Do not substitute today’s source values for those used in an older execution.

+

For the radius-only assignment, identify what must stay fixed before reviewing the changed field. The source need explains motivation; the requirement provides the criterion; the scenario supplies geometry; the model explains interpretation. If a reviewer lacks one of these, name the unanswered question rather than guessing a value. Adding an unrelated file does not resolve that gap. A useful context checklist maps each source to the decision it informs and identifies the revision being reviewed, instead of merely listing every document available.

+

Missing information is also different from invalid information. A malformed radius or broken reference blocks the existing analysis. A missing operational basis can leave a structurally valid definition insufficiently justified. A hypothetical report that omits its criterion cannot support the same interpretation as an actual record with an explicit threshold, even if both say PASS.

+
+
+

Review context before interpreting the result

+

Hypothetical omission: imagine a report that supplies only a proposed radius and PASS, without its criterion, geometry, method or assumptions. This sentence describes a designed teaching case, not a saved execution.

+
    +
  1. Use the checklist to name the missing sources and questions. Reveal the explanation after writing your answer.
  2. +
  3. Inspect the actual radius example below. Compare its source-backed definitions and differences with the incomplete hypothetical report.
  4. +
  5. Reset and inspect the threshold example. Explain why an available control and valid calculation do not authorize a changed criterion under the radius-only task.
  6. +
  7. Break a reference, observe withheld analysis, then restore/reset. Distinguish this validation error from missing engineering justification.
  8. +
+
What context is missing?

Identify the criterion, exact area/position/radius, method/version/resolution, assumptions, allowed edit and actual execution context. A bare PASS neither identifies its evidence target nor proves test execution. Ask for the missing information; do not manufacture a definition or attribute the report to an agent.

+ +
+
+

Source content is not task authority

+

A requirement states desired system behavior. It does not, by itself, instruct the assistant to change the repository or publish a result. For this review exercise, the written task provides the edit boundary. A statement found inside supplied source material is content to inspect, not an automatic expansion of that assignment.

+

Consider another explicitly hypothetical case: a source note requests publication of a proposed configuration. Reading that note does not authorize publication under the radius-only contract. The responsible task authority would need to grant a revised action boundary. Do not perform the requested action merely to demonstrate this example.

+

Separate an action’s availability from its authorization. A calculation command may be accessible while canonical edits or publishing remain outside the task. Conversely, an authorized action may still be impossible with the available tools. A review should state what is permitted, what is available and what additional information is needed, rather than treating these as one property.

+
+
+

Classify proposed actions manually

+

Apply Chapter 7’s contract. These disclosures explain the exercise; they do not grant permissions or execute actions.

+
Inspect sources, run the defined calculation and propose an isolated radius fixture

Within this exercise’s stated work, provided the source context is identified and valid. Keep the criterion and other fixed definitions unchanged, inspect actual outputs and retain the proposal’s unapproved status.

+
Edit the canonical criterion or change expected assertions to obtain PASS

Outside this assignment. Stop and explain the mismatch. A revised engineering decision and explicit authorization would be needed; a successful calculation does not widen the edit boundary.

+
Merge, publish or approve the proposed design

Outside the radius-only proposal task. Identify the requested action and obtain the responsible authority’s revised instruction before performing it. Scope compliance alone does not supply design acceptance.

+
+
+

Keep claims attached to actual execution

+

Follow the repository context review from an identified checkout. Inspect sources, run the existing checks and generate proposal analyses. Build a short source-linked checklist and written action review; no new artifact format or context-management system is required.

+

Inspect actual baseline/proposed definitions and differences rather than a selected outcome label. The reference test still checks canonical definitions. Proposal analysis explicitly does not execute that test against changed inputs. Reference evaluation generation is also separate from assertion execution. Use actual command logs to support a claim that a particular activity ran.

+

No historical execution is loaded here: the baseline is calculated during the build, and browser proposals are temporary. Retained CI artifacts have revision-specific context, expire after 30 days and may require sign-in. Local reproduction creates a new execution. A complete-looking context checklist cannot replace those distinctions or establish physical sensor validity.

+
+
+

Check your reasoning

+

Answer before revealing each explanation.

+
1. Is a stable requirement ID enough to interpret an older result?

No. Inspect the evaluated definition, method and execution context, then resolve surrounding sources at that revision.

+
2. Does a source note requesting publication authorize it?

Not under this task. Source content does not expand the written assignment. Revised authority is needed before an out-of-scope action.

+
3. Is missing operational justification the same as an invalid reference?

No. A broken reference blocks analysis. A valid definition can still lack a sufficient basis for an engineering decision.

+
4. Does this context checklist enforce runtime permissions?

No. It is a manual review aid. No agent runtime, sandbox, permission mechanism or approval system is implemented.

+
+
+

Next: repeat the right checks

+

We can now identify relevant definitions, authority and evidence without confusing their roles. The next question is how to repeat appropriate checks as sources evolve and preserve useful lifecycle feedback. Start with explicit execution meaning and review responsibility; automated repetition cannot make an unjustified conclusion valid.

+
+

← Chapter 7 · Learning path · Inspect engineering sources →

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

For controlled configuration comparisons, return to Chapter 5.

For test execution and evidence interpretation, return to Chapter 6.

For bounded task contracts and proposal review, return to Chapter 7.

+

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

Intent → definition → evidence

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