atlas-outcomes: a place-decision pack built from real outcomes (USGS flow, NWS flood warnings)

.github/workflows/ci.yml

@@ -642,6 +642,39 @@ jobs:
           fi
           echo "No pack artifacts tracked"
 
+  # apps/atlas-outcomes: the outcome-real place-decision pack (stdlib only).
+  # Lint is a HARD gate (the app started at 0 findings). The tests run on a
+  # synthetic fixture, with a floor so a green run that collected nothing fails.
+  # The rebuild step proves `curate` reproduces the committed PACK_MANIFEST.json
+  # and sample byte for byte from the committed sources/ snapshots, offline.
+  atlas-outcomes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Ruff lint — apps/atlas-outcomes (HARD gate, at 0)
+        run: |
+          pip install ruff==0.15.22
+          ruff check apps/atlas-outcomes
+      - name: Unit tests (floor 14)
+        run: |
+          set -euo pipefail
+          python3 -m unittest discover -s apps/atlas-outcomes/tests -v 2>&1 | tee /tmp/atlas.txt
+          ran=$(grep -oE 'Ran [0-9]+ tests?' /tmp/atlas.txt | tail -1 | grep -oE '[0-9]+' || echo 0)
+          if [ "${ran}" -lt 14 ]; then
+            echo "FAIL: only ${ran} tests ran (floor 14)."
+            exit 1
+          fi
+          grep -qE '^OK$' /tmp/atlas.txt
+      - name: Offline rebuild matches the committed manifest
+        run: |
+          set -euo pipefail
+          python3 apps/atlas-outcomes/run.py curate > /dev/null
+          git diff --exit-code -- apps/atlas-outcomes/PACK_MANIFEST.json apps/atlas-outcomes/sample
+
   bluehenre-checks:
     # The Dottie site (apps/bluehenre) — zero-dep, bare-node. Enforces the
     # provenance guarantees: pure parsers, the Hub exporter parser, and that the

HANDOFF.md

@@ -18,8 +18,8 @@ before writing "current" anywhere in this file.
 
 ## 📌 Session continuation — 2026-09-23 (supersedes every block below)
 
