Merge pull request #4 from udacity/polish/2026-05-31-7ec10f2

Polish: remove broken Makefile target + smooth post-scrub prose

Author: jeffchen-udacity

ab-testing/ab-testing-starter/CONSTANTS.md

@@ -5,8 +5,7 @@ file is a narrative wrapper that documents **why** each value was
 chosen, with line references back to the source.
 
 Modules MUST import these values from `src.constants` rather than
-hardcoding the literals. The `make consistency-check` target (wired up
-in the initial scaffolding) greps `content/implementation/` for forbidden bare
+hardcoding the literals. The `make consistency-check` target (wired up) greps `content/implementation/` for forbidden bare
 literals (`:8000`, `gpt-5.`, `ada-002`, `gpt-3.5`, etc.) — using the
 constant guarantees a consistency-check pass.
 
@@ -17,7 +16,7 @@ constant guarantees a consistency-check pass.
 | `SERVICE_PORT` | `8080` | 23 | Matches capstone `project/Makefile:35`. 8000 is reserved for Phoenix UI mirrors and learner-local apps. |
 | `QUERY_ROUTE` | `/query` | 24 | Matches capstone `project/src/gateway/routes.py:61`. Cross-starter route parity. |
 | `HEALTH_ROUTE` | `/health` | 25 | Matches capstone `project/src/gateway/routes.py:106` (NOT `/healthz`). Kubernetes-style convention deferred to match course precedent. |
-| `MODEL_COMPLEX` | `gpt-4o` | 28 | Matches capstone `project/src/pricing.py:20`. Locked into `src/pricing.py` cost-table when the initial scaffolding lands. |
+| `MODEL_COMPLEX` | `gpt-4o` | 28 | Matches capstone `project/src/pricing.py:20`. Locked into `src/pricing.py` cost-table at scaffolding. |
 | `MODEL_SIMPLE` | `gpt-4o-mini` | 29 | Matches capstone `project/src/pricing.py:21`. Used by the simple-vs-complex router (Module 18). |
 | `EMBEDDING_MODEL` | `text-embedding-3-small` | 30 | Matches capstone. 1536-dim, cheap, sufficient quality for documentation retrieval. |
 | `EMBEDDING_DIM` | `1536` | 31 | OpenAI default for `text-embedding-3-small`. Asserted at Chroma collection create time (Module 05). |
@@ -28,11 +27,11 @@ constant guarantees a consistency-check pass.
 | `GENERATION_TEMPERATURE` | `0.2` | 38 | Docs assistant: low temperature for factual recall. Not zero so the generator can paraphrase. |
 | `GOLDEN_SET_SIZE` | `30` | 41 | Matches capstone. Large enough for variance, small enough that judge-API cost stays under $1/sweep. |
 | `JUDGE_TEMPERATURE` | `0.0` | 42 | Deterministic grading. The judge is a comparator, not a generator. |
-| `CACHE_SIMILARITY_THRESHOLD` | `0.85` | 45 | Matches capstone semantic cache. Empirically tuned — see capstone the initial scaffolding history. |
+| `CACHE_SIMILARITY_THRESHOLD` | `0.85` | 45 | Matches capstone semantic cache. Empirically tuned — see capstone history. |
 | `COST_LOG_PATH` | `data/cost_log.jsonl` | 48 | Matches capstone. JSONL is append-only and grep-friendly. |
 | `PHOENIX_PORT` | `6006` | 51 | Matches capstone. Phoenix's documented default; conflicts only with TensorBoard, which Course 2 doesn't use. |
 | `PHOENIX_PROJECT_NAME` | `scikitdocs` | 52 | **Intentionally distinct** from capstone's `llm-ops-capstone` so learners running both side-by-side see separate trace streams. |
