release: add docs/CHANGELOG.md

docs/CHANGELOG.md

@@ -9,28 +9,50 @@ Status tags: `RESOLVED` · `OPEN` · `CLOSED` · `DEFERRED` · `REJECTED`.
 
 ## [1.0.0] — 2026-09-25 — Final documentation, model release and archival freeze
 
-The release that makes the project legible and citable: repository documentation, research
-documentation, model documentation, a Hugging Face model release, a curated public repository, and a
-verified evidence archive.
+The release that makes the project legible, citable and reproducible: repository documentation, a
+deep research/engineering documentation set, model documentation, a Hugging Face model release, a
+curated public repository, and a verified evidence archive.
 
 ### Added
-- **Repository README** (27 sections) — motivation through citation, with the deployed topology, the
-  six supported tasks, routing, the eight execution events, measured results, live validation, and
-  known limitations.
-- **Research documentation set** — `ARCHITECTURE.md`, `MODELS.md`, `BENCHMARKS.md`, `DATASETS.md`,
-  `TRAINING.md`, `EVALUATION.md`, `DEPLOYMENT.md`, `REPRODUCIBILITY.md`, `LIMITATIONS.md`,
-  `RESEARCH_NOTES.md`, `CHANGELOG.md`.
-- **Model documentation** — `MODEL_CARD.md`, generated `models/manifest.json` and
-  `models/checksums.sha256`.
+
+**Documentation**
+
+- **Repository README** — motivation through citation, with the deployed topology, the six supported
+  tasks, routing, the eight execution events, measured results, live validation, and known
+  limitations.
+- **Deep architecture reference** (hub + 10 chapters):
+  | Chapter | Topic |
+  |---|---|
+  | `docs/ARCHITECTURE.md` | hub: thesis, sub-document index, cross-cutting principles |
+  | `docs/architecture/01-system-overview.md` | thesis, component inventory, frozen-backbone strategy |
+  | `docs/architecture/02-deployment-topology.md` | four tiers, gateway, tunnel, wake flow, cold start |
+  | `docs/architecture/03-request-lifecycle.md` | the nine-state controller, validation, tiling |
+  | `docs/architecture/04-router.md` | frozen MiniLM, the 5-head adapter, `interpret()` vs `chooseTask()`, lexical fallback |
+  | `docs/architecture/05-specialists.md` | all six tasks in depth |
+  | `docs/architecture/06-evidence-and-confidence.md` | evidence aggregation, temperature scaling, the eight events |
+  | `docs/architecture/07-configuration-freeze.md` | the registry, enforced invariants, the config hash |
+  | `docs/architecture/08-api-contract.md` | the four endpoints, envelopes, error codes |
+  | `docs/architecture/09-frontend.md` | the static pages, real-vs-preview, platform traps |
+  | `docs/architecture/10-observability-and-ops.md` | health, counters, traces, what is not observed |
+- **Research documentation** — `MODELS.md`, `BENCHMARKS.md`, `DATASETS.md`, `TRAINING.md`,
+  `EVALUATION.md`, `DEPLOYMENT.md`, `REPRODUCIBILITY.md`, `LIMITATIONS.md`, `RESEARCH_NOTES.md`,
+  `CHANGELOG.md`.
+- **Model documentation** — `MODEL_CARD.md`, plus **generated** `models/manifest.json` and
+  `models/checksums.sha256` (computed by reading the files, never typed).
+- **Metric verification tooling** — `release/tools/verify_readme_metrics.py`, which walks every quoted
+  metric to its source artifact. Result: **`ALL CLAIMS VERIFIED`** (20/20).
+
+**Release**
+
 - **Hugging Face release** of the six trained artifacts to `thundercode/SatQuery`, with a verification
