merge: cohort survey + denominator fix into main (ADR-0006/0007)

origin/main had moved 10 commits ahead (ADR-0006 join contract, ADR-0007
re-curation cadence + weekly freshness job, machine-API auth diagnosis).

Conflicts, and how they were resolved:

- variant_status.py — both sides added fields to StatusMatrix. Additive, so
both kept: genes_assayed + profiled (this branch) alongside curation
(ADR-0007). Fields regrouped ahead of the methods; a field declared after a
method is legal but reads as an accident.
- TODO.md / memory.md — both appended dated 2026-07-28 entries. Kept both in
chronological order. Dropped main's placeholder "curate more PDAC studies"
and this branch's stale "re-curation cadence" placeholder, each superseded
by the other side's completed item.

ALL SIX ARTIFACTS RE-CURATED, not merged textually. The four pre-existing ones
had been overwritten by this branch (dropping ADR-0007's source_import_date)
and then textually auto-merged back by git. That produced plausible JSON, but
a semantically-merged data file nobody generated is not evidence of anything —
and the two NEW cohorts genuinely lacked source_import_date, which would have
left them permanently drift_comparable:false, i.e. silently exempt from the
freshness check they most needed. Regenerating on the merged code is the only
way the artifacts provably match it.

Verified: all six carry schema v3 + profiled + source_import_date, and
`python -m src.curate --check` now reports six cohorts up_to_date and
drift-comparable (exit 0). ADR-0007's freshness machinery works over
list_curated(), so the two new cohorts were picked up with no change to it.

Left ADR-0007's "Four cohorts are curated today" untouched — that is a
point-in-time observation in an accepted ADR's Context, not a live list.

Tests: 153 pass (136 from this branch + 17 from main).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.github/workflows/curation-freshness.yml

@@ -0,0 +1,61 @@
+# ADR-0007 — weekly curated-artifact freshness check.
+#
+# Runs `python -m src.curate --check`: one `/studies/<id>` metadata request per curated study,
+# comparing upstream's `importDate` against the `source_import_date` recorded at curation. It
+# REPORTS; it never re-curates. Re-curation stays a reviewed commit — a job that "fixed" what it
+# found would put the cBioPortal API back on an unattended path, which is what ADR-0005 C4 removed.
+#
+# ---------------------------------------------------------------------------------------------
+# READ THIS BEFORE TRUSTING THIS FILE: it does NOT run today.
+#
+# This repo's `origin` IS the HuggingFace Space (`git push origin main` builds the Space), and
+# HuggingFace does not execute GitHub Actions. Unlike its siblings — `DecoupleRpy_Agent`,
+# `pdac-subtype-agent`, `pdac-analysis-orchestrator`, which each carry a second `github` remote —
+# this repo has **no GitHub mirror**, so nothing schedules this workflow. It is committed anyway
+# for the same reason `DecoupleRpy_Agent/.github/workflows/security.yml` is: adding the mirror
+# becomes zero extra work, and the check's definition never diverges between the two paths.
+#
+# To make it actually run, add the mirror (matching the sibling naming):
+#   git remote add github https://github.com/Anne-Voigt/pdac-genomics-agent.git
+#   git push github main
+#
+# Until then, the check is a manual command — `python -m src.curate --check` — or a local
+# scheduler; see `docs/adr/ADR-0007-recuration-cadence.md` § "Running the check".
+# ---------------------------------------------------------------------------------------------
+name: curation-freshness
+
+on:
+  schedule:
+    # Weekly, Monday 07:00 UTC — an hour after the sibling security scan so the two unattended
+    # jobs don't report at once. Weekly is the right granularity for a signal that moved twice
+    # in the last year: it is four metadata requests, and drift is never urgent (a stale cohort
+    # keeps answering, and says its age).
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"   # matches `python_version` in the README front-matter
+
+      - name: Install deps
+        # The whole pinned set rather than a hand-picked subset: `src.curate` imports the
+        # curation chain (pandas, scipy), and a second dependency list is a second thing to
+        # drift.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Check curated-artifact freshness
+        # Exits 1 on upstream drift or an artifact past the 365-day horizon. That failure is the
+        # notification — it means "a human should look and decide", never "the Space is broken".
+        # The deployed Space is unaffected either way: it serves artifacts, not this job.
+        run: python -m src.curate --check

CLAUDE.md

@@ -136,6 +136,9 @@ tests/
 - **ADR-0005** — public cBioPortal instance + **curate-and-cache** for v1 (no self-host); its
   conditions C1–C4 are the standing obligations on the source (attribution, per-study license,
   polite client, no live API on the request path).
+- **ADR-0007** — re-curation cadence: drift is detected from upstream's `importDate`
+  (`python -m src.curate --check`, one metadata request per study, never writes), artifact age
+  rides in every answer's `citation.curation` block, and staleness is **visible, never a refusal**.
 - Originating decision: `pdac-subtype-agent` **ADR-0019** (scope, data model, sources, panel) +
   `SPIKE-dna-panel-feasibility.md` (cBioPortal proven).
 

TODO.md

@@ -73,27 +73,58 @@ the design doc's M0–M4 is the intent behind it — see that doc's §0).
       **`ACCESS_CONTROL=enforce` flipped 2026-07-27** (set as a *variable*, not a secret: it is not
       sensitive, and an auditor should be able to see the gate is on without revealing a secret).
       Verified live: the machine API now returns `denied` — fail-closed, as designed.
-      - [ ] **`ALLOWED_IDS` is still unset.** Right now **only `anne-voigt` can use the Space.**
-            Needs the HF usernames of the lab members who should have access — a membership
-            decision, and guessing usernames would either lock out real people or grant access to
-            accounts that are not theirs.
-      - [ ] **Verify the OAuth UI path while signed in.** The machine-API denial is confirmed; the
-            *allowed* path is not. Sign in to the Space and run one query. If the owner is denied,
-            roll back by setting `ACCESS_CONTROL` to empty (gate off) and investigate.
-      - [ ] **Machine API is now closed to the orchestrator** until it sends a custom
-            `x-orchestrator-token` whose identity is allow-listed — HF edge strips the `x-hf-*`
-            header `gradio_client` sends automatically. Expected, not a regression.
+      - [x] **`ALLOWED_IDS` set** ✅ 2026-07-27 — `anne-voigt,cpelz741` (Carl), mirroring
+            `pdac-subtype-agent` prod rather than guessing an id.
+      - [x] **OAuth UI path VERIFIED signed in** ✅ 2026-07-27 — signed in as `anne-voigt`, ran a
+            CCLE query in the deployed UI: chart rendered (KRAS ~84% of 57 pancreatic lines) and the
+            licence caution displayed. Signed-out the same query correctly returns
+            `{"status":"denied"}`. Both halves of the gate now confirmed in the UI.
+      - [x] **Machine API DIAGNOSED — this Space was never broken** ✅ (2026-07-28). Probed the
+            deployed Space directly: a valid token in `x-orchestrator-token` → `status: ok`;
+            a bogus one → denied; none → denied. The gate resolves `whoami` correctly from
+            inside the Space. **The earlier "server-side identity resolution" diagnosis was
+            wrong.** Root cause is caller-side: `router._build_client_kwargs()` attaches the
+            header **only if `HF_TOKEN` is set**, so an unset secret on the *orchestrator's*
+            Space sends no header at all — which this Space reported as "Please sign in",
+            pointing the investigation the wrong way.
+      - [ ] ⚠️ **ACTION (human, on the ORCHESTRATOR Space, not this one): set `HF_TOKEN`** in
+            `pdac-analysis-orchestrator` prod Space secrets. Nothing to change here.
+      - [x] **Denial diagnosis added** ✅ (2026-07-28) — machine denials now carry
+            `machine_auth: no_token_header | token_unresolved | not_allowlisted` with a message
+            naming the side that must act (never "sign in" to a machine). 4 regression tests.
+      - [ ] Open design question, unchanged: should the gate depend on an outbound `whoami` per
+            request at all (vs a shared secret)? Same request-path-coupling class as ADR-0005 C4.
+            Not urgent — it works; it is a latency/failure-mode question.
 - [x] **Confirm cBioPortal ToS for automated use; public instance vs self-host** ✅ (2026-07-24) →
       `docs/cbioportal-terms-and-deployability.md` + **ADR-0005**. Verdict: usable with conditions,
       no ToS bar on automated access, **public instance + curate-and-cache, no self-host**.
       Remaining is *implementation* of conditions C1–C4 (attribution, per-study license flag, polite
       client, no live API on the request path) — see "Pre-deploy gates" below.
-- [ ] Merge the registration descriptor into `pdac-analysis-orchestrator`'s `agents.yaml`.
+- [~] Merge the registration descriptor into `pdac-analysis-orchestrator`'s `agents.yaml` —
+      **spun off and in progress** in that repo (`dispatch_kind: tool_server`, modelled on its
+      existing `pdac_subtype_agent` entry). Its auth is already in place: that repo sends
+      `x-orchestrator-token` (its `05bda30`) resolving to `anne-voigt`, who is allow-listed here,
+      and the pattern is verified working against prod.
 
 ## Later
 
-- [ ] **Re-curation cadence** — artifacts are a point-in-time snapshot (`curated_at` in each file).
-      Decide when they get refreshed and how a stale one is noticed; nothing warns today.
+- [x] **Re-curation cadence** ✅ 2026-07-28 — **ADR-0007**. Cadence is driven by upstream's
+      `importDate`, not a calendar: `python -m src.curate --check` costs one metadata request per
+      study, reports drift + age, exits non-zero for CI, and **never writes** (re-curation stays a
+      reviewed commit). Artifact age rides in every answer (`citation.curation`) and on the page
+      past 180d/365d horizons. **Stale is visible, never a refusal** — old is not wrong. Confirmed
+      the premise while building: all four cohorts last imported upstream Jan 2026, curated Jul —
+      a monthly refresh would have been pure churn. Follow-ups below.
+- [~] **Weekly `--check` job** — written 2026-07-28: `.github/workflows/curation-freshness.yml`
+      (Mondays 07:00 UTC + `workflow_dispatch`, report-only, exits non-zero on drift/stale; a test
+      asserts it can never gain a writing `src.curate` step). **It does not run yet** and the file
+      says so: `origin` IS the HF Space and HuggingFace does not execute GitHub Actions, and unlike
+      every sibling this repo has **no `github` remote**. Committed anyway on the
+      `DecoupleRpy_Agent/security.yml` precedent, so adding the mirror is the only step left.
+- [ ] **Add the GitHub mirror** — the one ops action that turns the weekly check on (and would give
+      this repo CI at all, which it has never had):
+      `git remote add github https://github.com/Anne-Voigt/pdac-genomics-agent.git && git push github main`.
+      Needs a human: creating the repo under the org. Until then `--check` is a manual command.
 - [x] **Tumor cohorts beyond cell lines** ✅ (2026-07-28) — full survey of all 538 cBioPortal
       studies; **+2 curated, 6 total**: `pancreas_cptac_gdc` (183, mut+CNV+expr, GRCh38) and
       `pdac_msk_2024` (2,336, mut+CNV, the largest PDAC cohort available). Driver frequencies
@@ -164,8 +195,12 @@ the design doc's M0–M4 is the intent behind it — see that doc's §0).
             an uncurated study is a **refusal**, never a live fetch. Four cohorts curated and
             committed (paad_tcga, ccle_broad_2019, paad_qcmg_uq_2016, paad_utsw_2015). Proven by
             a test that sabotages the HTTP layer and still answers.
-- [ ] Write the **variant×subtype join-contract ADR** (see `RESERVED.md`) — the label-join half is
-      built; the orchestrator-side contract is undocumented.
+- [x] Write the **variant×subtype join-contract ADR** ✅ (2026-07-28) →
+      `docs/adr/ADR-0006-variant-subtype-join-contract.md`. Settles the split (label-join here /
+      live-PurIST via the orchestrator), the routing contract + the orchestrator's obligations,
+      subtype-label VALUE validation against a closed vocabulary (the CCLE histology trap), the
+      statistical-honesty stance (no cross-gene correction, `testable=false` + reason, small-n
+      caveats), and metadata-label vs live-PurIST provenance. No behaviour change.
 
 ## Open questions
 
