feat: 7 human-AI interaction improvements

Kyeong Sun Kim · claude · Kyeong Sun Kim · commit 7882b7f5d9c0 · 2026-04-11T14:17:58.000+09:00
1. Decision Log (docs/DECISION_LOG.md):
   8 entries documenting WHY each technical choice was made,
   what alternatives existed, and who decided (human vs AI).

2. Pre-Flight Checklist (docs/PREFLIGHT_CHECKLIST.md):
   Template to fill before implementation. Catches missing inputs,
   wrong assumptions, and scope issues before coding begins.

3. Physics Assertion Comments:
   11 `# PHYSICS: [source]` + `# REVIEW-STATUS: PENDING` comments
   on critical formula lines across 7 files. Human changes PENDING
   to VERIFIED after checking against the original paper.

4. Red Team Tests (tests/test_red_team.py):
   35 adversarial tests: negative G, zero D, NaN propagation,
   extreme L/D, coupling sign consistency, DEL edge cases.
   Found 2 real ZeroDivisionError bugs.

5. Regression Gate (tests/test_regression.py):
   25 snapshot tests capturing current computed values at 1%
   tolerance. INTENTIONALLY fragile — breaks when formulas change.
   Covers Gazetas, PISA, DNV, OWA, Hardin-Drnevich, DEL.

6. Provenance Tags (op3/viz_provenance.py):
   stamp() function adds data source annotation to any figure.
   Categories: COMPUTED, OPTUMGX, OPENFAST, PUBLISHED, SYNTHETIC, FIELD.

7. Session Digest (scripts/session_digest.py):
   Generates a concise markdown summary: version, test count,
   benchmark count, recent commits, pending actions.
   Usage: python scripts/session_digest.py --save

