aero-agent-roles 1.0.0

package/roles/aircraft-design-engineer/templates/concept-design-template.md

@@ -0,0 +1,99 @@
+# Concept Design Package - RegionalJet-1500 (100 pax / 1500 nm / M0.78)
+
+**Document type:** Concept Design Package  
+**Status:** draft-for-review  
+**Aircraft class:** transport (class-I conceptual sizing)
+**Generated:** 2026-09-05
+
+## 1. Requirements and design space
+
+| Requirement | Value |
+|---|---|
+| Passengers | 100 pax |
+| Payload | 20,000 lb (100 pax x 200 lb + baggage, class-I) |
+| Design range | 1,500 nm |
+| Cruise | M0.78 at 10,668 m (FL350), 450 kt TAS |
+| Takeoff field length | 1,829 m (6,001 ft) |
+| Engines | 2 turbofans |
+
+Constraint diagram (matching chart, T/W vs W/S; SI inputs, sea-level ISA for takeoff, cruise at FL350):
+
+| Constraint | Rule | Value at design W/S |
+|---|---|---|
+| Stall (max W/S) | W/S = 0.5*rho*CLmax*VS^2 | 5,512 N/m^2 (115.1 psf) |
+| Takeoff | T/W = 1.21*(W/S)/(rho*g*CLmax*s_TO) | 0.1404 |
+| Climb | T/W = 1/LD + gamma (OEI -> installed, x n/(n-1)) | 0.2147 |
+| Cruise | T/W = q*CD0/(W/S) + k*(W/S)/q | 0.0569 |
+
+**Selected design point:** W/S = 5,100 N/m^2 (106.5 psf), T/W = 0.2147 (binding constraint: climb).
+**Feasible:** True - the point lies on the lower bound of the feasible region (stall limit not exceeded).
+Feasible-region boundary samples (W/S N/m^2 -> minimum T/W): 1,378 -> 0.2147, 1,895 -> 0.2147, 2,412 -> 0.2147, 2,929 -> 0.2147, 3,445 -> 0.2147, 3,962 -> 0.2147, 4,479 -> 0.2147, 4,996 -> 0.2147, 5,512 -> 0.2147.
+
+## 2. Sizing mission
+
+Mission profile (segments in flight order; each burns from the weight remaining after earlier segments, Breguet range/endurance models):
+
+| Segment | Fuel burned | Fraction of MTOW |
+|---|---|---|
+| Taxi | 300 lb | 0.2% of MTOW |
+| Takeoff | 900 lb | 0.7% of MTOW |
+| Climb | 6,000 lb | 5.0% of MTOW |
+| Cruise (1,500 nm @ 450 kt) | 30,057 lb | 25.0% of MTOW |
+| Descent | 750 lb | 0.6% of MTOW |
+
+| **Block fuel** | **38,007 lb** | **31.6%** |
+| Block time | 4.19 hr | |
+| Landing weight | 82,292 lb | |
+| Reserve (hold45_5pct: 45 min hold at 1500 ft + 5% trip) | 3,932 lb | |
+| **Required fuel (mission + reserves)** | **41,939 lb** | **34.9% of MTOW** |
+
+## 3. Configuration (from the design point)
+
+- Wing loading W/S: 5,100 N/m^2 (106.5 psf) - design choice, 92.5% of the stall-limited maximum.
+- Wing area S = W/(W/S) = 104.9 m^2 (1,129 ft^2); aspect ratio 9.5; span b = 31.6 m.
+- Drag model: CD0 = 0.018, e = 0.80, k = 1/(pi*e*AR) = 0.0419; L/D_max = 18.2 (consistent with the mission cruise L/D of 18).
+- Engines: 2 x ~12,912 lbf class sea-level static thrust (see Section 5).
+- 3-view reference geometry from the OpenVSP stage (initial layout) feeds the class-II mass build-up; not required for the class-I sizing closure.
+
+## 4. Mass statement (class-I, balances to converged MTOW)
+
+| Group | Weight (lb) | % MTOW |
+|---|---|---|
+| Operating empty weight (class-I fit 0.485 x MTOW) | 58,345 | 48.5% |
+| Design payload (100 pax x 200 lb + cargo) | 20,000 | 16.6% |
+| Fuel (mission + reserves, hold45_5pct) | 41,939 | 34.9% |
+| **Maximum takeoff weight (converged)** | **120,298** | **100.0%** |
+
+- Balance check (empty + payload + fuel vs MTOW): PASS within 1%.
+- Empty-weight fraction 0.485 inside the transport class-I band 0.42-0.55: PASS.
+- Weight-growth context: conceptual phase growth allowance 10% applies to the detailed mass budget roll-up (mass-budget stage).
+- CG envelope and critical loading conditions require the 3-view layout and the mass-properties stage (component arms); the class-I closure above bounds the balance (fuel + payload = 61,939 lb available below MTOW - OEW = 61,954 lb).
+
+## 5. MTOW convergence and engine size check
+
+Fuel-fraction sizing iteration (W0 = payload / (1 - W_e/W0 - W_f/W0), class-I empty fraction 0.485):
+
+| Iteration | Guess (lb) | Fuel fraction | New MTOW (lb) | Rel. change |
+|---|---|---|---|---|
+| 1 | 100,000 | 0.3591 | 128,259 | 28.26% |
+| 2 | 128,259 | 0.3454 | 117,944 | 8.04% |
+| 3 | 117,944 | 0.3496 | 120,955 | 2.55% |
+| 4 | 120,955 | 0.3483 | 120,007 | 0.78% |
+| 5 | 120,007 | 0.3487 | 120,298 | 0.24% |
+
+**Converged MTOW = 120,298 lb (54,566 kg)** after 5 iterations (tolerance 0.5%): CONVERGED.
+
+- Installed sea-level thrust: 25,824 lbf total = 12,912 lbf per engine (T/W = 0.215).
+- Engine weight estimate: ~2,582 lb per engine at engine T/W = 5.0 (4-6 typical band).
+- Top-of-climb margin at 10,668 m (thrust lapse sigma^0.7 vs W/(L/D)): 1.81 - PASS (>= 1.0).
+- Engine-out second-segment gradient is carried on the installed basis: T/W = (n/(n-1)) x (1/LD + gamma) with LD = 12 and gamma = 0.024 (FAR 25.121(b)(1) two-engine value, 2 engines); the engine-sizing stage re-checks OEI climb, hot day, and takeoff derate against the catalogue engine.
+
+## 6. Feasibility notes and next stages
+
+- Class-I results are FEASIBILITY, not detailed design: the converged MTOW, the W/S-T/W design point, and the mass statement close the sizing loop within the stated class-I model accuracy.
+- Structure/propulsion/systems mass split requires the class-II component build-up (weight-estimation, engine-sizing, fuselage/wing/tail-sizing leaves); the conceptual growth allowance (10%) is the margin policy for that roll-up.
+- Payload-range, cost (parametric DOC/LCC), and CG envelope are produced by the dedicated stages (payload-range-diagram, parametric-cost, cg-envelope) once the class-II breakdown exists.
+
+---
+
+*DRAFT - conceptual feasibility for human design review. Not a production release and not an approval document. Conceptual results are class-I estimates; every configuration choice must trace to the trade data before detailed design.*