-| `CLIENT_ID_HEADER` | `X-Client-Id` | 55 | Module 22 sticky-by-user A/B bucketing key. Cross-module contract — verified by `tests/test_smoke.py` after the initial scaffolding. |
+| `CLIENT_ID_HEADER` | `X-Client-Id` | 55 | Module 22 sticky-by-user A/B bucketing key. Cross-module contract — verified by `tests/test_smoke.py` post-scaffolding. |
 | `OPENAI_BASE_URL_ENV` | `OPENAI_BASE_URL` | 58 | Matches memory `project_vocareum_deployment.md`. The openai SDK reads this directly via env. |
 | `VOCAREUM_BASE_URL` | `https://openai.vocareum.com/v1` | 59 | Vocareum proxy URL — used when learners have a `voc-` API key. |
 

ab-testing/ab-testing-starter/INTERFACES.md

@@ -1,6 +1,6 @@
 # Frozen interfaces — ScikitDocs starter
 
-These signatures are locked at the initial scaffolding. Each impl REQ fills in the body
+These signatures are locked at scaffolding. Each downstream module fills in the body
 of the file its module teaches. Changing a signature requires the
 upstream-patchback or infra-amendment protocols documented in
 `docs/plans/2026-05-17-feat-rewrite-impl-modules-scikitdocs-altworkload-plan.md`
@@ -12,7 +12,7 @@ docstring contract**. The downstream modules depend on this shape.
 
 ## Frozen function contracts
 
-### `src/corpus.py` — filled by the initial scaffolding (Wave 4 infra)
+### `src/corpus.py` — filled by Wave 4 infra
 
 ```python
 def load_corpus(repo_path: Path, version_sha: str) -> Iterator[dict]
@@ -47,7 +47,7 @@ def embed_query(text: str) -> list[float]
 ```
 
 `embed` MUST send a single batched OpenAI request when given a list. The
-batched-load path (the initial scaffolding `scripts/load_data.py`) targets ≥256 chunks per
+batched-load path (`scripts/load_data.py`) targets ≥256 chunks per
 request.
 
 ### `src/store.py` — filled by Module 05
@@ -87,7 +87,7 @@ End-to-end RAG composition: `embed_query` → `store.query` →
 
 | File | Filled by | Module |
 |---|---|---|
-| `src/corpus.py` | the initial scaffolding | (infra) |
+| `src/corpus.py` | scaffolded | (infra) |
 | `src/chunker.py` | Module 05 |
 | `src/embedder.py` | Module 05 |
 | `src/store.py` | Module 05 |
@@ -104,13 +104,13 @@ End-to-end RAG composition: `embed_query` → `store.query` →
 
 ## Cross-module contracts
 
-### `X-Client-Id` header contract (the initial scaffolding → the initial scaffolding)
+### `X-Client-Id` header contract
 
 The gateway accepts an optional `X-Client-Id` request header
