chore: publish from main

2026-08-17 06:36:56 +00:00 · 2026-08-05 05:18:23 +00:00
parent 3cfa6a707f
commit de02cfbad3
6 changed files with 857 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Evidence ladder
+
+Use the strongest evidence practical for the decision. A higher class can still
+be stale, irrelevant, or too broad for the nearby claim.
+
+1. **Direct current observation** — reproduced behavior, command output,
+   inspected artifact, or measured result.
+2. **Authoritative primary source** — official specification, dataset, law,
+   documentation, first-party repository, or original research.
+3. **Independent corroboration** — competent sources with distinct underlying
+   evidence.
+4. **Explicit inference** — a conclusion whose premises and assumptions are
+   visible in the map.
+5. **Weak proxy** — related metric, benchmark, anecdote, or test that does not
+   exercise the exact claim.
+6. **Unsupported assertion** — confidence, repetition, or polished language
+   without evidence.
+
+## Source-region test
+
+Before creating an evidence node, answer:
+
+- What exact sentence, table, command output, page, section, or line range is
+  being relied on?
+- Does it entail the node text, or merely discuss the same subject?
+- Is its date and version appropriate for the claim?
+- Is the evidence independent, or copied from another cited source?
+- What context would reverse or narrow the interpretation?
+
+If the exact region cannot be located, create an `unknown` node instead of an
+evidence node.
+
+## Edge test
+
+| Relation | Use when | Common counterfeit |
+| --- | --- | --- |
+| `supports` | The source increases reason to accept the target | Topical similarity |
+| `contradicts` | Both cannot hold under the same scope and conditions | Different dates or populations |
+| `qualifies` | The source narrows scope, strength, or applicability | Hiding inconvenient evidence |
+| `missing` | A specific absent fact blocks or could reverse the target | Generic “more research needed” |
@@ -0,0 +1,101 @@
+# Evidence map schema
+
+The canonical artifact is UTF-8 JSON. Use a `.doubt.json` suffix when practical.
+
+```json
+{
+  "title": "Short artifact title",
+  "question": "One decision-changing question?",
+  "updatedAt": "YYYY-MM-DD",
+  "verdict": "A provisional, evidence-bounded answer.",
+  "nodes": [
+    {
+      "id": "current-position",
+      "type": "position",
+      "label": "Current position",
+      "text": "The proposition represented by this node."
+    },
+    {
+      "id": "primary-observation",
+      "type": "evidence",
+      "label": "Observed result",
+      "text": "A faithful statement of the source region.",
+      "sourceId": "source-1"
+    },
+    {
+      "id": "missing-baseline",
+      "type": "unknown",
+      "label": "Missing baseline",
+      "text": "The exact absent fact and why it matters."
+    }
+  ],
+  "edges": [
+    {
+      "from": "primary-observation",
+      "to": "current-position",
+      "relation": "supports",
+      "note": "Why the observation increases reason to accept the position."
+    },
+    {
+      "from": "missing-baseline",
+      "to": "current-position",
+      "relation": "missing",
+      "note": "Why this missing baseline could reverse the position."
+    }
+  ],
+  "sources": [
+    {
+      "id": "source-1",
+      "title": "Source title",
+      "url": "https://example.com/source",
+      "publisher": "Publisher",
+      "date": "YYYY-MM-DD",
+      "retrievedAt": "YYYY-MM-DD",
+      "locator": "Section: Results, p. 7, § 2.1, L12-L18, or 00:04:31",
+      "excerpt": "A short, checkable excerpt or bounded source-region description."
+    }
+  ]
+}
+```
+
+## Invariants
+
+- Allowed node types: `position`, `claim`, `evidence`, `unknown`.
+- Allowed relations: `supports`, `contradicts`, `qualifies`, `missing`.
+- Exactly one `position` node is required.
+- Evidence nodes require `sourceId`.
+- Every evidence node must be the `from` side of at least one edge.
+- Every non-position node must have a directed path to the position.
+- Duplicate reasoning edges and directed cycles are rejected.
+- Every source must be used by an evidence node.
+- Every edge needs a plain-language `note`.
+- Map and source dates are real ISO calendar dates; source dates cannot be later
+  than `updatedAt`.
+- Every source records `retrievedAt`. Receipts cover that value and the recorded
+  excerpt, not the mutable bytes currently served by the URL.
+- Locators identify a bounded section, page, line range, or timestamp.
+- Excerpts contain 40–500 characters of varied, checkable content; repeated
+  filler is invalid.
+- `confidence` fields are invalid. Use an `unknown` node or a qualified claim.
+
+## Optional verification record
+
+Only a successful explicit source-verification command may add this object to a
+source:
+
+```json
+{
+  "verification": {
+    "status": "verified",
+    "method": "normalized-excerpt-match",
+    "checkedAt": "YYYY-MM-DDTHH:mm:ss.sssZ",
+    "contentSha256": "64 lowercase hexadecimal characters",
+    "excerptSha256": "64 lowercase hexadecimal characters",
+    "finalUrl": "The checked URL or absolute local path",
+    "locatorStatus": "matched"
+  }
+}
+```
+
+`locatorStatus` may be `not-machine-checked` for page, section, and timestamp
+locators. Do not treat it as proof that the region was manually confirmed.