@@ -173,7 +208,11 @@ the design doc's M0–M4 is the intent behind it — see that doc's §0).
   (private, empty, no deploy; `origin` not yet pointed at it — wire up at first deploy).
 - ~~cBioPortal public instance vs self-host~~ **RESOLVED 2026-07-24** — public + curate-and-cache,
   no self-host (ADR-0005).
-- Does the orchestrator align sample ids across two Spaces cleanly, or does the join need a shared id map?
+- Does the orchestrator align sample ids across two Spaces cleanly, or does the join need a shared id
+  map? **Still open — deliberately** (ADR-0006 §2). The spike's 145/146 was *within* one cBioPortal
+  cohort, not the cross-Space case that would need a map. Interim rule is written down: exact
+  sample-id string equality, report join coverage, no fuzzy/prefix matching, and a collapsed join is
+  a refusal with the numbers shown. Resolving it amends ADR-0006 §2; it does not reopen the split.
 - Does the orchestrator cache a fetched subtype label per session, or re-call PurIST per join?
   (Belongs to `pdac-analysis-orchestrator`, not here.)
 - Should this agent ever route through `biodata-registry`, or stay a direct-source agent? The

docs/adr/ADR-0005-cbioportal-public-vs-selfhost.md

@@ -61,6 +61,10 @@ exponential backoff + jitter on `429`/`5xx`, and a descriptive `User-Agent` with
   change on their side can break an ingest run (fail loud, don't serve partial).
 - Cached matrices can drift from upstream until we deliberately re-curate (acceptable — variant
   *status* over a driver panel is stable; invalidation is a deliberate re-pull, not a poll).
+  **Superseded in part by ADR-0007 (2026-07-28):** "a deliberate re-pull" was a mechanism, not a
+  policy — nothing said *when*, and nothing read `curated_at`. ADR-0007 fixes the cadence to
+  upstream's `importDate` (`--check`), surfaces artifact age in every answer, and rules that
+  staleness is visible but never a refusal. The re-pull stays deliberate and reviewed.
 
 **Neutral**
 - No change to the tool contracts or the data model; this is purely a source-dependency decision.

docs/adr/ADR-0006-variant-subtype-join-contract.md

@@ -0,0 +1,260 @@
+# ADR-0006 — The variant×subtype join contract: label-join here, live-PurIST join in the orchestrator
+
+**Status:** Accepted · **Date:** 2026-07-28 · **Deciders:** Annie + Carl (source author)
+
+**Relates to:** ADR-0001 (this agent is a stateless specialist; the cross-agent join is orchestration)
+· ADR-0002 (the gene×sample status matrix this joins from) · ADR-0003 (BYOD is `grounded=false` and
+never label-joined) · ADR-0005 C4 (the request path reads curated artifacts, never the live API).
+**Sibling:** `pdac-subtype-agent` **ADR-0020** — variant×subtype is a cross-*modality* instance of
+its alignment-by-sample-id primitive, and inherits its "align, never pool" and mandatory-caveat
+stances. **Originating:** `pdac-subtype-agent` ADR-0019 (scope) and
+`docs/design/DESIGN-pdac-genomics-agent.md` §4.
+
+> **Why this ADR is late.** The label-join half shipped in M2 (2026-07-24) and the routing result was
+> already exposed, but the contract lived only as prose in `TODO.md`, the design doc §4, and module
+> docstrings. It is this agent's differentiator *and* the one decision that spans two Spaces — the
+> only major decision without an ADR. This writes it down; it does not change the built behaviour,
+> with the exception of §3, which records a correctness fix already made in code.
+
+## Context
+
+The question Carl actually wants answered is **"does a gene's variant status line up with molecular
+subtype?"** — KRAS/TP53/MYC/GATA6 alteration against basal-like vs classical. It is the reason a DNA
+specialist earns its place next to `pdac-subtype-agent`: neither agent can answer it alone.
+
+Three facts constrain any design:
+
+1. **It needs two modalities that live in two Spaces.** Variant status is here; the PurIST subtype
+   call is in `pdac-subtype-agent`. ADR-0001/ADR-0011 fixed the family's Option A: specialists are
+   **stateless siblings that never call each other**; cross-agent composition is the orchestrator's
+   job. A `variant_by_subtype` that reached out to a sibling would violate that outright.
+2. **But not every cohort needs a live PurIST call.** Several registered cBioPortal cohorts already
+   carry a molecular-subtype label as a clinical attribute (`paad_tcga` → `MOFFITT_SUBTYPE` and
+   friends). For those, the whole join is local: the label is already in the curated artifact next to
+   the status matrix, and no sibling is involved.
+3. **The join key is the sample id**, the same primitive `pdac-subtype-agent` ADR-0020 uses for
+   multi-dataset alignment. The feasibility spike measured 145/146 join coverage on `paad_tcga`
+   between the DNA and expression modalities of the same cohort.
+
+So the design question is not "who owns the join" but **where the seam falls** — and what shape this
+agent hands the orchestrator when the join is not local.
+
+## Decision
+
+### 1. The split: the label-join is local, the live-PurIST join is orchestration — DECIDED
+
+`variant_by_subtype(genes, source, …)` implements **only** the half a stateless agent can do alone:
+
+- **Local (label-join).** The cohort carries a validated subtype label in its curated clinical
+  attributes → this agent inner-joins per-gene variant status to that label **on sample id**, builds
+  the subtype × {altered, WT} contingency table, and runs the association test itself. It returns
+  `join_available: true` with `subtype_source: "clinical_attribute:<ATTR>"`.
+- **Routed (live-PurIST).** No in-metadata label, or a non-registered (BYOD) source → this agent
+  computes nothing and returns `{join_available: false, route: "orchestrator", reason, …}`.
+
+`altered` is defined per modality: mutation = `{missense, truncating, hotspot}` (i.e. non-`WT`),
+CNV = `{deep_del, loss, gain, amp}` (i.e. non-`neutral`). The test is **Fisher's exact for a 2×2**
+table and **chi-square for R×2** (R>2 subtype classes) — Fisher because subtype cohorts are small
+and asymptotic χ² is unreliable at low expected counts, chi-square above 2×2 because exact R×2 is
+not worth the cost at these n.
+
+The per-study modality-coverage gate and the pancreatic-lineage filter apply **before** the join, not
+after: a cohort with no CNV data returns `route: "unavailable_modality"`, never a null column read as
+"no alteration".
+
+### 2. The routing contract: exact shape, orchestrator obligation, and the sample-id question — DECIDED
+
+**The shape this agent guarantees.** Both branches are the *same tool's* return value, discriminated
+by `join_available`. The orchestrator must switch on it, never on the presence of `genes`:
+
+```jsonc
+// local — the join happened here
+{ "join_available": true, "source": "cbioportal:paad_tcga", "grounded": true,
+  "subtype_source": "clinical_attribute:MOFFITT_SUBTYPE", "modality": "mutation",
+  "n_labeled": 145,
+  "genes": { "KRAS": { "contingency": {"basal-like": {"altered": 41, "WT": 3}, …},
+                       "n": 145, "testable": true,
+                       "test": {"name": "fisher_exact", "odds_ratio": …, "p_value": …} } },
+  "caveats": [...], "citation": {...} }
+
+// routed — the orchestrator must complete the join
+{ "join_available": false, "route": "orchestrator", "reason": "<machine-stable reason>",
+  "source": "cbioportal:<study>", "note": "<human-readable restatement>" }
+```
+
+**What the orchestrator must do with `route: "orchestrator"`.** Three steps, in this order:
+
+1. Call `query_variant_status(genes, source)` **here** for the per-sample status matrix.
+2. Call `pdac-subtype-agent` for the PurIST label over the *same cohort*.
+3. Join the two on **sample id** and run the association test on its side, stamping
+   `subtype_source: "purist:<version>"` (see §5).
+
+The orchestrator **must not** synthesize a label and call back into `variant_by_subtype`: the
+`subtype_attribute` parameter exists for a *curator* naming a real clinical attribute, not as a
+back-door for injecting externally computed labels. Nor may it re-run this agent's test on a mixed
+provenance set. Composition is the orchestrator's; **this agent never calls a sibling**, which is why
+`route: "orchestrator"` is a terminal answer here rather than an internal retry.
+
+**Sample-id alignment across two Spaces — the open question, and the interim rule.** Whether ids
+align cleanly across Spaces is recorded as open in `TODO.md` and is **not resolved by this ADR**,
+because the evidence does not yet exist to resolve it: the spike measured alignment *within* one
+cBioPortal cohort (145/146 on `paad_tcga`), not between a cBioPortal cohort here and a GEO/registry
+matrix there, which is the case that would actually need a mapping. The interim rule is the honest
+one, and it is the same refuse-rather-than-guess posture the family uses elsewhere:
+
+> The orchestrator joins on **exact sample-id string equality** and **reports the join coverage**
+> (`n_joined` / `n_variant` / `n_subtype`). It performs **no fuzzy matching, no normalization, no
+> truncation-to-a-prefix** (e.g. TCGA barcode trimming) unless a *declared, reviewed* id map says so.
+> A join whose coverage collapses is a **refusal with the coverage numbers shown**, not a quiet
+> analysis of whatever overlapped.
+
+A silent low-coverage join is the dangerous failure here: it yields a small, biased, confident-looking
+table. Building a shared id map is deferred until a real cross-Space cohort pair demonstrates it is
+needed — and it would be a **declared artifact**, not inference at join time.
+
+### 3. Subtype-label validation: attribute id is not enough — the VALUES must speak PDAC subtype — DECIDED
+
+`find_subtype_labels` auto-detects a label from a known ordered attribute list (`MOFFITT_SUBTYPE`,
+`MRNA_SUBTYPE`, `SUBTYPE`, …). **Attribute-id matching alone is unsafe and is now insufficient by
+contract.** `SUBTYPE` is a generic id that cohorts fill differently: in `ccle_broad_2019` it holds
+**histology** — "Adenocarcinoma", "Melanoma", "Small Cell Lung Cancer" — so id-matching produced a
+confident, well-formatted **variant × histology** association across a pan-cancer panel, presented as
+variant × *molecular subtype*. That is precisely the "plausible-looking wrong answer" the family's
+gates exist to prevent, and it is worse than no answer.
+
+Therefore, on the **auto-detect** path, a candidate attribute is accepted only if its **values** pass
+a closed PDAC molecular-subtype vocabulary check (`basal`, `classical`, `squamous`, `progenitor`,
+`immunogenic`, `adex`, `quasimesenchymal`, `exocrine`, `mesenchymal`), with a **≥0.5** fraction of
+non-blank values matching — below 1.0 because real cohorts carry stray `NA`/`Other`/unclassified
+entries. A candidate that fails is **skipped**, the probe continues, and if nothing passes the cohort
+routes to the orchestrator. The vocabulary is deliberately **closed**: a label set that does not
+speak it is not a PDAC subtype call, whatever the attribute is named. Widening it is a deliberate
+edit, and each addition must be a real published PDAC subtype term.
+
+**An explicitly named `subtype_attribute` bypasses the vocabulary check.** The caller has named a
+specific attribute and taken responsibility for it; this is the escape hatch for a legitimately
+oddly-vocabularied cohort, and it keeps the guard from becoming a wall. The bypass is visible in the
+output — `subtype_source` always names the attribute used, so any answer is traceable to its label
+source.
+
+### 4. Statistical honesty: no multiple-testing correction, explicit `testable=false`, standing small-n caveat — DECIDED
+
+**No multiple-testing correction across genes, and this stays for v1.** The tool is a *descriptive
+screen* over a 19-gene driver panel the user chose, not a discovery scan over a genome; the family's
+consumers are non-coding scientists asking about specific genes. Correcting silently would be worse
+than not correcting: it would imply a family-wise hypothesis the user did not pose, and the correct
+denominator depends on how many genes they actually asked about across the session — something a
+stateless tool cannot know. Instead the p-values are shipped **uncorrected and labelled as such** via
+a mandatory caveat (`"Association is descriptive (no multiple-testing correction across genes
+here)."`), and the caveat block is not optional output. If a caller wants FDR across a panel, that is
+an orchestrator-side decision made with the full set of tests in hand.
+
+**`testable: false` with a machine-readable `reason` is the answer when a table cannot support a
+test** — rather than a p-value of 1.0, a `NaN`, or an exception. Two cases:
+- `"only one subtype class present"` — fewer than 2 subtype classes after the join.
+- `"no variation in alteration status (all-altered or all-WT)"` — a degenerate column.
+
+Both still return the **contingency table and `n`**, because the counts are the useful answer even
+when the test is undefined. All-altered is not hypothetical: KRAS is altered in ~90%+ of PDAC, so
+the panel's flagship gene is exactly the one that degenerates most often — the honest report is "45/45
+basal, 98/100 classical, no test possible", not a spurious statistic.
+
+**Small-n caveat discipline.** PDAC subtype cohorts are small and get smaller after the lineage
+filter and the label inner-join. `n_labeled` and the per-gene `n` are always returned so the reader
+can see how thin the table is, and the caveat block always states that the label is a pre-existing
+cohort attribute rather than a live call. Fisher's exact is used at 2×2 specifically so small counts
+do not get an unreliable asymptotic p-value. This ADR does **not** impose a hard minimum-n refusal:
+below-threshold cells still carry real information as *counts*, and a hard cut would silently drop
+cohorts the user explicitly asked about. Show the n, show the table, let the caveat do its work.
+
+### 5. A live-PurIST label and a metadata label are NEVER interchangeable — different provenance, reported as such — DECIDED
+
+They are not the same measurement and must never be pooled, averaged, or silently substituted:
+
+- A **metadata label** is a historical call by the cohort's authors, using their classifier, their
+  data version, and their thresholds (Moffitt 2015, Bailey 2016, Collisson 2011 — *different
+  taxonomies with different class counts*).
+- A **live PurIST call** is our classifier run now, on the expression matrix we hold, at a known
+  model version.
+
+Therefore `subtype_source` is a **required** field on every joined result and is the provenance
+discriminator: `"clinical_attribute:<ATTR>"` versus `"purist:<version>"`. The rules that follow:
+
+- **Never mix within one contingency table.** A cohort is joined against one label source, not a
+  fill-in-the-gaps blend of a metadata label plus PurIST for the unlabelled samples. That would put
+  two classifiers' calls in the same table and attribute the disagreement to biology.
+- **Cross-source comparison is a concordance question, not a join.** "Does the metadata label agree
+  with PurIST?" is a legitimate and interesting question — but it is *its own* analysis with its own
+  output (agreement rate, confusion matrix), owned by the orchestrator, and it is **not** licence to
+  treat the two as one variable afterwards.
+- **Two results with different `subtype_source` are not comparable head-to-head** and must be
+  reported with their provenance attached, in the same spirit as ADR-0020's mandatory comparability
+  banner. A downstream renderer may not drop `subtype_source` from a variant×subtype result.
+
+## Consequences
+
+**Positive**
+- The differentiator is finally specified end-to-end: the orchestrator has a written contract with a
+  discriminated return shape, three ordered steps, and an explicit prohibition list.
+- Statelessness (ADR-0001/0011) survives contact with the one genuinely cross-Space question, and the
+  common case (`paad_tcga`) still answers in one hop with zero sibling traffic and no API call
+  (ADR-0005 C4).
+- The vocabulary check closes a live, demonstrated wrong-answer path (CCLE histology-as-subtype)
+  rather than a theoretical one.
+- Degenerate tables and small cohorts produce honest, machine-readable non-answers instead of
+  statistics that read as findings.
+
+**Negative**
+- The orchestrator carries real work this ADR only *specifies*: the routed branch, the id join with
+  coverage reporting, and its own association test. Until that lands, unlabelled cohorts have no
+  end-to-end answer — a routed refusal, not a result.
+- Two association-test implementations will exist (here and orchestrator-side). They must agree on
+  the `altered` vocabulary and the Fisher/χ² rule, or the same cohort answers differently by route.
+  Mitigation: this ADR is the single normative statement of both, and the orchestrator implementation
+  should be reviewed against §1.
+- The closed vocabulary will reject a genuinely-labelled cohort using unusual terms; the named-attribute
+  bypass is the intended (manual) remedy.
+- Uncorrected p-values can still be over-read by a non-statistician reader, caveat or not.
+
+**Neutral**
+- No change to the status-matrix model (ADR-0002) or the curation pipeline; this is a contract over
+  existing artifacts.
+- Sample-id alignment across Spaces remains open, with a conservative interim rule; resolving it will
+  amend §2 rather than reopen the split.
+
+## Alternatives considered
+
+1. **This agent calls `pdac-subtype-agent` directly to get PurIST and completes every join itself.**
+   Rejected — it is the exact coupling ADR-0001/0011 rejected family-wide: specialists become clients
+   of each other, gain a second Space as a runtime dependency, and lose statelessness. It would also
+   duplicate the orchestrator's routing and auth surface in a specialist.
+2. **Push the label-join to the orchestrator too, so there is exactly one join implementation.**
+   Rejected — for a cohort whose label sits in its own curated artifact, this would force two Space
+   round-trips and a sibling call to do something purely local, on the most common path
+   (`paad_tcga`). The seam belongs where the data is: local label → local join.
+3. **Auto-detect subtype labels by attribute id only (the pre-fix behaviour).** Rejected on evidence
+   — `ccle_broad_2019`'s `SUBTYPE` is histology, and id-matching turned that into a confident
+   variant×histology association labelled as subtype.
+4. **Free-text/heuristic label discovery over all clinical attributes.** Rejected — a wider net finds
+   more wrong labels, not more right ones. The known-attribute list plus a closed value vocabulary
+   keeps every join traceable to a named, recognized label source.
+5. **Apply Benjamini–Hochberg across the requested gene panel inside the tool.** Rejected for v1 —
+   imposes a family-wise hypothesis the user did not pose, and the correct denominator is
+   session-level knowledge a stateless tool does not have. Available to the orchestrator, which does.
+6. **Refuse below a minimum n (e.g. n<20) instead of caveating.** Rejected — the counts are still the
+   answer at small n, and a hard cut would silently drop cohorts the user named. Report n, caveat,
+   and refuse only the genuinely *undefined* (`testable=false`).
+7. **Treat a metadata label and a PurIST call as one interchangeable "subtype" variable.** Rejected —
+   different classifiers and, for Bailey/Collisson, different taxonomies entirely; pooling them
+   converts classifier disagreement into apparent biology.
+
+## Revisit triggers
+
+- A real cross-Space cohort pair shows sample-id alignment **is not** clean → resolve §2's open
+  question with a declared id map (amendment, not a re-split).
+- The orchestrator-side live-PurIST join lands → confirm it matches §1's `altered`/test rules and
+  stamps `subtype_source: "purist:<version>"` per §5.
+- A registered cohort is rejected by the §3 vocabulary despite carrying real molecular subtypes →
+  widen the closed list deliberately (and record the term's source).
+- Panel-wide screening becomes a routine ask (rather than gene-specific questions) → revisit §4's
+  no-correction stance at the orchestrator layer.

docs/adr/ADR-0007-recuration-cadence.md

@@ -0,0 +1,170 @@
+# ADR-0007 — Re-curation cadence: upstream-signal staleness, visible age, no refusal
+
+**Status:** Accepted · **Date:** 2026-07-28 · **Renumbered:** 2026-07-28 · **Deciders:** Annie
+
+**Numbering.** Claimed and written on this lane as **ADR-0006**, renumbered to **0007** before
+merge. A concurrent lane had claimed 0006 for the variant×subtype join contract (`a792086`) and
+published it (`64d7f04`) — both already on `main`. Per `RESERVED.md` protocol rule 4 the earlier
+claim keeps the number and the later one moves; this ADR had not been merged or cited outside its
+branch, so the rename is safe.
+
+**Third occurrence of the same root cause, and it is worth naming.** This lane's worktree held its
+own copy of `RESERVED.md` and was branched before the other lane's claim landed, so the
+one-shared-row conflict could not fire at claim time — exactly the failure recorded for the 0003
+collision below. The claim was committed alone and pushed, but to the *feature branch*, not to
+`main` (rule 5), because `origin/main` here IS the live Space and pushing it is a deploy. That is a
+real tension in the protocol on this repo: **the collision was caught by reading
+`SHOWCASE_STATUS.md` before updating it, not by the ledger.** Until rule 5 has a deploy-safe
+mechanism here, `git fetch origin main && git show origin/main:docs/adr/RESERVED.md` before
+claiming is the check that actually works.
+
+**Follows:** ADR-0005 (public cBioPortal + curate-and-cache, condition C4) and ADR-0002 (the
+curation contract). ADR-0005 made the API a curation-time dependency; this ADR handles the
+consequence it named and left open.
+
+## Context
+
+ADR-0005's own Consequences section wrote the gap down and moved on:
+
+> Cached matrices can drift from upstream until we deliberately re-curate (acceptable — variant
+> *status* over a driver panel is stable; invalidation is a deliberate re-pull, not a poll).
+
+"A deliberate re-pull" is a mechanism, not a policy. In practice nothing told anyone *when* to
+pull. Each artifact carried a `curated_at` timestamp from the beginning, but **nothing read it,
+nothing warned, and no threshold existed** — so a cohort could sit unrefreshed for years and every
+answer would look exactly as confident as one curated yesterday. Four cohorts are curated today
+(`paad_tcga`, `ccle_broad_2019`, `paad_qcmg_uq_2016`, `paad_utsw_2015`).
+
+Three facts shape the answer:
+
+1. **cBioPortal studies are versioned releases, not a live feed.** A published cohort like
+   `paad_tcga` can be byte-stable for years; `ccle_broad_2019` gets periodic refreshes. A blanket
+   "re-curate monthly" would spend the condition-C3 politeness budget rewriting identical files.
+2. **Upstream publishes the signal we need.** `/studies/<id>` carries `importDate` — one cheap
+   request per study answers "has upstream re-imported since we curated?" without re-pulling
+   anything.
+3. **Artifacts are committed and reviewable by design** (ADR-0005). That reviewability is the
+   reason a stale artifact is a governance problem at all, and it is also the constraint: nothing
+   may refresh an artifact automatically at runtime, or C4's decoupling comes back as an
+   intermittent one.
+
+## Decision
+
+**Drive re-curation off upstream's `importDate`, make artifact age visible in every answer, and
+never refuse for staleness alone.** Three parts:
+
+### 1. Cadence — event-driven, with a time-based backstop
+
+`python -m src.curate --check` fetches **only** `/studies/<id>` for each curated study and compares
+upstream's `importDate` against the one recorded in the artifact. Drift → re-curate; no drift →
+do nothing, regardless of age. Curation now records `source_import_date` in the payload so the
+comparison exists at all.
+
+Two time horizons act as a backstop for the case where nobody ran the check either:
+`REVIEW_AFTER_DAYS = 180` ("a human should look") and `STALE_AFTER_DAYS = 365` ("say it in the
+answer"). They are advisory in both states.
+
+`--check` exits non-zero on drift or a stale artifact, so CI or a periodic job can fail on it.
+**It never writes.** A checker that repaired what it found would re-establish the automatic
+API path C4 removed, and would do so unreviewed.
+
+### 2. Visibility — in the answer, not just the log
+
+Every grounded tool payload's `citation` block now carries a `curation` sub-block:
+`curated_at`, `age_days`, `level` (`current` / `review_due` / `stale` / `unknown`),
+`source_import_date`, `drift_comparable`, and a plain-language `note`. Past the review horizon the
+Gradio page also renders a visible line, next to the existing licence caution.
+
+This follows the repo's standing stance, already applied to `terms` in `licenses.citation_block`
+and to the licence caution in the UI: provenance that stops at the storage layer is provenance
+nobody honours. A maintainer-only `--check` would have satisfied the letter of the gap and left
+the person acting on a frequency none the wiser.
+
+### 3. Staleness never refuses
+
+A stale-but-valid cohort is **old, not wrong**. Its status calls were correct for the upstream
+release they were curated from, and that release still exists and is still citable. Refusing it
+would withhold a correct answer because a maintainer missed a review window — trading the user's
+answer for our maintenance signal.
+
+Refusal stays reserved for gates where the answer would be *incorrect*: genome-build mismatch,
+species, absent per-study modality, and controlled access (C2). Age is not in that class, and
+putting it there would dilute what a refusal from this agent means.
+
+`test_stale_artifact_still_answers_and_says_so` pins this: it ages an artifact past the horizon and
+asserts the answer is intact *and* labelled.
+
+## Running the check
+
+A check nobody runs is the same as the `curated_at` nobody read, so the schedule is part of the
+decision rather than a follow-up.
+
+**Weekly, unattended:** `.github/workflows/curation-freshness.yml` — Monday 07:00 UTC, plus
+`workflow_dispatch`. Weekly is right for a signal that moved twice in the last year: four metadata
+requests, and drift is never urgent, because a stale cohort keeps answering and says its age.
+
+**It does not run yet, and that is stated in the file rather than assumed away.** `origin` here IS
+the HuggingFace Space, and HuggingFace does not execute GitHub Actions. Every sibling
+(`DecoupleRpy_Agent`, `pdac-subtype-agent`, `pdac-analysis-orchestrator`) carries a second `github`
+remote; **this repo has none**, so nothing schedules the workflow. It is committed anyway on the
+precedent of `DecoupleRpy_Agent/.github/workflows/security.yml`: adding the mirror later is then
+zero work, and the check's definition never forks between the two paths. Adding that mirror is the
+one ops step that turns this on.
+
+**Until then**, the check is `python -m src.curate --check` — run by hand, or from a local
+scheduler. A launchd agent on the maintainer's machine is the low-ceremony option and is
+deliberately *not* installed by this repo: a job that runs on one laptop is invisible to everyone
+else, and pretending otherwise is how the original gap happened.
+
+The job is report-only in every form. Nothing in this cadence writes an artifact.
+
+## Consequences
+
+**Positive**
+- Re-curation is triggered by evidence rather than a calendar; the polite-client budget is spent
+  only where upstream actually moved.
+- A reader of any answer can see the snapshot's age without asking a maintainer.
+- `--check` is CI-attachable, so drift can become a failing build rather than a memory.
+- No new runtime dependency and no runtime writes — C4 holds exactly as before.
+
+**Negative**
+- The four artifacts curated before this ADR carried no `source_import_date`. Rather than leave
+  them `drift_unknown` until each happened to be re-curated, the field was **backfilled once**,
+  in this ADR's commit, from a live `/studies/<id>` read of each — a metadata-only addition that
+  touches no status call. Any *future* artifact arriving without the field still reports
+  `drift_unknown`, which is the honest state and not "no drift". (The backfill also confirmed the
+  premise empirically: all four were last imported upstream in **January 2026** and curated in
+  July — six months of a published cohort not moving, which is exactly why a monthly re-pull would
+  have been churn.)
+- `importDate` is trusted as upstream's release stamp. If cBioPortal re-imports without moving it,
+  the check misses the drift — the time horizons are the only backstop for that.
+- Freshness metadata is now part of the response contract, so consumers may start depending on it.
+
+**Neutral**
+- **No schema-version bump.** `source_import_date` is optional and its absence degrades to an
+  honest "not comparable". Bumping to v3 would refuse all four existing artifacts and force
+  precisely the blanket re-curation this cadence exists to avoid.
+
+## Alternatives considered
+
+1. **Fixed calendar refresh (e.g. monthly/quarterly re-curate everything).** Rejected — busywork
+   against versioned releases that rarely change; burns the C3 budget re-fetching identical data,
+   and produces no-op commits that train reviewers to skim artifact diffs.
+2. **Refuse to serve past a staleness threshold.** Rejected — disproportionate. See part 3. It also
+   converts a maintenance lapse into a user-visible outage of a *correct* answer.
+3. **A background job that re-curates on drift.** Rejected — artifacts are committed and reviewed
+   on purpose (ADR-0005); an automatic writer both bypasses that review and reintroduces the
+   request-path API coupling C4 removed.
+4. **`--check` only, no age in the answer.** Rejected — it fixes the maintainer's blindness and
+   leaves the reader's intact, against the repo's own stance on provenance.
+5. **Hash the upstream payload instead of trusting `importDate`.** Rejected for v1 — that is a full
+   re-fetch, i.e. re-curation, which is the cost this design is avoiding. Revisit if `importDate`
+   proves unreliable.
+
+## Revisit triggers
+
+- `importDate` observed to be stale or unmoved across a real upstream change → move to a
+  content-hash check (alternative 5) or shorten the horizons.
+- A cohort where drift is *frequent* (a live-updating source rather than a versioned release) →
+  that source needs its own cadence, not this one.
+- The panel or the cohort count grows enough that a serial `--check` stops being cheap.

docs/adr/RESERVED.md

@@ -33,10 +33,12 @@ use) · `DROPPED` (burned).
 | 0003 | PUBLISHED | BYOD MAF/segment upload contract (`grounded=false`, refusals) | `ADR-0003-byod-contract.md` |
 | 0004 | PUBLISHED | Auth gate — OAuth allow-list + `ACCESS_CONTROL` dark-launch | `ADR-0004-auth-gate.md` |
 | 0005 | PUBLISHED | Public cBioPortal instance + curate-and-cache for v1 (no self-host) | `ADR-0005-cbioportal-public-vs-selfhost.md` |
+| 0006 | PUBLISHED | variant×subtype join contract — label-join here / live-PurIST via the orchestrator | `ADR-0006-variant-subtype-join-contract.md` |
+| 0007 | PUBLISHED | Re-curation cadence — upstream-signal staleness, visible age, no refusal | `ADR-0007-recuration-cadence.md` |
 | **0014** | **EXTERNAL** | Shared security-scan standard (pip-audit + bandit + gitleaks + trivy) — authored in `DecoupleRpy_Agent`. **Do not use;** adopt it, don't renumber it. Adopted here as `security/scan.sh`. | *(sibling repo)* |
 | **0015** | **EXTERNAL** | `data_level` / registry `modality` semantics — authored in `biodata-registry`. **Do not use.** A DNA `modality` extension would be an amendment *there*, under that owner. | *(sibling repo)* |
 
-**Next free number: 0006.**
+**Next free number: 0008.**
 
 ## Resolved: the 0003 collision (2026-07-24 → fixed 2026-07-25)
 
@@ -58,9 +60,6 @@ outside the repo. Both branches are now merged into `main`.
 
 ## Known upcoming ADRs (claim a number when you start)
 
-- **variant×subtype join contract** — the orchestrator-owned cross-agent join (subtype from a live
-  PurIST call vs a metadata label), the association test, and small-n honesty. Sibling of
-  `pdac-subtype-agent` ADR-0020. The label-join half is built (M2); the contract is unwritten.
 - **Does this agent use `biodata-registry` at all?** The founding design assumed a registry `modality`
   extension as a hard blocker; the build bypassed it and reads cBioPortal directly (ADR-0001
   amendment, 2026-07-25). Reopening that route needs this ADR — but nothing is blocked meanwhile.

docs/cbioportal-terms-and-deployability.md

@@ -183,6 +183,12 @@ Sources:
 - [x] **C4 — Curate-and-cache** ✅ 2026-07-25: `python -m src.curate` is the only caller that touches
       the API; the request path reads committed artifacts and refuses an uncurated study. Verified by
       a test that sabotages the HTTP layer and still answers.
+      **Cadence (ADR-0007, 2026-07-28):** C4's own consequence — a cached artifact drifting
+      unnoticed — is now handled. `python -m src.curate --check` compares upstream's `importDate`
+      against the one recorded at curation (one metadata request per study, no re-pull, C3-cheap),
+      every grounded answer carries the artifact's age in `citation.curation`, and staleness is
+      **visible, never a refusal**. `--check` deliberately does not write: re-curation stays a
+      reviewed commit, because an automatic repairer would put the API back on an unattended path.
 - [x] **v1 = public instance** — ratified in ADR-0005; self-host deferred with the re-visit triggers
       above.
 - [x] Only **open-access** studies curated for v1 — enforced in code (C2), not just intended; a test

gradio_ui.py

@@ -190,6 +190,24 @@ def _licence_caution(result) -> str:
     return ""
 
 
+def _freshness_caution(result) -> str:
+    """A visible line once a cohort's artifact is past the review horizon (ADR-0007).
+
+    Same reasoning as `_licence_caution`: the freshness block is already in the JSON, but a
+    snapshot date nobody reads is a snapshot date nobody accounts for. Deliberately NOT a
+    refusal — the answer is old, not wrong, and it still renders in full.
+    """
+    curation = (result or {}).get("citation", {}).get("curation") if isinstance(result, dict) else None
+    if not curation:
+        return ""
+    level = curation.get("level")
+    if level == "stale":
+        return f" 🕰️ **Snapshot age:** {curation.get('note')}"
+    if level in ("review_due", "unknown"):
+        return f" ℹ️ **Snapshot age:** {curation.get('note')}"
+    return ""
+
+
 def _status_caution_md(result):
     """Surface the per-study coverage gate and any licence constraint — say it, loudly."""
     if not isinstance(result, dict):
@@ -203,6 +221,7 @@ def _status_caution_md(result):
             "'no alterations found'."
         )
     parts.append(_licence_caution(result))
+    parts.append(_freshness_caution(result))
     text = "".join(p for p in parts if p).strip()
     if not text:
         return gr.update(value="", visible=False)
@@ -223,9 +242,12 @@ def _subtype_caution_md(result):
             visible=True,
         )
     caveats = result.get("caveats") or []