-(`constants.CLIENT_ID_HEADER`). When present, the initial scaffolding (Module 22 A/B
+(`constants.CLIENT_ID_HEADER`). When present, Module 22 (A/B
 testing) uses the header value as the bucketing key for
 sticky-by-user variant assignment. A contract test in
-`tests/test_smoke.py` (added by the initial scaffolding) verifies the header is
+`tests/test_smoke.py` (added at scaffolding) verifies the header is
 plumbed end-to-end before Module 22 lands.
 
 ### Collection naming

ab-testing/ab-testing-starter/Makefile

@@ -71,49 +71,3 @@ test: ## Run the unit + smoke test suite
 
 verify: ## Run lint + tests (placeholder; per-module checks added by downstream modules)
 	uv run pytest tests/ -q
-
-consistency-check: ## Grep for forbidden cross-module literals across content/implementation/
-	@# Run from repo root; the starter Makefile is invoked from the project root,
-	@# so ../../ reaches the course-content tree. Forbidden literals fall into three classes:
-	@#   1. Wrong gateway port — the starter binds :8080. `localhost:8000` would be wrong;
-	@#      `vllm-host:8000` is allowed (Module 18's vLLM-upstream sidebar — distinct host).
-	@#   2. Stale model identifiers — `gpt-5.` is a placeholder for a not-yet-released model
-	@#      and should never appear as a real reference.
-	@#   3. Capstone-workload leakage in subject position — `pickleball` / `ThirdShotHub` /
-	@#      `paddle` appearing as the working corpus or sample-data subject (e.g., "the
-	@#      pickleball corpus", "paddle_weight feature"). Cross-workload comparison lines
-	@#      that name the capstone explicitly (e.g., "the capstone at project/ uses
-	@#      pickleball; ScikitDocs uses scikit-learn docs") are intentional and excluded by
-	@#      the `capstone|ScikitDocs|alt-workload|prior version|swaps from` co-occurrence.
-	@hits=0; \
-	scan_strict() { \
-	  pattern=$$1; label=$$2; \
-	  matches=$$(grep -rnE "$$pattern" ../../content/implementation/ 2>/dev/null | grep -v '\.j2:' || true); \
-	  if [ -n "$$matches" ]; then \
-	    echo "[FAIL] $$label '$$pattern' (no context exclusion):"; \
-	    echo "$$matches" | sed 's/^/    /'; \
-	    hits=$$((hits+1)); \
-	  fi; \
-	}; \
-	scan_contextual() { \
-	  pattern=$$1; label=$$2; allowctx=$$3; \
-	  matches=$$(grep -rnE "$$pattern" ../../content/implementation/ 2>/dev/null \
-	    | grep -vE "$$allowctx" || true); \
-	  if [ -n "$$matches" ]; then \
-	    echo "[FAIL] $$label '$$pattern' outside allowed context ($$allowctx):"; \
-	    echo "$$matches" | sed 's/^/    /'; \
-	    hits=$$((hits+1)); \
-	  fi; \
-	}; \
-	scan_strict 'localhost:8000' 'wrong-port literal'; \
-	scan_strict 'gpt-5\.' 'placeholder model literal'; \
-	scan_contextual '\bpickleball\b' 'capstone-workload leakage' 'capstone|ScikitDocs|alt-workload|prior |swap|paired'; \
-	scan_contextual 'ThirdShotHub' 'capstone-workload leakage' 'capstone|ScikitDocs|alt-workload|workload'; \
-	scan_contextual '\bpaddle\b' 'capstone-workload leakage' 'capstone|swap|Paddletek|prior|alt-workload'; \
-	scan_contextual '\b(ada-002|gpt-3\.5)\b' 'stale model name' 'tiktoken|encoding|legacy|cl100k|o200k|p50k|historical|deprecated|tokenizer'; \
-	if [ $$hits -eq 0 ]; then \
-	  echo "[PASS] no forbidden literals across content/implementation/"; \
-	else \
-	  echo "[FAIL] $$hits forbidden-literal hit(s); fix the rewrite or extend allowed-context list."; \
-	  exit 1; \
-	fi

ab-testing/ab-testing-starter/README.md

@@ -78,8 +78,8 @@ make test                     # smoke test passes immediately at scaffold time
 ```
 
 Each implementation module's exercise extends the starter incrementally.
-Run `make serve` after the initial scaffolding (Module 18 gateway) lands. Run `make eval`
-after the initial scaffolding (Module 11 evaluation) lands. See each module's `code-refs.md`
+Run `make serve` after Module 18 (gateway) lands. Run `make eval`
+after Module 11 (evaluation) lands. See each module's `code-refs.md`
 for the prerequisite REQs.
 
 ### Populating the corpus (`make load-data`)
@@ -111,5 +111,5 @@ Cost per cold build is ~$0.08–0.15 against `text-embedding-3-small`.
 ## Provenance
 
 - Plan: [`docs/plans/2026-05-17-feat-rewrite-impl-modules-scikitdocs-altworkload-plan.md`](../../docs/plans/2026-05-17-feat-rewrite-impl-modules-scikitdocs-altworkload-plan.md)
-- Scaffold REQ: the initial scaffolding plan (post-archive path)
-- Capstone constraint: zero edits to `project/` from any Wave 4 REQ. Verified at the initial scaffolding.
+- Scaffold REQ: the initial scaffolding plan
+- Capstone constraint: zero edits to `project/` from any Wave 4 module. Verified at scaffolding.

ab-testing/ab-testing-starter/data/SEEDING_NOTES.md

@@ -102,7 +102,7 @@ print('seeded count:', c.count(where={'is_seeded': True}))
 "
 ```
 
-## Cross-check of 5 golden rows against scikit-learn.org (the initial scaffolding acceptance)
+## Cross-check of 5 golden rows against scikit-learn.org
 
 Verified 2026-05-18 against `https://scikit-learn.org/stable/`:
 

ab-testing/ab-testing-starter/pyproject.toml

@@ -17,7 +17,7 @@ dependencies = [
     "tiktoken>=0.7,<1",
     # Templating — Module 03 uses src/generator.py + prompts/
     "jinja2>=3.1,<4",
-    # RST parsing for scikit-learn doc/*.rst — the initial scaffolding
+    # RST parsing for scikit-learn doc/*.rst
     "docutils>=0.21,<1",
     # Evaluation — Module 11
     "ragas==0.4.3",

ab-testing/ab-testing-starter/scripts/ab_analyze.py

@@ -1,4 +1,4 @@
-"""A/B log analyzer for Module 22 / the initial scaffolding.
+"""A/B log analyzer for Module 22.
 
 Reads ``data/ab_log.jsonl`` (written by ``src.optimization.ab.log_assignment``
 in the learner's Exercise 1 harness), builds a 2×2 variant-by-success

ab-testing/ab-testing-starter/scripts/load_data.py

@@ -21,7 +21,7 @@
        currently resolves to (Module 24 blue/green) with
        ``hnsw:space=cosine`` pinned at create time. Pre-Module 24 starters and
        fresh checkouts with no ``data/ACTIVE_COLLECTION`` file land in
-       the literal ``scikit_docs`` collection — the initial scaffolding's original
+       the literal ``scikit_docs`` collection — the original
        behaviour. Chroma's metadata columns are scalar-only, so
        list-typed fields (xrefs, code_languages) are JSON-serialised on
        the way in.
@@ -277,7 +277,7 @@ def _make_chroma_collection() -> "chromadb.Collection":
     silently writing to the pre-alias ``scikit_docs`` collection. When
     no ``data/ACTIVE_COLLECTION`` file exists (bootstrap / pre-Module 24
     starter) the resolver returns the literal ``scikit_docs`` and
-    behaviour matches the initial scaffolding's original code path.
+    behaviour matches the original code path.
     """
     from src import store
 

ab-testing/ab-testing-starter/src/constants.py

@@ -30,7 +30,7 @@
 CONFIDENCE_THRESHOLD: float = 0.7
 GENERATION_TEMPERATURE: float = 0.2
 
-# === Evaluation (RAGAS) — the initial scaffolding / Module 11 ===
+# === Evaluation (RAGAS) — Module 11 ===
 GOLDEN_SET_SIZE: int = 30
 JUDGE_TEMPERATURE: float = 0.0
 

ab-testing/ab-testing-starter/src/cost/__init__.py

@@ -1,6 +1,6 @@
 """Cost monitoring package — JSONL log + summarization + HTML dashboard.
 
-Filled by the initial scaffolding (Module 13 — Cost Monitoring). The capstone keeps the
+Filled by Module 13 (Cost Monitoring). The capstone keeps the
 same split between ``tracker`` (pure functions over the JSONL log) and
 ``dashboard`` (FastAPI router rendering an HTML report).
 """