@antoneeo/course-creator 0.1.0-beta.14 → 0.1.0-beta.15

package/skills/course-creator/scripts/course_check.py

@@ -2,6 +2,7 @@
 """Structural checks for one course; never certifies teaching quality or learning."""
 from dataclasses import dataclass
 from pathlib import Path
+import os
 import re
 
 
@@ -54,7 +55,7 @@ def _items(cell):
             if part.strip() and part.strip() != "-"]
 
 
-def _anchor_exists(path, anchor):
+def _anchor_exists(path, anchor):
     if path.suffix.lower() not in (".md", ".txt"):
         if path.suffix.lower() == ".pdf":
             return bool(re.fullmatch(r"page=[1-9]\d*", anchor))
@@ -63,132 +64,284 @@ def _anchor_exists(path, anchor):
         return bool(re.fullmatch(r"\d{2}:\d{2}(?::\d{2})?", anchor))
     text = path.read_text(encoding="utf-8", errors="replace")
     return any(re.sub(r"[^a-z0-9 -]", "", heading.lower()).strip().replace(" ", "-") == anchor.lower()
-               for heading in re.findall(r"^#+\s+(.+)$", text, re.M))
-
-
-def _content_contract(course_dir, plan, plan_rows, read, ref, add):
-    """Validate authored-source structure, not its pedagogical sufficiency."""
-    plan_path = course_dir / "COURSE_PLAN.md"
-
-    def field(text, key, path, item):
-        values = re.findall(r"^" + re.escape(key) + r":[ \t]*(.*)$", text, re.M)
-        if len(values) != 1 or not values[0].strip() or values[0].strip() == "-":
-            add(path, item, f"{key} must occur once with a value")
-            return ""
-        return values[0].strip()
-
-    declarations = re.findall(r"^Content contract:[ \t]*(.*)$", plan, re.M)
-    if not declarations:
-        add(plan_path, "content", "legacy course: migrate to a complete textual content contract; quality is not certified", "WARN")
-        return
-    contract = field(plan, "Content contract", plan_path, "content")
-    if contract not in ("slide-content-v1", "text-content-v1"):
-        add(plan_path, "content", "unknown content contract")
-        return
-    prefix, name = ("S", "SLIDE_CONTENT.md") if contract == "slide-content-v1" else ("U", "COURSE_CONTENT.md")
-    if prefix == "U":
-        field(plan, "Format exception", plan_path, "content")
-    path = course_dir / name
-    text = read(path, "content")
-    if text is None:
-        return
-    intro = text.split("\n## ", 1)[0]
-    if field(intro, "Course version", path, "version") != field(plan, "Course version", plan_path, "version"):
-        add(path, "version", "content version differs from COURSE_PLAN")
-    if field(intro, "Delivery mode", path, "delivery") not in ("self-study", "instructor-led"):
-        add(path, "delivery", "unknown delivery mode")
-    for key in ("Efficacy", "Feedback flow"):
-        if field(intro, key, path, key) != field(plan, key, plan_path, key):
-            add(path, key, f"{key} differs from COURSE_PLAN")
-    headers = ("profile", "baseline", "target capability", "teaching contribution", "observable check", "alternative and limits")
-    values = _table(text, headers) or []
-    expected_profiles = {row["profile"] for row in plan_rows}
-    if {row["profile"] for row in values} != expected_profiles or len(values) != len(expected_profiles):
-        add(path, "value", "Course Value must cover each taught profile exactly once")
-    for row in values:
-        if any(not row[h] or row[h] == "-" for h in headers):
-            add(path, "value", "Course Value fields must be populated; semantic review still required")
-        ref(row["observable check"], path, "value")
-    modules = {row["module id"]: row for row in plan_rows}
-    sections = re.split(r"(?m)^## (.+)\n", text)
-    units = {}
-    order = []
-    for heading, body in zip(sections[1::2], sections[2::2]):
-        if heading == "Course Value":
-            continue
-        if not re.fullmatch(prefix + r"[0-9]+", heading):
-            add(path, heading, "unexpected unit heading")
-            continue
-        if heading in units:
-            add(path, heading, "duplicate unit ID")
-        metadata = body.split("### ", 1)[0]
-        unit = {key: field(metadata, key, path, heading) for key in
-                ("Module", "Objective", "Role", "Title", "Value contribution")}
-        units[heading] = unit
-        order.append(heading)
-        unit["coverage"] = {(unit["Module"], unit["Objective"])}
-        extra_coverage = re.findall(r"^Covers:[ \t]*(.*)$", metadata, re.M)
-        if len(extra_coverage) > 1:
-            add(path, heading, "Covers must occur at most once")
-        if extra_coverage:
-            pairs = _items(extra_coverage[0])
-            if not pairs:
-                add(path, heading, "Covers must list module/objective pairs")
-            for pair in pairs:
-                if not re.fullmatch(r"M\d+/O\d+", pair):
-                    add(path, heading, "invalid coverage pair; expected M1/O1")
-                    continue
-                mid, objective = pair.split("/")
-                if (mid, objective) in unit["coverage"]:
-                    add(path, heading, "duplicate coverage pair")
-                unit["coverage"].add((mid, objective))
-        for mid, objective in unit["coverage"]:
-            if mid not in modules or modules[mid]["objective id"] != objective:
-                add(path, heading, "coverage module/objective differs from COURSE_PLAN")
-        module = modules.get(unit["Module"])
-        if not module or module["objective id"] != unit["Objective"]:
-            add(path, heading, "unit module/objective differs from COURSE_PLAN")
-        if unit["Role"] not in ("orientation", "explanation", "check", "solution", "closing"):
-            add(path, heading, "unknown unit role")
-        if unit["Role"] == "check":
-            unit["Solution"] = field(metadata, "Solution", path, heading)
-        parts = re.split(r"(?m)^### (.+)\n", body)
-        content = list(zip(parts[1::2], parts[2::2]))
-        for key in ("Learner content", "Complete explanation", "Visual content", "Transition", "Sources"):
-            blocks = [b.strip() for k, b in content if k == key]
-            if len(blocks) != 1 or not blocks[0] or blocks[0] == "-":
-                add(path, heading, f"{key} section must occur once with content")
-        for key, block in content:
-            if key == "Sources":
-                for source in block.strip().splitlines():
-                    ref(source.removeprefix("- ").strip(), path, heading, allow_url=True)
-    source_path = path.relative_to(course_dir.parents[3]).as_posix()
-    for mid, row in modules.items():
-        for key, roles in (("explanation", {"orientation", "explanation"}), ("check", {"check"})):
-            references = _items(row[key])
-            if not references:
-                continue  # existing module checker reports missing fields
-            for value in references:
-                target, _, anchor = value.partition("#")
-                uid = anchor.upper()
-                unit = units.get(uid, {})
-                if (target != source_path or (mid, row["objective id"]) not in unit.get("coverage", set())
-                        or unit.get("Role") not in roles):
-                    add(plan_path, mid, f"{key} must locate its module's canonical content unit")
-    for uid, unit in units.items():
-        if unit["Role"] == "check":
-            solution_id = unit.get("Solution", "")
-            solution = units.get(solution_id, {})
-            if (solution.get("Role") != "solution"
-                    or not unit["coverage"].issubset(solution.get("coverage", set()))
-                    or order.index(solution_id) <= order.index(uid)):
-                add(path, uid, "check needs a subsequent solution covering every module/objective")
-    for row in values:
-        target, _, anchor = row["observable check"].partition("#")
-        unit = units.get(anchor.upper(), {})
-        covered_profiles = {modules[mid]["profile"] for mid, obj in unit.get("coverage", set()) if mid in modules}
-        if target != source_path or unit.get("Role") != "check" or row["profile"] not in covered_profiles:
-            add(path, "value", "observable check must locate a canonical check for its profile")
+               for heading in re.findall(r"^#+\s+(.+)$", text, re.M))
+
+
+def _content_contract(course_dir, plan, plan_rows, read, ref, add):
+    """Validate authored-source structure, not its pedagogical sufficiency."""
+    plan_path = course_dir / "COURSE_PLAN.md"
+
+    def field(text, key, path, item):
+        values = re.findall(r"^" + re.escape(key) + r":[ \t]*(.*)$", text, re.M)
+        if len(values) != 1 or not values[0].strip() or values[0].strip() == "-":
+            add(path, item, f"{key} must occur once with a value")
+            return ""
+        return values[0].strip()
+
+    declarations = re.findall(r"^Content contract:[ \t]*(.*)$", plan, re.M)
+    if not declarations:
+        add(plan_path, "content", "legacy course: migrate to a complete textual content contract; quality is not certified", "WARN")
+        return
+    contract = field(plan, "Content contract", plan_path, "content")
+    if contract not in ("slide-content-v1", "text-content-v1"):
+        add(plan_path, "content", "unknown content contract")
+        return
+    prefix, name = ("S", "SLIDE_CONTENT.md") if contract == "slide-content-v1" else ("U", "COURSE_CONTENT.md")
+    if prefix == "U":
+        field(plan, "Format exception", plan_path, "content")
+    path = course_dir / name
+    text = read(path, "content")
+    if text is None:
+        return
+    intro = text.split("\n## ", 1)[0]
+    if field(intro, "Course version", path, "version") != field(plan, "Course version", plan_path, "version"):
+        add(path, "version", "content version differs from COURSE_PLAN")
+    mode = field(intro, "Delivery mode", path, "delivery")
+    if mode not in ("self-study", "instructor-led"):
+        add(path, "delivery", "unknown delivery mode")
+    for key in ("Efficacy", "Feedback flow"):
+        if field(intro, key, path, key) != field(plan, key, plan_path, key):
+            add(path, key, f"{key} differs from COURSE_PLAN")
+    headers = ("profile", "baseline", "target capability", "teaching contribution", "observable check", "alternative and limits")
+    values = _table(text, headers) or []
+    expected_profiles = {row["profile"] for row in plan_rows}
+    if {row["profile"] for row in values} != expected_profiles or len(values) != len(expected_profiles):
+        add(path, "value", "Course Value must cover each taught profile exactly once")
+    for row in values:
+        if any(not row[h] or row[h] == "-" for h in headers):
+            add(path, "value", "Course Value fields must be populated; semantic review still required")
+        ref(row["observable check"], path, "value")
+    modules = {row["module id"]: row for row in plan_rows}
+    sections = re.split(r"(?m)^## (.+)\n", text)
+    units = {}
+    order = []
+    for heading, body in zip(sections[1::2], sections[2::2]):
+        if heading == "Course Value":
+            continue
+        if not re.fullmatch(prefix + r"[0-9]+", heading):
+            add(path, heading, "unexpected unit heading")
+            continue
+        if heading in units:
+            add(path, heading, "duplicate unit ID")
+        metadata = body.split("### ", 1)[0]
+        unit = {key: field(metadata, key, path, heading) for key in
+                ("Module", "Objective", "Role", "Title", "Value contribution")}
+        units[heading] = unit
+        order.append(heading)
+        unit["coverage"] = {(unit["Module"], unit["Objective"])}
+        extra_coverage = re.findall(r"^Covers:[ \t]*(.*)$", metadata, re.M)
+        if len(extra_coverage) > 1:
+            add(path, heading, "Covers must occur at most once")
+        if extra_coverage:
+            pairs = _items(extra_coverage[0])
+            if not pairs:
+                add(path, heading, "Covers must list module/objective pairs")
+            for pair in pairs:
+                if not re.fullmatch(r"M\d+/O\d+", pair):
+                    add(path, heading, "invalid coverage pair; expected M1/O1")
+                    continue
+                mid, objective = pair.split("/")
+                if (mid, objective) in unit["coverage"]:
+                    add(path, heading, "duplicate coverage pair")
+                unit["coverage"].add((mid, objective))
+        for mid, objective in unit["coverage"]:
+            if mid not in modules or modules[mid]["objective id"] != objective:
+                add(path, heading, "coverage module/objective differs from COURSE_PLAN")
+        module = modules.get(unit["Module"])
+        if not module or module["objective id"] != unit["Objective"]:
+            add(path, heading, "unit module/objective differs from COURSE_PLAN")
+        if unit["Role"] not in ("orientation", "explanation", "check", "solution", "closing"):
+            add(path, heading, "unknown unit role")
+        if unit["Role"] == "check":
+            unit["Solution"] = field(metadata, "Solution", path, heading)
+        parts = re.split(r"(?m)^### (.+)\n", body)
+        content = list(zip(parts[1::2], parts[2::2]))
+        for key in ("Learner content", "Complete explanation", "Visual content", "Transition", "Sources"):
+            blocks = [b.strip() for k, b in content if k == key]
+            if len(blocks) != 1 or not blocks[0] or blocks[0] == "-":
+                add(path, heading, f"{key} section must occur once with content")
+        for key, block in content:
+            if key == "Sources":
+                for source in block.strip().splitlines():
+                    ref(source.removeprefix("- ").strip(), path, heading, allow_url=True)
+    source_path = path.relative_to(course_dir.parents[3]).as_posix()
+    for mid, row in modules.items():
+        for key, roles in (("explanation", {"orientation", "explanation"}), ("check", {"check"})):
+            references = _items(row[key])
+            if not references:
+                continue  # existing module checker reports missing fields
+            for value in references:
+                target, _, anchor = value.partition("#")
+                uid = anchor.upper()
+                unit = units.get(uid, {})
+                if (target != source_path or (mid, row["objective id"]) not in unit.get("coverage", set())
+                        or unit.get("Role") not in roles):
+                    add(plan_path, mid, f"{key} must locate its module's canonical content unit")
+    for uid, unit in units.items():
+        if unit["Role"] == "check":
+            solution_id = unit.get("Solution", "")
+            solution = units.get(solution_id, {})
+            if (solution.get("Role") != "solution"
+                    or not unit["coverage"].issubset(solution.get("coverage", set()))
+                    or order.index(solution_id) <= order.index(uid)):
+                add(path, uid, "check needs a subsequent solution covering every module/objective")
+    for row in values:
+        target, _, anchor = row["observable check"].partition("#")
+        unit = units.get(anchor.upper(), {})
+        covered_profiles = {modules[mid]["profile"] for mid, obj in unit.get("coverage", set()) if mid in modules}
+        if target != source_path or unit.get("Role") != "check" or row["profile"] not in covered_profiles:
+            add(path, "value", "observable check must locate a canonical check for its profile")
+    title = re.search(r"^# (.+)$", text, re.M)
+    return {"path": path, "text": text, "mode": mode, "title": title.group(1).strip() if title else "",
+            "solutions": [uid for uid in dict.fromkeys(order) if units[uid]["Role"] == "solution"]}
+
+
+GUIDE_SECTIONS = ("Before the course", "Schedule", "Reserved material", "When something deviates",
+                  "After the course", "Materials")
+VERSION_MENTION = re.compile(r"\bversion[e]?\s*:?\s*v?(\d+\.[A-Za-z0-9][A-Za-z0-9.-]*)", re.I)
+COURSE_WORD = re.compile(r"\b(?:corso|course)\b", re.I)
+
+
+def _version_mentions(path, body, version, names, add):
+    """Flag a line that names the course and mentions a version other than Course version."""
+    heading = "text"
+    for line in body.splitlines():
+        if line.startswith("## "):
+            heading = line[3:].strip()
+            continue
+        if not (COURSE_WORD.search(line) or any(
+                re.search(r"(?<!\w)" + re.escape(name) + r"(?!\w)", line, re.I) for name in names if name)):
+            continue
+        for match in VERSION_MENTION.finditer(line):
+            found = match.group(1).rstrip(".")
+            if found != version:
+                add(path, heading, f"mentions course version {found}; Course version is {version}")
+
+
+def _delivery_package(root, course_dir, plan, plan_rows, contract, risks, read, add):
+    """Validate the instructor-led delivery package; structure only, never the quality of the instructions."""
+    version = (re.findall(r"^Course version:[ \t]*(.*)$", plan, re.M) or [""])[0].strip()
+    names = (course_dir.name, contract["title"])
+    if version:
+        _, _, rest = contract["text"].partition("\n## ")
+        _version_mentions(contract["path"], "## " + rest if rest else "", version, names, add)
+    guide_path = course_dir / "INSTRUCTOR_GUIDE.md"
+    if not guide_path.is_file():
+        if contract["mode"] == "instructor-led":
+            add(guide_path, "instructor guide", "instructor-led course needs INSTRUCTOR_GUIDE.md before delivery")
+        return
+    guide = read(guide_path, "instructor guide")
+    if guide is None:
+        return
+    intro, _, rest = guide.partition("\n## ")
+    body = "## " + rest if rest else ""
+    for key in ("Course version", "Feedback flow"):
+        values = re.findall(r"^" + re.escape(key) + r":[ \t]*(.*)$", intro, re.M)
+        expected = re.findall(r"^" + re.escape(key) + r":[ \t]*(.*)$", plan, re.M)
+        if len(values) != 1 or not expected or values[0].strip() != expected[0].strip():
+            add(guide_path, key, f"{key} must occur once and equal COURSE_PLAN")
+    if version:
+        _version_mentions(guide_path, body, version, names, add)
+    parts = re.split(r"(?m)^## (.+)\n", body)
+    sections = {}
+    for heading, block in zip(parts[1::2], parts[2::2]):
+        sections.setdefault(heading.strip(), []).append(block.strip())
+    for name in GUIDE_SECTIONS:
+        blocks = sections.get(name, [])
+        if len(blocks) != 1 or not blocks[0]:
+            add(guide_path, name, f"section '## {name}' must occur once with content")
+
+    def section(name):
+        return (sections.get(name) or [""])[0]
+
+    course_root = course_dir.resolve()
+    docs_root = (root / "ai_docs").resolve()
+
+    def packaged(value, item, locator_allowed):
+        """Resolve a guide path inside the project; report and return None when it is not usable."""
+        path_part, sep, anchor = value.partition("#")
+        path = Path(path_part)
+        if (not path.parts or path.is_absolute() or path.drive or path.root or ".." in path.parts
+                or (sep and (not locator_allowed or not anchor))):
+            add(guide_path, item, f"'{value}' must be a path relative to the project root, with no drive, "
+                "leading '/' or '..'" + ("" if locator_allowed else ", and no '#locator'"))
+            return None
+        target = (root / path).resolve()
+        if not target.is_relative_to(root):
+            add(guide_path, item, f"'{value}' resolves outside the project, so it cannot be delivered")
+        elif not target.exists():
+            add(guide_path, item, f"'{value}' does not exist: create it, or correct the path")
+        elif not locator_allowed and path_part.endswith("/") != target.is_dir():
+            add(guide_path, item, f"'{value}' must end with '/' exactly when it is a folder")
+        elif anchor and (not target.is_file() or not _anchor_exists(target, anchor)):
+            add(guide_path, item, f"'{value}' has no matching locator")
+        else:
+            return target
+        return None
+
+    def nested_repository(target):
+        """Read folder names only; never follow a symlink or a Windows junction out of the folder."""
+        for base, dirs, _ in os.walk(target):
+            if ".git" in dirs or "ai_docs" in dirs or Path(base, ".git").is_file():
+                return True
+            dirs[:] = [d for d in dirs if not (os.path.islink(os.path.join(base, d))
+                                               or getattr(os.path, "isjunction", lambda _: False)(
+                                                   os.path.join(base, d)))]
+        return False
+
+    rows = _table(section("Materials"), ("material", "path", "seen by", "used in")) or []
+    if not rows:
+        add(guide_path, "Materials", "Materials table must list the delivered package")
+    targets = []
+    for row in rows:
+        target = packaged(row["path"], "Materials", False)
+        if target is not None:
+            targets.append(target)
+            if target.is_dir() and target.is_relative_to(docs_root) and nested_repository(target):
+                add(guide_path, "Materials", f"'{row['path']}' holds its own repository (.git or ai_docs/) "
+                    "inside ai_docs/, so project memory indexes its files as this project's: "
+                    "keep it outside ai_docs/", "WARN")
+        if row["seen by"] not in ("instructor", "learners"):
+            add(guide_path, "Materials", f"'{row['path']}' Seen by must be instructor or learners")
+    listed = {row["path"] for row in rows}
+    materials = {value.rstrip("/") for value in listed}
+    cited = {value.rstrip(".,;:") for value in re.findall(r"(?<![\w/.])ai_docs/[^\s|`<>\"'()*]+", guide)}
+    for value in sorted(cited - listed):
+        target = packaged(value, "citation", True)
+        if target is not None and not any(target == t or target.is_relative_to(t)
+                                          for t in (course_root, *targets)):
+            add(guide_path, "citation", f"'{value}' is cited but is not in the delivered package: "
+                "list it in '## Materials' or move it into the course folder")
+    reserved = section("Reserved material")
+    for uid in contract["solutions"]:
+        if not re.search(r"\b" + re.escape(uid) + r"\b", reserved):
+            add(guide_path, uid, f"solution unit {uid} must be named in '## Reserved material'")
+    rows = _table(section("When something deviates"),
+                  ("risk id", "in class it looks like", "instructor action", "fallback material")) or []
+    if not rows:
+        add(guide_path, "When something deviates", "deviation table must have at least one row")
+    for row in rows:
+        rid = row["risk id"] or "deviation"
+        if row["risk id"] not in risks:
+            add(guide_path, rid, f"risk {rid} is not defined in P-TM.md")
+        fallback = row["fallback material"]
+        if not fallback:
+            add(guide_path, rid, "fallback material must be '-' or paths listed in '## Materials'")
+        elif fallback != "-":
+            for value in (part.strip() for part in fallback.split(",") if part.strip()):
+                if value.rstrip("/") not in materials:
+                    add(guide_path, rid, f"fallback '{value}' is not listed in '## Materials'")
+    modules = {row["module id"] for row in plan_rows}
+    rows = _table(section("Schedule"), ("session", "duration", "modules")) or []
+    if not rows:
+        add(guide_path, "Schedule", "schedule table must have at least one session")
+    for row in rows:
+        if not row["session"] or not row["duration"] or not (_items(row["modules"]) or row["modules"] == "-"):
+            add(guide_path, "Schedule", "each schedule row needs a name, a duration and its modules, "
+                "or '-' for a break or closing")
+        for mid in _items(row["modules"]):
+            if mid not in modules:
+                add(guide_path, mid, f"schedule module {mid} is not in COURSE_PLAN")
 
 
 def validate_course(root, course_dir):