-    if not caveats:
+    parts = ["⚠️ **Caveats:** " + " ".join(caveats) if caveats else ""]
+    parts.append(_freshness_caution(result))
+    text = "".join(p for p in parts if p).strip()
+    if not text:
         return gr.update(value="", visible=False)
-    return gr.update(value="⚠️ **Caveats:** " + " ".join(caveats), visible=True)
+    return gr.update(value=text, visible=True)
 
 
 # --------------------------------------------------------------------------- #
@@ -247,6 +269,25 @@ def _subtype_caution_md(result):
 _MACHINE_TOKEN_HEADERS = ("x-orchestrator-token", "x-hf-authorization")
 _WHOAMI_CACHE: dict[str, str | None] = {}
 
+# Machine-caller denial text, per diagnosis. Deliberately NOT the UI's "please sign in": a
+# machine caller cannot sign in, and telling it to is what made this look like a Space-side
+# auth bug. Each message names the side that has to act.
+_MACHINE_DENIAL_REASONS = {
+    "no_token_header": (
+        "🔒 No machine credential presented: neither 'x-orchestrator-token' nor "
+        "'x-hf-authorization' reached this Space. The caller is misconfigured — the "
+        "orchestrator attaches that header only when its own HF_TOKEN is set, so check that "
+        "secret on the CALLING Space. (Note HF edge infra strips the reserved 'x-hf-*' "
+        "namespace, so only the custom header survives in a deployed Space.)"
+    ),
+    "token_unresolved": (
+        "🔒 A machine credential was presented but could not be resolved to a HuggingFace "
+        "identity — the token is invalid/expired, or the identity lookup failed upstream. "
+        "This is fail-closed by design; retry once before treating it as a rejection."
+    ),
+    "not_allowlisted": None,  # check_access already says who was refused and why — keep it.
+}
+
 
 def _header_value(headers, name: str) -> str | None:
     if not headers:
@@ -278,28 +319,55 @@ def _resolve_token_identity(token: str) -> str | None:
     return identity
 
 
-def _machine_caller_identity(request) -> str | None:
-    """Identity behind a machine call, or None (fail-closed)."""
+def _machine_caller_identity(request) -> tuple[str | None, str]:
+    """`(identity, diagnosis)` behind a machine call. Identity None ⇒ denied (fail-closed).
+
+    The ``diagnosis`` is why, and it exists because the three failure modes are operationally
+    very different but used to be indistinguishable in the response:
+
+    - ``no_token_header`` — the caller sent neither machine header. **The caller is
+      misconfigured, not unauthorized**: the orchestrator only attaches
+      ``x-orchestrator-token`` when its own ``HF_TOKEN`` is set, so an unset secret on *its*
+      Space silently produces this. (Cost a live debugging session, 2026-07-27→28: this state
+      returned "Please sign in", which reads as a *this*-Space auth bug and sent the
+      investigation server-side, where nothing was wrong.)
+    - ``token_unresolved`` — a token arrived but ``whoami`` would not resolve it (bad/expired
+      token, or an upstream blip — the ambiguity ADR-0005 C4's reasoning warns about, since
+      this is an outbound call on the request path).
+    - ``not_allowlisted`` — identity resolved fine; it is simply not on ``ALLOWED_IDS``. The
+      only one of the three that is a genuine authorization decision.
+    """
     headers = getattr(request, "headers", None) if request else None
