rsc-universal 0.1.1

package/skills/course-storytelling/references/learner-grounding.md

@@ -0,0 +1,183 @@
+# Learner Grounding — Checklist, Question Script & Persistence
+
+The learner + audience profile is the source of truth every reframing is grounded in. You cannot make teaching *land* for a student you haven't profiled — you'll default to the AI-median explainer: abstract, jargon-true, emotionally dead. This file holds the **completeness checklist** (what "complete" means), the **question script** (how to interview the user, batched), and the **persistence format** (how to write it into `02-DOCS` and link it from `CLAUDE.md`). The runtime hard STOP that invokes this lives in `SKILL.md` under "Learner grounding (read this first)".
+
+## Where the profile lives
+
+Following the `harness` Karpathy-wiki convention:
+
+```text
+02-DOCS/
+├── raw/teaching/        ← immutable: transcripts, outlines, existing slides, pasted verbatim
+│   ├── transcript-module-1.md
+│   ├── outline.md
+│   └── …
+└── wiki/teaching/       ← compiled profile, one article per dimension
+    ├── index.md             ← the transformation one-liner + links to every dimension article
+    ├── learner.md           ← level, prior knowledge, pains, desires, what they want to DO after
+    ├── audience.md          ← buyer vs learner? live vs recorded? size? context?
+    ├── transformation.md    ← the one result; before → after
+    ├── false-beliefs.md     ← current false beliefs, typed vehicle / internal / external
+    └── constraints.md       ← format, length, medium, tone, hard limits
+```
+
+Small projects may collapse this into a single `index.md` with all dimensions as `##` headings — but every dimension must still be present and filled.
+
+## Completeness checklist
+
+The profile is **COMPLETE** only when every dimension is filled with real, specific content. Any empty, placeholder, or "TBD" dimension = **INCOMPLETE** = hard STOP, interview the user.
+
+- [ ] **1. Learner — level & prior knowledge** — who exactly is learning (role, experience), what they already know about this subject, what they definitely don't.
+- [ ] **2. Learner — pains & desires** — in THEIR words: the top 2–3 frustrations/fears around this topic, and the top 2–3 things they actually want.
+- [ ] **3. Learner — current false beliefs** — what they wrongly believe today that blocks the teaching, each typed as **vehicle** ("this approach won't work"), **internal** ("I can't do it"), or **external** ("something outside me will stop it"). (→ `brunson-frameworks.md`)
+- [ ] **4. Learner — the "do" after** — the concrete action/capability they should be able to perform after the lesson/module ("after this they can add an idempotency key to a POST and explain why").
+- [ ] **5. Audience — who's listening** — are the listeners the same as the buyer (decision-maker) or different? Live or recorded? Solo or cohort (size)? In what context do they consume it (commute, classroom, on the job)?
+- [ ] **6. Transformation — the one result** — the single before→after the whole course/module exists to produce, stated as an identity + capability shift, not a topic list.
+- [ ] **7. Constraints & format** — medium (video / live / written / slides), length budget, tone/voice expectations, hard limits (no code? must be language-agnostic? compliance constraints?).
+
+## Question script (ask in batches, never all at once)
+
+Ask **one batch at a time**. Send the batch, wait for the answer, persist what you learned, then send the next batch. Skip questions a located-but-incomplete profile already answers — only fill the gaps. Stop interviewing the moment all seven dimensions are complete.
+
+### Batch 1 — the learner
+
+```text
+1. Who is this for, exactly? Role, experience level, and how familiar they already are with the topic.
+2. What do they ALREADY know coming in, and what do they definitely NOT know yet?
+3. In THEIR words, what frustrates or scares them about this topic? (top 2–3)
+4. What do they actually want — the outcome that made them show up? (top 2–3)
+```
+
+### Batch 2 — false beliefs (the block)
+
+```text
+5. What do they wrongly BELIEVE about this topic today that gets in the way? For each, tell me
+   whether it's: "this approach won't work" (vehicle), "I personally can't do it" (internal),
+   or "something outside me will stop me" (external). I'll break each one with a story before teaching.
+6. After this lesson/module, what should they be able to DO that they couldn't before? (be concrete)
+```
+
+### Batch 3 — the audience & the medium
+
+```text
+7. Are the listeners the same people as the buyer/decision-maker, or different?
+8. Is this live or recorded? Solo learner or a cohort — roughly how many?
+9. Where/how do they consume it (on a commute, in a classroom, at their desk while working)?
+```
+
+### Batch 4 — transformation & constraints
+
+```text
+10. In one sentence: what's the single before→after this whole thing exists to produce? Frame it as
+    who they become + what they can now do, not a list of topics.
+11. What's the format and length budget? (video, live, written, slides; minutes/pages)
+12. Any hard constraints on tone, vocabulary, or content? (must be language-agnostic? no jargon?
+    compliance limits? a voice to match?)
+```
+
+If the user can't answer a question, that dimension stays incomplete — note the gap, keep the STOP in place for that dimension, and offer to draft a hypothesis they can confirm rather than fabricating an answer.
+
+## Persistence format
+
+### Profile wiki article template
+
+Each `02-DOCS/wiki/teaching/*.md` article follows the harness wiki format:
+
+```markdown
+# Teaching — Learner
+
+> Sources: {user interview, YYYY-MM-DD}
+> Raw: [transcript-module-1](../../raw/teaching/transcript-module-1.md)
+
+## Overview
+
+One paragraph: who is learning and what must change in them.
+
+## Level & prior knowledge
+
+- Role / experience: …
+- Already knows: …
+- Does not know yet: …
+
+## Pains & desires (their words)
+
+- Pain: …
+- Desire: …
+
+## The "do" after
+
+After this, the learner can: …
+
+## See Also
+
+- [Transformation](transformation.md)
+- [False beliefs](false-beliefs.md)
+```
+
+### False-beliefs article specifics
+
+`false-beliefs.md` must type every belief so `brunson-frameworks.md` can match it to a breaking story:
+
+```markdown
+# Teaching — False Beliefs
+
+> Sources: {user interview, YYYY-MM-DD}
+
+## Vehicle ("this approach won't work")
+
+- "Tests just slow me down and don't catch real bugs." -> break with: the data-loss bug a
+  test-first caught when review missed it.
+
+## Internal ("I can't do it")
+
+- "TDD is for real engineers, I just hack." -> break with: your year-one CRUD feature where
+  test-first made you faster.
+
+## External ("something outside me will stop it")
+
+- "My deadline won't allow tests first." -> break with: the sprint where the test became the
+  spec and shipped early.
+```
+
+### Raw inputs
+
+Paste each user-provided transcript / outline / slide deck verbatim into its own `02-DOCS/raw/teaching/<name>.md` with a one-line provenance header:
+
+```markdown
+> Source: user-pasted, YYYY-MM-DD, origin: "Module 1 lecture transcript"
+
+<the material, unedited>
+```
+
+### CLAUDE.md link
+
+Add (or update) this section in the root `CLAUDE.md`. Additive only — never delete existing sections. Create `CLAUDE.md` if absent.
+
+```markdown
+## Knowledge map
+
+Teaching is grounded in the learner + audience profile under `02-DOCS/wiki/teaching/`.
+Read it before reframing any lesson:
+
+- [Transformation (index)](02-DOCS/wiki/teaching/index.md)
+- [Learner](02-DOCS/wiki/teaching/learner.md)
+- [Audience](02-DOCS/wiki/teaching/audience.md)
+- [Transformation](02-DOCS/wiki/teaching/transformation.md)
+- [False beliefs](02-DOCS/wiki/teaching/false-beliefs.md)
+- [Constraints & format](02-DOCS/wiki/teaching/constraints.md)
+
+Course teaching conventions (narrative spine, named models, Big Dominoes, Attractive Character):
+`02-DOCS/wiki/stack/course-storytelling.md`.
+Raw transcripts / outlines / slides: `02-DOCS/raw/teaching/`.
+The `course-storytelling` skill maintains this profile and stops to interview the user
+if any dimension is missing.
+```
+
+If a `## Knowledge map` section already exists (e.g. from `marketing`/`design`), append the teaching links to it rather than creating a second one.
+
+## See Also
+
+- `../SKILL.md` — the runtime grounding mechanism (hard STOP) that uses this checklist.
+- `brunson-frameworks.md` — consumes the typed false beliefs and the transformation.
+- `course-analysis.md` — uses the "do after" + transformation to sequence the spine.
+- `../../harness/SKILL.md` — the canonical `02-DOCS` wiki protocol and article templates.

