diff --git a/MILESTONE_10.md b/MILESTONE_10.md index 0ba819d..611e64d 100644 --- a/MILESTONE_10.md +++ b/MILESTONE_10.md @@ -1,6 +1,6 @@ # Milestone 10 — Governance and Assurance -**Status:** Proposed educational scope · **Version:** 0.1 · **Date:** 2026-10-23 +**Status:** Plan accepted through PR #21; Chapter 10 ready for review, publication pending · **Version:** 0.1 · **Date:** 2026-10-23 ## Objective and baseline diff --git a/README.md b/README.md index 83d8808..f1a32ba 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–9 connect engineering intent, executable experiments, qualified evidence and accountable review with continuous feedback. Milestone 9 was published on 2026-10-23; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_10.md](MILESTONE_10.md) for the proposed governance and assurance lesson. No agent runtime or governance integration is introduced. +A practical learning site built around a fictional Distributed Monitoring System (DMS). Chapters 1–9 connect engineering intent, executable experiments, qualified evidence and accountable review with continuous feedback. Milestone 9 was published on 2026-10-23; Home and Learn share the completed-chapter register. See [ROADMAP.md](ROADMAP.md) for release evidence and [MILESTONE_10.md](MILESTONE_10.md) for the accepted governance and assurance scope. Chapter 10 is ready for review, with publication pending; see [Milestone 10 verification](docs/MILESTONE_10_VERIFICATION.md). No agent runtime or governance integration is introduced. ## Reproduce locally diff --git a/ROADMAP.md b/ROADMAP.md index 9049216..55154df 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -85,9 +85,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/39906474919); [successful post-merge validation](https://github.com/And-Gu/executable-engineering-lab/actions/runs/39906475089). - Public nine-entry Home/Learn, Chapter 8→9, source return, direct refresh, proposals, invalid-reference/restore/reset and keyboard review/quiz checks passed smoke review. See [Milestone 9 verification](docs/MILESTONE_09_VERIFICATION.md) for observations and limits. -## Milestone 10 — proposed +## Milestone 10 — Chapter 10 ready for review -[Governance and Assurance](MILESTONE_10.md) proposes a manual claim/control/evidence review using existing sources and checks. It introduces no governance integration, compliance engine or operational approval. +[Governance and Assurance](MILESTONE_10.md) adds a manual claim/control/evidence review using existing sources and checks. Planning PR #21 is merged. The educational increment includes the chapter, source-linked expectations table, gap cases, existing proposal workspace, repository review template and shared tenth Home/Learn entry. It introduces no governance integration, compliance engine or operational approval. See [Milestone 10 verification](docs/MILESTONE_10_VERIFICATION.md). Publication remains pending review/merge and exact-revision CI/Pages/public checks. ## Later learning increments diff --git a/docs/10-assurance-review.md b/docs/10-assurance-review.md new file mode 100644 index 0000000..2b4277b --- /dev/null +++ b/docs/10-assurance-review.md @@ -0,0 +1,49 @@ +# Review a bounded assurance claim + +This manual exercise uses existing V0 definitions and isolated proposals. It records no approval and requires no canonical edits, push or publication. + +At an identified checkout: + +```sh +git rev-parse HEAD +git status --short +npm ci +npm run check +npm run evidence +npm run proposals +``` + +Record which commands actually completed. If the environment blocks the tsx CLI's IPC setup, execute the same scripts with `node --import tsx scripts/validate.ts`, `node --import tsx scripts/evidence.ts` and `node --import tsx scripts/proposals.ts`; record the substitution. A direct Astro build still needs separate validation, type checks and tests. + +Inspect canonical YAML, model assumptions, registered assertions and the [radius-only contract](07-task-review.md#written-task-contract). Compare actual outputs: + +```sh +node --input-type=module <<'JS' +import { readFileSync } from 'node:fs'; +for (const path of ['artifacts/reference-evidence.json', + 'artifacts/proposals/PROPOSAL-RADIUS-45.json', + 'artifacts/proposals/PROPOSAL-THRESHOLD-35.json']) { + const record = JSON.parse(readFileSync(path, 'utf8')); + console.log({ path, definition: record.definition, calculation: record.calculation, + verification: record.verification, execution: record.execution }); +} +JS +``` + +Reference generation is not assertion execution. Proposal records explicitly set testExecuted false; the reference test did not verify changed inputs. Separate command logs establish actual test execution. Current source links must not silently replace definitions from an older execution. + +For historical evidence, choose an actual [validation run](https://github.com/And-Gu/executable-engineering-lab/actions/workflows/validate.yml), inspect its checkout revision and completed steps, then inspect available artifacts. Retention is 30 days and sign-in may be required. Record unavailable evidence explicitly. Local reproduction is a new event. + +## Written review template + +- Narrow claim and task boundary: +- Canonical sources, evaluated definitions, source commit and working-tree state: +- Actual commands/logs and records inspected: +- Observation supporting the claim, with method and assumptions: +- Reasoning connecting observation to claim: +- Counterarguments, missing evidence and limits: +- Responsible next review role and unresolved decision: + +Compare a radius proposal with a threshold proposal. A correct calculation and valid definition do not authorize changing the criterion or establish operational suitability. The expected canonical geometric FAIL remains useful evidence, not a software test failure to hide. + +The template is a teaching aid separate from generated engineering evidence. It is not a policy schema, approval record, conformity assessment or implemented governance control. diff --git a/docs/MILESTONE_10_VERIFICATION.md b/docs/MILESTONE_10_VERIFICATION.md new file mode 100644 index 0000000..c3d2725 --- /dev/null +++ b/docs/MILESTONE_10_VERIFICATION.md @@ -0,0 +1,43 @@ +# Milestone 10 educational increment — verification + +Checked 2026-10-23. Planning PR #21 is merged. Chapter 10 is ready for review, not published. This development record is separate from generated engineering evidence. + +## Scope and source review + +- Main narrative: 827 words excluding headings, source table, exercise/workspace and quiz. Claim, reasoning, control and responsibility are explicitly local teaching terms, without standards-conformance claims. +- Source-linked table distinguishes expectations, actual mechanisms, observations needed and remaining responsibility. Criterion and source IDs use validated canonical imports. Roles are illustrative review responsibilities, not appointed people or recorded approvals. +- Gemara is omitted as an editorial choice: the engineering learning objective is better served by inspecting existing checks and their limits before introducing another representation. No claims about Gemara or standards are made, and no governance integration or V4 capability is introduced. +- Existing shared workspace, model/evaluator, schemas, assertions, workflows, dependencies and canonical YAML remain unchanged. Hypothetical evidence-gap cases are labeled; no historical event, approval or enforcement result is fabricated. + +## Automated checks + +- `npm run check` passes: 86 tests across six files, zero Astro/TypeScript errors/warnings/hints, engineering/proposal validation and fourteen static routes. +- `npm run evidence` retains canonical 38.52% geometric FAIL. `npm run proposals` produces unapproved radius 63.76%/50% PASS and threshold 38.52%/35% PASS. Assertion execution is distinct from record generation; proposal records do not claim reference-test execution against changed inputs. +- Built HTML inspection resolves 352 local links/assets/fragments and unique IDs per page. Static fallback retains source context, baseline, disabled pre-initialization controls and native disclosures. Full JavaScript-disabled browser testing was not performed. +- No tests were added merely to mirror narrative. Final prose-only addition was followed by the same complete check/build and link review. + +## Static-preview browser review + +Reviewed at port 4327 under `/executable-engineering-lab/`. + +| Check | Observation | +| --- | --- | +| Home/Learn | Ten cards/entries; Chapter 10 links open correctly | +| Chapter 10→9→10 | Back and continuation reach correct lessons | +| Source view and return | Base-prefixed reference and Chapter 10 return resolve | +| Radius and threshold via Enter | Distinct shared-calculation outcomes shown | +| Broken reference | Analysis withheld; previous result removed | +| Restore/reset and refresh | Canonical 38.52% FAIL restored | +| Expired-artifact case and missing-behavior quiz via Enter | Native disclosures open and distinguish unavailable evidence from a measured failure | +| 375px | Document width 375px; table in its own 343px region, 641px content; keyboard ArrowRight scrolls it | +| 1280px | No document overflow | +| First Tab after reload | Skip-to-content receives focus | +| Browser errors | None observed during checked flows | + +Final narrative count and preview screenshot were checked after rebuild. Screenshot: workspace outputs/chapter-10-preview.png. Manual smoke checks do not constitute comprehensive accessibility, cross-browser or security certification; older full exercises were not repeated. + +## Evidence and release limits + +Inspect generated records at the clean committed checkout for actual revision and dirty-state provenance. The written repository review is an aid separate from generated engineering evidence, not an approval artifact. This lesson loads no historical CI record. Artifact expiry/sign-in and V0 physical/numerical limitations remain. + +Local observations support M10-EDU-01, CTL-01, EVD-01, SRC-01 (documented omission), UI-01 and REG-01 within these limits. M10-PUB-01 remains pending review/merge, successful exact main-revision validation/Pages and public Home/Learn/Chapter 9→10/source return/exercise/refresh checks. No operational acceptance or production-system assurance is claimed. diff --git a/site/src/data/chapters.ts b/site/src/data/chapters.ts index b31e0fd..75b2cd2 100644 --- a/site/src/data/chapters.ts +++ b/site/src/data/chapters.ts @@ -9,4 +9,5 @@ export const chapters = [ { 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.' }, { path: '09-continuous-engineering', title: 'Continuous Engineering', summary: 'Follow revision-bound checks, interpret automated feedback, and identify the engineering decisions still open.' }, + { path: '10-governance-assurance', title: 'Governance and Assurance', summary: 'Connect bounded claims to actual checks and evidence, identify gaps, and retain accountable review decisions.' }, ] as const; diff --git a/site/src/pages/learn/09-continuous-engineering.astro b/site/src/pages/learn/09-continuous-engineering.astro index 02f05a3..60e684b 100644 --- a/site/src/pages/learn/09-continuous-engineering.astro +++ b/site/src/pages/learn/09-continuous-engineering.astro @@ -69,7 +69,7 @@ const repo = 'https://github.com/And-Gu/executable-engineering-lab';

