From bdbcbe17b15d045102a51f888f4f9a639e2f3e49 Mon Sep 17 00:00:00 2001 From: Anders Gustafsson Date: Wed, 21 Oct 2026 15:00:51 +0200 Subject: [PATCH] Complete Chapter 7 bounded task and proposal review lesson --- MILESTONE_07.md | 2 +- README.md | 2 +- ROADMAP.md | 4 +- docs/07-task-review.md | 59 ++++++++++++++ docs/MILESTONE_07_VERIFICATION.md | 51 ++++++++++++ site/src/data/chapters.ts | 1 + .../learn/06-verification-evidence.astro | 2 +- .../pages/learn/07-agentic-engineering.astro | 79 +++++++++++++++++++ site/src/pages/reference.astro | 1 + 9 files changed, 196 insertions(+), 5 deletions(-) create mode 100644 docs/07-task-review.md create mode 100644 docs/MILESTONE_07_VERIFICATION.md create mode 100644 site/src/pages/learn/07-agentic-engineering.astro diff --git a/MILESTONE_07.md b/MILESTONE_07.md index 4785902..8cc1681 100644 --- a/MILESTONE_07.md +++ b/MILESTONE_07.md @@ -1,6 +1,6 @@ # Milestone 07 — Agentic Engineering -**Status:** Proposed for review · **Version:** 0.1 · **Date:** 2026-10-21 +**Status:** Plan accepted through PR #15; Chapter 7 ready for review, publication pending · **Version:** 0.1 · **Date:** 2026-10-21 ## Objective and baseline diff --git a/README.md b/README.md index ea6ca80..a9ecb89 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–6 connect engineering intent, structured definitions, executable experiments and qualified evidence. Milestone 6 and synchronized homepage chapter cards were published on 2026-10-21. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_07.md](MILESTONE_07.md) for the proposed lesson on bounded engineering-assistance tasks and review; no agent runtime is proposed. +A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1–6 connect engineering intent, structured definitions, executable experiments and qualified evidence. Milestone 6 and synchronized homepage chapter cards were published on 2026-10-21. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_07.md](MILESTONE_07.md) for the accepted bounded-task/review scope. Chapter 7 is ready for review, with publication pending; see [Milestone 7 verification](docs/MILESTONE_07_VERIFICATION.md). No agent runtime is introduced. ## Reproduce locally diff --git a/ROADMAP.md b/ROADMAP.md index 152e9ea..68474bd 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -58,9 +58,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/39598903854); [successful post-merge validation](https://github.com/And-Gu/executable-engineering-lab/actions/runs/39598904031). - Public six-card Home/Learn, Chapter 5→6, refresh, radius/reset/broken-reference behavior, artifact/source return and keyboard quiz passed smoke checks. See [Milestone 6 verification](docs/MILESTONE_06_VERIFICATION.md). -## Milestone 7 — proposed planning scope +## Milestone 7 — Chapter 7 ready for review -[Agentic Engineering](MILESTONE_07.md) proposes a bounded task-contract and manual proposal-review lesson using existing fixtures and executable checks. It introduces no agent runtime, API, autonomous permissions or V3 capability. No Chapter 7 is published yet. +[Agentic Engineering](MILESTONE_07.md) defines a bounded task-contract and manual proposal-review lesson using existing fixtures and executable checks. It introduces no agent runtime, API, autonomous permissions or V3 capability. Planning PR #15 is merged. The educational increment adds the lesson, written contract, manual proposal review, repository procedure and quiz; Home and Learn use the shared seven-chapter register. See [Milestone 7 verification](docs/MILESTONE_07_VERIFICATION.md). Publication remains pending review/merge, deployment and public smoke checks. ## Later learning increments diff --git a/docs/07-task-review.md b/docs/07-task-review.md new file mode 100644 index 0000000..8ce843e --- /dev/null +++ b/docs/07-task-review.md @@ -0,0 +1,59 @@ +# Chapter 7 — bounded task contract and proposal review + +This is a manual review exercise using designed fixtures. No actual AI agent, provider API, tool sandbox or permission enforcement is implemented. The examples must not be attributed to an agent run. + +## Written task contract + +| Part | Assignment | +| --- | --- | +| Objective | Propose one single-sensor radius change for evaluation against the unchanged geometric criterion; report limitations | +| Baseline/context | Identify checkout/revision; inspect canonical need, requirement, scenario, model assumptions and registered test | +| Allowed edit | One finite nonnegative radius in an isolated unapproved proposal fixture; browser controls retain their existing 0–200 model-unit range | +| Fixed definitions | Area, sensor center, threshold, requirement wording/basis, references, method, grid and model version | +| Prohibited actions | Edit canonical YAML, relax criterion, change test expectations/model code, merge/publish or approve a requirement/design | +| Checks | Validate sources/proposals, inspect exact differences, run shared analysis, separately run canonical regressions | +| Stop conditions | Missing/contradictory context, invalid references, out-of-scope requested changes, or insufficient evidence for the intended claim | +| Deliverable | Exact proposed input, rationale, scoped diff, actual commands/results and provenance where recorded, limits and reviewer question/decision | + +This document expresses a task boundary; it does not enforce access controls. Geometric PASS does not grant authority to widen the assignment or approve a design. + +## Reproduce the review + +Use an identified checkout and Node from `.nvmrc`. Run: + +```sh +git rev-parse HEAD +git status --short +npm ci +npm run check +npm run proposals +``` + +Inspect the actual fixture sources in `exercises/proposals/`. The radius-45 proposal changes `scenario.sensor.radius` in the derived definition. The threshold-35 proposal changes threshold, statement and unapproved threshold basis. Neither fixture edits canonical YAML; both are unapproved teaching proposals. + +Print the generated analyses from this checkout: + +```sh +node --input-type=module <<'JS' +import { readFileSync } from 'node:fs'; +for (const name of ['PROPOSAL-RADIUS-45', 'PROPOSAL-THRESHOLD-35']) { + const record = JSON.parse(readFileSync(`artifacts/proposals/${name}.json`, 'utf8')); + console.log(JSON.stringify({ id: record.id, kind: record.kind, + differences: record.definition.differences, calculation: record.calculation, + verification: record.verification, execution: record.execution }, null, 2)); +} +JS +``` + +Also read `definition.baseline` and `definition.proposed` in each JSON file to inspect the exact sources and inputs, not only the outcome label. These are actual local analyses, not stored agent responses. Their source revision, dirty status, timestamp and context must describe the actual checkout. Do not infer a clean state or CI execution from the printed number alone. + +Apply the same contract to both cases: + +1. Does each changed field fit the permitted edit? Why is a changed criterion outside this task even though Chapter 2 legitimately explores it? +2. Which activity actually ran? `npm run check` executes the canonical regression suite; proposal analysis does not execute TEST-COV-001 against proposals. Inspect `verification.testExecuted` and actual logs. +3. What does the geometric calculation establish, and what physical/operational justification is missing? +4. Should the reviewer reject the edit, request more evidence or accept only that it fits the permitted scope? Do not turn that last observation into design approval. + +Keep canonical assertions unchanged. `npm run evidence` is a separate reference evaluation generator and does not itself invoke Vitest; see [Chapter 6's evidence review](06-evidence-review.md). Existing CI artifacts expire after 30 days and may require sign-in. Browser results are temporary copies, not retained CI evidence. + +There is no generic scope classifier or approval engine in this exercise. The reviewer explains the decision. A broken source reference must be corrected before analysis; a valid but out-of-scope threshold change must be rejected for this assignment rather than hidden behind PASS. diff --git a/docs/MILESTONE_07_VERIFICATION.md b/docs/MILESTONE_07_VERIFICATION.md new file mode 100644 index 0000000..a155402 --- /dev/null +++ b/docs/MILESTONE_07_VERIFICATION.md @@ -0,0 +1,51 @@ +# Milestone 7 educational increment — verification + +Checked 2026-10-21. Planning PR #15 is merged. Chapter 7 is ready for review, not published. This development record is separate from generated engineering evidence. + +## Scope and automated checks + +- Chapter 7 contains 806 words of main prose excluding the status callout, workspace, exercise and quiz. It introduces a local pedagogical task contract, separates proposal/check/review, contrasts the same radius/threshold cases under fixed scope, and explains absent enforcement and missing engineering justification. +- The manual exercise is explicitly labeled: no actual agent runs, provider/API calls, permission enforcement, mock transcripts or attributed agent outputs. Existing fixtures are designed teaching examples. +- Shared ProposalWorkspace, analysis/model/evaluator, canonical YAML, schemas, artifact formats, model version and reference assertions are unchanged. No client script, dependency or new executable helper was needed. +- `npm run check` passes: 86 tests across six files, source/proposal validation, zero Astro/TypeScript diagnostics and eleven static routes. No test was added to mirror prose. +- Built HTML inspection resolves 267 local links/assets/fragments under the Pages base path and confirms unique IDs per page. +- Generated no-JavaScript HTML retains canonical baseline, disabled proposal controls, task narrative, written-contract/repository links and native quiz. Full JavaScript-disabled browser testing was not performed. +- Chapter registration uses the shared `site/src/data/chapters.ts`; no separate Home list was introduced. + +## Repository exercise + +Executed the exact Node inspection snippet from `docs/07-task-review.md` against newly generated proposal files. The radius proposal's `definition.differences` contains only `scenario.sensor.radius`. The threshold proposal contains threshold, statement and threshold-basis differences. Both calculate PASS under their respective definitions; both retain `verification.testExecuted: false`. + +The written fixed-criterion contract permits the radius edit and excludes criterion relaxation. This is a manual review conclusion, not an automated classifier or approval decision. Both records remain unapproved, and neither establishes physical suitability. The instructions also require inspecting exact baseline/proposed definitions and actual source revision/dirty state, rather than treating a summary or proposer claim as evidence. + +Reference evidence and proposal records are regenerated and inspected from the committed checkout for handoff. Canonical TEST-COV-001 remains independently tested against its expected geometric FAIL. No unexecuted assertion run or agent provenance is claimed. + +## Production-build browser smoke review + +Reviewed the static build at `/executable-engineering-lab/` using Astro preview on port 4327. + +| Check | Observation | +| --- | --- | +| Radius example | 63.76% PASS against 50%, only scenario.sensor.radius differs | +| Threshold example | 38.52% PASS against 35%, threshold/statement/basis differ visibly | +| Broken source reference | Result withheld and difference rows cleared | +| Restore/reset via Enter | Valid analysis recovers; canonical 38.52% FAIL returns | +| Review explanation and permission-boundary quiz via Enter | Native disclosures reveal explanations | +| Direct chapter reload after trial | Canonical baseline restored | +| Home and Learn | Both contain seven entries; Chapter 7 opens from its Home card | +| Chapter 7→6→7 | Chapter 6 baseline still gives 38.52% FAIL and continuation returns to new lesson | +| Reference/source return | Base-prefixed links and return to Chapter 7 work | +| 375px | No document overflow; instructions wrap; Home shows seven cards without overflow | +| 1280px | No document overflow and readable chapter layout | +| First Tab after chapter refresh | Skip-to-content receives focus | +| Browser errors | None observed in checked flows | + +These are manual smoke checks, not comprehensive accessibility/cross-browser certification. Older full exercises were not repeated beyond Chapter 6 regression navigation; shared code and model behavior remain unchanged. + +## Acceptance and release work + +Local review supports M7-EDU-01, SCP-01, EVD-01, STOP-01, UI-01 and REG-01 within the limits above. Stop/reject decisions are reasoning tasks; the workspace deliberately permits valid out-of-scope teaching cases. A readable contract does not enforce runtime permissions, and an in-scope edit is not design acceptance. + +M7-PUB-01 remains pending: review/merge, inspect exact main-revision CI/Pages, then publicly test Home/Learn seven-entry path, Chapter 6→7, refresh, both proposal diffs, broken/restore/reset behavior, reference return and quiz. Intended path: `/executable-engineering-lab/learn/07-agentic-engineering/`. + +No real agent integration, V3 capability, autonomous editing or physical validation is delivered. V0 modeling limits, artifact expiry/sign-in and unperformed comprehensive assistive-technology audits remain limitations. This educational increment does not authorize a later runtime integration implicitly. diff --git a/site/src/data/chapters.ts b/site/src/data/chapters.ts index 71c43ab..38bbcf7 100644 --- a/site/src/data/chapters.ts +++ b/site/src/data/chapters.ts @@ -6,4 +6,5 @@ export const chapters = [ { path: '04-executable-models', title: 'Executable Engineering Models', summary: 'Inspect the discrete calculation, separate evaluation from geometry, and reproduce its output.' }, { 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.' }, ] as const; diff --git a/site/src/pages/learn/06-verification-evidence.astro b/site/src/pages/learn/06-verification-evidence.astro index da22966..2cac9af 100644 --- a/site/src/pages/learn/06-verification-evidence.astro +++ b/site/src/pages/learn/06-verification-evidence.astro @@ -61,7 +61,7 @@ const reference = `${base}reference/`;

