@antoneeo/course-creator 0.1.0-beta.3 → 0.1.0-beta.5

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

@@ -54,7 +54,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 +63,132 @@ 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")
+    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")
 
 
 def validate_course(root, course_dir):
@@ -448,11 +448,11 @@ 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):
+    _content_contract(course_dir, plan, plan_rows, read, ref, add)
+    return findings
+
+
+def validate_all(root):
     root = Path(root).resolve()
     docs = root / "ai_docs"
     parent = docs / "solutions/courses"

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

@@ -125,6 +125,21 @@ def kb_unquote(value):
     return v
 
 
+def frontmatter_date(meta):
+    """A note's or a sidecar's `date:` as `YYYY-MM-DD`, or None (F-073).
+    Quotes stripped, a datetime suffix tolerated, an impossible date refused --
+    the one parser behind orient's recency probe and any chronology reader."""
+    m = re.match(r"(\d{4}-\d{2}-\d{2})", kb_unquote((meta or {}).get("date")))
+    if not m:
+        return None
+    try:
+        import datetime as _dt
+        _dt.date.fromisoformat(m.group(1))
+    except ValueError:
+        return None
+    return m.group(1)
+
+
 def kb_parse_scope(text):
     """'-' | 'from X' | 'until X' | 'from X until Y' | 'if <cond>' ->
     ('always',) | ('window', from, until) | ('if', cond). Raises on junk."""
@@ -336,6 +351,17 @@ def kb_check_claims(root):
         if rel not in fm_cache:
             fm_cache[rel] = _note_frontmatter(root, rel)
         return fm_cache[rel]
+    # F-069: the same per-run memo for the source paths themselves -- each
+    # distinct path is resolved and stat'ed once, and each cited extraction
+    # read once (loc_cache, owned here, dropped when this call returns).
+    src_cache = {}
+    loc_cache = {}
+
+    def _resolved(path_s):
+        if path_s not in src_cache:
+            t = sdlc_core.confine_under(root, path_s)
+            src_cache[path_s] = (t, t is not None and t.is_file())
+        return src_cache[path_s]
     per_file_rows = []
     for p in sorted(topics.glob("*.md")):
         rel = "topics/" + p.name
@@ -357,16 +383,16 @@ def kb_check_claims(root):
                     errors.append("%s: source %r has no locator" % (where, src))
                     continue
                 path_s, loc = src.rsplit("#", 1)
-                target = sdlc_core.confine_under(root, path_s)
+                target, is_file = _resolved(path_s)
                 if target is None:
                     errors.append("%s: source %r escapes the docs root" % (where, src))
                     continue
-                if not target.is_file():
+                if not is_file:
                     errors.append("%s: source %r does not resolve — a claim whose "
                                   "origin cannot be reopened is model knowledge"
                                   % (where, src))
                     continue
-                kb_check_locator(target, loc, where, errors)
+                kb_check_locator(target, loc, where, errors, loc_cache)
             # --- provenance ---
             prov = row["prov"]
             # Resolved ONCE, for every provenance: the non-GIVEN classes read it
@@ -556,8 +582,14 @@ def kb_check_claims(root):
     return errors, warnings, notes
 
 
-def kb_check_locator(target, loc, where, errors):
-    """A locator must address an existing span of the stored bytes."""
+def kb_check_locator(target, loc, where, errors, cache=None):
+    """A locator must address an existing span of the stored bytes.
+
+    `cache` is an optional dict the CALLER owns for one run (F-069): keyed by
+    the path actually read, it holds only what the checks compare against --
+    page lengths, a line count, or False for a missing extraction -- never the
+    text. Findings are still appended per call, so per row. Without it, every
+    call reads the file, as before."""
     m = LOC_PAGE_RE.match(loc)
     if m:
         page, a, b = int(m.group(1)), int(m.group(2)), int(m.group(3))
@@ -566,17 +598,24 @@ def kb_check_locator(target, loc, where, errors):
             return
         # offsets address the stored extraction (<stem>.txt beside the original)
         ext = target if target.suffix == ".txt" else target.with_suffix(".txt")
-        if not ext.is_file():
+        key = ("p", ext)
+        if cache is None or key not in cache:
+            lengths = ([len(pg) for pg in sdlc_core.read_text(ext).split("\f")]
+                       if ext.is_file() else False)
+            if cache is not None:
+                cache[key] = lengths
+        else:
+            lengths = cache[key]
+        if lengths is False:
             errors.append("%s: no stored extraction %s for locator %r — offsets "
                           "must address kept bytes" % (where, ext.name, loc))
             return