package/roles/aircraft-design-engineer/tests/test_aircraft_design_core.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Test aircraft_design_core: the executable engine of the aircraft
+conceptual design engineer role.
+
+Proves the role can DO its job standalone (no AeroSkills needed):
+constraint-analysis T/W rules, mission fuel-fraction models, class-I
+empty-weight fit, MTOW convergence within 0.5%, concept package
+generation, and evidence-gate checks.
+"""
+import math
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "core"))
+from aircraft_design_core import (          # noqa: E402
+    EMPTY_WEIGHT_FRACTION_BANDS, breguet_cruise_fuel_fraction,
+    breguet_loiter_fuel_fraction, build_concept, chain_mission, check_concept,
+    check_concept_markdown, check_empty_weight_fraction, climb_constraint_tw,
+    constraint_tw, cruise_constraint_tw, empty_weight_fraction,
+    example_item, example_concept_markdown, render_concept_markdown,
+    segment_fuel_fraction, size_mtow, stall_max_ws, takeoff_constraint_tw,
+    tow_estimate, weight_breakdown_ok,
+)
+
+G = 9.80665
+RHO_SL = 1.225
+
+
+class TestConstraintAnalysis(unittest.TestCase):
+    """Matching-chart rules must match the AeroSkills leaf formulas."""
+
+    def test_stall_max_ws(self):
+        # W/S = 0.5*rho*CLmax*VS^2: 0.5*1.225*2.5*60^2
+        self.assertAlmostEqual(stall_max_ws(60.0, 2.5), 0.5 * 1.225 * 2.5 * 3600.0)
+        with self.assertRaises(ValueError):
+            stall_max_ws(-1.0, 2.5)
+
+    def test_takeoff_constraint(self):
+        # T/W = 1.21*(W/S)/(rho*g*CLmax*s_TO) with clean SI inputs
+        ws, rho, cl, s_to = 4000.0, 1.225, 2.0, 1500.0
+        expected = 1.21 * ws / (rho * G * cl * s_to)
+        self.assertAlmostEqual(takeoff_constraint_tw(ws, rho, cl, s_to), expected)
+        # dispatcher agrees with the direct leaf call
+        self.assertAlmostEqual(
+            constraint_tw("takeoff", W_S=ws, rho=rho, CLmax=cl, s_TO=s_to),
+            expected)
+        with self.assertRaises(ValueError):
+            takeoff_constraint_tw(-5.0, rho, cl, s_to)
+
+    def test_climb_constraint(self):
+        # T/W = 1/LD + gamma
+        self.assertAlmostEqual(climb_constraint_tw(20.0, 0.03), 1.0 / 20.0 + 0.03)
+        # OEI second-segment on the installed basis: x n/(n-1)
+        raw = constraint_tw("climb", LD=12.0, gamma=0.024)
+        inst = constraint_tw("climb", LD=12.0, gamma=0.024, engines=2)
+        self.assertAlmostEqual(raw, 1.0 / 12.0 + 0.024)
+        self.assertAlmostEqual(inst, 2.0 * raw)
+        with self.assertRaises(ValueError):
+            constraint_tw("climb", LD=12.0, gamma=0.024, engines=1)
+
+    def test_cruise_constraint_shape(self):
+        # q*CD0/W_S + k*W_S/q is U-shaped in W/S with its minimum at
+        # W/S* = q*sqrt(CD0/k); takeoff grows with W/S, so high W/S values
+        # are takeoff-bound while very low W/S values are cruise-bound.
+        v, rho, cd0, k = 231.3, 0.3796, 0.018, 0.0419
+        q = 0.5 * rho * v * v
+        ws_opt = q * math.sqrt(cd0 / k)
+        vals = [cruise_constraint_tw(w, v, rho, cd0, k)
+                for w in (ws_opt * 0.7, ws_opt, ws_opt * 1.3)]
+        self.assertLess(vals[1], vals[0])
+        self.assertLess(vals[1], vals[2])
+        with self.assertRaises(ValueError):
+            cruise_constraint_tw(-1.0, v, rho, cd0, k)
+        with self.assertRaises(ValueError):
+            constraint_tw("bogus", W_S=4000.0)
+
+    def test_design_point_on_feasible_boundary(self):
+        item = example_item()
+        model = build_concept(item)
+        dp = model["design_point"]
+        # chosen W/S below the stall limit and inside the feasible region
+        self.assertLessEqual(dp["ws_nm2"], dp["ws_stall_max_nm2"])
+        self.assertTrue(dp["feasible"])
+        # required T/W equals the max over the constraint curves at that W/S
+        max_curve = max(dp["curves"][name]["tw_at_design"]
+                        for name in dp["curves"])
+        self.assertAlmostEqual(dp["tw_required"], max_curve, places=6)
+        self.assertIn(dp["binding_constraint"], dp["curves"])
+        # the example has a real, defensible regional-jet design point
+        self.assertGreater(dp["tw_required"], 0.10)
+        self.assertLess(dp["tw_required"], 0.35)
+
+
+class TestMissionFuelFractions(unittest.TestCase):
+    """Segment fuel models must match the sizing-mission-profile leaf."""
+
+    def test_breguet_cruise_fraction_matches_doc_case(self):
+        # AeroSkills worked example: 3000 nm, V 450 kt, TSFC 0.6, L/D 18,
+        # W0 150000 lb burns 69088.9 lb on the cruise leg -> fraction 0.46059
+        frac = breguet_cruise_fuel_fraction(3000.0, 450.0, 0.6, 18.0)
+        self.assertAlmostEqual(frac * 150000.0, 69088.9, delta=1.0)
+
+    def test_loiter_endurance_fraction(self):
+        # hold 0.75 hr at TSFC 0.5, L/D 15: 1 - exp(-0.75*0.5/15)
+        frac = breguet_loiter_fuel_fraction(0.75, 0.5, 15.0)
+        self.assertAlmostEqual(frac, 1.0 - math.exp(-0.75 * 0.5 / 15.0))
+
+    def test_segment_fuel_fraction_dispatch(self):
+        # absolute-flow segments scale with the start weight (W0-dependent)
+        f1 = segment_fuel_fraction("taxi", {"fuel_flow": 1200.0, "time": 0.25},
+                                   120000.0)
+        self.assertAlmostEqual(f1, 300.0 / 120000.0)
+        # climb fraction model returns the fraction directly
+        self.assertAlmostEqual(
+            segment_fuel_fraction("climb", {"fraction": 0.01}, 120000.0), 0.01)
+        # cruise dispatches to Breguet range
+        fc = segment_fuel_fraction("cruise", {"R_nm": 1500.0, "V_kt": 450.0,
+                                              "TSFC": 0.6, "LD": 18.0},
+                                   120000.0)
+        self.assertAlmostEqual(fc, 1.0 - math.exp(-1500.0 / (450.0 * 0.6 * 18.0)))
+        with self.assertRaises(ValueError):
+            segment_fuel_fraction("weird", {}, 120000.0)
+
+    def test_mission_chains_weights_and_balances_fractions(self):
+        item = example_item()
+        mission = chain_mission(item, 150000.0)
+        # weight chains: block fuel < start weight, landing weight positive
+        self.assertGreater(mission["block_fuel_lb"], 0.0)
+        self.assertGreater(mission["landing_weight_lb"], 0.0)
+        # required fuel = block + reserve; reserve = hold + 5% of trip
+        self.assertAlmostEqual(mission["required_fuel_lb"],
+                               mission["block_fuel_lb"] + mission["reserve_fuel_lb"])
+        # per-segment fractions of MTOW sum to the block-fuel fraction
+        total_frac = sum(s["fraction_of_mtow"] for s in mission["segments"])
+        self.assertAlmostEqual(total_frac,
+                               mission["block_fuel_lb"] / 150000.0)
+        # segment types in the expected order
+        types = [s["type"] for s in mission["segments"]]
+        self.assertEqual(types, ["taxi", "takeoff", "climb", "cruise", "descent"])
+
+
+class TestEmptyFractionAndTow(unittest.TestCase):
+    """Class-I empty-weight fit and the tow-estimation leaf parity."""
+
+    def test_empty_weight_fraction_band_and_fit(self):
+        self.assertEqual(EMPTY_WEIGHT_FRACTION_BANDS["transport"], (0.42, 0.55))
+        # representative fraction is the transport band midpoint
+        self.assertAlmostEqual(empty_weight_fraction("transport"), 0.485)
+        with self.assertRaises(ValueError):
+            empty_weight_fraction("airship")
+
+    def test_empty_fraction_in_band_check(self):
+        in_band, band, frac = check_empty_weight_fraction(58300.0, 120000.0,
+                                                          "transport")
+        self.assertTrue(in_band)
+        self.assertEqual(band, (0.42, 0.55))
+        self.assertAlmostEqual(frac, 58300.0 / 120000.0)
+        # out-of-band case fails
+        in_band2, _, _ = check_empty_weight_fraction(80000.0, 120000.0, "transport")
+        self.assertFalse(in_band2)
+
+    def test_tow_estimate_leaf(self):
+        # W0 = payload/(1 - empty - fuel)
+        self.assertAlmostEqual(tow_estimate(20000.0, 0.485, 0.35),
+                               20000.0 / (1.0 - 0.485 - 0.35))
+        with self.assertRaises(ValueError):
+            tow_estimate(20000.0, 0.6, 0.5)  # fractions reach 1.0
+
+    def test_weight_breakdown_balances(self):
+        self.assertTrue(weight_breakdown_ok(58000.0, 42000.0, 20000.0, 120000.0))
+        self.assertFalse(weight_breakdown_ok(60000.0, 42000.0, 20000.0, 120000.0))
+
+
+class TestMTOWConvergence(unittest.TestCase):
+    """The sizing loop must genuinely iterate and converge within 0.5%."""
+
+    def test_mtow_converges_within_tolerance(self):
+        item = example_item()
+        sizing = size_mtow(item)
+        self.assertTrue(sizing["converged"])
+        self.assertEqual(sizing["tolerance"], 0.005)
+        self.assertGreaterEqual(len(sizing["iterations"]), 2)
+        # final successive estimates within the 0.5% band
+        last = sizing["iterations"][-1]
+        self.assertLess(last["rel_change"], 0.005)
+        # MTOW dominates payload and matches a 100-pax regional jet class
+        self.assertGreater(sizing["mtow_lb"], 3.0 * sizing["payload_lb"])
+        self.assertGreater(sizing["mtow_lb"], 90000.0)
+        self.assertLess(sizing["mtow_lb"], 160000.0)
+
+    def test_fuel_fraction_is_weight_dependent(self):
+        # fixed-fuel segments make the fuel fraction fall as W0 grows
+        f_small = chain_mission(example_item(), 80000.0)["fuel_fraction"]
+        f_large = chain_mission(example_item(), 160000.0)["fuel_fraction"]
+        self.assertLess(f_large, f_small)
+
+    def test_breakdown_balances_at_convergence(self):
+        sizing = size_mtow(example_item())
+        self.assertTrue(weight_breakdown_ok(
+            sizing["empty_weight_lb"], sizing["required_fuel_lb"],
+            sizing["payload_lb"], sizing["mtow_lb"], tol=0.01))
+
+    def test_converges_from_a_different_guess(self):
+        item = example_item()
+        item.initial_guess_lb = 250000.0
+        sizing = size_mtow(item)
+        self.assertTrue(sizing["converged"])
+        # converges to the same fixed point regardless of the start guess
+        base = size_mtow(example_item())["mtow_lb"]
+        self.assertAlmostEqual(sizing["mtow_lb"], base, delta=base * 0.005)
+
+
+class TestConceptPackageAndGates(unittest.TestCase):
+
+    def test_build_concept_model_complete(self):
+        model = build_concept(example_item())
+        for key in ("document_type", "status", "item", "requirement",
+                    "design_point", "mission", "sizing", "engine",
+                    "mass_statement"):
+            self.assertIn(key, model)
+        ms = model["mass_statement"]
+        self.assertEqual(model["status"], "draft-for-review")
+        self.assertTrue(model["sizing"]["empty_in_band"])
+        # mass statement carries the three rows and a total
+        self.assertEqual(len(ms["rows"]), 3)
+        self.assertAlmostEqual(ms["total_lb"], model["sizing"]["mtow_lb"])
+        # engine check: 2 engines, positive thrust, top-of-climb margin >= 1
+        self.assertEqual(model["engine"]["n_engines"], 2)
+        self.assertGreater(model["engine"]["toc_margin"], 1.0)
+        self.assertTrue(model["engine"]["toc_ok"])
+
+    def test_core_gates_all_pass(self):
+        model = build_concept(example_item())
+        gates = check_concept(model)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_markdown_gates_all_pass_and_no_blanks(self):
+        md = example_concept_markdown()
+        self.assertGreater(len(md), 3000)
+        self.assertNotIn("___", md)
+        gates = check_concept_markdown(md)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_render_contains_key_numbers(self):
+        md = example_concept_markdown()
+        model = build_concept(example_item())
+        s = model["sizing"]
+        dp = model["design_point"]
+        # converged MTOW, W/S-T/W point, and the mass statement are present
+        self.assertIn(f"{s['mtow_lb']:,.0f}", md)
+        self.assertIn(f"{dp['ws_nm2']:,.0f} N/m^2", md)
+        self.assertIn(f"{dp['tw_required']:.4f}", md)
+        self.assertIn("CONVERGED", md.upper())
+        self.assertIn("not an approval", md.lower())
+
+    def test_standalone_no_skills_repo(self):
+        # Core must work with no AeroSkills present and no local paths.
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = build_concept(example_item())
+        md = render_concept_markdown(model)
+        self.assertTrue(model["sizing"]["converged"])
+        self.assertGreater(len(md), 3000)
+        gates = check_concept(model)
+        self.assertTrue(gates["all_pass"], gates)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/aircraft-design-engineer/tests/test_role_aircraft_design_engineer.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Role test: aircraft-design-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", "aircraft-design-engineer")
+TEMPLATE = os.path.join(ROLE_DIR, "templates", "concept-design-template.md")
+
+EXPECTED_BOUND = [
+    "vehicle-design/conceptual/constraint-analysis",
+    "vehicle-design/conceptual/sizing-mission-profile",
+    "vehicle-design/conceptual/payload-range-diagram",
+    "vehicle-design/conceptual/tow-estimation",
+    "vehicle-design/conceptual/openvsp-geometry",
+    "vehicle-design/sizing/ws-tw-trade",
+    "vehicle-design/sizing/weight-estimation",
+    "vehicle-design/sizing/engine-sizing",
+    "vehicle-design/sizing/fuselage-sizing",
+    "vehicle-design/sizing/wing-planform-sizing",
+    "vehicle-design/sizing/tail-sizing",
+    "vehicle-design/sizing/landing-gear-sizing",
+    "vehicle-design/sizing/control-surface-sizing",
+    "vehicle-design/sizing/fuel-tank-sizing",
+    "vehicle-design/sizing/battery-sizing",
+    "vehicle-design/sizing/environmental-control-sizing",
+    "vehicle-design/sizing/electrical-wire-sizing",
+    "vehicle-design/sizing/apu-fuel-burn-sizing",
+    "vehicle-design/sizing/bleed-air-system-sizing",
+    "vehicle-design/sizing/fire-protection-sizing",
+    "vehicle-design/sizing/ice-protection-sizing",
+    "vehicle-design/sizing/hydraulic-system-sizing",
+    "vehicle-design/sizing/landing-gear-retraction-sizing",
+    "vehicle-design/mass-properties/mass-budget",
+    "vehicle-design/mass-properties/cg-envelope",
+    "vehicle-design/mass-properties/inertia-estimation",
+    "vehicle-design/mdo/design-of-experiments",
+    "vehicle-design/mdo/multidisciplinary-optimization",
+    "vehicle-design/mdo/surrogate-modeling",
+    "vehicle-design/cost-estimation/parametric-cost",
+    "vehicle-design/cost-estimation/operating-cost",
+    "vehicle-design/cost-estimation/life-cycle-cost",
+    "vehicle-design/structures-integration/wing-box-sizing",
+    "vehicle-design/structures-integration/fuselage-skin-stringer"
+]
+
+STAGES = [
+    "1. Requirements framing",
+          "2. Sizing mission",
+          "3. Initial layout",
+          "4. W/S vs T/W trade",
+          "5. Weight iteration",
+          "6. Component sizing",
+          "7. Subsystem sizing",
+          "8. Mass + CG",
+          "9. MDO exploration",
+          "10. Payload-range",
+          "11. Cost",
+          "12. Structures check",
+          "13. Package"
+]
+
+
+def role_text():
+    p = os.path.join(ROLE_DIR, "ROLE.md")
+    return open(p).read() if os.path.exists(p) else None
+
+
+class TestAircraftDesignEngineerRole(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_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/airworthiness-compliance-engineer/ROLE.md

@@ -0,0 +1,122 @@
+---
+type: role
+name: airworthiness-compliance-engineer
+title: "Airworthiness Compliance Engineer"
+status: draft
+domain: systems-engineering-safety
+deliverable_type: "compliance checklist / certification matrix"
+standards_bound:
+  - id: far-25
+    tier: TIER-1
+    reference-only: false
+  - id: cs-25
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - avionics/far-cs25/airworthiness
+  - avionics/far-cs25/special-conditions
+  - systems-engineering-safety/certification/certification-basis
+  - systems-engineering-safety/certification/equivalent-level-of-safety
+  - systems-engineering-safety/certification/means-of-compliance
+  - systems-engineering-safety/certification/mmel-development
+  - systems-engineering-safety/continued-airworthiness/airworthiness-directive-compliance
+  - systems-engineering-safety/continued-airworthiness/type-certificate-data-sheet
+  - systems-engineering-safety/continued-airworthiness/in-service-safety-assessment
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "declare a compliance finding"
+  - "claim certification approval"
+  - "assert applicability without the certification basis"
+sign_off_required: true
+license: Apache-2.0
+compatibility: "agentskills.io ROLE.md; any SKILL.md host"
+metadata:
+  version: 0.1.0
+  author: Aero Agent Roles
+  skills_release: "v1.3.0+"
+---
+
+# Airworthiness Compliance Engineer
+
+## Role identity
+
+Drives the certification compliance workflow: determine the applicable
+certification basis (FAR/CS), select means of compliance per regulation,
+map each regulation to the compliance document and status, and produce
+the compliance checklist (the certification matrix). Use when a project
+needs to show how it will comply with airworthiness regulations. Do NOT
+use for design engineering, or when no cert basis exists.
+
+## Deliverable contract
+
+1. **Compliance checklist / certification matrix** — per regulation:
+   applicability determination, selected means of compliance, the
+   associated compliance document(s), status of the finding, responsible
+   owner. Original skeleton per templates/compliance-matrix-template.md.
+2. **Certification basis summary** — the regs + special conditions +
+   equivalent level of safety findings that apply.
+3. **Gap report** — open items for the human compliance engineer.
+
+## Workflow (stages → bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Certification basis | certification/certification-basis | regs that apply, TC/STC context |
+| 2. Special conditions | far-cs25/special-conditions | special conditions list |
+| 3. ELOS | certification/equivalent-level-of-safety | ELOS findings |
+| 4. Means of compliance | certification/means-of-compliance | MoC per reg |
+| 5. Airworthiness mapping | far-cs25/airworthiness | reg → MoC → document map |
+| 6. MMEL | certification/mmel-development | MMEL applicability |
+| 7. Continued airworthiness | continued-airworthiness/airworthiness-directive-compliance + type-certificate-data-sheet + in-service-safety-assessment | AD/TCDS/in-service inputs |
+| 8. Compliance matrix | (all above) | the deliverable |
+
+## Evidence gates
+
+- Stage 1 done = certification basis list cites the actual reg text
+  (FAR/CS are TIER-1 public-domain — quotable with citation).
+- Stage 5 done = every applicable reg has a chosen MoC + document.
+- FINAL = matrix complete; statuses are PROPOSED (not found); nothing
+  marked "compliant" without evidence.
+
+## Boundary / forbidden
+
+- NEVER declare a compliance finding — the authority/designee does.
+- NEVER claim approval.
+- FAR/CS are public domain — quote with citation, but keep paraphrase
+  preferred per standards-map.
+
+## Verification
+
+The role runs STANDALONE: `core/airworthiness_core.py` is an executable
+engine that determines regulation applicability (aircraft type + change
+scope), selects the means of compliance per regulation (real MOC
+vocabulary: analysis, test, inspection, safety assessment, similarity),
+computes severity/DAL context, BUILDS the compliance matrix, and
+gate-checks deliverables. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out matrix.md                    # example item (FAR-25 STC)
+python3 cli.py build --out matrix-cs.md --jurisdiction EASA   # CS-25 basis variant
+python3 cli.py check --file matrix.md                   # gate-check a matrix
+```
+
+Tests:
+- tests/test_airworthiness_core.py (20 tests): domain rules (severity →
+  DAL, 25.1309 safety assessment applicability, MOC suitability),
+  applicability logic (transport vs other categories, change-scope
+  screening), MOC selection (FAR-25 vocabulary + CS-25 MOC scheme),
+  matrix builder completeness (real regs, no blank fields), gates
+  pass/fail, and standalone (AEROSKILLS_DEV=/nonexistent).
+- tests/test_role_airworthiness.py: bound-skill resolution (skips if the
+  skills repo is absent) + workflow + template present + boundaries.
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (certification basis, means of compliance, ELOS,
+airworthiness mapping); the core engine does not depend on them.
+
+## Compliance
+
+- far-25 / cs-25 TIER-1 (public-domain regulations); standards-map gated:
+  false — quotable with citation.
+- SOURCES.md records acquisition/extraction/verification status.

package/roles/airworthiness-compliance-engineer/SOURCES.md

@@ -0,0 +1,16 @@
+# SOURCES.md - Airworthiness Compliance 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 21 | certification procedures (TC/STC/TSO) | false |
+| 14 CFR Part 25 | airworthiness standards for transport category | false |
+| EASA CS-25 | EASA certification specifications | false |
+| EASA Part 21 (Easy Access Rules) | EASA certification procedures | false |
+| SAE ARP4754A | development assurance context (shared) | true |
+
+FAR and CS are public-domain regulations, quotable with citation. The
+compliance matrix template in `templates/` is an original structure; rows
+map regulation to means of compliance to evidence document.