Next: bound the assistance

-

These distinctions also constrain future engineering assistance. A tool may help inspect sources, propose a change or repeat a calculation, but its output must retain the activity’s actual meaning. Before delegating work, define the allowed changes, independent checks and review responsibility. More automation does not create engineering authority.

+

These distinctions also constrain future engineering assistance. A tool may help inspect sources, propose a change or repeat a calculation, but its output must retain the activity’s actual meaning. Before delegating work, define the allowed changes, independent checks and review responsibility. Chapter 7: Agentic Engineering explores that boundary through a manual task-contract and proposal-review exercise.

← Chapter 5 · Learning path · Inspect engineering sources →

diff --git a/site/src/pages/learn/07-agentic-engineering.astro b/site/src/pages/learn/07-agentic-engineering.astro new file mode 100644 index 0000000..a7567f6 --- /dev/null +++ b/site/src/pages/learn/07-agentic-engineering.astro @@ -0,0 +1,79 @@ +--- +import Layout from '../../layouts/Layout.astro'; +import ProposalWorkspace from '../../components/ProposalWorkspace.astro'; +const base = import.meta.env.BASE_URL; +const reference = `${base}reference/`; +--- + +
+

Learn / Chapter 07

+

Agentic Engineering

+

What may an assistant change, and what must an engineer still verify?