-  record.
-- **Curated public repository** at `Anish-lab-blip/SatQuery-AI` with a release manifest.
-- **Evidence archive** (ZIP64, artifacts verbatim) with an integrity-verified extraction and a
-  documented remote location.
-- **Metric verification tool** — `tools/verify_readme_metrics.py`, checking all 20 quoted metrics and
-  the status assertions against their artifacts.
+  record (`HF_RELEASE_VERIFICATION.md`). Independent re-download confirmed **6/6 artifacts
+  byte-identical**.
+- **Curated public repository** at `Anish-lab-blip/SatQuery-AI` with `RELEASE_MANIFEST.md`.
+- **Evidence archive** (ZIP64, `artifacts/` verbatim per owner decision G3) with an integrity-verified
+  extraction and a documented remote location.
 
 ### Changed
+
 - The monorepo `README.md` was **materially stale** and is superseded by this release's README. The
   stale version called the frontend "hermetic — no backend calls", put Render/Codespace as
   "in progress", described a `/v1/*` contract, and pointed at the untracked `deploy/` as the
@@ -40,6 +62,7 @@ verified evidence archive.
   false at release time and are corrected.
 
 ### Fixed
+
 - **Router defect** — *"Where are the built-up areas in this image?"* collapsed to `vqa` and answered
   "River". Fixed in the dispatch path and validated across three independent live passes (8/8 each).
   `RESOLVED`.
@@ -50,8 +73,12 @@ verified evidence archive.
   with a same-shape pair (both 720×720). `RESOLVED` (supersedes `FINAL_DELIVERY_REPORT.md` §6).
 - **B-01 (Hugging Face header link)** — previously `BLOCKED`; the link is now live on all 11 pages.
   `CLOSED`.
+- **Metric-verifier dotted-path bug** — the resolver split the artifact key `"0.50"` on its own dot,
+  producing a false `NOKEY` for the two grounding recall claims. Fixed to prefer the **longest**
+  matching key at each step.
 
 ### Known issues at this release
+
 - **B-07** — transient tunnel-agent gaps; a request can hang or return 504. Patch prepared, **NOT
   deployed**. `OPEN`.
 - **B-02** — `/api/health` `codespace_name` carries a trailing `\n`. Cosmetic. `OPEN`.
@@ -64,6 +91,7 @@ verified evidence archive.
 - **optical-SAR** and **change-VQA** rulings remain `OPEN`.
 
 ### Deployment revisions at this release
+
 | Component | Revision |
 |---|---|
 | Frontend | `2d7ae53b482d` |
@@ -75,11 +103,14 @@ verified evidence archive.
 
 ## [0.9.0] — 2026-09-25 — Router-defect sprint
 
-- Diagnosed and fixed the router misroute (region queries → `vqa`).
+- Diagnosed and fixed the router misroute (region queries → `vqa`): the temporal slot in
+  `interpret()` now derives from `changeStem` / `pairWording` / `newAsChange`; `built` was dropped as a
+  change marker; the quantifier `area` was tightened to `\barea\b`.
 - Deployed three commits to the frontend.
-- Ran **3 independent live validation passes**, 8/8 each — 24 live runs, 24 correct dispatches,
-  0 mock nodes, trace fill 94.4444 %.
-- Wrote the delivery report and handoff.
+- Ran **3 independent live validation passes**, 8/8 each — **24 live runs, 24 correct dispatches,
+  0 mock nodes, trace fill 94.4444 %**.
+- Wrote the delivery report and the handoff.
+- Prepared (but did not deploy) the B-07 backend patch.
 
 ---
 
@@ -88,23 +119,26 @@ verified evidence archive.
 - Live topology settled on **Cloudflare Pages → Render → outbound tunnel → Codespace** (CPU).
 - Closed the five historical backend blockers (ASGI stack in requirements; `$PORT` read; `OPTIONS`
   preflight; fail-fast app construction; adapter integrity compared against an expected digest).
-- Documented cold start; `transport_mode: auto` fallthrough recorded.
+- Documented cold start; recorded the `transport_mode: auto` fallthrough.
 
 ---
 
 ## [0.7.0] — Grounding and change heads
 