@@ -448,11 +601,14 @@ def validate_course(root, course_dir):
         else:
             add(course_dir / "COURSE_PLAN.md", "efficacy",
                 "human review of efficacy evidence required", severity="WARN")
-    _content_contract(course_dir, plan, plan_rows, read, ref, add)
-    return findings
-
-
-def validate_all(root):
+    contract = _content_contract(course_dir, plan, plan_rows, read, ref, add)
+    if contract:
+        risks = {row["risk id"] for row in _table(material["P-TM.md"] or "", ("risk id",)) or []}
+        _delivery_package(root, course_dir, plan, plan_rows, contract, risks, read, add)
+    return findings
+
+
+def validate_all(root):
     root = Path(root).resolve()
     docs = root / "ai_docs"
     parent = docs / "solutions/courses"

package/skills/course-creator/scripts/shared_manifest.json

@@ -1,37 +1,37 @@
-{
-  "_comment": "Generated by shared_files.py --update. IDENTICAL in every distribution of the family: if two copies of this file differ, the spine has diverged. Never edit by hand.",
-  "files": {
-    "LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
-    "NOTICE": "8414f424f7c1db19d89d74286fd2d6b1acdd9eedde910fa57a16d6835602e4bd",
-    "dispatch.md": "d127057198415f81b921c74e3234a47d5794a2af662eeadaf3dff3cc1739ebc8",
-    "docs_site/app.js": "ce9ed4341f7d24b648dee7531700d09f4af07f7e9ffc4be90aff29ecc276f27f",
-    "docs_site/index.html": "2b64167470f754e46fa4bb4e73a3d2c34ee632d91fe2f17705a58d18b5018af5",
-    "docs_site/strings.js": "440c11830f87602152422766b6d5b84da904150c37b0b6347e2ad53a7fec62b8",
-    "docs_site/style.css": "1cbd71eb2e62bb9251ecb62796fe4cecf6a78eecf2f9a7493703290ae55d1244",
-    "guides.md": "8fd85ab176d01ad7fc4c72020afa062f37f3c2f6b380f064c20f114c0680b46b",
-    "memory.md": "765c8cf34e9161143d6f8b982106251de0ac7f4f6f5d768336f3e4b4b150823e",
-    "review.md": "c8564114171feaeaa149247d2202005c2880d4507feb0d3a51acf513964f738c",
-    "routing.md": "5116e8dbd3b215919b897506f28917ac8f1c44cd91f8b64ec901048320e6c1f6",
-    "scripts/docs_site.py": "bfc7a521142251b85b229e1873ccf2e375bb5c7f1990cef574e1a78ef14f0091",
-    "scripts/entry_point.py": "4a560d4d41db989d3426182f1b24270cbb934b3db0f3246c700578a4ed93089b",
-    "scripts/knowledge.py": "6047deb7a2be4cf9ef2949cbcf8a52a8ea61500f4e12d203f1c58076540d50ab",
-    "scripts/sdlc_core.py": "099151cc45d295218df1fa83d893ebf4b095c4a633bc1f2018b7ea6faad3117c",
-    "scripts/shared_files.py": "ebc3c6cf207ccd98ec70f7565a12cb7c54da5c8a1a759bae7e62bdb74cb5c6e2",
-    "scripts/test_audit_refs.py": "5c207be46da566db47069b08373195e748fca19c047418f09cc2f78841dfd9a5",
-    "scripts/test_chronology.py": "ef482ed2261822778c69ade5dae6c875eca97ae8ef4f47b60bc262ac857eb95c",
-    "scripts/test_constraints.py": "4be3bbff7032e53b464de2f4e2eb18a824311adb2359c77fb9be065aded09239",
-    "scripts/test_docs_root.py": "19753e0316c0df63ed321d24b411a9ff36eea2058421fd69fc57e507d75566d0",
-    "scripts/test_docs_site.py": "391ec5c635c67f0fbefe458426e352b5b1ef626ae65c099b1e8e1db491d0a5f9",
-    "scripts/test_domain_rules.py": "33542b5dc2bb77c05ece55cf0446065cc4226c763ef5e040aa77364f226937bb",
-    "scripts/test_drift.py": "c7b7121a8a308b0f3fe12c0c0c346444e632b7aaeff47dc8818b621e5c20cb38",
-    "scripts/test_guide_check.py": "19c7a6f009fa1b7f70b0beba059b97fa05e69255f6b2dec8829a87bd9fba283f",
-    "scripts/test_merge_safety.py": "8b9241077bf7ecd6dd335907c640044ab38968ff4c9fdc464450e732cb77adf4",
-    "scripts/test_migrate.py": "c129823bf4feb0614acd975351632a6ae62d7896a0ef32724419a8e9335e3110",
-    "scripts/test_plan.py": "4c011a63aa834b55e9c5d13fb4ea76b131b742356001364b0a508435ba013e27",
-    "scripts/test_project_memory.py": "2cb85cef01161d881a11d84cfe9ebb72915104e8d1822e4de739f7d00ae6cd59",
-    "scripts/test_session_start.py": "723f748c0aef461d1051191dbd18f4ea5697a1e0467df73bccb0af8024d17f56",
-    "scripts/test_skill_invariants.py": "47d116563a37a16b7d25b322020dd730eecac8cf4cfc7916b877df4e729f8373",
-    "scripts/test_verdict.py": "8620be2f962f900e9fa0f979f80984671baa373de1ce3f29045104d813e71844",
-    "vision.md": "a19a7d7d5044215b726b66f74e422c9cdedcc856c0a53151f20a6d9840b8f6c4"
-  }
-}
+{
+  "_comment": "Generated by shared_files.py --update. IDENTICAL in every distribution of the family: if two copies of this file differ, the spine has diverged. Never edit by hand.",
+  "files": {
+    "LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30",
+    "NOTICE": "8414f424f7c1db19d89d74286fd2d6b1acdd9eedde910fa57a16d6835602e4bd",
+    "dispatch.md": "d127057198415f81b921c74e3234a47d5794a2af662eeadaf3dff3cc1739ebc8",
+    "docs_site/app.js": "ce9ed4341f7d24b648dee7531700d09f4af07f7e9ffc4be90aff29ecc276f27f",
+    "docs_site/index.html": "2b64167470f754e46fa4bb4e73a3d2c34ee632d91fe2f17705a58d18b5018af5",
+    "docs_site/strings.js": "440c11830f87602152422766b6d5b84da904150c37b0b6347e2ad53a7fec62b8",
+    "docs_site/style.css": "1cbd71eb2e62bb9251ecb62796fe4cecf6a78eecf2f9a7493703290ae55d1244",
+    "guides.md": "8fd85ab176d01ad7fc4c72020afa062f37f3c2f6b380f064c20f114c0680b46b",
+    "memory.md": "765c8cf34e9161143d6f8b982106251de0ac7f4f6f5d768336f3e4b4b150823e",
+    "review.md": "c8564114171feaeaa149247d2202005c2880d4507feb0d3a51acf513964f738c",
+    "routing.md": "5116e8dbd3b215919b897506f28917ac8f1c44cd91f8b64ec901048320e6c1f6",
+    "scripts/docs_site.py": "bfc7a521142251b85b229e1873ccf2e375bb5c7f1990cef574e1a78ef14f0091",
+    "scripts/entry_point.py": "4a560d4d41db989d3426182f1b24270cbb934b3db0f3246c700578a4ed93089b",
+    "scripts/knowledge.py": "6047deb7a2be4cf9ef2949cbcf8a52a8ea61500f4e12d203f1c58076540d50ab",
+    "scripts/sdlc_core.py": "099151cc45d295218df1fa83d893ebf4b095c4a633bc1f2018b7ea6faad3117c",
+    "scripts/shared_files.py": "ebc3c6cf207ccd98ec70f7565a12cb7c54da5c8a1a759bae7e62bdb74cb5c6e2",
+    "scripts/test_audit_refs.py": "5c207be46da566db47069b08373195e748fca19c047418f09cc2f78841dfd9a5",
+    "scripts/test_chronology.py": "ef482ed2261822778c69ade5dae6c875eca97ae8ef4f47b60bc262ac857eb95c",
+    "scripts/test_constraints.py": "4be3bbff7032e53b464de2f4e2eb18a824311adb2359c77fb9be065aded09239",
+    "scripts/test_docs_root.py": "19753e0316c0df63ed321d24b411a9ff36eea2058421fd69fc57e507d75566d0",
+    "scripts/test_docs_site.py": "391ec5c635c67f0fbefe458426e352b5b1ef626ae65c099b1e8e1db491d0a5f9",
+    "scripts/test_domain_rules.py": "33542b5dc2bb77c05ece55cf0446065cc4226c763ef5e040aa77364f226937bb",
+    "scripts/test_drift.py": "c7b7121a8a308b0f3fe12c0c0c346444e632b7aaeff47dc8818b621e5c20cb38",
+    "scripts/test_guide_check.py": "19c7a6f009fa1b7f70b0beba059b97fa05e69255f6b2dec8829a87bd9fba283f",
+    "scripts/test_merge_safety.py": "8b9241077bf7ecd6dd335907c640044ab38968ff4c9fdc464450e732cb77adf4",
+    "scripts/test_migrate.py": "c129823bf4feb0614acd975351632a6ae62d7896a0ef32724419a8e9335e3110",
+    "scripts/test_plan.py": "4c011a63aa834b55e9c5d13fb4ea76b131b742356001364b0a508435ba013e27",
+    "scripts/test_project_memory.py": "2cb85cef01161d881a11d84cfe9ebb72915104e8d1822e4de739f7d00ae6cd59",
+    "scripts/test_session_start.py": "723f748c0aef461d1051191dbd18f4ea5697a1e0467df73bccb0af8024d17f56",
+    "scripts/test_skill_invariants.py": "47d116563a37a16b7d25b322020dd730eecac8cf4cfc7916b877df4e729f8373",
+    "scripts/test_verdict.py": "8620be2f962f900e9fa0f979f80984671baa373de1ce3f29045104d813e71844",
+    "vision.md": "a19a7d7d5044215b726b66f74e422c9cdedcc856c0a53151f20a6d9840b8f6c4"
+  }
+}

