PR 7.2.1: agent-reviewable release artifacts

.github/workflows/ci.yml

@@ -62,6 +62,29 @@ jobs:
           include-hidden-files: true
           if-no-files-found: ignore
 
+  release-artifacts-sync:
+    name: Release artifacts in sync (PR 7.2.1)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      # Each script's --check mode reports drift as exit-code-1 without
+      # touching disk; the verifier is exit-code-1 on a real claim drift.
+      # Running them in CI is the only way the audit-sync guarantee
+      # actually holds — without this job, a stale metrics.json /
+      # claims_register / docs/ copy could land on main unnoticed.
+      - name: docs/ vendored copies are in sync
+        run: python scripts/sync_release_docs.py --check
+      - name: release/metrics.json + per-tier metrics.json are in sync
+        run: python scripts/build_release_metrics.py --check
+      - name: release/claims_register.{md,json} are in sync with source.yaml
+        run: python scripts/build_claims_register.py --check
+      - name: every claim in claims_register_source.yaml resolves & values match
+        run: python scripts/verify_claims_register.py
+
   validate-dataset:
     name: Validate lead scoring dataset
     runs-on: ubuntu-latest

release/README.md

@@ -29,13 +29,17 @@ rose materially in 2024).
 release/
 ├── intro/ intermediate/ advanced/    # student_public bundles, one per difficulty tier
 │   ├── manifest.json                 # provenance + file hashes