-**Stamped 2026-09-23 at HEAD `07a2146`** (branch `claude/decision-plane`, the
-merge of `origin/main` after PR #58's squash into this branch). Measured with
+**Stamped 2026-09-23 at HEAD `8266088`** (`main`, the squash merge of PR #60;
+the earlier stamp named a pre-squash branch commit that is not on `main`). Measured with
 `git rev-parse --short HEAD` + `scripts/check_handoff_fresh.py --check`.
 
 **What landed: decision plane, phase 1** (`docs/ARCHITECTURE.md` is now the

apps/atlas-outcomes/BASELINE.json

@@ -0,0 +1,139 @@
+{
+  "features": [
+    "pct_date",
+    "pct_all",
+    "log_flow_over_p90",
+    "above_p90_today",
+    "chg1",
+    "chg3",
+    "chg7",
+    "up_present",
+    "up_pct_date",
+    "up_chg1",
+    "up_chg3",
+    "warn_active",
+    "warn_gauge_30d",
+    "warn_wfo_7d",
+    "warn_wfo_1d",
+    "doy_sin",
+    "doy_cos"
+  ],
+  "holdout": {
+    "days": [
+      "2025-09-22",
+      "2026-09-21"
+    ],
+    "rows": 20921
+  },
+  "questions": {
+    "flow_change": {
+      "climatology": {
+        "accuracy": 0.4348,
+        "brier_multiclass": 0.69199,
+        "mae_expected_level": 0.8194
+      },
+      "holdout_levels": {
+        "falls 5% to 20%": 5976,
+        "falls more than 20%": 1531,
+        "rises 5% to 20%": 2716,
+        "rises more than 20%": 2334,
+        "within 5% either way": 8364
+      },
+      "logistic": {
+        "accuracy": 0.4653,
+        "brier_multiclass": 0.66652,
+        "mae_expected_level": 0.7431
+      },
+      "persistence": {
+        "accuracy": 0.5003,
+        "brier_multiclass": 0.99947,
+        "mae_expected_level": 0.7828
+      },
+      "type": "score"
+    },
+    "high_next": {
+      "climatology": {
+        "accuracy": 0.9522,
+        "auc": 0.7303,
+        "brier": 0.04984
+      },
+      "holdout_positives": 999,
+      "holdout_rate": 0.0478,
+      "logistic": {
+        "accuracy": 0.9799,
+        "auc": 0.9818,
+        "brier": 0.01568
+      },
+      "logistic_weights": {
+        "above_p90_today": 0.6524,
+        "chg1": 0.4213,
+        "chg3": -0.2192,
+        "chg7": -0.0909,
+        "doy_cos": 0.1636,
+        "doy_sin": 0.0821,
+        "intercept": -6.2591,
+        "log_flow_over_p90": 3.2662,
+        "pct_all": 0.683,
+        "pct_date": -0.2581,
+        "up_chg1": 0.2979,
+        "up_chg3": 0.0537,
+        "up_pct_date": 0.5385,
+        "up_present": -0.4769,
+        "warn_active": 0.1392,
+        "warn_gauge_30d": 0.0272,
+        "warn_wfo_1d": 0.4312,
+        "warn_wfo_7d": -0.0074
+      },
+      "persistence": {
+        "accuracy": 0.9772,
+        "auc": 0.8744,
+        "brier": 0.0228
+      },
+      "type": "noul"
+    },
+    "warn_next": {
+      "climatology": {
+        "accuracy": 0.9909,
+        "auc": 0.6968,
+        "brier": 0.00894
+      },
+      "holdout_positives": 190,
+      "holdout_rate": 0.0091,
+      "logistic": {
+        "accuracy": 0.9909,
+        "auc": 0.8313,
+        "brier": 0.00887
+      },
+      "logistic_weights": {
+        "above_p90_today": 0.0041,
+        "chg1": 0.0008,
+        "chg3": -0.0016,
+        "chg7": -0.0235,
+        "doy_cos": -0.1225,
+        "doy_sin": -0.0773,
+        "intercept": -5.19,
+        "log_flow_over_p90": -0.1188,
+        "pct_all": 0.4422,
+        "pct_date": 0.0294,
+        "up_chg1": 0.0263,
+        "up_chg3": 0.0548,
+        "up_pct_date": 0.0673,
+        "up_present": -0.0432,
+        "warn_active": 0.0264,
+        "warn_gauge_30d": 0.1802,
+        "warn_wfo_1d": 0.3904,
+        "warn_wfo_7d": 0.1468
+      },
+      "persistence": {
+        "accuracy": 0.9833,
+        "auc": 0.5326,
+        "brier": 0.01673
+      },
+      "type": "noul"
+    }
+  },
+  "train": {
+    "rows": 79491,
+    "weighted_rows": 226290.0
+  }
+}

apps/atlas-outcomes/PACK_MANIFEST.json

@@ -0,0 +1,175 @@
+{
+  "balance": {
+    "holdout": {
+      "flow_change": {
+        "falls 5% to 20%": 5976,
+        "falls more than 20%": 1531,
+        "rises 5% to 20%": 2716,
+        "rises more than 20%": 2334,
+        "within 5% either way": 8364
+      },
+      "high_next": {
+        "natural_rate": 0.0478,
+        "positive_rate": 0.0478,
+        "positives": 999
+      },
+      "rows": 20921,
+      "warn_next": {
+        "natural_rate": 0.0091,
+        "positive_rate": 0.0091,
+        "positives": 190
+      },
+      "weighted_rows": 20921.0
+    },
+    "train": {
+      "flow_change": {
+        "falls 5% to 20%": 23807,
+        "falls more than 20%": 9639,
+        "rises 5% to 20%": 9284,
+        "rises more than 20%": 10584,
+        "within 5% either way": 26177
+      },
+      "high_next": {
+        "natural_rate": 0.1033,
+        "positive_rate": 0.294,
+        "positives": 23368
+      },
+      "rows": 79491,
+      "warn_next": {
+        "natural_rate": 0.0094,
+        "positive_rate": 0.0268,
+        "positives": 2131
+      },
+      "weighted_rows": 226290.0
+    }
+  },
+  "consent": {
+    "capture_training": true,
+    "champion": false,
+    "public_sources": true
+  },
+  "downsampling": {
+    "applies_to": "train only",
+    "easy_keep": 0.1,
+    "easy_negatives_before": {
+      "holdout": 16641,
+      "train": 163136
+    },
+    "rule": "both noul labels false, pct_date < 90, pct_all < 90, no warning over the gauge in 30 days"
+  },
+  "files": {
+    "holdout.jsonl": {
+      "bytes": 37903287,
+      "sha256": "1ff022452ca5ca36a595de6b855d0b225f707843adbcae6c2047966e30a5ef4a"
+    },
+    "provenance.jsonl": {
+      "bytes": 43704421,
+      "sha256": "fb0004042da132f828aec6639965d57b29b962ca860c8738ff5e9ed9d154e68b"
+    },
+    "train.jsonl": {
+      "bytes": 144326335,
+      "sha256": "bbd6a2dc5c03ae5340df26819a8b186fc8e67d3b6c362c7705c5d0942b79a0ef"
+    }
+  },
+  "gauges": {
+    "harvest_end": "2026-09-22",
+    "in_pack": 60,
+    "offices": [
+      "BGM",
+      "BOX",
+      "BTV",
+      "CRP",
+      "CTP",
+      "DVN",
+      "EAX",
+      "EWX",
+      "FFC",
+      "FWD",
+      "HGX",
+      "ILM",
+      "ILN",
+      "ILX",
+      "LMK",
+      "LSX",
+      "LWX",
+      "MHX",
+      "MTR",
+      "PAH",
+      "PBZ",
+      "PHI",
+      "RAH",
+      "RLX",
+      "SEW"
+    ],
+    "states": [
+      "CA",
+      "CT",
+      "GA",
+      "IA",
+      "IL",
+      "IN",
+      "KY",
+      "MA",
+      "MD",
+      "MO",
+      "NC",
+      "NJ",
+      "OH",
+      "PA",
+      "TX",
+      "VA",
+      "VT",
+      "WA",
+      "WV"
+    ]
+  },
+  "label_sources": {
+    "flow_change": "usgs-nwis-dv",
+    "high_next": "usgs-nwis-dv",
+    "warn_next": "iem-vtec-sbw"
+  },
+  "pack": "atlas-outcomes-1",
+  "provenance": "outcome-real",
+  "questions": {
+    "flow_change": "score (5 levels)",
+    "high_next": "noul",
+    "warn_next": "noul"
+  },
+  "rejected": {
+    "easy negative downsampled (train)": 146825,
+    "embargo (label window touches the holdout)": 58
+  },
+  "rows": {
+    "candidates": 247295,
+    "holdout": 20921,
+    "holdout_frac": 0.2084,
+    "total": 100412,
+    "train": 79491
+  },
+  "rules": [
+    "labels are recorded futures (USGS daily values on t+1, IEM VTEC warning polygons issued after T): provenance tier outcome-real",
+    "features use only data dated <= t and warnings issued <= T (end of local standard day t); percentiles from days strictly before t",
+    "holdout is the latest 365 days; a one-day embargo keeps every train label window out of it",
+    "easy negatives are downsampled in train only; sample_weight in provenance.jsonl restores natural rates",
+    "may train candidates; eval on the time-split holdout; consent.champion=false: nothing auto-promotes"
+  ],
+  "schema": "jev-decision-schema-1.0.0",
+  "seed": 20260923,
+  "sources": {
+    "flows.jsonl.gz": "6c0e7305d69e1afab7756e4bf6fc3a30c8019c187884eefc4da7029d1a152f3e",
+    "gauges.jsonl.gz": "5de5a28331aac5ed67a3c728e2e1bc9f3aee7c4c143c52aa8277323f390d26ae",
+    "warnings.jsonl.gz": "ca5d4e7756e2cc78922f36e7df0bb651012d3bba06e692915b12e92b04ce8b93"
+  },
+  "split": {
+    "embargo_days": 1,
+    "holdout_days": [
+      "2025-09-22",
+      "2026-09-21"
+    ],
+    "kind": "time",
+    "train_days": [
+      "2015-01-01",
+      "2025-09-20"
+    ]
+  }
+}