@dzhechkov/keysarium 1.5.33 → 1.5.35

package/.dz-manifest.json

@@ -13,7 +13,7 @@
       },
       {
         "path": "README.md",
-        "sha256": "0b1de0c5bd3bde4586c64bab4a3ab90a4313c8659f327bfa774d9fe9d7a268b7"
+        "sha256": "5f1e61279a3f6b18e7db46adab9860d3cc95ed31926b122bc8508bf445f11117"
       },
       {
         "path": "README.ru.md",
@@ -29,7 +29,7 @@
       },
       {
         "path": "package.json",
-        "sha256": "0869b59a6f7c9dfeb990cf4251d5d8dc7ce12c4b54a1c9a058e5caf12461d11f"
+        "sha256": "206ba50881c8dc2a62ab44af643f314928b52c0b711757f9e1a3d1b0312724bb"
       },
       {
         "path": "scripts/sync-templates.js",
@@ -297,7 +297,7 @@
       },
       {
         "path": "templates/.claude/skills/edu-site-generator/SKILL.md",
-        "sha256": "24c5e069fa0aead7584bd5adb0136107da0339da0ff92460f6f16435b73904fd"
+        "sha256": "c999b07ed76c289e1433cfea0b59abd8723d9c36455f76dc2fd8a3c6cf064bcf"
       },
       {
         "path": "templates/.claude/skills/edu-site-generator/examples/sample-course-structure.md",
@@ -353,7 +353,7 @@
       },
       {
         "path": "templates/.claude/skills/explore/SKILL.md",
-        "sha256": "254b51db25336fcc09317b5ac297448c5da7c3e218a21018c10ec3dd8970d964"
+        "sha256": "2473e7961845db0d64566cd42627b374d1830664b9e302058a1b1aa466bc7361"
       },
       {
         "path": "templates/.claude/skills/explore/references/questioning-techniques.md",
@@ -365,7 +365,7 @@
       },
       {
         "path": "templates/.claude/skills/feature-adr/SKILL.md",
-        "sha256": "ca6daf5b3470061dd9b0243236f5657fb4d3ad9dbcd1f7b7c30ef0a498f7f905"
+        "sha256": "c422d1e2b50cf7b8bd56cd5d886d96af30d8bf33a468b925396f395ebf32de53"
       },
       {
         "path": "templates/.claude/skills/feature-adr/examples/sample-feature-output.md",
@@ -505,11 +505,11 @@
       },
       {
         "path": "templates/.claude/skills/frontend-design/SKILL.md",
-        "sha256": "cc49f8684f9706a93ba56648c9f2a34ad29e55f90cfcb92c1ef0b1122cfe4d6f"
+        "sha256": "c9e93c1b95b99a9e120b93d7683afa804713f98ce44bf29ba6d24e9ea1b44aee"
       },
       {
         "path": "templates/.claude/skills/goap-research-ed25519/SKILL.md",
-        "sha256": "d8d4dcdf3377f9a600e5a8d047ff17578c17ebb2e0059236d6b38739080418b5"
+        "sha256": "95459a1566b2f88b6fb0c1d2f096f7631d698b95fa156afa26444a7c06e76451"
       },
       {
         "path": "templates/.claude/skills/goap-research-ed25519/references/ed25519-verification.md",
@@ -523,18 +523,42 @@
         "path": "templates/.claude/skills/goap-research-ed25519/references/source-evaluation.md",
         "sha256": "d6a19abb6be64dc9e1f539903080029125d2d899da4de3063e75e1afb7e4906f"
       },
