aero-agent-roles 1.0.0

package/roles/flight-mechanics-engineer/templates/perf-sc-report-template.md

@@ -0,0 +1,82 @@
+# Performance and S&C Analysis Report
+
+**Aircraft:** AeroLine AT-78 (example transport configuration, 150-seat class)
+**Assessment basis:** FAR/CS Part 25 performance context (25.121/25.125/25.181) and MIL-STD-1797A mode criteria by analogy (aircraft class III (large transport, MIL-STD-1797A classing); flight phase categories B and C (cruise and approach)).
+**Status:** draft-for-review
+
+## 1. Mission performance
+
+**Cruise point:** FL350 (ISA -54 degC), M0.78, V = 231.3 m/s (450 kt TAS), MTOW. CL = 0.603, CD = 0.0351, L/D = 17.2; (L/D)max = 17.5 at CL* = 0.74. Input basis: MTOW 78,000 kg, cruise altitude FL350, M0.78, clean configuration, example class data.
+
+- **Still-air range (Breguet):** R = (V/(TSFC*g))*(L/D)*ln(W0/W1) = **6,492 km (3,506 nm)** burning 17,160 kg over the cruise segment (78,000 -> 60,840 kg). Breguet assumptions stated: constant L/D = 17.2, constant TSFC = 1.55e-05 kg/(N s), still air, cruise configuration.
+- **Loiter endurance (Breguet):** E = (1/(TSFC*g))*(L/D)*ln(W0/W1) = **1.56 h** on 3,000 kg hold fuel at L/D = 17.2.
+- **Specific air range:** SAR = V*(L/D)/(TSFC*W) = **335.0 m/kg** (0.335 km/kg); 5,000 km sector fuel ~ 14,925 kg. SAR curve (same weight, M = 0.74/0.78/0.82): 0.74 M -> 0.323 km/kg (L/D 17.4), 0.78 M -> 0.335 km/kg (L/D 17.2), 0.82 M -> 0.344 km/kg (L/D 16.8).
+- **Climb (MTOW, clean, all engines):** ROC(SL) = (T-D)V/W = **17.7 m/s (3,491 ft/min)** at 250 KCAS; ROC(FL350) = **6.50 m/s (1,280 ft/min)** (climb thrust scaled by sigma^0.7); time to climb SL->FL350 at mean ROC = **14.7 min**. ROC at FL410 = 3.19 m/s (628 ft/min); linear-lapse ceiling estimate ~45.9k ft (indicative; nonlinear refinement is an open item).
+- **Takeoff (SL ISA, MTOW):** Vs = 141 kt; V_LOF = V2 = 1.2*Vs = 169 kt; estimated ground roll Sg = 1.44*W^2/(g*rho*S*CLmax*(T-mu*W)) = **1,499 m** (mu = 0.03, CLmax = 1.9). The FAR 25.113 takeoff distance demonstration (airborne segment to 35 ft, 1.15 factor) is a flight-test determination - open item for the takeoff leaf build.
+- **Landing (SL ISA, MLW):** Vs = 112 kt, Vref = 1.3*Vs = 145 kt, touchdown = 138 kt; air distance over 50 ft 365 m + ground roll 511 m = 877 m actual; certified field length (FAR 25.125, x1.67) = **1,464 m**.
+- **Glide (engine-out reference):** best glide L/D = 17.5 at 227 kt EAS; from FL350: glide range 187 km, sink 6.6 m/s, 27 min to sea level.
+- **Turn (25 deg bank, cruise, MTOW):** n = 1/cos(phi) = 1.103; turn rate 1.13 deg/s; radius 11.7 km; sustained (yes: D_turn = 49,148 N vs cruise available 58,000 N).
+- **Wind effects (enroute):** 40 kt headwind lowers groundspeed 231 -> 211 m/s (6.00 h -> 6.59 h on 5,000 km).
+
+## 2. Safety performance
+
+- **OEI second segment (FAR 25.121(b), one engine inoperative at V2, gear up):** T_oei = 110,000 N, L/D = 10.8, gradient = (T_oei - D)/W = **5.13%** vs the 2-engine minimum of **2.4%** -> meets.
+- **Energy height / time to climb:** cruise energy height h_e = h + V^2/2g = **13,396 m** (44k ft), kinetic term 2,728 m of zoom-climb reserve; specific excess power equals ROC (steady unaccelerated) by identity.
+- **Wind / windshear effects:** enroute headwind case above (wind-effects leaf). Windshear assessment needs a shear profile (windshear-analysis leaf) - **open item**.
+
+## 3. Rotorcraft
+
+Not applicable to this example (fixed-wing transport). For a rotary-wing vehicle the rotorcraft performance leaves (hover OGE/IGE, forward flight, autorotation, tail-rotor sizing, vertical climb) replace this section.
+
+## 4. Stability
+
+- **Longitudinal static stability:** stick-fixed neutral point h_np = h_ac_w + V_h*(a_t/a_w)*(1-d_eps/d_alpha) = 0.25 + 0.862*0.72*0.55 = **0.591 MAC** (V_h = 0.862). Static margin SM = h_np - h_cg: **fwd CG 27.1%**, **aft CG 15.1%** (minimum margin band 0.05 MAC; positive SM = stable).
+- **Directional stability (build):** V_v = 0.051; Cn_beta(vt) = eta*V_v*a_vt*(1+k_s) = 0.179; total Cn_beta = **0.120/rad** (fuselage term -0.059) - directionally stable (Cn_beta > 0).
+- **Lateral stability (build):** dihedral term Cl_beta(gamma) = -CL*Gamma = -0.055 at cruise CL; total Cl_beta = **-0.080/rad** (remainder -0.025, class data) - laterally stable (Cl_beta < 0).
+- **Trim (linear model):** cruise CL_trim = 0.603, alpha_trim = 6.3 deg, elevator to trim -3.0 deg (limit +/-25 deg); approach CL_trim = 1.420, elevator to trim -14.0 deg. Linear-model values; the stabilizer/elevator split and flap Cm increments are trim-analysis + AVL stage items (open item).
+
+## 5. Dynamic modes
+
+| Mode | Condition | Frequency | Damping | Requirement | Result |
+|---|---|---|---|---|---|
+| short period | cruise FL350 aft CG | 1.10 rad/s (0.17 Hz) | zeta = 0.31 | FAR 25.181 heavily damped (zeta >= 0.3 band); MIL-STD-1797A cat B L1 zeta 0.30-2.00, freq floor 2.0 rad/s (n_alpha 9.1 g/rad, table-clamped) | damping L1, freq-limited -> Level 2 by analogy (FAR heavy damping met) |
+| short period | cruise FL350 fwd CG | 1.44 rad/s | zeta = 0.24 | as above | damping below L2 floor 0.25 -> Level 3 by analogy; fwd-CG cruise damping open item |
+| short period | approach aft CG | 0.77 rad/s | zeta = 0.57 | FAR 25.181; cat C L1 zeta 0.30-2.00, freq floor 2.0 rad/s | damping L1 -> Level 2 by analogy (frequency-limited) |
+| short period | approach fwd CG | 0.96 rad/s | zeta = 0.46 | as above | Level 2 by analogy |
+| phugoid | cruise FL350 | 0.0600 rad/s (T = 105 s) | zeta = 0.041 | FAR 25.181 not growing (zeta > 0); 1797A L1 zeta >= 0.04 | Level 1 (t_half 281 s, 2.7 cycles) |
+| phugoid | approach | 0.1855 rad/s (T = 34 s) | zeta = 0.085 | as above | Level 1 |
+| dutch roll | cruise FL350 | 0.92 rad/s (T = 6.8 s) | zeta = 0.099 (zeta*omega = 0.090) | FAR 25.181 positively damped; 1797A cat B L1 zeta >= 0.08 & zeta*omega >= 0.15 | stable (FAR ok); Level 2 by analogy - yaw damper need (GNC boundary) |
+| dutch roll | approach | 0.54 rad/s (T = 11.7 s) | zeta = 0.187 (product 0.101) | 1797A cat C L1 as above | Level 2 by analogy |
+| roll subsidence | cruise FL350 | tau = 1.35 s | - | 1797A cat B L1 tau <= 1.4 s | Level 1 |
+| roll subsidence | approach | tau = 1.30 s | - | 1797A cat C L1 tau <= 1.0 s | Level 2 |
+| spiral | cruise FL350 | lambda = -0.00365 1/s | - | 1797A L1 T2 >= 12 s (cat B); stable root passes | convergent, Level 1 |
+| spiral | approach | lambda = -0.01128 1/s | - | 1797A L1 T2 >= 20 s (cat C) | convergent, Level 1 |
+
+Short-period/phugoid frequency separation (omega_sp/omega_ph): 18x cruise, 4.1x approach (>= 5x ideal for the two-timescale split; well separated at cruise, tighter at approach - a full 4-DOF longitudinal root solve is an open item).
+
+## 6. Control effectiveness
+
+- Elevator authority for trim: cruise -3.0 deg, approach -14.0 deg of +/-25 deg limits (linear model; margins acceptable, verify in the AVL/6DOF stage - open item).
+- Aileron reversal: requires wing torsional stiffness and aileron geometry (aileron-reversal leaf) - **open item**.
+- Deep stall: example has a low-mounted tailplane; deep-stall analysis (deep-stall-analysis leaf) remains a verification item for the stall-characteristics campaign - open item.
+- Spin: no spin demonstration is required for the FAR Part 25 transport category; the spin-recovery leaf applies to Part 23-class vehicles.
+
+## 7. Handling qualities
+
+- Mode-based assessment (MIL-STD-1797A summary by analogy, class III): longitudinal modes damped at the aft-CG design point (zeta_sp 0.57 approach, 0.31 cruise); Dutch roll positively damped but below the Level 1 product criterion -> production fitment of a yaw damper is expected (SAS design is the GNC role boundary).
+- FAR 25.181 context: short period heavily damped (zeta >= 0.3 band met at the aft CG), phugoid not growing in amplitude (zeta > 0) - satisfied at the analyzed conditions; formal compliance is a flight-test demonstration, not an analytic finding (boundary).
+- Cooper-Harper ratings are pilot-in-the-loop observations: they are NOT assigned analytically. The cooper-harper-rating leaf structures the evaluation campaign (simulator/flight) - open item. PIO/pitch-bandwidth criteria likewise require the closed-loop response (6DOF + pilot model) - open item.
+
+## 8. Simulation
+
+- Trajectory evidence in this report is the analytic energy/climb set of sections 1-2 (specific excess power = rate of climb identity, energy height, time-to-climb at mean ROC).
+- Point-mass trajectory and 6-DOF simulation runs (point-mass-trajectory / six-dof-simulation leaves, JSBSim class tools) plus the AVL derivative build (stability-derivatives-avl leaf) are the deeper stages that replace the class-range derivative data - open items with the input basis recorded above.
+
+## 9. Conclusions and open items
+
+- Performance vs requirement: computed still-air range 6,492 km, cruise ROC 17.7 m/s at SL, takeoff ground roll 1,499 m, certified landing field 1,464 m - all in the class range for a 150-seat twin-engine transport at the stated assumptions (Breguet assumptions for range, example thrust ratings, dry runway).
+- S&C vs requirement: static margin 15.1% (aft CG) positive; short-period damping meets the FAR 25.181 heavy-damping band at the aft-CG design point (zeta 0.57 approach / 0.31 cruise); all modes stable.
+- Open items: (1) replace example class-range inputs with project data; (2) AVL derivative build and wind-tunnel/flight-data correlation; (3) takeoff distance/accelerate-stop demonstration inputs (takeoff leaf); (4) windshear profile analysis; (5) 6DOF/JSBSim trajectory and closed-loop handling checks; (6) stabilizer scheduling and elevator authority verification; (7) fwd-CG cruise pitch damping margin; (8) yaw damper authority (GNC role).
+
+---
+*Generated by Aero Agent Roles flight-mechanics-engineer core (2026-09-05). Every number above carries its stated input basis (mass, CG, altitude, configuration, assumptions). DRAFT for human flight-mechanics review - engineering assessment, not an approval or certification finding.*

package/roles/flight-mechanics-engineer/tests/test_flight_mechanics_core.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""Test flight_mechanics_core: the executable engine of the role.
+
+Proves the role can DO its job standalone (no AeroSkills needed): the
+domain rules produce REAL numbers (range, ROC, takeoff, static margin,
+short-period damping) that are physically plausible, the builder produces
+the full report model, the evidence gates pass, and the markdown
+deliverable carries every gate marker.
+"""
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                "..", "core"))
+from flight_mechanics_core import (  # noqa: E402
+    ExampleTransport, analyze_vehicle, assess_dutch_roll,
+    assess_phugoid, assess_roll_mode, assess_short_period, assess_spiral,
+    breguet_range, build_report, c_m_alpha_from_sm, check_report,
+    check_report_markdown, cl_beta_dihedral, cn_beta_vertical_tail,
+    elevator_to_trim, example_report_markdown, example_vehicle,
+    far_25_121_minimum, isa, jet_endurance, landing_ground_roll, neutral_point,
+    oei_gradient_pct, oei_thrust, phugoid_damping, render_report_markdown,
+    roll_time_constant, short_period_damping, short_period_frequency,
+    specific_air_range, spiral_eigenvalue, spiral_stability_parameter,
+    stall_speed, static_margin, takeoff_ground_roll,
+)
+
+G = 9.80665
+
+
+class TestDomainRules(unittest.TestCase):
+    """Real formulas from the bound flight-mechanics leaves."""
+
+    def test_isa_atmosphere(self):
+        sl = isa(0.0)
+        self.assertAlmostEqual(sl["rho"], 1.225, places=3)
+        self.assertAlmostEqual(sl["p"], 101325.0, delta=1.0)
+        self.assertAlmostEqual(sl["sigma"], 1.0, places=6)
+        fl350 = isa(10668.0)
+        self.assertTrue(0.35 < fl350["rho"] < 0.41, fl350["rho"])
+        self.assertAlmostEqual(fl350["T"], 218.81, delta=0.5)
+        self.assertAlmostEqual(fl350["a"] * 0.78, 231.3, delta=2.0)
+
+    def test_breguet_range_hand(self):
+        # R = (V/(TSFC*g))*(L/D)*ln(m0/m1) in meters
+        r = breguet_range(231.3, 1.55e-5, 17.2, 78000.0, 60840.0)
+        expect = (231.3 / (1.55e-5 * G)) * 17.2 * \
+            __import__("math").log(78000.0 / 60840.0)
+        self.assertAlmostEqual(r, expect, places=1)
+        self.assertGreater(r / 1000.0, 5000.0)  # multi-thousand km class
+
+    def test_breguet_rejects_no_fuel(self):
+        with self.assertRaises(ValueError):
+            breguet_range(231.3, 1.55e-5, 17.2, 78000.0, 78000.0)
+
+    def test_jet_endurance_hours(self):
+        e = jet_endurance(1.55e-5, 17.2, 62000.0 * G, 59000.0 * G)
+        self.assertGreater(e, 3000.0)   # ~1.5 h loiter
+        self.assertLess(e, 20000.0)
+
+    def test_specific_air_range_units(self):
+        sar = specific_air_range(231.3, 1.55e-5, 78000.0 * G, 17.2)
+        self.assertTrue(100.0 < sar < 1000.0)  # ~0.3 km/kg
+
+    def test_takeoff_rules(self):
+        vs = stall_speed(6119.0, 1.225, 1.9)
+        self.assertAlmostEqual(vs, 72.5, delta=1.0)   # ~141 kt
+        sg = takeoff_ground_roll(78000.0 * G, 125.0, 220000.0, 1.225, 1.9)
+        self.assertTrue(1000.0 < sg < 2500.0, sg)     # realistic ground roll
+        with self.assertRaises(ValueError):
+            takeoff_ground_roll(78000.0 * G, 125.0, 1000.0, 1.225, 1.9)
+
+    def test_landing_certified_factor(self):
+        res = analyze_vehicle(example_vehicle())
+        self.assertAlmostEqual(res["land_certified"],
+                               res["land_actual"] * 1.67, places=3)
+        self.assertTrue(1000.0 < res["land_certified"] < 3000.0)
+
+    def test_oei_far_25_121(self):
+        self.assertEqual(far_25_121_minimum("second-segment", 2), 2.4)
+        self.assertEqual(far_25_121_minimum("approach", 2), 2.1)
+        self.assertEqual(far_25_121_minimum("landing", 4), 3.2)
+        t = oei_thrust(220000.0, 2, 1)
+        self.assertEqual(t, 110000.0)
+        res = analyze_vehicle(example_vehicle())
+        self.assertGreater(res["oei"]["gradient_pct"],
+                           res["oei"]["min_pct"])  # meets 25.121(b)
+
+    def test_neutral_point_and_margin(self):
+        np_ = neutral_point(0.25, 0.862, 0.72, 0.45)
+        self.assertAlmostEqual(np_, 0.591, places=3)
+        self.assertAlmostEqual(static_margin(np_, 0.44), 0.1515, places=3)
+        with self.assertRaises(ValueError):
+            static_margin(1.2, 0.3)
+
+    def test_cm_alpha_sign(self):
+        self.assertAlmostEqual(c_m_alpha_from_sm(5.5, 0.1515), -0.833, places=3)
+        self.assertLess(c_m_alpha_from_sm(5.5, 0.15), 0.0)
+
+    def test_lateral_stability_build(self):
+        clb = cl_beta_dihedral(0.603, 5.2)
+        self.assertAlmostEqual(clb, -0.0547, places=3)  # -CL*Gamma
+        cnb_vt = cn_beta_vertical_tail(0.95, 0.0512626, 3.4, 0.08)
+        self.assertAlmostEqual(cnb_vt, 0.1788, places=3)
+        aero = analyze_vehicle(example_vehicle())["aero"]
+        self.assertGreater(aero["cn_beta"], 0.0)   # directionally stable
+        self.assertLess(aero["cl_beta"], 0.0)      # laterally stable
+
+    def test_short_period_hand_identity(self):
+        # short period from the dynamic-stability leaf formulas
+        qbar = 0.5 * 0.37949 * 231.3 ** 2
+        za = -(qbar * 125.0 * 5.5) / 78000.0
+        cm_a = c_m_alpha_from_sm(5.5, 0.1515)
+        ma = qbar * 125.0 * 3.4916 * cm_a / 3.4e6
+        mq = qbar * 125.0 * 3.4916 ** 2 * (-30.0) / (2 * 231.3 * 3.4e6)
+        om = short_period_frequency(za, ma, mq, 231.3)
+        zeta = short_period_damping(za, ma, mq, 231.3)
+        self.assertTrue(0.9 < om < 1.4, om)
+        self.assertTrue(0.2 < zeta < 0.45, zeta)
+
+    def test_phugoid_damping_small(self):
+        z = phugoid_damping(17.2)
+        self.assertAlmostEqual(z, 1.0 / (1.41421356 * 17.2), places=5)
+        self.assertGreater(z, 0.0)
+
+    def test_spiral_roll_dutch_roll_helpers(self):
+        # stable spiral criterion term > 0 -> convergent
+        self.assertGreater(spiral_stability_parameter(-1.8, 0.23, 0.84,
+                                                       -0.14), 0.0)
+        lam = spiral_eigenvalue(-1.8, 0.23, 0.84, -0.14, -0.74, 231.3)
+        self.assertLess(lam, 0.0)                      # convergent spiral
+        with self.assertRaises(ValueError):
+            roll_time_constant(0.5)                     # L_p must be < 0
+        self.assertAlmostEqual(roll_time_constant(-0.74), 1.351, places=3)
+
+
+class TestFlyingQualitiesAssessors(unittest.TestCase):
+    """Level criteria as summarized by the mil-std-1797a leaf."""
+
+    def test_short_period_level1(self):
+        r = assess_short_period(0.50, 3.5, "A", "III", 1.0)
+        self.assertEqual(r["level"], 1)
+
+    def test_short_period_frequency_degrade(self):
+        r = assess_short_period(0.50, 2.0, "A", "III", 3.0)  # floor 6.0
+        self.assertEqual(r["level"], 2)
+
+    def test_short_period_band_boundary(self):
+        r = assess_short_period(0.31, 2.0, "B", "III", 1.0)
+        self.assertEqual(r["level"], 1)   # cat B floor 0.30
+
+    def test_dutch_roll_levels(self):
+        self.assertEqual(assess_dutch_roll(0.1, 1.6, "B", "III"), 1)
+        self.assertEqual(assess_dutch_roll(0.1, 0.5, "B", "III"), 2)
+        self.assertEqual(assess_dutch_roll(-0.01, 0.5, "B", "III"), 3)
+
+    def test_phugoid_spiral_roll_levels(self):
+        self.assertEqual(assess_phugoid(0.041), 1)
+        self.assertEqual(assess_phugoid(0.02), 2)
+        self.assertEqual(assess_phugoid(-0.01), 3)
+        self.assertEqual(assess_spiral(-0.004, "B"), 1)
+        self.assertEqual(assess_roll_mode(1.3, "B"), 1)
+        self.assertEqual(assess_roll_mode(1.3, "C"), 2)
+
+
+class TestAnalysisAndBuilder(unittest.TestCase):
+
+    @classmethod
+    def setUpClass(cls):
+        cls.vehicle = example_vehicle()
+        cls.results = analyze_vehicle(cls.vehicle)
+        cls.model = build_report(cls.vehicle, cls.results)
+
+    def test_example_transport_realistic_class(self):
+        v = self.vehicle
+        self.assertTrue(100.0 < v.s < 200.0)
+        self.assertTrue(60000.0 < v.m_mtow < 100000.0)
+        self.assertTrue(0.25 < v.thrust_total_to / v.w_mtow < 0.35)
+
+    def test_range_number(self):
+        self.assertTrue(5500.0 < self.results["range_km"] < 8000.0,
+                        self.results["range_km"])
+
+    def test_climb_roc_number(self):
+        self.assertTrue(10.0 < self.results["roc_sl"] < 30.0)
+        self.assertTrue(2.0 < self.results["roc_350"] < 12.0)
+
+    def test_takeoff_number(self):
+        self.assertTrue(1000.0 < self.results["to_ground_roll"] < 2500.0)
+
+    def test_static_margins(self):
+        sm_f = self.results["aero"]["sm_fwd"]
+        sm_a = self.results["aero"]["sm_aft"]
+        self.assertGreater(sm_f, sm_a)
+        self.assertGreater(sm_a, 0.05)   # above the minimum margin band
+
+    def test_short_period_numbers(self):
+        ca = self.results["sp_cruise_aft"]
+        aa = self.results["sp_appr_aft"]
+        self.assertTrue(0.8 < ca["omega_sp"] < 2.0)
+        self.assertTrue(0.25 < ca["zeta_sp"] < 0.5)
+        self.assertTrue(0.5 < aa["omega_sp"] < 1.5)
+        self.assertTrue(0.4 < aa["zeta_sp"] < 0.9)
+        # aft CG short period damping exceeds the FAR heavy-damping band
+        self.assertGreaterEqual(aa["zeta_sp"], 0.30)
+
+    def test_modes_all_stable(self):
+        self.assertGreater(self.results["phugoid_cruise"]["zeta"], 0.0)
+        self.assertGreater(self.results["lat_cruise"]["zeta_dr"], 0.0)
+        self.assertLess(self.results["lat_cruise"]["lambda_spiral"], 0.0)
+        self.assertGreater(self.results["lat_appr"]["zeta_dr"], 0.0)
+
+    def test_derivative_signs(self):
+        sp = self.results["sp_cruise_aft"]
+        self.assertLess(sp["za"], 0.0)      # Z_alpha negative
+        self.assertLess(sp["ma"], 0.0)      # M_alpha negative (stable)
+        self.assertLess(sp["mq"], 0.0)      # M_q negative (damping)
+        la = self.results["lat_cruise"]
+        self.assertGreater(la["nb"], 0.0)   # yaw stiffness
+        self.assertLess(la["lp"], 0.0)      # roll damping
+
+    def test_elevator_trim_within_authority(self):
+        tr = self.results["trim_cruise"]
+        ta = self.results["trim_appr"]
+        lim = self.vehicle.elevator_limit_deg
+        self.assertLess(abs(tr["de_deg"]), lim)
+        self.assertLess(abs(ta["de_deg"]), lim)
+
+    def test_model_has_all_sections(self):
+        self.assertEqual(self.model["document_type"],
+                         "Performance and S&C Analysis Report")
+        self.assertEqual(self.model["status"], "draft-for-review")
+
+
+class TestGatesAndDeliverable(unittest.TestCase):
+
+    def test_core_gates_all_pass(self):
+        r = analyze_vehicle(example_vehicle())
+        gates = check_report(r)
+        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_rendered_sections(self):
+        md = example_report_markdown()
+        for sec in ["## 1. Mission performance", "## 4. Stability",
+                    "## 5. Dynamic modes", "## 7. Handling qualities",
+                    "## 9. Conclusions"]:
+            self.assertIn(sec, md)
+        self.assertIn("not an approval", md.lower())
+        self.assertIn("draft", md.lower())
+
+    def test_template_zero_blanks(self):
+        here = os.path.dirname(os.path.abspath(__file__))
+        tmpl = os.path.join(here, "..", "templates",
+                            "perf-sc-report-template.md")
+        with open(tmpl) as f:
+            text = f.read()
+        self.assertNotIn("___", text)
+        self.assertIn("AeroLine AT-78", text)
+
+    def test_standalone_no_skills_repo(self):
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        v = example_vehicle()
+        r = analyze_vehicle(v)
+        md = render_report_markdown(build_report(v, r))
+        self.assertGreater(len(md), 5000)
+        self.assertTrue(check_report(r)["all_pass"])
+        self.assertTrue(check_report_markdown(md)["all_pass"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/flight-mechanics-engineer/tests/test_role_flight_mechanics_engineer.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Role test: flight-mechanics-engineer."""
+import os
+import re
+import unittest
+
+ROLES_REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(
+    os.path.abspath(__file__)))))
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+HAS_SKILLS = os.path.isdir(os.path.join(AEROSKILLS, "skills"))
+ROLE_DIR = os.path.join(ROLES_REPO, "roles", "flight-mechanics-engineer")
+TEMPLATE = os.path.join(ROLE_DIR, "templates", "perf-sc-report-template.md")
+
+EXPECTED_BOUND = [
+    "flight-mechanics/performance/breguet-range",
+    "flight-mechanics/performance/breguet-endurance",
+    "flight-mechanics/performance/specific-range",
+    "flight-mechanics/performance/climb-performance",
+    "flight-mechanics/performance/descent-performance",
+    "flight-mechanics/performance/glide-performance",
+    "flight-mechanics/performance/takeoff-performance",
+    "flight-mechanics/performance/landing-performance",
+    "flight-mechanics/performance/turn-performance",
+    "flight-mechanics/performance/thrust-required",
+    "flight-mechanics/performance/oei-climb-gradient",
+    "flight-mechanics/performance/energy-height",
+    "flight-mechanics/performance/speed-stability",
+    "flight-mechanics/performance/wind-effects",
+    "flight-mechanics/performance/windshear-analysis",
+    "flight-mechanics/performance/rotorcraft-hover-performance",
+    "flight-mechanics/performance/rotorcraft-forward-flight-performance",
+    "flight-mechanics/performance/rotorcraft-blade-element-hover-performance",
+    "flight-mechanics/performance/rotorcraft-autorotative-descent",
+    "flight-mechanics/performance/rotorcraft-tail-rotor-sizing",
+    "flight-mechanics/performance/rotorcraft-vertical-climb-performance",
+    "flight-mechanics/stability-control/longitudinal-stability",
+    "flight-mechanics/stability-control/lateral-directional-stability",
+    "flight-mechanics/stability-control/dynamic-stability",
+    "flight-mechanics/stability-control/short-period-mode-analysis",
+    "flight-mechanics/stability-control/phugoid-mode-analysis",
+    "flight-mechanics/stability-control/trim-analysis",
+    "flight-mechanics/stability-control/stability-derivatives-avl",
+    "flight-mechanics/stability-control/control-surface-effectiveness",
+    "flight-mechanics/stability-control/aileron-reversal",
+    "flight-mechanics/stability-control/deep-stall-analysis",
+    "flight-mechanics/stability-control/spin-recovery",
+    "flight-mechanics/handling-qualities/cooper-harper-rating",
+    "flight-mechanics/handling-qualities/mil-std-1797a",
+    "flight-mechanics/handling-qualities/pilot-induced-oscillation",
+    "flight-mechanics/handling-qualities/pitch-bandwidth-criteria",
+    "flight-mechanics/flight-dynamics-sim/point-mass-trajectory",
+    "flight-mechanics/flight-dynamics-sim/six-dof-simulation"
+]
+
+STAGES = [
+    "1. Range/endurance",
+          "2. Mission performance",
+          "3. Safety performance",
+          "4. Rotorcraft performance",
+          "5. Static stability",
+          "6. Dynamic stability",
+          "7. Control effectiveness",
+          "8. Handling qualities",
+          "9. Simulation",
+          "10. Report"
+]
+
+
+def role_text():
+    p = os.path.join(ROLE_DIR, "ROLE.md")
+    if not os.path.exists(p):
+        return None
+    with open(p) as f:
+        return f.read()
+
+
+class TestFlightMechanicsEngineerRole(unittest.TestCase):
+
+    def test_bound_skills_resolve(self):
+        if not HAS_SKILLS:
+            self.skipTest("skills checkout absent (cross-repo dev check)")
+        for leaf in EXPECTED_BOUND:
+            self.assertTrue(
+                os.path.exists(os.path.join(AEROSKILLS, "skills", leaf, "SKILL.md")),
+                f"bound skill missing: {leaf}")
+
+    def test_stages_ordered(self):
+        role = role_text()
+        self.assertIsNotNone(role)
+        wf = role[role.find("## Workflow"):role.find("## Evidence gates")]
+        idx = [wf.find(s) for s in STAGES]
+        self.assertTrue(all(i >= 0 for i in idx), "stage missing in workflow")
+        self.assertEqual(idx, sorted(idx), "stage order not deterministic")
+
+    def test_template_present(self):
+        self.assertTrue(os.path.exists(TEMPLATE), "deliverable template missing")
+
+    def test_template_is_filled_deliverable(self):
+        """100% standard: the template IS a complete worked example report
+        (zero blank ___, all sections, gate markers)."""
+        with open(TEMPLATE) as f:
+            text = f.read()
+        self.assertNotIn("___", text)
+        for n in range(1, 10):
+            self.assertTrue(
+                re.search(rf"^## {n}\. ", text, re.M),
+                f"report section {n} missing")
+        low = text.lower()
+        self.assertIn("draft", low)
+        self.assertIn("not an approval", low)
+        self.assertIn("aeroline at-78", low)
+        # key computed numbers present (range, ROC, static margin, damping)
+        self.assertRegex(text, r"\d[\d,]*\s*km")
+        self.assertRegex(text, r"static margin[^\n]*\d+\.\d+%")
+        self.assertRegex(text, r"zeta\s*=\s*\d+\.\d+")
+
+    def test_core_engine_exists(self):
+        """100% standard: every role ships an executable core + cli."""
+        for f in ["core", "cli.py"]:
+            self.assertTrue(os.path.exists(os.path.join(ROLE_DIR, f)),
+                            f"{f} missing - role is not executable")
+
+    def test_core_test_file_exists(self):
+        core_test = os.path.join(ROLE_DIR, "tests",
+                                 "test_flight_mechanics_core.py")
+        self.assertTrue(os.path.exists(core_test),
+                        "core test file missing")
+
+    def test_boundaries(self):
+        role = role_text()
+        self.assertIsNotNone(role)
+        for phrase in ["sign_off_required: true", "forbidden"]:
+            self.assertIn(phrase, role)
+
+    def test_sources(self):
+        self.assertTrue(os.path.exists(os.path.join(ROLE_DIR, "SOURCES.md")),
+                        "SOURCES.md missing")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/flight-test-engineer/ROLE.md

