Bring example catalog to quality target

Author: adewale

docs/lessons-learned.md

@@ -115,5 +115,5 @@ git diff --check
 - **Quality debt must be tracked, not normalized away.** `docs/example-quality-rubric.md` sets a 9.0 target and `scripts/check_quality_scores.py` enforces the score registry: pages below the hard minimum need a concrete improvement backlog entry, stale backlog entries fail once a page clears the gate, and Hello World is the only standing waiver because first examples are traditionally tiny. A score below target is allowed only when the remaining work is named.
 - **No-figure decisions need a registry.** Some examples should not have figures, but that cannot be an invisible omission. `scripts/check_no_figure_rationales.py` validates `no_figure_rationales` so future constraint-shaped pages can opt out explicitly instead of shipping weak diagrams.
 - **Journey sections need outcome contracts.** `scripts/check_journey_outcomes.py` ties each journey section to learner outcomes and support examples so journey pages stay mental maps rather than catalog slices.
-- **Opaque scores hide the next move.** `scripts/score_example_criteria.py` breaks each page into rubric criteria so quality work can target decomposition, boundaries, source/result pairing, graph support, or practical payoff directly. `docs/quality-search.md` records the hill-climbing and simulated-annealing loop for escaping locally tidy but globally weak page shapes.
+- **Opaque scores hide the next move.** `scripts/score_example_criteria.py` breaks each page into rubric criteria so quality work can target decomposition, boundaries, source/result pairing, graph support, or practical payoff directly. The bottom-28 pass showed that most misses were boundary/neighbor problems, not syntax problems. `docs/quality-search.md` records the hill-climbing and simulated-annealing loop for escaping locally tidy but globally weak page shapes.
 - **Deployment smoke belongs beside CI.** `scripts/smoke_deployment.py` checks rendered Worker pages, runtime-boundary pages, journey pages, prototype review pages, and representative Dynamic Worker POST runs for HTTP failures, exception markers, and stale edited-code output. Build success is not enough; the deployed Worker must render and execute edited examples.

docs/quality-registries.toml

@@ -196,114 +196,6 @@ expires = "never"
 # figure would distort the lesson. Current production attaches figures
 # to every example, so this registry is intentionally empty.
 