+      {
+        "path": "templates/.claude/skills/goap-research-ed25519/scripts/check_report_evidence.py",
+        "sha256": "81dfdb14a868c7d0d72a640cfdf8ae3b2b5a453a17fcc1a3396587f3b488a919"
+      },
       {
         "path": "templates/.claude/skills/goap-research-ed25519/scripts/ed25519_verifier.py",
-        "sha256": "dc9edc4d7907d13b28dfa74cc86b30a27a41de707ce72f39aca0ae08f07b5703"
+        "sha256": "9d0e74bab811a15b5032ec605e66a58081b52129aac873e7402e30b4dc4a2f10"
+      },
+      {
+        "path": "templates/.claude/skills/goap-research-ed25519/scripts/evidence_fetch.py",
+        "sha256": "5f4d7cb5d6fb3106d64130b6606582eb55a4f633ef969cf7890b1de1c179345b"
+      },
+      {
+        "path": "templates/.claude/skills/goap-research-ed25519/scripts/fixture_legacy_v1_fact.json",
+        "sha256": "e613de4737145cbfb5f349fbf9f1122801ce3508b62c3a18e2e0cba26b9da5b0"
       },
       {
         "path": "templates/.claude/skills/goap-research-ed25519/scripts/goap_planner.py",
         "sha256": "2ec359e1ddc52ca3118144532ed483dcc609e856a04b29bb191b875c60ff4260"
       },
+      {
+        "path": "templates/.claude/skills/goap-research-ed25519/scripts/learning_bridge.py",
+        "sha256": "6980dd654d77e296f1ab20a9b7a7c43741fd4125ee44727183c63587421d5503"
+      },
+      {
+        "path": "templates/.claude/skills/goap-research-ed25519/scripts/source_tiers.py",
+        "sha256": "e1aae76fad01693ab35b51466fc4369c04a5ac64230fd307e7b798dc5beeff7a"
+      },
       {
         "path": "templates/.claude/skills/goap-research-ed25519/scripts/test_ed25519_verifier.py",
         "sha256": "ea6d888ac53bac3a0fe236c101f90a984edbac044d787d73c8414f1c4fc540d3"
       },
+      {
+        "path": "templates/.claude/skills/goap-research-ed25519/scripts/test_evidence_provenance.py",
+        "sha256": "6825da92d859a299b86bd9bf9910088a95665e0716346e55f0f117d991d25c9b"
+      },
       {
         "path": "templates/.claude/skills/knowledge-extractor/SKILL.md",
         "sha256": "56a397fcd376bf3427373b3e74051c6a5de3a9dc3f66a398a58b9329aaca755b"
@@ -577,7 +601,7 @@
       },
       {
         "path": "templates/.claude/skills/presentation-storyteller/SKILL.md",
-        "sha256": "b9abcd495ce21630caebb3f000799b99113fbe89ce86f526f9a358f65c57c334"
+        "sha256": "f6ad6e6020280f17ccc4e7b71b28551310805aa99999b4056ec0ccfead1193d5"
       },
       {
         "path": "templates/.claude/skills/presentation-storyteller/references/example-presentation.md",
@@ -601,11 +625,11 @@
       },
       {
         "path": "templates/.claude/skills/problem-solver-enhanced/SKILL.md",
-        "sha256": "3f76c97479ce63b160f9040ae3f2621d45e6fbf9b17358b552bde48d12a6173a"
+        "sha256": "031378aa2e10c98928e35de07d454135e73550cd0c49f0cd886d53e4208d6b9f"
       },
       {
         "path": "templates/.claude/skills/reverse-engineering-unicorn/SKILL.md",
-        "sha256": "5efaafc3011af807b205774e32894c7e5f40053833f0adbfa79a7fe186050c15"
+        "sha256": "20d6b667971f9749d091c1d47e2f75df957f259647cbb861ac54174280096c71"
       },
       {
         "path": "templates/.claude/skills/reverse-engineering-unicorn/examples/noom-cjm-example.md",
@@ -941,5 +965,5 @@
       }
     ]
   },
-  "signature": "Zha9YxKobLgXgBV+tQ7B1xiGPXelkCRa3gSuG0ge7q6Sn7N7SkE9myZ/QGn7heGRXCFV1sbiYPH6Ao4omzHKAg=="
+  "signature": "e14W9eecgau7bIlWej75568LWR2BC5IMnjU+T14Tz5Cq/2WOySneuN53xfxl3oFJyCUr+vDAojeq4B1gs7wqDg=="
 }

package/README.md

@@ -6,6 +6,15 @@ Full 7-phase pipeline for AI case studies, hackathons, and casariums. Provides s
 
 ---
 
