From b273673f269557ff9f0e6bd08433b4e297702808 Mon Sep 17 00:00:00 2001
From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com>
Date: Thu, 17 Sep 2026 22:01:53 +0000
Subject: [PATCH] =?UTF-8?q?docs(deed):=20mapping=20spec=20family=205=20?=
 =?UTF-8?q?=E2=80=94=20scorecard=20corpus=20decision=20+=20path-leak=20rem?=
 =?UTF-8?q?ediation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refs #837
---
 .../mappings/scorecard-corpus-decision.adoc   | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 1-formats/deed/mappings/scorecard-corpus-decision.adoc

diff --git a/1-formats/deed/mappings/scorecard-corpus-decision.adoc b/1-formats/deed/mappings/scorecard-corpus-decision.adoc
new file mode 100644
index 000000000..0060e7af0
--- /dev/null
+++ b/1-formats/deed/mappings/scorecard-corpus-decision.adoc
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= Decision spec — `*.scorecard.a2ml` corpus (70+) → deed era (family 5)
+Campaign: standards#837 · Frame: link:README.adoc[mappings/README] ·
+Status: **DECISION REQUIRED (owner)** — plus one remediation that needs
+no ruling (the absolute-path leak, §4)
+
+Scorecards are the wrong shape for the naïve "translate each file" move:
+they are **time-stamped assessment records**, not repo state. Translating
+them like descriptiles would mint dozens of mute permanent snapshots into
+the coordination surface that repo deeds are.
+
+== 1. Corpus shape (recon: standards repo, scorecard dir)
+
+* One file per spec under test: `<spec_id>.scorecard.a2ml`.
+* Header table: `spec_id`, `version`, `assessed_date`, `assessor` (the
+  `assessor` is "estate-audit" — a TOOL IDENTITY, i.e. provenance
+  metadata, not content).
+* Repeated `[[must]]` / `[[should]]` / `[[could]]` arrays: per-criterion
+  `id`, `text`, `system` (probe description), `status` (`pass|fail`),
+  `evidence`, `check`, `effects`.
+* Field spelling is snake_case at the header (`spec_id`, `assessed_date`)
+  — GENUINE a2ml dialect difference from the descriptile families
+  (kebab-case); the dialect split is recorded here so the translator's
+  per-family normalisation is explicit, not discovered.
+
+== 2. Options on the table
+
+**A. Translate all 70+ into repo deeds** — bloat: a `(must …)` entry with
+pass/fail for a moment in 2026 is a record; after one re-assessment there
+are competing "latest" claims. Rejected in spec terms: repo-deed is a
+current-state registry form (§251 of the grammar spec: order-free,
+dedupe-free by design for state).
+
+**B. Freeze corpus + current-verdict summary only (RECOMMENDED)** —
+1. The 70+ historical files become an archive surface
+   (`.machine_readable/archive/scorecards-v1/`) with a tombstone comment;
+   the data is **not translated** — translation of time-series records is
+   lossy by construction, and the archive preserves provenance verbatim.
+2. ONE current snapshot per spec_id lands on the *assessed repo's* deed as
+   `(assessment :spec accessibility :version "1.0.0" :date "2026-07-03"
+   :assessor estate-audit :must-pass 2 :must-fail 2)` — aggregate counts
+   only, never rows; row-level truth stays in the archive + auditor.
+3. Future assessments are produced by estate-audit directly in the deeds
+   era (tool PR rides separately) — the corpus stops accumulating v1s
+   at the seam.
+
+**C. New doc-head `scorecard-deed`** — grammar change, owner-ruling
+territory by definition (grammar surface). Recorded so it is answered
+once, not re-litigated per PR: NOT requested; the assessment-summary
+clause + archive covers the need without expanding the four-head grammar.
+
+== 3. Acceptance (once ruled)
+
+* Zero live `*.scorecard.a2ml` outside the archive surface.
+* Exactly one `(assessment …)` clause per previously-covered spec_id on
+  the right repo deed; `:assessor` carried as SYMBOL (`estate-audit`).
+* Archive tombstones link forward: each archived file names the repo deed
+  that now carries its summary.
+
+== 4. Remediation needing NO ruling: the absolute-path leak
+
+While reconnning: `evidence` fields in the corpus contain absolute local
+paths, e.g. `…/accessibility.scorecard.a2ml` cites
+`/home/user/standards/.machine_readable/contractiles/adjust/Adjustfile.a2ml`.
+Machine-local absolute paths in repo-committed assessment evidence are
+(a) meaningless on any other machine, (b) a workstation-layout disclosure.
+
+Because this is *fix-in-place data hygiene on files we are freezing anyway*,
+it does NOT wait for the A/B ruling: the recommendation is a sed-level pass
+over the corpus (only literal `/home/user/standards/` and equivalents →
+repo-relative `…/`) **before** archiving, so the archive is clean from the
+first day. Deliverable list of offending lines rides in the owner-side
+residue ledger rather than being silently edited in a translation PR.
+(Per closeout discipline: listed, evidence-attached, owner-visible — not
+swept.)