+│   ├── metrics.json                  # per-tier headline metrics (medians + spreads)
 │   ├── dataset_card.md               # auto-rendered per-bundle card
 │   ├── feature_dictionary.csv        # authoritative column spec
 │   ├── lead_scoring.csv              # flat convenience CSV (all splits)
 │   ├── tables/*.parquet              # 7 snapshot-safe relational tables
 │   └── tasks/converted_within_90_days/{train,valid,test}.parquet
 ├── intermediate_instructor/          # research companion: full-horizon tables + metadata/
+├── docs/                             # vendored DGP / leakage / break-me docs (agent-readable)
 ├── notebooks/                        # 01 baseline · 02 relational · 03 leakage · 04 calibration
+├── metrics.json                      # top-level cross-tier metrics summary
+├── claims_register.{md,json}         # claims → backing-artifact map (agent-readable)
 └── validation/                       # validation_report.{json,md} + figures
 ```
 
@@ -45,6 +49,35 @@ hidden causal structure (DAG, latent registry, mechanism summary)
 under `metadata/`. The full layout is documented in each bundle's
 `manifest.json`.
 
+### Agent-reviewable artifacts
+
+The published bundle is self-contained for AI review and offline
+auditing — every numeric / structural claim on this page can be
+verified without following an external link:
+
+- **`metrics.json` (root) + `<tier>/metrics.json`** — deterministic
+  JSON view of the headline LR AUC / AP / P@100 / Brier / conversion
+  rate / cohort-shift / cross-tier-ordering medians, with JSON-path
+  back-references to `validation/validation_report.json` (the
+  source of truth).
+- **`claims_register.{md,json}`** — every numerical or structural
+  claim on this page paired with the artifact and path that backs it.
+  Rendered from `claims_register_source.yaml` by
+  `scripts/build_claims_register.py`.
+- **`docs/`** — vendored copies of `generation_method.md`,
+  `channel_signal_audit.md`, `break_me_guide.md`,
+  `feature_dictionary.md`, `v1_acceptance_gates_bands.yaml`,
+  `v2_decision_log.md`, plus a hand-authored
+  `relational_table_schemas.csv` documenting every column of every
+  relational table.  These match the GitHub-blob links cited below but
+  ship inside the bundle so a reviewer never needs network access.
+- **`<tier>/manifest.json`** — SHA-256 hash for every file plus the
+  full redaction contract (`structural_redactions.columns`,
+  `omitted_tables`, `relational_snapshot_safe`, `snapshot_day`).
+- Kaggle / HuggingFace preview pages additionally inject a
+  `schema.org/Dataset` JSON-LD block in their `<head>` for agent
+  ingestion without HTML parsing.
+
 ## Quick start
 
 ```python

release/_preview_committed/huggingface_instructor.html

@@ -35,6 +35,50 @@
 .dataset-footer { margin-top: 48px; padding-top: 16px; border-top: 1px solid var(--border); color: var(--muted); font-size: 0.9em; }
 .dataset-footer__note { font-style: italic; margin-top: 8px; }
 </style>
+  <script type="application/ld+json">{
+  "@context": "https://schema.org",
+  "@type": "Dataset",
+  "citation": "Generated by leadforge (https://github.com/leadforge-dev/leadforge); recipe b2b_saas_procurement_v1, seed 42.",
+  "creator": {
+    "@type": "Organization",
+    "name": "leadforge"
+  },
+  "description": "Hugging Face preview of leadforge-lead-scoring-v1.",
+  "distribution": [
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intermediate/tasks/converted_within_90_days/train.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intermediate/tasks/converted_within_90_days/valid.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intermediate/tasks/converted_within_90_days/test.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    }
+  ],
+  "isAccessibleForFree": true,
+  "keywords": [
+    "b2b",
+    "crm",
+    "datasets",
+    "lead-scoring",
+    "pandas",
+    "synthetic-data",
+    "tabular"
+  ],
+  "license": "https://opensource.org/licenses/MIT",
+  "name": "LeadForge: Synthetic B2B Lead Scoring (v1) — Instructor companion",
+  "sameAs": [
+    "https://github.com/leadforge-dev/leadforge",
+    "https://huggingface.co/datasets/leadforge/leadforge-lead-scoring-v1"
+  ],
+  "version": "v1"
+}</script>
 </head>
 <body>
 <main class="container">
@@ -92,6 +136,8 @@ <h2>What this companion contains</h2>
 │   ├── tables/*.parquet              # full-horizon tables (incl. customers, subscriptions)
 │   ├── tasks/converted_within_90_days/{train,valid,test}.parquet
 │   └── metadata/                     # world_spec, graph.{graphml,json}, latent_registry, etc.
+├── docs/                             # vendored DGP / leakage / break-me docs (agent-readable)
+├── claims_register.{md,json}         # claims → backing-artifact map (agent-readable)
 ├── README.md                         # this file (HF dataset card)
 ├── dataset-cover-image.png           # dataset thumbnail
 └── LICENSE
@@ -218,6 +264,23 @@ <h2>Composition</h2>
 every parquet file.</li>
 <li><strong>Bundle schema version.</strong>  5 (matches the public dataset).</li>
 </ul>
+<h2>Agent-reviewable artifacts</h2>
+<p>The companion ships the same self-contained review surface as the public
+bundle so an AI reviewer (or a researcher without GitHub access) can
+verify claims locally:</p>
+<ul>
+<li><code>docs/</code> — vendored copies of the generation method, leakage probes
+contract, acceptance bands, break-me guide, v2 decision log, and the
+per-relational-table column descriptions (<code>relational_table_schemas.csv</code>).</li>
+<li><code>claims_register.{md,json}</code> — every numerical / structural claim
+in this card paired with the artifact and path that backs it.</li>
+<li><code>intermediate/manifest.json</code> and <code>intermediate/feature_dictionary.csv</code>
+— SHA-256-hashed provenance and the authoritative column spec.</li>
+</ul>
+<p>The instructor companion intentionally omits the top-level
+<code>metrics.json</code> (cross-tier medians would be misleading for a single
+tier).  Use the public dataset's <code>metrics.json</code> when comparing tier
+behaviour.</p>
 <h2>Maintenance, license</h2>
 <p>We <em>want</em> the dataset to be broken.  See the
 <a href="https://huggingface.co/datasets/leadforge/leadforge-lead-scoring-v1">public dataset card</a>

release/_preview_committed/huggingface_public.html

@@ -35,6 +35,80 @@
 .dataset-footer { margin-top: 48px; padding-top: 16px; border-top: 1px solid var(--border); color: var(--muted); font-size: 0.9em; }
 .dataset-footer__note { font-style: italic; margin-top: 8px; }
 </style>
+  <script type="application/ld+json">{
+  "@context": "https://schema.org",
+  "@type": "Dataset",
+  "citation": "Generated by leadforge (https://github.com/leadforge-dev/leadforge); recipe b2b_saas_procurement_v1, seed 42.",
+  "creator": {
+    "@type": "Organization",
+    "name": "leadforge"
+  },
+  "description": "Hugging Face preview of leadforge-lead-scoring-v1.",
+  "distribution": [
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intro/tasks/converted_within_90_days/train.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intro/tasks/converted_within_90_days/valid.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intro/tasks/converted_within_90_days/test.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intermediate/tasks/converted_within_90_days/train.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intermediate/tasks/converted_within_90_days/valid.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "intermediate/tasks/converted_within_90_days/test.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "advanced/tasks/converted_within_90_days/train.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "advanced/tasks/converted_within_90_days/valid.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    },
+    {
+      "@type": "DataDownload",
+      "contentUrl": "advanced/tasks/converted_within_90_days/test.parquet",
+      "encodingFormat": "application/vnd.apache.parquet"
+    }
+  ],
+  "isAccessibleForFree": true,
+  "keywords": [
+    "b2b",
+    "crm",
+    "datasets",
+    "lead-scoring",
+    "pandas",
+    "synthetic-data",
+    "tabular"
+  ],
+  "license": "https://opensource.org/licenses/MIT",
+  "name": "LeadForge: Synthetic B2B Lead Scoring (v1)",
+  "sameAs": [
+    "https://github.com/leadforge-dev/leadforge",
+    "https://huggingface.co/datasets/leadforge/leadforge-lead-scoring-v1"
+  ],
+  "version": "v1"
+}</script>
 </head>
 <body>
 <main class="container">
@@ -115,11 +189,15 @@ <h2>What's inside</h2>
 <pre><code>.
 ├── intro/ intermediate/ advanced/    # student_public bundles, one per difficulty tier
 │   ├── manifest.json                 # provenance + file hashes
+│   ├── metrics.json                  # per-tier headline metrics (medians + spreads)
 │   ├── dataset_card.md               # auto-rendered per-bundle card
 │   ├── feature_dictionary.csv        # authoritative column spec
 │   ├── lead_scoring.csv              # flat convenience CSV (all splits)
 │   ├── tables/*.parquet              # 7 snapshot-safe relational tables
 │   └── tasks/converted_within_90_days/{train,valid,test}.parquet
+├── docs/                             # vendored DGP / leakage / break-me docs (agent-readable)
+├── metrics.json                      # top-level cross-tier metrics summary
+├── claims_register.{md,json}         # claims → backing-artifact map (agent-readable)
 ├── README.md                         # this file (HF dataset card)
 ├── dataset-cover-image.png           # dataset thumbnail
 └── LICENSE
@@ -129,6 +207,34 @@ <h2>What's inside</h2>
 hidden causal structure (DAG, latent registry, mechanism summary)
 under <code>metadata/</code>. The full layout is documented in each bundle's
 <code>manifest.json</code>.</p>
+<h3>Agent-reviewable artifacts</h3>
+<p>The published bundle is self-contained for AI review and offline
+auditing — every numeric / structural claim on this page can be
+verified without following an external link:</p>
+<ul>
+<li><strong><code>metrics.json</code> (root) + <code>&lt;tier&gt;/metrics.json</code></strong> — deterministic
+JSON view of the headline LR AUC / AP / P@100 / Brier / conversion
+rate / cohort-shift / cross-tier-ordering medians, with JSON-path
+back-references to <code>validation/validation_report.json</code> (the
+source of truth).</li>
+<li><strong><code>claims_register.{md,json}</code></strong> — every numerical or structural
+claim on this page paired with the artifact and path that backs it.
+Rendered from <code>claims_register_source.yaml</code> by
+<code>scripts/build_claims_register.py</code>.</li>
+<li><strong><code>docs/</code></strong> — vendored copies of <code>generation_method.md</code>,
+<code>channel_signal_audit.md</code>, <code>break_me_guide.md</code>,
+<code>feature_dictionary.md</code>, <code>v1_acceptance_gates_bands.yaml</code>,
+<code>v2_decision_log.md</code>, plus a hand-authored
+<code>relational_table_schemas.csv</code> documenting every column of every
+relational table.  These match the GitHub-blob links cited below but
+ship inside the bundle so a reviewer never needs network access.</li>
+<li><strong><code>&lt;tier&gt;/manifest.json</code></strong> — SHA-256 hash for every file plus the
+full redaction contract (<code>structural_redactions.columns</code>,
+<code>omitted_tables</code>, <code>relational_snapshot_safe</code>, <code>snapshot_day</code>).</li>
+<li>Kaggle / HuggingFace preview pages additionally inject a
+<code>schema.org/Dataset</code> JSON-LD block in their <code>&lt;head&gt;</code> for agent
+ingestion without HTML parsing.</li>
+</ul>
 <h2>Quick start</h2>
 <pre><code class="language-python"># Flat CSV
 df = pd.read_csv(&quot;intermediate/lead_scoring.csv&quot;)