+
+> **`goap-research-ed25519` — self-learning (optional, since this release).** When
+> [`@dzhechkov/harness-cli`](https://www.npmjs.com/package/@dzhechkov/harness-cli) is on PATH, the
+> bundled research skill recalls prior METHOD lessons at the start of an investigation and records new
+> ones at four named moments. Without it the skill behaves exactly as before and says so once — it is
+> detected, never required. A guard refuses to record anything shaped like personal data: a method
+> lesson is written in lower case, carries no digits, and holds no identifier. See
+> `skills/goap-research-ed25519/SKILL.md`.
+
 ## Quick Start
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.5.33",
+  "version": "1.5.35",
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline with feature-adr, dream cycles, background workers, multi-platform support, reward learning, and Cloud.ru AI Factory mapping (--ai-factory flag)",
   "main": "src/cli.js",
   "bin": {

package/sbom.json

@@ -35,7 +35,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0b1de0c5bd3bde4586c64bab4a3ab90a4313c8659f327bfa774d9fe9d7a268b7"
+          "content": "5f1e61279a3f6b18e7db46adab9860d3cc95ed31926b122bc8508bf445f11117"
         }
       ]
     },
@@ -75,7 +75,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0869b59a6f7c9dfeb990cf4251d5d8dc7ce12c4b54a1c9a058e5caf12461d11f"
+          "content": "206ba50881c8dc2a62ab44af643f314928b52c0b711757f9e1a3d1b0312724bb"
         }
       ]
     },
@@ -745,7 +745,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "24c5e069fa0aead7584bd5adb0136107da0339da0ff92460f6f16435b73904fd"
+          "content": "c999b07ed76c289e1433cfea0b59abd8723d9c36455f76dc2fd8a3c6cf064bcf"
         }
       ]
     },
@@ -885,7 +885,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "254b51db25336fcc09317b5ac297448c5da7c3e218a21018c10ec3dd8970d964"
+          "content": "2473e7961845db0d64566cd42627b374d1830664b9e302058a1b1aa466bc7361"
         }
       ]
     },
@@ -915,7 +915,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ca6daf5b3470061dd9b0243236f5657fb4d3ad9dbcd1f7b7c30ef0a498f7f905"
+          "content": "c422d1e2b50cf7b8bd56cd5d886d96af30d8bf33a468b925396f395ebf32de53"
         }
       ]
     },
@@ -1265,7 +1265,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cc49f8684f9706a93ba56648c9f2a34ad29e55f90cfcb92c1ef0b1122cfe4d6f"
+          "content": "c9e93c1b95b99a9e120b93d7683afa804713f98ce44bf29ba6d24e9ea1b44aee"
         }
       ]
     },
@@ -1275,7 +1275,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "d8d4dcdf3377f9a600e5a8d047ff17578c17ebb2e0059236d6b38739080418b5"
+          "content": "95459a1566b2f88b6fb0c1d2f096f7631d698b95fa156afa26444a7c06e76451"
         }
       ]
     },
@@ -1309,13 +1309,43 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "templates/.claude/skills/goap-research-ed25519/scripts/check_report_evidence.py",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "81dfdb14a868c7d0d72a640cfdf8ae3b2b5a453a17fcc1a3396587f3b488a919"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "templates/.claude/skills/goap-research-ed25519/scripts/ed25519_verifier.py",
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dc9edc4d7907d13b28dfa74cc86b30a27a41de707ce72f39aca0ae08f07b5703"
+          "content": "9d0e74bab811a15b5032ec605e66a58081b52129aac873e7402e30b4dc4a2f10"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "templates/.claude/skills/goap-research-ed25519/scripts/evidence_fetch.py",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "5f4d7cb5d6fb3106d64130b6606582eb55a4f633ef969cf7890b1de1c179345b"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "templates/.claude/skills/goap-research-ed25519/scripts/fixture_legacy_v1_fact.json",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "e613de4737145cbfb5f349fbf9f1122801ce3508b62c3a18e2e0cba26b9da5b0"
         }
       ]
     },
@@ -1329,6 +1359,26 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "templates/.claude/skills/goap-research-ed25519/scripts/learning_bridge.py",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "6980dd654d77e296f1ab20a9b7a7c43741fd4125ee44727183c63587421d5503"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "templates/.claude/skills/goap-research-ed25519/scripts/source_tiers.py",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "e1aae76fad01693ab35b51466fc4369c04a5ac64230fd307e7b798dc5beeff7a"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "templates/.claude/skills/goap-research-ed25519/scripts/test_ed25519_verifier.py",
@@ -1339,6 +1389,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "templates/.claude/skills/goap-research-ed25519/scripts/test_evidence_provenance.py",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "6825da92d859a299b86bd9bf9910088a95665e0716346e55f0f117d991d25c9b"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "templates/.claude/skills/knowledge-extractor/SKILL.md",
@@ -1445,7 +1505,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b9abcd495ce21630caebb3f000799b99113fbe89ce86f526f9a358f65c57c334"
+          "content": "f6ad6e6020280f17ccc4e7b71b28551310805aa99999b4056ec0ccfead1193d5"
         }
       ]
     },
@@ -1505,7 +1565,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3f76c97479ce63b160f9040ae3f2621d45e6fbf9b17358b552bde48d12a6173a"
+          "content": "031378aa2e10c98928e35de07d454135e73550cd0c49f0cd886d53e4208d6b9f"
         }
       ]
     },
@@ -1515,7 +1575,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5efaafc3011af807b205774e32894c7e5f40053833f0adbfa79a7fe186050c15"
+          "content": "20d6b667971f9749d091c1d47e2f75df957f259647cbb861ac54174280096c71"
         }
       ]
     },

package/templates/.claude/skills/edu-site-generator/SKILL.md

@@ -10,7 +10,7 @@ trust_tier: 1
 
 # edu-site-generator — Gamified Educational Site Generator
 
-<!-- Trust Tier: 1 — Structured | Path to Tier 2: run a BTO evaluation (separate package: npx @dzhechkov/skills-bto) -->
+<!-- Trust Tier: 1 — Structured | Path to Tier 2: run a BTO evaluation (see the skills-bto package) -->
 
 > Generate a complete gamified educational SPA from documentation/content, optimized for GitHub Pages deployment.
 
@@ -21,7 +21,7 @@ Trigger on:
 - "create learning site [topic]"
 - "build educational app [topic]"
 - "gamified site from documentation"
-- `/edu-site [topic or docs path]`
+- `/edu-site-generator [topic or docs path]`
 
 ## Overview
 

package/templates/.claude/skills/explore/SKILL.md

@@ -10,7 +10,7 @@ description: >
   provide solutions until task is fully explored.
 trust_tier: 1
 trust_tier_label: "Structured"
-trust_tier_path: "Run a BTO evaluation from the separate package @dzhechkov/skills-bto to promote to Tier 2"
+trust_tier_path: "Run a BTO evaluation (see the skills-bto package) to promote to Tier 2"
 ---
 
 # Explore: Adaptive Task Clarification

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -11,7 +11,7 @@ description: >
   "implement feature", "/feature-adr".
 trust_tier: 0
 trust_tier_label: "Advisory"
-trust_tier_path: "Run a BTO evaluation from the separate package @dzhechkov/skills-bto to promote to Tier 1"
+trust_tier_path: "Run a BTO evaluation (see the skills-bto package) to promote to Tier 1"
 agentic_qe_version: "7.5.1"
 agentic_qe_source: "https://github.com/proffesor-for-testing/agentic-qe"
 agentic_qe_skills_core: 9

package/templates/.claude/skills/frontend-design/SKILL.md

@@ -4,7 +4,7 @@ description: Create distinctive, production-grade frontend interfaces with high
 license: Complete terms in LICENSE.txt
 trust_tier: 0
 trust_tier_label: "Advisory"
-trust_tier_path: "Add references/ directory and run a BTO evaluation from the separate package @dzhechkov/skills-bto to promote to Tier 1"
+trust_tier_path: "Add references/ directory and run a BTO evaluation (see the skills-bto package) to promote to Tier 1"
 ---
 
 This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

package/templates/.claude/skills/goap-research-ed25519/SKILL.md

@@ -3,7 +3,7 @@ name: goap-research-ed25519
 description: GOAP research system with Ed25519 provenance and tamper-evidence under pinned trusted-issuer keys. Use for high-stakes research that needs cited sources, explicit confidence, signed audit trails, or cryptographic proof of who signed a fact. Ed25519 does not prove truthfulness or prevent hallucination.
 trust_tier: 1
 trust_tier_label: "Structured"
-trust_tier_path: "Run a BTO evaluation from the separate package @dzhechkov/skills-bto to promote to Tier 2"
+trust_tier_path: "Run a BTO evaluation (see the skills-bto package) to promote to Tier 2"
 ---
 
 # GOAP Research with Ed25519 Provenance
@@ -28,6 +28,107 @@ Ed25519 provides cryptographic provenance and tamper-evidence under pinned trust
 | `SELF_ATTESTED` | Researcher signature verifies against the embedded researcher key | The research record was not altered after self-signing | up to `0.60` |
 | `UNVERIFIED` | Unknown issuer, missing pin, revoked key, key mismatch, malformed key, or invalid signature | No cryptographic provenance | `0.0` |
 
+## Evidence Classes — the second, independent axis
+
+Trust classes answer **"was this record altered after signing?"**. They say nothing about whether
+anyone opened the source. That second question caused every content error in real operation, so it
+gets its own axis. A fact can be `ISSUER_SIGNED` **and** `ASSERTED` — a cryptographically perfect
+record of something recited from memory. That combination is legal, expressible, and the dangerous one.
+
+| Evidence class | Requirement | What it proves | Ceiling |
+|---|---|---|---|
+| `FETCH_VERIFIED` | `evidence_fetch.fetch_source()` performed the request and got a 2xx body | This script issued an HTTP request and received a body with this byte hash on this date | `1.0` |
+| `LISTING_ONLY` | URL known from a listing, or a body supplied by hand, or the fetch failed | The URL is known; nobody opened it through this tool | `0.50` |
+| `ASSERTED` | Stated from model memory, source never opened | Nothing about the source | `0.0` |
+| *(absent)* | Fact predates this axis | Evidence is **unknown** — neither asserted nor verified | no ceiling of its own |
+
+**`FETCH_VERIFIED` cannot be self-declared.** It is minted only by `create_fetched_fact()`, which
+requires a `FetchRecord` — the byte hash, HTTP status and date of a request that actually happened.
+The manual constructors (`create_listing_fact`, `create_asserted_fact`) have no way to produce it.
+The restriction lives in the API shape, not in the author's discipline.
+
+**Honest scope of `FETCH_VERIFIED`:** it means the bytes were received. It does **not** mean the
+source is authoritative, that the claim follows from it, or that the reader understood it.
+Provenance, not truth.
+
+### The report gate
+
+```bash
+python3 scripts/check_report_evidence.py --report report.md --facts facts.json
+```
+
+`ASSERTED` claims must not appear in a report at all. `LISTING_ONLY` claims may appear only with a
+visible marker next to the claim. This is an exit code, not advice — exit `1` on violation, exit `2`
+when the inputs cannot be read (a gate that could not evaluate has cleared nothing).
+
+## Self-learning (optional — needs `dz` on PATH)
+
+The most valuable signal in research is the moment a conclusion turned out to be
+WRONG. `scripts/learning_bridge.py` records those as METHOD lessons in the shared
+`dz` store and replays them at the start of the next investigation.
+
+```bash
+python3 scripts/learning_bridge.py status                      # is the loop on at all?
+python3 scripts/learning_bridge.py recall "transferrin saturation"   # traps already caught
+python3 scripts/learning_bridge.py teach "total testosterone is uninterpretable without SHBG"
+python3 scripts/learning_bridge.py check "<candidate>"         # privacy guard alone
+```
+
+**Recall at the START of an investigation** — before interpreting anything, ask what
+this analyte has already fooled us with. **Teach at four moments**, not at random:
+
+| Moment | Why it is the signal |
+|---|---|
+| a conclusion was RETRACTED | the single most valuable lesson available |
+| a population check flipped a conclusion | the effect did not transfer, and now we know the shape |
+| a preanalytical finding explained an alarming value | the value was an artifact; the rule generalises |
+| an open question was closed | the answer, not the waiting |
+
+**PRIVACY IS AN INVARIANT, NOT A PREFERENCE.** A lesson describes a METHOD, never a
+person. `teach` REFUSES the wrong shape before any store is touched:
+
+```
+good  "a fast lowers total testosterone by roughly a third, LH down, FSH normal"
+bad   "testosterone 8.04 nmol/l in this patient turned out to be a fasting artifact"
+bad   "John Smith has HIV"          — a capitalised word after the first is refused
+```
+
+The accepted form has three properties, all checkable: **no digits** (spelled-out
+values count — `eight point zero four` is a value), **no identifiers**, and **lower
+case** after the first word. The last one replaced an attempt to detect names: a name
+is any word, no list of them exists, and the attempt let `John Smith has HIV` through.
+Lower case costs a keystroke and closes that hole. Acronyms are unaffected — a token
+passes if it is fully upper (`SHBG`, `TSH`) or opens lower (`apoB`, `mmHg`); only Title
+Case is refused, because Title Case is the shape of a name. A token mixing letters with
+a long digit run (`ab1234567`, `NCT04368728`) is an identifier and is refused however it
+is punctuated, while a short lab acronym carrying a digit (`hba1c`) is not.
+
+Pass `--allow-numbers` when the number IS the knowledge (a guideline threshold) and
+you take responsibility for it. It never waves through a person beside a number.
+
+The refusal is not bureaucracy — the method form is the more useful lesson: a reading
+helps once, a rule helps every time. Honest scope: this is a SHAPE detector, not a
+de-identifier. A lower-case sentence that names nobody and quotes no figure can still
+describe one person, and no regular expression can see that. The shape rule plus the
+four METHOD moments is what keeps the store clean; the guard alone is not a guarantee.
+
+Without `dz` installed the package behaves exactly as before and says so once. An
+older `dz` does **not** reject `--domain` — it ignores the flag and exits 0 — so recall
+makes ONE call and detects the older CLI by the ABSENCE of the boost note in the
+output, then states that results may mix other domains. A degraded loop that says so
+beats a silent one. A real failure (non-zero exit) is reported as itself: proceeding
+without prior lessons, never as "your CLI is old".
+
+## Source Tiers
+
+`source_tiers.classify_source(url)` assigns a class ceiling: A `0.90` (guideline bodies, WHO,
+registries) · B `0.80` (peer-reviewed literature) · C `0.60` (preprints, trial registries) ·
+D `0.40` (everything else, including unknown domains). A tier is a claim about the CLASS a domain
+belongs to — it is **not** a cryptographic statement and must never be confused with issuer pinning.
+
+`source_tiers.is_stale(source_date, kind)` flags sources past their TTL. A **missing** `source_date`
+is flagged too: freshness that cannot be established is not freshness.
+
 ## Signed Message
 
 `sign_fact()` and `verify_fact()` use the same deterministic JSON message containing:
@@ -39,6 +140,16 @@ Ed25519 provides cryptographic provenance and tamper-evidence under pinned trust
 - `timestamp`
 - optional `research_context` / nonce
 
+**Schema v2** additionally covers `evidence_class`, `fetch_date` and `source_date`, plus a
+`"schema": "fact-v2"` self-description marker. Version is chosen by the presence of
+`evidence_class`: legacy facts keep verifying against the six-field v1 message forever.
+
+Because the three evidence fields are part of the signed text, **both** tamper directions fail:
+stripping `evidence_class` makes the verifier build the v1 text, which no longer matches the signed
+v2 text; adding it to a legacy fact makes it build the v2 text, which does not match the signed v1
+text. (The marker is self-description and the growth point for a future v3 — it is not itself the
+protection; a discrimination run proved that.)
+
 Changing the issuer or moving the source URL after signing invalidates the signature. The code signs the raw canonical message bytes; Ed25519 performs its own internal hashing. Do not pre-hash with SHA-512 before signing.
 
 ## Pinned Issuers
@@ -77,25 +188,43 @@ Reordering, substituting, editing, relabeling, or moving a signed fact fails ver
 ## Confidence Formula
 
 ```
-confidence =
-  0.0   if UNVERIFIED
-  <=0.60 if SELF_ATTESTED
-  min(0.95, base_by_source_level * recency_factor) if ISSUER_SIGNED
+confidence = min(
+    trust_ceiling,      # UNVERIFIED 0.0 · SELF_ATTESTED 0.60 · ISSUER_SIGNED 0.95
+    evidence_ceiling,   # FETCH_VERIFIED 1.0 · LISTING_ONLY 0.50 · ASSERTED 0.0 · absent → no cap
+    tier_ceiling,       # A 0.90 · B 0.80 · C 0.60 · D 0.40
+)
 ```
 
+The **weakest link decides**, never the average. An `ISSUER_SIGNED` fact that nobody read is capped
+at `0.0` by its evidence class — which is the whole point of the second axis.
+
 Invalid signatures are rejected with confidence `0.0`; they are never a recoverable `0.5` penalty.
 
 ## Research Workflow
 
 1. Define the research goal and required evidence threshold.
 2. Configure pinned issuer keys when issuer-grade provenance is required.
-3. Search and fetch sources.
+3. Search and locate candidate sources.
 4. Extract claims and source URLs.
-5. Hash source content with SHA-256 for `source_hash`.
-6. Create self-attested facts for the research ledger or issuer-signed facts when a pinned issuer key actually signed the message.
+5. **Fetch each source through the tool, not by hand:**
+   ```python
+   from evidence_fetch import fetch_source, FetchRecord
+   record = fetch_source(url)                      # real HTTP, stdlib only
+   if isinstance(record, FetchRecord):
+       fact = verifier.create_fetched_fact(claim, record, issuer, source_date="2024-03-01")
+   else:                                            # offline, 404, oversize, refused scheme…
+       fact = verifier.create_listing_fact(claim, url, reason=record.reason)
+   ```
+   A claim you never opened a source for is `verifier.create_asserted_fact(claim)` — record it
+   honestly and let the gate refuse it. Never hand-label a class you did not earn.
+6. Add facts to the research ledger; issuer-signed facts only when a pinned issuer key actually
+   signed the message.
 7. Verify facts and citation chains.
 8. Cross-check claims through ordinary source evaluation.
-9. Report confidence, unsigned claims, rejected signatures, and limitations explicitly.
+9. **Run the report gate before delivering:**
+   `python3 scripts/check_report_evidence.py --report <report.md> --facts <facts.json>` — exit 0 required.
+10. Report confidence, evidence-class mix, unsigned claims, rejected signatures, and limitations
+    explicitly.
 
 ## Output Expectations
 
@@ -103,10 +232,14 @@ Reports should include:
 
 - Research objective and GOAP plan executed.
 - Findings with source URLs.
-- Verification status per claim (`ISSUER_SIGNED`, `SELF_ATTESTED`, or `UNVERIFIED`).
+- Verification status per claim on BOTH axes: trust (`ISSUER_SIGNED` / `SELF_ATTESTED` /
+  `UNVERIFIED`) and evidence (`FETCH_VERIFIED` / `LISTING_ONLY` / `ASSERTED` / unknown-legacy).
+- The evidence-class mix as a count — the share of `ASSERTED` should be zero.
+- A visible marker next to every `LISTING_ONLY` claim ("source not opened directly — verify").
 - Chain integrity result when citation chains are used.
 - Unsigned and rejected claims.
-- Explicit caveat that cryptographic provenance is not truth verification.
+- Explicit caveat that cryptographic provenance is not truth verification, and that
+  `FETCH_VERIFIED` means the bytes arrived — not that the source is right.
 
 ## Implementation