+

Learning objective: define a bounded assistance task, inspect its proposal against that scope, and retain responsibility for interpreting evidence.

+

Prerequisite: Verification and Engineering Evidence.

+

This is a manual task-contract and review exercise. It runs the existing engineering calculation, not an AI agent. The proposal fixtures are designed teaching examples, not outputs attributed to a real agent run.

+ +
+

Delegate a bounded question

+

The monitoring team has a failing geometric configuration and wants help proposing a change. “Make it pass” leaves too much unstated. It could invite a larger assumed footprint, a relaxed criterion or altered assertions. Each might produce a reassuring label while answering a different question. Define the permitted work before asking for a proposal.

+

In this lesson, agentic engineering is a working label for examining assistance that may propose changes and carry out authorized steps toward an engineering objective. We use a manual exercise to study those boundaries. We make no claim that a particular agent architecture is required, that an agent has executed these examples, or that delegation transfers engineering authority.

+

Separate three activities: proposing a change, executing checks and deciding what to accept. A proposer can describe its reasoning, but that description is not execution evidence. A reviewer needs the exact changed definition and actual outputs from the specified checks. Even a correctly calculated result remains limited by the model and requirement basis.

+
+
+

Write the task contract first

+

For this exercise, the objective is to propose one sensor-radius change against the unchanged geometric criterion. Identify the source revision and inspect the need, requirement, scenario, model assumptions and registered test. Missing or contradictory context is a reason to stop and ask for clarification, not permission to invent a requirement.

