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

package/skills/course-creator/docs_site/app.js

@@ -12,7 +12,7 @@
   var D = null;   // documents, loaded on first use
   var K = null;   // knowledge base, loaded on first use
   var app = document.getElementById("app");
-  var ORIGINS = ["given", "elicited", "derived", "ruling", "imported"];
+  var ORIGINS = ["given", "elicited", "derived", "ruling", "imported", "declared"];
 
   // ------------------------------------------------------------- helpers
 
@@ -483,6 +483,7 @@
     if (f.statement) marks.push(el("span", { "class": "tag statement", title: t("statement_notice"), text: t("statement_mark") }));
     if (f.state === "superseded") marks.push(el("span", { "class": "tag replaced", title: t("state_superseded_why"), text: t("state_superseded") }));
     if (f.state === "contested") marks.push(el("span", { "class": "tag conflict", title: t("state_contested_why"), text: t("state_contested") }));
+    if (f.state === "diverges") marks.push(el("span", { "class": "tag conflict", title: t("state_diverges_why"), text: t("state_diverges") }));
     if (opts && opts.topic) marks.push(link("#/topic/" + encodeURIComponent(f.topic), f.topic, "chip"));
     return el("li", { "class": "fact" + (f.state === "superseded" ? " replaced" : ""), onclick: function () { location.hash = "#/fact/" + encodeURIComponent(id); } },
       el("span", { "class": "dot bg-" + oc }),
@@ -597,6 +598,11 @@
           el("p", { "class": "why-line", text: t("state_contested_why") }),
           el("ul", { "class": "facts" }, (f.with || []).map(function (s) { return factLine(s, { topic: true }); })));
       }
+      if (f.state === "diverges") {
+        parts.push(el("h3", null, el("span", { "class": "tag conflict", text: t("state_diverges") }), " ", t("fact_diverges_from")),
+          el("p", { "class": "why-line", text: t("state_diverges_why") }),
+          el("ul", { "class": "facts" }, (f.diverges_from || []).map(function (s) { return factLine(s, { topic: true }); })));
+      }
       if (f.grounds) {
         parts.push(el("h3", { text: t("fact_rests_on") }),
           el("p", { "class": "why-line", text: t("ground_class_" + f.ground_class) }),

package/skills/course-creator/docs_site/strings.js

@@ -56,7 +56,9 @@ window.DOCS_SITE_STRINGS = {
   event_request: "request record",
   event_note: "note",
   event_source: "source document received",
+  event_sent: "document sent",
   event_review: "review",
+  event_defect: "defect reported after merge",
   event_decision: "decision record",
   event_project_note: "project note",
   event_spike: "exploration outcome",
@@ -231,6 +233,8 @@ window.DOCS_SITE_STRINGS = {
   origin_ruling_why: "Taken to settle a conflict.",
   origin_imported: "from another knowledge base",
   origin_imported_why: "Brought in from another knowledge base, where its own sources are.",
+  origin_declared: "declared by this project",
+  origin_declared_why: "What this project told a recipient, on the day it was sent: a statement of ours, not a fact about the product.",
   origin_other: "origin as written: {v}",
   origin_other_why: "An origin this site does not know.",
 
@@ -239,6 +243,8 @@ window.DOCS_SITE_STRINGS = {
   state_superseded_why: "A newer fact takes its place.",
   state_contested: "in conflict",
   state_contested_why: "Facts that disagree, not yet settled.",
+  state_diverges: "diverges",
+  state_diverges_why: "What we declared contradicts what the project decided. It is corrected by a new send, or the decision changes.",
 
   statement_mark: "statement",
   statement_prefix: "[statement] {text}",
@@ -254,6 +260,7 @@ window.DOCS_SITE_STRINGS = {
   fact_replaced_by: "Replaced by",
   fact_current_at_end: "Current fact at the end of each chain",
   fact_in_conflict_with: "In conflict with",
+  fact_diverges_from: "Diverges from",
   fact_rests_on: "What it rests on",
   fact_untraced: "This part could not be traced.",
   fact_sources: "Sources",
@@ -266,6 +273,7 @@ window.DOCS_SITE_STRINGS = {
   fact_unknown: "This fact is not in this knowledge base.",
 
   ground_document: "a document",
+  ground_declared: "a document this project sent",
   ground_statement: "a person's statement",
   ground_decision: "a decision",
   ground_kb: "another knowledge base",
@@ -273,6 +281,7 @@ window.DOCS_SITE_STRINGS = {
   ground_class_statement: "Rests, at least in part, on a person's statement.",
   ground_class_untraceable: "Part of what it rests on could not be traced.",
   ground_class_imported: "Rests on another knowledge base.",
+  ground_class_declared: "Rests on our own declaration to a recipient, not on evidence.",
   ground_class_documents: "Rests on documents or decisions only.",
 
   chain_loop: "The chain of replacements loops back to {id}: it stops here.",

package/skills/course-creator/docs_site/style.css

@@ -18,6 +18,7 @@
   --o-derived: #a99be0;
   --o-ruling: #7fa7e6;
   --o-imported: #9cc96b;
+  --o-declared: #d98fb0;
   --conflict: #e0605a;
   --display: "Iowan Old Style", "Palatino Linotype", Palatino, "Book Antiqua", Charter, Georgia, serif;
   --body: "Segoe UI Variable Text", "Avenir Next", Avenir, "Gill Sans Nova", "Gill Sans", "Trebuchet MS", sans-serif;
@@ -179,6 +180,7 @@ a.factid code { color: var(--link); }
 .o-derived { color: var(--o-derived); } .bg-derived { background: var(--o-derived); }
 .o-ruling { color: var(--o-ruling); } .bg-ruling { background: var(--o-ruling); }
 .o-imported { color: var(--o-imported); } .bg-imported { background: var(--o-imported); }
+.o-declared { color: var(--o-declared); } .bg-declared { background: var(--o-declared); }
 .o-other { color: var(--paper-3); } .bg-other { background: var(--paper-3); }
 
 .panel {

package/skills/course-creator/guides.md

@@ -262,6 +262,12 @@ in the snapshot, never to your assumption about what the code does.
   (source-anchored), not an elaborated version of it.
 - When in doubt about whether something is "supported" by the source, treat it
   as not covered rather than stretching the marker to fit.
+- **Declared exception: `## Preservation constraints`.** A code guide may carry
+  this section, copied at an L3 closure from the ANALYSIS's table (code lens,
+  `SKILL.md` Phase 5). The section's marker cites each row it holds as
+  `[source: solutions/ANALYSIS_<name>.md#P<n>]` instead of a snapshot anchor: each
+  row records what the code must keep doing, as that unit enumerated and probed it,
+  not an excerpt of the code.
 
 ## 4. Ingestion bound (T9)
 
@@ -293,5 +299,7 @@ state it explicitly when handing off a newly created guide.
   closure (docs travel with the code); when you merely READ one, check it against
   the code before trusting it. Too large to absorb → mark it `SUPERSEDED` rather
   than leave a confident-wrong map badged CURRENT, which is worse than none.
+- **A regenerated guide keeps `## Preservation constraints` unchanged**: the
+  section does not come from the snapshot (§3), so regeneration carries it over.
 - **Agent-global KB guides** use the same pipeline and validator via
   `--root ~/.agentic-sdlc`; freshness via the same `stale` engine.

package/skills/course-creator/learning_design.md

@@ -40,7 +40,7 @@ When the procedure is performed by a tool or agent, the worked case shows the to
 
 Introduce necessary terms before using them; keep related data, diagram labels and explanations together. Remove decorative or irrelevant information. Segment a complex explanation into meaningful steps while retaining how they connect. Tailor support to the learner rather than equating more words with better teaching.
 
-The complete source can be detailed without making every slide dense. In self-study, all essential reasoning must remain visible across the learner's units; in guided delivery, author the necessary spoken explanation. If content does not fit, divide the canonical units before rendering instead of shrinking text or hiding meaning in notes. Preserve exact examples and visual relationships through the handoff.
+The complete source can be detailed without making every slide dense. In self-study, all essential reasoning must remain visible across the learner's units; in guided delivery, author the necessary spoken explanation, and give the instructor the operating instructions and materials in `INSTRUCTOR_GUIDE.md` (`templates.md`). If content does not fit, divide the canonical units before rendering instead of shrinking text or hiding meaning in notes. Preserve exact examples and visual relationships through the handoff.
 
 ## 6. Use recall, practice and feedback to improve the explanation
 

package/skills/course-creator/review.md

@@ -187,7 +187,10 @@ can block forever gets removed. **Log one row per completed review, PASS or FAIL
 logging only passes would erase exactly that evidence. The row goes in
 `ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
 `| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
-with `tier` = `design` or `closure` in Standalone. **`model` records the capability
+with `tier` = `design` or `closure` in Standalone. In the code lens, a wrong behaviour
+the owner reports in a merged L3 change is one row too, tier `post-merge`, `model`
+`none (owner report)`, reviewer `owner`, the owner quoted in the notes: a defect
+record, not a review, so `benefit` keeps it out of every review figure. **`model` records the capability
 tier that actually ran** — `deep`, `light`, `economy`, `single (client exposes no
 choice)`, `below floor: <reason>`, or `none (not due)` on a NOT DUE row — never a provider name in doctrine (a project
 may of course write its own model names in its own log). Without it the floor above
@@ -285,6 +288,11 @@ The binding inputs, by review type:
   clause reads both), and the **probe harness** (`ai_docs/solutions/harness_[feature]/`).
   Hand these *in addition to* the design artifact — the reviewer checks the artifact
   **against** them, not only for internal consistency.
+- **The constraint view comes last.** Where the ANALYSIS carries ids, the reviewer
+  derives the callers and behaviours first, then compares with
+  `sdlc_check.py constraints --unit <id>`: a constraint the design states and the
+  diff breaks is a finding. The view never replaces the ANALYSIS or the diff in the
+  request.
 - **For a closure review, the diff and the test evidence**: the run output that
   backs every completion claim, dated after the final relevant change.
 - **For a design or closure review of an L3/E3 unit, the request record**

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"