-        pages = sdlc_core.read_text(ext).split("\f")
-        if page < 1 or page > len(pages):
+        if page < 1 or page > len(lengths):
             errors.append("%s: locator %r addresses page %d of %d" %
-                          (where, loc, page, len(pages)))
-        elif b > len(pages[page - 1]):
+                          (where, loc, page, len(lengths)))
+        elif b > lengths[page - 1]:
             errors.append("%s: locator %r spans past the end of page %d "
-                          "(%d chars)" % (where, loc, page, len(pages[page - 1])))
+                          "(%d chars)" % (where, loc, page, lengths[page - 1]))
         return
     m = LOC_LINE_RE.match(loc)
     if m:
@@ -584,7 +623,13 @@ def kb_check_locator(target, loc, where, errors):
         if a > b or a < 1:
             errors.append("%s: locator %r has an invalid line range" % (where, loc))
             return
-        n = sdlc_core.read_text(target).count("\n") + 1
+        key = ("L", target)
+        if cache is None or key not in cache:
+            n = sdlc_core.read_text(target).count("\n") + 1
+            if cache is not None:
+                cache[key] = n
+        else:
+            n = cache[key]
         if b > n:
             errors.append("%s: locator %r spans past line %d" % (where, loc, n))
         return
@@ -1085,12 +1130,18 @@ KB_GENERATED_RE = re.compile(r"GENERATED by \S+ index - do not edit by hand")
 KB_HEX12_RE = re.compile(r"^[0-9a-f]{12}$")
 
 
-def _kb_hex_bounded(text, cid):
-    """True when cid appears NOT embedded in a longer hex run: a git hash
-    sharing a substring must never count as a citation (either side, either
-    case). cid is pre-validated 12-hex, so it is regex-safe by construction."""
-    return re.search(r"(?<![0-9a-fA-F])%s(?![0-9a-fA-F])" % cid,
-                     text) is not None
+# A citation of a claim id is a run of exactly its 12 lowercase hex characters
+# NOT embedded in a longer hex run: a git hash sharing a substring must never
+# count as a citation (either side, either case). Two such bounded runs cannot
+# overlap, so findall returns every one of them.
+KB_HEX_TOKEN_RE = re.compile(r"(?<![0-9a-fA-F])[0-9a-f]{12}(?![0-9a-fA-F])")
+
+
+def _kb_hex_tokens(text):
+    """The ids a text cites, extracted in one pass (F-069). Callers test
+    membership instead of scanning the text once per id: that per-(document,
+    id) scan made the time cycle grow with superseded ids x living documents."""
+    return frozenset(KB_HEX_TOKEN_RE.findall(text))
 
 
 def _kb_df_entries(value):
@@ -1172,19 +1223,23 @@ def kb_time_cycle(docs):
         if (meta.get("status") or "").strip() == "SUPERSEDED":
             continue
         living.append((rel, text))
-    for rel, text in living:
-        for old in sorted(superseded):
-            if _kb_hex_bounded(text, old):
-                succs = superseded[old]
-                missing = tuple(x for x in succs
-                                if not _kb_hex_bounded(text, x))
-                if missing:
-                    cited.append((rel, old, missing, succs))
+    # One token pass per living document, and none at all on a KB with no
+    # supersession and no validity window (the orient line runs this at every
+    # session start).
+    tokens = ({rel: _kb_hex_tokens(text) for rel, text in living}
+              if superseded or windows else {})
+    for rel, _text in living:
+        cites = tokens[rel] if tokens else frozenset()
+        for old in cites.intersection(superseded):
+            succs = superseded[old]
+            missing = tuple(x for x in succs if x not in cites)
+            if missing:
+                cited.append((rel, old, missing, succs))
     today = _dt.date.today().isoformat()
     for topic_rel, rid, until in sorted(windows):
         if until <= today:
-            by = tuple(rel for rel, text in living
-                       if rel != topic_rel and _kb_hex_bounded(text, rid))
+            by = tuple(rel for rel, _text in living
+                       if rel != topic_rel and rid in tokens[rel])
             expired.append((topic_rel, rid, until, by))
     rev = {}
     node_meta = {}
@@ -1905,14 +1960,13 @@ def kb_cmd_orient(argv):
                     # it -- the file was already fully read, so the cap bought
                     # only failure. load_frontmatter is the authoritative
                     # reader (fence-bounded, so a column-0 date: in the body
-                    # still cannot misdate the note); kb_unquote covers quoted
-                    # dates; the prefix match tolerates a datetime suffix.
+                    # still cannot misdate the note); frontmatter_date covers
+                    # quoted dates and tolerates a datetime suffix.
                     meta = sdlc_core.load_frontmatter(
                         sdlc_core.read_text(p).splitlines()) or {}
-                    m = re.match(r"(\d{4}-\d{2}-\d{2})",
-                                 kb_unquote(meta.get("date")))
-                    if m:
-                        stamp = _dt.date.fromisoformat(m.group(1))
+                    day = frontmatter_date(meta)
+                    if day:
+                        stamp = _dt.date.fromisoformat(day)
                 except Exception:
                     pass
                 if stamp is None: