aero-agent-roles 1.0.0

package/roles/numerical-analysis-engineer/templates/verification-memo-template.md

@@ -0,0 +1,120 @@
+# Numerical Methods Verification Memo
+
+**Code under verification:** Loads Post-Processor (LPP) (version v2.3.1)
+**Verification basis:** classical numerical analysis (Richardson 1910/1927; Euler-Maclaurin error analysis; Newton/Simpson/Gauss); ASME V&V 20-2009 vocabulary for discretization error
+**Status:** draft-for-review
+
+## 1. Scope and method selection
+
+The LPP loads post-processor turns the spanwise load distribution into the half-span resultant used by the loads report, inverts the isentropic area-Mach relation for duct sizing, and solves the 2x2 aerodynamic coefficient system A c = b. This memo independently verifies the numerical methods of the item above: the spanwise-load integral, the area-Mach root inversion, and the loads coefficient solve are each recomputed with reference methods and compared against the code's reported values and claimed tolerances. A three-mesh convergence study and a conditioning report bound the discretization and rounding error of the results.
+
+| Operation | Code method | Reference method | Why |
+|---|---|---|---|
+| spanwise load intensity w(y) = w0*(1 - (2y/span)^2), half-span integral | composite trapezoid, n=16 panels | composite Simpson | Composite Simpson error scales with h^4 and the rule is exact for polynomials of degree <= 3, beating trapezoid on smooth integrands at moderate panel counts. |
+| area-Mach inversion (A/A* = 1.2, subsonic) | code-internal Newton solver | Newton-Raphson (quadratic, simple root) with bisection bracket cross-check | Bisection guarantees convergence when the bracket straddles zero (linear); Newton gives quadratic convergence from a nearby guess when the derivative is non-zero; agreement of the two independent iterations cross-validates the root. |
+| loads coefficient solve A c = b | code-internal dense solver | Gaussian elimination with partial pivoting | Partial pivoting bounds element growth and avoids zero pivots; the reference residual A x - b is checked at machine precision, and the conditioning report bounds how much backward error the solve amplifies. |
+
+## 2. Reference computations
+
+### 2.1 Reference integral
+
+Integrand: spanwise load intensity w(y) = w0*(1 - (2y/span)^2), half-span integral on [0.000000, 18.000000] m (peak load 4200 N/m, span 36 m).
+- Reference value (composite Simpson): 50400.000000 N
+- Closed-form anchor w0*span/3: 50400.000000 N (the integrand is a quadratic, so Simpson is exact here)
+- Richardson error estimate at the code's panel count: the trapezoid error scales with h^2, giving error(2n) = |I_2n - I_n|/3 = 12.304688 N.
+
+### 2.2 Reference root
+
+- isentropic area-Mach inversion (A/A* = 1.2, gamma = 1.4), subsonic branch: M* = 0.590248761
+- Reference method: reference Newton-Raphson from x0 = 0.3 + bisection bracket cross-check - converged in 6 iterations, residual |f| = 2.22e-16
+- Derivative at the root f'(M*) = -1.238449 (non-zero: simple root, quadratic convergence expected); root sensitivity per unit residual 1/|f'| = 0.807462
+- Bracket [0.200, 0.990] straddles zero: True
+- Bisection cross-check: M = 0.590248761, agreement with Newton 8.17e-12
+
+### 2.3 Reference linear solve
+
+- Reference solution c = A^-1 b: 0.285714286, 0.285714286
+- Condition number kappa = s_max/s_min: 7.0000
+- Conditioning assessment: kappa = 7: up to 0.85 decimal digits of input uncertainty can be amplified by the solve
+
+## 3. Cross-check against the engineering code
+
+Each operation: code-reported value vs reference value; verdict PASS when the discrepancy is within the code's own claimed tolerance.
+
+### 3.1 Integration
+
+- Operation: spanwise load integral
+- Code method: composite trapezoid, n=16 panels
+- Reference method: composite Simpson, n=64 (exact for degree <= 3) + Richardson error estimate
+- Code-reported value: 50350.781250000 N
+- Reference value (composite Simpson, n=64): 50400.000000000 N
+- Discrepancy: 49.218750000 N
+- Code-claimed tolerance: 1.000 N
+- Richardson estimate of the code's n-panel error: 49.218750 N (from the code's own n and 2n outputs)
+- **Verdict: FAIL**
+- Method fingerprint: the reference engine's trapezoid at the code's panel count reproduces the code output (50350.781250000) - the code's method was identified correctly.
+
+### 3.2 Root finding
+
+- Operation: isentropic area-Mach inversion (A/A* = 1.2, gamma = 1.4), subsonic branch
+- Code method: code-internal Newton solver
+- Reference method: reference Newton-Raphson from x0 = 0.3 + bisection bracket cross-check
+- Code-reported value: M = 0.590248761
+- Reference value: M* = 0.590248760988 (residual |f| = 2.22e-16)
+- Bisection cross-check: M = 0.590248761 (agreement with Newton 8.17e-12)
+- Discrepancy: 1.15e-11
+- Code-claimed tolerance: 1.00e-08
+- **Verdict: PASS**
+
+### 3.3 Linear solve
+
+- Operation: loads coefficient solve A c = b
+- Code method: code-internal dense solver
+- Reference method: Gaussian elimination with partial pivoting (reference engine)
+- Code-reported solution: [0.285714000, 0.285714000]
+- Reference solution: [0.285714286, 0.285714286]
+- Discrepancy (max component): 2.86e-07
+- Code-claimed tolerance: 1.00e-06
+- **Verdict: PASS**
+- Condition number kappa = s_max/s_min: 7.0000
+- Conditioning: kappa = 7: up to 0.85 decimal digits of input uncertainty can be amplified by the solve
+
+## 4. Convergence and error analysis
+
+Three-mesh study of the code's own outputs (refinement ratio r = 2, finest f1 to coarsest f3):
+
+- 64: 50396.923828
+- 32: 50387.695312
+- 16: 50350.781250
+- Observed order p = 2.000 (consistent with composite trapezoid (order 2))
+- Richardson extrapolated value: 50400.000000
+- Grid convergence index (GCI, Fs = 1.25): 7.63e-05 fraction (0.0076%)
+- Verdict: monotone converged
+- Code-reported value vs finest mesh: 46.142578 N
+
+## 5. Findings and recommendations
+
+### F-1 (Discrepancy)
+
+spanwise load integral reports 50350.781250 N while the reference integration gives 50400.000000 N: discrepancy 49.218750 N exceeds the code's claimed tolerance of 1 N.
+
+Evidence: Richardson error estimate of the code's n-panel output is 49.218750 N (measured discrepancy 49.218750 N); the three-mesh study shows observed order 2.00, so the code's panel count cannot support the claimed tolerance.
+
+Recommendation: Refine to n >= 64 panels or switch to a composite Simpson rule, and gate the output with a Richardson error estimate before release.
+
+### O-1 (Observation)
+
+root-finding (isentropic area-Mach inversion (A/A* = 1.2, gamma = 1.4), subsonic branch) verified within the code's claimed tolerance (discrepancy 1.1549e-11 <= 1e-08).
+
+### O-2 (Observation)
+
+linear solve (loads coefficient solve A c = b) verified within the code's claimed tolerance (discrepancy 2.85714e-07 <= 1e-06).
+
+## 6. Verification limits
+
+- Scope: the three numerical operations named above, on the example item's input set. Other code paths (ODE integration, interpolation, least-squares fitting, finite-difference derivatives, uncertainty propagation) follow the same reference-engine workflow when exercised.
+- The code's claimed tolerances are inputs to this memo, not endorsements; a PASS verdict means the claim is supported by the reference computation on this input set.
+- Export classification: uncontrolled technical data (example).
+
+---
+*Generated by Aero Agent Roles numerical-analysis-engineer core (2026-09-05). DRAFT for human numerical-analysis review. Not an approval document.*

package/roles/numerical-analysis-engineer/tests/test_bundle_protocol.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Test the evidence bundle + skill-dispatch protocol (PROTOCOL.md v1).
+
+Verifies:
+- build --bundle emits evidence/{model,gates,provenance}.json
+- bundle JSON parses, model contains the computed reference numbers,
+  gates all_pass
+- the ten dispatch rows agree with the bound numerics leaf logic
+  modules (delta <= 1e-6) when AeroSkills is present
+- standalone (no AeroSkills) emits the bundle honestly with
+  cross_checked=false
+- build --profile prepends a program context header
+- CLI overrides re-verify a different code report
+- check gate-checks a built memo
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+ROLE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+CLI = os.path.join(ROLE_DIR, "cli.py")
+PROFILE = os.path.normpath(os.path.join(ROLE_DIR, "..", "..", "profiles",
+                                        "example-airframer.json"))
+
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+HAS_SKILLS = os.path.isdir(os.path.join(AEROSKILLS, "skills"))
+
+EXPECTED_LEAVES = {
+    "numerical-integration", "root-finding", "convergence-verification",
+    "singular-value-decomposition", "matrix-operations",
+}
+EXPECTED_FUNCS = {"trapezoid", "simpson", "error_estimate_trapezoid",
+                  "newton_raphson", "bisection", "condition_number", "solve"}
+
+
+def run_build(outdir, env_extra=None, extra_args=None):
+    env = dict(os.environ)
+    if env_extra:
+        env.update(env_extra)
+    args = [sys.executable, CLI, "build", "--out",
+            os.path.join(outdir, "memo.md"), "--bundle"]
+    if extra_args:
+        args.extend(extra_args)
+    r = subprocess.run(args, capture_output=True, text=True, env=env)
+    return r
+
+
+class TestBundleProtocol(unittest.TestCase):
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_bundle_emits_three_files(self):
+        r = run_build(self.tmp)
+        self.assertEqual(r.returncode, 0, (r.stdout + r.stderr)[-800:])
+        ev = os.path.join(self.tmp, "evidence")
+        for f in ("model.json", "gates.json", "provenance.json"):
+            self.assertTrue(os.path.exists(os.path.join(ev, f)), f + " missing")
+
+    def test_model_has_numbers_and_status(self):
+        run_build(self.tmp)
+        m = json.load(open(os.path.join(self.tmp, "evidence", "model.json")))
+        self.assertEqual(m["role"], "numerical-analysis-engineer")
+        self.assertEqual(m["deliverable_type"],
+                         "Numerical Methods Verification Memo")
+        self.assertEqual(m.get("status"), "draft-for-review")
+        # the model must carry the numbers that appear in the markdown
+        self.assertAlmostEqual(m["integration"]["code_value"], 50350.78125,
+                               places=6)
+        self.assertAlmostEqual(m["integration"]["reference_value"], 50400.0,
+                               places=6)
+        self.assertAlmostEqual(
+            m["root_finding"]["reference_root"], 0.59024876099, places=9)
+        self.assertAlmostEqual(m["convergence"]["observed_order"], 2.0,
+                               places=6)
+        self.assertAlmostEqual(m["linear_solve"]["conditioning"]["kappa"],
+                               7.0, places=6)
+
+    def test_gates_all_pass_exit_zero(self):
+        r = run_build(self.tmp)
+        self.assertEqual(r.returncode, 0)
+        g = json.load(open(os.path.join(self.tmp, "evidence", "gates.json")))
+        self.assertTrue(g["all_pass"])
+        self.assertEqual(g["exit_code"], 0)
+        self.assertGreaterEqual(len(g["gates"]), 5)
+
+    def test_dispatch_crosschecks_when_skills_present(self):
+        if not HAS_SKILLS:
+            self.skipTest("AeroSkills not present")
+        r = run_build(self.tmp)
+        self.assertEqual(r.returncode, 0, (r.stdout + r.stderr)[-800:])
+        p = json.load(open(os.path.join(self.tmp, "evidence",
+                                        "provenance.json")))
+        self.assertTrue(p["cross_checked"])
+        rows = [row for row in p["skills"] if row.get("dispatched")
+                and not row.get("error")]
+        self.assertGreaterEqual(len(rows), 10)
+        leafs = {row["leaf"].rsplit("/", 1)[-1] for row in rows}
+        self.assertEqual(leafs, EXPECTED_LEAVES)
+        funcs = {row["function"] for row in rows}
+        self.assertTrue(EXPECTED_FUNCS.issubset(funcs), funcs)
+        for row in rows:
+            self.assertTrue(row["agrees"],
+                            "core/skill disagree for %s: %s"
+                            % (row["function"], row))
+            self.assertLessEqual(row["delta"], 1e-6)
+            self.assertIn("cross-cutting/numerics/", row["leaf"])
+
+    def test_standalone_honest_no_skills(self):
+        r = run_build(self.tmp, env_extra={"AEROSKILLS_DEV": "/nonexistent"})
+        self.assertEqual(r.returncode, 0)
+        p = json.load(open(os.path.join(self.tmp, "evidence",
+                                        "provenance.json")))
+        self.assertFalse(p["cross_checked"])
+        self.assertEqual(len(p["skills"]), 0)
+
+    def test_profile_header_applied(self):
+        if not os.path.exists(PROFILE):
+            self.skipTest("profiles/example-airframer.json not present")
+        r = run_build(self.tmp, extra_args=["--profile", PROFILE])
+        self.assertEqual(r.returncode, 0, (r.stdout + r.stderr)[-800:])
+        md = open(os.path.join(self.tmp, "memo.md")).read()
+        self.assertIn("Example Airframers Ltd", md)
+        self.assertIn("Program context (profile)", md)
+        m = json.load(open(os.path.join(self.tmp, "evidence", "model.json")))
+        self.assertEqual(m["profile"]["customer"], "Example Airframers Ltd")
+
+    def test_cli_overrides_flip_verdict(self):
+        # re-verify a code report that reports the correct integral:
+        # the integration check must now PASS
+        r = run_build(self.tmp, extra_args=["--code-integral", "50400.0"])
+        self.assertEqual(r.returncode, 0, (r.stdout + r.stderr)[-800:])
+        m = json.load(open(os.path.join(self.tmp, "evidence", "model.json")))
+        self.assertEqual(m["integration"]["verdict"], "PASS")
+        self.assertTrue(all(c["verdict"] == "PASS" for c in m["checks"]))
+        # findings become observations, not discrepancies
+        self.assertTrue(all(fd["severity"] == "observation"
+                            for fd in m["findings"]))
+
+    def test_check_still_works(self):
+        run_build(self.tmp)
+        md = os.path.join(self.tmp, "memo.md")
+        c = subprocess.run([sys.executable, CLI, "check", "--file", md],
+                           capture_output=True, text=True)
+        self.assertEqual(c.returncode, 0, c.stdout)
+        self.assertIn("RESULT: PASS", c.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/numerical-analysis-engineer/tests/test_numerical_analysis_core.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""Test numerical_analysis_core: the executable engine of the
+Numerical Analysis Engineer role.
+
+Proves the role can DO its job standalone (no AeroSkills needed):
+reference quadrature + Richardson error estimation, Newton/bisection
+root finding with the area-Mach anchor, pivoted reference solves,
+condition numbers, the three-mesh convergence study (observed order,
+Richardson extrapolation, GCI), the memo builder, evidence-gate checks,
+and the filled template.
+"""
+import math
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                "..", "core"))
+from numerical_analysis_core import (  # noqa: E402
+    EPS_MACH, GCI_FS, RULE_SELECTION,
+    area_mach_derivative, area_mach_ratio, area_mach_residual, bisection,
+    bracket_straddles, build_report, check_report, check_report_markdown,
+    condition_number, condition_report, convergence_verdict,
+    example_item, example_report_markdown, forward_error_bound,
+    grid_convergence_index, lift_intensity, max_abs_component_diff,
+    newton_iterations, newton_raphson, observed_order,
+    render_report_markdown, richardson_error_n, richardson_error_trapezoid,
+    richardson_extrapolation, root_sensitivity, select_integration_rule,
+    simpson, solve, trapezoid,
+)
+
+# Deterministic across midnight: the committed template carries the
+# generation date 2026-09-05; pin fresh renders to it (CI override wins).
+os.environ.setdefault("ROLE_GEN_DATE", "2026-09-05")
+
+ROLE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+TEMPLATE = os.path.join(ROLE_DIR, "templates",
+                        "verification-memo-template.md")
+
+
+class TestQuadratureRules(unittest.TestCase):
+
+    def test_trapezoid_linear_exact(self):
+        # trapezoid is exact for linears: integral of x on [0, 2] = 2
+        self.assertAlmostEqual(trapezoid(lambda x: x, 0.0, 2.0, 4), 2.0,
+                               places=12)
+
+    def test_quadratic_anchor_x2(self):
+        # integral of x^2 on [0, 2] = 8/3; trapezoid converges O(h^2)
+        est = trapezoid(lambda x: x * x, 0.0, 2.0, 1000)
+        self.assertAlmostEqual(est, 8.0 / 3.0, places=4)
+        # Simpson n=2 is exact for the quadratic
+        self.assertAlmostEqual(simpson(lambda x: x * x, 0.0, 2.0, 2),
+                               8.0 / 3.0, places=12)
+
+    def test_sin_anchor(self):
+        # integral of sin(x) on [0, pi] = 2 (leaf textbook anchor)
+        self.assertAlmostEqual(simpson(math.sin, 0.0, math.pi, 1000), 2.0,
+                               places=8)
+
+    def test_invalid_panels_raise(self):
+        with self.assertRaises(ValueError):
+            trapezoid(lambda x: x, 0.0, 1.0, 0)
+        with self.assertRaises(ValueError):
+            simpson(lambda x: x, 0.0, 1.0, 3)   # odd n raises
+        with self.assertRaises(ValueError):
+            trapezoid(lambda x: x, 0.0, 1.0, 2.5)
+
+    def test_richardson_error_estimate(self):
+        # error(2n) = |I_2n - I_n| / 3 ; on the smooth quadratic
+        # half-span load at n=16 this is 12.3046875 N (measured)
+        f = lambda y: lift_intensity(y, 4200.0, 36.0)
+        self.assertAlmostEqual(
+            richardson_error_trapezoid(f, 0.0, 18.0, 16), 12.3046875,
+            places=9)
+
+    def test_richardson_error_n_recovers_trapezoid_error(self):
+        # for an order-2 rule E_n = |I_n - I_2n|/(1 - 2^-2); on the
+        # quadratic integrand the trapezoid error is exactly known:
+        # I16 - exact = -49.21875 N
+        f = lambda y: lift_intensity(y, 4200.0, 36.0)
+        i16 = trapezoid(f, 0.0, 18.0, 16)
+        i32 = trapezoid(f, 0.0, 18.0, 32)
+        self.assertAlmostEqual(richardson_error_n(i16, i32, 2),
+                               abs(i16 - 4200.0 * 36.0 / 3.0), places=6)
+        self.assertAlmostEqual(richardson_error_n(i16, i32, 2), 49.21875,
+                               places=6)
+
+
+class TestRuleSelection(unittest.TestCase):
+
+    def test_smooth_selects_simpson(self):
+        sel = select_integration_rule("smooth")
+        self.assertEqual(sel["rule"], "composite Simpson")
+        self.assertEqual(sel["order"], 4)
+
+    def test_noisy_selects_trapezoid(self):
+        sel = select_integration_rule("arbitrary-or-noisy")
+        self.assertIn("trapezoid", sel["rule"])
+        self.assertEqual(sel["order"], 2)
+
+    def test_all_classes_have_rationale(self):
+        for cls, sel in RULE_SELECTION.items():
+            self.assertTrue(sel["rationale"])
+
+    def test_unknown_class_raises(self):
+        with self.assertRaises(ValueError):
+            select_integration_rule("not-a-class")
+
+
+class TestRootFinding(unittest.TestCase):
+
+    def test_sqrt2_anchors(self):
+        # f = x^2 - 2, root sqrt(2) = 1.4142135623730951
+        root_b = bisection(lambda x: x * x - 2.0, 1.0, 2.0)
+        root_n = newton_raphson(lambda x: x * x - 2.0, lambda x: 2.0 * x,
+                                1.5)
+        self.assertAlmostEqual(root_b, math.sqrt(2.0), places=9)
+        self.assertAlmostEqual(root_n, math.sqrt(2.0), places=9)
+
+    def test_newton_quadratic_speed(self):
+        # three Newton steps reach ~machine precision from x0 = 1.5
+        r = newton_iterations(lambda x: x * x - 2.0, lambda x: 2.0 * x, 1.5)
+        self.assertLessEqual(r["iterations"], 3)
+        self.assertLess(r["residual"], 1e-10)
+
+    def test_area_mach_subsonic_anchor(self):
+        # isentropic area-Mach relation, A/A* = 1.2, gamma = 1.4:
+        # subsonic root M = 0.59024876099 (leaf-tested anchor)
+        resid = lambda M: area_mach_residual(M, 1.2, 1.4)
+        deriv = lambda M: area_mach_derivative(M, 1.4)
+        rn = newton_raphson(resid, deriv, 0.3)
+        rb = bisection(resid, 0.2, 0.99)
+        self.assertAlmostEqual(rn, 0.59024876099, places=9)
+        self.assertAlmostEqual(rb, 0.59024876099, places=9)
+        self.assertLess(abs(area_mach_residual(rn, 1.2, 1.4)), 1e-10)
+
+    def test_bracket_behavior(self):
+        resid = lambda M: area_mach_residual(M, 1.2, 1.4)
+        ok = bracket_straddles(resid, 0.2, 0.99)
+        self.assertTrue(ok["straddles"])
+        bad = bracket_straddles(resid, 0.05, 0.4)  # both sides positive
+        self.assertFalse(bad["straddles"])
+        with self.assertRaises(ValueError):
+            bisection(resid, 0.05, 0.4)            # no sign change
+        # Newton step undefined when the derivative vanishes before
+        # convergence: f = x^3 - 1 from x0 = 0 has df(0) = 0
+        with self.assertRaises(ValueError):
+            newton_raphson(lambda x: x ** 3 - 1.0, lambda x: 3.0 * x * x, 0.0)
+
+    def test_root_sensitivity(self):
+        # simple root: sensitivity 1/|f'|; multiple root: unbounded
+        self.assertAlmostEqual(root_sensitivity(-2.0), 0.5)
+        self.assertEqual(root_sensitivity(0.0), float("inf"))
+
+
+class TestLinearSolveAndConditioning(unittest.TestCase):
+
+    def test_solve_leaf_anchor(self):
+        # matrix-operations leaf worked anchor:
+        # A x = b with A = [[2,1,-1],[-3,-1,2],[-2,1,2]], b = [8,-11,-3]
+        # gives x = [2, 3, -1]
+        A = [[2.0, 1.0, -1.0], [-3.0, -1.0, 2.0], [-2.0, 1.0, 2.0]]
+        b = [8.0, -11.0, -3.0]
+        x = solve(A, b)
+        self.assertAlmostEqual(x[0], 2.0, places=10)
+        self.assertAlmostEqual(x[1], 3.0, places=10)
+        self.assertAlmostEqual(x[2], -1.0, places=10)
+
+    def test_singular_matrix_raises(self):
+        with self.assertRaises(ValueError):
+            solve([[1.0, 2.0], [2.0, 4.0]], [1.0, 2.0])
+
+    def test_max_abs_component_diff(self):
+        self.assertAlmostEqual(max_abs_component_diff([1.0, 2.0],
+                                                      [1.0, 2.5]), 0.5)
+
+    def test_condition_number(self):
+        # kappa = s_max/s_min: [1.75, 0.25] -> 7
+        self.assertAlmostEqual(condition_number([1.75, 0.25]), 7.0)
+        self.assertEqual(condition_number([1.0, 0.0]), float("inf"))
+        with self.assertRaises(ValueError):
+            condition_number([])
+        with self.assertRaises(ValueError):
+            condition_number([-1.0])
+
+    def test_condition_report_and_bound(self):
+        rep = condition_report([1.75, 0.25])
+        self.assertAlmostEqual(rep["kappa"], 7.0)
+        self.assertAlmostEqual(rep["digits_lost_max"],
+                               math.log10(7.0), places=3)
+        self.assertFalse(rep["at_precision_limit"])
+        # classical forward-error bound: kappa * backward error
+        self.assertAlmostEqual(forward_error_bound(7.0, 1e-12), 7e-12)
+        # at the precision limit kappa >= 1/eps
+        lim = condition_report([EPS_MACH, 1.0])
+        self.assertTrue(lim["at_precision_limit"])
+
+
+class TestConvergenceStudy(unittest.TestCase):
+
+    # three-mesh trapezoid outputs of the half-span quadratic load
+    F1, F2, F3 = 50396.923828125, 50387.6953125, 50350.78125
+
+    def test_observed_order_is_two(self):
+        # trapezoid on a quadratic: exactly second order, ratio 4
+        p = observed_order(self.F1, self.F2, self.F3, 2.0)
+        self.assertAlmostEqual(p, 2.0, places=9)
+
+    def test_richardson_extrapolation_recovers_exact(self):
+        p = observed_order(self.F1, self.F2, self.F3, 2.0)
+        exact = richardson_extrapolation(self.F1, self.F2, 2.0, p)
+        self.assertAlmostEqual(exact, 50400.0, places=6)
+
+    def test_gci_fraction(self):
+        p = observed_order(self.F1, self.F2, self.F3, 2.0)
+        gci = grid_convergence_index(self.F1, self.F2, 2.0, p)
+        self.assertAlmostEqual(gci, 7.62986022096e-05, places=12)
+        self.assertEqual(GCI_FS, 1.25)
+
+    def test_convergence_verdicts(self):
+        v = convergence_verdict(self.F1, self.F2, self.F3, 2.0)
+        self.assertEqual(v["verdict"], "monotone converged")
+        self.assertAlmostEqual(v["order"], 2.0, places=9)
+        # diverging: |ratio| > 1 on the negative branch
+        vd = convergence_verdict(1.0, 0.5, 2.0, 2.0)
+        self.assertEqual(vd["verdict"], "diverging")
+        # oscillatory: ratio < 0 with |ratio| <= 1
+        vo = convergence_verdict(1.0, 0.5, 0.75, 2.0)
+        self.assertEqual(vo["verdict"], "oscillatory")
+        self.assertIsNone(vo["order"])
+
+    def test_invalid_studies_raise(self):
+        with self.assertRaises(ValueError):
+            observed_order(1.0, 2.0, 3.0, 1.0)      # r <= 1
+        with self.assertRaises(ValueError):
+            observed_order(1.0, 1.0, 1.5, 2.0)      # f2 == f1
+        with self.assertRaises(ValueError):
+            observed_order(1.0, 0.5, 0.6, 2.0)      # non-monotone
+
+
+class TestMemoBuilder(unittest.TestCase):
+
+    def test_example_item_reports(self):
+        item = example_item()
+        # code reported the n=16 trapezoid value (50350.78125 N) and the
+        # subsonic area-Mach root to 9 decimals
+        self.assertAlmostEqual(item.code_integral, 50350.78125, places=6)
+        self.assertAlmostEqual(item.code_mach, 0.590248761, places=9)
+
+    def test_model_structure(self):
+        model = build_report(example_item())
+        self.assertEqual(model["document_type"],
+                         "Numerical Methods Verification Memo")
+        self.assertEqual(model["status"], "draft-for-review")
+        self.assertEqual(len(model["checks"]), 3)
+        self.assertEqual(len(model["method_selection"]), 3)
+        self.assertTrue(model["findings"])
+
+    def test_example_verdicts(self):
+        # integration fails (49.2 N vs 1 N claim); root and solve pass
+        int_chk = build_report(example_item())["integration"]
+        self.assertEqual(int_chk["verdict"], "FAIL")
+        self.assertAlmostEqual(int_chk["discrepancy"], 49.21875, places=6)
+        root_chk = build_report(example_item())["root_finding"]
+        self.assertEqual(root_chk["verdict"], "PASS")
+        self.assertLess(root_chk["discrepancy"], 1e-9)
+        solve_chk = build_report(example_item())["linear_solve"]
+        self.assertEqual(solve_chk["verdict"], "PASS")
+        self.assertAlmostEqual(solve_chk["conditioning"]["kappa"], 7.0)
+
+    def test_convergence_in_model(self):
+        conv = build_report(example_item())["convergence"]
+        self.assertAlmostEqual(conv["observed_order"], 2.0, places=6)
+        self.assertAlmostEqual(conv["gci_fraction"], 7.62986022096e-05,
+                               places=12)
+        self.assertEqual(conv["verdict"], "monotone converged")
+        self.assertAlmostEqual(conv["richardson_extrapolated"], 50400.0,
+                               places=6)
+
+    def test_correct_report_flips_verdict(self):
+        # re-verify a code report that is actually correct: all PASS
+        item = example_item()
+        item.code_integral = 50400.0
+        model = build_report(item)
+        for c in model["checks"]:
+            self.assertEqual(c["verdict"], "PASS")
+
+    def test_core_gates_all_pass(self):
+        model = build_report(example_item())
+        gates = check_report(model)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_markdown_gates_all_pass(self):
+        md = example_report_markdown()
+        gates = check_report_markdown(md)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_sign_off_gate_fails_when_honest_marker_removed(self):
+        model = build_report(example_item())
+        model["status"] = "approved"
+        gates = check_report(model)
+        self.assertFalse(gates["sign_off_honest"])
+        self.assertFalse(gates["all_pass"])
+
+    def test_convergence_gate_fails_when_study_missing(self):
+        model = build_report(example_item())
+        model["convergence"] = {"meshes": []}
+        gates = check_report(model)
+        self.assertFalse(gates["convergence_study_present"])
+        self.assertFalse(gates["all_pass"])
+
+    def test_render_is_draft_and_not_approval(self):
+        md = example_report_markdown()
+        self.assertIn("draft", md.lower())
+        self.assertIn("not an approval", md.lower())
+        self.assertIn("Numerical Methods Verification Memo", md)
+
+    def test_template_is_the_filled_example(self):
+        # ROLE-STANDARD: the template IS the example deliverable
+        # generated by the core - byte-identical, zero blanks.
+        with open(TEMPLATE) as fh:
+            template = fh.read()
+        self.assertNotIn("___", template)
+        self.assertEqual(template, example_report_markdown())
+
+    def test_standalone_no_skills_repo(self):
+        # Core must work with no AeroSkills present
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = build_report(example_item())
+        md = render_report_markdown(model)
+        self.assertGreater(len(md), 2000)
+        self.assertTrue(check_report(model)["all_pass"])
+
+
+if __name__ == "__main__":
+    unittest.main()