+    presented = False
     for header in _MACHINE_TOKEN_HEADERS:
         raw = _header_value(headers, header)
         if not raw:
             continue
         token = raw[7:].strip() if raw.lower().startswith("bearer ") else raw.strip()
         if token:
+            presented = True
             identity = _resolve_token_identity(token)
             if identity:
-                return identity
-    return None
+                return identity, "resolved"
+    return None, ("token_unresolved" if presented else "no_token_header")
 
 
 def _machine_gate(tool: str, source: dict, request) -> tuple[str | None, str | None]:
     """(identity, denial_json). A non-None denial must be returned to the caller verbatim."""
-    username = _machine_caller_identity(request)
+    username, diagnosis = _machine_caller_identity(request)
     allowed, denial = check_access(username)
     if not allowed:
+        if username:
+            diagnosis = "not_allowlisted"
         record_run(tool, username=username, source=source, status="denied")
-        return username, json.dumps({"status": "denied", "reason": denial}, indent=2)
+        return username, json.dumps(
+            {
+                "status": "denied",
+                "reason": _MACHINE_DENIAL_REASONS.get(diagnosis) or denial,
+                "machine_auth": diagnosis,
+            },
+            indent=2,
+        )
     return username, None
 
 

licenses.py

@@ -291,7 +291,9 @@ def study_citation(study_id: str | None, terms: dict | None = None) -> str:
     return CBIOPORTAL_STUDY_UNKNOWN
 
 
-def citation_block(source: str | None, terms: dict | None = None) -> dict:
+def citation_block(
+    source: str | None, terms: dict | None = None, curation: dict | None = None
+) -> dict:
     """The attribution + terms block stamped onto every tool payload (C1 + C2).
 
     `source` is the tool's source string — ``"cbioportal:<study>"`` for a grounded cohort, or
@@ -301,6 +303,11 @@ def citation_block(source: str | None, terms: dict | None = None) -> dict:
     `terms` is the curated per-study license block (C2). It rides in the *answer*, not just in
     the artifact, because the person acting on the number is the one who needs to know the
     cohort's license — provenance that stops at the storage layer is provenance nobody reads.
+
+    `curation` is the artifact's freshness block (ADR-0007), carried for exactly the same
+    reason and computed by `curated_store.freshness_from_payload`. It states how old the
+    snapshot is and which upstream release it came from; it never changes whether an answer is
+    produced. An answer that is old is still an answer — it just has to say so.
     """
     src = (source or "").strip()
     if not src.startswith("cbioportal:"):
@@ -314,4 +321,6 @@ def citation_block(source: str | None, terms: dict | None = None) -> dict:
     }
     if terms:
         block["study_terms"] = terms
+    if curation:
+        block["curation"] = curation
     return block

memory.md

@@ -500,6 +500,222 @@ failure.
 
 ---
 