-- Grounding: trainable head over frozen RemoteCLIP ViT-B/32. Resolution **224 chosen, 448 rejected**
-  by a pre-registered paired test.
-- Change: STANet-style Siamese detector on LEVIR-CD-256 — the only `VERIFIED` headline metric.
-- Optical-SAR: CROMA-base fusion head, seed sweep, pre-registered 115-class metric.
+- **Grounding**: trainable head over frozen RemoteCLIP ViT-B/32. Resolution **224 chosen, 448
+  REJECTED** by a pre-registered paired test (mean best IoU −0.0147, t = −22.63).
+- **Change**: STANet-style Siamese detector on LEVIR-CD-256 — the only `VERIFIED` headline metric
+  (pooled IoU 0.8122 / macro IoU 0.8457 / pooled F1 0.8964).
+- **Optical-SAR**: CROMA-base fusion head, armA/armB × seeds 100–104 sweep, pre-registered 115-class
+  metric (accuracy 0.931 / macro-F1 0.434161, ruling `OPEN`).
 
 ---
 
 ## [0.6.0] — VLM adaptation
 
-- SmolVLM-500M LoRA adapter trained (PEFT 0.19.1, r = 16, α = 32).
-- Metrics usable (exact_match 0.963) but **acceptance-rejected** for promotion. `REJECTED`.
+- SmolVLM-500M LoRA adapter trained (PEFT 0.19.1, r = 16, α = 32, dropout 0.05, fp16).
+- Metrics usable (exact_match 0.963, F1 0.96432) but **ACCEPTANCE-REJECTED** for promotion.
+  `REJECTED`.
 - Findings F5-1/F5-2/F5-3 recorded (loader class, ~17× processor overrun, chat-template requirement).
 
 ---
@@ -113,7 +147,9 @@ verified evidence archive.
 
 - 50,822-parameter adapter over frozen MiniLM; cached embeddings; CPU-only training (0.28 s for 20
   epochs / 4,096 vectors).
-- Group-based splits with hard negatives in the test split.
+- Group-based splits with hard negatives placed in the test split.
+- Deterministic lexical fallback with ordered precedence and a `self_check()` against curated hard
+  negatives.
 
 ---
 
@@ -121,7 +157,7 @@ verified evidence archive.
 
 - Monorepo, frozen configuration registry (`configs/base.yaml`), config-hash freeze
   (`78f1e3700da15aa1`), nine-state controller, four-endpoint inference contract, evidence schema
-  (`Region` / `ChangeRegion`), eight frontend execution events.
+  (`Region` / `ChangeRegion` / `Evidence`), eight frontend execution events.
 
 ---
 
@@ -135,3 +171,25 @@ verified evidence archive.
 | Select a licence | **OPEN** |
 | Resolve the optical-SAR and change-VQA rulings | **OPEN** |
 | Plot the calibrated reliability curve | **NOT RUN** |
+| Replace the illustrative benchmark adapter numbers with real runs | **NOT RUN** |
+
+---
+
+## Documentation inventory shipped in 1.0.0
+
+| File | Purpose |
+|---|---|
+| `README.md` | repository front page |
+| `MODEL_CARD.md` | model card for the six trained artifacts |
+| `docs/ARCHITECTURE.md` + `docs/architecture/01…10` | the deep architecture reference |
+| `docs/MODELS.md` | model detail, hyperparameters, acceptance status |
+| `docs/BENCHMARKS.md` | every measured metric with its artifact and protocol |
+| `docs/DATASETS.md` | dataset provenance, splits, leakage controls |
+| `docs/TRAINING.md` | training procedures and hyperparameters |
+| `docs/EVALUATION.md` | evaluation protocols and honesty rules |
+| `docs/DEPLOYMENT.md` | live topology, env vars, mechanics, traps |
+| `docs/REPRODUCIBILITY.md` | what can and cannot be reproduced |
+| `docs/LIMITATIONS.md` | the full limitation catalogue |
+| `docs/RESEARCH_NOTES.md` | engineering findings and negative results |
+| `docs/CHANGELOG.md` | this file |
+| `models/manifest.json`, `models/checksums.sha256` | generated artifact identities |