@@ -0,0 +1,137 @@
+---
+type: role
+name: flight-test-engineer
+title: "Flight Test Engineer"
+status: draft
+domain: flight-test-operations
+deliverable_type: "flight test plan + envelope expansion report"
+standards_bound:
+  - id: far-25
+    tier: TIER-1
+    reference-only: false
+  - id: mil-std-1797a
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - flight-test-operations/planning/flight-test-safety
+  - flight-test-operations/envelope/envelope-expansion
+  - flight-test-operations/envelope/v-speeds
+  - flight-test-operations/envelope/load-factor-envelope
+  - flight-test-operations/envelope/stall-characteristics-testing
+  - flight-test-operations/envelope/high-angle-of-attack-testing
+  - flight-test-operations/envelope/buffet-boundary-testing
+  - flight-test-operations/envelope/spin-testing
+  - flight-test-operations/envelope/icing-flight-test
+  - flight-test-operations/envelope/vmc-determination
+  - flight-test-operations/envelope/flight-loads-survey
+  - flight-test-operations/envelope/structural-coupling-test
+  - flight-test-operations/flutter/ground-vibration-testing
+  - flight-test-operations/flutter/flight-vibration-survey
+  - flight-test-operations/flutter/flutter-testing
+  - flight-test-operations/flutter/limit-cycle-oscillation
+  - flight-test-operations/performance/accelerate-stop-distance
+  - flight-test-operations/performance/climb-performance-flight-test
+  - flight-test-operations/performance/cruise-performance-flight-test
+  - flight-test-operations/performance/engine-failure-takeoff-flight-test
+  - flight-test-operations/performance/engine-flight-test
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "clear an envelope"
+  - "declare airworthiness"
+  - "authorize flight"
+  - "reproduce proprietary standard text"
+sign_off_required: true
+license: Apache-2.0
+compatibility: "agentskills.io ROLE.md; any SKILL.md host"
+metadata:
+  version: 0.2.0
+  author: Aero Agent Roles
+  skills_release: "v1.3.0+"
+---
+
+# Flight Test Engineer
+
+## Role identity
+
+Owns the flight test campaign: plan safe, structured envelope expansion
+and performance flights; define the test points, instrumentation,
+build-up approach, and safety limits; reduce and report the data with
+clear PASS/FAIL against requirements. Use when a vehicle must prove its
+flight characteristics in the air (envelope, stall, flutter, V-speeds,
+performance). Do NOT use for ground certification workflow, design
+analysis (aero/structures), or control law design.
+
+## Deliverable contract
+
+1. **Flight test plan** - objectives, build-up blocks, test points,
+   instrumentation, safety limits, crew/airspace, data criteria.
+2. **Envelope expansion report** - results per test (V-speeds, stall,
+   flutter, loads, icing, VMC), limits expanded with evidence, findings.
+3. **Safety assessment** - risks + mitigations per test block.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Safety planning | flight-test-safety | risk assessment, limits, go/no-go |
+| 2. Ground vibration | ground-vibration-testing | GVT results, mode clearance |
+| 3. Flutter build-up | flight-vibration-survey + flutter-testing + limit-cycle-oscillation | flutter clearance per point |
+| 4. V-speeds | v-speeds + vmc-determination | V-speeds determination |
+| 5. Envelope expansion | envelope-expansion + load-factor-envelope | build-up block results |
+| 6. Stall/alpha | stall-characteristics-testing + high-angle-of-attack-testing | stall margins |
+| 7. Buffet/loads | buffet-boundary-testing + flight-loads-survey | buffet boundary, loads survey |
+| 8. Spin/icing | spin-testing + icing-flight-test | spin/icing results |
+| 9. Structural coupling | structural-coupling-test | coupling check |
+| 10. Performance | accelerate-stop-distance + climb-performance-flight-test + cruise-performance-flight-test + engine-failure-takeoff-flight-test + engine-flight-test | performance results |
+| 11. Report | (all above) | the test plan + expansion report |
+
+## Evidence gates
+
+- Stage 1 done = every test block has a stated limit + abort criteria.
+- Stage 3 done = flutter tested to the planned build-up with no LCO
+  beyond limits.
+- FINAL = each envelope limit change traces to a flight data point; no
+  clearance claimed beyond the data.
+
+## Boundary / forbidden
+
+- NEVER clear an envelope, declare airworthiness, or authorize flight.
+  The flight test CONDUCTOR / authority does that.
+- Reports state "data supports expanding to X pending human sign-off",
+  never "envelope cleared". Every deliverable carries the explicit
+  "not a clearance" marker.
+- Icing/spin results are test-specific; never generalize beyond the
+  tested configuration.
+
+## Verification
+
+The role runs STANDALONE: `core/flight_test_core.py` is an executable
+engine that computes V-speeds (vref = 1.3*vs0, v2 = 1.2*vs1, vr =
+1.1*vs1), the maneuvering speed VA = VS*sqrt(n_max), stall warning and
+recovery checks, the flutter build-up with the 0.03 minimum damping and
+1.2 x V_D margin, the altitude/Mach grid, the load factor envelope,
+climb gradient check, and the safety/go-no-go register; BUILDS the
+flight test plan + envelope expansion report; and gate-checks the
+deliverable. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out plan.md                     # worked-example aircraft
+python3 cli.py check --file plan.md                    # gate-check a plan/report
+```
+
+Tests:
+- tests/test_flight_test_engineer_core.py (24 tests): domain rules +
+  builder + gates + standalone (no skills repo)
+- tests/test_role_flight_test_engineer.py: bound-skill resolution
+  (skips if the skills repo is absent) + workflow + template filled +
+  executable core + boundaries
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (safety, envelope expansion, flutter, stall,
+performance methodology); the core engine does not depend on them.
+
+## Compliance
+
+- far-25 + mil-std-1797a context. Data references summary-not-copy.
+- SOURCES.md records standards referenced.

package/roles/flight-test-engineer/SOURCES.md

@@ -0,0 +1,24 @@
+# SOURCES.md - Flight Test Engineer
+
+Standards and documents this role references. Summary-not-copy: see
+[STANDARDS.md](../../STANDARDS.md) for the full rule and purchase links.
+
+| Source | Role use | Gated |
+|---|---|---|
+| 14 CFR Part 25 (FAR-25, public domain) | V-speed factors (25.107/25.125 context), flutter margin and damping (25.629), stall warning and recovery (25.203/25.207), maneuvering speed (25.335), climb gradient context (25.121) | false |
+| EASA CS-25 (free download) | same context as FAR-25 for European basis | false |
+| MIL-STD-1797A | handling qualities evaluation during flight test | false |
+| FAA Flight Test Guide (AC) | accepted flight test methodology | false |
+| Kimberlin, Flight Testing of Fixed-Wing Aircraft | flight test build-up methods (book) | true |
+| Ward, Introduction to Flight Test Engineering | methods (book) | true |
+| ISA atmosphere (public physics) | altitude/Mach grid reduction (sigma, speed of sound) | false |
+
+The flight test plan and envelope expansion report in `templates/` and
+the numbers produced by `core/flight_test_core.py` come from the domain
+rules encoded in the bound Aero Agent Skills flight-test-operations
+leaves (v-speeds, envelope-expansion, flutter-testing,
+stall-characteristics-testing, climb-performance-flight-test,
+flight-test-safety, flight-test-planning), which themselves paraphrase
+the FAR/CS-25 context and common flight test practice. Summary-not-copy
+per STANDARDS.md; no proprietary text is reproduced. Worked-example
+flight data in the template is explicitly labeled simulated.