package/skills/course-storytelling/references/mental-models.md

@@ -0,0 +1,115 @@
+# Mental Models — Naming, Analogy Engineering & Grounding
+
+A concept the student can't *name* is a concept they can't repeat — and what can't be repeated isn't retained. A concept they can't picture is one that never gets concrete enough to *use*. This file is the craft of both: designing sticky, ownable names and engineering the analogies that drop an abstraction down to earth. It feeds the "MENTAL MODEL" and "GROUNDED ANALOGY" beats of the landing recipe (`concept-landing-recipe.md`) and the "new opportunity" handoff from `brunson-frameworks.md`.
+
+---
+
+## Part 1 — Designing a named mental model
+
+A mental model is a short, ownable handle the student carries out of the lesson and reuses. Good names do three jobs: **compress** (one phrase recalls the whole idea), **transfer** (it applies beyond the example), and **stick** (it's easy to say and hard to forget).
+
+### The naming tests (a name must pass all four)
+
+1. **Sayable** — a student can repeat it out loud, from memory, a week later. 2–4 words.
+2. **Picturable** — it evokes a concrete image or object, not an abstraction. ("The Elevator Button" pictures; "Operational Convergence" does not.)
+3. **Ownable** — it's specific enough to feel like *this* teacher's coinage, not a generic term they could Google.
+4. **Load-bearing** — the name encodes the *mechanism*, so recalling the name recalls how it works.
+
+### Naming patterns that work
+
+| Pattern | Shape | Example (for a concept) |
+| --- | --- | --- |
+| Concrete object | "The [familiar object]" | "The Elevator Button" (idempotency) |
+| Vivid action | "[Verb] the [noun]" | "Shrink the Blast Radius" (fault isolation) |
+| Memorable contrast | "[X], not [Y]" | "Spec, Not Chore" (test-first) |
+| Rule of N | "The [N] [things]" | "The Two-Pizza Rule" (team size) |
+| Named law/effect | "The [Name] [Law/Effect]" | "The Last-Mile Tax" (deployment friction) |
+
+```text
+Bad  (no name)    — "We should design operations so repeated execution is safe."
+Bad  (jargon name)— "Operational Idempotence Convergence" (unsayable, unpicturable, un-ownable)
+Good (named)      — "The Elevator Button: press it five times, one elevator still comes."
+```
+
+### Where names live
+
+Persist every coined model in `02-DOCS/wiki/stack/course-storytelling.md` (or under `wiki/teaching/`) so names stay consistent across lessons and the student hears the same handle every time. A model renamed mid-course is a model un-learned.
+
+---
+
+## Part 2 — Analogy & metaphor engineering
+
+An analogy maps an unfamiliar concept onto something the student already understands deeply. Engineered well, it does the explaining for you. Engineered carelessly, it teaches the wrong thing.
+
+### The mapping method
+
+```text
+ANALOGY MAP
+Target (unfamiliar) ... the concept you're teaching
+Source (familiar) ..... something from the LEARNER'S world (from wiki/teaching/learner.md)
+Mapped parts .......... list each piece of the target -> its match in the source
+Where it breaks ....... the ONE place the analogy fails (state it — prevents over-extension)
+```
+
+### Rules
+
+- **Source from THEIR world, not yours.** A cooking analogy for chefs, a sports analogy for athletes, a spreadsheet analogy for finance folks. Pull the source domain from the learner profile.
+- **Map the mechanism, not just the vibe.** A good analogy survives "okay, so what happens when…" — the parts correspond. A vibe-only analogy ("it's like magic") collapses on the first follow-up.
+- **State where it breaks.** Every analogy fails somewhere. Naming the break point *before* a student finds it keeps trust and prevents them from learning the wrong thing.
+- **One analogy per concept.** Stacking three analogies for one idea dilutes all three. Pick the strongest.
+
+### Worked example — "idempotency" → "The Elevator Button"
+
+```text
+Target: an idempotent operation (repeated calls = one effect)
+Source: pressing an elevator call button
+Mapped parts:
+  - the request          -> pressing the button
+  - the side effect      -> one elevator dispatched
+  - retries / dup sends  -> pressing the lit button again
+  - the idempotency key  -> the button's "already lit" state
+Where it breaks: a real elevator eventually arrives regardless; an idempotent API needs the key
+  to RECOGNIZE the duplicate — name this so they don't think "it just works by magic".
+```
+
+```text
+Bad  (vibe only)  — "Idempotency is like, you know, it just handles duplicates gracefully."
+Good (mapped)     — the elevator map above: every part corresponds, and the break is named.
+```
+
+---
+
+## Part 3 — Grounding abstract → concrete
+
+Three moves that pull an abstraction down to where the student lives.
+
+1. **Replace the variable with a value.** Don't say "for any request"; say "for *your* 4pm deploy." Specifics are graspable; generalities float.
+2. **Explain it like their day.** Recast the concept inside a moment from the learner's actual routine (commute, standup, the ticket they're avoiding). Pulled from `wiki/teaching/learner.md`.
+3. **Future-pace it.** Walk them through a near-future moment where they use the idea and it pays off. The brain pre-experiences the win and wants the concept that delivers it. (Story-selling move — see `brunson-frameworks.md`.)
+
+```text
+Bad  (abstract)  — "Backoff prevents thundering-herd retries from overwhelming a recovering service."
+Good (grounded)  — "Your service just came back from an outage. The instant it's up, 10,000 queued
+                    retries hit it at once and knock it over again. Backoff is everyone waiting a
+                    polite, increasing beat before knocking — so the recovering service can breathe.
+                    Next incident, you'll add jittered backoff and watch the recovery actually hold."
+```
+
+---
+
+## Part 4 — "Make it land" tests
+
+Apply these to any reframed concept before shipping. If it fails one, it isn't landed.
+
+- **The repeat-back test.** Could the student explain this to a peer in one sentence using your name for it? If not, the name or analogy is weak.
+- **The week-later test.** Will they still recall the name and the picture next week with no notes? If it needs notes, it's not sticky.
+- **The follow-up test.** Does the analogy survive "okay, but what about…"? If it collapses, the mapping is vibe-only — re-map or name the break.
+- **The so-what test.** Can the student say why it matters to *them*, in their world? If not, you stopped before grounding.
+- **The jargon test.** Every term either glossed, grounded, or cut. An unexplained term is a leak where attention drains out.
+
+## See Also
+
+- `../SKILL.md` — the non-negotiables (name everything, ground everything).
+- `concept-landing-recipe.md` — where the named model + analogy slot into the seven beats.
+- `brunson-frameworks.md` — the "new opportunity" beat that hands off to the named model; future-pacing.
+- `learner-grounding.md` — the learner's world that analogy source domains are drawn from.