Next: make assurance responsibilities explicit

-

The feedback loop now exposes what changed, what ran and what remains unresolved. The next question is which decisions, controls and evidence an assurance argument requires. Automated repetition supports that argument only when its scope and limitations remain explicit; no governance system is implemented by this lesson.

+

The feedback loop now exposes what changed, what ran and what remains unresolved. Continue with Chapter 10: Governance and Assurance to examine which decisions, controls and evidence an assurance argument requires. Automated repetition supports that argument only when its scope and limitations remain explicit; no governance system is implemented by this lesson.

← Chapter 8 · Learning path · Inspect engineering sources →

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

Learn / Chapter 10

+

Governance and Assurance

+

Which claim does this evidence support, and who must decide what remains acceptable?

+

Learning objective: construct a bounded review argument, distinguish expectations from implemented checks, and identify evidence gaps and decision responsibility.

+

Prerequisite: Continuous Engineering.

+

Manual assurance review using V0 sources. No approval, compliance evaluation or certification is performed. Hypothetical cases are teaching examples.

+ +
+

From a passing calculation to a justified claim

+

The monitoring team proposes a larger sensor radius and obtains a geometric PASS. Someone asks whether the configuration can now be accepted for operational use. The calculation supports a narrower statement: under particular inputs, criterion and idealized assumptions, the sampled area estimate meets the threshold. It does not establish that a physical sensor will detect the objects the operator needs to monitor.

+

The gap is a reasoning problem before it is a tooling problem. We must say what is being claimed, why the available evidence bears on that claim and what remains unsupported. A longer list of successful checks cannot supply a missing relationship between geometric area and operational detection.

+

For this lesson, a claim is a statement under review; evidence is an actual observation from an identified execution or source; supporting reasoning explains their connection. A control is a defined measure intended to constrain or check work. Decision responsibility identifies who must resolve remaining questions within the real assignment. These are local teaching terms, not a claim of standards conformance.

+
+
+

Separate the expectation from its mechanism

+

The operational need motivates the work. The requirement defines a geometric criterion, currently {requirement.threshold_percent}%, for {scenario.id}. A review expectation such as “identify the evaluated revision” concerns how a proposal is assessed. It does not replace that behavioral criterion or provide its operational basis.

+

An expectation also differs from an implemented mechanism. The source validator checks contracts and relationships. The registered test assertions check specified behavior. Generated analyses record inputs and execution context. None of those mechanisms automatically decides whether the operational need is adequately addressed. Read their actual scope before describing them as controls over a broader decision.

+

The table maps selected review expectations to existing sources and observations. It is a manual teaching aid, not a canonical policy, a control evaluation result or an approval record. The responsible reviewers named here describe roles needed by the exercise; they do not identify appointed people or assert configured repository permissions.

+
+
+ + + + + +
What each existing mechanism can support
ExpectationExisting source/checkObservation neededLimit and next responsibility
Definitions are interpretableSource validationActual validation outcome and definitions at its revisionContracts do not establish operational basis; requirement reviewer examines the criterion.
Implemented behavior matches assertions{manifest.test.id} and model testsActual test command/log and checked revisionSuccessful assertions preserve the canonical geometric FAIL; model reviewer assesses omitted behavior.
Analysis is attributableProposal records and provenanceDefinitions, differences, calculation and execution contextAttribution is not acceptance; proposal reviewer checks task scope and evidence applicability.
Decision is justifiedWritten task boundaryExplicit claim, gaps and responsible next reviewNo operational approval is recorded here; responsible engineering authority must resolve acceptance.
+
+
+

Traceability is a route to review

+

A source link lets a reviewer inspect a definition; a stable identifier connects records across changes. Neither establishes that an execution used today's definition. Match source revision, working-tree state, inputs, criterion, method and model version before attaching a retained result to the claim being reviewed.

+

Then test the reasoning, not merely the links. An ideal circular footprint omits terrain, occlusion, uncertainty and sensor faults. Evidence of its sampled area supports a geometric statement under those omissions. If the claim concerns physical detection, name the missing observations or models instead of treating additional trace links as stronger physical evidence.

+

Counterarguments make that boundary inspectable. Ask whether the criterion has a justified operational basis, whether the scenario represents intended use and whether the method can observe the behavior claimed. An unanswered question is an explicit limitation. It is not automatically a measured failure, and it must not disappear because another check passed.

+

Keep the argument reviewable as the proposal evolves. If the evaluated input changes, revisit the associated observation. If the claim broadens, revisit whether the same method can support it. If only a document link changes, confirm that it still identifies the intended definition. These are different review questions; recording them explicitly helps the next engineer avoid carrying an unsupported conclusion into a later decision.

+
+
+

Build a bounded review argument

+
    +
  1. Apply the radius-only task. Try the radius proposal and inspect its exact difference. Write the narrow geometric claim, including criterion and assumptions.
  2. +
  3. Reset and try the threshold proposal. Compare changed fields and explain why calculation success does not justify the new criterion under that assignment.
  4. +
  5. Break a reference, then restore/reset. Distinguish invalid definitions from valid definitions with insufficient operational support.
  6. +
  7. Use the review table to name actual evidence needed, remaining gaps and the responsible next review. No decision is saved or approved by this page.
  8. +
+ +
+
+

A proposal can pass and still need a decision

+

Both existing proposal examples can produce a modeled PASS. The radius example changes geometry while retaining the criterion. The threshold example changes evaluation meaning while keeping the same coverage. Under the radius-only assignment, the latter is outside the agreed edit boundary even though its data validate and its arithmetic is correct.

+

A request to relax the criterion therefore needs a separately justified requirement decision and appropriate authority. The proposal author cannot derive that authority from the result they wish to obtain. Likewise, changing expected assertions to conceal a known outcome would remove useful feedback rather than resolve the engineering problem.

+

Keep the stages visible: propose, validate, analyze, interpret and decide. In this exercise the decision remains unresolved. A reviewer can identify the narrow supported claim and request missing evidence without either accepting the physical design or declaring every aspect of the proposal invalid. No automated approval system is needed to practice that distinction.

+
+
+

Review hypothetical evidence gaps

+

These designed cases do not report actual missing artifacts or failed controls. State what remains supportable before revealing the explanation.

+
A PASS has no provenance

The label alone cannot be attributed to the candidate. Request definitions and execution context; do not invent a revision or claim verified suitability.

+
The proposal is valid, but operational evidence is absent

The geometric claim may remain supported by its actual calculation. Physical acceptance remains open; the responsible engineering reviewer must identify required operational evidence.

+
Someone asks to lower the threshold

Identify the changed requirement and its missing justification. Refer it to the responsible requirement authority; a passing number cannot authorize the change.

+
The historical artifact has expired

State that the original record was unavailable. A local reproduction is a new execution with its own provenance; it does not reconstruct an original approval or observation.

+
+
+

Record what was actually inspected

+

Follow the repository assurance review to inspect actual definitions and generated records at an identified checkout. Reference generation evaluates canonical inputs; separate test logs establish assertion execution. Proposal analysis explicitly does not execute the registered reference test against changed inputs. Preserve those meanings in your written argument.

+

No historical CI artifact is loaded by this page. Browser proposals are temporary; the baseline is calculated at build time. Retained artifacts expire after 30 days and may require sign-in. Record what you actually inspected, what was unavailable and which claim remains unresolved. This review is an aid to accountable reasoning, not production-system assurance or certification.

+
+
+

Check your reasoning

+
1. Does traceability establish evidence sufficiency?

No. It enables inspection; reasoning must still connect the evidence's scope and limitations to the claim.

+
2. Is an unobserved operational behavior a measured failure?

No. Missing support and a measured failure are different findings. Name the gap without inventing a result.

+
3. Can a PASS authorize a changed criterion?

No. The criterion needs its own engineering basis and responsible decision; task authority does not follow from arithmetic.

+
4. Does this review table implement governance controls?

No. It maps expectations to existing checks and remaining decisions. It records no approval or compliance evaluation.

+
+
+

Next: preserve meaning through evolution

+

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

+
+

← Chapter 9 · Learning path · Inspect engineering sources →

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

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

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

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

+

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

Intent → definition → evidence

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