+## 2026-07-27 — Carl allow-listed; UI gate verified BOTH ways; machine auth still failing
+
+**`ALLOWED_IDS=anne-voigt,cpelz741`.** Carl's HF id was taken from `pdac-subtype-agent` prod
+(`SHOWCASE_STATUS.md` records its live config) rather than guessed — a wrong username would either
+lock out a colleague or hand access to an unrelated account that owns that name.
+
+**The OAuth UI path is now VERIFIED, which was the last open deploy question.** Signed in as
+`anne-voigt` in the deployed Space: a CCLE query rendered the frequency chart (KRAS ~84% across the
+57 lineage-filtered pancreatic lines) *and* displayed the licence caution — "commercial use of this
+cohort is restricted under Broad DepMap/CCLE Portal Terms". Signed out, the same query returns
+`{"status":"denied"}`. Both halves of the gate confirmed end-to-end in the real UI.
+
+Incidental: the Space **does not render inside the huggingface.co page frame** (blank), but works at
+the direct host `https://anne-voigt-pdac-genomics-agent.hf.space`. Use the direct host for testing.
+The cohort dropdown renders its value only on focus — a Gradio display quirk, not an empty default.
+
+**Broad terms read directly** (see previous entry): confirmed, and the *Continuity of Terms* clause
+means rehosting requires reposting them in full — done in `CCLE_BROAD_TERMS.md`.
+
+**Open and now spun off: the machine API denies the orchestrator despite correct configuration.**
+The orchestrator already sends `x-orchestrator-token` (its commit `05bda30`, built for the subtype
+agent's ADR-0018 gate) and that token resolves to `anne-voigt`, which is allow-listed here. It is
+still denied. What is ruled out: the header is *not* being dropped — a local probe confirmed
+`x-orchestrator-token` arrives in `gr.Request.headers` alongside `x-hf-authorization`. So the
+failure is **server-side identity resolution**: `_resolve_token_identity()` calls
+`huggingface_hub.whoami()` at request time from inside the Space and returns None on any failure.
+It fails closed, which is right, but silently, which is why this took a live test to notice.
+
+The design question worth answering before patching: **should a gate depend on an outbound network
+call per request at all?** That is a third-party dependency on the request path — the same class of
+coupling ADR-0005 C4 removed for cBioPortal. A shared-secret comparison would have neither the
+latency nor the failure mode.
+
+---
+
+## 2026-07-28 — ADR-0006: the variant×subtype join contract (written down at last)
+
+The agent's differentiator was the only major decision without an ADR — it lived as prose in
+`TODO.md`, `DESIGN-pdac-genomics-agent.md` §4, and module docstrings, despite being the one part of
+the design that **spans two Spaces**. Now `docs/adr/ADR-0006-variant-subtype-join-contract.md`.
+
+**No behaviour changed.** This documents what M2 already ships (plus the vocabulary fix already in
+code) and, crucially, states the orchestrator's obligations normatively so the other repo has a
+contract to build against rather than a docstring to interpret.
+
+What it settles:
+
+1. **The split.** Label-join is local (cohort carries a validated subtype clinical attribute → join
+   on sample id + test here); the live-PurIST join is orchestration (ADR-0001/0011 — stateless
+   siblings never call each other), returning `{join_available: false, route: "orchestrator"}`.
+   `altered` vocabularies and the Fisher-2×2 / χ²-R×2 rule are pinned here as the single normative
+   statement, because the orchestrator will implement the *same* test on its side.
+2. **The routing contract** — the discriminated return shape (switch on `join_available`, never on
+   the presence of `genes`), the orchestrator's three ordered steps, and an explicit prohibition:
+   it may **not** synthesize a label and call back through `subtype_attribute`.
+   **Sample-id alignment across Spaces stays OPEN** (the spike measured 145/146 *within* one
+   cBioPortal cohort — not the cross-Space case that would actually need a map). Interim rule:
+   exact string equality, **report join coverage**, no fuzzy/prefix matching, and a collapsed join
+   is a refusal **with the numbers shown**. A silent low-coverage join is the dangerous failure.
+3. **Label validation is load-bearing.** Attribute-id matching alone is unsafe *on evidence*:
+   `ccle_broad_2019`'s `SUBTYPE` holds histology ("Adenocarcinoma", "Melanoma"), which produced a
+   confident variant×histology association dressed as variant×subtype. Auto-detect now validates
+   VALUES against a **closed** PDAC subtype vocabulary (≥0.5 of non-blank values); an explicitly
+   named attribute bypasses it (caller took responsibility) and is always visible in `subtype_source`.
+4. **Statistical honesty — kept as-is, deliberately.** No multiple-testing correction across genes
+   (descriptive screen over a user-chosen panel; the right denominator is session-level knowledge a
+   stateless tool lacks — FDR is the orchestrator's call), mandatory caveat saying so, and
+   `testable=false` + machine-readable reason instead of a bogus p-value. Contingency table and `n`
+   are returned even when untestable — KRAS is altered in ~90%+ of PDAC, so the flagship gene is the
+   one that degenerates most often. No hard minimum-n refusal; show n, caveat, refuse only the
+   genuinely undefined.
+5. **Metadata label ≠ live PurIST call.** Never interchangeable, never mixed in one contingency
+   table, never blended to fill gaps. `subtype_source` is required on every joined result
+   (`clinical_attribute:<ATTR>` vs `purist:<version>`) and may not be dropped downstream.
+   "Do they agree?" is a *concordance analysis*, not a licence to pool.
+
+Cross-references `pdac-subtype-agent` **ADR-0020**, whose alignment-by-sample-id primitive this
+reuses — variant×subtype is a cross-*modality* instance of the same cross-source alignment pattern,
+and inherits its align-never-pool + mandatory-caveat stance.
+
+**Ledger protocol followed to the letter**: 0006 claimed with status `CLAIMED`, committed **alone**,
+pushed to `main` (`a792086`) *before* the ADR was written — the step that exists because of the real
+0003 collision. Flipped to `PUBLISHED` after.
+
+**Known follow-up (not a blocker):** two association-test implementations will exist (here and
+orchestrator-side) and must agree on §1's rules, or the same cohort answers differently by route.
+
+---
+
+## 2026-07-28 — Machine-API auth: the Space was never broken; the bug is caller-side
+
+**The 2026-07-27 diagnosis in the entry above is WRONG and is corrected here.** It concluded the
+failure was "server-side identity resolution — `_resolve_token_identity()` calls `whoami` per
+request and returns None". Probing the deployed Space directly disproves that:
+
+| probe (against prod, `ACCESS_CONTROL=enforce`) | result |
+|---|---|
+| valid HF token in `x-orchestrator-token` | **`status: ok`** — full panel returned |
+| bogus token in `x-orchestrator-token` | denied |
+| header absent entirely | denied |
+
+So `whoami` resolves fine from inside the Space and the gate discriminates exactly as designed.
+**Root cause is the caller:** `pdac-analysis-orchestrator`'s `router._build_client_kwargs()`
+attaches `x-orchestrator-token` **only when its own `HF_TOKEN` is set** — an unset secret on *that*
+Space sends no header at all. The fix is a secret on the orchestrator Space; **no code change was
+needed here.**
+
+**Why it was misdiagnosed, and the actual fix shipped.** All three failure modes returned one
+message — *"🔒 Please sign in with your HuggingFace account"* — which reads as a this-Space auth
+bug and sent the investigation server-side, where nothing was wrong. A machine caller cannot sign
+in; telling it to is a category error. Machine denials now carry a `machine_auth` diagnosis:
+
+- `no_token_header` — **caller misconfigured**, message names the orchestrator's `HF_TOKEN`.
+- `token_unresolved` — a token arrived but did not resolve (bad/expired, or an upstream blip).
+- `not_allowlisted` — resolved fine, simply not on `ALLOWED_IDS`. The *only* one of the three that
+  is a real authorization decision; still names who was refused.
+
+4 regression tests pin the three states apart (`tests/test_machine_api_auth.py`). **113 green.**
+
+**Method note worth keeping:** the earlier conclusion came from reading the code and a local
+header probe; it took ~4 curl calls against the deployed Space to overturn it. When a gate is
+"failing", probe the deployed thing with a known-good credential *before* theorising about why the
+resolution path is broken — the cheap experiment discriminates caller-side from server-side in one
+step. The lookalike messages are what made theorising feel productive.
+
+**Still open (unchanged, not urgent):** should an auth gate depend on an outbound `whoami` on the
+request path at all, versus a shared-secret comparison? Same coupling class ADR-0005 C4 removed for
+cBioPortal. It works today; this is a latency/failure-mode question, not a correctness one.
+
+---
+
+## 2026-07-28 — Re-curation cadence (ADR-0007): drift, visibility, and no refusal
+
+Closed the gap ADR-0005 C4 created and left open. `curated_at` had been written into every
+artifact since commit one and **read by nothing** — no threshold, no warning, no policy. A cohort
+could drift from upstream for years and every answer would look equally confident.
+
+**Cadence is upstream-driven, not calendar-driven.** `python -m src.curate --check` reads one
+`/studies/<id>` per curated study and compares upstream's `importDate` against the stamp now
+recorded at curation (`source_import_date`). Drift → re-curate; no drift → do nothing, however old
+the file is. **The empirical confirmation is the point:** all four cohorts were last imported
+upstream in **January 2026** and curated in July — six months of a published cohort not moving.
+A "refresh monthly" policy would have rewritten four byte-identical files and spent the C3
+politeness budget for zero new data. `REVIEW_AFTER_DAYS=180` / `STALE_AFTER_DAYS=365` are only a
+backstop for when nobody runs the check.
+
+**Age is visible to the reader, not just the maintainer.** Every grounded answer's `citation` block
+now carries `curation` (`curated_at`, `age_days`, `level`, `source_import_date`, `drift_comparable`,
+plain-language `note`); the UI renders a line past the horizon, next to the existing licence
+caution. Same stance that put `terms` in the response contract — provenance that stops at the
+storage layer is provenance nobody honours.
+
+**Stale never refuses.** A stale-but-valid cohort is old, not wrong: its calls were correct for the
+release they were curated from. Refusing would withhold a correct answer over a maintenance lapse
+and would dilute what a refusal from this agent means. Refusal stays for the *incorrectness* gates
+(build, species, absent modality, access tier). Pinned by
+`test_stale_artifact_still_answers_and_says_so`.
+
+**`--check` never writes**, deliberately — re-curation stays a reviewed commit. A checker that
+repaired what it found would put the API back on an unattended path, i.e. undo C4 quietly.
+
+Two implementation notes worth keeping:
+
+- **No schema bump.** `source_import_date` is optional; absence degrades to an honest
+  `drift_comparable: false`. Bumping to v3 would have refused all four existing artifacts and
+  forced exactly the blanket re-curation this cadence exists to avoid.
+- The four pre-existing artifacts had their `source_import_date` **backfilled once** in the same
+  commit from a live metadata read (metadata only — no status call touched), so `--check` is useful
+  today rather than "unknown until each happens to be re-curated".
+
+121 tests pass (11 new, `tests/test_recuration_cadence.py`). `--check` verified live against the
+public instance: all four `up_to_date`. **Not deployed** — the branch
+`claude/infallible-kowalevski-2d4648` is pushed to origin and rebased onto `main`, but
+`origin/main` IS the live Space, so promoting is a deliberate deploy decision.
+
+**Renumbered 0006 → 0007, and the near-miss is the lesson again.** A concurrent lane had already
+claimed *and published* 0006 (the variant×subtype join contract) on `main`. This lane's worktree
+held its own copy of `RESERVED.md` and predated that claim, so the one-shared-row conflict could
+not fire — the **third** time that root cause has bitten this family. The claim here was committed
+alone and pushed, but to the feature branch rather than `main` (protocol rule 5), because
+`origin/main` IS the live Space and pushing it is a deploy: rule 5 and the deploy model are in
+genuine tension on this repo. **What actually caught it was reading `SHOWCASE_STATUS.md` before
+updating it.** Practical check until rule 5 has a deploy-safe form here:
+`git fetch origin main && git show origin/main:docs/adr/RESERVED.md` *before* claiming.
+
+**Weekly job added the same day** (`.github/workflows/curation-freshness.yml`, Mondays 07:00 UTC +
+`workflow_dispatch`, report-only). **It does not run, and the file says so in its own header rather
+than looking green.** `origin` IS the HF Space and HuggingFace does not execute GitHub Actions —
+and unlike **every** sibling (`DecoupleRpy_Agent`, `pdac-subtype-agent`,
+`pdac-analysis-orchestrator`, each of which carries a second `github` remote),
+**this repo has no GitHub mirror at all**, so it has never had CI of any kind. Committed anyway on
+the `DecoupleRpy_Agent/.github/workflows/security.yml` precedent: the definition never forks, and
+adding the mirror later is then zero work. **The one remaining ops step is creating
+`Anne-Voigt/pdac-genomics-agent` on GitHub and `git push github main`** — that turns the check on
+and gives the repo CI. A local launchd agent was deliberately NOT installed: a job that runs on one
+laptop is invisible to everyone else, which is how the original gap happened. A test
+(`test_weekly_job_is_report_only`) asserts the job can never gain a writing `src.curate` step —
+that would re-establish the unattended API path C4 removed, in a file nobody reads once it is
+green. 122 tests.
+
+**Deployed 2026-07-28** (`6f23703` → live; a third lane's `4b8cb52` landed on top minutes later and
+the Space is RUNNING at that sha, which contains ours). Rebased onto `fdfbfb3` (the machine-auth
+diagnosis lane) before pushing — **126 tests green** with both lanes' changes together, up from our
+122. **Verified in prod, not just RUNNING:** `paad_tcga` → 186 samples, KRAS 136, TP53 104 —
+identical to local and to the original spike — and `citation.curation` serves
+`level: current, age_days: 2, source_import_date: 2026-01-12, drift_comparable: true`, confirming
+the backfill landed in the artifacts the Space actually reads.
+
+Not a bug, but worth knowing before someone loses an hour to it: the machine endpoints take
+`genes` as a **comma-separated string** (`_split_genes`), not a list. Passing a Python list returns
+`{"status":"error","reason":"AttributeError: 'list' object has no attribute 'split'"}` — an
+unhelpful message for what is a caller-side mistake, and the same class of lookalike-error problem
+the machine-auth lane just fixed for denials.
+
+---
+
 ## 2026-07-28 — Cohort survey; +2 curated (6 total); per-GENE coverage gate added
 
 Surveyed all 538 cBioPortal studies for pancreatic cohorts and curated the two that earned it.

src/curate.py

@@ -5,6 +5,7 @@ Run by a developer, on purpose, rarely::
     python -m src.curate paad_tcga
     python -m src.curate paad_tcga ccle_broad_2019 --dry-run
     python -m src.curate --list
+    python -m src.curate --check          # drift/age report, no re-curation, exit 1 if stale
 
 It fetches a study's mutation + discrete-CNV calls plus the clinical attributes the request
 path needs, classifies everything through the same `variant_status` rules the live path always
@@ -18,6 +19,11 @@ someone looked at.
 
 **Politeness (condition C3).** Studies are curated serially with a pause between them, and the
 client self-throttles. Curation is a handful of requests per study, not a crawl.
+
+**Cadence (ADR-0007).** Re-curation is event-driven, not scheduled: `--check` costs one metadata
+request per study and tells you whether upstream re-imported the study since we curated it. Only
+then is a re-pull worth making. `--check` never writes — refreshing an artifact stays a reviewed
+commit, because that reviewability is the whole reason the artifacts are in git.
 """
 
 from __future__ import annotations
@@ -101,7 +107,11 @@ def curate(study_id: str, *, dry_run: bool = False) -> dict:
     )
     clinical = fetch_clinical(study_id)
     payload = curated_store.build_payload(
-        matrix, study_id=study_id, clinical=clinical, terms=terms
+        matrix,
+        study_id=study_id,
+        clinical=clinical,
+        terms=terms,
+        import_date=metadata.get("importDate"),
     )
     counts = payload["counts"]
     print(
@@ -121,6 +131,88 @@ def curate(study_id: str, *, dry_run: bool = False) -> dict:
     return payload
 
 
+def check(study_ids: list[str] | None = None) -> tuple[list[dict], int]:
+    """Staleness CHECK — report drift without re-curating anything (ADR-0007).
+
+    One `/studies/<id>` request per study: compare upstream's `importDate` against the one
+    recorded when we curated, and report the artifact's age. That is the whole point of driving
+    off an upstream signal rather than a calendar — a cohort that upstream has not re-imported
+    needs no refresh no matter how old our file is, and re-pulling it on a monthly timer would
+    spend the C3 politeness budget to rewrite a byte-identical artifact.
+
+    This is a maintainer/CI tool, not a request-path one: it *reads* artifacts and never writes.
+    Re-curation stays a deliberate, reviewed commit — a checker that repaired what it found
+    would put the API back on an automatic path, which is exactly what C4 removed.
+
+    Returns `(rows, exit_code)`. Exit code 1 on any drift or `stale` artifact, so CI can fail.
+    """
+    studies = list(study_ids) if study_ids else curated_store.list_curated()
+    if not studies:
+        print("(no curated studies)")
+        return [], 0
+
+    rows: list[dict] = []
+    for i, study in enumerate(studies):
+        if i:
+            time.sleep(INTER_STUDY_PAUSE_S)
+        fresh = curated_store.freshness(study)
+        if fresh is None:
+            rows.append({"study": study, "state": "not_curated"})
+            continue
+        row = {
+            "study": study,
+            "age_days": fresh["age_days"],
+            "level": fresh["level"],
+            "curated_import_date": fresh["source_import_date"],
+        }
+        try:
+            row["upstream_import_date"] = cbioportal_io.study_metadata(study).get("importDate")
+        except Exception as exc:  # noqa: BLE001 — an unreachable API is a check failure, not drift
+            row["state"] = "check_failed"
+            row["error"] = f"{type(exc).__name__}: {exc}"
+            rows.append(row)
+            continue
+        if not fresh["drift_comparable"]:
+            # Pre-ADR-0007 artifact: no recorded importDate to compare against. Say so — an
+            # unknown is not a "no drift".
+            row["state"] = "drift_unknown"
+        elif row["upstream_import_date"] != row["curated_import_date"]:
+            row["state"] = "drift"
+        else:
+            row["state"] = "up_to_date"
+        rows.append(row)
+
+    print(f"{'study':<24} {'state':<14} {'age':>6}  upstream importDate")
+    for row in rows:
+        age = "?" if row.get("age_days") is None else f"{row['age_days']}d"
+        print(
+            f"{row['study']:<24} {row.get('state', '?'):<14} {age:>6}  "
+            f"{row.get('upstream_import_date') or '-'}"
+            + (f"  (curated from {row['curated_import_date']})" if row.get("state") == "drift" else "")
+            + (f"  {row.get('error')}" if row.get("error") else "")
+        )
+
+    drifted = [r["study"] for r in rows if r.get("state") == "drift"]
+    stale = [r["study"] for r in rows if r.get("level") == "stale"]
+    unknown = [r["study"] for r in rows if r.get("state") == "drift_unknown"]
+    if unknown:
+        print(
+            f"\nNo recorded upstream importDate for: {', '.join(unknown)} — curated before "
+            "ADR-0007. Drift cannot be established for these until they are next re-curated."
+        )
+    if drifted:
+        print(f"\nUpstream has re-imported since we curated: {', '.join(drifted)}")
+        print(f"Review and re-curate deliberately: python -m src.curate {' '.join(drifted)}")
+    if stale:
+        print(
+            f"\nPast the {curated_store.STALE_AFTER_DAYS}-day horizon: {', '.join(stale)} "
+            "(answers still serve, and say their age)."
+        )
+    if not drifted and not stale:
+        print("\nAll curated artifacts are within the review horizon and match upstream.")
+    return rows, (1 if (drifted or stale) else 0)
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="python -m src.curate", description=__doc__.splitlines()[0]
@@ -128,6 +220,12 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("studies", nargs="*", help="cBioPortal study ids, e.g. paad_tcga")
     parser.add_argument("--list", action="store_true", help="list already-curated studies")
     parser.add_argument("--dry-run", action="store_true", help="fetch and report, do not write")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="report artifact age + upstream drift without re-curating; exit 1 if any drifted "
+        "or is past the stale horizon (CI-friendly)",
+    )
     args = parser.parse_args(argv)
 
     if args.list:
@@ -135,8 +233,12 @@ def main(argv: list[str] | None = None) -> int:
         print("\n".join(curated) if curated else "(no curated studies)")
         return 0
 
+    if args.check:
+        print(f"[check] User-Agent: {cbioportal_io.user_agent()}\n")
+        return check(args.studies)[1]
+
     if not args.studies:
-        parser.error("give at least one study id, or --list")
+        parser.error("give at least one study id, --check, or --list")
 
     # C3: show what we are identifying ourselves as, so an operator can see it in one place.
     # The +URL in the User-Agent is the contact channel; no extra config is required.

src/resources/curated/ccle_broad_2019.json

@@ -7328,7 +7328,7 @@
     "n_mutated_cells": 3485,
     "n_samples": 1739
   },
-  "curated_at": "2026-07-28T19:28:30.612841+00:00",
+  "curated_at": "2026-07-28T23:39:38.203680+00:00",
   "genes_assayed": null,
   "modalities": {
     "cnv": true,
@@ -14401,7 +14401,7 @@
     "ELAVL1\tDJM1_SKIN": "ELAVL1 E6K",
     "ELAVL1\tDV90_LUNG": "ELAVL1 G58*",
     "ELAVL1\tEN_ENDOMETRIUM": "ELAVL1 X58_splice",
-    "ELAVL1\tGP2D_LARGE_INTESTINE": "ELAVL1 T143A",
+    "ELAVL1\tGP2D_LARGE_INTESTINE": "ELAVL1 R115W",
     "ELAVL1\tGP5D_LARGE_INTESTINE": "ELAVL1 R115W",
     "ELAVL1\tHCC1428_BREAST": "ELAVL1 N280S",
     "ELAVL1\tHEC108_ENDOMETRIUM": "ELAVL1 A240T",
@@ -15943,7 +15943,7 @@
     "TGFBR2\tHEC6_ENDOMETRIUM": "TGFBR2 G586S",
     "TGFBR2\tHRT18_LARGE_INTESTINE": "TGFBR2 L477P",
     "TGFBR2\tHT115_LARGE_INTESTINE": "TGFBR2 R522*",
-    "TGFBR2\tKM12_LARGE_INTESTINE": "TGFBR2 L479P",
+    "TGFBR2\tKM12_LARGE_INTESTINE": "TGFBR2 S587F",
     "TGFBR2\tLN235_CENTRAL_NERVOUS_SYSTEM": "TGFBR2 F304L",
     "TGFBR2\tLNZ308_CENTRAL_NERVOUS_SYSTEM": "TGFBR2 R232W",
     "TGFBR2\tLNZTA3WT4_CENTRAL_NERVOUS_SYSTEM": "TGFBR2 R232W",
@@ -18717,6 +18717,7 @@
   ],
   "schema_version": 3,
   "source": "cbioportal:ccle_broad_2019",
+  "source_import_date": "2026-01-05 21:05:38",
   "study": "ccle_broad_2019",
   "terms": {
     "access_tier": "open",

src/resources/curated/paad_qcmg_uq_2016.json

@@ -924,7 +924,7 @@
     "n_mutated_cells": 932,
     "n_samples": 456
   },
-  "curated_at": "2026-07-28T19:28:38.629322+00:00",
+  "curated_at": "2026-07-28T23:39:47.011537+00:00",
   "genes_assayed": null,
   "modalities": {
     "cnv": false,
@@ -3705,6 +3705,7 @@
   ],
   "schema_version": 3,
   "source": "cbioportal:paad_qcmg_uq_2016",
+  "source_import_date": "2026-01-12 13:30:07",
   "study": "paad_qcmg_uq_2016",
   "terms": {
     "access_tier": "open",

src/resources/curated/paad_tcga.json

@@ -1672,7 +1672,7 @@
     "n_mutated_cells": 350,
     "n_samples": 186
   },
-  "curated_at": "2026-07-28T19:28:08.341270+00:00",
+  "curated_at": "2026-07-28T23:39:26.922919+00:00",
   "genes_assayed": null,
   "modalities": {
     "cnv": true,
@@ -2964,6 +2964,7 @@
   ],
   "schema_version": 3,
   "source": "cbioportal:paad_tcga",
+  "source_import_date": "2026-01-12 13:01:54",
   "study": "paad_tcga",
   "terms": {
     "access_tier": "open",

src/resources/curated/paad_utsw_2015.json

@@ -1576,7 +1576,7 @@
     "n_mutated_cells": 222,
     "n_samples": 109
   },
-  "curated_at": "2026-07-28T19:28:46.756019+00:00",
+  "curated_at": "2026-07-28T23:39:56.327392+00:00",
   "genes_assayed": null,
   "modalities": {
     "cnv": true,
@@ -2203,6 +2203,7 @@
   ],
   "schema_version": 3,
   "source": "cbioportal:paad_utsw_2015",
+  "source_import_date": "2026-01-12 13:08:04",
   "study": "paad_utsw_2015",
   "terms": {
     "access_tier": "open",

src/resources/curated/pancreas_cptac_gdc.json

@@ -926,7 +926,7 @@
     "n_mutated_cells": 411,
     "n_samples": 183
   },
-  "curated_at": "2026-07-28T19:28:54.461154+00:00",
+  "curated_at": "2026-07-28T23:40:06.073894+00:00",
   "genes_assayed": null,
   "modalities": {
     "cnv": true,
@@ -2339,6 +2339,7 @@
   ],
   "schema_version": 3,
   "source": "cbioportal:pancreas_cptac_gdc",
+  "source_import_date": "2026-01-14 11:11:19",
   "study": "pancreas_cptac_gdc",
   "terms": {
     "access_tier": "open",

src/resources/curated/pdac_msk_2024.json

@@ -5373,7 +5373,7 @@
     "n_mutated_cells": 5970,
     "n_samples": 2336
   },
-  "curated_at": "2026-07-28T19:29:05.834992+00:00",
+  "curated_at": "2026-07-28T23:40:19.051177+00:00",
   "genes_assayed": [
     "KRAS",
     "TP53",
@@ -19738,6 +19738,7 @@
   ],
   "schema_version": 3,
   "source": "cbioportal:pdac_msk_2024",
+  "source_import_date": "2026-01-13 10:24:41",
   "study": "pdac_msk_2024",
   "terms": {
     "access_tier": "open",

src/tools/query_variant_status.py

@@ -131,7 +131,9 @@ def query_variant_status(genes: list[str], source: str) -> dict:
         "unassayed_genes": unassayed,  # explicit, so a caller can SAY what was not measured
         "genes": out_genes,
         # C1 (ADR-0005 / cBioPortal terms): attribution rides the response contract itself.
-        "citation": citation_block(sm.source, getattr(sm, "terms", None)),
+        "citation": citation_block(
+            sm.source, getattr(sm, "terms", None), getattr(sm, "curation", None)
+        ),
     }
 
 

src/tools/variant_by_subtype.py

@@ -115,7 +115,9 @@ def variant_by_subtype(
             "Subtype label is a pre-existing cohort clinical attribute, not a live PurIST call.",
             "Association is descriptive (no multiple-testing correction across genes here).",
         ],
-        "citation": citation_block(sm.source, getattr(sm, "terms", None)),
+        "citation": citation_block(
+            sm.source, getattr(sm, "terms", None), getattr(sm, "curation", None)
+        ),
     }
 
 

src/workflows/curated_store.py

@@ -41,6 +41,25 @@ SCHEMA_VERSION = 3
 
 ARTIFACT_DIR = Path(__file__).resolve().parents[1] / "resources" / "curated"
 
+# --------------------------------------------------------------------------- #
+# Re-curation cadence (ADR-0007)
+# --------------------------------------------------------------------------- #
+# An artifact is a point-in-time snapshot. It carried `curated_at` from the start, but nothing
+# read it — so a cohort could drift from upstream for years and every answer would look equally
+# confident. These two horizons make age *visible*; they never make an answer refuse.
+#
+# The horizons are a BACKSTOP, not the primary signal. The primary signal is upstream's own
+# `importDate` (`python -m src.curate --check`), because cBioPortal studies are versioned
+# releases that change rarely: a published cohort like `paad_tcga` can be correct for years, and
+# re-curating it on a calendar is churn that spends the C3 politeness budget for no new data.
+# Time-based horizons exist only to catch the case where nobody ran the check either.
+#
+# 180 days = "a human should look" (roughly one release cycle for the refreshed cohorts, e.g.
+# CCLE). 365 days = "say so in the answer itself" — a year is long enough that a reader acting
+# on the number deserves to be told, whether or not anything upstream actually moved.
+REVIEW_AFTER_DAYS = 180
+STALE_AFTER_DAYS = 365
+
 # Clinical attributes an artifact must carry for the request path to stay offline:
 # lineage (pan-cancer subsetting) + every subtype label the join knows how to use.
 LINEAGE_ATTRIBUTES = ["CANCER_TYPE", "ONCOTREE_CODE"]
@@ -89,12 +108,21 @@ def write(payload: dict) -> Path:
     return path
 
 
-def build_payload(matrix, *, study_id: str, clinical: dict, terms: dict) -> dict:
+def build_payload(
+    matrix, *, study_id: str, clinical: dict, terms: dict, import_date: str | None = None
+) -> dict:
     """Serialize a live-built `StatusMatrix` + its clinical attributes into an artifact.
 
     Sparse: only cells that differ from the implied baseline (`WT` / `neutral`) are kept.
     `terms` is the per-study license/access block (condition C2), stored so the serve path can
     re-check it without the API and so every answer can carry it.
+
+    `import_date` is upstream's own `importDate` for the study *as of this curation* (ADR-0007).
+    It is what makes drift detectable without re-curating: `--check` fetches one metadata record
+    and compares. **Deliberately NOT a schema bump** — the four artifacts curated before the
+    cadence existed simply lack the field, and refusing them would force exactly the blanket
+    re-curation this cadence is designed to avoid. Absence degrades to "drift not comparable",
+    which the check reports honestly instead of guessing.
     """
     def _sparse(frame, baseline: str) -> dict:
         if frame is None:
@@ -112,6 +140,7 @@ def build_payload(matrix, *, study_id: str, clinical: dict, terms: dict) -> dict
         "terms": terms,
         "source": matrix.source,
         "curated_at": datetime.now(UTC).isoformat(),
+        "source_import_date": import_date,
         "panel_genes": list(matrix.genes),
         # Per-GENE assay coverage for targeted cohorts (null = genome/exome-wide, all covered).
         # Not a schema bump: every artifact written before this key existed came from a
@@ -142,6 +171,84 @@ def build_payload(matrix, *, study_id: str, clinical: dict, terms: dict) -> dict
     }
 
 
+def _parse_ts(value: str | None) -> datetime | None:
+    """Parse an ISO timestamp, tolerating a missing/naive/garbage value.
+
+    A freshness *display* must never be the thing that breaks an answer, so an unparseable
+    `curated_at` reports "unknown age" rather than raising on the request path.
+    """
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+
+
+def freshness_from_payload(payload: dict, *, now: datetime | None = None) -> dict:
+    """How old this artifact is, and whether that is worth saying out loud (ADR-0007).
+
+    Returned with every grounded answer via `licenses.citation_block`, because the person
+    acting on a frequency is the one who needs to know the snapshot is from 2026. Provenance
+    that stops at the storage layer is provenance nobody honours — the same argument that put
+    `terms` in the response contract.
+
+    `level` is advisory in all three states. **Nothing here refuses.** A stale-but-valid cohort
+    is old, not wrong: the numbers were correct for the release they were curated from, and
+    withholding a correct answer because a maintainer missed a review window would trade a real
+    answer for a maintenance signal. Refusal is reserved for the gates where the answer would
+    be *incorrect* — genome build, species, absent modality, controlled access.
+    """
+    now = now or datetime.now(UTC)
+    curated_at = payload.get("curated_at")
+    parsed = _parse_ts(curated_at)
+    age_days = None if parsed is None else max(0, (now - parsed).days)
+
+    if age_days is None:
+        level = "unknown"
+        note = (
+            "This cohort's artifact carries no readable curation date, so its age cannot be "
+            "stated. Re-curate it to restore the provenance."
+        )
+    elif age_days >= STALE_AFTER_DAYS:
+        level = "stale"
+        note = (
+            f"This cohort was curated {age_days} days ago and has not been refreshed since. "
+            "The status calls were correct for the upstream release they were curated from; "
+            "check whether that release has been superseded before relying on them."
+        )
+    elif age_days >= REVIEW_AFTER_DAYS:
+        level = "review_due"
+        note = (
+            f"This cohort was curated {age_days} days ago and is due a re-curation review "
+            "(`python -m src.curate --check`)."
+        )
+    else:
+        level = "current"
+        note = f"Curated {age_days} days ago from the upstream release named below."
+
+    return {
+        "curated_at": curated_at,
+        "age_days": age_days,
+        "level": level,
+        "note": note,
+        # Upstream's release stamp as of curation. `None` on artifacts predating ADR-0007 —
+        # reported as such rather than silently treated as "no drift".
+        "source_import_date": payload.get("source_import_date"),
+        "drift_comparable": payload.get("source_import_date") is not None,
+        "review_after_days": REVIEW_AFTER_DAYS,
+        "stale_after_days": STALE_AFTER_DAYS,
+    }
+
+
+def freshness(study_id: str, *, now: datetime | None = None) -> dict | None:
+    """`freshness_from_payload` for a curated study id; None if it is not curated."""
+    if not is_curated(study_id):
+        return None
+    return freshness_from_payload(read(study_id), now=now)
+
+
 def study_terms(study_id: str) -> dict | None:
     """The cached per-study license/access block (C2), or None if the study is not curated."""
     if not is_curated(study_id):

src/workflows/variant_status.py

@@ -132,6 +132,9 @@ class StatusMatrix:
     # full cohort silently counts it as one (paad_tcga: 186 samples, 150 sequenced -> KRAS
     # reads 73% instead of its true 91%).
     profiled: dict = None  # {"mutation": [ids] | None, "cnv": [ids] | None}
+    # Artifact age / upstream-release provenance (ADR-0007). None for BYOD and for a
+    # freshly-curated in-memory matrix — an artifact that was never written has no age.
+    curation: dict | None = None
 
     def __post_init__(self):
         if self.profiled is None:
@@ -252,6 +255,7 @@ def _from_artifact(payload: dict, *, restrict: list[str] | None) -> StatusMatrix
         terms=payload.get("terms"),
         genes_assayed=payload.get("genes_assayed"),
         profiled=payload.get("profiled") or {},
+        curation=curated_store.freshness_from_payload(payload),
     )
 
 

tests/test_machine_api_auth.py

@@ -110,3 +110,60 @@ def test_empty_genes_falls_back_to_full_panel():
     """The machine contract sends a comma-separated string; empty means 'the whole panel'."""
     assert gradio_ui._split_genes("") == list(gradio_ui.PANEL)
     assert gradio_ui._split_genes("kras, tp53") == ["KRAS", "TP53"]
+
+
+# --------------------------------------------------------------------------- #
+# Denial DIAGNOSIS — the three failure modes must be distinguishable
+# --------------------------------------------------------------------------- #
+# Regression guard for a real misdiagnosis (2026-07-27→28). The orchestrator was denied and
+# the response said "Please sign in with your HuggingFace account", so the investigation went
+# server-side — probing headers, suspecting `whoami`. Nothing was wrong here: the caller had
+# simply sent no header at all (its own HF_TOKEN was unset). These three states are
+# operationally different and must never again be one indistinguishable message.
+
+
+def test_no_token_header_is_diagnosed_as_caller_misconfiguration(monkeypatch):
+    monkeypatch.setattr(gradio_ui, "_query_variant_status", _explode)
+    body = json.loads(gradio_ui.query_variant_status(source="x", request=_Request()))
+
+    assert body["status"] == "denied"
+    assert body["machine_auth"] == "no_token_header"
+    # names the calling Space's secret, and does NOT tell a machine to sign in
+    assert "HF_TOKEN" in body["reason"]
+    assert "sign in" not in body["reason"].lower()
+
+
+def test_unresolvable_token_is_diagnosed_separately_from_a_missing_one(monkeypatch):
+    monkeypatch.setattr(gradio_ui, "_resolve_token_identity", lambda token: None)
+    monkeypatch.setattr(gradio_ui, "_query_variant_status", _explode)
+
+    body = json.loads(
+        gradio_ui.query_variant_status(
+            source="x", request=_Request({"x-orchestrator-token": "bad-token"})
+        )
+    )
+
+    assert body["machine_auth"] == "token_unresolved"
+
+
+def test_resolved_but_unlisted_identity_is_the_only_real_authorization_denial(monkeypatch):
+    """Identity resolved fine — this one IS an allow-list decision, and still names who."""
+    monkeypatch.setattr(gradio_ui, "_resolve_token_identity", lambda token: "stranger-bot")
+    monkeypatch.setattr(gradio_ui, "_query_variant_status", _explode)
+
+    body = json.loads(
+        gradio_ui.query_variant_status(
+            source="x", request=_Request({"x-orchestrator-token": "good-token"})
+        )
+    )
+
+    assert body["machine_auth"] == "not_allowlisted"
+    assert "stranger-bot" in body["reason"]
+
+
+def test_identity_resolution_reports_resolved_on_success(monkeypatch):
+    monkeypatch.setattr(gradio_ui, "_resolve_token_identity", lambda token: "orchestrator-bot")
+    identity, diagnosis = gradio_ui._machine_caller_identity(
+        _Request({"x-orchestrator-token": "good-token"})
+    )
+    assert (identity, diagnosis) == ("orchestrator-bot", "resolved")

tests/test_recuration_cadence.py

@@ -0,0 +1,203 @@
+"""Re-curation cadence — artifact age is visible, and never a refusal (ADR-0007).
+
+Two claims are load-bearing here:
+
+1. `test_stale_artifact_still_answers` — the whole decision. A stale cohort is old, not wrong,
+   so the answer must still be produced *and* must say its age. A future change that turns
+   staleness into a refusal breaks this test, which is the point.
+2. `test_check_makes_one_metadata_call_per_study` — the cadence is driven by upstream's
+   `importDate`, not a calendar, and checking costs one request per study rather than a re-pull.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from src import curate
+from src.tools.query_variant_status import query_variant_status
+from src.workflows import cbioportal_io, curated_store
+
+
+def _age_artifact(study: str, days: int, *, import_date: str | None = "2026-01-01 00:00:00"):
+    """Rewrite a curated artifact's dates in place (test-local; curation is normally the writer)."""
+    payload = curated_store.read(study)
+    payload["curated_at"] = (datetime.now(UTC) - timedelta(days=days)).isoformat()
+    payload["source_import_date"] = import_date
+    curated_store.write(payload)
+    return payload
+
+
+# --------------------------------------------------------------------------- #
+# Freshness levels
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize(
+    ("days", "expected"),
+    [
+        (1, "current"),
+        (curated_store.REVIEW_AFTER_DAYS + 1, "review_due"),
+        (curated_store.STALE_AFTER_DAYS + 1, "stale"),
+    ],
+)
+def test_freshness_levels(patched_cbio, days, expected):
+    _age_artifact("paad_tcga", days)
+    assert curated_store.freshness("paad_tcga")["level"] == expected
+
+
+def test_unparseable_curated_at_reports_unknown_not_crash(patched_cbio):
+    """A broken date must degrade to 'unknown age', never take an answer down with it."""
+    payload = curated_store.read("paad_tcga")
+    payload["curated_at"] = "not-a-date"
+    curated_store.write(payload)
+
+    fresh = curated_store.freshness("paad_tcga")
+    assert fresh["level"] == "unknown"
+    assert fresh["age_days"] is None
+    # and the tool still answers
+    assert query_variant_status(["KRAS"], "cbioportal:paad_tcga")["n_samples"] == 5
+
+
+def test_missing_import_date_is_not_reported_as_no_drift(patched_cbio):
+    """Artifacts predating ADR-0007 carry no importDate — that is an unknown, not a match."""
+    _age_artifact("paad_tcga", 10, import_date=None)
+    assert curated_store.freshness("paad_tcga")["drift_comparable"] is False
+
+
+# --------------------------------------------------------------------------- #
+# Visibility: the age rides in the answer
+# --------------------------------------------------------------------------- #
+def test_answer_carries_the_curation_block(patched_cbio):
+    """Every grounded answer states its snapshot age, next to the citation and terms."""
+    result = query_variant_status(["KRAS"], "cbioportal:paad_tcga")
+    curation = result["citation"]["curation"]
+
+    assert curation["level"] == "current"
+    assert curation["age_days"] is not None
+    assert curation["curated_at"]
+
+
+def test_stale_artifact_still_answers_and_says_so(patched_cbio):
+    """THE decision (ADR-0007): stale is visible, not refused.
+
+    A stale-but-valid cohort was correct for the upstream release it was curated from. Refusing
+    it would withhold a correct answer over a maintenance lapse — refusal stays reserved for the
+    gates where the answer would be *wrong* (build, species, modality, access tier).
+    """
+    _age_artifact("paad_tcga", curated_store.STALE_AFTER_DAYS + 30)
+
+    result = query_variant_status(["KRAS"], "cbioportal:paad_tcga")
+
+    assert result["n_samples"] == 5  # the answer is intact
+    assert "KRAS" in result["genes"]
+    curation = result["citation"]["curation"]
+    assert curation["level"] == "stale"
+    assert str(curation["age_days"]) in curation["note"]
+
+
+def test_ui_surfaces_stale_note(patched_cbio):
+    """Past the horizon the page says so — a date only in the JSON is a date nobody reads."""
+    from gradio_ui import _freshness_caution
+
+    _age_artifact("paad_tcga", curated_store.STALE_AFTER_DAYS + 5)
+    stale = query_variant_status(["KRAS"], "cbioportal:paad_tcga")
+    assert "Snapshot age" in _freshness_caution(stale)
+
+    _age_artifact("paad_tcga", 5)
+    fresh = query_variant_status(["KRAS"], "cbioportal:paad_tcga")
+    assert _freshness_caution(fresh) == ""  # and stays quiet when there is nothing to say
+
+
+# --------------------------------------------------------------------------- #
+# `--check`: upstream-signal drift, cheap and read-only
+# --------------------------------------------------------------------------- #
+def test_check_detects_drift_and_exits_nonzero(patched_cbio, monkeypatch):
+    _age_artifact("paad_tcga", 10, import_date="2026-01-01 00:00:00")
+    monkeypatch.setattr(
+        cbioportal_io, "study_metadata", lambda s: {"importDate": "2026-07-01 00:00:00"}
+    )
+    monkeypatch.setattr(curate.time, "sleep", lambda *_: None)
+
+    rows, code = curate.check(["paad_tcga"])
+
+    assert rows[0]["state"] == "drift"
+    assert code == 1
+
+
+def test_check_reports_up_to_date_when_upstream_matches(patched_cbio, monkeypatch):
+    _age_artifact("paad_tcga", 10, import_date="2026-01-01 00:00:00")
+    monkeypatch.setattr(
+        cbioportal_io, "study_metadata", lambda s: {"importDate": "2026-01-01 00:00:00"}
+    )
+    rows, code = curate.check(["paad_tcga"])
+
+    assert rows[0]["state"] == "up_to_date"
+    assert code == 0
+
+
+def test_check_makes_one_metadata_call_per_study_and_writes_nothing(patched_cbio, monkeypatch):
+    """The cadence is cheap by construction: a check is metadata, not a re-pull (C3).
+
+    It must also not mutate artifacts — re-curation stays a reviewed commit, and a checker that
+    repaired what it found would put the API back on an automatic path (C4).
+    """
+    _age_artifact("paad_tcga", 10)
+    before = json.dumps(curated_store.read("paad_tcga"), sort_keys=True)
+
+    calls = []
+    monkeypatch.setattr(
+        cbioportal_io,
+        "study_metadata",
+        lambda s: calls.append(s) or {"importDate": "2026-01-01 00:00:00"},
+    )
+    for name in ("fetch_mutations", "fetch_molecular_data", "clinical_data", "entrez_ids"):
+        monkeypatch.setattr(
+            cbioportal_io,
+            name,
+            lambda *a, **k: pytest.fail("--check must not re-fetch variant data"),
+        )
+    monkeypatch.setattr(curate.time, "sleep", lambda *_: None)
+
+    curate.check(["paad_tcga"])
+
+    assert calls == ["paad_tcga"]
+    assert json.dumps(curated_store.read("paad_tcga"), sort_keys=True) == before
+
+
+def test_check_failure_is_not_reported_as_drift(patched_cbio, monkeypatch):
+    """An unreachable API means we do not know — it must not masquerade as a drift verdict."""
+
+    def _boom(_study):
+        raise RuntimeError("upstream down")
+
+    monkeypatch.setattr(cbioportal_io, "study_metadata", _boom)
+    rows, code = curate.check(["paad_tcga"])
+
+    assert rows[0]["state"] == "check_failed"
+    assert code == 0  # their outage is not our staleness
+
+
+# --------------------------------------------------------------------------- #
+# The scheduled job
+# --------------------------------------------------------------------------- #
+def test_weekly_job_is_report_only():
+    """The scheduled freshness job must invoke `--check` and nothing that writes.
+
+    The whole cadence rests on re-curation being a reviewed commit. A job that quietly gained a
+    `python -m src.curate <study>` step would re-establish the unattended API path ADR-0005 C4
+    removed — and it would do it in a file nobody reads once it is green.
+    """
+    from pathlib import Path
+
+    workflow = Path(__file__).resolve().parents[1] / ".github/workflows/curation-freshness.yml"
+    assert workflow.is_file(), "the weekly freshness job is missing"
+
+    runs = [
+        line.strip()
+        for line in workflow.read_text().splitlines()
+        if "src.curate" in line and not line.lstrip().startswith("#")
+    ]
+    assert runs, "the job does not invoke src.curate at all"
+    for line in runs:
+        assert "--check" in line, f"non-check curate invocation in the scheduled job: {line}"