package/skills/course-creator/slide_content.md

@@ -59,7 +59,7 @@ Value contribution: <why this step is needed for the module objective>
 - ai_docs/.../sources.md#claim-1
 ```
 
-`Delivery mode` is `self-study` or `instructor-led`. `Role` is `orientation`, `explanation`, `check`, `solution` or `closing`. A check may cover several modules/objectives; do not force one separate exercise per module. A check adds `Solution: S04` (or U04); the referenced unit is a subsequent `solution` covering all the check’s module/objective pairs, and contains the actual answer, rationale and correction path in its authored content. Put fictional-case labels in learner-visible copy, not only in production notes. A necessary definition, inference or caveat cannot exist only in notes for a self-study course.
+`Delivery mode` is `self-study` or `instructor-led`. In `instructor-led` the Complete explanation is the text to speak, but it is not enough to deliver the course: preparation, reserved material, what to do when a live step fails, clean-up and the list of delivered materials belong in `INSTRUCTOR_GUIDE.md` (`templates.md`). `Role` is `orientation`, `explanation`, `check`, `solution` or `closing`. A check may cover several modules/objectives; do not force one separate exercise per module. A check adds `Solution: S04` (or U04); the referenced unit is a subsequent `solution` covering all the check’s module/objective pairs, and contains the actual answer, rationale and correction path in its authored content. Put fictional-case labels in learner-visible copy, not only in production notes. A necessary definition, inference or caveat cannot exist only in notes for a self-study course.
 
 For a shared explanation or cumulative check, add optional `Covers: M2/O2; M3/O3` metadata listing the additional module/objective pairs beyond the primary `Module`/`Objective`. Every pair must match the plan. A shared unit may serve separate module rows for different profiles without duplicating content, provided its explanation is suitable for all those profiles. A cumulative solution covers every pair assessed by its check. Review the actual check and answer for every declared objective; a coverage label alone is not proof.
 
@@ -67,7 +67,7 @@ For a shared explanation or cumulative check, add optional `Covers: M2/O2; M3/O3
 
 ## Release review and rendering handoff
 
-Review the actual learner surface: self-study uses Learner content plus visible transitions and captions; guided delivery additionally uses the authored spoken explanation. Separate solutions from the learner test packet. Give a renderer enough detail to construct every unit without writing new teaching material. If splitting a dense slide is necessary, update the canonical units/IDs first. Return semantic changes to this source before regenerating a deck.
+Review the actual learner surface: self-study uses Learner content plus visible transitions and captions; guided delivery additionally uses the authored spoken explanation, and is handed over with `INSTRUCTOR_GUIDE.md` and every material it lists. Separate solutions from the learner test packet. Give a renderer enough detail to construct every unit without writing new teaching material. If splitting a dense slide is necessary, update the canonical units/IDs first. Return semantic changes to this source before regenerating a deck.
 
 Apply the clarity-review handoff in `SKILL.md` §4 to this learner surface, using the course's declared audience rather than the author's familiarity with the subject.