+

The allowed edit is one finite nonnegative radius in an isolated, unapproved proposal. Keep the area, center, threshold, requirement wording, source relationships, grid and model version fixed. The existing browser range is a usability boundary for this exercise. It does not establish a physical sensor capability or authorize edits to canonical YAML.

+

Specify prohibited actions as well as the deliverable. This assignment excludes changing the criterion, weakening assertions, editing model code, merging, publishing and approving a requirement. Require the exact proposed input, rationale, scoped differences, actual commands and results, execution context where recorded, and unresolved limitations. A useful output may include a question for the reviewer rather than a recommendation.

+

The written task contract makes those expectations inspectable. It is an instruction and review aid, not enforced permission control. Describing a prohibition does not prevent a tool from violating it. This lesson implements neither sandboxing nor runtime authorization; the reviewer must not confuse a readable contract with a security boundary.

+
+
+

Review the proposal, not just PASS

+

Apply the fixed-criterion contract above. The workspace intentionally permits both teaching cases; it does not enforce that contract.

+
    +
  1. Reset proposal. Predict which field the assignment allows to change.
  2. +
  3. Try the radius example. Inspect the exact differences and validated definition. Does it fit the edit scope? What remains unjustified?
  4. +
  5. Reset, then try the threshold example. Inspect the criterion, statement and basis changes. Explain why a passing outcome cannot authorize them for this task.
  6. +
  7. Break a source reference. Observe withheld analysis, name the stop condition, then restore/reset.
  8. +
  9. Write a brief review distinguishing edit scope, calculated outcome and missing evidence. Compare your reasons with the explanation below.
  10. +
