purpose: fix vacuous matching, name the sections, guard the doc hand-copies

Audit of this round's purpose-registry work, on the three axes asked for.

EFFECTIVENESS — three checks were VACUOUS. Naive substring matching satisfied
`ct` inside "a-CT-ion", `fit` inside "bene-FIT", `is a` inside "this IS A
summary". On an adversarial deck carrying only those three phrases,
product_pitch reported NOTHING missing at all. `_names()` now anchors at a word
START for Latin (a start anchor, not a full boundary, because `feasib` and
`demo` are deliberate prefixes), plain substring for CJK (no word boundaries),
substring for a term with no alphanumerics (`%`). Non-indicative terms removed.

    before  tumour board   missing=['presentation','outcome']
            job talk       missing=['track record','research plan']
            product pitch  missing=[]
    after   tumour board   missing=['presentation','investigations','outcome']
            job talk       missing=['track record','research plan','fit']
            product pitch  missing=['positioning']

…and five sections did not list their OWN NAME as a term, so `job_talk/track
record` reported MISSING on a slide reading "My track record".

GENERALISATION — the two reference files are hand-copies of the registry, and a
hand-copy drifts. Writing one out got 1 of 12 wrong within minutes: the runbook
said "lab meeting" (a trigger word) where every gate message prints
`research_meeting`, so an agent grepping the doc for the name in its own error
found nothing. `check_purpose --selftest` now checks both files for every genre
name, every section name, the delivery-mode note, and the stated count. Each arm
is mutation-tested in the suite — including a duplicate of an already-documented
genre, which only the count can catch, proving that arm is not dead code.

NON-CLAUDE AGENTS — `codex-runtime.md` still said "Four genres" and never
mentioned `purposes.py`; a capability absent from that runbook is one the next
Codex run rediscovers by failing a gate, or never uses. It now states 12 of 13
with every section, why the thirteenth (webinar) has no list, and how matching
works. The medium-vs-genre message was also duplicating a clause on that path.

Verified: test_purpose_sections 176 passed · test_schema_reach 27 passed ·
gate_parity, codex_delivery_gate, codex_scaffold_complete, step1_artifacts,
smoke_deckkit ok · inventory/tests-wired/parity/reference-code/repo-integrity/
secrets clean · lossless 2719/2719. Synced to ~/.agents/skills/slide-maker and
re-run there.

Author: dong845

skills/slide-maker/references/codex-runtime.md

@@ -212,11 +212,19 @@ be reconstructed post-hoc at the delivery gate.
    device that advisory is the expected result — say so in the plan rather than adding a key you
    do not want.
 
