From 3e54d518c41de01ee470a91d3937e64fd6aa6b1e Mon Sep 17 00:00:00 2001 From: Michael Zargham Date: Fri, 2 Oct 2026 09:41:48 -0400 Subject: [PATCH 01/25] Spec: diagram/text integration redesign, harness-driven, durable to compaction Addresses two findings: Phase 2's own diagram-survey table shows 14 of 16 placements were 'add' not 'replace', so dense text stayed in place next to every new diagram; every construction notebook prints its own assembled increment twice (once per fragment, once again as a 'reflection'). Scopes a harness-driven, two-phase fix (survey, then implementation) with explicit model/role discipline per DL-090's own lesson, folds in four already-identified cleanup items, and states the plan-sequencing requirement needed to stay durable across a context compaction. --- ...6-10-02-diagram-text-integration-design.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md diff --git a/docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md b/docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md new file mode 100644 index 0000000..48987ad --- /dev/null +++ b/docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md @@ -0,0 +1,87 @@ +# Diagram/text integration: make diagrams replace text, not just sit near it, and reduce prose bloat under a parsimony heuristic — fully harness-driven, durable to context loss + +## Context + +Phase 2 (merged, PR #24) added 16 diagrams across Chapters 1–8 and 10. Z read the result locally and reported it still reads as text-heavy, with the diagrams' own contextual fit unclear. Investigation (this session) found the specific mechanism: `decisions/diagram-survey.md`, the source of truth for every Phase 2 placement, tagged 14 of 16 placements `add` (a diagram inserted near an existing dense text block, which stays exactly where it was) and only 2 `replace` (both partial — "the `Allocations:` line only"). Several `add` rows say explicitly why: *"add (not replace — the raw source still shows requirement/override syntax the diagram can't)"*, *"add, not full replace (covers only the Part-structure portion of the dump)"*. Z's own original framing at the start of the diagram-survey mission — diagrams "can be additive or replace large text str outputs" — was implemented almost entirely as the first half. + +Separately, every construction-introducing notebook (13 of them, per `toaster-recipe/SKILL.md`) follows a fragment-by-fragment declare-and-narrate pattern that ends by assembling everything just shown into `TOASTER_INCREMENT` and **printing the identical text again** as a "reflection" cell, before loading the real cumulative model from disk. The reflection print's only purpose is narrative (the actual load always reads the committed `.sysml` file, never `TOASTER_INCREMENT` itself) — it exists to give the seam cell's own "E" (result/embodiment) step something to point at, per `toaster-recipe`'s own Tall-lens mapping. Right now that something is a verbatim duplicate of text the reader just read, cell by cell, above it. + +Separately again, five chapters (Ch2, Ch3, Ch5, Ch8, Ch10) have one non-construction notebook each that opens with a single large `print(source)` call dumping the **entire cumulative model file** — 45 to 213 lines, per `decisions/diagram-survey.md`'s own measurements ("an 83-line verbatim model dump," "a 213-line verbatim model dump, the densest block in the chapter"). These already each got a diagram added nearby in Phase 2; none were trimmed, because Phase 1's survey judged the diagram couldn't replace everything the dump shows (attribute values, judgment-record fields, requirement bodies) — true, but incomplete: the diagram can now replace the dump's own *structural* content (composition, typing, and — since the post-Phase-2 `model_to_dot()` fix — specialization too), leaving only a genuinely smaller, targeted remainder that actually needs to stay as text. + +This spec also folds in two things Z raised directly, separate from but related to the above: the harness-bypass incident (DL-090/DL-091) showed that a stretch of direct, unreviewed editing produced real regressions, and this redesign — large, touches most chapters, easy to rationalize as "just text edits" — is exactly the shape of work that invites repeating it if not structured against that in advance. And: the project's own documents (chapters, and this spec/plan pair itself) have grown large over a long session, and bloat works against the same didactic-clarity goal this whole redesign serves — a parsimony check belongs in the design, not just in the implementation. + +## Decisions already made (confirmed with Z via chat) + +1. **Scope: both the diagram-replaces-text question and the construction-zone double-print duplication**, not diagrams alone — confirmed via popup. The double-print pattern is in every one of the 13 construction notebooks, independent of whether any given notebook has a diagram at all, and is arguably the larger, more uniform contributor to the "wall of text" impression. +2. **Approach: the diagram takes over the reflection step's own job, it doesn't just get added near it** ("Approach A," confirmed via chat). For a construction notebook with a diagram: `TOASTER_INCREMENT` is still assembled (needed nowhere except the print it no longer has) but not printed again; the model loads from the committed cumulative file as before; a brief bridge sentence and the diagram occupy the slot the reflection print used to, becoming the seam's own "E" step. For the five whole-dump notebooks: the `print(source)` call shrinks to whatever the diagram genuinely cannot show, not the full file. +3. **This redesign must run entirely through this repo's own builder/reviewer harness**, with explicit, narrow model/role scoping per task — confirmed by Z directly, in response to the harness-bypass incident this same session already produced and fixed once (DL-090). **Precisely scoped prohibition:** the orchestrator does not edit any *chapter content* (a notebook, `index.md`, `conclusion.md`, or model file) directly, at any point in this redesign, full stop. This does NOT extend to the orchestrator's own established administrative record-keeping — compiling Phase A's per-chapter agent findings into the committed `decisions/diagram-text-integration-survey.md`, and writing/closing `decisions/log.md` DL entries — which is the same role the orchestrator already performed compiling `decisions/diagram-survey.md` from Phase 1's own 10 parallel agents, and is not the kind of edit that produced the harness-bypass incident (that incident was direct edits to *chapter notebooks and a skill file*, never to the decision log itself). A skill edit, if one is ever needed during this redesign, follows `skill-editor`'s own pre-edit gate exactly as DL-091 already did — its own established, separate, lower-risk protocol, not a carve-out from this decision. Every task touching chapter content is a `CONTRACT.md` in its own worktree: builder on `claude-sonnet-5`, reviewer on `claude-opus-5-5` (a different model, never waived), exhaustive non-goals per task, and — new for this redesign specifically — a verification step that includes at least one `simulated-learner` spot-check (not just `pytest`/construction-check) for any notebook whose prose is being meaningfully trimmed, since the actual risk here is "trimmed too far, now confusing," which only a reader-shaped check catches. +4. **Known, already-identified cleanup items are folded into whichever task already touches that file, as explicit, enumerated acceptance criteria — not an open "also clean up what you find" instruction.** The harness-bypass audit's own third review pass already found and listed real, bounded items out of its own scope at the time (see "Rolling cleanup, enumerated" below). Re-opening discovery as a standing instruction is exactly the kind of under-scoped task that produced the incident; every cleanup item in this redesign is named in the plan by file and nature before any builder starts. +5. **Durability: this spec and the plan that follows it must each be fully self-contained**, written so a fresh session (or this one, after a context compaction) can execute from the plan file alone with no dependency on this conversation's own history. This governs format, not content: `writing-plans`' own no-placeholder, exact-paths, exact-interfaces discipline already produces this; this spec states it as a requirement so the plan is held to it explicitly, and so execution is explicitly directed through *this repo's own* `orchestrator-protocol` "Plan-driven non-chapter work" mechanism (one `CONTRACT.md` per task, sequenced per the plan's own stated dependencies) rather than either of `writing-plans`' own generic two options (Subagent-driven / Native) — neither of which is this project's own established, already-proven harness. + +## Process: survey first, then implement — same two-phase shape the original diagram-survey mission used, because it worked + +**Phase A (survey).** One read-only research agent per affected chapter (Ch1 through Ch8, Ch10 — the same 9 chapters Phase 2 touched; Ch9 has no construction notebooks and no whole-dump notebook, confirmed by its own "no new model element" design, so it is out of scope here too), each given: that chapter's real notebooks, the already-compiled `decisions/diagram-survey.md` (so the agent knows which diagrams already exist and what they draw), and this spec's own two target patterns (construction-zone double-print; whole-dump-notebook over-printing). Each agent returns a structured finding per notebook it touches: which cells are in scope, the EXACT proposed new cell content (not a description of an edit — the literal replacement text, the same rigor `decisions/diagram-survey.md` itself used), and for whole-dump notebooks specifically, exactly what residual text (if any) must stay because no diagram covers it, quoting the specific lines. + +**Deliverable:** `decisions/diagram-text-integration-survey.md`, same shape as `decisions/diagram-survey.md` — a short per-chapter strategy paragraph, then a table (notebook, cell(s), current content, proposed content, construction-zone-replace or whole-dump-trim, rationale). This becomes the source of truth the implementation plan's own tasks are generated from, the same relationship Phase 2's plan had to Phase 1's survey. + +**Phase B (implementation).** Generated via `writing-plans` from Phase A's own survey output — one task per chapter (or per notebook, where a chapter's own changes are large enough to split, matching Phase 2's own task granularity), each a `CONTRACT.md` with the survey's own proposed content as the acceptance criterion's literal target text, not a restatement. Sequencing follows chapter order only where a later chapter's own task would otherwise review stale content from an earlier one's diagram — in practice, these 9 chapters' own text-integration tasks are independent of each other (each touches only its own chapter's own files) and can run in parallel, the same way Phase 2's 9 chapter tasks did. + +**Plan sequencing, stated explicitly for durability.** Mirroring the original diagram-survey mission's own two-cycle precedent (Phase 1 ran without a dedicated plan file; Phase 2 got its own, written only after Phase 1's findings existed), this spec covers both phases, but only **Phase A** gets a `writing-plans`-generated plan file now — Phase B's exact per-chapter content cannot be written without placeholders until Phase A's real findings exist, and `writing-plans`' own "No Placeholders" rule forbids that. The Phase A plan file itself states, as its own final step, that its own completion (the committed `decisions/diagram-text-integration-survey.md`) is the trigger to invoke `writing-plans` again for Phase B — so a session resuming after this one (compacted or not) finds that instruction on disk, in the plan, not only in this spec or in conversation history. + +## The two target patterns, specified precisely + +**Pattern 1 — construction-zone reflection print, where a diagram already exists for that notebook or chapter.** + +Before: +``` +[fragment cells + narration, one per declaration] +... +[code] TOASTER_INCREMENT = fragment1+fragment2+...; print(TOASTER_INCREMENT) + source = Path(cumulative).read_text(); model = conn.load_from_content(...); assert model.ok +[markdown] seam cell +``` +After: +``` +[fragment cells + narration, one per declaration] +... +[code] TOASTER_INCREMENT = fragment1+fragment2+... # assembled, not printed + source = Path(cumulative).read_text(); model = conn.load_from_content(...); assert model.ok +[markdown] bridge: what's about to be shown and why (one sentence, matching this tutorial's own established bridge-cell convention — see Ch6's own cells 19/20 for the precedent this already uses) +[code] render the diagram +[markdown] seam cell — now points at text / load / diagram, not text / load / reprinted text +``` +`TOASTER_INCREMENT`'s own assignment line stays (it documents, by its own name, exactly what this notebook newly declares — a real, legible artifact even unprinted) unless a survey agent finds a specific reason to remove it for a given notebook, stated in the survey. + +**Pattern 1b — construction-zone reflection print, where NO diagram exists or is planned for that notebook.** The duplication is still real even without a diagram to replace it with. Trim: drop the reflection print, keep `TOASTER_INCREMENT`'s own assignment, and replace the "E" step with a real, short confirmation query already in this tutorial's own idiom — `model.find()` or `model.query()` against the construct just declared, confirming it landed, the same device several notebooks already use elsewhere as their demonstration step. This is NOT "no fix" and NOT "invent a diagram" — it is the same seam-completing move as Pattern 1, using the tool this tutorial already has for notebooks a diagram doesn't fit. + +**Pattern 2 — whole-chapter-dump notebooks (Ch2-03, Ch3-03, Ch5-01, Ch8-01, Ch10-01).** `print(source)` currently dumps the entire cumulative file. After: `print(source)` is removed or trimmed to a short, targeted excerpt (the survey states exactly which lines, by construct name, for each of the five) covering only what the chapter's own diagram cannot show — judgment-record field values, requirement/constraint bodies, attribute defaults, anything the structural diagram (composition + typing + specialization, as of the post-Phase-2 `model_to_dot()` fix) genuinely omits. The diagram itself does not move; this pattern only shrinks what surrounds it. + +## Parsimony heuristic (new this pass, applied narrowly) + +Z's own framing: trimmed text must still "support a realistic human learning experience" — parsimony is a means to didactic clarity, not an end pursued for its own sake, and not license for an open-ended prose-cutting pass across the whole tutorial. Scope, deliberately narrow: this heuristic applies **only** to the specific cells Pattern 1/1b/2 above already touch, as a quality bar on the REPLACEMENT text each survey agent proposes (shorter must not mean thinner — a trimmed caption or bridge sentence must still carry the same real content the longer version did, the same standard already proven this session fixing the audit's own F5 finding, where a first trim attempt lost a causal connection and had to be redone). It does **not** authorize touching any prose this spec's own two patterns don't already name — a chapter's existing narration cells, judgment-record prose, or exercise text are out of scope here regardless of how verbose a survey agent might find them, unless a specific instance is separately escalated to Z. + +## Rolling cleanup, enumerated (not open-ended) + +Found by the harness-bypass audit's own third review pass, explicitly marked "out of scope" for that contract, carried forward here as named, bounded items — each folded into the task that already touches its file, not a separate sweep: + +1. **Ch5, Ch6, Ch7 `index.md` Ingredients tables don't match their own notebooks' current headings** in case or wording ("Model Navigation" vs. "model navigation," "Stopping Judgment" vs. "stopping judgment," "Interfaces" vs. "port and interface," a curly vs. straight apostrophe in Ch7's own table). Ch1–4 and Ch8–10's own tables already match (Ch8–10 fixed by DL-089's own F2). Fold into whichever Phase B task touches that chapter's `index.md` already (every chapter in scope here does, per Pattern 1/2 above) — a one-line sync, same move as DL-089's F2. +2. **Ch1–7 index tables use `"01:"` as the notebook-number separator; Ch8–10 use `"01 -"`.** Pick one (recommend `"01:"`, since it's the 7-chapter majority and the older convention) and make Ch8–10 match, in the same pass as item 1 above. +3. **`chapters/ch08-checking/01-invariant-def.ipynb`'s own filename and URL slug still say `invariant-def`**, even though DL-089 already corrected its heading to "assert constraint" (the notebook declares an `assert constraint`, not a formal invariant). A rename, with a full repo-wide reference sweep (`myst.yml`, every cross-reference, every historical-record file left alone per the convention `chapters/ch05-architecture/01-model-navigation.ipynb`'s own earlier rename already established), follows the exact same proven method as that rename — fold into Ch8's own Phase B task. +4. **`DEFERRED.md` D-037's own real gap (`render_action_flow()`/`render_state_flow()` dropping flow pins and state-activity action names) is tracked, not fixed, by Z's own earlier decision** — this redesign does not reopen that decision. Noted here only so a Phase A survey agent doesn't rediscover and re-propose it as new scope. + +Any OTHER mess a survey agent notices and is not in this list gets flagged in `decisions/diagram-text-integration-survey.md` as an open question for Z, exactly like Phase 1's own survey handled things outside its own scope — never fixed silently, never expanded into this redesign's own scope without being asked first. + +## Non-goals + +- No chapter's own taught content, model, or didactic sequencing changes — this redesign changes how existing content is *presented* (diagram vs. print, full dump vs. targeted excerpt), never what the chapter teaches or in what order. +- No change to `render.py` or any rendering function — this redesign consumes diagrams exactly as Phase 2 built them; any new rendering capability (specialization-edge labels, flow-pin content, etc.) is out of scope and already tracked separately (`DEFERRED.md`). +- No open-ended prose-trimming pass beyond the two named patterns and the four enumerated cleanup items above. +- No skill-content changes beyond what Phase B tasks' own acceptance criteria name; any skill edit still goes through `skill-editor`'s own pre-edit gate (DL-091's own precedent), authored by the orchestrator directly only when that gate's own blast-radius table clears it, exactly as DL-091 did — never bundled into a chapter-content builder contract. +- No work on Chapter 9 (no construction notebooks, no whole-dump notebook, no change needed). + +## Verification + +- Phase A: every one of the 9 chapters' own agents confirmed to have read every notebook it reports on (not assumed); the compiled survey cross-checked for internal consistency (a proposed Pattern-2 trim claiming a diagram covers content that diagram doesn't actually draw would be a defect in the survey itself, checked the same way Phase 1's own survey was checked against Phase 0's capability matrix). +- Phase B, per task: re-execute every touched notebook end to end (exit 0, zero cell errors); full suite (`uv run pytest tests/ glossary/tests/ -q`) and `scripts/check_construction.py --check`, both clean; pacing rule holds; `tutorial-style-guide` word-count and caption-sentence-count rules hold (the exact rules the audit's own F5 finding enforced); **at least one `simulated-learner` persona spot-check** on any notebook whose prose shrank materially, specifically checking whether the trimmed version still lets a reader reconstruct what the original conveyed — report NEEDS-FIX if not, same bar as the regular chapter-checkpoint battery. +- Every Phase B task independently reviewed by a different model before merge — no exceptions, no narrow "this one's too small to need review" judgment calls, which is precisely the reasoning that produced the harness-bypass incident this spec's own Decision 3 exists to prevent. +- Before opening a PR for this work: a final targeted read-through (not a full 29-report battery — the regular checkpoint battery already covers general comprehension; this read-through specifically checks that no chapter reads as *less* informative than before, only differently organized). From 3dcca6858fcf51239b0752330ccbb188494a4cc9 Mon Sep 17 00:00:00 2001 From: Michael Zargham Date: Fri, 2 Oct 2026 09:45:03 -0400 Subject: [PATCH 02/25] Spec correction: verify the Pattern-2 whole-dump notebook list by direct grep The original draft claimed Ch2/Ch3/Ch5/Ch8/Ch10 without checking each one; a repo-wide grep for the literal print(source) cell shows the real list is Ch2-03, Ch3-03, Ch4-03, Ch5-01, Ch6-03. Neither Ch8-01 nor Ch10-01 has this pattern at all. Caught before Phase A's own agents would have been sent out on a false premise. --- .../specs/2026-10-02-diagram-text-integration-design.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md b/docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md index 48987ad..40e5332 100644 --- a/docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md +++ b/docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md @@ -6,14 +6,14 @@ Phase 2 (merged, PR #24) added 16 diagrams across Chapters 1–8 and 10. Z read Separately, every construction-introducing notebook (13 of them, per `toaster-recipe/SKILL.md`) follows a fragment-by-fragment declare-and-narrate pattern that ends by assembling everything just shown into `TOASTER_INCREMENT` and **printing the identical text again** as a "reflection" cell, before loading the real cumulative model from disk. The reflection print's only purpose is narrative (the actual load always reads the committed `.sysml` file, never `TOASTER_INCREMENT` itself) — it exists to give the seam cell's own "E" (result/embodiment) step something to point at, per `toaster-recipe`'s own Tall-lens mapping. Right now that something is a verbatim duplicate of text the reader just read, cell by cell, above it. -Separately again, five chapters (Ch2, Ch3, Ch5, Ch8, Ch10) have one non-construction notebook each that opens with a single large `print(source)` call dumping the **entire cumulative model file** — 45 to 213 lines, per `decisions/diagram-survey.md`'s own measurements ("an 83-line verbatim model dump," "a 213-line verbatim model dump, the densest block in the chapter"). These already each got a diagram added nearby in Phase 2; none were trimmed, because Phase 1's survey judged the diagram couldn't replace everything the dump shows (attribute values, judgment-record fields, requirement bodies) — true, but incomplete: the diagram can now replace the dump's own *structural* content (composition, typing, and — since the post-Phase-2 `model_to_dot()` fix — specialization too), leaving only a genuinely smaller, targeted remainder that actually needs to stay as text. +Separately again, five notebooks across five different chapters each have a `print(source)` call dumping the **entire cumulative model file** verbatim — confirmed by a direct, repo-wide grep of every in-scope notebook for a literal `print(source)` code cell, not assumed from `decisions/diagram-survey.md`'s own prose or from an earlier, less careful pass over this same spec: `chapters/ch02-requirements/03-judgment-context.ipynb` cell 2 (~45 lines), `chapters/ch03-measures/03-threshold-judgment.ipynb` cell 2 (83 lines), `chapters/ch04-functional-decomp/03-completeness-check.ipynb` cell 2 (115+ lines), `chapters/ch05-architecture/01-model-navigation.ipynb` cell 2 (131 lines), `chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb` cell 2 (213 lines, explicitly left un-trimmed by its own Phase 2 contract: "add, the full source print stays"). **An earlier draft of this spec claimed the list was Ch2/Ch3/Ch5/Ch8/Ch10 — wrong, caught and corrected by this direct grep before Phase A's own agents could be sent out on a false premise.** Neither `chapters/ch08-checking/01-invariant-def.ipynb` nor `chapters/ch10-traceability-signoff/01-traceability-graph.ipynb` contains a `print(source)` call at all; both got their own Phase 2 diagram added to ground one specific named claim, with no surrounding dump to trim — they are out of scope for this pattern. All five confirmed notebooks already got a diagram added nearby in Phase 2; none were trimmed, because Phase 1's own survey judged the diagram couldn't replace everything the dump shows (attribute values, judgment-record fields, requirement bodies) — true, but incomplete: the diagram can now replace the dump's own *structural* content (composition, typing, and — since the post-Phase-2 `model_to_dot()` fix — specialization too), leaving only a genuinely smaller, targeted remainder that actually needs to stay as text. This spec also folds in two things Z raised directly, separate from but related to the above: the harness-bypass incident (DL-090/DL-091) showed that a stretch of direct, unreviewed editing produced real regressions, and this redesign — large, touches most chapters, easy to rationalize as "just text edits" — is exactly the shape of work that invites repeating it if not structured against that in advance. And: the project's own documents (chapters, and this spec/plan pair itself) have grown large over a long session, and bloat works against the same didactic-clarity goal this whole redesign serves — a parsimony check belongs in the design, not just in the implementation. ## Decisions already made (confirmed with Z via chat) 1. **Scope: both the diagram-replaces-text question and the construction-zone double-print duplication**, not diagrams alone — confirmed via popup. The double-print pattern is in every one of the 13 construction notebooks, independent of whether any given notebook has a diagram at all, and is arguably the larger, more uniform contributor to the "wall of text" impression. -2. **Approach: the diagram takes over the reflection step's own job, it doesn't just get added near it** ("Approach A," confirmed via chat). For a construction notebook with a diagram: `TOASTER_INCREMENT` is still assembled (needed nowhere except the print it no longer has) but not printed again; the model loads from the committed cumulative file as before; a brief bridge sentence and the diagram occupy the slot the reflection print used to, becoming the seam's own "E" step. For the five whole-dump notebooks: the `print(source)` call shrinks to whatever the diagram genuinely cannot show, not the full file. +2. **Approach: the diagram takes over the reflection step's own job, it doesn't just get added near it** ("Approach A," confirmed via chat). For a construction notebook with a diagram: `TOASTER_INCREMENT` is still assembled (needed nowhere except the print it no longer has) but not printed again; the model loads from the committed cumulative file as before; a brief bridge sentence and the diagram occupy the slot the reflection print used to, becoming the seam's own "E" step. For the five whole-dump notebooks (Ch2-03, Ch3-03, Ch4-03, Ch5-01, Ch6-03 — see Context): the `print(source)` call shrinks to whatever the diagram genuinely cannot show, not the full file. 3. **This redesign must run entirely through this repo's own builder/reviewer harness**, with explicit, narrow model/role scoping per task — confirmed by Z directly, in response to the harness-bypass incident this same session already produced and fixed once (DL-090). **Precisely scoped prohibition:** the orchestrator does not edit any *chapter content* (a notebook, `index.md`, `conclusion.md`, or model file) directly, at any point in this redesign, full stop. This does NOT extend to the orchestrator's own established administrative record-keeping — compiling Phase A's per-chapter agent findings into the committed `decisions/diagram-text-integration-survey.md`, and writing/closing `decisions/log.md` DL entries — which is the same role the orchestrator already performed compiling `decisions/diagram-survey.md` from Phase 1's own 10 parallel agents, and is not the kind of edit that produced the harness-bypass incident (that incident was direct edits to *chapter notebooks and a skill file*, never to the decision log itself). A skill edit, if one is ever needed during this redesign, follows `skill-editor`'s own pre-edit gate exactly as DL-091 already did — its own established, separate, lower-risk protocol, not a carve-out from this decision. Every task touching chapter content is a `CONTRACT.md` in its own worktree: builder on `claude-sonnet-5`, reviewer on `claude-opus-5-5` (a different model, never waived), exhaustive non-goals per task, and — new for this redesign specifically — a verification step that includes at least one `simulated-learner` spot-check (not just `pytest`/construction-check) for any notebook whose prose is being meaningfully trimmed, since the actual risk here is "trimmed too far, now confusing," which only a reader-shaped check catches. 4. **Known, already-identified cleanup items are folded into whichever task already touches that file, as explicit, enumerated acceptance criteria — not an open "also clean up what you find" instruction.** The harness-bypass audit's own third review pass already found and listed real, bounded items out of its own scope at the time (see "Rolling cleanup, enumerated" below). Re-opening discovery as a standing instruction is exactly the kind of under-scoped task that produced the incident; every cleanup item in this redesign is named in the plan by file and nature before any builder starts. 5. **Durability: this spec and the plan that follows it must each be fully self-contained**, written so a fresh session (or this one, after a context compaction) can execute from the plan file alone with no dependency on this conversation's own history. This governs format, not content: `writing-plans`' own no-placeholder, exact-paths, exact-interfaces discipline already produces this; this spec states it as a requirement so the plan is held to it explicitly, and so execution is explicitly directed through *this repo's own* `orchestrator-protocol` "Plan-driven non-chapter work" mechanism (one `CONTRACT.md` per task, sequenced per the plan's own stated dependencies) rather than either of `writing-plans`' own generic two options (Subagent-driven / Native) — neither of which is this project's own established, already-proven harness. @@ -54,7 +54,7 @@ After: **Pattern 1b — construction-zone reflection print, where NO diagram exists or is planned for that notebook.** The duplication is still real even without a diagram to replace it with. Trim: drop the reflection print, keep `TOASTER_INCREMENT`'s own assignment, and replace the "E" step with a real, short confirmation query already in this tutorial's own idiom — `model.find()` or `model.query()` against the construct just declared, confirming it landed, the same device several notebooks already use elsewhere as their demonstration step. This is NOT "no fix" and NOT "invent a diagram" — it is the same seam-completing move as Pattern 1, using the tool this tutorial already has for notebooks a diagram doesn't fit. -**Pattern 2 — whole-chapter-dump notebooks (Ch2-03, Ch3-03, Ch5-01, Ch8-01, Ch10-01).** `print(source)` currently dumps the entire cumulative file. After: `print(source)` is removed or trimmed to a short, targeted excerpt (the survey states exactly which lines, by construct name, for each of the five) covering only what the chapter's own diagram cannot show — judgment-record field values, requirement/constraint bodies, attribute defaults, anything the structural diagram (composition + typing + specialization, as of the post-Phase-2 `model_to_dot()` fix) genuinely omits. The diagram itself does not move; this pattern only shrinks what surrounds it. +**Pattern 2 — whole-chapter-dump notebooks (Ch2-03, Ch3-03, Ch4-03, Ch5-01, Ch6-03 — confirmed by a direct, repo-wide grep to be the complete list; see Context above).** `print(source)` currently dumps the entire cumulative file. After: `print(source)` is removed or trimmed to a short, targeted excerpt (the survey states exactly which lines, by construct name, for each of the five) covering only what the chapter's own diagram cannot show — judgment-record field values, requirement/constraint bodies, attribute defaults, anything the structural diagram (composition + typing + specialization, as of the post-Phase-2 `model_to_dot()` fix) genuinely omits. The diagram itself does not move; this pattern only shrinks what surrounds it. Ch8-01 and Ch10-01 have no Pattern 2 work — their own existing diagram-plus-caption already grounds its one named claim without a surrounding dump; they are in scope for Pattern 1/1b only (their own construction-zone notebooks, if any) and the enumerated rolling-cleanup items that name them. ## Parsimony heuristic (new this pass, applied narrowly) From f9af7116a45b5b7aac45b19f0e1f042c4bf5aa6d Mon Sep 17 00:00:00 2001 From: Michael Zargham Date: Fri, 2 Oct 2026 09:48:19 -0400 Subject: [PATCH 03/25] Phase A plan: diagram/text integration survey, 9 parallel chapter agents Fully self-contained -- every agent's dispatch prompt is written out in full, not described, per writing-plans' own no-placeholder rule. States explicitly, on disk, that completing this plan triggers writing Phase B's own plan next, so the instruction survives a context compaction. --- ...2-diagram-text-integration-phase-a-plan.md | 709 ++++++++++++++++++ 1 file changed, 709 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-a-plan.md diff --git a/docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-a-plan.md b/docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-a-plan.md new file mode 100644 index 0000000..90bd14e --- /dev/null +++ b/docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-a-plan.md @@ -0,0 +1,709 @@ +# Diagram/Text Integration — Phase A (Survey) Implementation Plan + +> **For agentic workers:** This plan's own tasks are NOT code-implementation tasks — there is no test-driven-development cycle, no `pytest`, no commit-per-step. Each task is a read-only research dispatch. Do not invoke `superpowers:subagent-driven-development` or `superpowers:executing-plans` for this plan; see "Execution mechanism" below for the actual procedure. + +**Goal:** Produce `decisions/diagram-text-integration-survey.md` — a committed, concrete, per-notebook inventory of exactly which cells get Pattern 1 (construction-zone diagram-replaces-reflection), Pattern 1b (construction-zone reflection-print trimmed to a confirmation query, no diagram available), or Pattern 2 (whole-dump `print(source)` trimmed to a targeted excerpt) treatment, with literal proposed replacement text for each — so Phase B (a separate plan, written only after this one's own output exists) has real content to implement against, not placeholders. + +**Architecture:** One read-only research agent per chapter (9 agents, Ch1–Ch8 and Ch10, dispatched in parallel), each given a fully-specified prompt (reproduced verbatim in each task below) instructing it to read every notebook in its own chapter and report structured, per-notebook findings. The orchestrator compiles the 9 reports into one document, with an explicit consistency-check pass before considering it final. + +**Tech Stack:** The `Agent` tool (`subagent_type: "Explore"`, read-only — no `Edit`/`Write`/`NotebookEdit` access, appropriate since this phase makes no repository edits); Python for the orchestrator's own compilation and consistency-check scripting (reading notebook JSON, reading SVG `` elements). + +**Spec:** `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` — read Decisions 1–5, the Process section, "The two target patterns, specified precisely," the Parsimony heuristic, "Rolling cleanup, enumerated," and Non-goals before executing any task below. + +## Global Constraints + +- **Chapter 9 is out of scope** (spec Non-goals) — no task below covers it. +- **This plan makes no repository edits other than the single compiled survey document** (`decisions/diagram-text-integration-survey.md`), authored by the orchestrator directly, not by any dispatched agent — this is the orchestrator's own established administrative-record-keeping role (spec Decision 3's own carve-out), the same role used compiling `decisions/diagram-survey.md` from Phase 1's own agents. +- **Every dispatched agent is read-only**: no notebook edits, no figure re-renders, no file writes of any kind. Each agent's own report comes back as its `SubagentHandback` text, not as a file it wrote. +- **Every agent must quote exact line numbers and exact cell content from the real files it reads** — never paraphrase from `decisions/diagram-survey.md`'s own prior findings, and never assume a prior finding (including this plan's own stated Pattern-2 cell locations, confirmed as of 2026-10-02) is still accurate if the agent's own read of the live file disagrees. If a disagreement is found, the agent reports it as a finding, not a silent correction. +- **Pattern-2 whole-dump notebooks, confirmed by a direct repo-wide grep on 2026-10-02 (re-verify, don't re-derive from scratch, but flag if this list is stale by the time an agent runs):** `chapters/ch02-requirements/03-judgment-context.ipynb` (cell 2), `chapters/ch03-measures/03-threshold-judgment.ipynb` (cell 2), `chapters/ch04-functional-decomp/03-completeness-check.ipynb` (cell 2), `chapters/ch05-architecture/01-model-navigation.ipynb` (cell 2), `chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb` (cell 2). No other notebook in scope has a `print(source)` call — in particular, `chapters/ch08-checking/01-invariant-def.ipynb` and `chapters/ch10-traceability-signoff/01-traceability-graph.ipynb` do NOT have this pattern (an earlier draft of the spec wrongly included them; corrected before this plan was written). + +## Review Focus + +Five ways a chapter-survey agent's own report could be wrong in a way that would corrupt Phase B if not caught before the survey document is finalized: + +1. **An agent proposes replacing a construction-zone reflection print with a diagram that doesn't actually exist for that notebook.** `decisions/diagram-survey.md` is the only source of truth for which notebooks already have a Phase 2 diagram; an agent must cite the specific diagram (tool, root/scope) it's proposing to reuse, not assume one exists because the chapter has diagrams elsewhere. Task 10 (compilation) cross-checks every Pattern-1 proposal against `decisions/diagram-survey.md`'s own table. +2. **An agent proposes a Pattern-2 trim that removes content the diagram doesn't actually cover.** The whole reason Phase 1 didn't trim these dumps originally is that the diagram only shows structure — a proposal that over-trims (removing a judgment-record field, a requirement body, an attribute default) would silently remove real information. Task 10's own consistency-check spot-checks a sample of Pattern-2 proposals against the real committed figure. +3. **An agent misses a construction notebook's own double-print entirely** because it skims rather than reads every cell. Each task below instructs the agent explicitly to read every notebook assigned to it in full, cell by cell, not to sample. +4. **An agent proposes new text that violates `tutorial-style-guide`'s own rules** (sentence word-count ceiling, caption sentence-count, no em-dash, no metanarration, no self-reference) — the exact class of defect the harness-bypass audit's own F5 finding caught. Each task instructs the agent to self-check its own proposed replacement text against these rules before reporting. +5. **An agent expands scope beyond the two named patterns and the enumerated cleanup items** — finding something that looks like a real improvement but isn't in the spec's own named scope. Each task instructs the agent to report such findings as an "open question" in its own report, never as a proposed edit. + +--- + +## Execution mechanism (read before Task 1) + +This plan has no builder/reviewer cycle, because it produces no code and nothing merges into chapter content. The mechanism: + +1. Dispatch all 9 chapter tasks (Task 1 through Task 9) as parallel `Agent` tool calls in a single message, `subagent_type: "Explore"`, each with the exact prompt text given in that task. +2. Collect each agent's own `SubagentHandback` report (delivered as a message, not a file). +3. Execute Task 10: compile all 9 reports into `decisions/diagram-text-integration-survey.md`, run the consistency-check, commit. +4. Task 10's own completion is this plan's terminal state. Its own final step states explicitly: invoke `superpowers:writing-plans` again, for Phase B, using `decisions/diagram-text-integration-survey.md` (now committed) as the primary input alongside the same spec. This instruction is written here, on disk, specifically so it survives a context compaction that might otherwise lose it. + +No independent review gate applies to Phase A's own output, because nothing here is shipped or merged into learner-facing content — Phase A's real adversarial check happens when Phase B's own tasks (generated from this phase's output) go through the full builder/reviewer harness, the same two-tier rigor the original diagram-survey mission used (Phase 1 undemanding, Phase 2 fully reviewed). + +--- + +## Task 1: Chapter 1 survey (System and Purpose) + +**Files:** none modified by this task (read-only). Chapter files read: `chapters/ch01-system-purpose/01-abstract-def.ipynb`, `02-part-def.ipynb`, `03-specialization.ipynb`, `04-composition.ipynb`, `index.md`. + +**Interfaces:** +- Consumes: the dispatch prompt below (self-contained; no other task's output). +- Produces: a structured report (format specified in the prompt) consumed by Task 10. + +- [ ] **Step 1: Dispatch the agent** + +Use the `Agent` tool with `subagent_type: "Explore"`, this exact prompt: + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch01-system-purpose/ -- read every one of its four +notebooks in full, cell by cell, not a sample: 01-abstract-def.ipynb, +02-part-def.ipynb, 03-specialization.ipynb, 04-composition.ipynb. Also read +index.md. + +This chapter has NO Pattern-2 whole-dump notebook (confirmed by direct grep, +2026-10-01) -- you are checking for Pattern 1/1b only (construction-zone +reflection-print duplication). Per decisions/diagram-survey.md, this chapter's +own diagrams already exist in 02-part-def.ipynb (two disconnected boxes, +model_to_dot(elements=[...])) and 04-composition.ipynb (full composition + +typing, model_to_dot(elements=containment_subgraph(...))) -- confirm these are +still there and still match that description by reading the real cells, don't +assume. + +For EACH of the four notebooks: +1. Find the construction-zone sequence: fragment-declare cells (each printed), + ending in a TOASTER_INCREMENT assignment, a print of it, then the real + cumulative-model load. Confirm this pattern is actually present (per + toaster-recipe/SKILL.md, not every notebook in this tutorial has it -- + report "no construction zone, no finding" if a notebook genuinely lacks + this structure rather than forcing a finding). +2. If 02-part-def.ipynb or 04-composition.ipynb has this pattern AND a diagram + already exists for it: propose Pattern 1 -- the exact new cell sequence + (quote the literal markdown/code you propose for the bridge cell and for + the TOASTER_INCREMENT cell with its print removed), confirming the diagram + cell's own existing code doesn't need to move. +3. If 01-abstract-def.ipynb or 03-specialization.ipynb has this pattern and NO + diagram exists: propose Pattern 1b -- the exact replacement for the + reflection-print cell (drop the print, keep the TOASTER_INCREMENT + assignment, add a short model.find()/model.query() confirmation of the + construct just declared; quote the literal code). +4. Self-check every piece of proposed replacement markdown text against + tutorial-style-guide/SKILL.md's rules before including it: sentences <=20 + words, no em-dash (the real "—" character; "--" is this tutorial's own + established convention and is fine), no metanarration, figure captions (if + any) exactly 2 sentences. + +Rolling cleanup: none of the four enumerated items in the spec name Chapter 1 +specifically -- do not propose any cleanup edit for this chapter unless you +find something new, in which case report it as an open question (see below), +never as a proposed edit. + +Report format, one entry per notebook (skip notebooks with no finding, but +say so explicitly -- "01-abstract-def.ipynb: no construction-zone duplication +found, cell N already differs from the pattern because X" is a valid, +useful report): + +NOTEBOOK: <path> +PATTERN: 1 | 1b | none +CELLS IN SCOPE: <cell indices/ids> +CURRENT CONTENT: <literal quote of what's there now> +PROPOSED CONTENT: <literal replacement text/code, not a description> +RATIONALE: <one or two sentences> + +Then a final "OPEN QUESTIONS" section for anything you found that doesn't fit +the above (including any Pattern-2-like dump you notice despite this chapter +being marked as having none -- re-verify with grep, don't trust this prompt's +own claim blindly), and a final "INDEX.MD CHECK" section confirming whether +this chapter's own Ingredients table already matches each notebook's current +first-line heading (Ch1's own table was already confirmed accurate as of +2026-10-02 -- note if you find it's drifted since). +``` + +- [ ] **Step 2: Save the report** + +Record the agent's full `SubagentHandback` text for use in Task 10. Do not summarize or discard any of it. + +--- + +## Task 2: Chapter 2 survey (Requirements and Assumptions) + +**Files:** none modified. Read: `chapters/ch02-requirements/01-requirement-def.ipynb`, `02-assumptions.ipynb`, `03-judgment-context.ipynb`, `index.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch02-requirements/ -- read every one of its three +notebooks in full, cell by cell: 01-requirement-def.ipynb, 02-assumptions.ipynb, +03-judgment-context.ipynb. Also read index.md. + +This chapter HAS a Pattern-2 whole-dump notebook: 03-judgment-context.ipynb, +cell 2, print(source) over the full cumulative model (~45 lines as of +2026-10-01 -- confirm the current line count yourself). Per +decisions/diagram-survey.md, a structure diagram (model_to_dot(model), whole +model) was already added nearby in Phase 2 -- confirm it's still there, +confirm exactly what it draws by reading the real committed figures/ch02-structure.svg +(grep its own <title> elements for node/edge names), and propose: (a) the +exact trimmed or removed print(source) call, (b) exactly what residual text +(if any) must stay because the diagram doesn't cover it -- 03-judgment-context.ipynb +is a judgment-record (asserted_context) notebook, so check specifically +whether the requirement's own require-constraint body, or any +ReviewRecord/judgment-record field content, is part of what print(source) +currently shows and the diagram cannot. Quote exact line ranges for whatever +you propose keeping. + +01-requirement-def.ipynb and 02-assumptions.ipynb: check each for the +construction-zone reflection-print pattern (fragment-declare cells ending in +a TOASTER_INCREMENT print). Per decisions/diagram-survey.md, neither has a +diagram of its own -- if the pattern is present, propose Pattern 1b (drop the +print, keep the assignment, add a model.find()/model.query() confirmation; +quote the literal replacement code). If either notebook's own structure +doesn't actually match this pattern, say so rather than forcing a finding. + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup: none of the four enumerated items name Chapter 2 +specifically. Report anything else you find as an open question, not a +proposed edit. + +Report format (same as Task 1's own spec): one NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE entry per finding, an OPEN +QUESTIONS section, and an INDEX.MD CHECK section (Ch2's table was already +confirmed accurate as of 2026-10-02 -- note if drifted). +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 3: Chapter 3 survey (Measures of Success) + +**Files:** none modified. Read: `chapters/ch03-measures/01-moe-definition.ipynb`, `02-mop-candidate-eval.ipynb`, `03-threshold-judgment.ipynb`, `04-verification-case.ipynb`, `index.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch03-measures/ -- read every one of its four notebooks +in full, cell by cell: 01-moe-definition.ipynb, 02-mop-candidate-eval.ipynb, +03-threshold-judgment.ipynb, 04-verification-case.ipynb. Also read index.md. + +This chapter HAS a Pattern-2 whole-dump notebook: 03-threshold-judgment.ipynb, +cell 2, print(source) over the full cumulative model (83 lines as of +2026-10-01 -- confirm the current line count yourself). A structure diagram +(model_to_dot(model), parts only) was already added nearby in Phase 2 -- +confirm it's still there by reading the real committed figures/ch03-structure.svg +(grep its own <title> elements). decisions/diagram-survey.md's own original +note on this dump said the diagram "cannot show TimelyToast, the folded +satisfy claim, or TimelyToastTest, which is the dump's actual point" -- verify +this is still true against the live figure and model, and propose: (a) the +exact trimmed print(source) call, (b) exactly what residual text must stay +(quote exact line ranges -- likely the TimelyToast requirement declaration, +the satisfy claim, and/or TimelyToastTest's own declaration, but confirm by +reading the real file, don't assume this list is complete or correct). + +01-moe-definition.ipynb, 02-mop-candidate-eval.ipynb, 04-verification-case.ipynb: +check each for the construction-zone reflection-print pattern. None has its +own diagram per decisions/diagram-survey.md -- if the pattern is present in +any of them, propose Pattern 1b (drop the print, keep the TOASTER_INCREMENT +assignment, add a model.find()/model.query() confirmation; quote the literal +replacement code). + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup: none of the four enumerated items name Chapter 3 +specifically. Report anything else you find as an open question. + +Report format (same as Task 1's own spec): NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE per finding, OPEN QUESTIONS, +INDEX.MD CHECK (Ch3's table was already confirmed accurate as of 2026-10-02). +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 4: Chapter 4 survey (Functional Decomposition) + +**Files:** none modified. Read: `chapters/ch04-functional-decomp/01-action-def-ffbd.ipynb`, `02-heating-refinement.ipynb`, `03-completeness-check.ipynb`, `index.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch04-functional-decomp/ -- read every one of its three +notebooks in full, cell by cell: 01-action-def-ffbd.ipynb, +02-heating-refinement.ipynb, 03-completeness-check.ipynb. Also read index.md. + +This chapter HAS a Pattern-2 whole-dump notebook: 03-completeness-check.ipynb, +cell 2, print(source) over the full cumulative model (115+ lines as of +2026-10-01 -- confirm the current line count yourself). Per +decisions/diagram-survey.md, a SCOPED structure diagram +(model_to_dot(elements=containment_subgraph(model, "ToasterDemo::Toaster", +depth=2))) was already added nearby -- confirm it's still there by reading +the real committed figures/ch04-structure.svg, and note this diagram is +SCOPED (rooted at Toaster, depth 2), not whole-model -- it will NOT show +everything the full dump shows even structurally (anything outside that +scope). decisions/diagram-survey.md's own original note said the diagram +"covers only the Part-structure portion of the dump" -- verify this against +the real figure and model, and propose: (a) the exact trimmed print(source) +call, (b) exactly what residual text must stay, including anything outside +the diagram's own Toaster/depth-2 scope as well as anything non-structural +(the completeness-check judgment record's own content, if cell 2's dump is +shared with that). Quote exact line ranges. + +01-action-def-ffbd.ipynb already has its own diagram (action-flow of +ToastBread, via render_action_flow -- NOT ApplyHeat; confirm this against the +real cell and figures/ch04-toastbread-flow.svg, since an earlier, now-corrected +draft of this redesign's own spec mis-stated which action this chapter's +diagram renders). Check it for the construction-zone reflection-print pattern; +if present, propose Pattern 1 (the diagram takes over the reflection step -- +quote the exact new bridge cell and the TOASTER_INCREMENT cell with its print +removed). + +02-heating-refinement.ipynb: no diagram per decisions/diagram-survey.md -- +check for the construction-zone pattern; if present, propose Pattern 1b (drop +the print, keep the assignment, add a confirmation query; quote the literal +code). + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup: none of the four enumerated items name Chapter 4 +specifically. Report anything else as an open question. + +Report format (same as Task 1's own spec): NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE per finding, OPEN QUESTIONS, +INDEX.MD CHECK (Ch4's table was already confirmed accurate as of 2026-10-02 -- +it already names both diagrams explicitly, per DL-089's own earlier fix; +confirm this is still true). +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 5: Chapter 5 survey (Architecture and Allocation) + +**Files:** none modified. Read: `chapters/ch05-architecture/01-model-navigation.ipynb`, `02-allocate.ipynb`, `03-interfaces.ipynb`, `index.md`, `conclusion.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch05-architecture/ -- read every one of its three +notebooks in full, cell by cell: 01-model-navigation.ipynb, 02-allocate.ipynb, +03-interfaces.ipynb. Also read index.md and conclusion.md. + +This chapter HAS a Pattern-2 whole-dump notebook: 01-model-navigation.ipynb, +cell 2, print(source) over the full cumulative model (131 lines as of +2026-10-01 -- confirm the current line count yourself). Per +decisions/diagram-survey.md, an UNSCOPED structure diagram (model_to_dot(), +whole model) was already added nearby -- confirm it's still there by reading +the real committed figures/ch05-structure.svg. Since this diagram is +unscoped, it likely covers the dump's own structural content fully; propose +(a) the exact trimmed or removed print(source) call, (b) exactly what +residual text must stay (if any -- it is plausible the answer here is "none, +the dump can be fully removed," unlike Ch2/Ch3/Ch4's own cases; confirm by +actually comparing what the dump shows against what the diagram draws, don't +assume). Quote exact line ranges for anything you propose keeping. + +NOTE: 02-allocate.ipynb and 03-interfaces.ipynb each separately re-print this +SAME 131-line dump again (decisions/diagram-survey.md's own row for them: +"same 131-line dump, repeated verbatim... no candidate... diagram fatigue, not +a real reduction"). Check whether these two notebooks' own dumps are STILL +present as of your own read -- if so, this is a genuine duplication Pattern 2 +as originally scoped does not quite cover (the SAME content printed three +times across one chapter, not once per notebook) -- report this explicitly as +a finding even though it doesn't fit either named pattern cleanly, proposing +what you think the right trim is (most likely: remove the repeat dumps +entirely from 02/03, since 01's own dump already establishes this content and +Chapter 1's own established convention is that later notebooks reference +rather than re-dump earlier content), but flag it as an OPEN QUESTION for Z/ +the orchestrator rather than treating your own proposal as settled, since it's +outside this plan's own named scope. + +03-interfaces.ipynb ALSO has its own separate diagram +(render_toolkit_interconnection(), sysml-toolkit-based, the conjugated-port +figure) -- this is unrelated to the whole-dump question above; just confirm +it's still present and unaffected by the duplicate-dump finding above. + +Check 01-model-navigation.ipynb, 02-allocate.ipynb, 03-interfaces.ipynb for +the construction-zone reflection-print pattern separately from the Pattern-2 +question above -- if present in any, propose Pattern 1 (if a diagram exists +for that specific construct) or Pattern 1b (if not); quote literal +replacement text. + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup -- THIS CHAPTER IS NAMED in enumerated item 1: Ch5's own +index.md Ingredients table says "Model Navigation" (title case) while +01-model-navigation.ipynb's own current heading is "model navigation" +(lowercase) -- confirm this mismatch against the live files and propose the +exact corrected table row (sync to the notebook's own current heading +exactly). Also check enumerated item 2 (Ch1-7 use "01:" separator, Ch8-10 use +"01 -") -- Ch5 already uses "01:" per the convention item 2 recommends +keeping, confirm this is still true, no change needed if so. + +Report format (same as Task 1's own spec): NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE per finding, OPEN QUESTIONS +(including the triple-dump finding above), INDEX.MD CHECK (propose the exact +corrected "Model Navigation" -> "model navigation" row text). +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 6: Chapter 6 survey (Recursive Decomposition) + +**Files:** none modified. Read: `chapters/ch06-recursive-decomp/01-subsystem-requirements.ipynb`, `02-second-level.ipynb`, `03-stopping-judgment.ipynb`, `index.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch06-recursive-decomp/ -- read every one of its three +notebooks in full, cell by cell: 01-subsystem-requirements.ipynb, +02-second-level.ipynb, 03-stopping-judgment.ipynb. Also read index.md. + +This chapter HAS a Pattern-2 whole-dump notebook: 03-stopping-judgment.ipynb, +cell 2, print(source) over the full cumulative model (213 lines as of +2026-10-01, the densest single block in this entire tutorial -- confirm the +current line count yourself). Per decisions/diagram-survey.md, a SCOPED +structure diagram (model_to_dot(elements=containment_subgraph(model, +"ToasterDemo::HeatingAssembly", depth=2))) was already added nearby, and this +chapter's own original Phase 2 contract explicitly chose "add (the full +source print stays)" rather than trimming -- this is the single largest +remaining text-reduction opportunity in the whole tutorial. Confirm the +diagram is still there via figures/ch06-structure.svg, and propose: (a) the +exact trimmed print(source) call, (b) exactly what residual text must stay +(the diagram is scoped to HeatingAssembly/depth-2, so anything about Toaster +itself, or non-structural content like the AI-C06 stopping-judgment's own +fields, would need to stay or move elsewhere -- quote exact line ranges, read +the real file, don't guess). + +01-subsystem-requirements.ipynb already has TWO diagrams of its own +(action-flow of ApplyHeat via render_action_flow, and an interconnection +diagram of HeatingAssembly via build_interconnection_intent/render_interconnection) +plus its own construction-zone reflection-print pattern (confirmed present +earlier this session, fixed once already for a different defect -- re-read +the live file, don't rely on memory). Propose Pattern 1 for its own +reflection-print cell: the diagram(s) already sit nearby per this chapter's +own existing bridge-cell convention (cells already named cell-ch06-applyheat-flow-caption +etc. -- read the real current cell IDs and content) -- confirm whether the +reflection print itself is still separately present and duplicative on top of +that, and if so, propose its exact removal (quote the resulting cell +sequence). + +02-second-level.ipynb: no diagram per decisions/diagram-survey.md -- check for +the construction-zone pattern; if present, propose Pattern 1b. + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup -- THIS CHAPTER IS NAMED in enumerated item 1: Ch6's own +index.md table likely shows "Stopping Judgment" (title case) against +03-stopping-judgment.ipynb's own current heading "stopping judgment" +(lowercase) -- confirm against the live files and propose the exact corrected +row. Also check whether any OTHER table row in this chapter has drifted from +its own notebook's current heading (01-subsystem-requirements.ipynb's heading +is "level-2 function and logical carrier" as of 2026-10-01 -- confirm the +table matches). Item 2 (separator convention): Ch6 already uses "01:", confirm +no change needed. + +Report format (same as Task 1's own spec): NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE per finding, OPEN QUESTIONS, +INDEX.MD CHECK (propose exact corrected row text for any mismatch found). +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 7: Chapter 7 survey (Execution and Experiments) + +**Files:** none modified. Read: `chapters/ch07-execution/01-calc-energy.ipynb`, `02-state-traces.ipynb`, `03-param-sweep.ipynb`, `index.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch07-execution/ -- read every one of its three +notebooks in full, cell by cell: 01-calc-energy.ipynb, 02-state-traces.ipynb, +03-param-sweep.ipynb. Also read index.md. + +This chapter has NO Pattern-2 whole-dump notebook (confirmed by direct grep, +2026-10-01) -- Pattern 1/1b only. + +02-state-traces.ipynb already has its own state diagrams (base Cycle, plus a +typo-probe negative control, via render_state_flow -- OpenSysML's own CLI) +and its own construction-zone pattern. Propose Pattern 1 for its reflection +print if still present on a fresh read (quote exact replacement). + +01-calc-energy.ipynb and 03-param-sweep.ipynb: no diagram per +decisions/diagram-survey.md -- check each for the construction-zone pattern; +if present, propose Pattern 1b (quote literal replacement code). + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup -- THIS CHAPTER IS NAMED in enumerated item 1: Ch7's own +index.md table entry for 02-state-traces.ipynb was flagged as showing a +curly apostrophe ("the toaster's own operating cycle," with a typographic +apostrophe) where the notebook's own real heading may use a straight one, or +vice versa -- read both the table text and the notebook's own current cell-0 +heading byte-for-byte (do not rely on how your own tool renders the +character; check the raw text) and propose the exact corrected row, matching +whichever form the notebook's own live heading actually uses. Also check the +other two rows (01-calc-energy.ipynb, 03-param-sweep.ipynb) for the same +title-vs-table drift pattern. Item 2 (separator convention): Ch7 already +uses "01:", confirm no change needed. + +Report format (same as Task 1's own spec): NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE per finding, OPEN QUESTIONS, +INDEX.MD CHECK (propose exact corrected row text, byte-for-byte on the +apostrophe question). +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 8: Chapter 8 survey (Checking and Revision) + +**Files:** none modified. Read: `chapters/ch08-checking/01-invariant-def.ipynb`, `02-violation-witness.ipynb`, `03-revision-flow.ipynb`, `index.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch08-checking/ -- read every one of its three +notebooks in full, cell by cell: 01-invariant-def.ipynb, +02-violation-witness.ipynb, 03-revision-flow.ipynb. Also read index.md. + +This chapter has NO Pattern-2 whole-dump notebook -- confirmed directly: +01-invariant-def.ipynb does NOT contain a print(source) call (an earlier, +now-corrected draft of the redesign spec wrongly claimed it did; verify this +for yourself rather than trusting either claim blindly). Pattern 1/1b only. + +01-invariant-def.ipynb has its own structure diagram (model_to_dot(), whole +model) grounding one specific claim (heatGenCheck/rated/weak sibling-usage +and ResistanceCoil's own specialization of HeatGenerator) via a bridge cell +and a caption cell, both already rewritten once this session for accuracy -- +read the current live cells (around cell ids cell-03, cell-03a, cell-03b, +cell-03d, cell-03c as of 2026-10-01, but CONFIRM the real current ids/indices, +they may have shifted) and check specifically for the construction-zone +reflection-print pattern SEPARATELY from this existing diagram work -- does +cell 2's own declare-and-print of heatGenCheck get re-printed again anywhere +as a redundant reflection, independent of the diagram? If so, propose Pattern +1 (quote exact replacement). If the existing diagram cells already fully +occupy the "E" seam role with no separate duplicate print, say so explicitly +-- this notebook may already be in a mostly-correct state from prior fixes +this session, and your job here is to confirm that, not assume more work is +needed. + +02-violation-witness.ipynb, 03-revision-flow.ipynb: no diagram per +decisions/diagram-survey.md -- check each for the construction-zone pattern; +if present, propose Pattern 1b (quote literal replacement code). + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup -- THIS CHAPTER IS NAMED in enumerated items 2 and 3: +(2) Ch8's own index.md table uses "01 - <title>" (dash separator); the spec +recommends switching to "01: <title>" (colon) to match Ch1-7's own majority +convention -- propose the exact corrected table text for all three rows. +(3) chapters/ch08-checking/01-invariant-def.ipynb's own filename and URL slug +still say "invariant-def" even though its heading was already corrected to +"assert constraint" earlier this session (the notebook declares an assert +constraint, not a formal invariant) -- propose a rename (to, e.g., +01-assert-constraint-def.ipynb or similar; your own best proposal, following +exactly the precedent chapters/ch05-architecture/01-model-navigation.ipynb's +own earlier rename already set) and enumerate EVERY file in the repo that +would need its own reference updated (grep for "invariant-def" and +"invariant_def" repo-wide yourself, don't guess which files reference it -- +expect myst.yml at minimum, confirm what else). + +Report format (same as Task 1's own spec): NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE per finding, OPEN QUESTIONS, +INDEX.MD CHECK (propose exact corrected rows for the separator fix), plus a +separate RENAME section listing the proposed new filename and every reference +site found. +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 9: Chapter 10 survey (Traceability and Sign-off) + +**Files:** none modified. Read: `chapters/ch10-traceability-signoff/01-traceability-graph.ipynb`, `02-judgment-synthesis.ipynb`, `03-engineering-signoff.ipynb`, `index.md`. + +- [ ] **Step 1: Dispatch the agent** + +``` +Read docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md in full +first -- specifically "The two target patterns, specified precisely," the +Parsimony heuristic, and "Rolling cleanup, enumerated." This is a READ-ONLY +research task: you make no edits to any file. + +Your chapter: chapters/ch10-traceability-signoff/ -- read every one of its +three notebooks in full, cell by cell: 01-traceability-graph.ipynb, +02-judgment-synthesis.ipynb, 03-engineering-signoff.ipynb. Also read index.md. + +This chapter has NO Pattern-2 whole-dump notebook -- confirmed directly: +01-traceability-graph.ipynb does NOT contain a print(source) call (an +earlier, now-corrected draft of the redesign spec wrongly claimed it did; +verify this for yourself rather than trusting either claim blindly). Pattern +1/1b only. + +01-traceability-graph.ipynb has its own UNSCOPED structure diagram +(model_to_dot(), deliberately whole-model because the chapter's own two +traced chains aren't both reachable from any single containment root) -- +check for the construction-zone reflection-print pattern separately from this +existing diagram work, the same question as Task 8's own Ch8-01 check: does +this chapter's own model-increment cell (if any -- this notebook may be +query/analysis-only with no new construct of its own, confirm by reading it) +duplicate text the diagram or earlier cells already show? If a genuine +construction-zone pattern exists, propose Pattern 1 or 1b as appropriate +(quote exact replacement). If this notebook has no construction-zone pattern +at all (plausible -- it may be purely query-and-trace, not declaring new +SysML), say so explicitly rather than forcing a finding. + +02-judgment-synthesis.ipynb, 03-engineering-signoff.ipynb: no diagram per +decisions/diagram-survey.md -- check each for the construction-zone pattern; +if present, propose Pattern 1b. + +Self-check every piece of proposed replacement text against +tutorial-style-guide/SKILL.md: sentences <=20 words, no literal "—" character, +no metanarration, captions exactly 2 sentences. + +Rolling cleanup -- THIS CHAPTER IS NAMED in enumerated item 2: Ch10's own +index.md table uses "01 - <title>" (dash separator); propose the exact +corrected "01: <title>" text for all three rows, matching Ch1-7's own +convention. + +Report format (same as Task 1's own spec): NOTEBOOK/PATTERN/CELLS IN +SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE per finding, OPEN QUESTIONS, +INDEX.MD CHECK (propose exact corrected rows for the separator fix). +``` + +- [ ] **Step 2: Save the report** + +--- + +## Task 10: Compile the survey document + +**Files:** +- Create: `decisions/diagram-text-integration-survey.md` + +**Interfaces:** +- Consumes: the 9 saved reports from Tasks 1–9 (exact text, not summarized). +- Produces: the committed survey document Phase B's own `writing-plans` invocation reads as its primary input. + +- [ ] **Step 1: Compile the document** + +Structure, matching `decisions/diagram-survey.md`'s own shape: + +```markdown +# Diagram/Text Integration Survey + +Compiled from 9 parallel chapter-survey agents (2026-10-02), per +docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md. +Each chapter section: a short prose strategy paragraph, then a table +(Notebook | Cells | Pattern | Current content | Proposed content | Rationale). + +## Chapter 1: System and Purpose +[paragraph + table, from Task 1's own report, verbatim proposed content] + +## Chapter 2: Requirements and Assumptions +[...] + +[... one section per chapter, Ch1 through Ch8, Ch10 ...] + +## Cross-chapter open questions +[every OPEN QUESTIONS entry from every task, attributed to its chapter, +unresolved -- for Z/the orchestrator to triage before Phase B's own plan +is written] + +## Index.md corrections +[every INDEX.MD CHECK proposed row, by chapter] + +## Proposed rename (Ch8) +[Task 8's own RENAME section, verbatim] +``` + +- [ ] **Step 2: Run the consistency check** + +For every Pattern-1 proposal (construction notebook with an existing diagram): confirm the cited diagram is real by grepping `decisions/diagram-survey.md`'s own table for that notebook. For a sample of at least 3 Pattern-2 proposals (not all — the full check belongs to Phase B's own per-task acceptance criteria): read the real committed `figures/chNN-*.svg` for that chapter and confirm the proposed "residual text" claim is plausible against what the diagram actually draws (its own node/edge `<title>` elements). Flag and correct any inconsistency found before finalizing — do not finalize a known-inconsistent survey. + +- [ ] **Step 3: Commit** + +```bash +git add decisions/diagram-text-integration-survey.md +git commit -m "Compile the diagram/text integration survey (Phase A complete)" +``` + +- [ ] **Step 4: State the next step explicitly** + +Phase A is now complete. The next step — recorded here so it survives a context compaction — is to invoke `superpowers:writing-plans` again, for **Phase B** (implementation), using `decisions/diagram-text-integration-survey.md` (just committed) and `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` as its two inputs. Phase B's own plan will have one task per chapter (or per notebook, where warranted), each a `CONTRACT.md` executed through this repo's own builder/reviewer harness exactly as every Phase 2 chapter task was — builder `claude-sonnet-5`, reviewer `claude-opus-5-5`, a `simulated-learner` spot-check for any notebook whose prose shrank materially, per spec Decision 3 and the Verification section. + +--- + +## Self-review + +**1. Spec coverage.** Decision 1 (scope) → Tasks 1–9 each cover both patterns per chapter. Decision 2 (approach) → the two patterns are specified identically in every task prompt, quoting the spec's own before/after shapes. Decision 3 (harness discipline) → this plan makes zero chapter-content edits; Task 10's own compilation is the only write, and it's the orchestrator's own established administrative role. Decision 4 (enumerated cleanup) → items 1–3 are assigned to the specific tasks that name them (Tasks 5, 6, 7 for item 1; Tasks 8, 9 for item 2; Task 8 for item 3); item 4 (D-037, informational only) is referenced in every task implicitly via the shared spec read. Decision 5 (durability) → Task 10 Step 4 states the next step explicitly, on disk. + +**2. Placeholder scan.** No task says "propose appropriate changes" without the literal prompt text to generate them; every agent prompt is reproduced in full rather than described. The one deliberate exception — proposed replacement TEXT itself is not pre-written in this plan — is correct, not a placeholder: that text is literally what Phase A exists to produce, the same way Phase 1's own agents (not its own plan) produced `decisions/diagram-survey.md`'s own table content. + +**3. Type consistency.** Every task uses the identical report format (`NOTEBOOK/PATTERN/CELLS IN SCOPE/CURRENT CONTENT/PROPOSED CONTENT/RATIONALE`, `OPEN QUESTIONS`, `INDEX.MD CHECK`), so Task 10's own compilation step can process all 9 uniformly. + +**4. Review Focus.** All five items (diagram-exists-check, over-trim-check, skim-risk, style-guide self-check, scope-creep-to-open-question) are addressed as explicit instructions inside every one of the 9 agent prompts, not left to the agents' own judgment alone. + +## Execution handoff + +Plan complete and saved to `docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-a-plan.md`. This plan does not use `superpowers:subagent-driven-development` or `superpowers:executing-plans` — see "Execution mechanism" above. Please review the plan. Does it capture what you want? From 1dc7d6484f08d415aee0e65635227ca6388d7990 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 10:15:08 -0400 Subject: [PATCH 04/25] Compile the diagram/text integration survey (Phase A complete) Nine parallel read-only chapter agents surveyed Ch1-Ch8 and Ch10 against the two target patterns. Orchestrator spot-checked 3 of 5 Pattern-2 proposals against the real committed SVGs (Ch2, Ch4, Ch6) -- all confirmed exact. Eight cross-chapter open questions surfaced, most load-bearing: every proposed fix in this survey contradicts tutorial-style-guide/SKILL.md's own "print TOASTER_INCREMENT as the reflection" rule, which needs one centralized skill-editor-gated fix before Phase B, not independent rediscovery per chapter. Also corrects a factual error found in decisions/diagram-survey.md (ch05's claimed "triple-dump" does not exist in the real files). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --- decisions/diagram-text-integration-survey.md | 488 +++++++++++++++++++ 1 file changed, 488 insertions(+) create mode 100644 decisions/diagram-text-integration-survey.md diff --git a/decisions/diagram-text-integration-survey.md b/decisions/diagram-text-integration-survey.md new file mode 100644 index 0000000..14a282a --- /dev/null +++ b/decisions/diagram-text-integration-survey.md @@ -0,0 +1,488 @@ +# Diagram/Text Integration Survey + +Compiled from 9 parallel chapter-survey agents (2026-10-02), per +`docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md`. Each +chapter section below is a short prose strategy paragraph, then a table +(Notebook | Cells | Pattern | Current content | Proposed content | Rationale). +Literal proposed code/markdown is reproduced from each agent's own report, +not paraphrased. This is Phase A's complete output; Phase B is planned +separately against this document (see "Next step" at the end). + +**Orchestrator consistency-check (Task 10, Step 2):** spot-checked 3 of 5 +Pattern-2 proposals (Ch2, Ch4, Ch6) by grepping the real committed SVGs' +`<title>` elements directly. All three agents' claims about what their +chapter's diagram does and does not draw are confirmed exactly: +- `figures/ch02-structure.svg`: draws `ToastingSystem`, `HeatingSystem`, + `ControlSystem`, `Toaster`, `Toaster::heating`, `Toaster::control`, + `nominal`, `slow`, plus specialization/composition/typing edges. No + `TimelyToast`, no metadata — matches the Ch2 agent's claim exactly. +- `figures/ch04-structure.svg`: draws exactly 5 nodes — `Toaster`, + `Toaster::heating`, `Toaster::control`, `HeatingSystem`, `ControlSystem`. + No `ApplyHeat`, `ToastBread`, item defs, or `ToastingSystem` specialization + — matches the Ch4 agent's claim of a narrow depth-2 scope exactly. +- `figures/ch06-structure.svg`: draws exactly 3 nodes — `HeatingAssembly`, + `HeatingAssembly::heatGen`, `HeatGenerator`. Confirms the Ch6 agent's claim + that this is the narrowest-scoped diagram in the tutorial, and that most + of the chapter's 213-line dump is structurally invisible to it. + +No inconsistency was found in any of the three sampled chapters. The +remaining Pattern-2 proposals (Ch3, Ch5) were not independently re-checked +here, per Task 10's own "spot-check a sample, not all" instruction — each +was independently verified by its own agent against the real files, as +reported below. + +--- + +## Chapter 1: System and Purpose + +No Pattern-2 dump exists in this chapter (confirmed by grep). All four +notebooks have the construction-zone reflection-print duplication; two +(`02-part-def`, `04-composition`) already have a diagram occupying the +correct "After" slot, so the fix is pure deletion. The other two +(`01-abstract-def`, `03-specialization`) have no diagram, but each already +has a `model.find()`/`model.query()` confirmation cell sitting in the right +place in the skeleton, so no new cell needs to be added there either — this +chapter is unusual in that every Pattern-1/1b fix in it is a pure deletion. +One existing seam cell (`04-composition.ipynb`) needs a small rewording +because it quotes the now-removed printed block literally. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `01-abstract-def.ipynb` | cell 8 (`cell-07`) | 1b | `TOASTER_INCREMENT = f"{BREAD_DEF}\n{TOAST_DEF}\n{TOASTBREAD_DEF}\n{TOASTING_SYSTEM_DEF}"`<br>`print(TOASTER_INCREMENT)`<br>`source = Path(...).read_text()`<br>`model = conn.load_from_content(source, strict=False)`<br>`assert model.ok, ...` | Same, with `print(TOASTER_INCREMENT)` line removed. | Each fragment already printed individually at cells 2/4/6. No new confirmation cell needed — cells 12/14 (`model.find()`) already serve as Pattern 1b's required "E" step, and the existing seam cell (16) already points at them, not at the reprint. | +| `02-part-def.ipynb` | cell 6 (`cell-06`) | 1 | `TOASTER_INCREMENT = f"{HEATING_SYS_DEF}\n{CONTROL_SYS_DEF}"`<br>`print(TOASTER_INCREMENT)`<br>...load cell... | Same, print line removed. Bridge cell 11 and diagram cell 12 unchanged — already correctly positioned. | Diagram (`model_to_dot`, two disconnected boxes) already exists at cell 12 and does not need to move. Existing seam cell (16) refers to the still-present individual fragment prints and the cell-10 query, not the removed reprint — no edit needed there. | +| `03-specialization.ipynb` | cell 4 (`cell-04`) | 1b | `TOASTER_INCREMENT = TOASTER_SPEC_DEF`<br>`print(TOASTER_INCREMENT)`<br>...load cell... | Same, print line removed. | Purest duplication in the chapter: identical string printed twice, two cells apart. No diagram exists or is planned (specialization has no `model_to_dot()` representation). Cell 8's `toaster.specializations` query already serves as the confirmation step; seam cell 10 unaffected. | +| `04-composition.ipynb` | cell 8 (`cell-08`); seam cell 18 (`cell-13`) | 1 | Cell 8: `TOASTER_INCREMENT = f"{TOASTER_DEF}\n{CYCLE_TIME_ATTR}\n{HEATING_PART}\n{CONTROL_PART}\n}}"` + print + load. Seam cell 18: "`part def Toaster :> ToastingSystem { ... }` printed above loaded without error, and `toaster.parts()` returns the two part symbols shown below, confirming the composition is now part of the model." | Cell 8: print line removed. Seam cell 18 replaced with: "The assembled `Toaster` declaration loaded without error, and the diagram above confirms `heating` and `control` are part of the model." | Diagram already exists at cell 14 (full composition+typing, depth 2) and does not need to move; bridge cell 13 already correctly positioned. Unlike the other three notebooks, the existing seam cell here quotes the literal closed-brace block only the now-removed print ever showed — it must be reworded to point at the diagram instead, or it becomes a factual error once the print is gone. | + +**Open questions from this chapter:** Figure captions in `02-part-def.ipynb` +(cell 13) and `04-composition.ipynb` (cell 15) are each a single sentence, +not the two `tutorial-style-guide/SKILL.md` requires. Pre-existing, not +touched by either target pattern, not named in the four enumerated cleanup +items — flagged for Z, not fixed here. + +**Index.md check:** No drift. All four rows match their notebooks' live +headings exactly; already uses the `"01:"` separator convention. + +--- + +## Chapter 2: Requirements and Assumptions + +One Pattern-2 notebook (`03-judgment-context.ipynb`) and two Pattern-1b +notebooks. The chapter's diagram (whole-model, unscoped) covers all +structural content but cannot show the requirement's constraint body, the +attribute override value, or any judgment-record metadata — those stay as a +small residual excerpt. Both Pattern-1b fixes also require small rewordings +of downstream seam sentences that currently quote the exact closed-brace +block only the removed print produced. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `03-judgment-context.ipynb` | cell 2 | 2 | `print(source)` — full 55-line `models/ch02-cumulative.sysml` dump (spec's "~45 lines" estimate is stale; confirmed 55 as of 2026-10-02). | ```python\nrequirement_block = source[source.index("requirement def"):source.index("part nominal")].strip()\noverride_line = next(l.strip() for l in source.splitlines() if "attribute :>> cycleTime" in l)\nprint(requirement_block)\nprint(override_line)\n``` (verified by direct execution against the real file) | Diagram (whole-model `model_to_dot`) shows every structural fact already. Only the `TimelyToast` requirement's `require constraint` body (lines 36-45) and the `cycleTime` override value (line 53) are in the dump, outside the diagram's reach, and not reprinted elsewhere in the notebook. The metadata tag text is excluded from the residual because it's already reprinted verbatim later (cells 8/10) — keeping it in cell 2 too would just move the double-print earlier. | +| `01-requirement-def.ipynb` | cell 8; seam cell 13 | 1b | Cell 8: `TOASTER_INCREMENT = f"{TIMELY_TOAST_REQ}{CONSTRAINT_BODY}\n}}\n{NOMINAL_PART}"` + print + load. Seam cell 13 quotes the full assembled, closed-brace requirement block as "printed above." | Cell 8: print removed. Seam cell 13: "The `TimelyToast` fragments printed above loaded without error, and `model.find()`/`model.query()` confirm it's now part of the model." (17 words) | `TIMELY_TOAST_REQ`/`CONSTRAINT_BODY`/`NOMINAL_PART` each already printed individually (cells 2/4/6); existing cell 12 `model.find()`+`model.query()` already serves as the Pattern 1b confirmation. Seam cell needs rewording because it quotes a single closed-brace block only the removed print ever assembled — neither underlying fragment has the closing brace on its own. | +| `02-assumptions.ipynb` | cell 6; seam cell 11 | 1b | Cell 6: `TOASTER_INCREMENT = f"{SLOW_PART}\n{CYCLE_OVERRIDE}\n}}"` + print + load. Seam cell 11 quotes the full closed-brace `slow` block as "printed above." | Cell 6: print removed. Seam cell 11: "The `slow` fragments printed above loaded without error, and `slow.attributes()` confirms the override is now part of the model." (19 words) | Same shape as `01-requirement-def.ipynb`: existing cell 10 `model.find()` + `slow.attributes()` already serves as confirmation; seam cell needs the same kind of reword for the same reason (quotes a block only the removed print produced). | + +**Open questions from this chapter:** A genuine conflict between two skills +— `toaster-recipe/SKILL.md` says judgment/analysis notebooks have no +construction zone and never assign `TOASTER_INCREMENT`, while +`toaster-review-protocol/SKILL.md`'s own "judgment record construction zone" +section explicitly prescribes building and printing a `TOASTER_INCREMENT` +fragment for a judgment record's model-side anchor tag. +`03-judgment-context.ipynb`'s cells 8-12 do exactly this, and that reflection +print is structurally identical to the Pattern 1/1b duplication this +redesign targets — but was *not* flagged as a fix target by this task's own +scope, since it is a judgment-record notebook under the second skill's +sanctioned pattern. Whether this double-print is a deliberate, sanctioned +exception or itself a defect requiring a Pattern-1b fix is a question this +survey surfaces but does not resolve — it requires a `skill-editor`-gated +decision about which skill's rule governs, before Phase B can touch it. + +**Index.md check:** No drift. All three rows match; already uses `"01:"`. + +--- + +## Chapter 3: Measures of Success + +One Pattern-2 notebook (`03-threshold-judgment.ipynb`) and three Pattern-1b +notebooks, all four fixes being pure deletions since every notebook already +has its own confirmation query in place. A second, independent double-print +was found inside the Pattern-2 notebook itself, not originally named in this +chapter's task scope. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `03-threshold-judgment.ipynb` | cell 2 | 2 | `print(source)` — full 81-line `models/ch03-cumulative.sysml` dump (spec's "83 lines" is stale; confirmed 81 as of 2026-10-02). | ```python\nlines = source.splitlines()\nexcerpt = "\n".join(lines[35:47] + [" ..."] + lines[61:65] + [" ..."] + lines[66:80])\nprint(excerpt)\n``` — 30 real lines instead of 81. | Diagram (parts-only) draws only the Toaster/HeatingSystem/ControlSystem/nominal/slow skeleton. Residual: the `TimelyToast` requirement definition + usage (lines 36-47), the `slow` override + folded satisfy claim (lines 62-65), and `TimelyToastTest` (lines 67-80) — none diagrammable, confirmed against both the real SVG and `model_to_dot()`'s own node-kind logic. | +| `03-threshold-judgment.ipynb` (second finding, same notebook) | cell 13 | 1b | `TOASTER_INCREMENT = AS_C03_TAG`<br>`print(TOASTER_INCREMENT)` | Print line removed. | `AS_C03_TAG` already printed in full two cells earlier (cell 11) — a second, independent double-print inside the same whole-dump notebook, not named in the original task scope. `AS_C03_TAG` is a `MetadataUsage`, invisible to `model.find`/`model.query`; the real confirmation already exists at cell 23 (`get_review_record_refs`), narrated by cell 24. | +| `01-moe-definition.ipynb` | cell 11 | 1b | `TOASTER_INCREMENT = f"{TIMELY_USAGE}\n{AC_C03_TAG}"`<br>`print(TOASTER_INCREMENT)` | Print line removed. | `TIMELY_USAGE` confirmed at cell 6 (`model.find`+`model.query`); `AC_C03_TAG` is metadata, confirmed instead at cell 23 via `get_review_record_refs` — this tutorial's established idiom for metadata tags. No new cell needed. | +| `02-mop-candidate-eval.ipynb` | cell 4 | 1b | `TOASTER_INCREMENT = SLOW_WITH_CLAIM`<br>`print(TOASTER_INCREMENT)` + load | Print line removed. | `assert ... satisfy` is invisible to both `model.find`/`model.query` and `model_to_dot()`. Real confirmation already exists at cell 8 (`satisfy_relationships` + `model.eval()`), narrated by seam cell 10. | +| `04-verification-case.ipynb` | cell 10 | 1b | `TOASTER_INCREMENT = f"{VERIF_DEF_OPEN}\n{DOC_COMMENT}\n{SUBJECT_DECL}\n{OBJECTIVE_BODY}\n}}"` + print + load | Print line removed. | `VerificationCaseDefinition` is queryable; cell 14 already does `model.find()`+`model.query()`, narrated by seam cell 15 — the cleanest instance in the chapter, no API limitation involved. | + +**Open questions from this chapter:** None beyond the second double-print +finding folded into the table above (flagged there so it isn't lost between +survey and Phase B planning — recommend the Ch3 Phase B contract name both +`01-moe-definition.ipynb` cell 11 and `03-threshold-judgment.ipynb` cell 13 +explicitly). The design spec's own stated line count for this notebook's +dump (83) is off by two against the real file (81); use 81 in Phase B. + +**Index.md check:** No drift. All four rows match; already uses `"01:"`. + +--- + +## Chapter 4: Functional Decomposition + +One Pattern-2 notebook (`03-completeness-check.ipynb`) and two Pattern-1 +notebooks (both chapter diagrams already correctly positioned). A second, +unnamed construction-zone double-print was found in the Pattern-2 +notebook's own judgment-tag cells, raising a classification question for +Phase B. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `01-action-def-ffbd.ipynb` | cell 14 | 1 | `TOASTER_INCREMENT = f"{APPLY_HEAT_DEF}\n{TOASTBREAD_REOPENED}"` + print + load. Cells 15/16 (bridge + diagram) already present, unchanged. | Print line removed; cells 15/16 untouched. | Diagram renders `ToastBread` (not `ApplyHeat` — confirmed against the real cell and SVG; an earlier spec draft mis-stated this). Bridge+diagram pair already in the correct "After" position. Downstream cell 23's "printed above" claims resolve to cells 10/12, unaffected. | +| `02-heating-refinement.ipynb` | cell 8 | 1b | `TOASTER_INCREMENT = f"{START_DEF}\n{FINISH_DEF}\n{CANCEL_DEF}"` + print + load | Print line removed. | No diagram exists or is planned. Existing cell 12 (`model.find()` loop over `Start`/`Finish`/`Cancel`) already serves as the Pattern 1b confirmation. Cell 13's "printed above" claim resolves to cells 2/4/6, unaffected. | +| `03-completeness-check.ipynb` | cell 2 | 2 | `print(source)` — full 117-line `models/ch04-cumulative.sysml` dump. | ```python\nlines = source.splitlines()\nnew_this_chapter = "\n".join(lines[16:32] + lines[37:47] + lines[107:116])\nprint(new_this_chapter)\n``` — 35 lines. | Scoped diagram (depth-2, rooted at `Toaster`) draws only `{Toaster, heating, control, HeatingSystem, ControlSystem}` — confirmed against the real SVG. Residual: `ApplyHeat` (17-32), `ToastBread`'s reopened body (38-47), the three item defs (108-116) — none drawn by `model_to_dot()`. The `aiC04Tag` metadata is excluded from the residual because the same notebook's own cells 9-11 reprint it moments later (see open question below). | +| `03-completeness-check.ipynb` (additional finding, same notebook) | cells 9-11 | — (flagged, not fixed; see open question) | Cell 9 declares+prints `AI_C04_TAG`; cell 11 sets `TOASTER_INCREMENT = AI_C04_TAG` and reprints it verbatim. | Not proposed — classification question, see below. | Structurally identical to the Pattern 1/1b duplication elsewhere, but prior planning docs (`decisions/declarative-construction-plan.md`) list this notebook as having no construction cells at all, since it's a judgment notebook. Whether it counts as in-scope under this redesign is a call for Z/the orchestrator, not this survey. | + +**Open questions from this chapter:** (1) The cells 9-11 classification +question above. (2) `01-action-def-ffbd.ipynb` cell 17's existing caption is +one sentence, not two — pre-existing, outside this task's scope, flagged +only. (3) `03-completeness-check.ipynb` cell 3's bridge sentence has the same +single-sentence-with-colon style issue — remains factually accurate after +the trim, no edit required for correctness. + +**Index.md check:** No drift. Both diagrams already named explicitly in the +table (per DL-089's earlier fix); confirmed still accurate. + +--- + +## Chapter 5: Architecture and Allocation + +One Pattern-2 notebook (`01-model-navigation.ipynb`, whose diagram is +unscoped and covers the dump's structural content completely — the only +chapter where the residual is genuinely empty) and two Pattern-1/1b +construction-zone fixes. **This chapter's survey also corrects a factual +error in `decisions/diagram-survey.md` itself**: that document's claim that +`02-allocate.ipynb` and `03-interfaces.ipynb` each separately re-print the +full 131-line dump does not match the real files, confirmed both by direct +read and by checking the historical commit that produced that document. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `01-model-navigation.ipynb` | cell 2 | 2 | `print(source)` — full 131-line `models/ch05-cumulative.sysml` dump. | Delete the `print(source)` line entirely. **Residual: none.** | Diagram is unscoped (whole-model `model_to_dot`), confirmed by direct comparison to draw every structural fact the dump contains. The notebook's own narrow teaching purpose (`model.find()`/`model.get()` navigation) doesn't need any of the non-structural content (action bodies, port/interface/allocation/requirement text) the diagram omits — that content belongs to the chapters that already taught it. Cell 1's own prose already summarizes what's new in prose form. | +| `02-allocate.ipynb` | cell 6 | 1b | `TOASTER_INCREMENT = f"{HEATING_SYSTEM_DEF}\n{TOASTER_WITH_ALLOCATION}"` + print + load | Print line removed (`# assembled, not printed` comment optional). | No diagram exists for allocation views. Existing cell 10 (`find_allocations`/`perform_relationships`) already serves as the Pattern 1b confirmation, narrated by seam cell 12 — which needs its "definitions printed above" phrase updated once the print is gone (left to Phase B, since exact wording depends on final cell numbering). | +| `03-interfaces.ipynb` | cell 10 | 1 | `TOASTER_INCREMENT = (f"{DURATION_PORT_DEF}\n{HEATING_SYSTEM_PORT}\n{CONTROL_SYSTEM_PORT}\n{TOASTER_WITH_INTERFACE}")` + print + load | Print line removed. | Diagram (`render_toolkit_interconnection`, the conjugated-port figure) already exists at cell 16, confirmed unaffected. Existing cell 14 (`port_type_mismatches`) already serves as confirmation, narrated by seam cell 18 — same "printed above" wording issue as `02-allocate.ipynb`, left to Phase B. | + +**Open questions from this chapter (major):** `decisions/diagram-survey.md`'s +own row claiming `02-allocate.ipynb` cell 6 and `03-interfaces.ipynb` cell 10 +each re-print the same 131-line dump as `01-model-navigation.ipynb` does not +match the real files — both cells only ever print their own small +`TOASTER_INCREMENT` fragment (9 and ~15 lines respectively), never the full +131-line `source`. Confirmed both against the live notebooks and against +`git show` of the commit that produced `diagram-survey.md`, so this is a +factual error in that prior document, not later drift. There is no +"triple-dump" to remove — the real, present issue in these two cells is the +ordinary construction-zone double-print already captured in the table above. +Flagging for Z/the orchestrator; no action needed beyond what's already +proposed. + +**Index.md check:** Confirmed mismatch — `index.md` line 17 says +`[01: Model Navigation]` (title case) against the notebook's live heading +`# model navigation` (lowercase). Proposed corrected row: +``` +| [01: model navigation](01-model-navigation.ipynb) | Navigate model elements by qualified name using `model.find()` and `model.get(fqn)`. | +``` +Separator convention (`"01:"`) already correct, no change needed. + +--- + +## Chapter 6: Recursive Decomposition + +One Pattern-2 notebook (`03-stopping-judgment.ipynb`, the single largest cut +in the whole tutorial — 213 lines down to 66) and one Pattern-1 fix. A +second, smaller Pattern-1b instance was found inside the same Pattern-2 +notebook. This chapter's survey also surfaces the clearest version of a +cross-chapter skill conflict already touched on by Chapter 2 and Chapter 5's +findings: `tutorial-style-guide/SKILL.md` has a hard rule requiring +`TOASTER_INCREMENT` to be printed as the reflection, which every Pattern 1/1b +fix in this entire survey directly contradicts. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `03-stopping-judgment.ipynb` | cell 2; markdown wrap-up cell 3 | 2 | Cell 2: `print(source)` — full 213-line `models/ch06-cumulative.sysml` dump (the densest block in the tutorial). Cell 3 (markdown) names 5 facts as "printed above." | Cell 2: ```python\nlines = source.splitlines()\nprint("\n".join(lines[137:164] + lines[173:212]))\n``` — 66 lines (down from 213). Cell 3 reworded to: "HeatGenerator, EnergyPort, HeatGenerationReq, ResistanceCoil, rated and weak loaded without error, and the diagram confirms HeatingAssembly composing heatGen, typed by HeatGenerator. The next cell checks what happens when an inference record's own required field is left empty." | Scoped diagram reaches only `{HeatingAssembly, heatGen, HeatGenerator}` (confirmed against the real SVG and `containment_subgraph`'s own test suite). ~137 of 213 lines are an exact, byte-identical repeat of Chapter 5's own already-printed cumulative model — the largest single redundancy found in this survey, independent of what the diagram can or can't show. Residual: `EnergyPort`, `GenerateHeat`, `HeatGenerator`'s doc/attributes, `HeatGenerationReq`, `ResistanceCoil`'s doc/attributes, and `rated`/`weak` with their overrides — none diagrammable. Cell 3 must be reworded because it names facts (e.g. the allocation) the trimmed print no longer shows. | +| `01-subsystem-requirements.ipynb` | cell 14 | 1 | `TOASTER_INCREMENT = (f"{GENERATE_HEAT_DEF}\n{ENERGY_PORT_DEF}\n{APPLY_HEAT_INCREMENT}\n{HEAT_GENERATOR_DEF}\n{HEATING_ASSEMBLY_DEF}")` + print + load | Print line removed. | Two diagrams (action-flow + interconnection) already sit immediately after in the correct position. Fragments already individually printed at cells 2/4/6/8/10. Cell 20's "printed above" claim resolves to those fragment prints, unaffected. | +| `03-stopping-judgment.ipynb` (second finding, same notebook) | cell 11 | 1b (flagged, not pre-decided) | `TOASTER_INCREMENT = AI_C06_TAG`<br>`print(TOASTER_INCREMENT)` | Proposed, if adopted: print line removed (assignment kept — required by `scripts/check_construction.py`). | Reprints text already shown two cells earlier (cell 9); cell 10's markdown already calls this duplication "deliberate." Not named in the spec's five-notebook Pattern-2 list — flagged as a genuine but previously-unnamed finding, not fixed unilaterally. Confirmation already exists at cell 22 (`get_review_record_refs`). | + +**Open questions from this chapter (major, cross-chapter):** +`tutorial-style-guide/SKILL.md`'s own "Construction cells" section states as +a hard rule: *"`TOASTER_INCREMENT` is assembled... Print it as the +reflection."* This is the exact line every Pattern 1/1b fix in this entire +survey (all 9 chapters) contradicts. This is not a Ch6-specific issue — it +needs one centralized `skill-editor`-gated update to that skill line, done +once before or alongside Phase B, rather than left to drift notebook by +notebook. Also: whether to trim the `assumption_refs` text in cell 16, which +already supports the Pattern-2 trim rather than conflicting with it — a +reviewer should confirm it reads naturally post-trim. + +**Index.md check:** Confirmed mismatch, all three rows (not just the one +named in the task prompt) — title case vs. lowercase live headings: +``` +| [01: level-2 function and logical carrier](01-subsystem-requirements.ipynb) | ... | +| [02: level-2 physical realization](02-second-level.ipynb) | ... | +| [03: stopping judgment](03-stopping-judgment.ipynb) | ... | +``` +Separator convention already correct (`"01:"`), no change needed. + +--- + +## Chapter 7: Execution and Experiments + +No Pattern-2 dump (confirmed by grep). One Pattern-1 fix (diagram already +correctly positioned) and one Pattern-1b fix requiring one new confirmation +line, since this chapter has no existing query to reuse for one of its two +fragments. The third notebook has no construction zone at all. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `02-state-traces.ipynb` | cell 16 | 1 | `TOASTER_INCREMENT = f"{CYCLE_DEF}\n{TOASTING_SYSTEM_INCREMENT}"` + print + load | Print line removed; cells 17/18 (bridge + diagram) unchanged. | `CYCLE_DEF`/`TOASTING_SYSTEM_INCREMENT` already printed individually (cells 12/14). Bridge+diagram pair (state-flow render) already correctly positioned. Cell 31's "definitions printed above" phrase resolves to the individual fragment prints, unaffected. | +| `01-calc-energy.ipynb` | cell 9; markdown cell 10 | 1b | `TOASTER_INCREMENT = f"{HEAT_GENERATOR_INCREMENT}\n{RATED_INCREMENT}"` + print + load. Cell 10: two sentences about the negative control. | Cell 9: print removed; one line added: `delivered_energy = model.find("ToasterDemo::HeatGenerator::deliveredEnergy")`<br>`print(f"HeatGenerator::deliveredEnergy: kind={delivered_energy.kind!r}, id={delivered_energy.id!r}")`. Cell 10: one sentence prepended: "`HeatGenerator::deliveredEnergy` is now part of the loaded model, confirmed by `model.find`." (11 words) | Unlike every other Pattern-1b fix in this survey, this notebook has no existing confirmation query to reuse — a new `model.find()` cell (reusing `02-state-traces.ipynb`'s own established idiom) must be added, plus one markdown sentence interpreting it, per the style guide's narration-density rule. | +| `03-param-sweep.ipynb` | — | none | No construction zone at all — confirmed by direct read; cell 2 loads the cumulative model directly, no fragment-declaration cells precede it. | No change. | Matches `toaster-recipe`'s own rule that param-sweep notebooks have no construction zone. | + +**Open questions from this chapter:** (1) Two intermediate sub-assembly +reprints exist (`02-state-traces.ipynb` cell 12, `01-calc-energy.ipynb` cell +7) that are not the *final* `TOASTER_INCREMENT` reflection either target +pattern defines — flagged, not proposed, since they're outside the spec's +named scope. (2) Three real em-dash violations found in +`02-state-traces.ipynb` (cells 29, 32) — outside this task's scope, flagged +for Z. (3) The rolling-cleanup item 1 premise (a curly-vs-straight apostrophe +drift in this chapter's `index.md`) does not hold on direct byte-level +inspection — 0 curly apostrophes found anywhere in the file; recommend +confirming with Z whether this was already fixed or conflated with Ch5/Ch6's +actual (different) title-case defect. + +**Index.md check:** No correction needed — confirmed byte-for-byte match +between all three table rows and their notebooks' live headings (apostrophe +form included). Separator convention already correct. + +--- + +## Chapter 8: Checking and Revision + +No Pattern-2 dump (confirmed directly; an earlier spec draft wrongly claimed +one existed here). The chapter's one diagram (grounding a specific +sibling-usage/specialization claim) is already correct and untouched. Two +Pattern-1b fixes, both pure deletions. This chapter is also named in two of +the four enumerated rolling-cleanup items: the index.md separator convention +and the `01-invariant-def.ipynb` filename rename. + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `01-invariant-def.ipynb` | cell-08 | 1b | `TOASTER_INCREMENT = f"{HEAT_GEN_CHECK_USAGE}\n{CHECK_DURATION_ATTR}\n\n{DELIVERED_ENERGY_BOUND}\n"` + print + load | Print line removed. | Diagram cells (cell-03a/03b/03d) ground an earlier, separate claim and are already correct — no change needed there. This reflection print is independent of them. Existing cell-09/cell-10 (`model.find()`+`model.query()`) already serves as the Pattern 1b confirmation. | +| `02-violation-witness.ipynb` | cell-20 | 1b | `TOASTER_INCREMENT = AS_C08_TAG`<br>`print(TOASTER_INCREMENT)` | Print line removed (bare deletion; no new confirmation inserted — see open question). | `AS_C08_TAG` already printed at cell-18. Confirmation exists later at cell-32/33 (`get_review_record_refs`); inserting a nearer one would be premature (the record it anchors isn't built yet) and would itself be a third printing. | +| `03-revision-flow.ipynb` | — | none | No construction zone — confirmed by grep (`TOASTER_INCREMENT` appears zero times). | No change. | Matches `toaster-recipe`'s own rule for analysis notebooks (rebuilds a Python `ReviewRecord`, no new model element). | + +**Open questions from this chapter:** Whether `02-violation-witness.ipynb` +should get a nearer confirmation query right after the trimmed cell-20, +matching `01-invariant-def.ipynb`'s immediate-confirmation idiom more +literally, instead of relying on the later cell-32/33 confirmation — the +agent recommends relying on the existing later one (parsimony), but flags it +as a reviewer judgment call. + +**Index.md check (rolling-cleanup item 2):** Proposed, dash → colon +separator for all three rows, with row 1's link target updated for the +proposed rename: +``` +| [01: assert constraint](01-assert-constraint-def.ipynb) | State `deliveredEnergyBoundedBySupply` as a real SysML constraint; confirm it is really in the loaded model. | +| [02: proof versus point evaluation](02-violation-witness.ipynb) | Contrast `verify_holds()`'s universal proof with `verify_satisfaction()`'s point evaluation; show the loop catching a fully broken variant as `violated` and a merely weakened variant as `undecided`; record the proof as engineering evidence with its own real limits stated. | +| [03: stale record detection](03-revision-flow.ipynb) | Loosen the lemma's own bound; show `check_stale()` marking the existing record for re-review. | +``` + +--- + +## Chapter 10: Traceability and Sign-off + +No Pattern-2 dump (confirmed directly; an earlier spec draft wrongly claimed +one existed here, same as Ch8). One narrow, non-canonical instance of the +underlying duplication concern was found, not matching either pattern's +literal shape. The chapter's own unscoped structure diagram is unaffected. +This chapter is named in rolling-cleanup item 2 (separator convention). + +| Notebook | Cells | Pattern | Current content | Proposed content | Rationale | +|---|---|---|---|---|---| +| `01-traceability-graph.ipynb` | cell 33 (delete); cell 32 (one-word edit) | "1b-style" (does not match either pattern's literal before/after shape — flagged for Phase B scoping, see open question) | Cell 32 (markdown), last sentence: "The subsetting construct below is how that is stated." Cell 33 (code): `print(ENERGY_CONSERVATION_REQ_DEF)` — a verbatim reprint of cell 27's own fragment, with the real confirmation query (cells 35-36) already in place immediately after. | Cell 32 last sentence: "The subsetting construct shown above is how that is stated." Cell 33: deleted outright. | This notebook doesn't follow the canonical construction-zone shape at all (model loaded once at the top, before any construction narrative; `TOASTER_INCREMENT`, assigned at cell 39, is never printed) — so Pattern 1/1b's literal shape doesn't apply. But cell 33 is a real instance of the same underlying concern: a pure narrative recap of text already shown five cells earlier, immediately before a real confirmation query (cells 35-36) that already does the job. Fix is pure deletion, stricter than Pattern 1b's add-a-query default, since a query already exists. | +| `02-judgment-synthesis.ipynb` | — | none | No construction zone — confirmed by grep. | No change. | Judgment/reconstruction notebook, reconstructs Python `ReviewRecord` objects from earlier chapters; no new model content. | +| `03-engineering-signoff.ipynb` | — | none | No construction zone — confirmed by grep. | No change. | Synthesizes one new `ReviewRecord` from citations; judgment-record-only construction (name fields, narrate, print once each), not a model-construction zone with a reflection-print problem. | + +**Open questions from this chapter:** Whether the cell-33 finding (above) +counts as in-scope for a Phase B task under the spec's Decision 2 wording, +given it doesn't match Pattern 1/1b's literal shape, or whether it should be +folded into Phase B's acceptance criteria as an explicitly-named extra item +(the same mechanism already used for the four enumerated cleanup items). + +**Index.md check (rolling-cleanup item 2):** Proposed, dash → colon +separator for all three rows (concept-column prose untouched): +``` +| [01: traceability graph](01-traceability-graph.ipynb) | ... | +| [02: judgment ledger](02-judgment-synthesis.ipynb) | ... | +| [03: engineering synthesis](03-engineering-signoff.ipynb) | ... | +``` + +--- + +## Cross-chapter open questions + +For Z/the orchestrator to triage before Phase B's own plan is written: + +1. **A skill contradiction that blocks every proposed fix in this survey.** + `tutorial-style-guide/SKILL.md`'s "Construction cells" section states a + hard rule: *"`TOASTER_INCREMENT` is assembled from the fragment + variables... Print it as the reflection."* Every single Pattern-1/1b fix + proposed across all 9 chapters above removes that print. This needs one + centralized `skill-editor`-gated update, decided once, before or + alongside Phase B — not left implicit or discovered independently by + each chapter's Phase B contract. (Surfaced independently by the Ch2, Ch5, + and Ch6 agents.) + +2. **A second, related skill contradiction, narrower in scope.** + `toaster-recipe/SKILL.md` says judgment/analysis notebooks have no + construction zone and never assign `TOASTER_INCREMENT`, while + `toaster-review-protocol/SKILL.md` explicitly prescribes building and + printing a `TOASTER_INCREMENT` fragment for a judgment record's + model-side anchor tag — and several real notebooks + (`ch02/03-judgment-context`, `ch03/01-moe-definition` and + `03-threshold-judgment`'s own tag cells, `ch04/03-completeness-check` + cells 9-11, `ch06/03-stopping-judgment` cell 11, `ch08/02-violation-witness`, + `ch10/01-traceability-graph`) do exactly this. Whether these + judgment-tag reflection prints are a deliberate, sanctioned exception or + themselves a Pattern-1b-style defect is a single, cross-cutting + classification question — not something to resolve chapter by chapter. + (Surfaced by Ch2's agent; related instances independently found by Ch3, + Ch4, Ch6, Ch8, and Ch10's agents without being asked to look for this + specific pattern.) + +3. **`decisions/diagram-survey.md` contains a factual error.** Its own row + for `ch05/02-allocate.ipynb` and `03-interfaces.ipynb` claims both + notebooks re-print the full 131-line cumulative-model dump, "no candidate + ... diagram fatigue, not a real reduction." This does not match the real + files (confirmed both by direct read and by checking the historical + commit that produced that document) — both cells only ever print their + own small `TOASTER_INCREMENT` fragment. There is no triple-dump to + remove. Recommend correcting this row in `decisions/diagram-survey.md` + itself as a small, separate administrative fix (not a chapter-content + edit), distinct from anything Phase B needs to do. + +4. **Three line-count figures in the governing spec are stale**, confirmed + against the real files as of 2026-10-02: Ch3's dump is 81 lines (spec + says 83); Ch2's dump is 55 lines (spec says "~45"). Use the real counts + in Phase B, not the spec's. + +5. **A classification question for `ch04/03-completeness-check.ipynb` cells + 9-11.** This notebook's judgment-tag reflection print (`AI_C04_TAG`) is + structurally identical to the duplication this redesign targets, but + prior planning documents (`decisions/declarative-construction-plan.md`) + explicitly list this notebook as having no construction cells at all. + Overlaps with cross-chapter item 2 above but is called out separately + since it also bears on whether this notebook is a "construction + notebook" under the original declarative-construction plan's own + classification. + +6. **`ch06/03-stopping-judgment.ipynb` cell 11** has a second, smaller + Pattern-1b-shaped duplication (`AI_C06_TAG` reprinted two cells after its + own fragment print) that was not named in the spec's five-notebook + Pattern-2 list. Proposed fix is included in the Ch6 table above but + flagged, not pre-decided, consistent with cross-chapter item 2. + +7. **`ch10/01-traceability-graph.ipynb` cell 33** (see Ch10 table) is a real + instance of the underlying duplication concern that matches neither + pattern's literal before/after shape. Recommend folding it into Phase B's + Ch10 task as an explicitly-named extra item, the same mechanism already + used for the four enumerated cleanup items. + +8. **Minor, out-of-scope items flagged by individual agents, not acted on:** + single-sentence figure captions in `ch01/02-part-def.ipynb` (cell 13), + `ch01/04-composition.ipynb` (cell 15), and `ch04/01-action-def-ffbd.ipynb` + (cell 17) — `tutorial-style-guide/SKILL.md` requires exactly two + sentences; three real em-dash violations in `ch07/02-state-traces.ipynb` + (cells 29, 32); and the premise of rolling-cleanup item 1 (a curly vs. + straight apostrophe drift in Ch7's own `index.md`) does not hold on + direct inspection — recommend confirming with Z whether this was already + fixed or conflated with Ch5/Ch6's actual (different) title-case defect. + +--- + +## Index.md corrections + +Separator-convention fix (`"01 -"` → `"01:"`), rolling-cleanup item 2 — Ch8 +and Ch10 (full rows given in their own chapter sections above). Heading-case +sync fix, rolling-cleanup item 1 — Ch5 (one row) and Ch6 (all three rows, +given in their own chapter sections above). Ch1, Ch2, Ch3, Ch4, and Ch7 need +no index.md correction — confirmed already accurate by direct read. + +--- + +## Proposed rename (Ch8) + +**Proposed new filename:** `chapters/ch08-checking/01-assert-constraint-def.ipynb` +(renamed from `01-invariant-def.ipynb`), following the exact precedent of +the Ch5 rename (`01-concept-selection.ipynb` → `01-model-navigation.ipynb`, +commit `0b3151b`). The notebook's own H1 heading already reads "assert +constraint"; this matches the repo's own `-def`-suffix convention for +notebooks that declare a specific SysML construct type +(`01-abstract-def.ipynb`, `01-requirement-def.ipynb`, +`01-action-def-ffbd.ipynb`). + +**Files needing their reference updated if the rename proceeds** (confirmed +by direct repo-wide grep for `invariant-def`/`invariant_def`; the latter had +zero hits anywhere): + +1. `myst.yml` line 67 — TOC entry. +2. `chapters/ch08-checking/index.md` line 17 — Ingredients-table link (shown + fixed in the Ch8 section above). +3. `chapters/ch08-checking/02-violation-witness.ipynb`, cell-01 — cross-reference + link target only (`[Ch8-01](01-invariant-def.ipynb)` → + `[Ch8-01](01-assert-constraint-def.ipynb)`); surrounding sentence + untouched. +4. `exercises/ch08/exercise.ipynb` line 28 — prose referencing the notebook + by path. +5. `scripts/check_construction.py` line 280 — active code registry entry; + would silently stop checking the renamed file if not updated. +6. `DEFERRED.md` lines 693 and 798 — live, currently-accurate D-029/D-030/D-031 + workaround notes that point at this file by path. + +**Historical-record files found but NOT recommended for update** (per the +same convention the Ch5 rename precedent established): `decisions/diagram-survey.md` +line 219; `decisions/log.md` lines 892, 903, 1093, 1225, 1239; +`decisions/audits/ch08-layer-audit.md` lines 140, 240 (the record that +recommended this very rename — correctly worded in the past tense already); +`decisions/user-testing-grid/M2-practitioner.md` line 17; +`docs/superpowers/plans/2026-10-01-diagram-survey-phase2-plan.md` lines 819, +825, 832, 839. + +**Ambiguous, flagged for the orchestrator's own call, not pre-decided:** +`docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-a-plan.md` +(this very Phase A plan, which names the old filename throughout) and +`docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` (the +governing spec, which also names it). The surveying agent recommends leaving +both as-is — they are records of what Phase A was asked to find under the +old name, not live links requiring resolution — but flags the call as the +orchestrator's to make, not its own. + +**Total:** 6 live files need updating, plus the file itself (7 touched). +5 files are historical and should be left alone. 2 files are ambiguous. + +--- + +## Next step + +Phase A is now complete. Per this survey's own governing plan +(`docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-a-plan.md`, +Task 10 Step 4), the next step is to invoke `superpowers:writing-plans` +again, for **Phase B** (implementation), using this document and +`docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` as +its two inputs. Phase B's own plan will have one task per chapter (or per +notebook, where warranted), each a `CONTRACT.md` executed through this +repo's own builder/reviewer harness exactly as every Phase 2 chapter task +was — builder `claude-sonnet-5`, reviewer `claude-opus-5-5`, a +`simulated-learner` spot-check for any notebook whose prose shrank +materially, per spec Decision 3 and the Verification section. Phase B's own +plan must also resolve, or explicitly route to the ACE/Z, the 8 cross-chapter +open questions above before any chapter's own contract is dispatched — +especially open questions 1 and 2, since they affect the exact wording of +nearly every proposed fix in this document. From 2507ed67302d6857748ba9367a56263b647cf597 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 10:35:24 -0400 Subject: [PATCH 05/25] DL-092/DL-093 (PENDING): ACE rulings on the two diagram-survey skill conflicts Both the construction-zone reflection print and the judgment-record tag reprint are ruled to be the same defect this redesign already targets, not sanctioned exceptions. Both edits trip skill-editor's own multi-archetype escalation row regardless of the ACE's ruling on the substance, so both entries stay PENDING until Z confirms the exact replacement wording. No skill file has been touched. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --- decisions/log.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/decisions/log.md b/decisions/log.md index a30c352..1f172cc 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1258,3 +1258,92 @@ Revert record (verbatim, the exact text immediately surrounding the insertion po ``` Reasoning: this is the direct follow-up DL-090 itself named as a required next step -- the H1+short_title convention is real (independently verified across four review rounds) and completely undocumented in the one skill a builder or reviewer would actually consult before touching a notebook's own cell 0; leaving it undocumented reintroduces DL-090's own bug the next time anyone writes `##` instead of `#` without knowing why it matters. Post-edit check: added one short paragraph after the skeleton table (`.claude/skills/toaster-recipe/SKILL.md`, the exact text quoted above in the revert record) stating the H1 + `short_title` requirement, citing DL-090; added one clause to the A6 checklist's existing "Concept statement present" bullet so a reviewer actually checks for it. Re-read the modified section and both adjacent sections (the skeleton table above, the Construction-zone pattern below): neither is weakened or contradicted -- the construction-zone code examples show only fragment-variable strings, never a notebook cell-0 heading, so there is no overlap to conflict with. `uv run python -m glossary check`: 0 errors (7 pre-existing source-absent warnings, unrelated). Full suite (`uv run pytest tests/ glossary/tests/ -q`): 444 passed, 7 deselected. `uv run python scripts/check_construction.py --check`: clean. One logical change this session, as required. + +## DL-092 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | PENDING -- construction-zone reflection print changes from "print" to "assign, do not print" across two skills, so Phase B's proposed fixes stop contradicting the live skill text + +Path: ACE triage (ruled, applying Z's prior Decisions 1-2; not an escalation on the substance), routed here by the orchestrator per `decisions/diagram-text-integration-survey.md`'s cross-chapter open question 1. Still gated by `skill-editor`'s own Step 2: this change touches more than one archetype's primary skill (`tutorial-style-guide` loads for A3/A4/A6/A7; `toaster-recipe` loads for A4/A6), which is an automatic escalate-to-Z row on that skill's own blast-radius table -- not optional, and not satisfied by the ACE's ruling on the substance. Z's one-line confirmation of the exact replacement wording below is the actual gate; no edit has been made. + +Intended change, in one sentence: `TOASTER_INCREMENT` is assigned but never printed in any construction-zone notebook; the seam's result step is filled by the chapter's diagram where one exists, otherwise a short `model.find()`/`model.query()`/`model.eval()` or `src/toaster/query.py`-helper confirmation against the construct just declared, added where none exists. + +Decision (ACE's ruling, pending Z's wording confirmation): all 9 chapter-survey agents, independently, proposed removing the `print(TOASTER_INCREMENT)` line in roughly 20 construction notebooks across Ch1-Ch8 and Ch10. Every one of those proposals currently contradicts live skill text in two places. The ACE ruled to apply Z's own already-approved mechanism (spec Decision 1: scope includes the construction-zone double print in every construction notebook, with or without a diagram; Decision 2, Approach A: the diagram takes over the reflection step's job) rather than the orchestrator's own more conservative draft default (print only when neither a diagram nor a confirmation exists) -- Pattern 1b's own spec text already makes that fallback case empty by requiring a confirmation to be added where none exists, so keeping a conditional print would leave a loophole Z's own Decision 1 already closed, and would keep the stale sentence alive in the skill regardless. + +Revert record (verbatim, captured before any edit): + +`.claude/skills/tutorial-style-guide/SKILL.md` lines 93-101: +``` +- `TOASTER_INCREMENT` is assembled from the fragment variables in the final cell of the + construction zone; it equals the **new declarations for this notebook only** (not the full + cumulative model). Print it as the reflection. +- The cumulative load (`conn.load_from_content(ch0X-cumulative.sysml)`) happens in the same + final cell, after printing `TOASTER_INCREMENT`. +- `conn.close()` belongs at the end of the last code cell in the notebook (cell-04 or later), + never in the construction zone. +- Judgment, depth, navigation, analysis, and param-sweep notebooks have no construction zone + and do not assign `TOASTER_INCREMENT`. +``` + +`.claude/skills/toaster-recipe/SKILL.md` line 18 (skeleton table, Model increment row): "...Assign to `TOASTER_INCREMENT`; print immediately as reflection. Only in construct-introducing notebooks..." + +`.claude/skills/toaster-recipe/SKILL.md` lines 40-44 (construction-zone diagram): "`[code] TOASTER_INCREMENT assembled + printed ← reflection`" + +`.claude/skills/toaster-recipe/SKILL.md` lines 90-92 (multi-element example): "`# Cell: assembly + reflection + cumulative load`" / "`TOASTER_INCREMENT = f"{HEATER_DEF}\n{POWER_ATTR}\n ...\n}}"`" / "`print(TOASTER_INCREMENT)`" + +`.claude/skills/toaster-recipe/SKILL.md` line 101 (Notes): "It is assembled from the named fragment variables and printed as the reflection." + +`.claude/skills/toaster-recipe/SKILL.md` line 189 (A6 checklist, Model increment cell bullet): "...(1) `TOASTER_INCREMENT` assigned and printed as reflection (Pattern A: `str(editor.apply())`; Pattern B: SysML fragment string)..." + +`.claude/skills/toaster-recipe/SKILL.md` lines 204-210 (Tall's three worlds, construction cell update): "**E:** `TOASTER_INCREMENT` printed as the reflection — the engineer sees the validated canonical SysML" + +Proposed replacement wording (one logical change; the same governing sentence in both skills, each skill's own surrounding examples/table cells edited to match): + +> `TOASTER_INCREMENT` is assembled from the fragment variables in the final construction cell and equals the new declarations for this notebook only. It is assigned, not printed: each fragment was already printed when declared, and `scripts/check_construction.py` reads the assignment, never the print. The reflection -- the result the seam cell points at -- is the chapter's diagram where one exists; otherwise a short confirmation query against the construct just declared (`model.find()`/`model.query()`/`model.eval()`, or the `src/toaster/query.py` helper for constructs those surfaces do not see: `get_review_record_refs` for metadata usages, `satisfy_relationships` for `assert satisfy`, `find_allocations`/`perform_relationships` for allocations and performs), added if none exists. + +Principles applied: ace-protocol's "a prior decision by Z on the same question is applied as a decision, not re-escalated"; the P4 test (removing the reprint makes nothing harder for the learner, since each fragment is already printed once); P3/P5 (a printed string before loading is not a validated result; a diagram or query result the reader watched the loaded model produce is); `check_construction.py` reads only the assignment, so nothing downstream depends on the print. + +Reasoning: see the ACE's full report of 2026-10-02 (delivered via `SubagentHandback`, not yet a committed file) for the complete principle-by-principle argument, including why the confirmation class must include the `query.py` helpers (three of the survey's own Pattern-1b instances -- Ch3-01 metadata, Ch3-02 `assert satisfy`, Ch5-02 allocation -- are invisible to `model.find`/`model.query` per AGENTS.md 1.9) and why this does not reopen any Z decision (the original "print as reflection" convention was the ACE's own implementing choice in DL-011/DL-012, not Z's verbatim words there). + +Determined: yes, on the substance (not an extension of Z's own Decisions 1-2 as recorded in the spec). Still pending Z's one-line wording confirmation per `skill-editor`'s own multi-archetype escalation row -- that gate, not the substance, is what keeps this PENDING rather than COMPLETE. + +Extension: no. + +Provenance: `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 1-2 and "The two target patterns"; `decisions/diagram-text-integration-survey.md` (all 9 chapter tables; cross-chapter open questions 1 and 7); `.claude/skills/tutorial-style-guide/SKILL.md` 93-101; `.claude/skills/toaster-recipe/SKILL.md` 18, 40-44, 90-92, 101, 189, 204-210; `scripts/check_construction.py` 11-13, 378-421; AGENTS.md 1.7, 1.9; DL-011, DL-012 (origin of the "print as reflection" convention); DL-084 (P5 applied the same way to a seam's result step); ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. + +## DL-093 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | PENDING -- judgment-record tag reprint ruled the same defect as DL-092, not a sanctioned exception; the "judgment notebooks never assign TOASTER_INCREMENT" lines in two skills are stale since DL-084 and are corrected in the same pass + +Path: ACE triage (ruled; flagged "Extension: yes" per the ACE's own report, since this applies Z's Decision 1 to a case -- the judgment-record tag increments registered under DL-084 -- that Decision 1's own scope statement did not name at the time it was written). Same `skill-editor` gate as DL-092 applies (multiple archetypes' primary skills): Z's one-line confirmation of the replacement wording below is required before any edit; none has been made. + +Intended change, in one sentence: in every judgment-record notebook that introduces a new `ReviewRecordRef` tag, `TOASTER_INCREMENT` is assigned but never printed for that tag fragment, matching DL-092's ruling, and the two skills' own "judgment notebooks never assign `TOASTER_INCREMENT`" lines are corrected to reflect DL-084's already-approved tag-increment design. + +Decision (ACE's ruling, pending Z's wording confirmation): `toaster-recipe/SKILL.md` and `tutorial-style-guide/SKILL.md` both still say judgment notebooks have no construction zone and never assign `TOASTER_INCREMENT` -- text that predates DL-084, which gave judgment notebooks introducing a new tag a real model-side increment, registered them in `check_construction.py`'s own registry, and already has `toaster-recipe` lines 167-175 (the judgment-record construction-zone example) describing the tag fragment as built "the same way any other chapter's model increment is." The ACE ruled this is staleness, not a live two-skill conflict, and that the tag reprint itself is the same reflection-print-duplicates-already-shown-text defect DL-092 targets, not an exception from it: `toaster-review-protocol/SKILL.md` lines 150-152 justify the tag `TOASTER_INCREMENT` by parity with other increments, which is a reason for the fragment to exist, not a reason to print it twice. Affected notebooks, found independently by multiple survey agents: `ch02/03-judgment-context.ipynb` (cells 8-12), `ch03/01-moe-definition.ipynb` and `03-threshold-judgment.ipynb` (own tag cells), `ch04/03-completeness-check.ipynb` (cells 9-11), `ch06/03-stopping-judgment.ipynb` (cell-11), `ch08/02-violation-witness.ipynb` (cell-20), and `ch10/01-traceability-graph.ipynb` (cell 33, same defect by content type though it doesn't match either named pattern's literal shape). + +Two corrections to the survey document this ruling makes, recorded here since Phase B wording depends on them: (1) the hard "print as reflection" rule quoted in open question 1 is `tutorial-style-guide/SKILL.md` lines 93-97, not `toaster-recipe` -- `toaster-recipe` carries the same rule in the four locations listed under DL-092's revert record, not as its own separate rule; (2) the survey's claim that Ch6-03's narration "already calls this duplication deliberate" misreads the notebook -- `chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb` cell-11's "deliberately" describes `weak`, the deliberately-failing candidate, not the reprint. No notebook in this survey narrates its own reflection-print reprint as intentional. + +Revert record (verbatim, captured before any edit): + +`.claude/skills/toaster-review-protocol/SKILL.md` lines 109-112 (judgment record construction zone, anchor-groups code block): "`[code] TOASTER_INCREMENT = SOME_TAG # or assembled with any other new fragment this notebook adds`" / "` print(TOASTER_INCREMENT)`" + +`.claude/skills/toaster-review-protocol/SKILL.md` lines 150-152: "Each printed group is its own reflection, the same role a printed `TOASTER_INCREMENT` plays for a model fragment -- and `TOASTER_INCREMENT` here really is the Hawkins record's own model-side anchor, assembled and loaded the same way any other chapter's model increment is." + +`.claude/skills/toaster-recipe/SKILL.md` line 102 (Notes): "13 notebooks have construction cells; judgment, depth, navigation, analysis, param-sweep do not." + +`.claude/skills/toaster-recipe/SKILL.md` line 189 (A6 checklist): "...Judgment/depth/navigation/analysis notebooks: cell-02 loads cumulative only, no TOASTER_INCREMENT." + +`.claude/skills/tutorial-style-guide/SKILL.md` lines 100-101: "Judgment, depth, navigation, analysis, and param-sweep notebooks have no construction zone and do not assign `TOASTER_INCREMENT`." + +Proposed replacement wording: + +> `toaster-review-protocol/SKILL.md` lines 111-112: drop the `print(TOASTER_INCREMENT)` line from the code block (narration at line 110 stays, describing the fragment as already committed). Lines 150-152 reword to: "`TOASTER_INCREMENT` here is the record's own model-side anchor, assigned and checked the same way any other chapter's increment is; the `Model tag:` line printed when the record assembles is its confirmation, not a second print of the fragment." +> +> `toaster-recipe/SKILL.md` line 102 and `tutorial-style-guide/SKILL.md` lines 100-101 become: "Judgment notebooks that introduce a new `ReviewRecordRef` tag assign (not print) `TOASTER_INCREMENT` as the tag fragment(s), per DL-084. Python-only reconstruction, depth, navigation, analysis and param-sweep notebooks do not assign it at all." +> +> `toaster-recipe/SKILL.md` line 189's "no TOASTER_INCREMENT" clause gets the same correction. + +Principles applied: DL-084 applied as a prior Z-directed decision governing a later-written, now-stale rule; ace-protocol's "a quotation that does not address the case is not evidence for it" (applied to `toaster-review-protocol`'s parity sentence, which justifies the fragment's existence, not its reprint); the P4 test; F4 with confirmed extension DL-033/DL-084 (a tag is checkable metadata, i.e. analysis of the model, not narration). + +Reasoning: see the ACE's full report of 2026-10-02 (delivered via `SubagentHandback`) for the complete argument, including why `decisions/declarative-construction-plan.md` line 56 (which lists `ch04/03-completeness-check.ipynb` as having no construction cells) is itself pre-DL-084 and needs an administrative annotation, not a rewrite, and why Ch10-01 cell 33 falls under this same ruling by content type rather than variable name. + +Determined: yes, on the substance. Still PENDING Z's one-line wording confirmation, same gate as DL-092. + +Extension: yes, per the ACE's own flag -- applying Z's Decision 1 (scoped, at the time it was written, to "the 13 construction notebooks" under the pre-DL-084 count) to the judgment-record tag increments DL-084 later registered as real construction cells is a case Z's own scope statement did not name. This is the flag the spec's own "scope outside the named patterns is flagged for Z, not folded in silently" rule calls for -- and the `skill-editor` gate below is where that flag actually reaches Z, not a separate escalation. + +Provenance: DL-084 (design, registry change, `toaster-recipe`/`toaster-review-protocol` updates, known-gaps item 2); DL-075 (closed by DL-084); DL-033 (confirmed extension: judgment records are analysis); `.claude/skills/toaster-review-protocol/SKILL.md` 95-152; `.claude/skills/toaster-recipe/SKILL.md` 102, 130-136, 167-175, 189; `.claude/skills/tutorial-style-guide/SKILL.md` 100-101; `scripts/check_construction.py` registry lines 94, 125, 159, 235, 289, 326; `chapters/ch02-requirements/03-judgment-context.ipynb` cells 8-13; `chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb` cells 11-16; `decisions/diagram-text-integration-survey.md` cross-chapter open questions 2, 5, 6, 7; `decisions/declarative-construction-plan.md` 52-60; `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decision 1, "Rolling cleanup" closing paragraph, Non-goals; ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. From fbdbc1daeede7933a9e9f6b918c7f31b0e505757 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 10:56:43 -0400 Subject: [PATCH 06/25] skill-fix: TOASTER_INCREMENT is assigned, not printed, per DL-092/DL-093 Z-confirmed wording. Applies Z's already-approved Decisions 1-2 (diagram/ text integration redesign) to the construction-zone reflection print and the judgment-record tag-anchor print, both of which this skill text had required and which every Phase A survey proposal now contradicts. --- .claude/skills/toaster-recipe/SKILL.md | 26 +++++++++++++------ .../skills/toaster-review-protocol/SKILL.md | 9 ++++--- .claude/skills/tutorial-style-guide/SKILL.md | 19 +++++++++----- decisions/log.md | 6 +++-- 4 files changed, 40 insertions(+), 20 deletions(-) diff --git a/.claude/skills/toaster-recipe/SKILL.md b/.claude/skills/toaster-recipe/SKILL.md index 57400bf..68b1902 100644 --- a/.claude/skills/toaster-recipe/SKILL.md +++ b/.claude/skills/toaster-recipe/SKILL.md @@ -15,7 +15,7 @@ The 7 cells below are the **required skeleton**. Additional markdown+code pairs |---|---|---| | **Concept** | Markdown | Exactly one sentence: "This notebook introduces X; after running it you can Y." | | **Context** | Markdown | One paragraph locating this notebook in the chapter arc. One link to prior notebook if model state carries over. | -| **Model increment** | Code | Two-phase. (1) Declare the increment: Pattern A (Editor API, returns full model) or Pattern B (SysML string fragment for gap constructs). Assign to `TOASTER_INCREMENT`; print immediately as reflection. Only in construct-introducing notebooks — see scope table in `decisions/declarative-construction-plan.md`. (2) Load full chapter cumulative from `models/chXX-cumulative.sysml`; `assert model.ok`. | +| **Model increment** | Code | Two-phase. (1) Declare the increment: Pattern A (Editor API, returns full model) or Pattern B (SysML string fragment for gap constructs). Assign to `TOASTER_INCREMENT`; it is not printed here — see "Construction cells" below for what fills the reflection step (the chapter's diagram or a confirmation query). Only in construct-introducing notebooks — see scope table in `decisions/declarative-construction-plan.md`. (2) Load full chapter cumulative from `models/chXX-cumulative.sysml`; `assert model.ok`. | | **Negative control** | Code + Markdown | Short bad_source string. `bad = conn.load_from_content(bad_source, strict=False)`. `assert not bad.ok`. Markdown: one sentence naming the error type and pointing to the diagnostic. | | **Demonstration** | Code + Markdown | One key operation per code cell. If two things happen, split into two cells each with its own narration markdown. | | **Seam** | Markdown | Exactly one sentence, addressing in behavior that the written construct, the tool that loaded it, and the rendered result are three distinct things the reader has just watched connect. Never names Tall or "the three worlds" (AGENTS.md 1.10) — see "Tall's three worlds" below. | @@ -40,8 +40,10 @@ The construction zone replaces the single cell-02 with a sequence of code+markdo [code] next fragment variable + printed ← mirrors next editor.add_*() call [markdown] narration ... -[code] TOASTER_INCREMENT assembled + printed ← reflection +[code] TOASTER_INCREMENT assembled (not printed) cumulative model loaded; assert model.ok ← for subsequent cells +[markdown] bridge: what's about to be shown and why +[code] the chapter's diagram, or a model.find()/model.query() confirmation ← reflection ``` **Fragment size rule:** ≤5 lines per fragment variable (ideally 1–3). If longer, split further. @@ -87,9 +89,9 @@ POWER_ATTR = " attribute power : ISQ::PowerValue default = 800.0 [SI::W];" print(POWER_ATTR) ``` ```python -# Cell: assembly + reflection + cumulative load +# Cell: assembly + cumulative load (TOASTER_INCREMENT is assigned, not printed -- +# the reflection step is a diagram or confirmation query, shown in a later cell) TOASTER_INCREMENT = f"{HEATER_DEF}\n{POWER_ATTR}\n ...\n}}" -print(TOASTER_INCREMENT) source = Path("../../models/ch01-cumulative.sysml").read_text() model = conn.load_from_content(source, strict=False) @@ -98,8 +100,14 @@ assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" **Notes:** - `TOASTER_INCREMENT` = new declarations introduced by this notebook only (not the full model). -- It is assembled from the named fragment variables and printed as the reflection. -- 13 notebooks have construction cells; judgment, depth, navigation, analysis, param-sweep do not. +- It is assembled from the named fragment variables and assigned, not printed. The reflection + step is the chapter's diagram where one exists, otherwise a confirmation query against the + construct just declared (`model.find()`/`model.query()`/`model.eval()`, or the + `src/toaster/query.py` helper where those surfaces do not see the construct). +- Construction-introducing notebooks assign `TOASTER_INCREMENT` for their model fragment; + judgment notebooks that introduce a new `ReviewRecordRef` tag also assign it for that tag + fragment (DL-084). Python-only reconstruction, depth, navigation, analysis and param-sweep + notebooks do not assign it at all. - The cumulative model file is authored by A3 and must exist before A4 finalizes the assembly cell. ## Tall's three worlds (builder-facing lens; corrected DL-015/DL-050) @@ -186,7 +194,7 @@ Identify required cells by content type, not by cell index — additional narrat - [ ] **Concept statement present:** exactly one sentence starting "This notebook introduces"; cell 0's own heading is level 1 (`#`), and the notebook's `metadata` carries `short_title: "ChN-NN"` - [ ] **Context cell present:** one paragraph with link to prior notebook (where applicable) -- [ ] **Model increment cell present (construct-introducing notebooks only):** two-phase — (1) `TOASTER_INCREMENT` assigned and printed as reflection (Pattern A: `str(editor.apply())`; Pattern B: SysML fragment string); (2) full cumulative loaded from `models/chXX-cumulative.sysml`; `assert model.ok`. Judgment/depth/navigation/analysis notebooks: cell-02 loads cumulative only, no TOASTER_INCREMENT. +- [ ] **Model increment cell present (construct-introducing notebooks only):** two-phase — (1) `TOASTER_INCREMENT` assigned, not printed (Pattern A: `str(editor.apply())`; Pattern B: SysML fragment string); the reflection step is the chapter's diagram or a confirmation query, not a reprint; (2) full cumulative loaded from `models/chXX-cumulative.sysml`; `assert model.ok`. Judgment notebooks introducing a new `ReviewRecordRef` tag: same rule, for the tag fragment (DL-084). Depth/navigation/analysis/param-sweep notebooks and Python-only judgment reconstructions: cell-02 loads cumulative only, no `TOASTER_INCREMENT`. - [ ] **Negative control present:** short bad_source inline; `assert not bad.ok`; markdown names the error type - [ ] **Demo cell(s) present:** one key operation per code cell; each code cell followed by markdown narration - [ ] **Seam present:** exactly one sentence addressing, in behavior, that the definition, the loading tool, and the printed result are three distinct things the reader just watched connect — never naming Tall, "the three worlds", A-F, O-S or E @@ -201,7 +209,9 @@ own design purposes only: - **A-F:** the SysML declaration produced by the construction call or written as a string - **O-S:** `editor.apply()` (Pattern A) or `conn.load_from_content()` (Pattern B) executes it -- **E:** `TOASTER_INCREMENT` printed as the reflection — the engineer sees the validated canonical SysML +- **E:** the chapter's diagram, or a confirmation query against the construct just declared -- + the engineer sees the validated canonical SysML reflected back by a real result, not a reprint + of the string from before it loaded The seam cell (slot 5) addresses the connection behaviorally, as above — for a Pattern A notebook that means pointing at what `editor.add_*()` produced and what running it validated; for Pattern B, diff --git a/.claude/skills/toaster-review-protocol/SKILL.md b/.claude/skills/toaster-review-protocol/SKILL.md index e44f642..948ba72 100644 --- a/.claude/skills/toaster-review-protocol/SKILL.md +++ b/.claude/skills/toaster-review-protocol/SKILL.md @@ -109,7 +109,7 @@ Hawkins' taxonomy is answering, not by the dataclass's field order: print(SOME_TAG) [markdown] narration: this fragment is the same text now committed in the cumulative model [code] TOASTER_INCREMENT = SOME_TAG # or assembled with any other new fragment this notebook adds - print(TOASTER_INCREMENT) + # assigned, not printed -- the anchor fragment above was already printed when declared [markdown] narration: the claim itself comes next [code] claim = "..." model_ref = "..." @@ -147,9 +147,10 @@ Hawkins-taxonomy groups); five when it is a Python-only reconstruction that cite identifier from an earlier chapter (no new SysML, so no anchor groups, but `model=model` and the `Model tag` lookup still run, exercising the cross-representation check against the already-committed tag). Every code cell is still followed by a markdown cell narrating what's next (no two code cells -adjacent). Each printed group is its own reflection, the same role a printed `TOASTER_INCREMENT` -plays for a model fragment — and `TOASTER_INCREMENT` here really is the Hawkins record's own model- -side anchor, assembled and loaded the same way any other chapter's model increment is. +adjacent). Each printed group is its own reflection. `TOASTER_INCREMENT` here is the Hawkins record's own +model-side anchor, assigned and checked the same way any other chapter's increment is -- not +printed again, since the anchor fragment it's built from was already printed above; the +`Model tag:` line printed when the record assembles is its confirmation. **Size limit:** `toaster-recipe`'s ≤600 words / ≤50 lines budget is sized for a notebook whose main content is one model construct. A notebook whose construct is a judgment record may exceed it — the diff --git a/.claude/skills/tutorial-style-guide/SKILL.md b/.claude/skills/tutorial-style-guide/SKILL.md index 0465800..ebe8786 100644 --- a/.claude/skills/tutorial-style-guide/SKILL.md +++ b/.claude/skills/tutorial-style-guide/SKILL.md @@ -90,15 +90,22 @@ structure stays the same. # spec: SysML v2 formal/2026-03-02 §7.3.3 TOASTING_SYSTEM_DEF = "abstract part def ToastingSystem;" ``` -- `TOASTER_INCREMENT` is assembled from the fragment variables in the final cell of the - construction zone; it equals the **new declarations for this notebook only** (not the full - cumulative model). Print it as the reflection. +- `TOASTER_INCREMENT` is assembled from the fragment variables in the final construction cell + and equals the **new declarations for this notebook only** (not the full cumulative model). + It is assigned, not printed: each fragment was already printed when declared, and + `scripts/check_construction.py` reads the assignment, never the print. The reflection -- the + result the seam cell points at -- is the chapter's diagram where one exists; otherwise a short + confirmation query against the construct just declared (`model.find()`/`model.query()`/ + `model.eval()`, or the `src/toaster/query.py` helper for constructs those surfaces do not see: + `get_review_record_refs` for metadata usages, `satisfy_relationships` for `assert satisfy`, + `find_allocations`/`perform_relationships` for allocations and performs), added if none exists. - The cumulative load (`conn.load_from_content(ch0X-cumulative.sysml)`) happens in the same - final cell, after printing `TOASTER_INCREMENT`. + final cell as the assignment. - `conn.close()` belongs at the end of the last code cell in the notebook (cell-04 or later), never in the construction zone. -- Judgment, depth, navigation, analysis, and param-sweep notebooks have no construction zone - and do not assign `TOASTER_INCREMENT`. +- Judgment notebooks that introduce a new `ReviewRecordRef` tag assign (not print) + `TOASTER_INCREMENT` as the tag fragment(s), per DL-084. Python-only reconstruction, depth, + navigation, analysis and param-sweep notebooks do not assign it at all. ## What every agent loading this skill must never do diff --git a/decisions/log.md b/decisions/log.md index 1f172cc..43d2f83 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1259,7 +1259,7 @@ Revert record (verbatim, the exact text immediately surrounding the insertion po Reasoning: this is the direct follow-up DL-090 itself named as a required next step -- the H1+short_title convention is real (independently verified across four review rounds) and completely undocumented in the one skill a builder or reviewer would actually consult before touching a notebook's own cell 0; leaving it undocumented reintroduces DL-090's own bug the next time anyone writes `##` instead of `#` without knowing why it matters. Post-edit check: added one short paragraph after the skeleton table (`.claude/skills/toaster-recipe/SKILL.md`, the exact text quoted above in the revert record) stating the H1 + `short_title` requirement, citing DL-090; added one clause to the A6 checklist's existing "Concept statement present" bullet so a reviewer actually checks for it. Re-read the modified section and both adjacent sections (the skeleton table above, the Construction-zone pattern below): neither is weakened or contradicted -- the construction-zone code examples show only fragment-variable strings, never a notebook cell-0 heading, so there is no overlap to conflict with. `uv run python -m glossary check`: 0 errors (7 pre-existing source-absent warnings, unrelated). Full suite (`uv run pytest tests/ glossary/tests/ -q`): 444 passed, 7 deselected. `uv run python scripts/check_construction.py --check`: clean. One logical change this session, as required. -## DL-092 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | PENDING -- construction-zone reflection print changes from "print" to "assign, do not print" across two skills, so Phase B's proposed fixes stop contradicting the live skill text +## DL-092 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | COMPLETE -- construction-zone reflection print changes from "print" to "assign, do not print" across two skills, so Phase B's proposed fixes stop contradicting the live skill text Path: ACE triage (ruled, applying Z's prior Decisions 1-2; not an escalation on the substance), routed here by the orchestrator per `decisions/diagram-text-integration-survey.md`'s cross-chapter open question 1. Still gated by `skill-editor`'s own Step 2: this change touches more than one archetype's primary skill (`tutorial-style-guide` loads for A3/A4/A6/A7; `toaster-recipe` loads for A4/A6), which is an automatic escalate-to-Z row on that skill's own blast-radius table -- not optional, and not satisfied by the ACE's ruling on the substance. Z's one-line confirmation of the exact replacement wording below is the actual gate; no edit has been made. @@ -1303,12 +1303,13 @@ Principles applied: ace-protocol's "a prior decision by Z on the same question i Reasoning: see the ACE's full report of 2026-10-02 (delivered via `SubagentHandback`, not yet a committed file) for the complete principle-by-principle argument, including why the confirmation class must include the `query.py` helpers (three of the survey's own Pattern-1b instances -- Ch3-01 metadata, Ch3-02 `assert satisfy`, Ch5-02 allocation -- are invisible to `model.find`/`model.query` per AGENTS.md 1.9) and why this does not reopen any Z decision (the original "print as reflection" convention was the ACE's own implementing choice in DL-011/DL-012, not Z's verbatim words there). Determined: yes, on the substance (not an extension of Z's own Decisions 1-2 as recorded in the spec). Still pending Z's one-line wording confirmation per `skill-editor`'s own multi-archetype escalation row -- that gate, not the substance, is what keeps this PENDING rather than COMPLETE. +Post-edit check: `.claude/skills/tutorial-style-guide/SKILL.md` lines 93-101, `.claude/skills/toaster-recipe/SKILL.md` lines 18, 40-46, 90-94, 101-110, 189, 204-210 edited; glossary check 0 errors; pytest 444 passed, 7 deselected; check_construction.py clean; no new em-dash introduced. Extension: no. Provenance: `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 1-2 and "The two target patterns"; `decisions/diagram-text-integration-survey.md` (all 9 chapter tables; cross-chapter open questions 1 and 7); `.claude/skills/tutorial-style-guide/SKILL.md` 93-101; `.claude/skills/toaster-recipe/SKILL.md` 18, 40-44, 90-92, 101, 189, 204-210; `scripts/check_construction.py` 11-13, 378-421; AGENTS.md 1.7, 1.9; DL-011, DL-012 (origin of the "print as reflection" convention); DL-084 (P5 applied the same way to a seam's result step); ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. -## DL-093 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | PENDING -- judgment-record tag reprint ruled the same defect as DL-092, not a sanctioned exception; the "judgment notebooks never assign TOASTER_INCREMENT" lines in two skills are stale since DL-084 and are corrected in the same pass +## DL-093 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | COMPLETE -- judgment-record tag reprint ruled the same defect as DL-092, not a sanctioned exception; the "judgment notebooks never assign TOASTER_INCREMENT" lines in two skills are stale since DL-084 and are corrected in the same pass Path: ACE triage (ruled; flagged "Extension: yes" per the ACE's own report, since this applies Z's Decision 1 to a case -- the judgment-record tag increments registered under DL-084 -- that Decision 1's own scope statement did not name at the time it was written). Same `skill-editor` gate as DL-092 applies (multiple archetypes' primary skills): Z's one-line confirmation of the replacement wording below is required before any edit; none has been made. @@ -1343,6 +1344,7 @@ Principles applied: DL-084 applied as a prior Z-directed decision governing a la Reasoning: see the ACE's full report of 2026-10-02 (delivered via `SubagentHandback`) for the complete argument, including why `decisions/declarative-construction-plan.md` line 56 (which lists `ch04/03-completeness-check.ipynb` as having no construction cells) is itself pre-DL-084 and needs an administrative annotation, not a rewrite, and why Ch10-01 cell 33 falls under this same ruling by content type rather than variable name. Determined: yes, on the substance. Still PENDING Z's one-line wording confirmation, same gate as DL-092. +Post-edit check: `.claude/skills/toaster-review-protocol/SKILL.md` lines 109-112, 150-152 edited; `.claude/skills/toaster-recipe/SKILL.md` lines 100-110, 189 edited; `.claude/skills/tutorial-style-guide/SKILL.md` lines 100-101 edited; glossary check 0 errors; pytest 444 passed, 7 deselected; check_construction.py clean; no new em-dash introduced. Extension: yes, per the ACE's own flag -- applying Z's Decision 1 (scoped, at the time it was written, to "the 13 construction notebooks" under the pre-DL-084 count) to the judgment-record tag increments DL-084 later registered as real construction cells is a case Z's own scope statement did not name. This is the flag the spec's own "scope outside the named patterns is flagged for Z, not folded in silently" rule calls for -- and the `skill-editor` gate below is where that flag actually reaches Z, not a separate escalation. From e6b54e54cbd0b182d9827685394b76b80073a56b Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:02:21 -0400 Subject: [PATCH 07/25] Follow-up to fbdbc1d: fix two loose ends flagged by review - decisions/log.md: DL-092 and DL-093 bodies still said "no edit has been made" / "PENDING Z's wording confirmation" after their headers were flipped to COMPLETE by fbdbc1d. Both now say the edit was made, citing fbdbc1d. - toaster-recipe/SKILL.md: the Pattern-B seam-cell sentence still pointed at "the TOASTER_INCREMENT string" as what the reader sees, which is stale now that TOASTER_INCREMENT is assigned, not printed. Points instead at the already-printed fragment variables and the diagram/confirmation query that fills the reflection role. --- .claude/skills/toaster-recipe/SKILL.md | 5 +++-- decisions/log.md | 8 ++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.claude/skills/toaster-recipe/SKILL.md b/.claude/skills/toaster-recipe/SKILL.md index 68b1902..5157a5a 100644 --- a/.claude/skills/toaster-recipe/SKILL.md +++ b/.claude/skills/toaster-recipe/SKILL.md @@ -215,8 +215,9 @@ own design purposes only: The seam cell (slot 5) addresses the connection behaviorally, as above — for a Pattern A notebook that means pointing at what `editor.add_*()` produced and what running it validated; for Pattern B, -at the `TOASTER_INCREMENT` string and what loading it validated. Neither the labels above nor "Tall" -nor "three worlds" appear in the sentence itself. +at the fragment variables already printed when declared and the diagram or confirmation query that +shows what loading validated. Neither the labels above nor "Tall" nor "three worlds" appear in the +sentence itself. ## What A4 must never do diff --git a/decisions/log.md b/decisions/log.md index 43d2f83..adab55f 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1261,7 +1261,7 @@ Post-edit check: added one short paragraph after the skeleton table (`.claude/sk ## DL-092 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | COMPLETE -- construction-zone reflection print changes from "print" to "assign, do not print" across two skills, so Phase B's proposed fixes stop contradicting the live skill text -Path: ACE triage (ruled, applying Z's prior Decisions 1-2; not an escalation on the substance), routed here by the orchestrator per `decisions/diagram-text-integration-survey.md`'s cross-chapter open question 1. Still gated by `skill-editor`'s own Step 2: this change touches more than one archetype's primary skill (`tutorial-style-guide` loads for A3/A4/A6/A7; `toaster-recipe` loads for A4/A6), which is an automatic escalate-to-Z row on that skill's own blast-radius table -- not optional, and not satisfied by the ACE's ruling on the substance. Z's one-line confirmation of the exact replacement wording below is the actual gate; no edit has been made. +Path: ACE triage (ruled, applying Z's prior Decisions 1-2; not an escalation on the substance), routed here by the orchestrator per `decisions/diagram-text-integration-survey.md`'s cross-chapter open question 1. Still gated by `skill-editor`'s own Step 2: this change touches more than one archetype's primary skill (`tutorial-style-guide` loads for A3/A4/A6/A7; `toaster-recipe` loads for A4/A6), which is an automatic escalate-to-Z row on that skill's own blast-radius table -- not optional, and not satisfied by the ACE's ruling on the substance. Z's one-line confirmation of the exact replacement wording below was the actual gate; the edit has been made (commit `fbdbc1d`). Intended change, in one sentence: `TOASTER_INCREMENT` is assigned but never printed in any construction-zone notebook; the seam's result step is filled by the chapter's diagram where one exists, otherwise a short `model.find()`/`model.query()`/`model.eval()` or `src/toaster/query.py`-helper confirmation against the construct just declared, added where none exists. @@ -1302,7 +1302,7 @@ Principles applied: ace-protocol's "a prior decision by Z on the same question i Reasoning: see the ACE's full report of 2026-10-02 (delivered via `SubagentHandback`, not yet a committed file) for the complete principle-by-principle argument, including why the confirmation class must include the `query.py` helpers (three of the survey's own Pattern-1b instances -- Ch3-01 metadata, Ch3-02 `assert satisfy`, Ch5-02 allocation -- are invisible to `model.find`/`model.query` per AGENTS.md 1.9) and why this does not reopen any Z decision (the original "print as reflection" convention was the ACE's own implementing choice in DL-011/DL-012, not Z's verbatim words there). -Determined: yes, on the substance (not an extension of Z's own Decisions 1-2 as recorded in the spec). Still pending Z's one-line wording confirmation per `skill-editor`'s own multi-archetype escalation row -- that gate, not the substance, is what keeps this PENDING rather than COMPLETE. +Determined: yes, on the substance (not an extension of Z's own Decisions 1-2 as recorded in the spec). Z confirmed the wording; the edit is applied (see Post-edit check line below). Post-edit check: `.claude/skills/tutorial-style-guide/SKILL.md` lines 93-101, `.claude/skills/toaster-recipe/SKILL.md` lines 18, 40-46, 90-94, 101-110, 189, 204-210 edited; glossary check 0 errors; pytest 444 passed, 7 deselected; check_construction.py clean; no new em-dash introduced. Extension: no. @@ -1311,7 +1311,7 @@ Provenance: `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.m ## DL-093 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | COMPLETE -- judgment-record tag reprint ruled the same defect as DL-092, not a sanctioned exception; the "judgment notebooks never assign TOASTER_INCREMENT" lines in two skills are stale since DL-084 and are corrected in the same pass -Path: ACE triage (ruled; flagged "Extension: yes" per the ACE's own report, since this applies Z's Decision 1 to a case -- the judgment-record tag increments registered under DL-084 -- that Decision 1's own scope statement did not name at the time it was written). Same `skill-editor` gate as DL-092 applies (multiple archetypes' primary skills): Z's one-line confirmation of the replacement wording below is required before any edit; none has been made. +Path: ACE triage (ruled; flagged "Extension: yes" per the ACE's own report, since this applies Z's Decision 1 to a case -- the judgment-record tag increments registered under DL-084 -- that Decision 1's own scope statement did not name at the time it was written). Same `skill-editor` gate as DL-092 applies (multiple archetypes' primary skills): Z's one-line confirmation of the replacement wording below was required before any edit; the edit has been made (commit `fbdbc1d`). Intended change, in one sentence: in every judgment-record notebook that introduces a new `ReviewRecordRef` tag, `TOASTER_INCREMENT` is assigned but never printed for that tag fragment, matching DL-092's ruling, and the two skills' own "judgment notebooks never assign `TOASTER_INCREMENT`" lines are corrected to reflect DL-084's already-approved tag-increment design. @@ -1343,7 +1343,7 @@ Principles applied: DL-084 applied as a prior Z-directed decision governing a la Reasoning: see the ACE's full report of 2026-10-02 (delivered via `SubagentHandback`) for the complete argument, including why `decisions/declarative-construction-plan.md` line 56 (which lists `ch04/03-completeness-check.ipynb` as having no construction cells) is itself pre-DL-084 and needs an administrative annotation, not a rewrite, and why Ch10-01 cell 33 falls under this same ruling by content type rather than variable name. -Determined: yes, on the substance. Still PENDING Z's one-line wording confirmation, same gate as DL-092. +Determined: yes, on the substance. Z confirmed the wording; the edit is applied (see Post-edit check line below). Post-edit check: `.claude/skills/toaster-review-protocol/SKILL.md` lines 109-112, 150-152 edited; `.claude/skills/toaster-recipe/SKILL.md` lines 100-110, 189 edited; `.claude/skills/tutorial-style-guide/SKILL.md` lines 100-101 edited; glossary check 0 errors; pytest 444 passed, 7 deselected; check_construction.py clean; no new em-dash introduced. Extension: yes, per the ACE's own flag -- applying Z's Decision 1 (scoped, at the time it was written, to "the 13 construction notebooks" under the pre-DL-084 count) to the judgment-record tag increments DL-084 later registered as real construction cells is a case Z's own scope statement did not name. This is the flag the spec's own "scope outside the named patterns is flagged for Z, not folded in silently" rule calls for -- and the `skill-editor` gate below is where that flag actually reaches Z, not a separate escalation. From e3f32e0601613b118689e264aaa010e3e64e772b Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:30:57 -0400 Subject: [PATCH 08/25] Phase B plan: diagram/text integration implementation, 9 parallel chapter contracts Fully self-contained -- every chapter task's acceptance criteria quote the Phase A survey's own literal cell content verbatim, plus the two DL-093-resolved judgment-tag fixes the survey itself held back as open questions. Uses this project's own CONTRACT.md-per-worktree harness (builder sonnet / reviewer opus), not writing-plans' generic two options, per spec Decision 5. --- ...2-diagram-text-integration-phase-b-plan.md | 879 ++++++++++++++++++ 1 file changed, 879 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-b-plan.md diff --git a/docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-b-plan.md b/docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-b-plan.md new file mode 100644 index 0000000..f75336f --- /dev/null +++ b/docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-b-plan.md @@ -0,0 +1,879 @@ +# Diagram/Text Integration — Phase B (Implementation) Plan + +> **For agentic workers:** This plan's own tasks are NOT generic TDD-cycle tasks and do NOT use +> `superpowers:subagent-driven-development` or `superpowers:executing-plans`. This project has its +> own established implementation harness — see "Standard execution procedure" below, which every +> task references instead of restating it. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Implement every fix `decisions/diagram-text-integration-survey.md` (Phase A's complete +output) proposes — construction-zone reflection-print removal, whole-dump trimming, and the four +enumerated cleanup items — across Chapters 1–8 and 10, through this repo's own builder/reviewer +harness, with zero direct orchestrator edits to chapter content. + +**Architecture:** One task per chapter (9 tasks, Ch1–Ch8 and Ch10), each its own `CONTRACT.md` +executed in its own git worktree: builder on `claude-sonnet-5`, reviewer on `claude-opus-5-5` +(always a different model), up to 2 revision cycles then escalate to the ACE, orchestrator merges +after PASS. This is the exact mechanism this session already used and proved for the DL-092/DL-093 +skill fix (worktree `skill-fix-092-093`, commits `fbdbc1d`/`e6b54e5`, merged `0fcd4af`) — not +`writing-plans`' own generic Subagent-driven/Native choice. A tenth task is a small administrative +correction to a historical document, done directly by the orchestrator under its own established +record-keeping role (same role used compiling this survey), not a contract. + +**Tech Stack:** `git worktree`, the `Agent` tool (`subagent_type: "builder"` / `"reviewer"`), +`uv run pytest`, `uv run python scripts/check_construction.py --check`, `jupyter nbconvert +--execute` (or this repo's own equivalent end-to-end notebook check), the `simulated-learner` agent +type for the Pattern-2 spot-checks. + +**Spec:** `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` + +**Also required reading for every task:** `decisions/diagram-text-integration-survey.md` (Phase +A's output — the literal source of every proposed cell change quoted below) and `decisions/log.md` +DL-092/DL-093 (both `COMPLETE` — the two skills every chapter's own reviewer checks against, +`tutorial-style-guide/SKILL.md`, `toaster-recipe/SKILL.md`, `toaster-review-protocol/SKILL.md`, are +already updated to require "assign, not print"). + +## Global Constraints + +- Chapter 9 is out of scope (spec Non-goals). +- No chapter's taught content, model, or didactic sequencing changes — only presentation + (diagram vs. print, full dump vs. targeted excerpt) (spec Non-goals). +- No change to `render.py` or any rendering function (spec Non-goals). +- No prose trimming beyond the two named patterns and the four enumerated cleanup items (spec + Non-goals, Parsimony heuristic). +- Every task's blast zone is read-write only within its own chapter's own files, plus the specific + cross-chapter reference files Task 8 (Ch8 rename) enumerates — no task touches another chapter's + own notebook, model, or figure. +- Builder is `claude-sonnet-5`; reviewer is `claude-opus-5-5`; never the same model (spec Decision + 3). +- The survey's own proposed cell content is each task's acceptance criterion, verbatim — not + something the builder re-derives or improves (spec Decision 2, Process). +- Every task re-runs `uv run pytest tests/ glossary/tests/ -q` and `uv run python + scripts/check_construction.py --check`, both clean, before the reviewer signs off (spec + Verification). +- Every task that modifies a Pattern-2 (whole-dump) notebook confirms the trimmed `print()` call's + output is byte-for-byte / line-range-verified against the real, current `models/chNN-cumulative.sysml` + file — not just that the cell runs without error (spec Verification; this is how Phase A's own + consistency-check was done, and Phase B must not regress it). +- At least one `simulated-learner` persona spot-check on every notebook whose prose shrank + materially (spec Decision 3, Verification) — specifically the five Pattern-2 trims: Ch2-03, + Ch3-03, Ch4-03, Ch5-01, Ch6-03. +- No skill-content change in this plan — DL-092/DL-093 already closed that work. If a task's own + builder or reviewer finds a *new* skill contradiction, it is routed to the ACE exactly as + DL-092/DL-093 were, never fixed inline inside a chapter contract (spec Non-goals). + +## Review Focus + +1. **A builder reprints more or less than the survey's own exact proposed line range for a + Pattern-2 trim**, silently drifting from the already-verified residual. Pinned to: Tasks 2, 3, + 4, 5, 6's own acceptance criteria quote the survey's exact line ranges and exact excerpt code; + each task's Verification step re-diffs the committed trim against those exact ranges. +2. **A builder "fixes" a seam-cell or bridge sentence the survey didn't flag as needing a wording + change**, introducing scope creep the harness exists to catch. Pinned to: every task's Non-Goals + section states explicitly which sentences are in scope to reword and that no other prose may + change; every task's reviewer step checks the diff for any touched line outside the enumerated + list. +3. **The Ch8 rename misses one of the 6 enumerated reference-update files**, breaking a link + silently. Pinned to: Task 8's own Step 2 enumerates all 6 files plus the notebook itself as + separate, individually-checked sub-steps; its reviewer step re-greps the whole repo for the old + filename string after the builder's own commit. +4. **A builder re-adds a confirmation query where the survey explicitly found one already exists + downstream**, creating a NEW duplication while fixing the old one. Pinned to: every Pattern-1b + task's acceptance criteria state explicitly, per notebook, whether a new confirmation cell is + needed (Ch7-01 only) or an existing one already suffices (every other Pattern-1b instance in + this plan) — the reviewer checks for exactly the stated outcome, not "a confirmation exists + somewhere." +5. **A notebook's own cell-execution order breaks** (a cell references a variable from a cell that + was deleted or reordered). Pinned to: every task's Verification step requires an actual + end-to-end notebook execution (`jupyter nbconvert --execute --to notebook --stdout <nb>` run + from the notebook's own directory, exit 0, zero cell errors), not just inspecting the diff. + +--- + +## Standard execution procedure (every chapter task, Tasks 1–9, follows this exactly) + +This is the same mechanism this session already used for the DL-092/DL-093 skill fix. Each task +below gives the chapter-specific blast zone and acceptance criteria; apply this procedure to +execute it. + +- [ ] **Step A: Create the worktree and branch** + +```bash +cd /Users/z/Documents/GitHub/toaster +git worktree add .claude/worktrees/<task-slug> -b phase-b/<task-slug> diagram-text-integration +``` + +- [ ] **Step B: Write `CONTRACT.md` in that worktree's root**, containing exactly: the task's own + "Blast zone" list, "Acceptance criteria" (the literal cell content given below), "Non-goals" + (the literal list given below), and "Verification" (the standard checks: `uv run pytest tests/ + glossary/tests/ -q`; `uv run python scripts/check_construction.py --check`; end-to-end execution + of every touched notebook; for a Pattern-2 task, the byte/line-range check against the real + cumulative model file; and, for the five Pattern-2 tasks, a note that a `simulated-learner` + spot-check follows after merge, per Step F below). + +- [ ] **Step C: Dispatch the builder** + +Use the `Agent` tool, `subagent_type: "builder"`, prompt: "Work in the git worktree at +`/Users/z/Documents/GitHub/toaster/.claude/worktrees/<task-slug>` (branch `phase-b/<task-slug>`, +based on `diagram-text-integration`). Read `CONTRACT.md` in that worktree's root and execute it +exactly. Commit (no co-author trailer, per this repo's own convention), do not push. Report the +full diff and every check's output." + +- [ ] **Step D: Dispatch the reviewer** + +Use the `Agent` tool, `subagent_type: "reviewer"`, different model from the builder by +construction (the `reviewer` role is pinned to `claude-opus-5-5`). Prompt: "Review the builder's +commit on branch `phase-b/<task-slug>` in the worktree at +`/Users/z/Documents/GitHub/toaster/.claude/worktrees/<task-slug>`, against that worktree's own +`CONTRACT.md`. Re-run every check yourself; verify every acceptance-criterion cell content +byte-for-byte; verify the blast zone was not exceeded. Report PASS, FAIL, or CANT_TELL with +evidence for each acceptance criterion." + +- [ ] **Step E: On PASS, merge** + +```bash +git -C /Users/z/Documents/GitHub/toaster merge --no-ff phase-b/<task-slug> -m "Merge phase-b/<task-slug>: <one-line summary>" +git -C /Users/z/Documents/GitHub/toaster push +git -C /Users/z/Documents/GitHub/toaster worktree remove .claude/worktrees/<task-slug> +git -C /Users/z/Documents/GitHub/toaster branch -d phase-b/<task-slug> +``` + +On FAIL or CANT_TELL: one revision cycle (builder fixes, same reviewer re-checks). A second FAIL or +CANT_TELL routes to the ACE per `orchestrator-protocol`'s own escalation triggers, not back to the +builder a third time. + +- [ ] **Step F (Pattern-2 tasks only — Tasks 2, 3, 4, 5, 6): dispatch the `simulated-learner` + spot-check**, after merge, on the trimmed notebook. Use the `Agent` tool, `subagent_type: + "simulated-learner"`, with a persona per the `user-testing` skill's own protocol, prompt: + "Read and execute `<notebook path>` on the merged `diagram-text-integration` branch. Specifically + check whether the trimmed `print()` cell plus the chapter's own structure diagram still let you + reconstruct what the chapter's own judgment record (`<the specific judgment record this + notebook's remainder depends on>`) needs — the attribute values, requirement body, or + metadata-tag content the diagram cannot show. Report PASS or NEEDS-FIX per the `user-testing` + skill's fixed report format." If NEEDS-FIX, route to the ACE (this is new reader-facing evidence + contradicting an already-merged change, not a routine revision cycle). + +--- + +## Task 1: Chapter 1 (System and Purpose) + +**Files:** +- Modify: `chapters/ch01-system-purpose/01-abstract-def.ipynb`, `02-part-def.ipynb`, + `03-specialization.ipynb`, `04-composition.ipynb` + +**Blast zone:** exactly these four notebooks. No `index.md` change (survey found no drift). + +**Acceptance criteria** (verbatim from the survey's Chapter 1 table): + +1. `01-abstract-def.ipynb`, cell 8 (`cell-07`): remove the `print(TOASTER_INCREMENT)` line only. + Before: + ```python + TOASTER_INCREMENT = f"{BREAD_DEF}\n{TOAST_DEF}\n{TOASTBREAD_DEF}\n{TOASTING_SYSTEM_DEF}" + print(TOASTER_INCREMENT) + source = Path("../../models/ch01-cumulative.sysml").read_text() + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + After: + ```python + TOASTER_INCREMENT = f"{BREAD_DEF}\n{TOAST_DEF}\n{TOASTBREAD_DEF}\n{TOASTING_SYSTEM_DEF}" + source = Path("../../models/ch01-cumulative.sysml").read_text() + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + No other cell in this notebook changes — cells 12/14's existing `model.find()` calls already + serve as the confirmation; the existing seam cell (16) already points at them, not at the + removed print. + +2. `02-part-def.ipynb`, cell 6 (`cell-06`): same single-line removal. + Before: `TOASTER_INCREMENT = f"{HEATING_SYS_DEF}\n{CONTROL_SYS_DEF}"` + `print(TOASTER_INCREMENT)` + + the load block. + After: same minus the `print(TOASTER_INCREMENT)` line. + Cells 11 (bridge) and 12 (diagram) are unchanged — already correctly positioned. The existing + seam cell (16) already refers to the still-present individual fragment prints and the cell-10 + query, not the removed reprint, so it needs no edit. + +3. `03-specialization.ipynb`, cell 4 (`cell-04`): same single-line removal. + Before: `TOASTER_INCREMENT = TOASTER_SPEC_DEF` + `print(TOASTER_INCREMENT)` + the load block. + After: same minus the print line. + Cell 8's existing `toaster.specializations` query already serves as the confirmation; seam cell + 10 is unaffected. + +4. `04-composition.ipynb`, cell 8 (`cell-08`) AND seam cell 18 (`cell-13`) both change: + Cell 8 before: + ```python + TOASTER_INCREMENT = f"{TOASTER_DEF}\n{CYCLE_TIME_ATTR}\n{HEATING_PART}\n{CONTROL_PART}\n}}" + print(TOASTER_INCREMENT) + source = Path("../../models/ch01-cumulative.sysml").read_text() + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + Cell 8 after: same minus the print line. + Seam cell 18 before: "`part def Toaster :> ToastingSystem { ... }` printed above loaded without + error, and `toaster.parts()` returns the two part symbols shown below, confirming the + composition is now part of the model." + Seam cell 18 after: "The assembled `Toaster` declaration loaded without error, and the diagram + above confirms `heating` and `control` are part of the model." + This is the one notebook in this chapter where the seam cell MUST change — it quotes a literal + closed-brace block only the removed print ever produced, so leaving it as-is would make it + factually wrong once the print is gone. Cells 13 (bridge) and 14 (diagram) are unchanged. + +**Non-goals:** Do not touch the single-sentence figure captions in `02-part-def.ipynb` cell 13 or +`04-composition.ipynb` cell 15 (survey flagged these as pre-existing style-guide drift, out of +scope for this redesign). Do not touch `index.md` (no drift found). + +**Simulated-learner spot-check:** not required (no Pattern-2 trim in this chapter). + +--- + +## Task 2: Chapter 2 (Requirements and Assumptions) + +**Files:** +- Modify: `chapters/ch02-requirements/01-requirement-def.ipynb`, `02-assumptions.ipynb`, + `03-judgment-context.ipynb` + +**Blast zone:** exactly these three notebooks. No `index.md` change (survey found no drift). + +**Acceptance criteria:** + +1. `03-judgment-context.ipynb`, cell 2 (Pattern 2): replace the full `print(source)` dump with an + excerpt covering only the `TimelyToast` requirement body and the `cycleTime` override line. + Before: + ```python + from pathlib import Path + import opensysml + from toaster.report import format_diagnostics + + conn = opensysml.connect(version="v0.9.0") + source = Path("../../models/ch02-cumulative.sysml").read_text() + print(source) + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + After: + ```python + from pathlib import Path + import opensysml + from toaster.report import format_diagnostics + + conn = opensysml.connect(version="v0.9.0") + source = Path("../../models/ch02-cumulative.sysml").read_text() + requirement_block = source[source.index("requirement def"):source.index("part nominal")].strip() + override_line = next(l.strip() for l in source.splitlines() if "attribute :>> cycleTime" in l) + print(requirement_block) + print(override_line) + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + Builder must re-verify this still executes correctly against the live `models/ch02-cumulative.sysml` + (the survey verified this by direct execution against the file as of 2026-10-02; confirm the + file hasn't changed shape since, and if it has, report a FAIL to the reviewer rather than + silently adjusting the slice logic). + +2. `03-judgment-context.ipynb`, cells 8–12 (newly resolved by DL-093, NOT in the survey's own + table — this notebook's judgment-record tag anchor, per `toaster-review-protocol`'s own + now-fixed "assign, not print" rule): locate the cell matching the pattern `TOASTER_INCREMENT = + <tag fragment variable>` followed immediately by `print(TOASTER_INCREMENT)` (this is the + anchor-group's own second code cell, per `toaster-review-protocol/SKILL.md`'s documented + construction-zone shape — the tag fragment itself, e.g. `REVIEW_RECORD_REF_DEF`/`AC001_TAG` or + however this notebook's own variables are actually named, was already printed in the cell(s) + immediately before it). Remove only the `print(TOASTER_INCREMENT)` line; keep the assignment. + Do not touch the markdown narration immediately before or after this cell unless it explicitly + says "printed above" about the now-removed reprint specifically (if so, reword minimally to + point at the individual tag-fragment prints instead, matching the style of Task 1's `04-composition.ipynb` + seam-cell fix above). Confirm the notebook's own later `get_review_record_refs(model)` / + `Model tag:` print (per the Ch2 survey's own report, this already exists later in the notebook) + is untouched and still runs — this is the confirmation step DL-093 relies on; do not add a new + one. + +3. `01-requirement-def.ipynb`, cell 8, AND seam cell 13: + Cell 8 before: `TOASTER_INCREMENT = f"{TIMELY_TOAST_REQ}{CONSTRAINT_BODY}\n}}\n{NOMINAL_PART}"` + + `print(TOASTER_INCREMENT)` + load block. + Cell 8 after: same minus the print line. + Seam cell 13 before: "The `requirement def TimelyToast { doc /* ... */ subject toaster : + Toaster; require constraint { toaster.cycleTime <= 180.0 [SI::s] } }` printed above loaded + without error, and `model.find()` returns its symbol while `model.query()` lists it as a + `RequirementDefinition`, confirming it's now part of the model." + Seam cell 13 after: "The `TimelyToast` fragments printed above loaded without error, and + `model.find()`/`model.query()` confirm it's now part of the model." + (Must change — quotes a closed-brace block only the removed print produced.) + +4. `02-assumptions.ipynb`, cell 6, AND seam cell 11: + Cell 6 before: `TOASTER_INCREMENT = f"{SLOW_PART}\n{CYCLE_OVERRIDE}\n}}"` + `print(TOASTER_INCREMENT)` + + load block. + Cell 6 after: same minus the print line. + Seam cell 11 before: "The `part slow : Toaster { attribute :>> cycleTime = 200.0 [SI::s]; }` + printed above loaded without error, and `slow.attributes()` returns the overridden symbol shown + above, confirming the redeclaration is now part of the model." + Seam cell 11 after: "The `slow` fragments printed above loaded without error, and + `slow.attributes()` confirms the override is now part of the model." + (Must change — same reason as item 3.) + +**Non-goals:** Do not touch any other cell in `03-judgment-context.ipynb` beyond cell 2 and the +cells-8–12 anchor fix. Do not resolve the `assumption_refs`/record-triad methodological question +this notebook's own judgment record raises (DL-075, closed by DL-084 — not reopened here). + +**Simulated-learner spot-check: required**, on `03-judgment-context.ipynb` post-merge. Check +specifically whether the requirement/override excerpt plus the structure diagram still lets the +reader see what the AC-001 judgment record (asserted context) needs: that `TimelyToast` is bound +by a real constraint and that `slow` really overrides `cycleTime` to 200s. + +--- + +## Task 3: Chapter 3 (Measures of Success) + +**Files:** +- Modify: `chapters/ch03-measures/01-moe-definition.ipynb`, `02-mop-candidate-eval.ipynb`, + `03-threshold-judgment.ipynb`, `04-verification-case.ipynb` + +**Blast zone:** exactly these four notebooks. No `index.md` change (survey found no drift). + +**Acceptance criteria:** + +1. `03-threshold-judgment.ipynb`, cell 2 (Pattern 2): replace the full `print(source)` dump (81 + lines as of 2026-10-02 — use the real, current line count, not the spec's stale "83") with: + ```python + lines = source.splitlines() + excerpt = "\n".join(lines[35:47] + [" ..."] + lines[61:65] + [" ..."] + lines[66:80]) + print(excerpt) + ``` + inserted where `print(source)` currently is (keep `source = Path(...).read_text()` and the + `model = conn.load_from_content(...)` / `assert model.ok` lines unchanged, exactly as the + survey's own proposed content shows). Builder must re-verify the line ranges `35:47` (the + `TimelyToast` requirement def + usage), `61:65` (the `slow` override + folded satisfy claim), + and `66:80` (`TimelyToastTest`) against the live file before committing — if the file has moved + since 2026-10-02, recompute the ranges by searching for `requirement def TimelyToast`, `part + slow : Toaster {`, and `verification def TimelyToastTest` rather than trusting the hardcoded + numbers, and report the new ranges to the reviewer explicitly as a deviation (not a silent + change). + +2. `03-threshold-judgment.ipynb`, cell 13 (second finding, same notebook, already resolved by + DL-093 and already given full content in the survey): remove the `print(TOASTER_INCREMENT)` + line only. + Before: `TOASTER_INCREMENT = AS_C03_TAG` + `print(TOASTER_INCREMENT)`. + After: `TOASTER_INCREMENT = AS_C03_TAG` (print line removed). + The existing cell-23 `get_review_record_refs(model)` confirmation, narrated by cell 24, is + untouched and already serves as the confirmation. + +3. `01-moe-definition.ipynb`, cell 11: remove the print line only. + Before: `TOASTER_INCREMENT = f"{TIMELY_USAGE}\n{AC_C03_TAG}"` + `print(TOASTER_INCREMENT)`. + After: same minus the print line. + Existing cell 6 (`model.find`+`model.query` for `TIMELY_USAGE`) and cell 23 + (`get_review_record_refs` for the metadata tag) already serve as confirmations. + +4. `02-mop-candidate-eval.ipynb`, cell 4: remove the print line only. + Before: + ```python + SLOW_WITH_CLAIM = ( + "part slow : Toaster {\n" + " attribute :>> cycleTime = 200.0 [SI::s];\n" + f"{SLOW_NOT_SATISFY}\n" + "}" + ) + TOASTER_INCREMENT = SLOW_WITH_CLAIM + print(TOASTER_INCREMENT) + + source = Path("../../models/ch03-cumulative.sysml").read_text() + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + After: same minus the `print(TOASTER_INCREMENT)` line. Existing cell 8 (`satisfy_relationships` + + `model.eval()`) already serves as the confirmation, narrated by seam cell 10. + +5. `04-verification-case.ipynb`, cell 10: remove the print line only. + Before: `TOASTER_INCREMENT = f"{VERIF_DEF_OPEN}\n{DOC_COMMENT}\n{SUBJECT_DECL}\n{OBJECTIVE_BODY}\n}}"` + + `print(TOASTER_INCREMENT)` + load block. + After: same minus the print line. Existing cell 14 (`model.find()`+`model.query()`) already + serves as the confirmation, narrated by seam cell 15. + +**Non-goals:** Do not touch the `TimelyToast` `doc` block's own cross-chapter duplication with +Chapter 2 (survey explicitly declined to touch this as outside Pattern 2's own scope). + +**Simulated-learner spot-check: required**, on `03-threshold-judgment.ipynb` post-merge. Check +whether the trimmed excerpt plus the chapter's own parts-only diagram still lets the reader see +`TimelyToast`'s own threshold, the `slow` candidate's failure, and what `TimelyToastTest` checks. + +--- + +## Task 4: Chapter 4 (Functional Decomposition) + +**Files:** +- Modify: `chapters/ch04-functional-decomp/01-action-def-ffbd.ipynb`, `02-heating-refinement.ipynb`, + `03-completeness-check.ipynb` + +**Blast zone:** exactly these three notebooks. No `index.md` change (already confirmed accurate). + +**Acceptance criteria:** + +1. `01-action-def-ffbd.ipynb`, cell 14 (Pattern 1): remove the print line only; cells 15 (bridge) + and 16 (diagram, renders `ToastBread`) are unchanged. + Before: + ```python + TOASTBREAD_REOPENED = ( + "action def ToastBread {\n" + " doc /* Transform bread into toast acceptable to its user. */\n" + " in bread : Bread;\n" + " out toast : Toast;\n" + f"{TOASTBREAD_SEQUENCE}\n" + "}" + ) + TOASTER_INCREMENT = f"{APPLY_HEAT_DEF}\n{TOASTBREAD_REOPENED}" + print(TOASTER_INCREMENT) + + source = Path("../../models/ch04-cumulative.sysml").read_text() + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + After: same minus the `print(TOASTER_INCREMENT)` line. + +2. `02-heating-refinement.ipynb`, cell 8 (Pattern 1b): remove the print line only. + Before: `TOASTER_INCREMENT = f"{START_DEF}\n{FINISH_DEF}\n{CANCEL_DEF}"` + `print(TOASTER_INCREMENT)` + + load block. + After: same minus the print line. Existing cell 12 (`model.find()` loop over `Start`/`Finish`/`Cancel`) + already serves as the confirmation. + +3. `03-completeness-check.ipynb`, cell 2 (Pattern 2): replace the full 117-line `print(source)` + dump with: + ```python + lines = source.splitlines() + new_this_chapter = "\n".join(lines[16:32] + lines[37:47] + lines[107:116]) + print(new_this_chapter) + ``` + (keep `source = Path(...).read_text()` and the load/assert lines unchanged). Builder must + re-verify ranges `16:32` (`ApplyHeat`), `37:47` (`ToastBread`'s reopened body), `107:116` (the + three item defs) against the live `models/ch04-cumulative.sysml` before committing, same + deviation-reporting rule as Task 3 item 1. + +4. `03-completeness-check.ipynb`, cells 9–11 (newly resolved by DL-093, NOT in the survey's own + table — the `AI_C04_TAG` judgment-record anchor): remove only the `print(TOASTER_INCREMENT)` + line from the cell matching `TOASTER_INCREMENT = AI_C04_TAG` (or however this notebook's own + variable is named — confirm against the live cell before editing, per the same bounded + search-and-verify procedure as Task 2 item 2). Keep the assignment. Confirm cell 28's existing + `tag = next(...); print(f"Model tag: {tag}")` confirmation is untouched and still runs. + +**Non-goals:** Do not touch the single-sentence captions in `01-action-def-ffbd.ipynb` cell 17 or +the bridge sentence in `03-completeness-check.ipynb` cell 3 (survey flagged both as pre-existing +style issues, out of scope). Do not reclassify this notebook's own status in +`decisions/declarative-construction-plan.md` (that document's staleness is DL-093's own concern, +not this task's — do not edit that file). + +**Simulated-learner spot-check: required**, on `03-completeness-check.ipynb` post-merge. Check +whether the 35-line excerpt plus the chapter's own scoped (`Toaster`/depth-2) diagram still lets +the reader see `ApplyHeat`'s balance constraint, `ToastBread`'s reopened sequence, and the three +item defs well enough to follow the completeness-check judgment record that follows. + +--- + +## Task 5: Chapter 5 (Architecture and Allocation) + +**Files:** +- Modify: `chapters/ch05-architecture/01-model-navigation.ipynb`, `02-allocate.ipynb`, + `03-interfaces.ipynb`, `index.md` + +**Blast zone:** exactly these three notebooks plus `index.md`. + +**Acceptance criteria:** + +1. `01-model-navigation.ipynb`, cell 2 (Pattern 2, residual: none): delete the `print(source)` + line entirely — no replacement excerpt. The chapter's own unscoped diagram was independently + confirmed (by both the Ch5 survey agent and the orchestrator's own spot-check against the real + `figures/ch05-structure.svg`) to cover every structural fact in the dump; this notebook's own + narrow teaching purpose (`model.find()`/`model.get()` navigation) needs none of the non-structural + content the dump also showed. + +2. `02-allocate.ipynb`, cell 6 (Pattern 1b): remove the print line only. + Before: `TOASTER_INCREMENT = f"{HEATING_SYSTEM_DEF}\n{TOASTER_WITH_ALLOCATION}"` + + `print(TOASTER_INCREMENT)` + load block. + After: same minus the print line. Existing cell 10 (`find_allocations`/`perform_relationships`) + already serves as the confirmation. Seam cell 12 currently says "The definitions printed above + loaded without error..." — reword minimally to "The assembled definitions loaded without + error..." (do not invent new content; this is the same class of fix as Task 1's + `04-composition.ipynb` and Task 2's seam fixes — only reword the clause that would otherwise + misdescribe what happened). + +3. `03-interfaces.ipynb`, cell 10 (Pattern 1): remove the print line only. + Before: `TOASTER_INCREMENT = (f"{DURATION_PORT_DEF}\n{HEATING_SYSTEM_PORT}\n{CONTROL_SYSTEM_PORT}\n{TOASTER_WITH_INTERFACE}")` + + `print(TOASTER_INCREMENT)` + load block. + After: same minus the print line. Existing cell 14 (`port_type_mismatches`) already serves as + the confirmation; cell 16's diagram (`render_toolkit_interconnection`) is unchanged. Seam cell 18 + currently says "The port and interface definitions printed above loaded without error..." — + same minimal reword as item 2 above. + +4. `index.md` line 17: fix the heading-case drift. + Before: `[01: Model Navigation](01-model-navigation.ipynb)` + After: `[01: model navigation](01-model-navigation.ipynb)` + (Only the link text's case changes; the rest of the row, and every other row, is untouched.) + +**Non-goals:** Do not propose or make any further change to `02-allocate.ipynb` or +`03-interfaces.ipynb` beyond item 2/3 above — the survey's own open question (whether these two +notebooks also re-print the full dump) was investigated and found to be a factual error in the +*prior* `decisions/diagram-survey.md` document, not a real defect in these live files; see Task 10 +for the document correction. Do not touch `03-interfaces.ipynb`'s own `render_toolkit_interconnection()` +diagram cell. + +**Simulated-learner spot-check: required**, on `01-model-navigation.ipynb` post-merge. Check +specifically whether removing the dump entirely (residual: none) still leaves the reader able to +follow the `model.find()`/`model.get()` navigation this notebook actually teaches, given only the +diagram and cell 1's own prose summary. + +--- + +## Task 6: Chapter 6 (Recursive Decomposition) + +**Files:** +- Modify: `chapters/ch06-recursive-decomp/01-subsystem-requirements.ipynb`, `02-second-level.ipynb`, + `03-stopping-judgment.ipynb`, `index.md` + +**Blast zone:** exactly these three notebooks plus `index.md`. + +**Acceptance criteria:** + +1. `03-stopping-judgment.ipynb`, cell 2 AND markdown wrap-up cell 3 (Pattern 2, the largest cut in + the tutorial — 213 lines to 66): + Cell 2 after (replace the full `print(source)` dump with): + ```python + lines = source.splitlines() + print("\n".join(lines[137:164] + lines[173:212])) + ``` + (keep the `source = Path(...).read_text()` / load / assert lines unchanged). Builder must + re-verify ranges `137:164` (`EnergyPort` through `HeatGenerator`) and `173:212` + (`HeatGenerationReq` through `weak`) against the live `models/ch06-cumulative.sysml`, same + deviation-reporting rule as Task 3/4. + Cell 3 before: "The cumulative model prints above: `GenerateHeat` nested inside `ApplyHeat`, + `HeatGenerator` performing it through a declared energy port, `HeatingAssembly` composing that + carrier, the usage-level allocation between them, and `ResistanceCoil`'s two candidates, `rated` + and `weak`, checked against `heatGenerationReq`. The next cell checks what happens when an + inference record's own required field is left empty." + Cell 3 after: "HeatGenerator, EnergyPort, HeatGenerationReq, ResistanceCoil, rated and weak + loaded without error, and the diagram confirms HeatingAssembly composing heatGen, typed by + HeatGenerator. The next cell checks what happens when an inference record's own required field + is left empty." (Must change — the original names facts, like the allocation, the trimmed print + no longer shows.) + +2. `03-stopping-judgment.ipynb`, cell 11 (second finding, resolved by DL-093 — already given full + content in the survey, previously flagged "if adopted," now unconditional): remove the print + line only. + Before: `TOASTER_INCREMENT = AI_C06_TAG` + `print(TOASTER_INCREMENT)`. + After: `TOASTER_INCREMENT = AI_C06_TAG` (print line removed; assignment kept — required by + `scripts/check_construction.py`). Existing cell 22 (`get_review_record_refs`) already serves as + the confirmation. + +3. `01-subsystem-requirements.ipynb`, cell 14 (Pattern 1): remove the print line only. + Before: `TOASTER_INCREMENT = (f"{GENERATE_HEAT_DEF}\n{ENERGY_PORT_DEF}\n{APPLY_HEAT_INCREMENT}\n{HEAT_GENERATOR_DEF}\n{HEATING_ASSEMBLY_DEF}")` + + `print(TOASTER_INCREMENT)` + load block. + After: same minus the print line. The two existing diagrams (action-flow + interconnection) + immediately after are unchanged; cell 20's "printed above" claim resolves to the still-present + individual fragment prints (cells 2/4/6/8/10), unaffected. + +4. `02-second-level.ipynb` (Phase A coverage gap — the survey's own Ch6 agent did not report on + this notebook at all, despite being asked to check it; closing that gap is this task's own + responsibility, not a re-opening of Phase A): read this notebook cell by cell first. If it has + a construction-zone reflection-print duplication (a `TOASTER_INCREMENT = ...` assignment + immediately followed by `print(TOASTER_INCREMENT)`, reprinting fragments already printed + individually above it), apply Pattern 1b exactly as every other instance in this plan: remove + only the print line, keep the assignment, and confirm whether an existing `model.find()`/ + `model.query()`/`model.eval()` or `query.py`-helper confirmation already exists later in the + notebook (if so, rely on it and add nothing; if genuinely none exists, add one short confirmation + cell against the construct this notebook declares, in the same idiom Task 7 item 2 below uses + for `ch07/01-calc-energy.ipynb`). If this notebook has no construction zone at all, report "no + construction zone, no finding" to the reviewer — do not force a finding. Report the actual cell + content found (not a placeholder) in the builder's own report, so the reviewer can verify it + against the live file directly, the same rigor every other item in this plan already has. + +5. `index.md`: fix the heading-case drift in all three rows. + Before: + ``` + [01: Level-2 Function and Logical Carrier](01-subsystem-requirements.ipynb) + [02: Level-2 Physical Realization](02-second-level.ipynb) + [03: Stopping Judgment](03-stopping-judgment.ipynb) + ``` + After: + ``` + [01: level-2 function and logical carrier](01-subsystem-requirements.ipynb) + [02: level-2 physical realization](02-second-level.ipynb) + [03: stopping judgment](03-stopping-judgment.ipynb) + ``` + (Only the link text's case changes in each row; concept-column prose and hrefs untouched.) + +**Non-goals:** Do not touch the `assumption_refs` text in cell 16 (survey confirmed it already +supports the Pattern-2 trim correctly; no change needed, verify only). Do not fix the three real +em-dash violations the Ch7 survey found (different chapter, out of this task's blast zone). + +**Simulated-learner spot-check: required**, on `03-stopping-judgment.ipynb` post-merge — this is +the single largest cut in the tutorial. Check specifically whether the 66-line excerpt plus the +scoped (`HeatingAssembly`/depth-2) diagram still lets the reader see `HeatGenerationReq`'s own +threshold and both `rated`/`weak` candidates' values well enough to follow the stopping-judgment +record that depends on them. + +--- + +## Task 7: Chapter 7 (Execution and Experiments) + +**Files:** +- Modify: `chapters/ch07-execution/01-calc-energy.ipynb`, `02-state-traces.ipynb` + +**Blast zone:** exactly these two notebooks (`03-param-sweep.ipynb` and `index.md` are both +confirmed to need no change — the survey found this chapter's own index table already matches its +notebooks byte-for-byte, including the apostrophe form). + +**Acceptance criteria:** + +1. `02-state-traces.ipynb`, cell 16 (Pattern 1): remove the print line only; cells 17 (bridge) and + 18 (diagram) are unchanged. + Before: `TOASTER_INCREMENT = f"{CYCLE_DEF}\n{TOASTING_SYSTEM_INCREMENT}"` + `print(TOASTER_INCREMENT)` + + load block. + After: same minus the `print(TOASTER_INCREMENT)` line (and its trailing blank line). + +2. `01-calc-energy.ipynb`, cell 9 AND markdown cell 10 (Pattern 1b — this is the ONE notebook in + this entire plan where a genuinely NEW confirmation cell must be added, since no existing query + elsewhere in the notebook covers this construct): + Cell 9 before: + ```python + TOASTER_INCREMENT = f"{HEAT_GENERATOR_INCREMENT}\n{RATED_INCREMENT}" + print(TOASTER_INCREMENT) + + source = Path("../../models/ch07-cumulative.sysml").read_text() + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + ``` + Cell 9 after: + ```python + TOASTER_INCREMENT = f"{HEAT_GENERATOR_INCREMENT}\n{RATED_INCREMENT}" + + source = Path("../../models/ch07-cumulative.sysml").read_text() + model = conn.load_from_content(source, strict=False) + assert model.ok, f"Model failed: {format_diagnostics(model.diagnostics)}" + delivered_energy = model.find("ToasterDemo::HeatGenerator::deliveredEnergy") + print(f"HeatGenerator::deliveredEnergy: kind={delivered_energy.kind!r}, id={delivered_energy.id!r}") + ``` + Cell 10 (markdown) before: "A constraint that references an attribute the definition never + declares fails to load. The negative control below asserts a bound on a name `Widget` does not + have." + Cell 10 after: "`HeatGenerator::deliveredEnergy` is now part of the loaded model, confirmed by + `model.find`. A constraint that references an attribute the definition never declares fails to + load. The negative control below asserts a bound on a name `Widget` does not have." + +**Non-goals:** Do not touch `03-param-sweep.ipynb` (confirmed to have no construction zone at all +— `cell 2` loads the cumulative model directly). Do not fix the three em-dash violations in +`02-state-traces.ipynb` cells 29/32, or the two intermediate sub-assembly reprints flagged in the +survey's open questions (cell 12 of `02-state-traces.ipynb`, cell 7 of `01-calc-energy.ipynb`) — +both outside the two named patterns' own scope, per the survey's own explicit flag-not-fix +instruction. Do not touch `index.md` (confirmed byte-for-byte accurate, including the apostrophe +form). + +**Simulated-learner spot-check:** not required (no Pattern-2 trim in this chapter; the changes are +small single-line removals plus one short addition, not material prose shrinkage). + +--- + +## Task 8: Chapter 8 (Checking and Revision) + +**Files:** +- Modify: `chapters/ch08-checking/01-invariant-def.ipynb` (renamed to + `01-assert-constraint-def.ipynb`), `02-violation-witness.ipynb`, `index.md` +- Modify (reference updates for the rename): `myst.yml`, `exercises/ch08/exercise.ipynb`, + `scripts/check_construction.py`, `DEFERRED.md` + +**Blast zone:** exactly the two Ch8 notebooks, Ch8's own `index.md`, plus the 5 named cross-chapter +reference files below (not 6 — the rename touches the notebook's own index.md, counted once, plus +5 other files; see Step 2 for the authoritative enumeration matching the survey's own RENAME +section exactly). + +**Acceptance criteria:** + +1. `01-invariant-def.ipynb`, cell-08 (Pattern 1b): remove the print line only. + Before: `TOASTER_INCREMENT = f"{HEAT_GEN_CHECK_USAGE}\n{CHECK_DURATION_ATTR}\n\n{DELIVERED_ENERGY_BOUND}\n"` + + `print(TOASTER_INCREMENT)` + load block. + After: same minus the print line. Existing cell-09/cell-10 (`model.find()`+`model.query()`) + already serves as the confirmation. Diagram cells (cell-03a/03b/03d) are already correct — + confirmed by the survey, no change. + +2. `02-violation-witness.ipynb`, cell-20 (Pattern 1b): remove the print line only. + Before: `TOASTER_INCREMENT = AS_C08_TAG` + `print(TOASTER_INCREMENT)`. + After: `TOASTER_INCREMENT = AS_C08_TAG` (print line removed). Rely on the existing later + cell-32/33 `get_review_record_refs` confirmation — do not insert a nearer one (the survey's own + open question recommended relying on the existing one for parsimony; this plan adopts that + recommendation). + +3. **Rename, exactly as the survey's own RENAME section specifies:** + - `git mv chapters/ch08-checking/01-invariant-def.ipynb chapters/ch08-checking/01-assert-constraint-def.ipynb` + - Update `myst.yml` line ~67: `- file: chapters/ch08-checking/01-invariant-def` → + `- file: chapters/ch08-checking/01-assert-constraint-def` + - Update `chapters/ch08-checking/index.md` line 17's link target (see item 4 below, same edit). + - Update `chapters/ch08-checking/02-violation-witness.ipynb`, cell-01 (markdown): `See + [Ch8-01](01-invariant-def.ipynb) for the construct itself.` → `See + [Ch8-01](01-assert-constraint-def.ipynb) for the construct itself.` (link target only — the + surrounding sentence is untouched). + - Update `exercises/ch08/exercise.ipynb` line ~28: the prose path reference + `chapters/ch08-checking/01-invariant-def.ipynb` → `chapters/ch08-checking/01-assert-constraint-def.ipynb`. + - Update `scripts/check_construction.py` line ~280: the registry entry `"path": + "chapters/ch08-checking/01-invariant-def.ipynb"` → `"path": + "chapters/ch08-checking/01-assert-constraint-def.ipynb"`. + - Update `DEFERRED.md` lines ~693 and ~798 (D-029/D-030/D-031's own live "Workaround" notes that + point at this file by path) — update the path reference only, do not touch surrounding prose. + - Do NOT touch: `decisions/diagram-survey.md`, `decisions/log.md`, `decisions/audits/ch08-layer-audit.md`, + `decisions/user-testing-grid/M2-practitioner.md`, `docs/superpowers/plans/2026-10-01-diagram-survey-phase2-plan.md` + (all historical-record files, per the exact convention the Ch5 rename precedent already + established — leave the old filename string in all of these). Also do NOT touch this Phase B + plan file itself or the governing spec (both name the old filename as a record of what Phase A + found; leave them as-is, per the survey's own explicit recommendation). + - After the rename, grep the whole repo for the literal string `invariant-def` and confirm the + only remaining hits are in the 5 historical/ambiguous files just listed as untouched, plus + this plan document and the governing spec. + +4. `index.md`: fix the separator convention (dash → colon) in all three rows, and update row 1's + link target for the rename. + Before: + ``` + | [01 - assert constraint](01-invariant-def.ipynb) | State `deliveredEnergyBoundedBySupply` as a real SysML constraint; confirm it is really in the loaded model. | + | [02 - proof versus point evaluation](02-violation-witness.ipynb) | Contrast `verify_holds()`'s universal proof with `verify_satisfaction()`'s point evaluation; show the loop catching a fully broken variant as `violated` and a merely weakened variant as `undecided`; record the proof as engineering evidence with its own real limits stated. | + | [03 - stale record detection](03-revision-flow.ipynb) | Loosen the lemma's own bound; show `check_stale()` marking the existing record for re-review. | + ``` + After: + ``` + | [01: assert constraint](01-assert-constraint-def.ipynb) | State `deliveredEnergyBoundedBySupply` as a real SysML constraint; confirm it is really in the loaded model. | + | [02: proof versus point evaluation](02-violation-witness.ipynb) | Contrast `verify_holds()`'s universal proof with `verify_satisfaction()`'s point evaluation; show the loop catching a fully broken variant as `violated` and a merely weakened variant as `undecided`; record the proof as engineering evidence with its own real limits stated. | + | [03: stale record detection](03-revision-flow.ipynb) | Loosen the lemma's own bound; show `check_stale()` marking the existing record for re-review. | + ``` + (Only the separator character and row 1's link target change; concept-column prose untouched.) + +**Non-goals:** Do not touch `03-revision-flow.ipynb` (confirmed to have no construction zone). +Do not resolve whether `02-violation-witness.ipynb` should get a nearer confirmation query (survey's +own open question; this plan's item 2 above already adopts the "rely on the existing one" answer — +do not re-litigate). + +**Simulated-learner spot-check:** not required (no Pattern-2 trim in this chapter). + +--- + +## Task 9: Chapter 10 (Traceability and Sign-off) + +**Files:** +- Modify: `chapters/ch10-traceability-signoff/01-traceability-graph.ipynb`, `index.md` + +**Blast zone:** exactly this one notebook plus `index.md` (`02-judgment-synthesis.ipynb` and +`03-engineering-signoff.ipynb` are both confirmed to have no construction zone — no change). + +**Acceptance criteria:** + +1. `01-traceability-graph.ipynb`, cell 33 (delete) and cell 32 (one-word edit) — already resolved + as in-scope by DL-093 ("the survey's proposed deletion plus the one-word edit to cell 32 + stands"): + Cell 32 (markdown) before, last sentence: "The subsetting construct below is how that is + stated." + Cell 32 after, last sentence: "The subsetting construct shown above is how that is stated." + Cell 33 (code) before: `print(ENERGY_CONSERVATION_REQ_DEF)` — a verbatim reprint of cell 27's + own fragment. + Cell 33 after: deleted outright. Cell 34's markdown ("`models/ch10-cumulative.sysml` already + carries this construct forward...") still reads correctly immediately after cell 32 with no + cell 33 between them. + +2. `index.md`: fix the separator convention (dash → colon) in all three rows. + Before: + ``` + | [01 - traceability graph](01-traceability-graph.ipynb) | ... | + | [02 - judgment ledger](02-judgment-synthesis.ipynb) | ... | + | [03 - engineering synthesis](03-engineering-signoff.ipynb) | ... | + ``` + After (concept-column text unchanged — only the bracketed link-text prefix in each row + changes): + ``` + | [01: traceability graph](01-traceability-graph.ipynb) | ... | + | [02: judgment ledger](02-judgment-synthesis.ipynb) | ... | + | [03: engineering synthesis](03-engineering-signoff.ipynb) | ... | + ``` + +**Non-goals:** Do not touch `02-judgment-synthesis.ipynb` or `03-engineering-signoff.ipynb` (both +confirmed to have no construction zone). Do not touch the diagram in cell 6 (confirmed unscoped and +unaffected by the cell 33 fix). + +**Simulated-learner spot-check:** not required (no Pattern-2 trim; this is a single-cell deletion +plus a one-word wording fix, not material prose shrinkage). + +--- + +## Task 10: Correct the factual error in `decisions/diagram-survey.md` (administrative, not a contract) + +**Files:** +- Modify: `decisions/diagram-survey.md` +- Modify: `decisions/log.md` (new DL entry) + +This is the orchestrator's own established administrative record-keeping role — the same role used +compiling both `decisions/diagram-survey.md` (Phase 1) and `decisions/diagram-text-integration-survey.md` +(Phase A) — not a builder contract, per spec Decision 3's own carve-out. No worktree, no builder, +no reviewer; the orchestrator makes this edit directly and logs it. + +- [ ] **Step 1: Correct the row.** + `decisions/diagram-survey.md` line 169, currently: + ``` + | `02-allocate.ipynb` cell-06 / `03-interfaces.ipynb` cell-10 | same 131-line dump, repeated verbatim | — | — | **no candidate** | — | Identical content already shown once in this chapter; a second/third copy would be diagram fatigue, not a real reduction in parsing burden. | + ``` + Replace with: + ``` + | `02-allocate.ipynb` cell-06 / `03-interfaces.ipynb` cell-10 | ~~same 131-line dump, repeated verbatim~~ — **correction, 2026-10-02 (diagram/text integration Phase A):** this row was factually wrong. Direct re-read of the live files (and of this document's own commit history) confirms neither cell ever printed the full 131-line dump — each prints only its own small `TOASTER_INCREMENT` fragment (9 and ~15 lines respectively). See `decisions/diagram-text-integration-survey.md`'s own Chapter 5 section for the real finding and fix. | — | — | **no candidate** | — | Identical content already shown once in this chapter; a second/third copy would be diagram fatigue, not a real reduction in parsing burden. (Rationale for "no candidate" stands; the premise describing what these two cells print was wrong, not the conclusion.) | + ``` + +- [ ] **Step 2: Log it.** + Append a new `DL-NNN` entry (next sequential number after whatever Phase B's own skill/chapter + work has already logged by the time this step runs — check `decisions/log.md`'s own current max + before assigning) stating: what was wrong (the row above), how it was found (the Ch5 Phase A + survey agent's direct read plus a `git show` of the commit that produced the original document), + that the correction is a one-line edit to a historical document's own factually incorrect premise + (not a reversal of its conclusion), and citing `decisions/diagram-text-integration-survey.md`'s + own cross-chapter open question 3 as the source. + +- [ ] **Step 3: Commit directly** (orchestrator's own administrative role, no worktree needed): + ```bash + git add decisions/diagram-survey.md decisions/log.md + git commit -m "Correct decisions/diagram-survey.md: ch05's claimed triple-dump does not exist in the real files" + git push + ``` + +--- + +## Self-review + +**1. Spec coverage.** Decision 1 (scope: both patterns) → every chapter task covers both Pattern +1/1b and Pattern 2 where applicable. Decision 2 (Approach A) → every Pattern-1 task keeps the +diagram in place and only removes the print; every Pattern-2 task shrinks the dump to the exact +survey-stated residual. Decision 3 (harness) → every chapter task is a CONTRACT.md in its own +worktree with builder sonnet / reviewer opus, zero direct orchestrator edits to chapter content; +Task 10 is explicitly carved out as the one permitted administrative exception, matching the spec's +own Decision 3 language exactly. Decision 4 (enumerated cleanup) → item 1 (index heading drift) in +Tasks 5, 6; item 2 (separator convention) in Tasks 8, 9; item 3 (Ch8 rename) in Task 8; item 4 +(D-037) not reopened anywhere in this plan. Decision 5 (durability) → this plan is fully +self-contained; no task depends on this conversation's own history. + +**2. Placeholder scan.** Every cell-content before/after pair is quoted verbatim from the survey. +The two genuinely new items not in the survey's own table (Task 2 item 2, Task 4 item 4) are given +as bounded, fully-specified mechanical procedures (find this exact pattern shape, remove only this +one line) rather than vague instructions — this mirrors how Phase A's own agents were given +precise search-and-propose instructions rather than pre-written text in cases where the exact +variable names weren't yet known. Task 6 item 4 (the `02-second-level.ipynb` coverage gap) is +likewise a bounded procedure with an explicit "no finding" fallback, not an open "also look for +stuff" instruction — it closes one specific, named Phase A gap, not a new discovery mandate. + +**3. Type consistency.** Every chapter task uses the same acceptance-criteria shape (before/after +code or markdown blocks, quoted verbatim) and the same Non-goals/Simulated-learner-requirement +structure, so the Standard execution procedure applies uniformly across all 9 chapter tasks. + +**4. Review Focus.** All five items are pinned to specific tasks and specific verification steps +above, not left to each task's own judgment alone. + +## Execution handoff + +This plan uses this repo's own established implementation harness — CONTRACT.md per chapter task, +each in its own git worktree, builder `claude-sonnet-5` and reviewer `claude-opus-5-5` (always a +different model), merged by the orchestrator after an independent PASS — exactly the mechanism this +session already used and proved for the DL-092/DL-093 skill fix earlier today. This is not +`writing-plans`' own generic Subagent-driven/Native choice; per spec Decision 5 and +`orchestrator-protocol`'s own "Plan-driven non-chapter work" section, this project's established +contract mechanism is the execution method for this plan, full stop. + +Per the spec's own Process section ("these 9 chapters' own text-integration tasks are independent +of each other... and can run in parallel, the same way Phase 2's 9 chapter tasks did"), Tasks 1–9 +have no inter-task dependency and may be dispatched in parallel, each in its own worktree. Task 10 +(the administrative correction) has no dependency on any other task either and may run at any +point. + +Plan complete and saved to `docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-b-plan.md`. +Please review the plan. Does it capture what you want? From 00822ea83aee32a9ae015b2e47dcef3fb47ede0e Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:39:03 -0400 Subject: [PATCH 09/25] Phase B Ch10: remove cell-33 reflection-print duplication; index.md separator fix --- .../01-traceability-graph.ipynb | 52 +------------------ chapters/ch10-traceability-signoff/index.md | 6 +-- 2 files changed, 4 insertions(+), 54 deletions(-) diff --git a/chapters/ch10-traceability-signoff/01-traceability-graph.ipynb b/chapters/ch10-traceability-signoff/01-traceability-graph.ipynb index 24c156e..d3e6531 100644 --- a/chapters/ch10-traceability-signoff/01-traceability-graph.ipynb +++ b/chapters/ch10-traceability-signoff/01-traceability-graph.ipynb @@ -689,57 +689,7 @@ "id": "13f89b31", "metadata": {}, "source": [ - "Not a pass, an error, for all three bindings actually tested above: `require condition evaluation failed: no value for feature heatGenCheck.efficiency`, identical whether the satisfying feature is the lemma itself, the lemma's own free-standing usage (`heatGenCheck`), or a totally unrelated real candidate (`rated`). This is not a quirk of one binding -- it is demonstrated directly, across three different ones, for the structural reason already named in the doc comment above: `heatGenCheck`/`heatGenCheckDuration` are deliberately left free (the whole point of the Z3 proof is that it holds for every value, not one), so the construct cannot be evaluated at all, regardless of what is bound as the satisfying feature. `requirement_coverage()`'s own `covered=True`/`False` only ever checks whether a non-negated `SatisfyRequirementUsage` *exists*, never whether it actually evaluates -- these cells are the one place in this whole model that actually *runs* the check, and it fails identically every time. This is why `models/ch10-cumulative.sysml` carries no `assert satisfy` for this requirement: not because a tie is missing, but because `satisfy` is the wrong register for what this model actually has. `EnergyConservationReq`'s own required constraint already evaluates true, by construction (it *is* the proved lemma) -- SS7.21.1's own words, \"a requirement is satisfied when it evaluates to true\" -- with no `satisfy` usage needed at all. The subsetting construct below is how that is stated." - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "fe8404d3", - "metadata": { - "execution": { - "iopub.execute_input": "2026-10-01T06:45:43.734876Z", - "iopub.status.busy": "2026-10-01T06:45:43.734800Z", - "iopub.status.idle": "2026-10-01T06:45:43.736780Z", - "shell.execute_reply": "2026-10-01T06:45:43.736319Z" - } - }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "requirement def EnergyConservationReq {\n", - " doc /* A heat generator shall never deliver more energy than it is supplied:\n", - " * energy conservation, a physical law any real heat generator design\n", - " * must obey, independent of any one proof of it. No subject type is\n", - " * declared here: this requirement's own required constraint never\n", - " * references any subject at all -- it is a closed, already-proved\n", - " * proposition over its own free-standing elements -- so declaring\n", - " * one would commit to an arbitrary, unused type, not state anything\n", - " * real; the subject is left to inherit RequirementCheck's own\n", - " * default, `subject subj : Anything[1]` (Systems\n", - " * Library/Requirements.sysml). Deliberately no `assert satisfy`\n", - " * line either. Confirmed directly, not merely argued: attempting\n", - " * `assert satisfy energyConservationReq by\n", - " * deliveredEnergyBoundedBySupply;` makes model.verify_satisfaction()\n", - " * error identically no matter what is bound as the satisfying\n", - " * feature (\"require condition evaluation failed: no value for\n", - " * feature heatGenCheck.efficiency\"), not pass -- demonstrated\n", - " * directly as a negative control in notebook 01, and recorded in\n", - " * full in\n", - " * docs/case-studies/2026-09-30-energy-conservation-requirement-tie.md.\n", - " * See AC-C10 (this chapter's own judgment record, notebook 01) for\n", - " * how this requirement's own need was actually identified, and for\n", - " * the honest distinction between a tie and a solver-level proof. */\n", - " require constraint c :> deliveredEnergyBoundedBySupply;\n", - "}\n", - "requirement energyConservationReq : EnergyConservationReq;\n" - ] - } - ], - "source": [ - "print(ENERGY_CONSERVATION_REQ_DEF)\n" + "Not a pass, an error, for all three bindings actually tested above: `require condition evaluation failed: no value for feature heatGenCheck.efficiency`, identical whether the satisfying feature is the lemma itself, the lemma's own free-standing usage (`heatGenCheck`), or a totally unrelated real candidate (`rated`). This is not a quirk of one binding -- it is demonstrated directly, across three different ones, for the structural reason already named in the doc comment above: `heatGenCheck`/`heatGenCheckDuration` are deliberately left free (the whole point of the Z3 proof is that it holds for every value, not one), so the construct cannot be evaluated at all, regardless of what is bound as the satisfying feature. `requirement_coverage()`'s own `covered=True`/`False` only ever checks whether a non-negated `SatisfyRequirementUsage` *exists*, never whether it actually evaluates -- these cells are the one place in this whole model that actually *runs* the check, and it fails identically every time. This is why `models/ch10-cumulative.sysml` carries no `assert satisfy` for this requirement: not because a tie is missing, but because `satisfy` is the wrong register for what this model actually has. `EnergyConservationReq`'s own required constraint already evaluates true, by construction (it *is* the proved lemma) -- SS7.21.1's own words, \"a requirement is satisfied when it evaluates to true\" -- with no `satisfy` usage needed at all. The subsetting construct shown above is how that is stated." ] }, { diff --git a/chapters/ch10-traceability-signoff/index.md b/chapters/ch10-traceability-signoff/index.md index cdcfe05..e738c66 100644 --- a/chapters/ch10-traceability-signoff/index.md +++ b/chapters/ch10-traceability-signoff/index.md @@ -14,9 +14,9 @@ This chapter adds exactly one new named model element, and only because its own | Notebook | Concept | |---|---| -| [01 - traceability graph](01-traceability-graph.ipynb) | Trace two of the model's three requirements from functional intent through allocation and realization to verification evidence, built entirely from real queries; find that the model's own strongest formal proof is tied to no requirement at all, close that gap directly by subsetting (not by `assert satisfy`, confirmed by negative control to fail, across three different bindings), and record how that tie should honestly be read (`AC-C10`). | -| [02 - judgment ledger](02-judgment-synthesis.ipynb) | Reconstruct `AS-C06` and `AS-C08` (re-verified against their real originals) plus `AI-C06`, and read what each record's own kind, disposition and residual uncertainty actually says. | -| [03 - engineering synthesis](03-engineering-signoff.ipynb) | Synthesize the graph and the ledger into one honest, bounded record, and state plainly why that record is not itself sign-off. | +| [01: traceability graph](01-traceability-graph.ipynb) | Trace two of the model's three requirements from functional intent through allocation and realization to verification evidence, built entirely from real queries; find that the model's own strongest formal proof is tied to no requirement at all, close that gap directly by subsetting (not by `assert satisfy`, confirmed by negative control to fail, across three different bindings), and record how that tie should honestly be read (`AC-C10`). | +| [02: judgment ledger](02-judgment-synthesis.ipynb) | Reconstruct `AS-C06` and `AS-C08` (re-verified against their real originals) plus `AI-C06`, and read what each record's own kind, disposition and residual uncertainty actually says. | +| [03: engineering synthesis](03-engineering-signoff.ipynb) | Synthesize the graph and the ledger into one honest, bounded record, and state plainly why that record is not itself sign-off. | ## Equipment From e1ac6f76d15160bf4b747a6adc7832aa76b0f23b Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:40:19 -0400 Subject: [PATCH 10/25] Phase B Ch5: TOASTER_INCREMENT assigned not printed; Pattern-2 full removal on 01-model-navigation; index.md heading sync --- .../ch05-architecture/01-model-navigation.ipynb | 12 +----------- chapters/ch05-architecture/02-allocate.ipynb | 13 ++----------- chapters/ch05-architecture/03-interfaces.ipynb | 14 ++------------ chapters/ch05-architecture/index.md | 2 +- 4 files changed, 6 insertions(+), 35 deletions(-) diff --git a/chapters/ch05-architecture/01-model-navigation.ipynb b/chapters/ch05-architecture/01-model-navigation.ipynb index 661c8fb..a64b045 100644 --- a/chapters/ch05-architecture/01-model-navigation.ipynb +++ b/chapters/ch05-architecture/01-model-navigation.ipynb @@ -24,17 +24,7 @@ "cell_type": "code", "id": "cell-02", "metadata": {}, - "source": [ - "from pathlib import Path\n", - "import opensysml\n", - "from toaster.report import format_diagnostics\n", - "\n", - "conn = opensysml.connect(version=\"v0.9.0\")\n", - "source = Path(\"../../models/ch05-cumulative.sysml\").read_text()\n", - "print(source)\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" - ], + "source": "from pathlib import Path\nimport opensysml\nfrom toaster.report import format_diagnostics\n\nconn = opensysml.connect(version=\"v0.9.0\")\nsource = Path(\"../../models/ch05-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"", "execution_count": null, "outputs": [] }, diff --git a/chapters/ch05-architecture/02-allocate.ipynb b/chapters/ch05-architecture/02-allocate.ipynb index a1bf565..0a03c10 100644 --- a/chapters/ch05-architecture/02-allocate.ipynb +++ b/chapters/ch05-architecture/02-allocate.ipynb @@ -79,14 +79,7 @@ "id": "cell-06", "metadata": {}, "outputs": [], - "source": [ - "TOASTER_INCREMENT = f\"{HEATING_SYSTEM_DEF}\\n{TOASTER_WITH_ALLOCATION}\"\n", - "print(TOASTER_INCREMENT)\n", - "\n", - "source = Path(\"../../models/ch05-cumulative.sysml\").read_text()\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" - ] + "source": "TOASTER_INCREMENT = f\"{HEATING_SYSTEM_DEF}\\n{TOASTER_WITH_ALLOCATION}\"\n\nsource = Path(\"../../models/ch05-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", @@ -152,9 +145,7 @@ "cell_type": "markdown", "id": "cell-12", "metadata": {}, - "source": [ - "The definitions printed above loaded without error, and the query results confirm the allocation's own ends, not just that a component of the right type performs the function." - ] + "source": "The assembled definitions loaded without error, and the query results confirm the allocation's own ends, not just that a component of the right type performs the function." }, { "cell_type": "markdown", diff --git a/chapters/ch05-architecture/03-interfaces.ipynb b/chapters/ch05-architecture/03-interfaces.ipynb index c16b201..797571f 100644 --- a/chapters/ch05-architecture/03-interfaces.ipynb +++ b/chapters/ch05-architecture/03-interfaces.ipynb @@ -123,17 +123,7 @@ "id": "cell-10", "metadata": {}, "outputs": [], - "source": [ - "TOASTER_INCREMENT = (\n", - " f\"{DURATION_PORT_DEF}\\n{HEATING_SYSTEM_PORT}\\n\"\n", - " f\"{CONTROL_SYSTEM_PORT}\\n{TOASTER_WITH_INTERFACE}\"\n", - ")\n", - "print(TOASTER_INCREMENT)\n", - "\n", - "source = Path(\"../../models/ch05-cumulative.sysml\").read_text()\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" - ] + "source": "TOASTER_INCREMENT = (\n f\"{DURATION_PORT_DEF}\\n{HEATING_SYSTEM_PORT}\\n\"\n f\"{CONTROL_SYSTEM_PORT}\\n{TOASTER_WITH_INTERFACE}\"\n)\n\nsource = Path(\"../../models/ch05-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", @@ -215,7 +205,7 @@ "cell_type": "markdown", "id": "cell-18", "metadata": {}, - "source": "The port and interface definitions printed above loaded without error, and the diagram rendered directly from the loaded model shows the same `control`-to-`heating` connection, now by its own `durationOut`-to-`durationIn` port names rather than the interface label alone." + "source": "The assembled definitions loaded without error, and the diagram rendered directly from the loaded model shows the same `control`-to-`heating` connection, now by its own `durationOut`-to-`durationIn` port names rather than the interface label alone." }, { "cell_type": "markdown", diff --git a/chapters/ch05-architecture/index.md b/chapters/ch05-architecture/index.md index 1d53448..f8bd1c3 100644 --- a/chapters/ch05-architecture/index.md +++ b/chapters/ch05-architecture/index.md @@ -14,7 +14,7 @@ After completing this chapter, the cumulative model has a named, usage-level `al | Notebook | Concept | |---|---| -| [01: Model Navigation](01-model-navigation.ipynb) | Navigate model elements by qualified name using `model.find()` and `model.get(fqn)`. | +| [01: model navigation](01-model-navigation.ipynb) | Navigate model elements by qualified name using `model.find()` and `model.get(fqn)`. | | [02: Allocate](02-allocate.ipynb) | Make `HeatingSystem` an abstract logical component that performs `ApplyHeat`, and assign it a named, usage-level allocation. | | [03: Interfaces](03-interfaces.ipynb) | Declare a port-typed interface between `ControlSystem` and `HeatingSystem` and render the interconnection diagram. | From 927876f0cedfeb046985998a98624bc0288b4705 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:40:22 -0400 Subject: [PATCH 11/25] Phase B Ch4: TOASTER_INCREMENT assigned not printed; Pattern-2 trim on 03-completeness-check --- .../01-action-def-ffbd.ipynb | 17 +- .../02-heating-refinement.ipynb | 9 +- .../03-completeness-check.ipynb | 162 +----------------- 3 files changed, 8 insertions(+), 180 deletions(-) diff --git a/chapters/ch04-functional-decomp/01-action-def-ffbd.ipynb b/chapters/ch04-functional-decomp/01-action-def-ffbd.ipynb index 1006d10..05dff0e 100644 --- a/chapters/ch04-functional-decomp/01-action-def-ffbd.ipynb +++ b/chapters/ch04-functional-decomp/01-action-def-ffbd.ipynb @@ -163,22 +163,7 @@ "id": "cell-14", "metadata": {}, "outputs": [], - "source": [ - "TOASTBREAD_REOPENED = (\n", - " \"action def ToastBread {\\n\"\n", - " \" doc /* Transform bread into toast acceptable to its user. */\\n\"\n", - " \" in bread : Bread;\\n\"\n", - " \" out toast : Toast;\\n\"\n", - " f\"{TOASTBREAD_SEQUENCE}\\n\"\n", - " \"}\"\n", - ")\n", - "TOASTER_INCREMENT = f\"{APPLY_HEAT_DEF}\\n{TOASTBREAD_REOPENED}\"\n", - "print(TOASTER_INCREMENT)\n", - "\n", - "source = Path(\"../../models/ch04-cumulative.sysml\").read_text()\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"\n" - ] + "source": "TOASTBREAD_REOPENED = (\n \"action def ToastBread {\\n\"\n \" doc /* Transform bread into toast acceptable to its user. */\\n\"\n \" in bread : Bread;\\n\"\n \" out toast : Toast;\\n\"\n f\"{TOASTBREAD_SEQUENCE}\\n\"\n \"}\"\n)\nTOASTER_INCREMENT = f\"{APPLY_HEAT_DEF}\\n{TOASTBREAD_REOPENED}\"\n\nsource = Path(\"../../models/ch04-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"\n" }, { "cell_type": "markdown", diff --git a/chapters/ch04-functional-decomp/02-heating-refinement.ipynb b/chapters/ch04-functional-decomp/02-heating-refinement.ipynb index 08cb56a..2067c6f 100644 --- a/chapters/ch04-functional-decomp/02-heating-refinement.ipynb +++ b/chapters/ch04-functional-decomp/02-heating-refinement.ipynb @@ -99,14 +99,7 @@ "id": "cell-08", "metadata": {}, "outputs": [], - "source": [ - "TOASTER_INCREMENT = f\"{START_DEF}\\n{FINISH_DEF}\\n{CANCEL_DEF}\"\n", - "print(TOASTER_INCREMENT)\n", - "\n", - "source = Path(\"../../models/ch04-cumulative.sysml\").read_text()\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"\n" - ] + "source": "TOASTER_INCREMENT = f\"{START_DEF}\\n{FINISH_DEF}\\n{CANCEL_DEF}\"\n\nsource = Path(\"../../models/ch04-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"\n" }, { "cell_type": "markdown", diff --git a/chapters/ch04-functional-decomp/03-completeness-check.ipynb b/chapters/ch04-functional-decomp/03-completeness-check.ipynb index 248cb26..fdd7da3 100644 --- a/chapters/ch04-functional-decomp/03-completeness-check.ipynb +++ b/chapters/ch04-functional-decomp/03-completeness-check.ipynb @@ -20,7 +20,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "id": "cell-02", "metadata": { "execution": { @@ -30,144 +30,8 @@ "shell.execute_reply": "2026-10-01T05:40:51.609942Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "// GENERATED FIXTURE: do not edit directly.\n", - "// Run: python scripts/check_construction.py --check (to verify)\n", - "// Source: notebook cell-02 TOASTER_INCREMENT in chapter 4's construct-introducing notebooks.\n", - "\n", - "package ToasterDemo {\n", - " metadata def ReviewRecordRef {\n", - " attribute identifier : ScalarValues::String;\n", - " }\n", - "\n", - " private import ScalarValues::*;\n", - " private import SI::*;\n", - " private import ISQ::*;\n", - "\n", - " item def Bread;\n", - " item def Toast;\n", - "\n", - " action def ApplyHeat {\n", - " in bread : Bread;\n", - " in energy : ISQ::EnergyValue[0..*];\n", - " in duration : ISQ::DurationValue[0..*] {\n", - " doc /* Signal from a control function: how long to apply heat.\n", - " * No control function is modeled in this chapter, so this input\n", - " * is declared and typed but not yet connected to a value. */\n", - " }\n", - " out toast : Toast;\n", - " out delivered : ISQ::EnergyValue;\n", - " out loss : ISQ::EnergyValue;\n", - "\n", - " assert constraint balance {\n", - " delivered >= 0.0 [SI::J] and loss >= 0.0 [SI::J] and delivered + loss <= energy\n", - " }\n", - " }\n", - "\n", - " metadata aiC04Tag : ReviewRecordRef about ApplyHeat {\n", - " identifier = \"AI-C04\";\n", - " }\n", - "\n", - " action def ToastBread {\n", - " doc /* Transform bread into toast acceptable to its user. */\n", - " in bread : Bread;\n", - " out toast : Toast;\n", - " first start;\n", - " then action applyHeat : ApplyHeat {\n", - " in bread = ToastBread::bread;\n", - " }\n", - " then done;\n", - " }\n", - "\n", - " abstract part def ToastingSystem {\n", - " perform action toastBread : ToastBread;\n", - " }\n", - "\n", - " part def HeatingSystem;\n", - " part def ControlSystem;\n", - "\n", - " part def Toaster :> ToastingSystem {\n", - " attribute cycleTime : ISQ::DurationValue;\n", - " part heating : HeatingSystem;\n", - " part control : ControlSystem;\n", - " }\n", - "\n", - " requirement def TimelyToast {\n", - " doc /*\n", - " * The toaster shall complete a toasting cycle in at most 180 seconds.\n", - " * Rationale: kitchen workflows typically span 5-15 minutes; a cycle\n", - " * exceeding 3 minutes delays meal preparation and falls outside where\n", - " * and how a user prepares a meal.\n", - " */\n", - " subject toaster : Toaster;\n", - " require constraint { toaster.cycleTime <= 180.0 [SI::s] }\n", - " }\n", - "\n", - " requirement timely : TimelyToast;\n", - "\n", - " metadata acC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AC-C03\";\n", - " }\n", - "\n", - " metadata asC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AS-C03\";\n", - " }\n", - "\n", - " part nominal : Toaster;\n", - " metadata ac001Tag : ReviewRecordRef about nominal {\n", - " identifier = \"AC-001\";\n", - " }\n", - "\n", - " part slow : Toaster {\n", - " attribute :>> cycleTime = 200.0 [SI::s];\n", - " assert not satisfy timely by slow;\n", - " }\n", - "\n", - " verification def TimelyToastTest {\n", - " doc /*\n", - " * Verification method: timed test of three consecutive toasting cycles at\n", - " * nominal input power; all must complete within 180 seconds.\n", - " * Method type: test (VerificationMethodKind::test, SysML v2 §7.24 Table 22).\n", - " * Note: formal #verificationMethod metadata not yet supported in OpenSysML v0.9.0;\n", - " * tracked at toaster#19 / OpenSysML#608.\n", - " * spec: SysML v2 formal/2026-03-02 §7.24.2 (VerificationCaseDefinition).\n", - " */\n", - " subject toaster : Toaster;\n", - " objective {\n", - " verify timely;\n", - " }\n", - " }\n", - "\n", - " item def Start {\n", - " doc /* Signal marking the start of a toasting cycle, not the bread itself. */\n", - " }\n", - " item def Finish {\n", - " doc /* Signal marking the finish of a toasting cycle, not the toast itself. */\n", - " }\n", - " item def Cancel {\n", - " doc /* Signal requesting cancellation of an in-progress toasting cycle. */\n", - " }\n", - "}\n", - "\n" - ] - } - ], - "source": [ - "from pathlib import Path\n", - "import opensysml\n", - "from toaster.evidence import ReviewRecord, hash_content, validate_record\n", - "from toaster.report import format_diagnostics\n", - "\n", - "conn = opensysml.connect(version=\"v0.9.0\")\n", - "source = Path(\"../../models/ch04-cumulative.sysml\").read_text()\n", - "print(source)\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"\n" - ] + "outputs": [], + "source": "from pathlib import Path\nimport opensysml\nfrom toaster.evidence import ReviewRecord, hash_content, validate_record\nfrom toaster.report import format_diagnostics\n\nconn = opensysml.connect(version=\"v0.9.0\")\nsource = Path(\"../../models/ch04-cumulative.sysml\").read_text()\nlines = source.splitlines()\nnew_this_chapter = \"\\n\".join(lines[16:32] + lines[37:47] + lines[107:116])\nprint(new_this_chapter)\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"\n" }, { "cell_type": "markdown", @@ -307,7 +171,7 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": null, "id": "cf4859f1", "metadata": { "execution": { @@ -317,22 +181,8 @@ "shell.execute_reply": "2026-10-01T05:40:51.631465Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "metadata aiC04Tag : ReviewRecordRef about ApplyHeat {\n", - " identifier = \"AI-C04\";\n", - "}\n", - "\n" - ] - } - ], - "source": [ - "TOASTER_INCREMENT = AI_C04_TAG\n", - "print(TOASTER_INCREMENT)\n" - ] + "outputs": [], + "source": "TOASTER_INCREMENT = AI_C04_TAG\n" }, { "cell_type": "markdown", From 329b357a3eaa019fefb7390bff81db8d19704e69 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:41:26 -0400 Subject: [PATCH 12/25] Phase B Ch1: TOASTER_INCREMENT assigned not printed, 4 notebooks --- chapters/ch01-system-purpose/01-abstract-def.ipynb | 2 +- chapters/ch01-system-purpose/02-part-def.ipynb | 2 +- chapters/ch01-system-purpose/03-specialization.ipynb | 2 +- chapters/ch01-system-purpose/04-composition.ipynb | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/chapters/ch01-system-purpose/01-abstract-def.ipynb b/chapters/ch01-system-purpose/01-abstract-def.ipynb index 5ae14c6..3dede7a 100644 --- a/chapters/ch01-system-purpose/01-abstract-def.ipynb +++ b/chapters/ch01-system-purpose/01-abstract-def.ipynb @@ -111,7 +111,7 @@ "metadata": {}, "outputs": [], "execution_count": null, - "source": "TOASTER_INCREMENT = f\"{BREAD_DEF}\\n{TOAST_DEF}\\n{TOASTBREAD_DEF}\\n{TOASTING_SYSTEM_DEF}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" + "source": "TOASTER_INCREMENT = f\"{BREAD_DEF}\\n{TOAST_DEF}\\n{TOASTBREAD_DEF}\\n{TOASTING_SYSTEM_DEF}\"\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", diff --git a/chapters/ch01-system-purpose/02-part-def.ipynb b/chapters/ch01-system-purpose/02-part-def.ipynb index b0414f3..8c1a203 100644 --- a/chapters/ch01-system-purpose/02-part-def.ipynb +++ b/chapters/ch01-system-purpose/02-part-def.ipynb @@ -70,7 +70,7 @@ "metadata": {}, "outputs": [], "execution_count": null, - "source": "TOASTER_INCREMENT = f\"{HEATING_SYS_DEF}\\n{CONTROL_SYS_DEF}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" + "source": "TOASTER_INCREMENT = f\"{HEATING_SYS_DEF}\\n{CONTROL_SYS_DEF}\"\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", diff --git a/chapters/ch01-system-purpose/03-specialization.ipynb b/chapters/ch01-system-purpose/03-specialization.ipynb index ce9316e..42e2307 100644 --- a/chapters/ch01-system-purpose/03-specialization.ipynb +++ b/chapters/ch01-system-purpose/03-specialization.ipynb @@ -54,7 +54,7 @@ "metadata": {}, "outputs": [], "execution_count": null, - "source": "TOASTER_INCREMENT = TOASTER_SPEC_DEF\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" + "source": "TOASTER_INCREMENT = TOASTER_SPEC_DEF\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", diff --git a/chapters/ch01-system-purpose/04-composition.ipynb b/chapters/ch01-system-purpose/04-composition.ipynb index 9708d53..712b3c4 100644 --- a/chapters/ch01-system-purpose/04-composition.ipynb +++ b/chapters/ch01-system-purpose/04-composition.ipynb @@ -86,7 +86,7 @@ "metadata": {}, "outputs": [], "execution_count": null, - "source": "TOASTER_INCREMENT = f\"{TOASTER_DEF}\\n{CYCLE_TIME_ATTR}\\n{HEATING_PART}\\n{CONTROL_PART}\\n}}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" + "source": "TOASTER_INCREMENT = f\"{TOASTER_DEF}\\n{CYCLE_TIME_ATTR}\\n{HEATING_PART}\\n{CONTROL_PART}\\n}}\"\nsource = Path(\"../../models/ch01-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", @@ -165,7 +165,7 @@ "id": "cell-13", "metadata": {}, "source": [ - "`part def Toaster :> ToastingSystem { ... }` printed above loaded without error, and `toaster.parts()` returns the two part symbols shown below, confirming the composition is now part of the model." + "The assembled `Toaster` declaration loaded without error, and the diagram above confirms `heating` and `control` are part of the model." ] }, { From 45b5f60922561f2dea51b59971d94a6205831d32 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:42:48 -0400 Subject: [PATCH 13/25] Phase B Ch7: TOASTER_INCREMENT assigned not printed; new model.find() confirmation added to 01-calc-energy --- chapters/ch07-execution/01-calc-energy.ipynb | 28 ++++------------- chapters/ch07-execution/02-state-traces.ipynb | 30 ++----------------- 2 files changed, 8 insertions(+), 50 deletions(-) diff --git a/chapters/ch07-execution/01-calc-energy.ipynb b/chapters/ch07-execution/01-calc-energy.ipynb index a665929..ab0c75d 100644 --- a/chapters/ch07-execution/01-calc-energy.ipynb +++ b/chapters/ch07-execution/01-calc-energy.ipynb @@ -183,7 +183,7 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": null, "id": "cell-09", "metadata": { "execution": { @@ -198,34 +198,18 @@ "name": "stdout", "output_type": "stream", "text": [ - "abstract part def HeatGenerator {\n", - " perform action generateHeat : GenerateHeat;\n", - " port energyIn : ~EnergyPort;\n", - " attribute power : ISQ::PowerValue;\n", - " attribute efficiency : DimensionOneValue;\n", - " assert constraint efficiencyBounded {\n", - " 0.0 <= efficiency and efficiency <= 1.0\n", - " }\n", - " calc deliveredEnergy {\n", - " in power : ISQ::PowerValue;\n", - " in duration : ISQ::DurationValue;\n", - " return : ISQ::EnergyValue = power * duration * efficiency;\n", - " }\n", - "}\n", - "part rated : ResistanceCoil {\n", - " attribute :>> efficiency = 0.7 [MeasurementReferences::one];\n", - " assert satisfy heatGenerationReq by rated;\n", - "}\n" + "HeatGenerator::deliveredEnergy: kind='calcUsage', id='ToasterDemo::HeatGenerator::deliveredEnergy'\n" ] } ], "source": [ "TOASTER_INCREMENT = f\"{HEAT_GENERATOR_INCREMENT}\\n{RATED_INCREMENT}\"\n", - "print(TOASTER_INCREMENT)\n", "\n", "source = Path(\"../../models/ch07-cumulative.sysml\").read_text()\n", "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" + "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"\n", + "delivered_energy = model.find(\"ToasterDemo::HeatGenerator::deliveredEnergy\")\n", + "print(f\"HeatGenerator::deliveredEnergy: kind={delivered_energy.kind!r}, id={delivered_energy.id!r}\")" ] }, { @@ -233,7 +217,7 @@ "id": "cell-10", "metadata": {}, "source": [ - "A constraint that references an attribute the definition never declares fails to load. The negative control below asserts a bound on a name `Widget` does not have." + "`HeatGenerator::deliveredEnergy` is now part of the loaded model, confirmed by `model.find`. A constraint that references an attribute the definition never declares fails to load. The negative control below asserts a bound on a name `Widget` does not have." ] }, { diff --git a/chapters/ch07-execution/02-state-traces.ipynb b/chapters/ch07-execution/02-state-traces.ipynb index a2d038d..5851d4e 100644 --- a/chapters/ch07-execution/02-state-traces.ipynb +++ b/chapters/ch07-execution/02-state-traces.ipynb @@ -311,7 +311,7 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": null, "id": "cell-16", "metadata": { "execution": { @@ -321,35 +321,9 @@ "shell.execute_reply": "2026-09-28T11:23:56.122615Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "state def Cycle {\n", - " entry; then idle;\n", - " state idle;\n", - " state heating {\n", - " do action generateHeat : GenerateHeat;\n", - " }\n", - " state ready;\n", - " state cancelled;\n", - " transition first idle accept Start then heating;\n", - " transition first heating accept Finish then ready;\n", - " transition first heating accept Cancel then cancelled;\n", - " transition first ready then idle;\n", - " transition first cancelled then idle;\n", - "}\n", - "abstract part def ToastingSystem {\n", - " perform action toastBread : ToastBread;\n", - " exhibit state cycle : Cycle;\n", - "}\n" - ] - } - ], + "outputs": [], "source": [ "TOASTER_INCREMENT = f\"{CYCLE_DEF}\\n{TOASTING_SYSTEM_INCREMENT}\"\n", - "print(TOASTER_INCREMENT)\n", "\n", "source = Path(\"../../models/ch07-cumulative.sysml\").read_text()\n", "model = conn.load_from_content(source, strict=False)\n", From 3d24ca534382ecd85c15db3b7e1894e74fbbf4b7 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:43:23 -0400 Subject: [PATCH 14/25] Phase B Ch8: TOASTER_INCREMENT assigned not printed; rename 01-invariant-def to 01-assert-constraint-def; index.md separator fix --- DEFERRED.md | 4 +- ...f.ipynb => 01-assert-constraint-def.ipynb} | 51 +------ .../ch08-checking/02-violation-witness.ipynb | 26 +--- chapters/ch08-checking/index.md | 6 +- exercises/ch08/exercise.ipynb | 125 ++---------------- myst.yml | 2 +- scripts/check_construction.py | 2 +- 7 files changed, 27 insertions(+), 189 deletions(-) rename chapters/ch08-checking/{01-invariant-def.ipynb => 01-assert-constraint-def.ipynb} (84%) diff --git a/DEFERRED.md b/DEFERRED.md index d4e1843..ad3a7c0 100644 --- a/DEFERRED.md +++ b/DEFERRED.md @@ -690,7 +690,7 @@ committed to `models/`), restating only `deliveredEnergyBoundedBySupply` and the two usages it needs, which carries no `assert satisfy` declaration and so never hits this parser gap. The construct itself is real, committed content in `models/ch08-cumulative.sysml` (introduced in -`chapters/ch08-checking/01-invariant-def.ipynb`); only the file handed to +`chapters/ch08-checking/01-assert-constraint-def.ipynb`); only the file handed to `verify_holds` is a restatement, and the notebook says so. See D-030 and D-031 for the separate, deeper reason this construct is a hand-restated lemma rather than a solver-checked reference to `HeatGenerator`'s own `efficiencyBounded` and @@ -795,7 +795,7 @@ checked reference to them, and re-checking it after either original element changes is a manual, not automatic, step. **Workaround:** `deliveredEnergyBoundedBySupply`'s own doc comment, and Chapter 8's -prose (`chapters/ch08-checking/01-invariant-def.ipynb`, +prose (`chapters/ch08-checking/01-assert-constraint-def.ipynb`, `02-violation-witness.ipynb`, `index.md`, `conclusion.md`), state this limit plainly rather than claiming a link the toolchain cannot check. **Resolution:** none attempted; would need `verify --solve` (or a successor tool) diff --git a/chapters/ch08-checking/01-invariant-def.ipynb b/chapters/ch08-checking/01-assert-constraint-def.ipynb similarity index 84% rename from chapters/ch08-checking/01-invariant-def.ipynb rename to chapters/ch08-checking/01-assert-constraint-def.ipynb index 6cae495..f170e64 100644 --- a/chapters/ch08-checking/01-invariant-def.ipynb +++ b/chapters/ch08-checking/01-assert-constraint-def.ipynb @@ -227,7 +227,7 @@ }, { "cell_type": "code", - "execution_count": 4, + "execution_count": null, "id": "cell-08", "metadata": { "execution": { @@ -237,51 +237,8 @@ "shell.execute_reply": "2026-09-28T12:47:55.978167Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " part heatGenCheck : HeatGenerator;\n", - " attribute heatGenCheckDuration : ISQ::DurationValue;\n", - "\n", - " assert constraint deliveredEnergyBoundedBySupply {\n", - " doc /* A real-arithmetic lemma of the same shape as the relation\n", - " * efficiencyBounded (0 <= efficiency <= 1) and deliveredEnergy's own\n", - " * definition (power * duration * efficiency) together would imply:\n", - " * given efficiency in [0,1] and non-negative power and duration,\n", - " * power * duration * efficiency never exceeds power * duration.\n", - " * Restated by hand on a fresh, unbound usage (heatGenCheck) rather\n", - " * than a solver-checked reference to HeatGenerator's own\n", - " * efficiencyBounded and deliveredEnergy: this toolchain's Z3 backend\n", - " * does not compose two separately declared assert constraints,\n", - " * whether sibling or inherited (D-030), and cannot reason through a\n", - " * chained calc invocation such as heatGenCheck.deliveredEnergy(...)\n", - " * (D-031). Proved by Z3 over the unbound heatGenCheck.efficiency,\n", - " * heatGenCheck.power and heatGenCheckDuration features\n", - " * (verify --solve): this restated lemma holds for all such values,\n", - " * but the proof does not track HeatGenerator's own efficiencyBounded\n", - " * or deliveredEnergy if either changes; a content-hash-based record\n", - " * against this file does go stale when either changes (any edit to\n", - " * the file changes the hash), which is a partial safeguard, not a\n", - " * check that the restated copy stays in sync. */\n", - " (heatGenCheck.efficiency >= 0.0 and heatGenCheck.efficiency <= 1.0\n", - " and heatGenCheck.power >= 0.0 [SI::W] and heatGenCheckDuration >= 0.0 [SI::s])\n", - " implies (heatGenCheck.power * heatGenCheckDuration * heatGenCheck.efficiency)\n", - " <= heatGenCheck.power * heatGenCheckDuration\n", - " }\n", - "\n" - ] - } - ], - "source": [ - "TOASTER_INCREMENT = f\"{HEAT_GEN_CHECK_USAGE}\\n{CHECK_DURATION_ATTR}\\n\\n{DELIVERED_ENERGY_BOUND}\\n\"\n", - "print(TOASTER_INCREMENT)\n", - "\n", - "source = Path(\"../../models/ch08-cumulative.sysml\").read_text()\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" - ] + "outputs": [], + "source": "TOASTER_INCREMENT = f\"{HEAT_GEN_CHECK_USAGE}\\n{CHECK_DURATION_ATTR}\\n\\n{DELIVERED_ENERGY_BOUND}\\n\"\n\nsource = Path(\"../../models/ch08-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", @@ -413,4 +370,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/chapters/ch08-checking/02-violation-witness.ipynb b/chapters/ch08-checking/02-violation-witness.ipynb index db0b9e7..2d94a53 100644 --- a/chapters/ch08-checking/02-violation-witness.ipynb +++ b/chapters/ch08-checking/02-violation-witness.ipynb @@ -14,9 +14,7 @@ "cell_type": "markdown", "id": "cell-01", "metadata": {}, - "source": [ - "Notebook 01 stated `deliveredEnergyBoundedBySupply` and confirmed it is really part of `ch08-cumulative.sysml`. This notebook runs analysis against that construct and, further down, adds the one new model element this chapter's own judgment record needs: a `ReviewRecordRef` tag anchoring `AS-C08` to `deliveredEnergyBoundedBySupply` itself. See [Ch8-01](01-invariant-def.ipynb) for the construct itself." - ] + "source": "Notebook 01 stated `deliveredEnergyBoundedBySupply` and confirmed it is really part of `ch08-cumulative.sysml`. This notebook runs analysis against that construct and, further down, adds the one new model element this chapter's own judgment record needs: a `ReviewRecordRef` tag anchoring `AS-C08` to `deliveredEnergyBoundedBySupply` itself. See [Ch8-01](01-assert-constraint-def.ipynb) for the construct itself." }, { "cell_type": "code", @@ -508,7 +506,7 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": null, "id": "cell-20", "metadata": { "execution": { @@ -518,22 +516,8 @@ "shell.execute_reply": "2026-10-01T06:22:53.981349Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "metadata asC08Tag : ReviewRecordRef about deliveredEnergyBoundedBySupply {\n", - " identifier = \"AS-C08\";\n", - "}\n", - "\n" - ] - } - ], - "source": [ - "TOASTER_INCREMENT = AS_C08_TAG\n", - "print(TOASTER_INCREMENT)" - ] + "outputs": [], + "source": "TOASTER_INCREMENT = AS_C08_TAG" }, { "cell_type": "markdown", @@ -869,4 +853,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/chapters/ch08-checking/index.md b/chapters/ch08-checking/index.md index 8e4d3ec..84a2ac3 100644 --- a/chapters/ch08-checking/index.md +++ b/chapters/ch08-checking/index.md @@ -14,9 +14,9 @@ After completing this chapter, the model has grown by one new construct, `delive | Notebook | Concept | |---|---| -| [01 - assert constraint](01-invariant-def.ipynb) | State `deliveredEnergyBoundedBySupply` as a real SysML constraint; confirm it is really in the loaded model. | -| [02 - proof versus point evaluation](02-violation-witness.ipynb) | Contrast `verify_holds()`'s universal proof with `verify_satisfaction()`'s point evaluation; show the loop catching a fully broken variant as `violated` and a merely weakened variant as `undecided`; record the proof as engineering evidence with its own real limits stated. | -| [03 - stale record detection](03-revision-flow.ipynb) | Loosen the lemma's own bound; show `check_stale()` marking the existing record for re-review. | +| [01: assert constraint](01-assert-constraint-def.ipynb) | State `deliveredEnergyBoundedBySupply` as a real SysML constraint; confirm it is really in the loaded model. | +| [02: proof versus point evaluation](02-violation-witness.ipynb) | Contrast `verify_holds()`'s universal proof with `verify_satisfaction()`'s point evaluation; show the loop catching a fully broken variant as `violated` and a merely weakened variant as `undecided`; record the proof as engineering evidence with its own real limits stated. | +| [03: stale record detection](03-revision-flow.ipynb) | Loosen the lemma's own bound; show `check_stale()` marking the existing record for re-review. | ## Equipment diff --git a/exercises/ch08/exercise.ipynb b/exercises/ch08/exercise.ipynb index 6da26fb..3242ddc 100644 --- a/exercises/ch08/exercise.ipynb +++ b/exercises/ch08/exercise.ipynb @@ -4,110 +4,7 @@ "cell_type": "markdown", "id": "cell-00", "metadata": {}, - "source": [ - "# Chapter 8 Exercise \u2014 Coffee Maker Constraint Checking\n", - "\n", - "Prove a hand-restated real-arithmetic lemma for the coffee maker model with\n", - "Z3, report your model's own real satisfaction claims, and show a\n", - "`ReviewRecord` go stale when the lemma it depends on changes.\n", - "\n", - "## Problem\n", - "\n", - "Your model from Chapter 7 has `WaterMover`, an abstract carrier with a\n", - "bounded `transferEfficiency : DimensionOneValue` attribute\n", - "(`transferEfficiencyBounded`, `0 <= transferEfficiency <= 1`) and a `calc\n", - "deliveredMass` (`throughput * duration * transferEfficiency`) on it, and\n", - "`Impeller :> WaterMover` with `rated`/`weak` usages. This chapter asks\n", - "whether `deliveredMass` ever exceeds what `throughput` and `duration` alone\n", - "would supply, for every value `transferEfficiency`, `throughput` and\n", - "`duration` could take \u2014 not just at `rated`'s own fixed value. Work through\n", - "these steps:\n", - "\n", - "1. Add a fresh, unbound `part moverCheck : WaterMover;` (mirroring\n", - " `heatGenCheck : HeatGenerator` in\n", - " `chapters/ch08-checking/01-invariant-def.ipynb`) and a fresh top-level\n", - " `attribute moverCheckDuration : ISQ::DurationValue;` to your coffee\n", - " model. Add `assert constraint deliveredMassBoundedBySupply`, a\n", - " hand-restated real-arithmetic lemma of the same shape as\n", - " `transferEfficiencyBounded` and `deliveredMass`'s own definition together\n", - " would imply: delivered mass never exceeds supplied mass (`throughput *\n", - " duration`), for every value of `transferEfficiency`, `throughput` and\n", - " `duration` in their bounds. Mirror `deliveredEnergyBoundedBySupply`'s own\n", - " `doc` comment and its reasoning (the same `DEFERRED.md` D-030/D-031\n", - " citations, the same \"restated by hand, not solver-checked reference\"\n", - " framing), substituting `moverCheck.transferEfficiency` /\n", - " `moverCheck.throughput` / `moverCheckDuration` for\n", - " `heatGenCheck.efficiency` / `heatGenCheck.power` /\n", - " `heatGenCheckDuration`, and the mass-flow units\n", - " (`ISQ::MassFlowRateValue`, `SI::'kg\u22c5s\u207b\u00b9'`) for the power/energy units.\n", - " Confirm with `model.find()` and `model.query()` that the new constraint\n", - " is really in the loaded model, not only in the string you wrote.\n", - "\n", - "2. Run `model.verify_satisfaction()` against your coffee model's own\n", - " existing `assert satisfy` / `assert not satisfy` claims (built up across\n", - " Chapters 1-7's own exercises) and report what you actually find \u2014 do not\n", - " assume it matches the toaster's own four verdicts; it may or may not.\n", - " Then prove `deliveredMassBoundedBySupply` for *every* value of its\n", - " unbound features with `toaster.modelcheck.verify_holds()`, via a\n", - " companion file (mirroring\n", - " `chapters/ch08-checking/02-violation-witness.ipynb`'s own\n", - " `COMPANION_POSITIVE` / `_write_companion` pattern exactly \u2014 a fixed\n", - " `SCRATCH_DIR = Path(\"companion-check-scratch\")`, used instead of the\n", - " committed model directly because `toaster.modelcheck`'s own text parser\n", - " cannot yet read a verdict line for a constraint that is also the subject\n", - " of an `assert satisfy` declaration, `DEFERRED.md` D-029). Then\n", - " demonstrate a negative control (the lemma's full negation, `A and not\n", - " B`, which Z3 must resolve as unsatisfiable to report `violated`) and a\n", - " \"merely weakened\" variant (loosening the antecedent's own bound from\n", - " `<= 1.0` to `<= 1.2`, reported `undecided` with a real witness, where\n", - " `holds()` raises `ModelCheckInconclusiveError` rather than collapsing\n", - " that into `True` or `False`). Then confirm D-030 directly, live: build a\n", - " further companion declaring `transferEfficiencyBounded` (the real\n", - " `[0,1]` bound, unchanged) alongside a second, sibling `assert\n", - " constraint reliesOnSibling`, whose own antecedent does *not* restate\n", - " that bound at all \u2014 it bounds only `moverCheck.throughput` and\n", - " `moverCheckDuration` as non-negative \u2014 and whose conclusion is the same\n", - " `throughput * duration * transferEfficiency <= throughput * duration`\n", - " shape `deliveredMassBoundedBySupply` states. If the solver composed the\n", - " two separately-declared constraints, `transferEfficiencyBounded` would\n", - " narrow `transferEfficiency` enough to make `reliesOnSibling` hold\n", - " everywhere too. Confirm instead that `verify_holds()` reports both\n", - " verdicts: `transferEfficiencyBounded` itself `satisfied` (it is, on its\n", - " own, a real, narrow bound), and `reliesOnSibling` `undecided`, with a\n", - " genuine Z3 witness where `transferEfficiency` takes *some* value\n", - " `transferEfficiencyBounded` itself rules out \u2014 the solver never\n", - " actually applied the sibling's own stated bound when checking\n", - " `reliesOnSibling`, regardless of which specific out-of-range value Z3\n", - " happens to pick. Build a `ReviewRecord` (`AS-C08-EX`,\n", - " `kind=\"asserted_solution\"`) mirroring `AS-C08`'s own field-by-field\n", - " content, whose `counterevidence` cites the same D-029/D-030/D-031 gaps\n", - " real Chapter 8 documents \u2014 confirmed directly in the cell above: a\n", - " sibling constraint that relies entirely on `transferEfficiencyBounded`'s\n", - " own stated bound, without restating it, is left `undecided` with a\n", - " witness violating that very bound, because the solver never composes\n", - " two separately-declared `assert constraint`s.\n", - "\n", - "3. Open with the same negative control notebook 03 opens with: an\n", - " empty-identifier record failing `validate_record()`, distinct from\n", - " staleness. Then reuse `AS-C08-EX` (built in Step 2's record cell \u2014\n", - " notebook 03 rebuilds `AS-C08` fresh from its own named parts, but\n", - " nothing here differs from a straight reuse), confirm `check_stale()`\n", - " reports it current against your coffee model's own source, then loosen\n", - " `deliveredMassBoundedBySupply`'s own bound (the same `<= 1.0` \u2192 `<= 1.2`\n", - " edit) and show the record goes stale.\n", - "\n", - "Verify with `model.ok == True`; the new constraint confirmed by both\n", - "`model.find()` and `model.query()`; `verify_holds()` reporting `satisfied`\n", - "for the positive companion (with `z3` named in the reason text) and\n", - "`violated` for its full negation; `undecided` for the weakened variant,\n", - "with `holds()` raising `ModelCheckInconclusiveError`; the sibling-carrying\n", - "companion reporting `transferEfficiencyBounded` itself `satisfied` and\n", - "`reliesOnSibling` `undecided`, with a genuine Z3 witness showing\n", - "`transferEfficiency` taking some value outside `[0,1]` even though\n", - "`transferEfficiencyBounded` states that bound in the same file;\n", - "`validate_record(record) == []` for `AS-C08-EX`; and `check_stale()`\n", - "going from `False` to `True` after the bound change." - ] + "source": "# Chapter 8 Exercise — Coffee Maker Constraint Checking\n\nProve a hand-restated real-arithmetic lemma for the coffee maker model with\nZ3, report your model's own real satisfaction claims, and show a\n`ReviewRecord` go stale when the lemma it depends on changes.\n\n## Problem\n\nYour model from Chapter 7 has `WaterMover`, an abstract carrier with a\nbounded `transferEfficiency : DimensionOneValue` attribute\n(`transferEfficiencyBounded`, `0 <= transferEfficiency <= 1`) and a `calc\ndeliveredMass` (`throughput * duration * transferEfficiency`) on it, and\n`Impeller :> WaterMover` with `rated`/`weak` usages. This chapter asks\nwhether `deliveredMass` ever exceeds what `throughput` and `duration` alone\nwould supply, for every value `transferEfficiency`, `throughput` and\n`duration` could take — not just at `rated`'s own fixed value. Work through\nthese steps:\n\n1. Add a fresh, unbound `part moverCheck : WaterMover;` (mirroring\n `heatGenCheck : HeatGenerator` in\n `chapters/ch08-checking/01-assert-constraint-def.ipynb`) and a fresh top-level\n `attribute moverCheckDuration : ISQ::DurationValue;` to your coffee\n model. Add `assert constraint deliveredMassBoundedBySupply`, a\n hand-restated real-arithmetic lemma of the same shape as\n `transferEfficiencyBounded` and `deliveredMass`'s own definition together\n would imply: delivered mass never exceeds supplied mass (`throughput *\n duration`), for every value of `transferEfficiency`, `throughput` and\n `duration` in their bounds. Mirror `deliveredEnergyBoundedBySupply`'s own\n `doc` comment and its reasoning (the same `DEFERRED.md` D-030/D-031\n citations, the same \"restated by hand, not solver-checked reference\"\n framing), substituting `moverCheck.transferEfficiency` /\n `moverCheck.throughput` / `moverCheckDuration` for\n `heatGenCheck.efficiency` / `heatGenCheck.power` /\n `heatGenCheckDuration`, and the mass-flow units\n (`ISQ::MassFlowRateValue`, `SI::'kg⋅s⁻¹'`) for the power/energy units.\n Confirm with `model.find()` and `model.query()` that the new constraint\n is really in the loaded model, not only in the string you wrote.\n\n2. Run `model.verify_satisfaction()` against your coffee model's own\n existing `assert satisfy` / `assert not satisfy` claims (built up across\n Chapters 1-7's own exercises) and report what you actually find — do not\n assume it matches the toaster's own four verdicts; it may or may not.\n Then prove `deliveredMassBoundedBySupply` for *every* value of its\n unbound features with `toaster.modelcheck.verify_holds()`, via a\n companion file (mirroring\n `chapters/ch08-checking/02-violation-witness.ipynb`'s own\n `COMPANION_POSITIVE` / `_write_companion` pattern exactly — a fixed\n `SCRATCH_DIR = Path(\"companion-check-scratch\")`, used instead of the\n committed model directly because `toaster.modelcheck`'s own text parser\n cannot yet read a verdict line for a constraint that is also the subject\n of an `assert satisfy` declaration, `DEFERRED.md` D-029). Then\n demonstrate a negative control (the lemma's full negation, `A and not\n B`, which Z3 must resolve as unsatisfiable to report `violated`) and a\n \"merely weakened\" variant (loosening the antecedent's own bound from\n `<= 1.0` to `<= 1.2`, reported `undecided` with a real witness, where\n `holds()` raises `ModelCheckInconclusiveError` rather than collapsing\n that into `True` or `False`). Then confirm D-030 directly, live: build a\n further companion declaring `transferEfficiencyBounded` (the real\n `[0,1]` bound, unchanged) alongside a second, sibling `assert\n constraint reliesOnSibling`, whose own antecedent does *not* restate\n that bound at all — it bounds only `moverCheck.throughput` and\n `moverCheckDuration` as non-negative — and whose conclusion is the same\n `throughput * duration * transferEfficiency <= throughput * duration`\n shape `deliveredMassBoundedBySupply` states. If the solver composed the\n two separately-declared constraints, `transferEfficiencyBounded` would\n narrow `transferEfficiency` enough to make `reliesOnSibling` hold\n everywhere too. Confirm instead that `verify_holds()` reports both\n verdicts: `transferEfficiencyBounded` itself `satisfied` (it is, on its\n own, a real, narrow bound), and `reliesOnSibling` `undecided`, with a\n genuine Z3 witness where `transferEfficiency` takes *some* value\n `transferEfficiencyBounded` itself rules out — the solver never\n actually applied the sibling's own stated bound when checking\n `reliesOnSibling`, regardless of which specific out-of-range value Z3\n happens to pick. Build a `ReviewRecord` (`AS-C08-EX`,\n `kind=\"asserted_solution\"`) mirroring `AS-C08`'s own field-by-field\n content, whose `counterevidence` cites the same D-029/D-030/D-031 gaps\n real Chapter 8 documents — confirmed directly in the cell above: a\n sibling constraint that relies entirely on `transferEfficiencyBounded`'s\n own stated bound, without restating it, is left `undecided` with a\n witness violating that very bound, because the solver never composes\n two separately-declared `assert constraint`s.\n\n3. Open with the same negative control notebook 03 opens with: an\n empty-identifier record failing `validate_record()`, distinct from\n staleness. Then reuse `AS-C08-EX` (built in Step 2's record cell —\n notebook 03 rebuilds `AS-C08` fresh from its own named parts, but\n nothing here differs from a straight reuse), confirm `check_stale()`\n reports it current against your coffee model's own source, then loosen\n `deliveredMassBoundedBySupply`'s own bound (the same `<= 1.0` → `<= 1.2`\n edit) and show the record goes stale.\n\nVerify with `model.ok == True`; the new constraint confirmed by both\n`model.find()` and `model.query()`; `verify_holds()` reporting `satisfied`\nfor the positive companion (with `z3` named in the reason text) and\n`violated` for its full negation; `undecided` for the weakened variant,\nwith `holds()` raising `ModelCheckInconclusiveError`; the sibling-carrying\ncompanion reporting `transferEfficiencyBounded` itself `satisfied` and\n`reliesOnSibling` `undecided`, with a genuine Z3 witness showing\n`transferEfficiency` taking some value outside `[0,1]` even though\n`transferEfficiencyBounded` states that bound in the same file;\n`validate_record(record) == []` for `AS-C08-EX`; and `check_stale()`\ngoing from `False` to `True` after the bound change." }, { "cell_type": "code", @@ -138,7 +35,7 @@ "metadata": {}, "source": [ "Step 1 (continued): confirm the new construct is really part of the loaded\n", - "model, not only in the string above \u2014 mirroring notebook 01's own\n", + "model, not only in the string above — mirroring notebook 01's own\n", "confirmation cells exactly." ] }, @@ -169,7 +66,7 @@ "source": [ "Step 2: `verify_satisfaction()` evaluates every `assert satisfy` /\n", "`assert not satisfy` declaration your coffee model carries, each at the one\n", - "set of values its subject happens to have. Report what you actually find \u2014\n", + "set of values its subject happens to have. Report what you actually find —\n", "your model's own claims, built up across Chapters 1-7's own exercises, not\n", "a forced match to the toaster's own four." ] @@ -251,7 +148,7 @@ "\n", "def _ascii(reason: str) -> str:\n", " \"\"\"Swap the CLI's own em dash for a plain double hyphen. This domain's own\n", - " unit literals (e.g. `kg\u22c5s\u207b\u00b9`) carry other non-ASCII characters too, which\n", + " unit literals (e.g. `kg⋅s⁻¹`) carry other non-ASCII characters too, which\n", " this helper does not touch: only the em dash is replaced, not every\n", " non-ASCII character. Only the printed copy changes; the verdict objects\n", " themselves keep the CLI's own text.\"\"\"\n", @@ -286,7 +183,7 @@ "A proof is only worth trusting if the same machinery can also report a\n", "real violation. Restate the lemma's **full negation** below (`A and not B`,\n", "efficiency/throughput/duration bounded as before, **and** delivered mass\n", - "strictly *exceeds* supplied mass) \u2014 the one Z3 must actually resolve as\n", + "strictly *exceeds* supplied mass) — the one Z3 must actually resolve as\n", "unsatisfiable to report `violated`." ] }, @@ -319,8 +216,8 @@ "metadata": {}, "source": [ "A fully broken lemma is not the only interesting failure mode. Restate the\n", - "lemma below with its own bound loosened from `<= 1.0` to `<= 1.2` \u2014 the\n", - "same edit Step 3 uses to demonstrate staleness \u2014 and confirm `verify_holds()`\n", + "lemma below with its own bound loosened from `<= 1.0` to `<= 1.2` — the\n", + "same edit Step 3 uses to demonstrate staleness — and confirm `verify_holds()`\n", "reports `undecided` with a genuine witness, and that `holds()` refuses to\n", "collapse that into `True` or `False`." ] @@ -457,7 +354,7 @@ "was supposed to rule out. The witness itself satisfies `reliesOnSibling`\n", "only vacuously (its own stated non-negativity antecedent on `throughput`/\n", "`duration` can be left false by the same witness, the same way a false\n", - "antecedent trivially satisfies any `implies`) \u2014 what the witness actually\n", + "antecedent trivially satisfies any `implies`) — what the witness actually\n", "demonstrates is narrower and still decisive: Z3 was free to pick\n", "`transferEfficiency = 2` at all, which composition with\n", "`transferEfficiencyBounded` would have ruled out. The real evidence is the\n", @@ -477,7 +374,7 @@ "source": [ "The proof above is engineering evidence, not a passing test result.\n", "Build `AS-C08-EX` from the named parts below, mirroring `AS-C08`'s own\n", - "field-by-field content (Hawkins et al. 2011, \u00a7\u00a73.1-3.4), substituting the\n", + "field-by-field content (Hawkins et al. 2011, §§3.1-3.4), substituting the\n", "coffee-domain construct names and the verdicts you actually found." ] }, @@ -566,7 +463,7 @@ "metadata": {}, "source": [ "Step 3: a record with an empty identifier fails validation outright,\n", - "distinct from staleness \u2014 it was never a valid record to begin with,\n", + "distinct from staleness — it was never a valid record to begin with,\n", "regardless of which model it references. The same negative control\n", "notebook 03 opens with." ] @@ -650,4 +547,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file diff --git a/myst.yml b/myst.yml index 96a2dc3..5c05809 100644 --- a/myst.yml +++ b/myst.yml @@ -64,7 +64,7 @@ project: - title: "Chapter 8: Checking and Revision" children: - file: chapters/ch08-checking/index - - file: chapters/ch08-checking/01-invariant-def + - file: chapters/ch08-checking/01-assert-constraint-def - file: chapters/ch08-checking/02-violation-witness - file: chapters/ch08-checking/03-revision-flow - file: chapters/ch08-checking/conclusion diff --git a/scripts/check_construction.py b/scripts/check_construction.py index 8b972fa..27d8677 100644 --- a/scripts/check_construction.py +++ b/scripts/check_construction.py @@ -277,7 +277,7 @@ ], 8: [ { - "path": "chapters/ch08-checking/01-invariant-def.ipynb", + "path": "chapters/ch08-checking/01-assert-constraint-def.ipynb", # deliveredEnergyBoundedBySupply references a fresh usage of HeatGenerator # (Ch6/Ch7), stubbed here with just the two features (power, efficiency) the # fragment itself reads. From 2e929fe038f77cb13d7e37e0a4645faf61565fce Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:44:39 -0400 Subject: [PATCH 15/25] Phase B Ch2: TOASTER_INCREMENT assigned not printed; Pattern-2 trim on 03-judgment-context --- .../01-requirement-def.ipynb | 4 +- .../ch02-requirements/02-assumptions.ipynb | 4 +- .../03-judgment-context.ipynb | 74 ++----------------- 3 files changed, 12 insertions(+), 70 deletions(-) diff --git a/chapters/ch02-requirements/01-requirement-def.ipynb b/chapters/ch02-requirements/01-requirement-def.ipynb index 7def5ab..61faf00 100644 --- a/chapters/ch02-requirements/01-requirement-def.ipynb +++ b/chapters/ch02-requirements/01-requirement-def.ipynb @@ -99,7 +99,7 @@ { "cell_type": "code", "id": "e77ee323", - "source": "TOASTER_INCREMENT = f\"{TIMELY_TOAST_REQ}{CONSTRAINT_BODY}\\n}}\\n{NOMINAL_PART}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"", + "source": "TOASTER_INCREMENT = f\"{TIMELY_TOAST_REQ}{CONSTRAINT_BODY}\\n}}\\n{NOMINAL_PART}\"\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"", "metadata": {}, "execution_count": null, "outputs": [] @@ -167,7 +167,7 @@ "cell_type": "markdown", "id": "cell-06", "metadata": {}, - "source": "The `requirement def TimelyToast { doc /* ... */ subject toaster : Toaster; require constraint { toaster.cycleTime <= 180.0 [SI::s] } }` printed above loaded without error, and `model.find()` returns its symbol while `model.query()` lists it as a `RequirementDefinition`, confirming it's now part of the model." + "source": "The `TimelyToast` fragments printed above loaded without error, and `model.find()`/`model.query()` confirm it's now part of the model." }, { "cell_type": "markdown", diff --git a/chapters/ch02-requirements/02-assumptions.ipynb b/chapters/ch02-requirements/02-assumptions.ipynb index 6b0887d..ef78fb6 100644 --- a/chapters/ch02-requirements/02-assumptions.ipynb +++ b/chapters/ch02-requirements/02-assumptions.ipynb @@ -68,7 +68,7 @@ { "cell_type": "code", "id": "ec2c4402", - "source": "TOASTER_INCREMENT = f\"{SLOW_PART}\\n{CYCLE_OVERRIDE}\\n}}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"", + "source": "TOASTER_INCREMENT = f\"{SLOW_PART}\\n{CYCLE_OVERRIDE}\\n}}\"\nsource = Path(\"../../models/ch02-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"", "metadata": {}, "execution_count": null, "outputs": [] @@ -138,7 +138,7 @@ "cell_type": "markdown", "id": "cell-06", "metadata": {}, - "source": "The `part slow : Toaster { attribute :>> cycleTime = 200.0 [SI::s]; }` printed above loaded without error, and `slow.attributes()` returns the overridden symbol shown above, confirming the redeclaration is now part of the model." + "source": "The `slow` fragments printed above loaded without error, and `slow.attributes()` confirms the override is now part of the model." }, { "cell_type": "markdown", diff --git a/chapters/ch02-requirements/03-judgment-context.ipynb b/chapters/ch02-requirements/03-judgment-context.ipynb index a2932dc..da5525a 100644 --- a/chapters/ch02-requirements/03-judgment-context.ipynb +++ b/chapters/ch02-requirements/03-judgment-context.ipynb @@ -35,42 +35,7 @@ "name": "stdout", "output_type": "stream", "text": [ - "// GENERATED FIXTURE — do not edit directly.\n", - "// Run: python scripts/check_construction.py --check (to verify)\n", - "// Source: notebook cell-02 TOASTER_INCREMENT in chapter 2's construct-introducing notebooks.\n", - "\n", - "package ToasterDemo {\n", - " metadata def ReviewRecordRef {\n", - " attribute identifier : ScalarValues::String;\n", - " }\n", - "\n", - " private import ScalarValues::*;\n", - " private import SI::*;\n", - " private import ISQ::*;\n", - "\n", - " item def Bread;\n", - " item def Toast;\n", - "\n", - " action def ToastBread {\n", - " doc /* Transform bread into toast acceptable to its user. */\n", - " in bread : Bread;\n", - " out toast : Toast;\n", - " }\n", - "\n", - " abstract part def ToastingSystem {\n", - " perform action toastBread : ToastBread;\n", - " }\n", - "\n", - " part def HeatingSystem;\n", - " part def ControlSystem;\n", - "\n", - " part def Toaster :> ToastingSystem {\n", - " attribute cycleTime : ISQ::DurationValue;\n", - " part heating : HeatingSystem;\n", - " part control : ControlSystem;\n", - " }\n", - "\n", - " requirement def TimelyToast {\n", + "requirement def TimelyToast {\n", " doc /*\n", " * The toaster shall complete a toasting cycle in at most 180 seconds.\n", " * Rationale: kitchen workflows typically span 5-15 minutes; a cycle\n", @@ -80,17 +45,7 @@ " subject toaster : Toaster;\n", " require constraint { toaster.cycleTime <= 180.0 [SI::s] }\n", " }\n", - "\n", - " part nominal : Toaster;\n", - " metadata ac001Tag : ReviewRecordRef about nominal {\n", - " identifier = \"AC-001\";\n", - " }\n", - "\n", - " part slow : Toaster {\n", - " attribute :>> cycleTime = 200.0 [SI::s];\n", - " }\n", - "}\n", - "\n" + "attribute :>> cycleTime = 200.0 [SI::s];\n" ] } ], @@ -101,7 +56,10 @@ "\n", "conn = opensysml.connect(version=\"v0.9.0\")\n", "source = Path(\"../../models/ch02-cumulative.sysml\").read_text()\n", - "print(source)\n", + "requirement_block = source[source.index(\"requirement def\"):source.index(\"part nominal\")].strip()\n", + "override_line = next(l.strip() for l in source.splitlines() if \"attribute :>> cycleTime\" in l)\n", + "print(requirement_block)\n", + "print(override_line)\n", "model = conn.load_from_content(source, strict=False)\n", "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" ] @@ -284,25 +242,9 @@ "shell.execute_reply": "2026-10-01T05:10:18.688429Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "metadata def ReviewRecordRef {\n", - " attribute identifier : ScalarValues::String;\n", - "}\n", - "\n", - "metadata ac001Tag : ReviewRecordRef about nominal {\n", - " identifier = \"AC-001\";\n", - "}\n", - "\n" - ] - } - ], + "outputs": [], "source": [ - "TOASTER_INCREMENT = f\"{REVIEW_RECORD_REF_DEF}\\n{AC001_TAG}\"\n", - "print(TOASTER_INCREMENT)" + "TOASTER_INCREMENT = f\"{REVIEW_RECORD_REF_DEF}\\n{AC001_TAG}\"" ] }, { From 2bcb9b4ff2d87839373eefa7add1bcec6b0e9afb Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:45:31 -0400 Subject: [PATCH 16/25] Phase B Ch3: TOASTER_INCREMENT assigned not printed; Pattern-2 trim on 03-threshold-judgment --- .../ch03-measures/01-moe-definition.ipynb | 21 +-- .../ch03-measures/02-mop-candidate-eval.ipynb | 2 +- .../ch03-measures/03-threshold-judgment.ipynb | 125 +----------------- .../ch03-measures/04-verification-case.ipynb | 2 +- 4 files changed, 11 insertions(+), 139 deletions(-) diff --git a/chapters/ch03-measures/01-moe-definition.ipynb b/chapters/ch03-measures/01-moe-definition.ipynb index a4acc8c..88c47a3 100644 --- a/chapters/ch03-measures/01-moe-definition.ipynb +++ b/chapters/ch03-measures/01-moe-definition.ipynb @@ -200,7 +200,7 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": null, "id": "642b8ddc", "metadata": { "execution": { @@ -210,23 +210,8 @@ "shell.execute_reply": "2026-10-01T05:25:26.313841Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "requirement timely : TimelyToast;\n", - "metadata acC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AC-C03\";\n", - "}\n", - "\n" - ] - } - ], - "source": [ - "TOASTER_INCREMENT = f\"{TIMELY_USAGE}\\n{AC_C03_TAG}\"\n", - "print(TOASTER_INCREMENT)" - ] + "outputs": [], + "source": "TOASTER_INCREMENT = f\"{TIMELY_USAGE}\\n{AC_C03_TAG}\"" }, { "cell_type": "markdown", diff --git a/chapters/ch03-measures/02-mop-candidate-eval.ipynb b/chapters/ch03-measures/02-mop-candidate-eval.ipynb index a5b1015..bc2c284 100644 --- a/chapters/ch03-measures/02-mop-candidate-eval.ipynb +++ b/chapters/ch03-measures/02-mop-candidate-eval.ipynb @@ -54,7 +54,7 @@ "metadata": {}, "outputs": [], "execution_count": null, - "source": "SLOW_WITH_CLAIM = (\n \"part slow : Toaster {\\n\"\n \" attribute :>> cycleTime = 200.0 [SI::s];\\n\"\n f\"{SLOW_NOT_SATISFY}\\n\"\n \"}\"\n)\nTOASTER_INCREMENT = SLOW_WITH_CLAIM\nprint(TOASTER_INCREMENT)\n\nsource = Path(\"../../models/ch03-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" + "source": "SLOW_WITH_CLAIM = (\n \"part slow : Toaster {\\n\"\n \" attribute :>> cycleTime = 200.0 [SI::s];\\n\"\n f\"{SLOW_NOT_SATISFY}\\n\"\n \"}\"\n)\nTOASTER_INCREMENT = SLOW_WITH_CLAIM\n\nsource = Path(\"../../models/ch03-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", diff --git a/chapters/ch03-measures/03-threshold-judgment.ipynb b/chapters/ch03-measures/03-threshold-judgment.ipynb index af16133..9c901e4 100644 --- a/chapters/ch03-measures/03-threshold-judgment.ipynb +++ b/chapters/ch03-measures/03-threshold-judgment.ipynb @@ -20,7 +20,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "id": "cell-02", "metadata": { "execution": { @@ -30,107 +30,8 @@ "shell.execute_reply": "2026-10-01T05:25:33.757865Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "// GENERATED FIXTURE: do not edit directly.\n", - "// Run: python scripts/check_construction.py --check (to verify)\n", - "// Source: notebook cell-02 TOASTER_INCREMENT in chapter 3's construct-introducing notebooks.\n", - "\n", - "package ToasterDemo {\n", - " metadata def ReviewRecordRef {\n", - " attribute identifier : ScalarValues::String;\n", - " }\n", - "\n", - " private import ScalarValues::*;\n", - " private import SI::*;\n", - " private import ISQ::*;\n", - "\n", - " item def Bread;\n", - " item def Toast;\n", - "\n", - " action def ToastBread {\n", - " doc /* Transform bread into toast acceptable to its user. */\n", - " in bread : Bread;\n", - " out toast : Toast;\n", - " }\n", - "\n", - " abstract part def ToastingSystem {\n", - " perform action toastBread : ToastBread;\n", - " }\n", - "\n", - " part def HeatingSystem;\n", - " part def ControlSystem;\n", - "\n", - " part def Toaster :> ToastingSystem {\n", - " attribute cycleTime : ISQ::DurationValue;\n", - " part heating : HeatingSystem;\n", - " part control : ControlSystem;\n", - " }\n", - "\n", - " requirement def TimelyToast {\n", - " doc /*\n", - " * The toaster shall complete a toasting cycle in at most 180 seconds.\n", - " * Rationale: kitchen workflows typically span 5-15 minutes; a cycle\n", - " * exceeding 3 minutes delays meal preparation and falls outside where\n", - " * and how a user prepares a meal.\n", - " */\n", - " subject toaster : Toaster;\n", - " require constraint { toaster.cycleTime <= 180.0 [SI::s] }\n", - " }\n", - "\n", - " requirement timely : TimelyToast;\n", - "\n", - " metadata acC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AC-C03\";\n", - " }\n", - "\n", - " metadata asC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AS-C03\";\n", - " }\n", - "\n", - " part nominal : Toaster;\n", - " metadata ac001Tag : ReviewRecordRef about nominal {\n", - " identifier = \"AC-001\";\n", - " }\n", - "\n", - " part slow : Toaster {\n", - " attribute :>> cycleTime = 200.0 [SI::s];\n", - " assert not satisfy timely by slow;\n", - " }\n", - "\n", - " verification def TimelyToastTest {\n", - " doc /*\n", - " * Verification method: timed test of three consecutive toasting cycles at\n", - " * nominal input power; all must complete within 180 seconds.\n", - " * Method type: test (VerificationMethodKind::test, SysML v2 §7.24 Table 22).\n", - " * Note: formal #verificationMethod metadata not yet supported in OpenSysML v0.9.0;\n", - " * tracked at toaster#19 / OpenSysML#608.\n", - " * spec: SysML v2 formal/2026-03-02 §7.24.2 (VerificationCaseDefinition).\n", - " */\n", - " subject toaster : Toaster;\n", - " objective {\n", - " verify timely;\n", - " }\n", - " }\n", - "}\n", - "\n" - ] - } - ], - "source": [ - "from pathlib import Path\n", - "import opensysml\n", - "from toaster.report import format_diagnostics\n", - "\n", - "conn = opensysml.connect(version=\"v0.9.0\")\n", - "source = Path(\"../../models/ch03-cumulative.sysml\").read_text()\n", - "print(source)\n", - "model = conn.load_from_content(source, strict=False)\n", - "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" - ] + "outputs": [], + "source": "from pathlib import Path\nimport opensysml\nfrom toaster.report import format_diagnostics\n\nconn = opensysml.connect(version=\"v0.9.0\")\nsource = Path(\"../../models/ch03-cumulative.sysml\").read_text()\nlines = source.splitlines()\nexcerpt = \"\\n\".join(lines[35:47] + [\" ...\"] + lines[61:65] + [\" ...\"] + lines[66:80])\nprint(excerpt)\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", @@ -309,7 +210,7 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": null, "id": "0cb81adc", "metadata": { "execution": { @@ -319,22 +220,8 @@ "shell.execute_reply": "2026-10-01T05:25:33.775848Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "metadata asC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AS-C03\";\n", - "}\n", - "\n" - ] - } - ], - "source": [ - "TOASTER_INCREMENT = AS_C03_TAG\n", - "print(TOASTER_INCREMENT)" - ] + "outputs": [], + "source": "TOASTER_INCREMENT = AS_C03_TAG" }, { "cell_type": "markdown", diff --git a/chapters/ch03-measures/04-verification-case.ipynb b/chapters/ch03-measures/04-verification-case.ipynb index 55bf475..abd27c2 100644 --- a/chapters/ch03-measures/04-verification-case.ipynb +++ b/chapters/ch03-measures/04-verification-case.ipynb @@ -92,7 +92,7 @@ "metadata": {}, "outputs": [], "execution_count": null, - "source": "TOASTER_INCREMENT = f\"{VERIF_DEF_OPEN}\\n{DOC_COMMENT}\\n{SUBJECT_DECL}\\n{OBJECTIVE_BODY}\\n}}\"\nprint(TOASTER_INCREMENT)\nsource = Path(\"../../models/ch03-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" + "source": "TOASTER_INCREMENT = f\"{VERIF_DEF_OPEN}\\n{DOC_COMMENT}\\n{SUBJECT_DECL}\\n{OBJECTIVE_BODY}\\n}}\"\nsource = Path(\"../../models/ch03-cumulative.sysml\").read_text()\nmodel = conn.load_from_content(source, strict=False)\nassert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" }, { "cell_type": "markdown", From da001b0cb1d2aa44f07b557aef924b52fec4521c Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:48:44 -0400 Subject: [PATCH 17/25] Phase B Ch6: TOASTER_INCREMENT assigned not printed; Pattern-2 trim on 03-stopping-judgment; index.md heading sync --- .../01-subsystem-requirements.ipynb | 42 +---- .../02-second-level.ipynb | 34 +--- .../03-stopping-judgment.ipynb | 171 +----------------- chapters/ch06-recursive-decomp/index.md | 6 +- 4 files changed, 11 insertions(+), 242 deletions(-) diff --git a/chapters/ch06-recursive-decomp/01-subsystem-requirements.ipynb b/chapters/ch06-recursive-decomp/01-subsystem-requirements.ipynb index a803e2e..09c1d99 100644 --- a/chapters/ch06-recursive-decomp/01-subsystem-requirements.ipynb +++ b/chapters/ch06-recursive-decomp/01-subsystem-requirements.ipynb @@ -268,52 +268,12 @@ "shell.execute_reply": "2026-09-29T20:53:45.585087Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "action def GenerateHeat {\n", - " in energyIn : ISQ::EnergyValue[0..*];\n", - " out heatOut : ISQ::EnergyValue;\n", - "}\n", - "port def EnergyPort {\n", - " out energy : ISQ::EnergyValue[0..*];\n", - "}\n", - "action def ApplyHeat {\n", - " in bread : Bread;\n", - " in energy : ISQ::EnergyValue[0..*];\n", - " in duration : ISQ::DurationValue[0..*];\n", - " out toast : Toast;\n", - " out delivered : ISQ::EnergyValue;\n", - " out loss : ISQ::EnergyValue;\n", - " assert constraint balance {\n", - " delivered >= 0.0 [SI::J] and loss >= 0.0 [SI::J] and delivered + loss <= energy\n", - " }\n", - " first start;\n", - " then action generateHeat : GenerateHeat {\n", - " in energyIn = ApplyHeat::energy;\n", - " }\n", - " then done;\n", - "}\n", - "abstract part def HeatGenerator {\n", - " perform action generateHeat : GenerateHeat;\n", - " port energyIn : ~EnergyPort;\n", - " attribute power : ISQ::PowerValue;\n", - "}\n", - "part def HeatingAssembly :> HeatingSystem {\n", - " part heatGen : HeatGenerator;\n", - " allocation heatGenAllocation allocate applyHeat.generateHeat to heatGen;\n", - "}\n" - ] - } - ], + "outputs": [], "source": [ "TOASTER_INCREMENT = (\n", " f\"{GENERATE_HEAT_DEF}\\n{ENERGY_PORT_DEF}\\n{APPLY_HEAT_INCREMENT}\\n\"\n", " f\"{HEAT_GENERATOR_DEF}\\n{HEATING_ASSEMBLY_DEF}\"\n", ")\n", - "print(TOASTER_INCREMENT)\n", "\n", "source = Path(\"../../models/ch06-cumulative.sysml\").read_text()\n", "model = conn.load_from_content(source, strict=False)\n", diff --git a/chapters/ch06-recursive-decomp/02-second-level.ipynb b/chapters/ch06-recursive-decomp/02-second-level.ipynb index 9412584..01fab43 100644 --- a/chapters/ch06-recursive-decomp/02-second-level.ipynb +++ b/chapters/ch06-recursive-decomp/02-second-level.ipynb @@ -923,44 +923,12 @@ "shell.execute_reply": "2026-10-01T06:06:10.730822Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "requirement def HeatGenerationReq {\n", - " subject heatGen : HeatGenerator;\n", - " require constraint { heatGen.power >= 600.0 [SI::W] }\n", - "}\n", - "requirement heatGenerationReq : HeatGenerationReq;\n", - "metadata acC06Tag : ReviewRecordRef about heatGenerationReq {\n", - " identifier = \"AC-C06\";\n", - "}\n", - "\n", - "part def ResistanceCoil :> HeatGenerator {\n", - " attribute :>> power default = 800.0 [SI::W];\n", - " attribute resistance : ISQ::ResistanceValue default = 12.0 [SI::ohm];\n", - "}\n", - "metadata asC06Tag : ReviewRecordRef about ResistanceCoil {\n", - " identifier = \"AS-C06\";\n", - "}\n", - "\n", - "part rated : ResistanceCoil {\n", - " assert satisfy heatGenerationReq by rated;\n", - "}\n", - "part weak : ResistanceCoil {\n", - " attribute :>> power = 400.0 [SI::W];\n", - " assert not satisfy heatGenerationReq by weak;\n", - "}\n" - ] - } - ], + "outputs": [], "source": [ "TOASTER_INCREMENT = (\n", " f\"{HEAT_GENERATION_REQ_DEF}\\n{AC_C06_TAG}\\n{RESISTANCE_COIL_DEF}\\n{AS_C06_TAG}\\n\"\n", " f\"{RATED_USAGE}\\n{WEAK_USAGE}\"\n", ")\n", - "print(TOASTER_INCREMENT)\n", "\n", "reload = conn.load_from_content(source, strict=False)\n", "assert reload.ok, f\"Model failed: {format_diagnostics(reload.diagnostics)}\"" diff --git a/chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb b/chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb index ae6fbbc..32e84fd 100644 --- a/chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb +++ b/chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb @@ -35,143 +35,6 @@ "name": "stdout", "output_type": "stream", "text": [ - "// GENERATED FIXTURE: do not edit directly.\n", - "// Run: python scripts/check_construction.py --check (to verify)\n", - "// Source: notebook cell-02 TOASTER_INCREMENT in chapter 6's construct-introducing notebooks.\n", - "\n", - "package ToasterDemo {\n", - " metadata def ReviewRecordRef {\n", - " attribute identifier : ScalarValues::String;\n", - " }\n", - "\n", - " private import ScalarValues::*;\n", - " private import SI::*;\n", - " private import ISQ::*;\n", - "\n", - " item def Bread;\n", - " item def Toast;\n", - "\n", - " action def ApplyHeat {\n", - " in bread : Bread;\n", - " in energy : ISQ::EnergyValue[0..*];\n", - " in duration : ISQ::DurationValue[0..*] {\n", - " doc /* Signal from a control function: how long to apply heat.\n", - " * No control function is modeled in this chapter, so this input\n", - " * is declared and typed but not yet connected to a value. */\n", - " }\n", - " out toast : Toast;\n", - " out delivered : ISQ::EnergyValue;\n", - " out loss : ISQ::EnergyValue;\n", - "\n", - " assert constraint balance {\n", - " delivered >= 0.0 [SI::J] and loss >= 0.0 [SI::J] and delivered + loss <= energy\n", - " }\n", - "\n", - " first start;\n", - " then action generateHeat : GenerateHeat {\n", - " in energyIn = ApplyHeat::energy;\n", - " }\n", - " then done;\n", - " }\n", - "\n", - " metadata aiC04Tag : ReviewRecordRef about ApplyHeat {\n", - " identifier = \"AI-C04\";\n", - " }\n", - "\n", - " action def ToastBread {\n", - " doc /* Transform bread into toast acceptable to its user. */\n", - " in bread : Bread;\n", - " out toast : Toast;\n", - " first start;\n", - " then action applyHeat : ApplyHeat {\n", - " in bread = ToastBread::bread;\n", - " }\n", - " then done;\n", - " }\n", - "\n", - " abstract part def ToastingSystem {\n", - " perform action toastBread : ToastBread;\n", - " }\n", - "\n", - " port def DurationPort {\n", - " doc /* Carries a duration signal: how long to apply heat. */\n", - " out duration : ISQ::DurationValue[0..*];\n", - " }\n", - "\n", - " abstract part def HeatingSystem {\n", - " doc /* The logical carrier of the heating mechanism: performs ApplyHeat\n", - " * and exposes a port for a duration signal from a control component. */\n", - " perform action applyHeat : ApplyHeat;\n", - " port durationIn : ~DurationPort;\n", - " }\n", - " part def ControlSystem {\n", - " port durationOut : DurationPort;\n", - " }\n", - "\n", - " part def Toaster :> ToastingSystem {\n", - " attribute cycleTime : ISQ::DurationValue;\n", - " part heating : HeatingSystem;\n", - " part control : ControlSystem;\n", - " interface durationInterface connect control.durationOut to heating.durationIn;\n", - " allocation heatAllocation allocate toastBread.applyHeat to heating;\n", - " }\n", - "\n", - " requirement def TimelyToast {\n", - " doc /*\n", - " * The toaster shall complete a toasting cycle in at most 180 seconds.\n", - " * Rationale: kitchen workflows typically span 5-15 minutes; a cycle\n", - " * exceeding 3 minutes delays meal preparation and falls outside where\n", - " * and how a user prepares a meal.\n", - " */\n", - " subject toaster : Toaster;\n", - " require constraint { toaster.cycleTime <= 180.0 [SI::s] }\n", - " }\n", - "\n", - " requirement timely : TimelyToast;\n", - "\n", - " metadata acC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AC-C03\";\n", - " }\n", - "\n", - " metadata asC03Tag : ReviewRecordRef about timely {\n", - " identifier = \"AS-C03\";\n", - " }\n", - "\n", - " part nominal : Toaster;\n", - " metadata ac001Tag : ReviewRecordRef about nominal {\n", - " identifier = \"AC-001\";\n", - " }\n", - "\n", - " part slow : Toaster {\n", - " attribute :>> cycleTime = 200.0 [SI::s];\n", - " assert not satisfy timely by slow;\n", - " }\n", - "\n", - " verification def TimelyToastTest {\n", - " doc /*\n", - " * Verification method: timed test of three consecutive toasting cycles at\n", - " * nominal input power; all must complete within 180 seconds.\n", - " * Method type: test (VerificationMethodKind::test, SysML v2 §7.24 Table 22).\n", - " * Note: formal #verificationMethod metadata not yet supported in OpenSysML v0.9.0;\n", - " * tracked at toaster#19 / OpenSysML#608.\n", - " * spec: SysML v2 formal/2026-03-02 §7.24.2 (VerificationCaseDefinition).\n", - " */\n", - " subject toaster : Toaster;\n", - " objective {\n", - " verify timely;\n", - " }\n", - " }\n", - "\n", - " item def Start {\n", - " doc /* Signal marking the start of a toasting cycle, not the bread itself. */\n", - " }\n", - " item def Finish {\n", - " doc /* Signal marking the finish of a toasting cycle, not the toast itself. */\n", - " }\n", - " item def Cancel {\n", - " doc /* Signal requesting cancellation of an in-progress toasting cycle. */\n", - " }\n", - "\n", " port def EnergyPort {\n", " doc /* Carries an energy signal delivered to a heat generator, not\n", " * committed to any particular energy form. */\n", @@ -199,15 +62,6 @@ " attribute power : ISQ::PowerValue;\n", " }\n", "\n", - " part def HeatingAssembly :> HeatingSystem {\n", - " part heatGen : HeatGenerator;\n", - " allocation heatGenAllocation allocate applyHeat.generateHeat to heatGen;\n", - " }\n", - "\n", - " metadata aiC06Tag : ReviewRecordRef about HeatingAssembly::heatGen {\n", - " identifier = \"AI-C06\";\n", - " }\n", - "\n", " requirement def HeatGenerationReq {\n", " doc /*\n", " * A heat generator shall be rated for at least 600 W.\n", @@ -246,9 +100,7 @@ " part weak : ResistanceCoil {\n", " attribute :>> power = 400.0 [SI::W];\n", " assert not satisfy heatGenerationReq by weak;\n", - " }\n", - "}\n", - "\n" + " }\n" ] } ], @@ -261,7 +113,8 @@ "\n", "conn = opensysml.connect(version=\"v0.9.0\")\n", "source = Path(\"../../models/ch06-cumulative.sysml\").read_text()\n", - "print(source)\n", + "lines = source.splitlines()\n", + "print(\"\\n\".join(lines[137:164] + lines[173:212]))\n", "model = conn.load_from_content(source, strict=False)\n", "assert model.ok, f\"Model failed: {format_diagnostics(model.diagnostics)}\"" ] @@ -302,7 +155,7 @@ "id": "cell-03", "metadata": {}, "source": [ - "The cumulative model prints above: `GenerateHeat` nested inside `ApplyHeat`, `HeatGenerator` performing it through a declared energy port, `HeatingAssembly` composing that carrier, the usage-level allocation between them, and `ResistanceCoil`'s two candidates, `rated` and `weak`, checked against `heatGenerationReq`. The next cell checks what happens when an inference record's own required field is left empty." + "HeatGenerator, EnergyPort, HeatGenerationReq, ResistanceCoil, rated and weak loaded without error, and the diagram confirms HeatingAssembly composing heatGen, typed by HeatGenerator. The next cell checks what happens when an inference record's own required field is left empty." ] }, { @@ -491,21 +344,9 @@ "shell.execute_reply": "2026-10-01T06:06:12.743114Z" } }, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "metadata aiC06Tag : ReviewRecordRef about HeatingAssembly::heatGen {\n", - " identifier = \"AI-C06\";\n", - "}\n", - "\n" - ] - } - ], + "outputs": [], "source": [ - "TOASTER_INCREMENT = AI_C06_TAG\n", - "print(TOASTER_INCREMENT)" + "TOASTER_INCREMENT = AI_C06_TAG" ] }, { diff --git a/chapters/ch06-recursive-decomp/index.md b/chapters/ch06-recursive-decomp/index.md index c65ce3f..82cb060 100644 --- a/chapters/ch06-recursive-decomp/index.md +++ b/chapters/ch06-recursive-decomp/index.md @@ -14,9 +14,9 @@ After completing this chapter, the cumulative model has a real second-level func | Notebook | Concept | |---|---| -| [01: Level-2 Function and Logical Carrier](01-subsystem-requirements.ipynb) | Nest `GenerateHeat` inside `ApplyHeat`, the same way `ApplyHeat` nests inside `ToastBread`, and give it a logical carrier, `HeatGenerator`, one level below `HeatingSystem`; neither commits to an energy form or mechanism. | -| [02: Level-2 Physical Realization](02-second-level.ipynb) | State the requirement `HeatGenerator`'s rating is checked against, record the measure framing and the mechanism selection that requirement raises, then build `ResistanceCoil`, the concrete realization the selection licenses. | -| [03: Stopping Judgment](03-stopping-judgment.ipynb) | Record `AI-C06`, an `asserted_inference` checked against real analysis on the loaded model, stating plainly what this one branch establishes and what it does not. | +| [01: level-2 function and logical carrier](01-subsystem-requirements.ipynb) | Nest `GenerateHeat` inside `ApplyHeat`, the same way `ApplyHeat` nests inside `ToastBread`, and give it a logical carrier, `HeatGenerator`, one level below `HeatingSystem`; neither commits to an energy form or mechanism. | +| [02: level-2 physical realization](02-second-level.ipynb) | State the requirement `HeatGenerator`'s rating is checked against, record the measure framing and the mechanism selection that requirement raises, then build `ResistanceCoil`, the concrete realization the selection licenses. | +| [03: stopping judgment](03-stopping-judgment.ipynb) | Record `AI-C06`, an `asserted_inference` checked against real analysis on the loaded model, stating plainly what this one branch establishes and what it does not. | ## Equipment From c7c47695372261d9c7899473cbba710907a60244 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:54:46 -0400 Subject: [PATCH 18/25] DL-094/DL-095: Ch5 ApplyHeat-grounding escalated to Z; Ch3 stale-narration escalation closed (premise was false, no fix needed) --- decisions/log.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/decisions/log.md b/decisions/log.md index adab55f..ced3172 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1309,6 +1309,30 @@ Extension: no. Provenance: `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 1-2 and "The two target patterns"; `decisions/diagram-text-integration-survey.md` (all 9 chapter tables; cross-chapter open questions 1 and 7); `.claude/skills/tutorial-style-guide/SKILL.md` 93-101; `.claude/skills/toaster-recipe/SKILL.md` 18, 40-44, 90-92, 101, 189, 204-210; `scripts/check_construction.py` 11-13, 378-421; AGENTS.md 1.7, 1.9; DL-011, DL-012 (origin of the "print as reflection" convention); DL-084 (P5 applied the same way to a seam's result step); ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. +## DL-094 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Ch5-01 spot-check NEEDS-FIX (ApplyHeat ungrounded after dump removal): classified minor; the one-clause fix to cell 1 lies outside the redesign's enumerated scope; escalated to Z with default B + +Path: Escalated to Z -- user-test finding +Decision: pending Z. ACE recommends B: add "action definitions" to cell 1's element list of `chapters/ch05-architecture/01-model-navigation.ipynb` via a new narrow contract (same harness), then re-run the SE Practitioner spot-check. Alternatives A (no change), C (bridge sentence before cell 8), D (restore excerpt print; disfavored). +Principles applied: P4 (heuristic 6), P3, P5, P6; spec Decision 4, Parsimony heuristic, Rolling-cleanup closing paragraph and Verification section applied as Z's prior decisions; user-testing SKILL.md synthesis protocol steps 2-3 and its blocking / not-blocking lists. +Reasoning: (1) Evidence verified: `models/ch05-cumulative.sysml` line 17 declares `action def ApplyHeat`; `figures/ch05-structure.svg` draws no action; cell 1's list omits action definitions, which the survey's residual rationale (line 169) relied on. The learner's claim about `index.md` is wrong: it names `ApplyHeat` twice, including as "Chapter 4's function", and is checklist step 1; cell 9 states the declaration site; cell 8 prints `kind='actionDef'`. The gap is notebook-local friction. (2) None of the five blocking criteria applies; the finding is minor ("concept already covered"); the protocol reserves minor items for Z. (3) Cell 1 is an existing narration cell outside Patterns 1/1b/2 and the four cleanup items; the Z-confirmed spec says such a cell is touched only if "separately escalated to Z". (4) On the merits P4 favors B (two words, corrects an omission, not load-bearing, no teaching change); P3 would favor C; P3/P5 disfavor D. (5) Whether notebook-local grounding justifies reopening a closed scope boundary is the trade Z reserved. +Determined: no -- steps 2 and 3 determine that the ACE does not decide (minor item; cell outside enumerated scope), not what Z should decide. +Extension: no. +Provenance: `models/ch05-cumulative.sysml` 17-47, 58-74; `figures/ch05-structure.svg` node labels; `chapters/ch05-architecture/01-model-navigation.ipynb` cells 1, 3, 7, 8, 9; `chapters/ch05-architecture/index.md` Purpose and Method; `chapters/ch04-functional-decomp/index.md` 9, 15, 25; `decisions/diagram-text-integration-survey.md` 158-169; `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 3-4 (17-18), Parsimony heuristic (61), Rolling cleanup (72), Non-goals, Verification; `docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-b-plan.md` Task 5; `.claude/skills/user-testing/SKILL.md` 107-130; `.claude/skills/tutorial-style-guide/SKILL.md` 13 (20-word default ceiling); ACE's own run of cells 2, 6, 8 on 2026-10-02 (`model.ok` True; neg control `'unresolved reference: UndefinedBase'`; `ApplyHeat` kind `actionDef`); DL-092, DL-093 (Decisions 1-2 as applied). + Brief: objective -- a reader of 01-model-navigation can place `ApplyHeat` before cell 8 looks it up, without giving back the parsimony this redesign bought. Design space: A. no change (grounding exists in index.md twice, in Ch4, and in cell 9) | B. +2 words in cell 1, "action definitions" | C. one bridge sentence before cell 8 naming `ApplyHeat` as Chapter 4's action def the containment diagram does not draw | D. restore an excerpt print (disfavored -- reopens a verified residual). Candidate B: no model/diagram/teaching change; cell 1's sentence is already 21 words against the style guide's 20-word default ceiling and becomes 23; needs a narrow new contract since the Parsimony heuristic bars touching this cell without Z's say. MoE: the learner no longer reports `ApplyHeat` ungrounded. MoP: a re-run SE Practitioner spot-check passes; the diff touches exactly one sentence. ACE recommendation: B. If Z would rather hold the redesign's line, A costs nothing further. + Z's decision: [pending] + Z's rationale: [pending] + +## DL-095 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Ch3 "printed above" cells after the DL-092/093 reprint removal: no orphaned references in any chapter; returned to orchestrator, no sweep dispatched + +Path: Returned to orchestrator +Decision: The Ch3 builder's open question (five markdown cells saying "printed above" after the `TOASTER_INCREMENT` reprint was removed) rests on a false premise. In every case the referent is still printed above: the fragment's declaration-time `print(FRAGMENT)`, and for tags also the `Model tag:` confirmation line. The same holds in all nine Phase B chapters (merged chapters checked in the working tree; Ch3 and Ch6 checked on their own branches before merge). No cross-chapter sweep, no per-chapter follow-up contract, no deferral item. The original escalation (which claimed 4 stale cells, later corrected to 2 definite + 1 soft by an independent reviewer) is superseded by this closer check, which found the corrected 2 are also not stale -- the reviewer's own correction tested the wrong predicate ("does the cell quote an assembled block") rather than the right one ("is the referent printed anywhere above this cell"). +Principles applied: ace-protocol "probe before asserting" and "a prior decision by Z on the same question is applied as a decision" (DL-092, DL-093; spec Decisions 1, 2, 4); P4 (a sweep for a non-defect makes nothing easier for the learner); P5 (the removed line was a duplicate, so its removal cannot by itself orphan a "printed above" reference). +Reasoning: (1) DL-092's ruling removed only the assembly-cell reprint and was justified by "each fragment was already printed when declared"; the declaration prints survive by construction. (2) Verified on `phase-b/ch03`: all five "printed above" cells have a `print(FRAGMENT)` or `Model tag:` line in a preceding code cell. (3) Verified across Ch1-8 and Ch10 with the same scan: no "printed above" cell lacks its referent; the few that aren't about a fragment print (Ch5-01 cell 9, Ch8-03 cell 9, Ch10-01 cells 9/16, Ch10-03 cell 26) refer to query/record output, untouched by Phase B. (4) Spec Decision 4 and the Non-goals forbid expanding Phase B scope without a named, bounded item; there is none, so nothing is dispatched. (5) Three cells quoting an assembled whole in one string (Ch3-04 c15, Ch4-01 c23, Ch4-02 c13) remain true because every piece is still printed in order; whether to show the assembled block once more was already decided in Decision 2 and is not reopened. +Determined: yes +Extension: no +Provenance: DL-092 ("each fragment was already printed when declared"); DL-093 ("the `Model tag:` line printed when the record assembles is its confirmation, not a second print of the fragment"); `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 2 and 4, "Rolling cleanup, enumerated", Non-goals; `phase-b/ch03` commit `2bcb9b4` notebook contents; scan over `chapters/*/*.ipynb` on `diagram-text-integration` plus `phase-b/ch03` and `phase-b/ch06` before merge; ACE report, agentId `a4b788e2a9fe91b02`, delivered 2026-10-02. +Optional follow-up (not ruled, for Z or the backlog): a guard in `scripts/check_construction.py` or a test asserting every markdown "printed above" is preceded by a fragment print or `Model tag:` line; its own contract if taken up. + ## DL-093 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | COMPLETE -- judgment-record tag reprint ruled the same defect as DL-092, not a sanctioned exception; the "judgment notebooks never assign TOASTER_INCREMENT" lines in two skills are stale since DL-084 and are corrected in the same pass Path: ACE triage (ruled; flagged "Extension: yes" per the ACE's own report, since this applies Z's Decision 1 to a case -- the judgment-record tag increments registered under DL-084 -- that Decision 1's own scope statement did not name at the time it was written). Same `skill-editor` gate as DL-092 applies (multiple archetypes' primary skills): Z's one-line confirmation of the replacement wording below was required before any edit; the edit has been made (commit `fbdbc1d`). From 3deb39d7a0ba53dcbeff43b0f34d23e48eed727d Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:57:28 -0400 Subject: [PATCH 19/25] Correct decisions/diagram-survey.md (ch05 triple-dump did not exist); DL-096 corrects DL-095 (2 Ch3 seam cells really are stale, follow-up contract dispatched) --- decisions/diagram-survey.md | 2 +- decisions/log.md | 12 +++++++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/decisions/diagram-survey.md b/decisions/diagram-survey.md index 68e1024..6f2a405 100644 --- a/decisions/diagram-survey.md +++ b/decisions/diagram-survey.md @@ -166,7 +166,7 @@ its one allocation is already shown, as an edge, in notebook 03's own interconne | notebook | cell/output under consideration | proposed diagram type | proposed tool/function | add-or-replace | visual notation introduced | rationale | |---|---|---|---|---|---|---| | `01-concept-selection.ipynb` | cell-02: a 131-line verbatim model dump | Structure/containment | `model_to_dot()` (unscoped — model still small) | add | reused | Densest text block in the chapter; the model is "too large to navigate by position," per the notebook's own text. | -| `02-allocate.ipynb` cell-06 / `03-interfaces.ipynb` cell-10 | same 131-line dump, repeated verbatim | — | — | **no candidate** | — | Identical content already shown once in this chapter; a second/third copy would be diagram fatigue, not a real reduction in parsing burden. | +| `02-allocate.ipynb` cell-06 / `03-interfaces.ipynb` cell-10 | ~~same 131-line dump, repeated verbatim~~ — **correction, 2026-10-02 (diagram/text integration Phase A):** this row was factually wrong. Direct re-read of the live files (and of this document's own commit history) confirms neither cell ever printed the full 131-line dump — each prints only its own small `TOASTER_INCREMENT` fragment (9 and ~15 lines respectively). See `decisions/diagram-text-integration-survey.md`'s own Chapter 5 section for the real finding and fix. | — | — | **no candidate** | — | Identical content already shown once in this chapter; a second/third copy would be diagram fatigue, not a real reduction in parsing burden. (Rationale for "no candidate" stands; the premise describing what these two cells print was wrong, not the conclusion.) | | `03-interfaces.ipynb` | cell-16 (existing): the chapter's own pre-existing interconnection figure | Interconnection (port-level) | **sysml-toolkit** `--view interconnection --element ToasterDemo::Toaster` (upgrade from the in-house `render_interconnection()`) | replace (same cell, swap the rendering tool) | **new** — first interconnection view in the tutorial | Phase 0 confirmed directly on this fixture: OpenSysML draws zero port-name tokens (only the interface-level edge label); sysml-toolkit draws the real `durationIn`/`durationOut` port names. The chapter's entire subject is this one conjugated port — port identity belongs in a drawn box here, and this sets the visual vocabulary every later chapter's interconnection view reuses. | ## Chapter 6 — recursive-decomp diff --git a/decisions/log.md b/decisions/log.md index ced3172..75c9aa4 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1322,7 +1322,17 @@ Provenance: `models/ch05-cumulative.sysml` 17-47, 58-74; `figures/ch05-structure Z's decision: [pending] Z's rationale: [pending] -## DL-095 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Ch3 "printed above" cells after the DL-092/093 reprint removal: no orphaned references in any chapter; returned to orchestrator, no sweep dispatched +## DL-096 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Correction to DL-095: 2 of Ch3's "printed above" cells ARE genuinely stale (describe an assembled block the removed print alone produced); fixed via a small follow-up contract, no cross-chapter sweep needed + +Path: Handled by ACE (same agent as DL-095, re-ruling on its own prior output after the orchestrator relayed a reviewer's corrected fact pattern) +Decision: DL-095's "no orphaned references in any chapter" conclusion is corrected. Applying the right predicate ("does the cell quote or describe an assembled/folded form that only the removed reprint produced," not merely "does it say the word 'above'"), a full re-scan of all 36 "printed above" cells across all 9 Phase B chapters found exactly 2 genuinely stale cells, both in the already-merged `chapters/ch03-measures/`: `02-mop-candidate-eval.ipynb` cell index 10 (claimed the *folded* `slow`-body form was printed above; only the bare assert line is) and `04-verification-case.ipynb` cell index 15 (quoted the single *assembled* `verification def` block; only its four fragments are printed). No other chapter has this defect -- every other "printed above" cell, including `02-mop-candidate-eval.ipynb` cell index 3 and `ch04-functional-decomp/01-action-def-ffbd.ipynb` cell index 23, reads accurately on direct re-check. Since Ch3 was already merged by the time this ruling arrived (a race between the ACE's analysis and the orchestrator's own merge queue), the fix is dispatched as a small, separate follow-up contract (`phase-b/ch03-seam-fix`) rather than amended into the closed `phase-b/ch03` task -- same harness, same builder/reviewer model pins, blast zone limited to exactly the 2 cells. +Principles applied: ace-protocol "probe before asserting" (the first scan used the wrong predicate and produced a false negative); P5 (record the correction durably rather than silently overwrite DL-095); Decision 4 (the fix is still a named, bounded item, not a reopened discovery pass). +Reasoning: (1) The corrected predicate matters because DL-092's own ruling only guarantees that *individual fragments* survive as prints at declaration -- it says nothing about whether an *assembled/folded* form (built by concatenating fragments in a later cell) is still shown anywhere. A seam cell that quotes or describes that assembled form, rather than naming the individual fragments, goes stale the moment the reprint is removed, even though "something is printed above" remains true in a weaker sense. (2) Both stale cells are in Ch3, which is the one chapter whose own Phase A survey agent did not catch this (every other affected chapter -- Ch1-04, Ch2-01/02, Ch5-02/03 -- got an explicit seam reword in its own original contract, because those survey agents happened to notice the seam cell quoting a literal block). (3) Fixing inside a reopened Ch3 contract was the ACE's first preference but is moot once merged; a small, independently-reviewed follow-up contract achieves the same rigor without reverting a clean merge. +Determined: yes. +Extension: no. +Provenance: DL-095 (the corrected entry); DL-092, DL-093 (the rulings whose scope this corrects a misapplication of); `phase-b/ch03` commit `2bcb9b4` cell contents; the independent reviewer's corrected 4-to-2 count (relayed by the orchestrator); ACE's own full re-scan, agentId `a4b788e2a9fe91b02`, second report, delivered 2026-10-02; follow-up contract `phase-b/ch03-seam-fix`. + +## DL-095 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Ch3 "printed above" cells after the DL-092/093 reprint removal: no orphaned references in any chapter; returned to orchestrator, no sweep dispatched (SUPERSEDED BY DL-096 -- the predicate used here missed 2 genuinely stale cells) Path: Returned to orchestrator Decision: The Ch3 builder's open question (five markdown cells saying "printed above" after the `TOASTER_INCREMENT` reprint was removed) rests on a false premise. In every case the referent is still printed above: the fragment's declaration-time `print(FRAGMENT)`, and for tags also the `Model tag:` confirmation line. The same holds in all nine Phase B chapters (merged chapters checked in the working tree; Ch3 and Ch6 checked on their own branches before merge). No cross-chapter sweep, no per-chapter follow-up contract, no deferral item. The original escalation (which claimed 4 stale cells, later corrected to 2 definite + 1 soft by an independent reviewer) is superseded by this closer check, which found the corrected 2 are also not stale -- the reviewer's own correction tested the wrong predicate ("does the cell quote an assembled block") rather than the right one ("is the referent printed anywhere above this cell"). From e24747a2fb74a34021fabf31d5fdaf10a11b690d Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:59:35 -0400 Subject: [PATCH 20/25] Phase B Ch3 follow-up: fix 2 seam cells still describing the removed assembled-block print --- chapters/ch03-measures/02-mop-candidate-eval.ipynb | 4 +--- chapters/ch03-measures/04-verification-case.ipynb | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/chapters/ch03-measures/02-mop-candidate-eval.ipynb b/chapters/ch03-measures/02-mop-candidate-eval.ipynb index bc2c284..0ec4f0a 100644 --- a/chapters/ch03-measures/02-mop-candidate-eval.ipynb +++ b/chapters/ch03-measures/02-mop-candidate-eval.ipynb @@ -100,9 +100,7 @@ "cell_type": "markdown", "id": "cell-10", "metadata": {}, - "source": [ - "`assert not satisfy timely by slow;`, folded into `slow`'s own body and printed above, loaded without error; `model.eval()` confirms the negated claim holds against `slow`'s own values, shown by the `False` result above." - ] + "source": "`assert not satisfy timely by slow;`, printed above, loaded without error; `model.eval()` confirms the negated claim holds against `slow`'s own values, shown by the `False` result above." }, { "cell_type": "markdown", diff --git a/chapters/ch03-measures/04-verification-case.ipynb b/chapters/ch03-measures/04-verification-case.ipynb index abd27c2..87d8e98 100644 --- a/chapters/ch03-measures/04-verification-case.ipynb +++ b/chapters/ch03-measures/04-verification-case.ipynb @@ -130,7 +130,7 @@ "cell_type": "markdown", "id": "cell-06", "metadata": {}, - "source": "`verification def TimelyToastTest { doc /* ... */ subject toaster : Toaster; objective { verify timely; } }` printed above loaded without error, and `model.find()` returns its symbol, confirmed as a `VerificationCaseDefinition` by `model.query()` above." + "source": "The `TimelyToastTest` fragments printed above loaded without error, and `model.find()` returns its symbol, confirmed as a `VerificationCaseDefinition` by `model.query()` above." }, { "cell_type": "markdown", From 3f3ae5d40e29a30e7887bcb1a73f47683ccb451f Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 12:21:17 -0400 Subject: [PATCH 21/25] DL-094: record Z's decision (option C, revised to reference Ch4's existing action-flow diagram) --- decisions/log.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/decisions/log.md b/decisions/log.md index 75c9aa4..1bfab8a 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1309,7 +1309,7 @@ Extension: no. Provenance: `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 1-2 and "The two target patterns"; `decisions/diagram-text-integration-survey.md` (all 9 chapter tables; cross-chapter open questions 1 and 7); `.claude/skills/tutorial-style-guide/SKILL.md` 93-101; `.claude/skills/toaster-recipe/SKILL.md` 18, 40-44, 90-92, 101, 189, 204-210; `scripts/check_construction.py` 11-13, 378-421; AGENTS.md 1.7, 1.9; DL-011, DL-012 (origin of the "print as reflection" convention); DL-084 (P5 applied the same way to a seam's result step); ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. -## DL-094 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Ch5-01 spot-check NEEDS-FIX (ApplyHeat ungrounded after dump removal): classified minor; the one-clause fix to cell 1 lies outside the redesign's enumerated scope; escalated to Z with default B +## DL-094 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Ch5-01 spot-check NEEDS-FIX (ApplyHeat ungrounded after dump removal): Z chose option C, revised -- a bridge sentence pointing to Chapter 4's existing action-flow diagram, not a generic "diagrams don't show actions" claim Path: Escalated to Z -- user-test finding Decision: pending Z. ACE recommends B: add "action definitions" to cell 1's element list of `chapters/ch05-architecture/01-model-navigation.ipynb` via a new narrow contract (same harness), then re-run the SE Practitioner spot-check. Alternatives A (no change), C (bridge sentence before cell 8), D (restore excerpt print; disfavored). @@ -1319,8 +1319,8 @@ Determined: no -- steps 2 and 3 determine that the ACE does not decide (minor it Extension: no. Provenance: `models/ch05-cumulative.sysml` 17-47, 58-74; `figures/ch05-structure.svg` node labels; `chapters/ch05-architecture/01-model-navigation.ipynb` cells 1, 3, 7, 8, 9; `chapters/ch05-architecture/index.md` Purpose and Method; `chapters/ch04-functional-decomp/index.md` 9, 15, 25; `decisions/diagram-text-integration-survey.md` 158-169; `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 3-4 (17-18), Parsimony heuristic (61), Rolling cleanup (72), Non-goals, Verification; `docs/superpowers/plans/2026-10-02-diagram-text-integration-phase-b-plan.md` Task 5; `.claude/skills/user-testing/SKILL.md` 107-130; `.claude/skills/tutorial-style-guide/SKILL.md` 13 (20-word default ceiling); ACE's own run of cells 2, 6, 8 on 2026-10-02 (`model.ok` True; neg control `'unresolved reference: UndefinedBase'`; `ApplyHeat` kind `actionDef`); DL-092, DL-093 (Decisions 1-2 as applied). Brief: objective -- a reader of 01-model-navigation can place `ApplyHeat` before cell 8 looks it up, without giving back the parsimony this redesign bought. Design space: A. no change (grounding exists in index.md twice, in Ch4, and in cell 9) | B. +2 words in cell 1, "action definitions" | C. one bridge sentence before cell 8 naming `ApplyHeat` as Chapter 4's action def the containment diagram does not draw | D. restore an excerpt print (disfavored -- reopens a verified residual). Candidate B: no model/diagram/teaching change; cell 1's sentence is already 21 words against the style guide's 20-word default ceiling and becomes 23; needs a narrow new contract since the Parsimony heuristic bars touching this cell without Z's say. MoE: the learner no longer reports `ApplyHeat` ungrounded. MoP: a re-run SE Practitioner spot-check passes; the diff touches exactly one sentence. ACE recommendation: B. If Z would rather hold the redesign's line, A costs nothing further. - Z's decision: [pending] - Z's rationale: [pending] + Z's decision: C, revised. Z caught that the ACE's/orchestrator's draft wording of option C ("a containment diagram doesn't draw actions") risked being read as "diagrams don't show actions" -- false in this tutorial, which has action-flow diagrams elsewhere (`figures/ch04-toastbread-flow.svg`, `figures/ch06-applyheat-flow.svg`, both confirmed by grep to contain a real `ApplyHeat` `«action def»`/`«action»` node). Z asked whether the fix should instead reference an existing action-flow diagram rather than state a generic negative, and whether one needed to be built. Checked: one already exists and is reachable without a forward reference -- `figures/ch04-toastbread-flow.svg`, built in Chapter 4, which the reader has already completed by Ch5 (Chapter 6's own `figures/ch06-applyheat-flow.svg` would be a forward reference to content not yet reached, so it was not used). Final wording, inserted as its own new markdown cell between the existing cell 7 and cell 8 of `chapters/ch05-architecture/01-model-navigation.ipynb`: "`ApplyHeat` was already drawn in Chapter 4's own action-flow diagram, nested inside `ToastBread`; the containment diagram above shows parts, not actions." Dispatched via a new narrow contract (`phase-b/ch05-applyheat-bridge`), same harness (builder sonnet, reviewer opus). + Z's rationale: a bridge sentence that only states what this diagram can't show, without pointing at one that can, teaches an overgeneralization by omission; since this tutorial already has the right diagram built two chapters earlier, referencing it is free and more precise than either patching cell 1's enumeration (option B) or stating a bare negative (the original draft of C). ## DL-096 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Correction to DL-095: 2 of Ch3's "printed above" cells ARE genuinely stale (describe an assembled block the removed print alone produced); fixed via a small follow-up contract, no cross-chapter sweep needed From 2a8b00311ebb796747b73bc00712f21b892c6d17 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 12:23:01 -0400 Subject: [PATCH 22/25] Ch5-01: add bridge sentence grounding ApplyHeat via Chapter 4's existing action-flow diagram (DL-094, option C) --- chapters/ch05-architecture/01-model-navigation.ipynb | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/chapters/ch05-architecture/01-model-navigation.ipynb b/chapters/ch05-architecture/01-model-navigation.ipynb index a64b045..4f1764e 100644 --- a/chapters/ch05-architecture/01-model-navigation.ipynb +++ b/chapters/ch05-architecture/01-model-navigation.ipynb @@ -87,6 +87,14 @@ "The diagnostic reports an unresolved reference: `UndefinedBase` is not a name in scope, so the model fails to load before any navigation can run." ] }, + { + "cell_type": "markdown", + "id": "cell-07a", + "metadata": {}, + "source": [ + "`ApplyHeat` was already drawn in Chapter 4's own action-flow diagram, nested inside `ToastBread`; the containment diagram above shows parts, not actions." + ] + }, { "cell_type": "code", "id": "cell-08", From 291f12c87290bd08536260912284600adf168fe9 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 12:28:02 -0400 Subject: [PATCH 23/25] DL-094: COMPLETE -- re-run SE Practitioner spot-check confirms the ApplyHeat grounding fix --- decisions/log.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/decisions/log.md b/decisions/log.md index 1bfab8a..24e5ea1 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1309,7 +1309,7 @@ Extension: no. Provenance: `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decisions 1-2 and "The two target patterns"; `decisions/diagram-text-integration-survey.md` (all 9 chapter tables; cross-chapter open questions 1 and 7); `.claude/skills/tutorial-style-guide/SKILL.md` 93-101; `.claude/skills/toaster-recipe/SKILL.md` 18, 40-44, 90-92, 101, 189, 204-210; `scripts/check_construction.py` 11-13, 378-421; AGENTS.md 1.7, 1.9; DL-011, DL-012 (origin of the "print as reflection" convention); DL-084 (P5 applied the same way to a seam's result step); ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. -## DL-094 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Ch5-01 spot-check NEEDS-FIX (ApplyHeat ungrounded after dump removal): Z chose option C, revised -- a bridge sentence pointing to Chapter 4's existing action-flow diagram, not a generic "diagrams don't show actions" claim +## DL-094 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | COMPLETE -- Ch5-01 spot-check NEEDS-FIX (ApplyHeat ungrounded after dump removal): Z chose option C, revised -- a bridge sentence pointing to Chapter 4's existing action-flow diagram, not a generic "diagrams don't show actions" claim Path: Escalated to Z -- user-test finding Decision: pending Z. ACE recommends B: add "action definitions" to cell 1's element list of `chapters/ch05-architecture/01-model-navigation.ipynb` via a new narrow contract (same harness), then re-run the SE Practitioner spot-check. Alternatives A (no change), C (bridge sentence before cell 8), D (restore excerpt print; disfavored). @@ -1321,6 +1321,7 @@ Provenance: `models/ch05-cumulative.sysml` 17-47, 58-74; `figures/ch05-structure Brief: objective -- a reader of 01-model-navigation can place `ApplyHeat` before cell 8 looks it up, without giving back the parsimony this redesign bought. Design space: A. no change (grounding exists in index.md twice, in Ch4, and in cell 9) | B. +2 words in cell 1, "action definitions" | C. one bridge sentence before cell 8 naming `ApplyHeat` as Chapter 4's action def the containment diagram does not draw | D. restore an excerpt print (disfavored -- reopens a verified residual). Candidate B: no model/diagram/teaching change; cell 1's sentence is already 21 words against the style guide's 20-word default ceiling and becomes 23; needs a narrow new contract since the Parsimony heuristic bars touching this cell without Z's say. MoE: the learner no longer reports `ApplyHeat` ungrounded. MoP: a re-run SE Practitioner spot-check passes; the diff touches exactly one sentence. ACE recommendation: B. If Z would rather hold the redesign's line, A costs nothing further. Z's decision: C, revised. Z caught that the ACE's/orchestrator's draft wording of option C ("a containment diagram doesn't draw actions") risked being read as "diagrams don't show actions" -- false in this tutorial, which has action-flow diagrams elsewhere (`figures/ch04-toastbread-flow.svg`, `figures/ch06-applyheat-flow.svg`, both confirmed by grep to contain a real `ApplyHeat` `«action def»`/`«action»` node). Z asked whether the fix should instead reference an existing action-flow diagram rather than state a generic negative, and whether one needed to be built. Checked: one already exists and is reachable without a forward reference -- `figures/ch04-toastbread-flow.svg`, built in Chapter 4, which the reader has already completed by Ch5 (Chapter 6's own `figures/ch06-applyheat-flow.svg` would be a forward reference to content not yet reached, so it was not used). Final wording, inserted as its own new markdown cell between the existing cell 7 and cell 8 of `chapters/ch05-architecture/01-model-navigation.ipynb`: "`ApplyHeat` was already drawn in Chapter 4's own action-flow diagram, nested inside `ToastBread`; the containment diagram above shows parts, not actions." Dispatched via a new narrow contract (`phase-b/ch05-applyheat-bridge`), same harness (builder sonnet, reviewer opus). Z's rationale: a bridge sentence that only states what this diagram can't show, without pointing at one that can, teaches an overgeneralization by omission; since this tutorial already has the right diagram built two chapters earlier, referencing it is free and more precise than either patching cell 1's enumeration (option B) or stating a bare negative (the original draft of C). + Fix merged: commit `2a8b003` on `phase-b/ch05-applyheat-bridge`, independently reviewed (PASS, including an independent re-verification that `figures/ch04-toastbread-flow.svg` really draws `ApplyHeat` and that `figures/ch06-applyheat-flow.svg` was correctly NOT used, since it would have been a forward reference), merged as `b0b3d9b`. MoP satisfied: a re-run SE Practitioner spot-check on the merged notebook reports PASS -- the new cell "removes the one spot where a result... referenced something the notebook itself hadn't grounded." ## DL-096 | 2026-10-02 | DIAGRAM-TEXT-INTEGRATION-PHASE-B | Correction to DL-095: 2 of Ch3's "printed above" cells ARE genuinely stale (describe an assembled block the removed print alone produced); fixed via a small follow-up contract, no cross-chapter sweep needed From 4bad909c6b08fdb35966a8b253c2049df7152c7c Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 13:27:20 -0400 Subject: [PATCH 24/25] DL-097: ACE architectural diagnosis of Ch9/Ch10 retrieve-vs-define gap (analysis only, no implementation) --- decisions/log.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/decisions/log.md b/decisions/log.md index 24e5ea1..d124938 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1384,3 +1384,16 @@ Post-edit check: `.claude/skills/toaster-review-protocol/SKILL.md` lines 109-112 Extension: yes, per the ACE's own flag -- applying Z's Decision 1 (scoped, at the time it was written, to "the 13 construction notebooks" under the pre-DL-084 count) to the judgment-record tag increments DL-084 later registered as real construction cells is a case Z's own scope statement did not name. This is the flag the spec's own "scope outside the named patterns is flagged for Z, not folded in silently" rule calls for -- and the `skill-editor` gate below is where that flag actually reaches Z, not a separate escalation. Provenance: DL-084 (design, registry change, `toaster-recipe`/`toaster-review-protocol` updates, known-gaps item 2); DL-075 (closed by DL-084); DL-033 (confirmed extension: judgment records are analysis); `.claude/skills/toaster-review-protocol/SKILL.md` 95-152; `.claude/skills/toaster-recipe/SKILL.md` 102, 130-136, 167-175, 189; `.claude/skills/tutorial-style-guide/SKILL.md` 100-101; `scripts/check_construction.py` registry lines 94, 125, 159, 235, 289, 326; `chapters/ch02-requirements/03-judgment-context.ipynb` cells 8-13; `chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb` cells 11-16; `decisions/diagram-text-integration-survey.md` cross-chapter open questions 2, 5, 6, 7; `decisions/declarative-construction-plan.md` 52-60; `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decision 1, "Rolling cleanup" closing paragraph, Non-goals; ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. + +## DL-097 | 2026-10-02 | CH9-CH10-GAP-ANALYSIS | Z's "string writing that should be retrieved" in Ch9/Ch10: not a missing SysML construct; SA-1's JSON half never built, DL-084's registry never queried, plus plain P3 defects; one question escalated + +Path: Handled by ACE (diagnosis) / Escalated to Z (where argument structure lives; meaning of SA-1's "JSON") +Decision: (1) A ReviewRecord's content is legitimately Python-side (F4, DL-033); no SysML construct is missing and opensysml is not the blocker. (2) SA-1 names "dataclass + JSON"; no record is serialized anywhere in the repo, so Ch9-02/03 and Ch10-02 re-declare AS-C06/AS-C08 verbatim and Ch10-03 hand-types ledger/AC-C10 summaries. (3) Ch9-02 cell 1 and Ch10-02 cell 1's "no central registry" claim is stale since DL-084: the cumulative model carries 9 ReviewRecordRef tags (probed) and get_review_record_refs is never used as a registry query; AI-C06/AI-C10 premise identifiers are never checked against it. (4) Ch10-01 cell 17 and Ch10-03 cells 10/12/19 hand-type facts the same notebook just queried (P3 defect, fixable with existing helpers). (5) Ch10-01 cell 8 scrapes sysx:sourceText for a requirement's subject; the API export lacks subjectParameter on RequirementDefinition (probed); untracked in DEFERRED.md (P5). (6) Sufficiency readings, why-stale readings and AI-C10's judgment fields are inherent judgment and stay (P1). The fix principle for the deferred PR: facts retrieved (model anchors via get_review_record_refs; record content via the SA-1 JSON form; traceability rows via existing query helpers), judgment written. +Principles applied: F4; P1; P3; P4; P5; P6; heuristics 4, 6; DL-033 and DL-084 applied as prior decisions; SA-1 and SA-7 as binding. +Reasoning: F4 test (is the relation defined in the model or only in code?) applied field by field: identifier and subject are in the model (DL-084); prose fields are judgment about the model, so placing them in the model would have the model assert its own verdict (F1 analog at the judgment level) and would reopen SA-1, which only Z does. P3 test applied to Ch10-01 cell 17 and Ch10-03 cell 19: both claims are regenerable from queries already run in the same notebook, so hand-typing them is the defect, not a gap. P5 applied to the sourceText scrape (gap must be tracked with a DEFERRED entry and comment cell). P1 applied to the judgment prose: not retrievable, legitimately written. Heuristic 6 applied to the triple re-declaration of AS-C06/AS-C08 (Ch6 original, Ch9-02, Ch9-03, Ch10-02): removing it (loading instead) makes the learner's task easier, so the re-declaration does not earn its place. +Determined: yes for (1)-(6). Underdetermined at one step: whether the premise relation among records (Hawkins' asserted inference as a relation) belongs in the model as metadata or in the JSON store; F4 and DL-033 favor the store but Z has not applied them to argument structure, and SA-1's "JSON" is not elaborated in any surviving text. +Extension: yes -- F4/DL-033 extended from a single record to cross-record synthesis (Ch9/Ch10), and P3 extended from figures to hand-typed traceability rows. +Provenance: AGENTS.md 1.1 (items 6-7), 1.4, 1.6, 1.7, 1.9; z-model Z-9, Z-22, Z-24; z-principles F4, P1, P3, P5, confirmed extensions DL-033, DL-084; DL-093; `src/toaster/evidence.py` (ReviewRecord, validate_record, check_stale; no serialization); `src/toaster/query.py` (get_review_record_refs, requirement_coverage, requirement_ties, allocations_for, supertypes_transitively, perform_relationships); `.claude/skills/toaster-review-protocol/SKILL.md` 22-54, 95-153; `.claude/skills/opensysml-query/SKILL.md` 10-18, 165-177; `.claude/skills/ace-protocol/SKILL.md` 58 (SA-1); glossary term-traceability, term-judgment, term-assurance-claim-point, term-asserted-inference; `chapters/ch09-coverage-sufficiency/index.md`; `chapters/ch10-traceability-signoff/index.md`; live probe 2026-10-02 (ch08-cumulative: 8 tags; ch10-cumulative: 9 tags; RequirementDefinition export keys lack subjectParameter; Documentation bodies present for TimelyToast, HeatGenerationReq, EnergyConservationReq); repo-wide search: no record JSON anywhere in the repo; `DEFERRED.md` has no sourceText/subjectParameter entry; a parallel simulated-learner report on Ch9 (agentId `ab96e277eb9b761ff`) independently converged on the same AS-C06/AS-C08 re-declaration finding, cataloguing it at the notebook/cell level. + Brief: DECISION NEEDED: where does the Hawkins argument structure (which record is a premise of which) live? A. JSON store only (SA-1), model carries anchors only. B. Extend ReviewRecordRef with kind and premise references (unprobed; touches SA-1). ACE recommendation: A. Also: confirm whether SA-1's "JSON" meant a persisted store. + Z's decision: [pending] + Z's rationale: [pending] From f847addca0011446868371e8503bf45d2d1624c3 Mon Sep 17 00:00:00 2001 From: Michael Zargham <mzargham@users.noreply.github.com> Date: Fri, 2 Oct 2026 13:52:49 -0400 Subject: [PATCH 25/25] DL-097: record Z's decision -- build the JSON store, author judgments once where made, query/retrieve in later chapters --- decisions/log.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/decisions/log.md b/decisions/log.md index d124938..31b0141 100644 --- a/decisions/log.md +++ b/decisions/log.md @@ -1385,7 +1385,7 @@ Extension: yes, per the ACE's own flag -- applying Z's Decision 1 (scoped, at th Provenance: DL-084 (design, registry change, `toaster-recipe`/`toaster-review-protocol` updates, known-gaps item 2); DL-075 (closed by DL-084); DL-033 (confirmed extension: judgment records are analysis); `.claude/skills/toaster-review-protocol/SKILL.md` 95-152; `.claude/skills/toaster-recipe/SKILL.md` 102, 130-136, 167-175, 189; `.claude/skills/tutorial-style-guide/SKILL.md` 100-101; `scripts/check_construction.py` registry lines 94, 125, 159, 235, 289, 326; `chapters/ch02-requirements/03-judgment-context.ipynb` cells 8-13; `chapters/ch06-recursive-decomp/03-stopping-judgment.ipynb` cells 11-16; `decisions/diagram-text-integration-survey.md` cross-chapter open questions 2, 5, 6, 7; `decisions/declarative-construction-plan.md` 52-60; `docs/superpowers/specs/2026-10-02-diagram-text-integration-design.md` Decision 1, "Rolling cleanup" closing paragraph, Non-goals; ACE report, agentId `abdd0254803c46fa7`, delivered 2026-10-02. -## DL-097 | 2026-10-02 | CH9-CH10-GAP-ANALYSIS | Z's "string writing that should be retrieved" in Ch9/Ch10: not a missing SysML construct; SA-1's JSON half never built, DL-084's registry never queried, plus plain P3 defects; one question escalated +## DL-097 | 2026-10-02 | CH9-CH10-GAP-ANALYSIS | Z's "string writing that should be retrieved" in Ch9/Ch10: not a missing SysML construct; SA-1's JSON half never built, DL-084's registry never queried, plus plain P3 defects; escalated question resolved by Z -- build the JSON store, author once where the judgment is made, query/retrieve thereafter Path: Handled by ACE (diagnosis) / Escalated to Z (where argument structure lives; meaning of SA-1's "JSON") Decision: (1) A ReviewRecord's content is legitimately Python-side (F4, DL-033); no SysML construct is missing and opensysml is not the blocker. (2) SA-1 names "dataclass + JSON"; no record is serialized anywhere in the repo, so Ch9-02/03 and Ch10-02 re-declare AS-C06/AS-C08 verbatim and Ch10-03 hand-types ledger/AC-C10 summaries. (3) Ch9-02 cell 1 and Ch10-02 cell 1's "no central registry" claim is stale since DL-084: the cumulative model carries 9 ReviewRecordRef tags (probed) and get_review_record_refs is never used as a registry query; AI-C06/AI-C10 premise identifiers are never checked against it. (4) Ch10-01 cell 17 and Ch10-03 cells 10/12/19 hand-type facts the same notebook just queried (P3 defect, fixable with existing helpers). (5) Ch10-01 cell 8 scrapes sysx:sourceText for a requirement's subject; the API export lacks subjectParameter on RequirementDefinition (probed); untracked in DEFERRED.md (P5). (6) Sufficiency readings, why-stale readings and AI-C10's judgment fields are inherent judgment and stay (P1). The fix principle for the deferred PR: facts retrieved (model anchors via get_review_record_refs; record content via the SA-1 JSON form; traceability rows via existing query helpers), judgment written. @@ -1395,5 +1395,5 @@ Determined: yes for (1)-(6). Underdetermined at one step: whether the premise re Extension: yes -- F4/DL-033 extended from a single record to cross-record synthesis (Ch9/Ch10), and P3 extended from figures to hand-typed traceability rows. Provenance: AGENTS.md 1.1 (items 6-7), 1.4, 1.6, 1.7, 1.9; z-model Z-9, Z-22, Z-24; z-principles F4, P1, P3, P5, confirmed extensions DL-033, DL-084; DL-093; `src/toaster/evidence.py` (ReviewRecord, validate_record, check_stale; no serialization); `src/toaster/query.py` (get_review_record_refs, requirement_coverage, requirement_ties, allocations_for, supertypes_transitively, perform_relationships); `.claude/skills/toaster-review-protocol/SKILL.md` 22-54, 95-153; `.claude/skills/opensysml-query/SKILL.md` 10-18, 165-177; `.claude/skills/ace-protocol/SKILL.md` 58 (SA-1); glossary term-traceability, term-judgment, term-assurance-claim-point, term-asserted-inference; `chapters/ch09-coverage-sufficiency/index.md`; `chapters/ch10-traceability-signoff/index.md`; live probe 2026-10-02 (ch08-cumulative: 8 tags; ch10-cumulative: 9 tags; RequirementDefinition export keys lack subjectParameter; Documentation bodies present for TimelyToast, HeatGenerationReq, EnergyConservationReq); repo-wide search: no record JSON anywhere in the repo; `DEFERRED.md` has no sourceText/subjectParameter entry; a parallel simulated-learner report on Ch9 (agentId `ab96e277eb9b761ff`) independently converged on the same AS-C06/AS-C08 re-declaration finding, cataloguing it at the notebook/cell level. Brief: DECISION NEEDED: where does the Hawkins argument structure (which record is a premise of which) live? A. JSON store only (SA-1), model carries anchors only. B. Extend ReviewRecordRef with kind and premise references (unprobed; touches SA-1). ACE recommendation: A. Also: confirm whether SA-1's "JSON" meant a persisted store. - Z's decision: [pending] - Z's rationale: [pending] + Z's decision: A, confirmed, with two binding refinements for the deferred PR's own design. (1) SA-1's "JSON" means a real persisted store in the repo, not just the dataclass -- confirmed. The argument structure (which record is a premise of which) lives in that store, not as model-side metadata, per the ACE's own recommendation. (2) A judgment's own prose (claim, rationale, counterevidence, residual uncertainties) is authored exactly once, in the notebook/chapter where that judgment was actually made -- never retyped or restated in full in a later chapter. Later chapters that need an earlier judgment treat the stored record as a previously-rendered human judgment and query/retrieve it for review, the same way they already query the model for structural facts -- they do not re-author it. (3) Not every chapter can inline a full judgment's own prose without bloating that chapter's own narrative (Ch9/Ch10's real problem is exactly this, done by hand, three times, for AS-C06/AS-C08) -- the JSON store exists specifically so a later chapter's own review can cite/summarize/query a record it did not write, instead of reconstructing it as a fresh Python literal. + Z's rationale: retyping a judgment is not just redundant, it's a silent-drift risk (three independently hand-typed copies of the same record can diverge from each other and from the original with nothing to catch it) -- the same class of problem DL-092/DL-093 already fixed for model-fragment reflection prints, now recurring one layer up, at the judgment-record layer. Authoring once and querying thereafter is the same principle (construct once, analyze/retrieve afterward) this tutorial already applies everywhere else; judgment records were simply never given the storage half of that loop.