@dzhechkov/p-replicator 1.5.14 → 1.5.15

package/templates/.claude/skills/goap-research-ed25519/scripts/learning_bridge.py

@@ -0,0 +1,462 @@
+#!/usr/bin/env python3
+"""
+Self-learning bridge — health-advisor learns from its own retractions, via dz.
+
+WHY A BRIDGE AND NOT AN ENGINE. The learning loop (`dz recall` / `dz teach`) is
+SQLite FTS5 + a vector tier + embeddings. Vendoring that into a content skill pack
+would not just be heavy — it would create a SECOND store, and a loop only compounds
+when recall and teach hit ONE. So harness-cli is an OPTIONAL, DETECTED dependency:
+absent, this package behaves exactly as before and says so once; present, research
+sessions start by recalling the traps already caught and end by teaching new ones.
+
+WHAT IS WORTH TEACHING HERE (the loop points, by analogy with the pipeline's own
+QE step — the moment a conclusion was WRONG is the most valuable signal there is):
+  * a retraction — a conclusion that had to be withdrawn;
+  * a population check that flipped a conclusion;
+  * a preanalytical finding that explained an alarming value;
+  * closing an open question.
+
+THE PRIVACY RULE IS AN INVARIANT, NOT A WISH.
+A lesson describes a METHOD, never a PATIENT:
+    good — "total testosterone is uninterpretable without SHBG"
+    bad  — "the patient has fasted 3 days weekly for 7 years, testosterone 8.04"
+Without this the learned store quietly becomes a medical record: it is a plain file
+on disk, it is shared across projects, and nobody consented to that. `check_lesson`
+REFUSES the second shape with a reason, so the caller must rewrite it as a method.
+
+HONEST SCOPE of that guard, stated at its real width: it enforces the SHAPE of a
+method lesson — no digits (spelled-out values included), no identifiers, lower case
+after the first word, and never a person beside a number. It is a shape detector, not
+a de-identifier. A sentence that names nobody, quotes no figure and is written in
+lower case can still describe one person; the guard cannot see that, and neither can
+any regular expression. What keeps the store clean is the shape rule PLUS the four
+teach moments, which are moments of method. The guard fails toward refusal.
+
+Usage (from a skill or by hand):
+    python3 learning_bridge.py status
+    python3 learning_bridge.py recall "transferrin saturation" [--limit 5]
+    python3 learning_bridge.py teach "<method lesson>" [--reward 0.8]
+    python3 learning_bridge.py check "<candidate lesson>"     # privacy guard only
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
+
+# The domain every lesson from this package is tagged with, and the one recall
+# boosts. One shared store, one namespace inside it.
+LEARNING_DOMAIN = "health-research"
+
+# THE WIRE CONTRACT between this bridge and `dz recall --domain`.
+#
+# The CURRENT dz ends its domain run with one of two note lines; their ABSENCE is how
+# an older CLI is detected (see recall() for why an exit code cannot do that job).
+#
+# Round 2 broke the first version of this: the marker was the bare substring `domain "`,
+# which any RECALLED LESSON could contain — `remember domain "ownership" before
+# reporting` would have certified an old CLI as boost-capable. A capability probe that
+# the payload can forge is not a probe. So the check is now anchored to the START of a
+# line AND requires one of the two full tails the renderer emits.
+#
+# These strings are pinned on the other side too: a harness-core test asserts
+# renderDomainBoostNote() still emits them, so changing the wording turns that test red
+# instead of silently switching this loop into permanent degraded mode.
+BOOST_NOTE_TAILS = (
+    "foreign-domain lessons kept (a boost, not a filter)",
+    "order unchanged, nothing was hidden",
+)
+
+
+def _boost_note_present(out: str, domain: str = LEARNING_DOMAIN) -> bool:
+    """True when THIS dz printed a real domain-boost note (not a lesson quoting one)."""
+    head = f'domain "{domain}":'
+    for line in out.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(head) and any(tail in stripped for tail in BOOST_NOTE_TAILS):
+            return True
+    return False
+
+DZ_MISSING_NOTE = (
+    "self-learning is OFF: `dz` (@dzhechkov/harness-cli) is not installed. "
+    "The package works exactly as before; install it to let research sessions recall "
+    "the traps already caught and record new ones: npm i -g @dzhechkov/harness-cli"
+)
+
+# ---------------------------------------------------------------- privacy guard
+
+# =============================================================================
+# THE GUARD IS AN ALLOWLIST, NOT A BLOCKLIST — and that is a deliberate rewrite.
+#
+# The first design listed personal-data SHAPES and refused those. A cross-model
+# review broke it in minutes, and the breakage was not a missing pattern but the
+# wrong SHAPE OF DESIGN:
+#   * one stray word laundered anything — "TSH was 8.04 mIU/L WHEN fasting" passed,
+#     because a threshold-marker exemption trusted the presence of a word to prove
+#     the number was a guideline rule;
+#   * every unit, date format, script and identifier outside the list walked
+#     through: `MRN 84729163`, `Patient John Smith has HIV`, `130 µmol/L`,
+#     `8 мая 2026`, an email, a phone number.
+# Enumerating what personal data LOOKS LIKE is an arms race whose every gap is a
+# leaked medical fact. So the rule is inverted:
+#
+#     A METHOD LESSON CARRIES NO DIGITS, NO IDENTIFIERS,
+#     AND IS WRITTEN IN LOWER CASE (acronyms excepted).
+#
+# All three clauses are properties of the ACCEPTED form. That matters: "no names" was
+# still a blocklist in disguise, because a name is any word and no list of them exists
+# — which is precisely how `John Smith has HIV` walked through round 2. "Lower case"
+# is checkable in one line and has a one-keystroke fix.
+#
+# It is almost free: "a fast lowers total testosterone by roughly a third" is a fine
+# lesson without the figure. When a number genuinely IS the knowledge (a guideline
+# threshold), the author passes --allow-numbers and takes responsibility explicitly —
+# a decision by a human, not an inference from a word.
+# =============================================================================
+
+# Any digit. Yes, any: a threshold, a dose, a year and a lab value are the same
+# character class, and no amount of context-sniffing reliably tells them apart.
+_DIGIT_RE = r"\d"
+
+# A value SPELLED OUT is still a value. Round 2 walked `John's TSH was eight point
+# zero four` through the digit rule untouched. Requiring two number-words in a row
+# (or a number-word beside "point") keeps the false-positive cost near zero: method
+# prose says "a third", "one marker", never "eight point zero four".
+_NUMBER_WORDS = (
+    "zero|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|"
+    "fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty|thirty|forty|fifty|"
+    "sixty|seventy|eighty|ninety|hundred|thousand|"
+    "ноль|один|одна|два|две|три|четыре|пять|шесть|семь|восемь|девять|десять|"
+    "двадцать|тридцать|сорок|пятьдесят|шестьдесят|семьдесят|восемьдесят|девяносто|сто|тысяч\\w*"
+)
+_SPELLED_NUMBER_RE = (
+    rf"\b(?:{_NUMBER_WORDS})\b[\s,-]+\b(?:point|целых|запятая|{_NUMBER_WORDS})\b"
+    rf"|\bpoint\b[\s,-]+\b(?:{_NUMBER_WORDS})\b"
+)
+
+# Direct identifiers — refused regardless of --allow-numbers, because no method
+# lesson needs them and every one of them is a person.
+# NOTE the per-pattern case flag. The identifier scan originally ran WITHOUT
+# IGNORECASE, so `MRN 84729163` walked straight through while the lowercase spelling
+# was caught — but the NAME pattern must stay case-SENSITIVE, since capitalisation is
+# the whole signal. One shared flag could not serve both; a test caught the gap.
+_IDENTIFIER_PATTERNS: Sequence[Tuple[str, str, bool]] = (
+    # (pattern, why, ignore_case)
+    (r"[\w.+-]+@[\w-]+\.[\w.]+", "an email address", True),
+    (r"\+?\d[\d\s().-]{7,}\d", "something shaped like a phone number", True),
+    (r"\b(mrn|снилс|полис|истори\w* болезни|medical record (no|number)|record no)\b[:\s#]*\w*",
+     "a medical-record identifier", True),
+)
+
+# THE CAPITALISATION RULE — round 2 forced this rewrite.
+#
+# The previous pattern hunted a NAME: two capitalised words in a row, exempting the
+# start of a sentence. Both halves were wrong, and both were measured:
+#   * `John Smith has HIV`   passed — the exemption fired on the sentence start;
+#   * `Patient John has HIV` passed — only one capitalised word followed "Patient".
+# Hunting names is a blocklist wearing an allowlist's clothes: a name is any word,
+# and there is no list of them. So stop hunting names and state a property of the
+# ACCEPTED form instead:
+#
+#     A METHOD LESSON IS WRITTEN IN LOWER CASE (acronyms excepted).
+#
+# Any capitalised word after the first token is refused, whatever it is. This does
+# refuse `compare Testosterone Replacement Therapy against placebo` — deliberately.
+# The fix is one keystroke ("lower-case it"), the rule is one sentence, and the
+# false-negative it closes is a named person beside a diagnosis.
+#
+# ROUND 3 forced this one step further, and the finding was the DESIGN again, not the
+# pattern. `\b[A-ZА-Я][a-zа-я]{2,}\b` is still a blocklist: it enumerates which
+# capitalised words look like names, so `Li` (too short), `Élodie` (Latin-1 letter)
+# and `method—John` (em dash, no \s before it) all walked through. Every round of
+# widening the pattern buys one more round.
+#
+# So the check moves to the TOKEN and states what is ACCEPTED, in a form with no
+# residue: split on whitespace, strip surrounding punctuation, and accept a token only
+# if it is one of
+#   * all lower case (letters, any script — `.islower()` answers for every alphabet);
+#   * an ACRONYM — two or more upper-case letters in it (SHBG, HIV, apoB, HbA1c);
+#   * pure punctuation, or the FIRST token of the lesson (an ordinary sentence start);
+#   * a NUMBER, judged by the number rules below.
+# `John`, `Li`, `Élodie`, `Testosterone` each carry exactly one capital and are refused
+# without the guard ever asking what they mean — which is the point, since names cannot
+# be enumerated and lower-casing costs one keystroke.
+_TOKEN_EDGE_PUNCT = " \t\n\r.,;:!?()[]{}\"'«»„“”‘’—–-/\\|*_`"
+
+
+def _is_acronym(token: str) -> bool:
+    """Two or more capitals in one token: SHBG, HIV, apoB, HbA1c. A name has one."""
+    return sum(1 for ch in token if ch.isupper()) >= 2
+
+
+# Splitting on whitespace ALONE was the last hole round 3 found: `method—John has HIV`
+# passed because the em dash kept `method—John` as ONE token, and that token was first,
+# so it took the sentence-start exemption. Any punctuation that can JOIN two words is a
+# token boundary. A period is a boundary only between non-digits, so `8.04` survives.
+_TOKEN_SPLIT_RE = r"(?:[\s—–/\\|()\[\]{}<>\"«»„“”‘’\',;:!?*_`]|(?<!\d)[.](?!\d))+"
+
+
+def _tokens(raw: str) -> List[str]:
+    return [t.strip(_TOKEN_EDGE_PUNCT) for t in re.split(_TOKEN_SPLIT_RE, raw) if t.strip(_TOKEN_EDGE_PUNCT)]
+
+
+# A token that mixes letters and digits is an IDENTIFIER SHAPE — `ab1234567`,
+# `NCT04368728`, an accession, a record number. It is refused even under
+# --allow-numbers, because that flag exists for a THRESHOLD (`8.04`, `56h`), and a
+# threshold is a number with at most a short unit after it. Letters BEFORE digits is
+# not a measurement in any unit system; it is a label for one thing.
+_NUMBER_TOKEN_RE = r"^[<>≥≤~±]?\d+([.,]\d+)?[a-zа-яё%°]{0,4}$"
+
+# A reference to ONE person. Alone it is fine — a method sentence may discuss patients
+# in the abstract. Beside a value it is load-bearing: a person plus a reading is a
+# record, and no --allow-numbers waves that through.
+#
+# SINGULAR ONLY, and that is the whole design. Round 3 was right that `the woman has
+# tsh 8.04` must be refused, but the first fix simply added `woman|man|adult|child` and
+# immediately refused `transferrin saturation above 45% warrants attention in men` — a
+# textbook population lesson. Plural person nouns ARE the vocabulary of method lessons
+# about populations; singular ones are the vocabulary of case notes. Number, not word
+# list, is what separates a cohort from a patient, and grammar is checkable.
+#
+# Honest scope: `the woman` is caught, `a 54 year old` is not, and this clause only ever
+# runs when --allow-numbers was passed (digits are refused outright otherwise). It is
+# the narrowest of the three clauses and the only one that is still an enumeration.
+_PERSON_RE = (
+    r"\b(patient|subject|participant|client|donor|volunteer|"
+    r"woman|man|individual|child|infant|adult|"
+    r"he|she|him|his|her|hers|"
+    r"пациент(?!ы|ов|ам|ами|ах)\w*|больн(ой|ого|ому|ым|ом)|испытуем(ый|ого|ому|ым|ом)|"
+    r"мужчина|мужчины\b|женщина|женщины\b|ребёнок|ребенок|доброволец|"
+    r"у него|у неё)\b"
+)
+
+@dataclass(frozen=True)
+class LessonVerdict:
+    ok: bool
+    reasons: List[str]
+
+    @property
+    def note(self) -> str:
+        if self.ok:
+            # NOT "safe": a shape detector cannot certify safety, and saying so would
+            # transfer responsibility it does not have (Codex QE #2). It reports the
+            # absence of a detected shape — the author still owns the content.
+            return (
+                "no personal-data SHAPE detected (no digits, no identifiers, lower case). This is "
+                "not a safety certificate: the guard checks shapes, not meaning — a lower-case "
+                "sentence with no figures can still describe one person, and you remain "
+                "responsible for what it says."
+            )
+        return "REFUSED — this reads like a record about a person, not a method:\n  - " + "\n  - ".join(self.reasons)
+
+
+def check_lesson(text: str, allow_numbers: bool = False) -> LessonVerdict:
+    """Refuse anything not shaped like a METHOD lesson. Fails toward refusal.
+
+    `allow_numbers` is an EXPLICIT human decision for the case where a number IS the
+    knowledge (a guideline threshold). It is a flag a person passes, never something
+    inferred from the presence of a word — inferring it is exactly how the first
+    design was laundered ("TSH was 8.04 mIU/L WHEN fasting" passed because "when"
+    was read as a threshold marker).
+
+    The right response to a refusal is to rewrite the lesson as the rule it taught,
+    which is also the more useful form: a reading helps once, a rule helps every time.
+    """
+    raw = text or ""
+    if not raw.strip():
+        return LessonVerdict(False, ["the lesson is empty"])
+    reasons: List[str] = []
+
+    # Identifiers with a fixed shape (email, phone, medical-record vocabulary) are
+    # refused ALWAYS — --allow-numbers must not reach them. This list is genuinely a
+    # blocklist and is NOT the guard's backbone: the token allowlist below is what
+    # catches identifier shapes the list never heard of.
+    for pattern, why, ignore_case in _IDENTIFIER_PATTERNS:
+        flags = re.UNICODE | (re.IGNORECASE if ignore_case else 0)
+        if re.search(pattern, raw, flags=flags):
+            reasons.append(why)
+
+    tokens = _tokens(raw)
+    for index, token in enumerate(tokens):
+        has_digit = any(ch.isdigit() for ch in token)
+        has_alpha = any(ch.isalpha() for ch in token)
+        if has_digit and has_alpha and not re.match(_NUMBER_TOKEN_RE, token):
+            reasons.append(
+                f"{token!r} mixes letters and digits — that is the shape of an identifier "
+                "(a record number, an accession, a passport), not of a measurement, and no "
+                "flag accepts it"
+            )
+            break
+        if has_digit or not has_alpha:
+            continue  # numbers are judged below; punctuation-only tokens carry nothing
+        if index == 0:
+            continue  # an ordinary sentence start
+        if token.islower() or _is_acronym(token):
+            continue
+        reasons.append(
+            f"a capitalised word ({token!r}) after the first one — a method lesson is written "
+            "in lower case, because one capital is the shape of a name and names cannot be "
+            "listed. Lower-case it (acronyms like SHBG, TSH or apoB carry two capitals and pass)"
+        )
+        break
+
+    spelled = re.search(_SPELLED_NUMBER_RE, raw, flags=re.IGNORECASE | re.UNICODE)
+    has_digits = re.search(_DIGIT_RE, raw) is not None or spelled is not None
+    if has_digits and not allow_numbers:
+        reasons.append(
+            "the lesson contains digits — a method lesson rarely needs them, and a number is where "
+            "readings hide. Rewrite it without the figure, or pass --allow-numbers if the number IS "
+            "the knowledge (a guideline threshold) and you take responsibility for it"
+            + (f" (spelled out, but still a value: {spelled.group(0)!r})" if spelled else "")
+        )
+
+    # A person beside a value is a RECORD — even under an explicit --allow-numbers.
+    # Note the widened trigger: ANY single number word counts here, not just the
+    # two-word sequences that read as a value on their own. `one marker` alone is
+    # ordinary method prose; `his tsh was twelve` is a reading about a human being,
+    # and round 3 walked it through because a lone number word was not a "number".
+    lone_number_word = re.search(rf"\b(?:{_NUMBER_WORDS})\b", raw, flags=re.IGNORECASE | re.UNICODE)
+    carries_value = has_digits or lone_number_word is not None
+    if carries_value and re.search(_PERSON_RE, raw, flags=re.IGNORECASE | re.UNICODE):
+        reasons.append(
+            "a person is referred to alongside a number — that is a record about someone, "
+            "and no flag makes it a method"
+        )
+    return LessonVerdict(not reasons, reasons)
+
+
+# ---------------------------------------------------------------- dz detection
+
+def dz_path() -> Optional[str]:
+    """Absolute path to `dz`, or None. Detection only — never installs anything."""
+    return shutil.which("dz")
+
+
+def _run_dz(args: Sequence[str], timeout: int = 60) -> Tuple[int, str, str]:
+    exe = dz_path()
+    if exe is None:
+        return 127, "", DZ_MISSING_NOTE
+    try:
+        proc = subprocess.run([exe, *args], capture_output=True, text=True, timeout=timeout, check=False)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return 1, "", f"dz call failed: {exc}"
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+def status() -> str:
+    exe = dz_path()
+    if exe is None:
+        return DZ_MISSING_NOTE
+    code, out, _ = _run_dz(["recall", "--all", "--stats"], timeout=90)
+    if code != 0:
+        return f"dz found at {exe}, but the learned store is not readable yet — teach the first lesson to create it."
+    total = out.splitlines()[0] if out else ""
+    return f"self-learning ON via {exe}\n  {total.strip()}\n  lessons from this package are tagged domain={LEARNING_DOMAIN}"
+
+
+def recall(query: str, limit: int = 5) -> str:
+    """Recall traps already caught. Absent dz is a NOTE, never a failure — a research
+    session must not depend on an optional dependency.
+
+    There is exactly ONE call, and no retry — an earlier version of this docstring
+    promised a fallback call that the code never made (round 2 caught the prose, not
+    the code, lying). No retry is needed: an older `dz` does not REJECT `--domain`, it
+    ignores the flag and exits 0 with unranked results, so the single call already
+    returns everything an unflagged one would. What the older CLI cannot do is print
+    the boost note — which is why detection reads the OUTPUT, not the exit code.
+
+    A non-zero exit is a different thing entirely and is reported as itself: recall is
+    unavailable and the session proceeds WITHOUT prior lessons. It is never reported as
+    "your CLI is old", because that would be a guess about the cause.
+    """
+    if query.startswith("--"):
+        # ARGUMENT injection, not shell injection: the query lands in argv, and a leading
+        # `--` makes the child parser read it as an option — recall("--all") would dump
+        # the entire learned store. Shell quoting does not help; this does.
+        #
+        # Only `--` is refused, not a single dash. Round 2 measured that `dz` treats
+        # `-contrast` as an ordinary positional argument, so refusing it blocked
+        # legitimate text ("-contrast", "-negative findings") to defend against nothing.
+        # A guard that refuses safe input teaches people to work around the guard.
+        return "refusing a query that starts with '--': it would be read as an option by dz, not as text"
+
+    code, out, err = _run_dz(["recall", query, "--domain", LEARNING_DOMAIN, "--limit", str(limit)])
+    if code == 127:
+        return err
+    if code != 0:
+        return f"recall unavailable ({err.strip() or 'unknown error'}) — proceeding WITHOUT prior lessons"
+
+    # CAPABILITY, not exit code (Codex QE #3 — the sharpest finding of the round).
+    # The PREVIOUS dz did not reject `--domain`: its parser accepted any `--key value`
+    # and cmdRecall simply ignored it, exiting 0 with UNFILTERED results. So an
+    # error-code test could never fire, and my own test had FABRICATED the failure it
+    # was checking — modelling a version that never existed. The observable difference
+    # is the boost note the new CLI prints; its absence is what "too old" looks like.
+    if not _boost_note_present(out):
+        return out.rstrip() + (
+            "\n  note: this dz ranked WITHOUT the domain boost (the installed CLI predates "
+            "`dz recall --domain`, which ignores the flag silently rather than failing) — results "
+            "may mix other domains. Upgrade: npm i -g @dzhechkov/harness-cli"
+        )
+    return out.rstrip() or "no prior lessons matched — this is new ground"
+
+
+def teach(lesson: str, reward: float = 0.8, allow_numbers: bool = False) -> Tuple[int, str]:
+    """Record a METHOD lesson. The privacy guard runs FIRST and can refuse."""
+    if lesson.startswith("--"):
+        return 1, "refusing a lesson that starts with '--': dz would read it as an option, not as text"
+    verdict = check_lesson(lesson, allow_numbers=allow_numbers)
+    if not verdict.ok:
+        return 1, verdict.note + (
+            "\n\nRewrite it as the general rule it taught. The method form is also the more useful "
+            "lesson: a reading helps once, a rule helps every time."
+        )
+    code, out, err = _run_dz([
+        "teach", lesson, "--reward", str(float(reward)), "--domain", LEARNING_DOMAIN, "--type", "lesson-learned",
+    ])
+    if code == 127:
+        return 0, err  # not an error: the package works without dz
+    if code != 0:
+        return 1, f"teach failed: {err.strip() or out.strip()}"
+    return 0, f"recorded (domain={LEARNING_DOMAIN})"
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="health-advisor ⇄ dz self-learning bridge")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("status")
+    p_recall = sub.add_parser("recall")
+    p_recall.add_argument("query")
+    p_recall.add_argument("--limit", type=int, default=5)
+    p_teach = sub.add_parser("teach")
+    p_teach.add_argument("lesson")
+    p_teach.add_argument("--reward", type=float, default=0.8)
+    p_teach.add_argument("--allow-numbers", action="store_true",
+                         help="the number IS the knowledge (a guideline threshold) — an explicit human decision")
+    p_check = sub.add_parser("check")
+    p_check.add_argument("lesson")
+    p_check.add_argument("--allow-numbers", action="store_true")
+    args = parser.parse_args(argv)
+
+    if args.cmd == "status":
+        print(status())
+        return 0
+    if args.cmd == "recall":
+        print(recall(args.query, args.limit))
+        return 0
+    if args.cmd == "check":
+        verdict = check_lesson(args.lesson, allow_numbers=args.allow_numbers)
+        print(verdict.note)
+        return 0 if verdict.ok else 1
+    code, message = teach(args.lesson, args.reward, allow_numbers=args.allow_numbers)
+    print(message)
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/.claude/skills/goap-research-ed25519/scripts/source_tiers.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""
+Source-class tiers and staleness — the THIRD ceiling (FR-5, FR-6).
+
+Before this, every fact carried trust_class=SELF_ATTESTED with a flat 0.60 cap,
+so a Cochrane meta-analysis and a forum post were indistinguishable by that field.
+Tiering by source CLASS is imperfect but incomparably more useful than flat.
+
+What a tier is NOT: it is not a cryptographic statement about the issuer, and it
+must never be confused with issuer key pinning (the `whitelist_available` defect
+fused exactly these two ideas and made high-stakes modes unreachable). A tier is
+a claim about the class a domain belongs to. Nothing more.
+
+Ceilings compose as a MINIMUM with the other two axes — the weakest link decides:
+    confidence = min(trust_ceiling, evidence_ceiling, tier_ceiling)
+
+Data lives in TIER_DOMAINS below rather than in a config file on purpose: this is
+a small, reviewable, version-controlled list, and a medical package should not
+silently pick up trust rules from an unversioned file on disk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Dict, Optional, Tuple
+from urllib.parse import urlparse
+
+TIER_A = "A"  # guideline bodies, national registries, systematic-review orgs
+TIER_B = "B"  # peer-reviewed literature
+TIER_C = "C"  # preprints, trial registries
+TIER_D = "D"  # secondary reviews, media, forums, unknown
+
+TIER_CEILINGS: Dict[str, float] = {TIER_A: 0.90, TIER_B: 0.80, TIER_C: 0.60, TIER_D: 0.40}
+
+# Suffix match on the registrable host: "www.cochrane.org" and "x.cochrane.org"
+# both match "cochrane.org", while "cochrane.org.evil.com" does NOT (see _host_matches).
+TIER_DOMAINS: Dict[str, str] = {
+    # A — guidelines, registries, HTA/【systematic review】 bodies
+    "cochrane.org": TIER_A,
+    "cochranelibrary.com": TIER_A,
+    "who.int": TIER_A,
+    "nice.org.uk": TIER_A,
+    "uspreventiveservicestaskforce.org": TIER_A,
+    "escardio.org": TIER_A,
+    "diabetes.org": TIER_A,
+    "acc.org": TIER_A,
+    "ahajournals.org": TIER_A,
+    "cdc.gov": TIER_A,
+    "nih.gov": TIER_A,
+    "fda.gov": TIER_A,
+    "ema.europa.eu": TIER_A,
+    # B — peer-reviewed literature
+    "pubmed.ncbi.nlm.nih.gov": TIER_B,
+    "ncbi.nlm.nih.gov": TIER_B,
+    "doi.org": TIER_B,
+    "nejm.org": TIER_B,
+    "thelancet.com": TIER_B,
+    "bmj.com": TIER_B,
+    "jamanetwork.com": TIER_B,
+    "sciencedirect.com": TIER_B,
+    "springer.com": TIER_B,
+    "wiley.com": TIER_B,
+    "nature.com": TIER_B,
+    # C — preprints and registries (registered ≠ peer-reviewed ≠ completed)
+    "medrxiv.org": TIER_C,
+    "biorxiv.org": TIER_C,
+    "clinicaltrials.gov": TIER_C,
+    "osf.io": TIER_C,
+}
+# NOTE: keys are HOSTS only. A path-scoped rule ("who.int/trialsearch": C) is DEAD
+# here — classify_source matches on hostname, so such a key can never fire and the
+# URL silently inherits its host's tier (Codex QE #13). Path-scoped tiering needs a
+# different matcher; until it exists, we do not pretend to have it.
+
+# Freshness TTLs in days, by topic kind. A source older than its TTL is flagged
+# `may_be_stale` — a flag, never a silent drop: an old guideline is still the
+# guideline until a newer one is found.
+TTL_DAYS: Dict[str, int] = {
+    "guideline": 365 * 2,
+    "registry": 180,
+    "meta_analysis": 365 * 2,
+    "trial": 365 * 3,
+    "price": 7,
+    "news": 30,
+    "default": 365,
+}
+
+
+@dataclass(frozen=True)
+class TierVerdict:
+    tier: str
+    ceiling: float
+    matched_domain: Optional[str]
+    known: bool
+
+
+def _registrable_candidates(host: str) -> Tuple[str, ...]:
+    """Progressive suffixes of the host, longest first: a.b.c → (a.b.c, b.c, c).
+
+    Matching on suffix LABELS (not raw string endswith) is what stops
+    `cochrane.org.evil.com` from inheriting tier A.
+    """
+    labels = [label for label in host.split(".") if label]
+    return tuple(".".join(labels[i:]) for i in range(len(labels)))
+
+
+def _host_matches(host: str) -> Optional[str]:
+    for candidate in _registrable_candidates(host):
+        if candidate in TIER_DOMAINS:
+            return candidate
+    return None
+
+
+def classify_source(url: str) -> TierVerdict:
+    """Tier for a URL. An UNKNOWN domain gets tier D — the most cautious class,
+    not an exception and not a free pass. Unknown is a state, not an error."""
+    try:
+        parsed = urlparse(url)
+        host = (parsed.hostname or "").lower()
+        scheme = (parsed.scheme or "").lower()
+    except Exception:
+        host, scheme = "", ""
+    # file://who.int/... must not read as tier A: a tier is a claim about a WEB
+    # source class, and a local path is not one (Codex QE #13).
+    if scheme not in ("http", "https"):
+        return TierVerdict(tier=TIER_D, ceiling=TIER_CEILINGS[TIER_D], matched_domain=None, known=False)
+    if not host:
+        return TierVerdict(tier=TIER_D, ceiling=TIER_CEILINGS[TIER_D], matched_domain=None, known=False)
+    matched = _host_matches(host)
+    if matched is None:
+        return TierVerdict(tier=TIER_D, ceiling=TIER_CEILINGS[TIER_D], matched_domain=None, known=False)
+    tier = TIER_DOMAINS[matched]
+    return TierVerdict(tier=tier, ceiling=TIER_CEILINGS[tier], matched_domain=matched, known=True)
+
+
+def _parse_date(value: str) -> Optional[datetime]:
+    raw = value.strip().replace("Z", "+00:00")
+    for parse in (
+        lambda v: datetime.fromisoformat(v),
+        lambda v: datetime.strptime(v, "%Y-%m-%d"),
+        lambda v: datetime.strptime(v, "%Y"),
+    ):
+        try:
+            parsed = parse(raw)
+            return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+        except (ValueError, TypeError):
+            continue
+    return None
+
+
+def is_stale(source_date: Optional[str], kind: str = "default", now: Optional[datetime] = None) -> Tuple[bool, str]:
+    """(stale?, reason). An ABSENT date is reported as unknown-and-therefore-flagged:
+    the report author must not be able to dodge the freshness question by omitting
+    the field — that is how "is the Turkish ban still in force?" went wrong."""
+    ttl = TTL_DAYS.get(kind, TTL_DAYS["default"])
+    if not source_date:
+        return True, "source_date missing — freshness cannot be established"
+    parsed = _parse_date(source_date)
+    if parsed is None:
+        return True, f"source_date {source_date!r} is unparseable — freshness cannot be established"
+    reference = now or datetime.now(timezone.utc)
+    age_days = (reference - parsed).days
+    if age_days < 0:
+        # A source dated in the future is not "fresh forever" — it is a data error,
+        # and treating it as fresh made 2099 an eternal pass (Codex QE #14).
+        return True, f"source_date {source_date!r} is in the future ({-age_days}d ahead) — implausible"
+    if age_days > ttl:
+        return True, f"source is {age_days}d old, past the {ttl}d TTL for kind={kind}"
+    return False, f"source is {age_days}d old, within the {ttl}d TTL for kind={kind}"