-**The deck's GENRE may declare required content — `check_purpose.py`, on both gate paths.** Four
-genres carry sections their audience is asked to judge against, so a deck missing one is not a lean
-deck: **grant** (aims · feasibility · risk) · **progress/guidance committee** (progress · plan ·
-**ask**) · **journal club** (attribution · critique) · **clinical case** (presentation ·
-investigations · management · outcome). 🔴 **This binds from the RECORD, and the Codex schema has no
+**The deck's GENRE may declare required content — `check_purpose.py`, on both gate paths.** TWELVE of the thirteen
+genres in `design-by-purpose.md` carry sections their audience is asked to judge against, so a deck
+missing one is not a lean deck: **grant** (aims · feasibility · risk) · **committee** (progress ·
+plan · **ask**) · **journal club** (attribution · critique) · **clinical case** (presentation ·
+investigations · management · outcome) · **defense** (contributions · limitations · future work) ·
+**conference talk** (contribution · evidence · limitations) · **job talk** (track record · research
+plan · fit) · **exec readout** (the ask · the number · the risk) · **research meeting** (lab/group meeting: what
+changed · open questions) · **work status** (outcome · the ask) · **product pitch** (positioning · benefits) ·
+**teaching** (objectives · worked example · recap). 🔴 The thirteenth, **webinar**, has no list on
+purpose — it is a delivery MODE, not a genre, and `check_purpose` says so and asks you for the
+GENRE rather than silently checking nothing. Matching is word-START boundary for Latin (naive
+substring made three of these VACUOUS: `ct` inside a-CT-ion, `fit` inside bene-FIT) and plain
+substring for CJK. 🔴 **This binds from the RECORD, and the Codex schema has no
 `purpose` key** — so it reads `interview.record` (the user's own answers), the `content.
 audience_brief` `who` + `decisions`, and any `design.purpose` you add. On a SUPERVISED Codex run
 `delegated_picks` records no purpose axis at all, so `interview.record` is frequently the only place

skills/slide-maker/scripts/check_purpose.py

@@ -36,6 +36,7 @@
 import argparse
 import json
 import os
+import re
 import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -114,6 +115,31 @@ def recorded_purpose(gates):
     return " ".join(b for b in bits if b)
 
 
+def _names(term, blob):
+    """Does `blob` NAME `term`? Word-START boundary for Latin, plain substring for CJK.
+
+    🔴 Naive substring matching made three of these checks VACUOUS, which is worse than having no
+    check at all — it passes every deck and teaches the reader that the gate is noise. Measured on
+    a deck containing only "Our action plan for the project", "The benefit of this approach" and
+    "This is a summary":
+
+        clinical_case/investigations   satisfied by "ct"  inside a-CT-ion / proje-CT
+        job_talk/fit                   satisfied by "fit" inside bene-FIT
+        product_pitch                  reported NOTHING missing at all
+
+    The boundary is on the START only, never the end, because several terms are deliberate
+    PREFIXES — "feasib" must match feasibility and feasible, "demo" must match demonstration. A
+    trailing boundary would silently break those, which is the same class of quiet failure.
+    A term with no letters or digits at all (`%`) has no word boundary to anchor to and falls back
+    to substring.
+    """
+    if any(ord(c) > 0x2E80 for c in term):
+        return term in blob                       # CJK has no word boundaries
+    if not any(c.isalnum() for c in term):
+        return term in blob                       # e.g. "%" — nothing to anchor
+    return re.search(r"(?<![a-z0-9])" + re.escape(term), blob) is not None
+
+
 def check(pptx, purpose_text, *, extra_terms=None, waive=None):
     """(problems, facts). problems = [(code, message), ...]. Raises when nothing binds."""
     import purposes
@@ -147,7 +173,7 @@ def check(pptx, purpose_text, *, extra_terms=None, waive=None):
         return [], facts
     for label, keys in p.required_sections:
         keys = tuple(keys) + tuple(more.get(label.lower(), ()))
-        if not any(str(k).lower() in blob for k in keys):
+        if not any(_names(str(k).lower(), blob) for k in keys):
             facts["missing"].append(label)
             problems.append((
                 "MISSING SECTION",
@@ -196,6 +222,52 @@ def _selftest():
         bad.append("the shared .deck-gates.json shape was not read")
     if purposes.match(recorded_purpose(codex)) is None:
         bad.append("the Codex evidence shape was not read")
+    # 🔴 THESE DOCS ARE HAND-COPIES OF THIS REGISTRY, AND HAND-COPIES DRIFT.
+    # Both files list the genres and their sections in prose, because that is where each runtime's
+    # agent LEARNS the genres exist — `design-by-purpose.md` on the shared path, `codex-runtime.md`
+    # on the Codex one. A genre absent from the doc its runtime reads is one that run never uses.
+    # Measured: writing that list out by hand got 1 of 12 wrong within minutes (it said "lab
+    # meeting", the colloquial trigger, where every gate message says `research_meeting`), so an
+    # agent grepping the doc for the name in its own error found nothing. Not a style check: it is
+    # the doc-vs-code drift that makes a capability invisible to whichever runtime reads that file.
+    COUNTS = {11: "eleven", 12: "twelve", 13: "thirteen", 14: "fourteen", 15: "fifteen"}
+    REF = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "references")
+    # (file, anchor, span) — an anchor bounds the check to the paragraph that makes the claim;
+    # None means the whole file is the genre reference.
+    DOCS = (("codex-runtime.md", "The deck's GENRE may declare required content", 2400),
+            ("design-by-purpose.md", None, None))
+    total = len(purposes.PURPOSES) + len(purposes.NOT_A_GENRE)
+    for fname, anchor, span in DOCS:
+        try:
+            doc = open(os.path.join(REF, fname), encoding="utf-8").read()
+            chunk = doc if anchor is None else doc[doc.index(anchor):doc.index(anchor) + span]
+        except (OSError, ValueError) as exc:
+            bad.append("could not read the genre reference in references/%s (%s) — that file is "
+                       "where one runtime learns these genres exist" % (fname, exc))
+            continue
+        para = " ".join(chunk.lower().split())
+        for p_ in purposes.PURPOSES:
+            if p_.name.replace("_", " ") not in para:
+                bad.append("references/%s never names %r — every gate message prints that exact "
+                           "name, so an agent grepping its own error finds nothing" % (fname, p_.name))
+            for lbl, _terms in p_.required_sections:
+                if lbl.lower() not in para:
+                    bad.append("references/%s omits section %r of %r — a doc that understates a "
+                               "genre's content reads as complete, which is worse than omitting it"
+                               % (fname, lbl, p_.name))
+        for _key in purposes.NOT_A_GENRE:                 # the key is a TUPLE of trigger words
+            medium = _key[0] if isinstance(_key, tuple) else _key
+            if medium not in para:
+                bad.append("references/%s never mentions %r as a DELIVERY MODE — that path would "
+                           "look like it silently checks nothing there" % (fname, medium))
+        word = COUNTS.get(total)
+        if word is None:
+            bad.append("the registry now holds %d entries, outside COUNTS in this selftest — extend "
+                       "the map so each doc's stated count keeps being checked" % total)
+        elif word not in para:
+            bad.append("references/%s does not say %r where it states its coverage, but the registry "
+                       "now holds %d entries — the stated count has gone stale" % (fname, word, total))
+
     for b in bad:
         print("  ✗", b)
     print("[purpose] selftest %s" % ("FAILED" if bad else "ok"))

skills/slide-maker/scripts/purposes.py

@@ -85,7 +85,8 @@ class Purpose:
                           "published", "achieved", "进展", "已完成", "去年")),
             ("plan", ("plan", "next", "remaining", "timeline", "roadmap", "schedule", "ahead",
                       "计划", "下一步", "时间线", "剩余")),
-            ("ask", ("advice", "guidance", "decision", "question", "input", "feedback",
+            # no bare "input": "input data" is not an ask, and the rest already cover it
+            ("ask", ("the ask", "advice", "guidance", "decision", "question", "feedback",
                      "recommend", "建议", "决策", "请教", "问题")),
         ),
         fidelity="What is NOT done yet must read as not done. A committee's value is advice on open "
@@ -101,8 +102,8 @@ class Purpose:
         binds_on=("journal club", "paper presentation", "reading group", "present a paper",
                   "discuss the paper", "文献汇报", "文献阅读", "组会读论文", "论文分享", "读书会"),
         required_sections=(
-            ("attribution", ("et al", "authors", "published in", "doi", "arxiv", "reference",
-                             "citation", "source", "作者", "发表于", "文献")),
+            ("attribution", ("attribution", "et al", "authors", "published in", "doi", "arxiv",
+                             "reference", "citation", "source", "作者", "发表于", "文献")),
             ("critique", ("limitation", "limitations", "weakness", "critique", "caveat",
                           "my take", "assessment", "concerns", "局限", "不足", "评价", "批评")),
         ),
@@ -161,7 +162,7 @@ class Purpose:
         required_sections=(
             ("contribution", ("contribution", "we propose", "our method", "this work", "novelty",
                               "我们提出", "本文", "贡献")),
-            ("evidence", ("result", "results", "evaluation", "experiment", "we evaluate",
+            ("evidence", ("evidence", "result", "results", "evaluation", "experiment", "we evaluate",
                           "benchmark", "结果", "实验", "评估")),
             ("limitations", ("limitation", "limitations", "caveat", "does not", "fails when",
                              "局限", "不足")),
@@ -177,7 +178,7 @@ class Purpose:
         binds_on=("job talk", "faculty interview", "faculty position", "tenure track",
                   "interview seminar", "求职报告", "教职面试"),
         required_sections=(
-            ("track record", ("published", "my work", "i have", "prior work", "to date",
+            ("track record", ("track record", "published", "my work", "i have", "prior work", "to date",
                               "已发表", "我的工作", "过往")),
             ("research plan", ("research plan", "next five years", "future programme", "my lab",
                                "will pursue", "agenda", "研究计划", "未来五年")),
@@ -197,7 +198,7 @@ class Purpose:
         required_sections=(
             ("the ask", ("we recommend", "the ask", "decision", "approve", "we propose", "request",
                          "建议", "决策", "请批准")),
-            ("the number", ("revenue", "cost", "roi", "budget", "headcount", "%", "growth",
+            ("the number", ("the number", "revenue", "cost", "roi", "budget", "headcount", "%", "growth",
                             "impact", "收入", "成本", "预算", "指标")),
             ("the risk", ("risk", "risks", "mitigation", "downside", "what could go wrong",
                           "assumption", "风险", "假设", "下行")),
@@ -247,8 +248,10 @@ class Purpose:
         binds_on=("product pitch", "sales deck", "product demo", "customer presentation",
                   "product launch", "go-to-market", "产品介绍", "产品发布", "销售材料", "客户演示"),
         required_sections=(
+            # 🔴 no "is a": it is not a positioning phrase, it is English. It matched "This is a
+            # summary" and made this whole section vacuous.
             ("positioning", ("for teams who", "for people who", "positioning", "we help",
-                             "is a", "designed for", "定位", "面向", "帮助"))
+                             "designed for", "built for", "helps you", "定位", "面向", "帮助"))
             ,
             ("benefits", ("benefit", "benefits", "you can", "saves", "so that", "value",
                           "outcome for you", "收益", "价值", "你可以")),
@@ -268,7 +271,9 @@ class Purpose:
         required_sections=(
             ("objectives", ("objective", "objectives", "learning goal", "by the end", "you will "
                             "be able", "what you will learn", "目标", "学习目标", "本节")),
-            ("worked example", ("example", "worked example", "let us", "walk through", "case",
+            # bare "case" is not a teaching signal ("in case", "use case", "showcase"); the
+            # distinctive words already carry it
+            ("worked example", ("example", "worked example", "let us", "walk through", "case study",
                                 "demo", "例子", "示例", "演练")),
             ("recap", ("recap", "summary", "to summarise", "to summarize", "key points",
                        "takeaway", "小结", "总结", "要点")),
@@ -279,6 +284,10 @@ class Purpose:
     ),
 )
 
+# 🔴 EVERY section's own NAME is one of its terms. Sounds obvious; five sections shipped without
+# it, and `job_talk/track record` reported MISSING on a deck whose slide said "My track record"
+# — the section's own words. A term list assembled from synonyms forgets the word it is a synonym
+# OF. `tests/test_purpose_sections.py` asserts this for every section so a new one cannot repeat it.
 BY_NAME = {p.name: p for p in PURPOSES}
 
 # 🔴 DELIVERY MODES, NOT GENRES — deliberately absent from PURPOSES, with the reason.
@@ -292,8 +301,8 @@ class Purpose:
 NOT_A_GENRE = {
     ("webinar", "online presentation", "zoom talk", "teams talk", "virtual talk", "livestream",
      "网络研讨会", "线上分享", "直播"):
-        "a webinar is a delivery MODE, not a genre — the same session can be a lecture, a product "
-        "pitch or an exec readout, and those need different content. Record the GENRE as the "
+        "the same session can be a lecture, a product pitch or an exec readout, and those need "
+        "different content. Record the GENRE as the "
         "purpose (the medium is already handled by the type floors and the safe-area rules), e.g. "
         "'a teaching webinar' or 'an investor webinar'.",
 }