-[quality_improvement_backlog.values]
-cause = "foundational page is graph-linked now but still needs a sharper object/type mental model"
-next_action = "add or revise a cell that connects value, type, and operation with a nearby See also path"
-
-[quality_improvement_backlog.booleans]
-cause = "boolean operators are covered but the boundary with truthiness and numeric bool is not prominent enough"
-next_action = "add a contrast cell for bool values, truthy objects, and bool-as-int footgun"
-
-[quality_improvement_backlog.none]
-cause = "absence is shown but not contrasted strongly enough with exceptions and missing mapping keys"
-next_action = "add a boundary cell comparing None, KeyError, and an explicit default"
-
-[quality_improvement_backlog.variables]
-cause = "binding model is shown but rebinding vs mutation is not reinforced enough"
-next_action = "add a rebinding cell and link it directly to mutability/object lifecycle"
-
-[quality_improvement_backlog.equality-and-identity]
-cause = "near the gate but needs a stronger practical warning about using is outside singletons"
-next_action = "add a decision cell for ==, is None, and identity-cache surprises"
-
-[quality_improvement_backlog.mutability]
-cause = "mutation vs rebinding is central enough to deserve a sharper copy/alias boundary"
-next_action = "add a cell that contrasts in-place list mutation with rebinding to a new object"
-
-[quality_improvement_backlog.strings]
-cause = "Unicode coverage is present but graph and boundary framing were previously isolated"
-next_action = "connect string immutability, formatting, and bytes with adjacent cells or links"
-
-[quality_improvement_backlog.string-formatting]
-cause = "f-string page needs clearer format-spec and boundary-to-repr coverage"
-next_action = "add a format-spec cell and a note/cell explaining when repr/debug formatting is better"
-
-[quality_improvement_backlog.conditionals]
-cause = "branching syntax is shown but predicate/truthiness model is under-emphasized"
-next_action = "add a cell that chooses a branch from a non-bool value and points to truthiness"
-
-[quality_improvement_backlog.match-statements]
-cause = "match syntax is shown but shape-dispatch vs if/elif boundary could be clearer"
-next_action = "add a comparable if/elif or data-shape cell that makes match's payoff visible"
-
-[quality_improvement_backlog.lists]
-cause = "list operations are shown but sequence vs set/dict and mutation boundaries need sharpening"
-next_action = "add a cell contrasting append/index order with set membership or tuple immutability"
-
-[quality_improvement_backlog.unpacking]
-cause = "unpacking forms are shown but sequence vs mapping and star-target boundaries need clearer outputs"
-next_action = "add a mapping-unpacking or too-many-values boundary cell"
-
-[quality_improvement_backlog.dicts]
-cause = "dictionary page is close but needs stronger mutation-during-iteration and default lookup framing"
-next_action = "add or sharpen cells for get/default, key membership, and safe deletion while iterating"
-
-[quality_improvement_backlog.sets]
-cause = "set uniqueness is shown but list-vs-set tradeoff and ordering boundary need emphasis"
-next_action = "add a cell comparing membership/duplicates with a list"
-
-[quality_improvement_backlog.comprehensions]
-cause = "map/filter shape is shown but eager vs lazy and loop equivalence need stronger progression"
-next_action = "add a generator-expression contrast or explicit loop-equivalence cell"
-
-[quality_improvement_backlog.sorting]
-cause = "key functions are shown but stable sort and sorted-vs-list.sort boundary need coverage"
-next_action = "add a cell demonstrating stability or in-place list.sort vs sorted()"
-
-[quality_improvement_backlog.functions]
-cause = "function definition is broad and close to gate but should foreground call/return and default footgun"
-next_action = "add a focused call-frame or mutable-default contrast cell"
-
-[quality_improvement_backlog.keyword-only-arguments]
-cause = "separator syntax is shown but API readability/stability rationale is thin"
-next_action = "add a call-site contrast where unnamed booleans are ambiguous"
-
-[quality_improvement_backlog.args-and-kwargs]
-cause = "collection of extra arguments is shown but forwarding boundary is underdeveloped"
-next_action = "add a wrapper cell that forwards *args and **kwargs to another callable"
-
-[quality_improvement_backlog.closures]
-cause = "closure memory is shown but late-binding footgun deserves more adjacent evidence"
-next_action = "add or sharpen loop-closure broken/fixed cells"
-
-[quality_improvement_backlog.lambdas]
-cause = "lambda syntax is shown but def-vs-lambda boundary is too light"
-next_action = "add a cell where lambda is useful as an argument and def is clearer for reuse"
-
-[quality_improvement_backlog.generator-expressions]
-cause = "lazy expression is shown but one-pass consumption and list-comprehension contrast need sharpening"
-next_action = "add a cell comparing list comprehension storage with generator expression streaming"
-
-[quality_improvement_backlog.itertools]
-cause = "lazy composition is shown but practical pipeline payoff could be clearer"
-next_action = "add a small pipeline with take/filter/map output proving values are pulled on demand"
-
-[quality_improvement_backlog.properties]
-cause = "property syntax is shown but method-vs-attribute API boundary needs stronger rationale"
-next_action = "add a before/after cell changing a public attribute into a property without caller changes"
-
-[quality_improvement_backlog.exceptions]
-cause = "try/except structure is shown but bare-except and cleanup boundaries need sharper evidence"
-next_action = "add a cell contrasting specific exception handling with overbroad catching"
-
-[quality_improvement_backlog.custom-exceptions]
-cause = "custom exception class is shown but when not to create one is underdeveloped"
-next_action = "add a boundary cell contrasting domain error with built-in ValueError"
-
-[quality_improvement_backlog.datetime]
-cause = "date/time operations are shown but timezone and naive-aware boundaries need more clarity"
-next_action = "add a timezone-aware datetime cell or explicitly scope the page to naive values"
-
 [journey_outcomes]
 
 [journey_outcomes."runtime::Start with executable evidence."]

docs/quality-search.md

@@ -40,6 +40,16 @@ Greedy hill-climbing tends to overfit the current page shape: it adds one more n
 
 This gives the project permission to try non-local changes — different domains, different cell order, or a no-figure rationale — without normalizing failed experiments into production.
 
+## Techniques learned from the bottom-28 pass
+
+The low-score pages mostly needed the same repair pattern rather than more prose:
+
+- **Name the boundary in the page graph.** Pages that were otherwise good still looked weak when they had no prerequisite/neighbor/next-depth `see_also` edges. Adding edges made the intended learning path inspectable.
+- **Use a three-cell spine.** Strong pages usually have setup, contrast/boundary, and payoff evidence. One compressed cell hides too many teaching jobs.
+- **Show the neighboring tool.** `for` vs `while`, `lambda` vs `def`, `list` vs `set`, `None` vs exception/default, and eager vs lazy examples score better because learners see when not to use the feature.
+- **Keep runtime/static distinctions explicit.** Typing pages improved when a cell showed the runtime caveat instead of leaving the type-checker promise implicit.
+- **Let criterion scoring detect stale editorial labels.** Several pages had already gained cells, notes, and graph edges, but the curated comment still said `isolated`. The criterion report is useful for finding those stale labels.
+
 ## Wider-system unlocks
 
 Future improvements that create new quality headroom:

scripts/check_quality_scores.py

@@ -81,15 +81,17 @@ def main() -> int:
     for slug, (score, _comment) in sorted(EXAMPLE_QUALITY_SCORES.items()):
         if score < target:
             below_target.append(slug)
-        if score < hard_min:
             if slug in waivers:
                 accepted = float(waivers[slug].get("accepted_min", hard_min))
                 if score < accepted:
                     errors.append(f"{slug}: score {score:.1f} below waiver floor {accepted:.1f}")
-            elif slug in backlog:
-                below_hard_min.append(slug)
+            elif score < hard_min:
+                if slug in backlog:
+                    below_hard_min.append(slug)
+                else:
+                    errors.append(f"{slug}: score {score:.1f} below hard minimum {hard_min:.1f} without backlog entry")
             else:
-                errors.append(f"{slug}: score {score:.1f} below hard minimum {hard_min:.1f} without backlog entry")
+                errors.append(f"{slug}: score {score:.1f} below target {target:.1f} without waiver")
 
     for title in sorted(section_backlog):
         if title not in SECTION_FIGURE_SCORES:

src/asset_manifest.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
 ASSET_PATHS = {'SITE_CSS': '/site.57a55415849b.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.a4a7766e1b9b.js'}
-HTML_CACHE_VERSION = 'b5738224e50a'
+HTML_CACHE_VERSION = '2e6da1f2a673'

src/example_sources/args-and-kwargs.md

@@ -4,6 +4,12 @@ title = "Args and Kwargs"
 section = "Functions"
 summary = "*args collects extra positional arguments and **kwargs collects named ones."
 doc_path = "/tutorial/controlflow.html#arbitrary-argument-lists"
+see_also = [
+  "functions",
+  "keyword-only-arguments",
+  "partial-functions",
+  "paramspec",
+]
 +++
 
 `*args` and `**kwargs` let a function accept flexible positional and keyword arguments. They are the function-definition counterpart to unpacking at a call site.

src/example_sources/closures.md

@@ -4,6 +4,12 @@ title = "Closures"
 section = "Functions"
 summary = "Inner functions can remember values from an enclosing scope."
 doc_path = "/reference/executionmodel.html#binding-of-names"
+see_also = [
+  "functions",
+  "lambdas",
+  "decorators",
+  "partial-functions",
+]
 +++
 
 A closure is a function that remembers names from the scope where it was created. This lets you configure behavior once and call it later.

src/example_sources/comprehensions.md

@@ -4,6 +4,12 @@ title = "Comprehensions"
 section = "Collections"
 summary = "Comprehensions build collections by mapping and filtering iterables."
 doc_path = "/tutorial/datastructures.html#list-comprehensions"
+see_also = [
+  "for-loops",
+  "generator-expressions",
+  "comprehension-patterns",
+  "lists",
+]
 +++
 
 Comprehensions are expression forms for building concrete collections from iterables. Read them from left to right: produce this value, for each item, optionally only when a condition is true.

src/example_sources/conditionals.md

@@ -4,6 +4,12 @@ title = "Conditionals"
 section = "Control Flow"
 summary = "if, elif, and else choose which block runs."
 doc_path = "/tutorial/controlflow.html#if-statements"
+see_also = [
+  "booleans",
+  "truthiness",
+  "guard-clauses",
+  "match-statements",
+]
 +++
 
 `if`, `elif`, and `else` let a program choose one path based on a condition. Python uses indentation to show which statements belong to each branch.

src/example_sources/custom-exceptions.md

@@ -4,6 +4,12 @@ title = "Custom Exceptions"
 section = "Errors"
 summary = "Custom exception classes name failures that belong to your domain."
 doc_path = "/tutorial/errors.html#user-defined-exceptions"
+see_also = [
+  "exceptions",
+  "exception-chaining",
+  "warnings",
+  "logging",
+]
 +++
 
 Custom exceptions give names to failures in your problem domain. A named exception is easier to catch and explain than a generic error with only a string message.