package/skills/course-storytelling/scripts/verify.sh

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+#
+# verify.sh — "did it land?" QA gate for the `course-storytelling` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free heuristics over your lesson/course source files. For each
+#   concept section it checks that the teaching has the ingredients that make it land:
+#     1. Story presence    — a section that teaches a concept but has no narrative
+#        markers (no "I", no "story", no time/place setup) is a `no-story` lesson.
+#     2. Named model       — a memorable, ownable name (a "The X" handle / bolded coinage).
+#     3. Grounded analogy  — an analogy marker ("like", "imagine", "think of it as").
+#     4. Application step   — a do-this-now action ("try this", "do this", "your turn").
+#     5. So-what payoff     — a future-paced close ("next time", "you'll be able to", "so that").
+#     6. Abstraction / jargon density — flags sections heavy on abstract nouns
+#        (-tion/-ity/-ность style) with no analogy nearby.
+#     7. markdownlint of lesson sources, if markdownlint is installed.
+#
+#   Every finding is a WARNING by default (teaching is judgement, not pass/fail).
+#   Use --strict to turn warnings into a failure (exit 1) so CI can gate on it.
+#   A missing tool is reported yellow and SKIPPED — never a failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                 # scan ./ for lesson sources (*.md, *.mdx, *.txt)
+#   ./verify.sh --path lessons  # scan a subdirectory
+#   ./verify.sh --strict        # treat any warning as a failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, or warnings only without --strict
+#   1  a real failure, or --strict with any warning
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, arrays are
+# initialised and only expanded when non-empty under `set -u`.
+
+set -euo pipefail
+
+# --- portability: runs on stock macOS bash 3.2 ------------------------------
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (any version >= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+# --- color helpers (no escape codes when not a TTY) -------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() {
+  # print the header comment block (lines 2..44), stripping the leading "# "
+  sed -n '2,44p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# count_lines <file>: number of lines in a file; 0 if missing/empty.
+# Robust across BSD/GNU: wc -l can print leading spaces, so strip non-digits.
+count_lines() {
+  if [ -s "$1" ]; then
+    wc -l < "$1" 2>/dev/null | tr -dc '0-9'
+  else
+    printf '0'
+  fi
+}
+
+# find lesson source files (markdown / text). Prints one path per line.
+# Excludes the conventional 02-DOCS wiki/raw so we lint LESSONS, not the profile.
+list_lessons() {
+  find "$SCAN_PATH" \
+    \( -name '*.md' -o -name '*.mdx' -o -name '*.txt' \) \
+    -type f \
+    ! -path '*/node_modules/*' \
+    ! -path '*/.git/*' \
+    ! -path '*/02-DOCS/*' \
+    2>/dev/null || true
+}
+
+# file_has <file> <pattern>: 0 if the (case-insensitive) pattern appears in the file.
+file_has() { grep -iqE "$2" "$1" 2>/dev/null; }
+
+# --- ensure we have a searcher ----------------------------------------------
+# The per-file checks use grep (via file_has); find gathers the lesson list.
+if ! have grep; then
+  skip "grep not found — cannot scan lesson sources; install grep"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# --- gather lesson files ----------------------------------------------------
+TMPDIR_V="$(mktemp -d 2>/dev/null || printf '/tmp/verify-cs.%s' "$$")"
+mkdir -p "$TMPDIR_V" 2>/dev/null || true
+cleanup() { rm -rf "$TMPDIR_V" 2>/dev/null || true; }
+trap cleanup EXIT
+
+LESSONS="$TMPDIR_V/lessons"
+list_lessons > "$LESSONS" 2>/dev/null || true
+n_lessons="$(count_lines "$LESSONS")"
+
+if [ "$n_lessons" -eq 0 ]; then
+  skip "no lesson sources (*.md, *.mdx, *.txt) found under $SCAN_PATH"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Scanning %s lesson file(s) under: %s\n\n' "$n_lessons" "$SCAN_PATH"
+
+# Heuristic markers (case-insensitive ERE).
+STORY_RE='\bi (was|had|remember|learned|realized|once)\b|\bstory\b|\bone (day|night|morning)\b|at the time|years? (ago|in)|epiphany|the moment (i|we|they)'
+NAME_RE='\bthe [A-Z][a-z]+( [A-Z][a-z]+)?\b|\*\*[^*]+\*\*|call (it|this) the|i call (it|this)|known as the'
+ANALOGY_RE='\blike (a|an|the|your)\b|\bimagine\b|\bthink of (it|this) as\b|\bit.?s (basically|essentially) (a|an|like)\b|analog|metaphor|as if'
+APPLICATION_RE='\btry (this|it)\b|\bdo this\b|\byour turn\b|right now|before you (close|move|continue)|exercise|step 1|hands.?on|go (build|add|write|open)'
+SOWHAT_RE='next time|you.?ll (be able|now|never)|so that you|what.?s now possible|from now on|imagine being able|future|the payoff'
+
+# Per-file results (bash 3.2: append to temp files, count in parent shell).
+NS="$TMPDIR_V/no_story";   : > "$NS"
+NN="$TMPDIR_V/no_name";    : > "$NN"
+NA="$TMPDIR_V/no_analogy"; : > "$NA"
+NP="$TMPDIR_V/no_appl";    : > "$NP"
+NW="$TMPDIR_V/no_sowhat";  : > "$NW"
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  file_has "$f" "$STORY_RE"       || printf '%s\n' "$f" >> "$NS"
+  file_has "$f" "$NAME_RE"        || printf '%s\n' "$f" >> "$NN"
+  file_has "$f" "$ANALOGY_RE"     || printf '%s\n' "$f" >> "$NA"
+  file_has "$f" "$APPLICATION_RE" || printf '%s\n' "$f" >> "$NP"
+  file_has "$f" "$SOWHAT_RE"      || printf '%s\n' "$f" >> "$NW"
+done < "$LESSONS" || true   # read returns 1 at EOF; harmless under set -e
+
+report_files() {
+  label="$1"; listfile="$2"
+  n="$(count_lines "$listfile")"
+  if [ "$n" -gt 0 ]; then
+    warn "$label ($n file(s)):"
+    head -n 8 "$listfile" | sed 's/^/        /'
+    warn_count=$((warn_count + n - 1))   # warn() already counted 1
+  else
+    ok "no $label"
+  fi
+}
+
+# --- 1..5 landing-ingredient checks -----------------------------------------
+report_files "lessons with no story marker (add an Epiphany Bridge beat)"        "$NS"
+report_files "lessons with no named mental model (name the concept)"             "$NN"
+report_files "lessons with no grounded analogy (add a concrete metaphor)"        "$NA"
+report_files "lessons with no application step (add a do-this-now)"              "$NP"
+report_files "lessons with no so-what payoff (future-pace the close)"            "$NW"
+
+# --- 6. abstraction / jargon density ----------------------------------------
+# Heuristic: lines dense in abstract -tion/-ity/-ism nouns. Flag files where such
+# lines appear AND the file has no analogy marker (analogy is the antidote).
+ABSTRACT_RE='\b[a-z]{4,}(tion|ality|ility|ism|ance|ence)\b'
+JARGON_HITS="$TMPDIR_V/jargon"; : > "$JARGON_HITS"
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  dense="$(grep -ioE "$ABSTRACT_RE" "$f" 2>/dev/null | wc -l | tr -dc '0-9')"
+  [ -z "$dense" ] && dense=0
+  if [ "$dense" -ge 12 ] && ! file_has "$f" "$ANALOGY_RE"; then
+    printf '%s (%s abstract nouns, no analogy)\n' "$f" "$dense" >> "$JARGON_HITS"
+  fi
+done < "$LESSONS" || true   # read returns 1 at EOF; harmless under set -e
+n_jargon="$(count_lines "$JARGON_HITS")"
+if [ "$n_jargon" -gt 0 ]; then
+  warn "jargon/abstraction-dense lessons with no grounding analogy ($n_jargon file(s)):"
+  head -n 8 "$JARGON_HITS" | sed 's/^/        /'
+  warn_count=$((warn_count + n_jargon - 1))
+else
+  ok "no abstraction-dense, analogy-less lessons"
+fi
+
+# --- 7. markdownlint of lesson sources (if available) -----------------------
+if have markdownlint; then
+  # Lint only the lesson files; warn on findings, never fail the gate here.
+  ml_out="$TMPDIR_V/mdlint"
+  # shellcheck disable=SC2046  # word-splitting the file list is intended here
+  markdownlint $(cat "$LESSONS") > "$ml_out" 2>&1 || true
+  if [ -s "$ml_out" ]; then
+    warn "markdownlint findings in lesson sources:"
+    head -n 10 "$ml_out" | sed 's/^/        /'
+  else
+    ok "markdownlint clean on lesson sources"
+  fi
+else
+  skip "markdownlint not found — skipping markdown lint (npm i -g markdownlint-cli)"
+fi
+
+# --- summary ----------------------------------------------------------------
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+cat <<'EOF'
+
+Note: every finding above is a heuristic WARNING — teaching is judgement, not pass/fail.
+Review each: does the concept actually have a story, a named model, a grounded analogy, an
+application step, and a so-what? Then fix or justify. Re-run with --strict to gate CI.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0