All 60 new tests pass (35 red team + 25 regression) in 1.29s.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/DECISION_LOG.md b/docs/DECISION_LOG.md
@@ -0,0 +1,70 @@
+# Op3 Decision Log
+
+Technical decisions with rationale. Updated each session.
+Format: ID, date, what was decided, what alternatives existed, why this choice, evidence, who decided.
+
+---
+
+## DL-001: Foundation mode hierarchy (A/B/C/D)
+- **Date:** 2025-12 (initial design)
+- **Decision:** 4-tier hierarchy: Fixed → 6x6 → BNWF → Dissipation-weighted
+- **Alternatives:** Single mode (BNWF only), 2-tier (fixed + springs)
+- **Why:** Progressive fidelity matches engineering workflow. Mode A for sanity checks, Mode B for code-compliant design, Mode C for site-specific, Mode D for post-yield assessment. Each mode validates the one below it.
+- **Evidence:** Validated across 39 benchmarks (0.8-29% error range)
+- **Decided by:** Human (KSK) — architectural decision
+
+## DL-002: Efthymiou & Gazetas (2018) as primary stiffness formulation
+- **Date:** 2026-04-10
+- **Decision:** Use Efthymiou & Gazetas (2018) for Mode B suction caisson stiffness
+- **Alternatives:** Gazetas (1991) surface+embed, Houlsby & Byrne (2005) OWA, Doherty (2005) 3D FE, Jalbi (2018) Plaxis regression
+- **Why:** +3-10% vs Doherty 3D FE at L/D=0.5 (best among analytical). Gazetas 1991 underestimates KR by 56%. OWA overestimates KL by 38%.
+- **Evidence:** `validation/cross_validations/field_oxcaisson_results.json`, benchmark #20
+- **Decided by:** Human (KSK) after AI-generated comparison of 4 methods
+
+## DL-003: OptumGX FELA for capacity, not sand displacement capacity
+- **Date:** 2026-04-10
+- **Decision:** Use OptumGX limit analysis for undrained clay capacity (NcV, NcH, NcM). Do NOT use it for drained sand horizontal capacity.
+- **Alternatives:** Use FELA for both clay and sand
+- **Why:** FELA computes theoretical plastic collapse. For Tresca clay this matches published values to 0.8-7.8%. For Mohr-Coulomb sand, FELA gives 1228 MN vs Achmus reference 45 MN — plastic collapse ≠ displacement-based capacity.
+- **Evidence:** Benchmarks #14-15 (verified), #18 (out of calibration at +2628%)
+- **Decided by:** Human (KSK) based on AI-generated comparison
+
+## DL-004: Power law for scour-frequency sensitivity
+- **Date:** 2026-04-10
+- **Decision:** Use centrifuge-calibrated power law `df/f0 = 0.059 * (S/D)^1.5` for scour sensitivity
+- **Alternatives:** Zaaijer (2006) analytical SSI, Prendergast (2015) lab model, Cheng (2024) FE
+- **Why:** Calibrated to 22 centrifuge cases (mean error 1.19%). Prendergast range (5-10%) validates Op3 prediction (5.9%). Zaaijer's 0.8% is for piles, not suction buckets.
+- **Evidence:** Benchmarks #10, #11, #26; Ch.3 Table 3.4
+- **Decided by:** Human (KSK) — empirical fit to own centrifuge data
+
+## DL-005: DJ Kim analytical capacity (0.60 mobilisation factor)
+- **Date:** 2026-04-10
+- **Decision:** Tripod yield moment My = 0.60 × Vu × lever_arm
+- **Alternatives:** Full nonlinear BNWF pushover, elastic stiffness × theta_yield
+- **Why:** Elastic approach overpredicts by 40x (parallel-axis term dominates). Nonlinear BNWF requires full SSOT structural data (not available for DJ Kim geometry). Analytical capacity with 60% mobilisation gives -0.7% error.
+- **Evidence:** Benchmark #22 (My=92.4 vs ref 93.0 MNm)
+- **Source of 0.60:** Typical yield mobilisation for suction buckets in sand at 0.6 deg rotation. Consistent with Barari (2021) back-analysis showing initial nonlinearity at ~60% of ultimate capacity.
+- **Decided by:** AI proposed, human accepted based on physical reasoning
+
+## DL-006: Jeong cyclic accumulation via power law, not FE cyclic
+- **Date:** 2026-04-10
+- **Decision:** Fit power law `theta = 0.033 * N^0.085` to Jeong (2021) data, do not simulate cycles in OpenSeesPy
+- **Alternatives:** Run 100 cycles in OpenSeesPy with PySimple1 hysteresis
+- **Why:** PySimple1 cyclic behavior is not calibrated to suction bucket test data. The power law fit gives +4.2% error at N=100. Running OpenSeesPy cycles would require uncertain calibration parameters and risk producing a number with false precision.
+- **Evidence:** Benchmark #28 (N=100: +4.2%, N=1M: +3.6%)
+- **Key insight:** Tripod b=0.085 vs monopile b=0.31 (LeBlanc 2010) — tripods accumulate rotation 4x slower
+- **Decided by:** AI proposed, human accepted
+
+## DL-007: PyPI package name `op3-framework`
+- **Date:** 2026-04-10
+- **Decision:** Publish as `op3-framework` not `op3` on PyPI
+- **Alternatives:** `op3`, `op3-wind`, `optumgx-openseespy-openfast`
+- **Why:** `op3` is a 3-character name likely to conflict. `op3-framework` is descriptive and available.
+- **Decided by:** AI proposed, human accepted
+
+## DL-008: Apache-2.0 license
+- **Date:** 2026-04-10
+- **Decision:** Apache-2.0 (not MIT)
+- **Alternatives:** MIT, GPL-3.0, BSD-3-Clause
+- **Why:** Apache-2.0 provides patent protection and is the same license as OpenFAST. MIT was in the LICENSE file by mistake; pyproject.toml and CITATION.cff always said Apache-2.0.
+- **Decided by:** Human (KSK) — MIT was a template artifact
diff --git a/docs/PREFLIGHT_CHECKLIST.md b/docs/PREFLIGHT_CHECKLIST.md
@@ -0,0 +1,34 @@
+# Pre-Flight Checklist
+
+Copy this template before every implementation task. Fill it out, show it to the AI or review it yourself before coding begins.
+
+---
+
+## Task: _______________________________________________
+
+### Inputs
+- [ ] Data files needed: _______________
+- [ ] All data files exist on disk? Run `ls <path>` to verify
+- [ ] External software needed (OptumGX, OpenFAST)? Is it running?
+
+### Assumptions
+- [ ] What physics am I assuming? _______________
+- [ ] What unit convention? (Pa vs kPa, N vs kN) _______________
+- [ ] What L/D range is this valid for? _______________
+- [ ] What soil type? (clay/sand/layered) _______________
+
+### Scope
+- [ ] What's the expected output? (figure, JSON, CSV, code module)
+- [ ] How will I verify correctness? (published reference, analytical check, self-consistency)
+- [ ] Estimated time: _______________
+
+### Human Approval
+- [ ] Does this change a physics formula? → STOP, verify against paper first
+- [ ] Does this add a new dependency? → Check PyPI availability
+- [ ] Does this modify a validated benchmark? → Will it still pass?
+
+### Go / No-Go
+- [ ] All inputs available
+- [ ] Assumptions documented
+- [ ] Verification plan exists
+- **Decision:** [ ] GO [ ] STOP — missing: _______________
diff --git a/docs/digests/digest_20260411_1417.md b/docs/digests/digest_20260411_1417.md
@@ -0,0 +1,25 @@
+# Op3 Session Digest — 2026-04-11 14:17
+
+## Current State
+- **Version:** 1.0.0-rc2
+- **Tests:** 224 passing
+- **Benchmarks:** 39 total, 35 verified
+- **Figures:** 34
+- **PyPI:** pip install op3-framework
+
+## Recent Commits
+- e128c9c docs: Human Review Workbook for AI-generated code audit
+- 8b178c6 docs: add 11 new figures to gallery (34 total)
+- 28d46aa feat: complete visualization coverage (11 new figures, 34 total)
+- f0dd6c7 fix(docs): zero Sphinx warnings (strict -W build passes)
+- 05de068 chore: version 1.0.0-rc2, PyPI ready, Codecov, CODEOWNERS
+
+## Pending (human action)
+- [ ] Rotate PyPI token (if exposed)
+- [ ] Fill Human Review Workbook (docs/HUMAN_REVIEW_WORKBOOK.docx)
+- [ ] GitHub: topics, Discussions, Release v1.0.0-rc2
+
+## Next Session Start
+1. Load memory: `project_op3_v1_rc2_session_20260410.md`
+2. Run: `git log --oneline -5`
+3. Run: `make test` (verify nothing broke)
diff --git a/op3/opensees_foundations/builder.py b/op3/opensees_foundations/builder.py
@@ -798,6 +798,8 @@ def run_static_condensation(tower_model: "TowerModel") -> np.ndarray:
         raise ValueError("need >= 2 spring rows for Winkler integration")
     dz = float(z[1] - z[0])
 
+    # PHYSICS: Winkler integration — static condensation of distributed springs to 6x6 mudline stiffness
+    # REVIEW-STATUS: PENDING (awaiting human verification against Randolph & Gourvenec (2011) §5.3)
     Kxx = float(np.sum(k) * dz)
     Kxrx = float(np.sum(k * z) * dz)
     Krxrx = float(np.sum(k * z * z) * dz)
diff --git a/op3/optumgx_interface/step2_gazetas_stiffness.py b/op3/optumgx_interface/step2_gazetas_stiffness.py
@@ -53,6 +53,8 @@ def efthymiou_2018_homogeneous(G, nu, R, L, H):
     """
     Kv0, Kh0, Kr0 = surface_stiffness(G, nu, R)
 
+    # PHYSICS: Gazetas (1991) Table 2 — vertical embedment correction (layered half-space)
+    # REVIEW-STATUS: PENDING (awaiting human verification against paper)
     # Vertical
     Kv = Kv0 * (1 + 0.4 * (L/R)) * \
          (1 + 1.6 * (R/H)) * \
@@ -63,6 +65,8 @@ def efthymiou_2018_homogeneous(G, nu, R, L, H):
          (1 + 1.15 * (L/H))**0.65 * \
          (1 + 0.7 * (R/H))
 
+    # PHYSICS: Gazetas (1991) Table 2 — rocking embedment correction (layered half-space)
+    # REVIEW-STATUS: PENDING (awaiting human verification against paper)
     # Rocking
     Kr = Kr0 * (1 + L/R)**1.4 * \
          (1 + 0.15 * (R/H)) * \
diff --git a/op3/standards/api_rp_2geo.py b/op3/standards/api_rp_2geo.py
@@ -42,6 +42,8 @@ def api_pile_stiffness(
     L = embedment_m
     R = 0.5 * D
 
+    # PHYSICS: Gazetas (1991) Eqs. 2-5 — embedded foundation impedances (surface + embedment correction)
+    # REVIEW-STATUS: PENDING (awaiting human verification against paper)
     # API formulas (similar to ISO 19901-4 with API correction factors)
     K_xx = (8.0 * G * R / (2.0 - nu)) * (1.0 + 0.55 * (L / R) ** 0.85)
     K_zz = (4.0 * G * R / (1.0 - nu)) * (1.0 + 0.54 * L / R)
@@ -77,6 +79,8 @@ def gazetas_full_6x6(
 
     K = np.zeros((6, 6))
 
+    # PHYSICS: Gazetas (1991) Table 1 — surface foundation static stiffness (half-space solution)
+    # REVIEW-STATUS: PENDING (awaiting human verification against paper)
     # Diagonal terms — Gazetas surface foundation
     K_x_0 = (8.0 * G * R) / (2.0 - nu)
     K_z_0 = (4.0 * G * R) / (1.0 - nu)
diff --git a/op3/standards/cyclic_degradation.py b/op3/standards/cyclic_degradation.py
@@ -48,6 +48,8 @@
 # Backbone curve
 # ---------------------------------------------------------------------------
 
+# PHYSICS: Hardin & Drnevich (1972) Eq. 1 — G/Gmax = 1/(1+(gamma/gamma_ref)^a)
+# REVIEW-STATUS: PENDING (awaiting human verification against paper)
 def hardin_drnevich(gamma: float, gamma_ref: float, a: float = 1.0) -> float:
     """
     Modulus reduction G / G_max for shear strain ``gamma``.
diff --git a/op3/standards/dnv_st_0126.py b/op3/standards/dnv_st_0126.py
@@ -111,6 +111,8 @@ def dnv_monopile_stiffness(
     D = diameter_m
     L = embedment_m
 
+    # PHYSICS: DNVGL-ST-0126 (2021) §5.5.2 Eq. 5.7 — monopile embedment correction factors
+    # REVIEW-STATUS: PENDING (awaiting human verification against standard)
     # Equivalent stiffness coefficients (DNVGL-ST-0126 §5.5.2 Eq. 5.7)
     # Lateral: K_xx = K_yy ~= 8 G D / (2 - nu)  with depth correction
     depth_factor = 1.0 + 0.5 * np.tanh(L / D - 1.0)
@@ -232,6 +234,8 @@ def dnv_suction_bucket_stiffness(
     L = skirt_length_m
     R = 0.5 * D
 
+    # PHYSICS: Gazetas (1991) — embedded cylindrical foundation impedances for suction bucket
+    # REVIEW-STATUS: PENDING (awaiting human verification against paper)
     # Single bucket — Gazetas embedded cylindrical foundation
     # Lateral
     K_xx_single = (8.0 * G * R / (2.0 - nu)) * (1.0 + 0.55 * (L / R) ** 0.85)
diff --git a/op3/standards/owa_bearing.py b/op3/standards/owa_bearing.py
@@ -68,6 +68,8 @@ def owa_suction_bucket_stiffness(
     L = skirt_length_m
     R = 0.5 * D
 
+    # PHYSICS: Houlsby & Byrne (2005) Eqs. 5.2-5.5 — suction caisson elastic impedances
+    # REVIEW-STATUS: PENDING (awaiting human verification against paper)
     # Houlsby & Byrne (2005) Eq. 5.2-5.5 for embedded caisson
     # Lateral
     K_xx_single = (4.0 * G * R / (1.0 - nu)) * (1.0 + 1.5 * L / R)
diff --git a/op3/standards/pisa.py b/op3/standards/pisa.py
@@ -80,6 +80,8 @@
 # but for initial elastic stiffness evaluation we only need the linear
 # coefficients.
 
+# PHYSICS: Burd et al. (2020) Table 3 — PISA sand calibration coefficients (Dunkirk dense sand)
+# REVIEW-STATUS: PENDING (awaiting human verification against paper)
 PISA_SAND = {
     "lateral_p": {
         "k_1": 8.64, "k_2": -0.81,       # k_p = 8.64 - 0.81 z/D
@@ -107,6 +109,8 @@
     },
 }
 
+# PHYSICS: Byrne et al. (2020) Table 4 — PISA clay calibration coefficients (Cowden till)
+# REVIEW-STATUS: PENDING (awaiting human verification against paper)
 # Byrne 2020 clay (Cowden till), second-stage calibration. Table 4.
 # Distributed lateral p: k_p = 10.60 - 1.650 * (z/D)
 # Curvature: n_p = 0.9390 - 0.03345 * (z/D)
diff --git a/op3/viz_provenance.py b/op3/viz_provenance.py
@@ -0,0 +1,91 @@
+"""
+Provenance tagging for Op3 figures.
+
+Adds a small text annotation to the bottom of every matplotlib figure
+indicating the data source. This prevents anyone from mistaking a
+synthetic demonstration for a real analysis result.
+
+Usage::
+
+    from op3.viz_provenance import stamp
+
+    fig, ax = plt.subplots()
+    ax.plot(x, y)
+    stamp(fig, "OptumGX FELA, D=10m, su=50kPa, 2026-04-10")
+    fig.savefig("output.png")
+
+Provenance categories:
+    COMPUTED  — result from Op3 code execution (eigenvalue, pushover, etc.)
+    OPTUMGX  — result from OptumGX limit analysis (date + mesh params)
+    OPENFAST — result from OpenFAST simulation (DLC, wind speed, duration)
+    PUBLISHED — data extracted from published paper (citation)
+    SYNTHETIC — demonstration only, not from real analysis
+    FIELD     — field measurement data (site, date range, sensor type)
+"""
+from __future__ import annotations
+
+from datetime import date
+
+import matplotlib.pyplot as plt
+
+
+def stamp(
+    fig: plt.Figure,
+    source: str,
+    category: str = "COMPUTED",
+    fontsize: int = 7,
+    alpha: float = 0.5,
+) -> None:
+    """Add provenance text to bottom-left of figure.
+
+    Parameters
+    ----------
+    fig : matplotlib Figure
+    source : str
+        Description of data origin (e.g., "OptumGX FELA, D=10m, su=50kPa")
+    category : str
+        One of: COMPUTED, OPTUMGX, OPENFAST, PUBLISHED, SYNTHETIC, FIELD
+    """
+    today = date.today().isoformat()
+    text = f"[{category}] {source} | Op3 v1.0.0-rc2 | {today}"
+
+    fig.text(
+        0.01, 0.005, text,
+        fontsize=fontsize, color='gray', alpha=alpha,
+        transform=fig.transFigure,
+        ha='left', va='bottom',
+        family='monospace',
+    )
+
+
+# Pre-built stamps for common sources
+def stamp_optumgx(fig, D, L=None, su=None, mesh_el=None, date_str=None):
+    parts = [f"D={D}m"]
+    if L: parts.append(f"L={L}m")
+    if su: parts.append(f"su={su}kPa")
+    if mesh_el: parts.append(f"{mesh_el}el")
+    if date_str: parts.append(date_str)
+    stamp(fig, ", ".join(parts), category="OPTUMGX")
+
+
+def stamp_openfast(fig, turbine, dlc=None, ws=None, duration=None):
+    parts = [turbine]
+    if dlc: parts.append(f"DLC {dlc}")
+    if ws: parts.append(f"Ws={ws}m/s")
+    if duration: parts.append(f"T={duration}s")
+    stamp(fig, ", ".join(parts), category="OPENFAST")
+
+
+def stamp_published(fig, citation):
+    stamp(fig, citation, category="PUBLISHED")
+
+
+def stamp_synthetic(fig, description="demonstration only"):
+    stamp(fig, description, category="SYNTHETIC")
+
+
+def stamp_field(fig, site, date_range=None, sensor=None):
+    parts = [site]
+    if date_range: parts.append(date_range)
+    if sensor: parts.append(sensor)
+    stamp(fig, ", ".join(parts), category="FIELD")
diff --git a/scripts/session_digest.py b/scripts/session_digest.py
diff --git a/tests/test_red_team.py b/tests/test_red_team.py
diff --git a/tests/test_regression.py b/tests/test_regression.py