+ +
Compare your review

The radius proposal fits the permitted numeric edit, but its result is still an unapproved geometric analysis without physical-range justification. The threshold proposal is outside this task’s fixed-criterion scope, even if it calculates PASS. It remains a valid teaching proposal in Chapter 2’s different context. A broken reference blocks analysis and needs correction. None of these observations constitutes approval or an actual agent run.

+
+
+

Scope and evidence answer different questions

+

The radius example can fit the task’s edit scope without becoming an accepted design. Its assumed footprint still needs physical justification, and the teaching threshold still needs an operational basis. Scope compliance asks whether the proposal changed only what was permitted. Engineering acceptance asks whether the resulting definition and evidence support the intended decision.

+

The threshold example is useful precisely because its outcome can look attractive. The model is allowed to evaluate that separate proposal, and Chapter 2 uses it to explain changed criteria. Here the same proposal violates the assignment. Valid structure and a passing calculation cannot silently expand the authority granted to the proposer.

+

A review can therefore conclude that an edit is within scope while evidence is insufficient for acceptance. It can also reject an out-of-scope change without disputing its numerical calculation. State these reasons explicitly rather than collapsing them into one approval score. The browser stores no review decision and offers no approval action.

+
+
+

Execute checks independently of the narrative

+

Use the repository review procedure from an identified checkout. Run validation, the canonical regression suite and the existing proposal analyses. Inspect their exact definitions, differences and numerical outputs. Do not substitute a proposer’s statement that tests passed for the command output showing which checks actually ran.

+

Independent checking here means executing and inspecting the defined checks rather than trusting that narrative. The same deterministic coverage model remains deliberately shared across browser and repository. This is not an alternative numerical implementation or independent physical validation. Known-geometry tests and explicit assumptions retain their separate roles.

+

Preserve the canonical reference assertions and their expected geometric FAIL. A passing radius proposal does not execute those assertions against changed inputs. Proposal records explicitly retain that distinction. If reference evidence is generated, remember Chapter 6: its generator calculates and evaluates canonical inputs but does not itself invoke Vitest.

+

Review the actual source commit, dirty status, timestamp and execution context where recorded. Browser trials remain temporary and unapproved; local output must not be relabeled CI evidence. CI artifacts expire after 30 days and can require sign-in. Inspect sources at the recorded revision, because stable identifiers alone do not establish which definitions were evaluated.

+
+
+

Check your reasoning

+

Answer before revealing each explanation.

+
1. Does “make it pass” define an adequate task boundary?

No. Specify the objective, fixed context, allowed edit, prohibited actions, checks, stop conditions and deliverable.

+
2. Can the threshold proposal be valid but outside this task?

Yes. It is a valid teaching case in another context, but this assignment requires the criterion to remain fixed. Numerical PASS does not extend authorization.

+
3. Does the written contract enforce tool permissions?

No. It supports instruction and review. This exercise implements no runtime permission enforcement or agent execution.

+
4. Does an in-scope radius proposal deserve immediate acceptance?

No. Inspect the actual checks and provenance, then identify missing operational and physical justification. Scope compliance and engineering acceptance are different judgments.

+
+
+

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.

+
+

← Chapter 6 · Learning path · Inspect engineering sources →

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

For numerical method and reproduction, return to Chapter 4.

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.

Intent → definition → evidence

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