aero-agent-roles 1.0.0

package/roles/space-systems-engineer/templates/space-systems-template.md

@@ -0,0 +1,88 @@
+# Spacecraft Mission and Subsystem Design Report
+
+**Spacecraft:** Aurora-1 Earth Observation Microsatellite
+**Mission:** 600 km circular sun-synchronous Earth observation microsatellite, 5-year design life, 10:30 LTDN.
+**Status:** draft-for-review
+
+## 1. Mission and orbit
+
+- Orbit: circular, altitude 600.0 km, inclination 97.8 deg (sun-synchronous), e = 0.000.
+- Orbit radius: 6978 km; period 96.7 min (5801 s); 14.9 orbits/day; circular velocity 7558 m/s.
+- Launch: rideshare, direct injection; design life 5 years.
+
+## 2. Transfer / maneuvers and delta-v budget
+
+- Injection: direct insertion (rideshare, direct injection); no interplanetary C3 or launch-window constraint applies (LEO circular mission).
+- Delta-v contributions (m/s):
+  - Injection dispersion correction: 20.0
+  - Orbit maintenance (drag, 5 yr): 15.0
+  - Collision avoidance (2 maneuvers): 10.0
+  - End-of-life disposal (perigee lowering): 141.7
+- Disposal leg is a single retrograde burn lowering perigee from 600 km to 100 km (Hohmann half-transfer, 141.7 m/s).
+- Nominal total delta-v: 186.7 m/s; budgeted with 15% margin: **214.8 m/s**.
+- Propellant (Isp 220 s, Tsiolkovsky): **15.7 kg**; wet mass 165.7 kg (9.5% propellant fraction).
+
+## 3. Environment
+
+- Eclipse (worst case, beta = 0): shadow fraction 36.7%; eclipse time 35.5 min per orbit.
+- Perturbations at 600 km SSO: J2 nodal precession used for the sun-synchronous plane; drag is the long-term orbit maintenance driver (budgeted above); three-body effects negligible at this altitude.
+- Radiation/debris: 600 km SSO sits in the inner belt proton/electron environment; parts list to a 25-50 krad(Si) total dose class (ECSS-Q-ST-60-15C practice); conjunction screening budgeted as 2 avoidance maneuvers over life.
+
+## 4. ADCS
+
+- Determination: star tracker (knowledge ~5 arcsec 1-sigma), sun sensors, 3-axis rate gyro, magnetometer; TRIAD/QUEST batch solutions on the C&DH.
+- Control: 3 orthogonal wheels + 1 redundant reaction wheels, momentum capacity **1.0 N m s** each at 6000 rpm (wheel inertia 1.59 x 1e-3 kg m^2, h = J*omega); torque class 0.02 N m; magnetorquers for momentum desaturation.
+- Sizing: slew 90 deg in 90 s -> slew momentum 0.349 N m s (J = 20 kg m^2 x omega 17.5 x 1e-3 rad/s); disturbance accumulation 0.0348 N m s/orbit; required with margin 0.58 N m s < capacity 1.0 N m s.
+- Pointing error budget (3-sigma RSS): **0.048 deg** vs requirement 0.1 deg (margin x 2.1, meets).
+  - attitude determination (star tracker): 0.020 deg
+  - control error (deadband + PD residual): 0.030 deg
+  - wheel-induced jitter: 0.020 deg
+  - sensor/actuator alignment: 0.020 deg
+  - thermal distortion: 0.015 deg
+
+## 5. Power and thermal
+
+| Item | Day power (W) | Eclipse power (W) |
+|---|---|---|
+| Payload (optical imager) | 60 | 0 |
+| Avionics / C&DH | 30 | 30 |
+| ADCS | 15 | 15 |
+| Comms (S-band Rx + X-band Tx duty) | 20 | 10 |
+| Thermal (heater duty) | 15 | 25 |
+| **Total** | **140** | **80** |
+
+- Orbit-average load: 118.0 W over a 96.7 min orbit (36.7% eclipse).
+- Battery: 80 W x 35.5 min eclipse at 30% DoD / 90% efficiency requires **175.2 Wh**; sized **215 Wh** Li-ion (margin 23%).
+- Solar array: daylight power 248.5 W; EOL specific power 315.1 W/m^2 (AM0 1367 W/m^2, 30% cells, packing 0.85, 2%/yr x 5 yr) -> array area **0.79 m^2**.
+- Thermal balance: 55 W continuous dissipation rejected by a radiator at 20 deg C (eps 0.90) -> **0.15 m^2**; eclipse heater duty 25 W is in the load table.
+
+## 6. Comms
+
+- Slant range at 5 deg elevation: 2329 km.
+- Downlink (X-band 8.2 GHz, 150 Mbps): EIRP 31.0 dBW, path loss 178.1 dB, C/N0 98.8 dB-Hz, Eb/N0 17.0 dB vs 10.5 dB required -> **margin 6.5 dB**.
+- Uplink (S-band 2.1 GHz, 4 kbps command): **margin 34.3 dB**.
+- Data: 11.2 GB per 10 min pass x 6 passes/day = **67.5 GB/day** capacity vs 30 GB/day imaging need (margin x 2.2); on-board storage 256 GB.
+
+## 7. Propulsion and C&DH
+
+- Propulsion: 15.7 kg hydrazine (Isp 220 s) at 1008 kg/m^3 -> 15.6 L propellant, 16.6 L spherical Ti tank (radius 15.8 cm, wall 0.33 mm, shell 0.51 kg, pressurant 3.9 g He); 4 x 1 N thrusters.
+- C&DH: single rad-tolerant computer (LEON-class) with watchdog + triple-redundant command path; ECSS-E-ST-40 / ECSS-Q-ST-80 software and product assurance context; on-board storage solid-state recorder with EDAC.
+
+## 8. System budgets
+
+| Budget | Value | Margin policy | Closes |
+|---|---|---|---|
+| mass (dry) | 150 kg (subsystems sum to stated 150 kg) | 20% at subsystem level in stated rows | YES |
+| mass (wet) | 165.7 kg | propellant on top of dry budget | YES |
+| power | 140 W day / 80 W eclipse | battery 23%, array 20% | YES |
+| delta-v | 186.7 m/s nominal / 214.8 m/s budgeted | 15% | YES |
+| pointing | 0.048 deg (3-sigma) | vs 0.1 deg requirement | YES |
+| link margin | down 6.5 dB / up 34.3 dB | >= 3 dB | YES |
+
+## 9. Conclusions and open items
+
+- Budgets close? **YES - all budgets close** (delta-v True, power True, pointing True, link True, mass True).
+- Open items for detailed phase: refined disturbance torque model with beta-angle profile; flight-like array incidence/cosine losses; thermal model with component-level margins; star tracker alignment campaign; launch-vehicle interface agreement and actual dispersion.
+
+---
+*Generated by Aero Agent Roles space-systems-engineer core (2026-09-05). DRAFT for human space systems lead review. Not launch readiness. Not an approval document.*

package/roles/space-systems-engineer/tests/test_role_space_systems_engineer.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Role test: space-systems-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", "space-systems-engineer")
+TEMPLATE = os.path.join(ROLE_DIR, "templates", "space-systems-template.md")
+
+EXPECTED_BOUND = [
+    "space-systems/mission-design/mission-delta-v-budget",
+    "space-systems/mission-design/launch-window-analysis",
+    "space-systems/mission-design/c3-departure-energy",
+    "space-systems/mission-design/entry-descent-landing",
+    "space-systems/mission-design/radiation-debris",
+    "space-systems/orbit-mechanics/keplerian-elements",
+    "space-systems/orbit-mechanics/kepler-orbit-propagation",
+    "space-systems/orbit-mechanics/hohmann-transfer",
+    "space-systems/orbit-mechanics/bi-elliptic-transfer",
+    "space-systems/orbit-mechanics/plane-change-maneuver",
+    "space-systems/orbit-mechanics/lambert-transfer",
+    "space-systems/orbit-mechanics/gravity-assist-swingby",
+    "space-systems/orbit-mechanics/low-thrust-spiral",
+    "space-systems/orbit-mechanics/orbital-perturbations",
+    "space-systems/orbit-mechanics/sun-synchronous-inclination",
+    "space-systems/orbit-mechanics/ground-track-repeat",
+    "space-systems/orbit-mechanics/eclipse-time",
+    "space-systems/orbit-mechanics/satellite-coverage",
+    "space-systems/orbit-mechanics/walker-delta-constellation",
+    "space-systems/orbit-mechanics/geostationary-station-keeping",
+    "space-systems/orbit-mechanics/conjunction-assessment",
+    "space-systems/orbit-mechanics/three-body-libration",
+    "space-systems/orbit-mechanics/orbital-decay",
+    "space-systems/orbit-mechanics/clohessy-wiltshire",
+    "space-systems/adcs/attitude-determination-triad",
+    "space-systems/adcs/attitude-determination-quest",
+    "space-systems/adcs/star-tracker",
+    "space-systems/adcs/sun-pointing",
+    "space-systems/adcs/reaction-wheel-control",
+    "space-systems/adcs/control-moment-gyro",
+    "space-systems/adcs/magnetorquer-control",
+    "space-systems/adcs/attitude-control-sizing",
+    "space-systems/adcs/pointing-error-budget",
+    "space-systems/adcs/gyro-allan-variance",
+    "space-systems/subsystems/communication-link-budget",
+    "space-systems/subsystems/antenna-aperture-sizing",
+    "space-systems/subsystems/power-thermal-budget",
+    "space-systems/subsystems/solar-array-sizing",
+    "space-systems/subsystems/spacecraft-battery-sizing",
+    "space-systems/subsystems/thermal-design",
+    "space-systems/subsystems/propellant-tank-sizing",
+    "space-systems/subsystems/command-data-handling",
+    "space-systems/ecss/systems-engineering",
+    "space-systems/ecss/software-engineering",
+    "space-systems/ecss/software-verification"
+]
+
+STAGES = [
+    "1. Mission delta-v",
+          "2. Transfers",
+          "3. Launch window",
+          "4. Constellation/coverage",
+          "5. Environment",
+          "6. Rendezvous",
+          "7. ADCS determination",
+          "8. ADCS control",
+          "9. Power/thermal",
+          "10. Comms",
+          "11. Propulsion/C&DH",
+          "12. ECSS context",
+          "13. Report"
+]
+
+
+def role_text():
+    p = os.path.join(ROLE_DIR, "ROLE.md")
+    return open(p).read() if os.path.exists(p) else None
+
+
+class TestSpaceSystemsEngineerRole(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/space-systems-engineer/tests/test_space_systems_engineer_core.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Test space_systems_core: the executable engine of the Space Systems role.
+
+Proves the role can DO its job standalone (no AeroSkills needed): orbit
+mechanics, delta-v budgeting and propellant sizing, reaction wheel
+sizing, power/thermal closure, comms link budget, report generation,
+and evidence-gate checks. Anchor values come from the bound AeroSkills
+space-systems leaves (hohmann-transfer, mission-delta-v-budget,
+power-thermal-budget, solar-array-sizing, eclipse-time,
+reaction-wheel-control, communication-link-budget).
+"""
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "core"))
+from space_systems_core import (          # noqa: E402
+    MU_EARTH, RE_EARTH, apply_margin,
+    battery_capacity_required, build_report, check_report,
+    check_report_markdown, circular_velocity, comms_link_budget,
+    eclipse_geometry, eol_specific_power, example_mission,
+    example_report_markdown, free_space_path_loss, hohmann_burn_delta_v,
+    mission_delta_v_budget, orbit_period_seconds, perigee_lowering_delta_v,
+    pointing_error_budget, power_and_thermal, propellant_mass,
+    radiator_area, reaction_wheel_sizing, render_report_markdown,
+    slant_range_m, solar_array_daylight_power, sum_delta_v, wet_mass,
+)
+
+
+class TestOrbitMechanics(unittest.TestCase):
+    """Domain rules: vis-viva, periods, Hohmann and disposal burns."""
+
+    def test_circular_velocity_anchors(self):
+        # hohmann-transfer leaf anchors: LEO 6878 km -> ~7613 m/s,
+        # GEO 42164 km -> ~3075 m/s.
+        self.assertAlmostEqual(circular_velocity(6878e3), 7612.7, delta=1.0)
+        self.assertAlmostEqual(circular_velocity(42164e3), 3074.7, delta=1.0)
+
+    def test_geostationary_period(self):
+        self.assertAlmostEqual(orbit_period_seconds(42164e3) / 3600.0,
+                               23.934, delta=0.05)
+
+    def test_hohmann_leo_to_geo_total(self):
+        # Leaf reference: LEO(Re+500 km) -> GEO totals about 3816 m/s.
+        dv = hohmann_burn_delta_v(RE_EARTH + 500e3, 42164e3)
+        self.assertAlmostEqual(dv["total_m_s"], 3816.0, delta=60.0)
+        self.assertEqual(dv["total_m_s"],
+                         dv["dv1_m_s"] + dv["dv2_m_s"])
+
+    def test_disposal_burn_positive_and_bounded(self):
+        dv = perigee_lowering_delta_v(600.0, 100.0)
+        v_circ = circular_velocity(RE_EARTH + 600e3)
+        self.assertGreater(dv, 0.0)
+        self.assertLess(dv, v_circ)
+        # 600 km -> 100 km perigee is a ~140 m/s class burn.
+        self.assertAlmostEqual(dv, 141.7, delta=3.0)
+
+
+class TestDeltaVAndPropellant(unittest.TestCase):
+    """Domain rules: rocket equation, margins (mission-delta-v-budget)."""
+
+    def test_propellant_mass_anchor(self):
+        # Leaf anchor: dv 2941.995 m/s, 1000 kg dry, 300 s -> ~1718.28 kg.
+        self.assertAlmostEqual(propellant_mass(2941.995, 1000.0, 300.0),
+                               1718.28, delta=0.5)
+        self.assertAlmostEqual(wet_mass(2941.995, 1000.0, 300.0),
+                               2718.28, delta=0.5)
+
+    def test_zero_dv_zero_propellant(self):
+        self.assertEqual(propellant_mass(0.0, 1000.0, 300.0), 0.0)
+
+    def test_sum_and_margin(self):
+        self.assertEqual(sum_delta_v([100.0, 200.0, 50.0]), 350.0)
+        self.assertAlmostEqual(apply_margin(350.0, 0.15), 402.5, places=6)
+        self.assertEqual(apply_margin(350.0, 0.0), 350.0)
+
+    def test_example_budget_structure(self):
+        budget = mission_delta_v_budget(example_mission())
+        self.assertAlmostEqual(
+            budget["nominal_dv_m_s"],
+            sum(budget["contributions"].values()), places=6)
+        self.assertAlmostEqual(budget["budgeted_dv_m_s"],
+                               budget["nominal_dv_m_s"] * 1.15, places=6)
+        self.assertGreater(budget["propellant_mass_kg"], 0.0)
+        self.assertLess(budget["propellant_fraction"], 0.2)
+        # disposal dominates a 600 km mission budget (realism marker)
+        self.assertGreater(
+            budget["contributions"]["End-of-life disposal (perigee lowering)"],
+            budget["contributions"]["Injection dispersion correction"])
+
+
+class TestEclipseAndPower(unittest.TestCase):
+    """Domain rules: eclipse geometry, battery and solar array sizing."""
+
+    def test_eclipse_geometry_600km(self):
+        g = eclipse_geometry(600.0)
+        self.assertAlmostEqual(g["period_s"], 5801.0, delta=20.0)
+        self.assertAlmostEqual(g["shadow_fraction"], 0.367, delta=0.005)
+        self.assertAlmostEqual(g["eclipse_time_min"], 35.5, delta=0.4)
+        self.assertAlmostEqual(g["daylight_fraction"],
+                               1.0 - g["shadow_fraction"], places=9)
+
+    def test_battery_capacity_required(self):
+        # 80 W over a 35.5 min eclipse at 30% DoD / 90% efficiency.
+        wh = battery_capacity_required(80.0, 35.5, 0.30, 0.90)
+        self.assertAlmostEqual(wh, 175.3, delta=0.2)
+
+    def test_solar_array_daylight_power_anchor(self):
+        # power-thermal-budget leaf anchor: 500 W, f=0.35, no margin.
+        self.assertAlmostEqual(solar_array_daylight_power(500.0, 0.35, 1.0),
+                               769.23, delta=0.5)
+        self.assertAlmostEqual(solar_array_daylight_power(500.0, 0.35, 1.0, 0.20),
+                               923.08, delta=0.5)
+
+    def test_eol_specific_power_anchor(self):
+        # solar-array-sizing leaf anchor: 1367*0.30*0.85*0.98^10.
+        self.assertAlmostEqual(eol_specific_power(1367.0, 0.30, 0.85, 0.02, 10),
+                               284.82, delta=0.05)
+
+    def test_radiator_area(self):
+        # 55 W at 293.15 K, eps 0.9 -> ~0.15 m^2.
+        self.assertAlmostEqual(radiator_area(55.0, 293.15, 3.0, 0.90),
+                               0.146, delta=0.01)
+
+    def test_example_power_closes(self):
+        pw = power_and_thermal(example_mission())
+        self.assertGreaterEqual(pw["battery_margin"], 0.20)
+        self.assertAlmostEqual(pw["array_area_m2"], 0.79, delta=0.03)
+        self.assertAlmostEqual(pw["battery_sized_wh"], 215.0, delta=1.0)
+
+
+class TestAdcs(unittest.TestCase):
+    """Domain rules: wheel sizing h = J*omega and pointing RSS."""
+
+    def test_slew_momentum_is_j_times_omega(self):
+        ad = reaction_wheel_sizing(example_mission(), 5801.0)
+        omega = (3.141592653589793 / 2.0) / 90.0
+        self.assertAlmostEqual(ad["omega_slew_rad_s"], omega, places=9)
+        self.assertAlmostEqual(ad["slew_momentum_nms"], 20.0 * omega,
+                               places=4)
+
+    def test_wheel_inertia_from_momentum_capacity(self):
+        ad = reaction_wheel_sizing(example_mission(), 5801.0)
+        # h = J_w * omega_max: 1.0 N m s at 6000 rpm.
+        self.assertAlmostEqual(ad["wheel_inertia_kgm2"], 1.0 / 628.3185,
+                               delta=1e-6)
+        self.assertGreater(ad["required_momentum_nms"], 0.3)
+        self.assertLess(ad["required_momentum_nms"],
+                        ad["wheel_momentum_capacity_nms"])
+
+    def test_pointing_budget_meets(self):
+        pt = pointing_error_budget(example_mission())
+        self.assertAlmostEqual(pt["rss_deg"], 0.0482, delta=0.001)
+        self.assertTrue(pt["meets"])
+        self.assertGreater(pt["margin"], 2.0)
+
+
+class TestComms(unittest.TestCase):
+    """Domain rules: Friis path loss and link margins."""
+
+    def test_slant_range_600km_5deg(self):
+        self.assertAlmostEqual(slant_range_m(600.0, 5.0) / 1000.0,
+                               2329.0, delta=10.0)
+
+    def test_free_space_path_loss_x_band(self):
+        fsl = free_space_path_loss(2329e3, 8.2e9)
+        self.assertAlmostEqual(fsl, 178.1, delta=0.5)
+
+    def test_example_links_close(self):
+        cm = comms_link_budget(example_mission())
+        self.assertGreaterEqual(cm["downlink"]["margin_db"], 3.0)
+        self.assertGreaterEqual(cm["uplink"]["margin_db"], 3.0)
+        self.assertGreater(cm["daily_capacity_gb"],
+                           cm["imaging_data_gb_per_day"])
+
+
+class TestReportBuilderAndGates(unittest.TestCase):
+
+    def test_example_model_values(self):
+        model = build_report(example_mission())
+        self.assertEqual(model["status"], "draft-for-review")
+        self.assertEqual(model["orbit"]["altitude_km"], 600.0)
+        dv = model["delta_v"]
+        self.assertGreater(dv["nominal_dv_m_s"], 180.0)
+        self.assertAlmostEqual(dv["budgeted_dv_m_s"],
+                               dv["nominal_dv_m_s"] * 1.15, places=6)
+        self.assertGreater(dv["propellant_mass_kg"], 15.0)
+        self.assertAlmostEqual(model["adcs"]["wheel_momentum_capacity_nms"],
+                               1.0, places=3)
+        self.assertLess(model["power"]["array_area_m2"], 1.0)
+        self.assertTrue(model["pointing"]["meets"])
+        self.assertTrue(model["comms"]["downlink_meets"])
+        self.assertTrue(model["mass"]["closes"])
+        self.assertTrue(all(model["verdicts"].values()), model["verdicts"])
+
+    def test_render_has_all_sections_and_markers(self):
+        md = example_report_markdown()
+        for n in range(1, 10):
+            self.assertIn(f"## {n}.", md, f"section {n} missing")
+        low = md.lower()
+        self.assertIn("draft", low)
+        self.assertIn("not an approval", low)
+        self.assertIn("not launch readiness", low)
+        self.assertGreater(len(md), 4000)
+
+    def test_core_gates_all_pass(self):
+        model = build_report(example_mission())
+        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_gate_fails_on_approval_status(self):
+        model = build_report(example_mission())
+        model["status"] = "approved"
+        gates = check_report(model)
+        self.assertFalse(gates["sign_off_honest"])
+        self.assertFalse(gates["all_pass"])
+
+    def test_gate_fails_when_pointing_exceeds(self):
+        model = build_report(example_mission())
+        model["pointing"]["requirement_deg"] = 0.01
+        model["pointing"]["meets"] = False
+        gates = check_report(model)
+        self.assertFalse(gates["pointing_meets"])
+        self.assertFalse(gates["all_pass"])
+
+    def test_deterministic_build(self):
+        a = build_report(example_mission())
+        b = build_report(example_mission())
+        self.assertEqual(a["delta_v"]["nominal_dv_m_s"],
+                         b["delta_v"]["nominal_dv_m_s"])
+
+    def test_standalone_no_skills_repo(self):
+        # Core must work with no AeroSkills present.
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = build_report(example_mission())
+        self.assertGreater(model["delta_v"]["budgeted_dv_m_s"], 0.0)
+        md = render_report_markdown(model)
+        self.assertGreater(len(md), 4000)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/state-estimation-engineer/ROLE.md

@@ -0,0 +1,154 @@
+---
+type: role
+name: state-estimation-engineer
+title: "State Estimation Engineer"
+status: draft
+domain: gnc-autonomy
+deliverable_type: "navigation state estimator design report"
+standards_bound:
+  - id: arp4754a
+    tier: TIER-2
+    reference-only: true
+skills_bound:
+  - gnc-autonomy/estimation-filtering/alpha-beta-filter
+  - gnc-autonomy/estimation-filtering/complementary-filter
+  - gnc-autonomy/estimation-filtering/extended-kalman-filter
+  - gnc-autonomy/estimation-filtering/interacting-multiple-model-filter
+  - gnc-autonomy/estimation-filtering/particle-filter
+  - gnc-autonomy/estimation-filtering/rts-smoother
+  - gnc-autonomy/estimation-filtering/unscented-kalman-filter
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "release navigation/flight software"
+  - "authorize flight"
+  - "claim certification approval"
+  - "reproduce proprietary standard text"
+  - "assert estimator performance without a checkable noise model"
+sign_off_required: true
+license: Apache-2.0
+compatibility: "agentskills.io ROLE.md; any SKILL.md host"
+metadata:
+  version: 0.1.0
+  author: ashfordeOU
+  skills_release: "v1.3.0+"
+---
+
+# State Estimation Engineer
+
+## Role identity
+
+This role designs and analyzes navigation state estimators for aerospace
+vehicles: the estimators that fuse inertial, GNSS, attitude-reference,
+and aiding sensors into the continuous attitude, position, velocity, and
+bias states a guidance or control loop consumes. Use when a project must
+select and size an estimator (attitude observer, GNSS/INS navigation
+filter, nonlinear tracking filter), choose process/measurement noise
+models, verify observability and consistency, or design offline
+post-processing. Do NOT use for pure control design (see GNC Engineer
+role), for sensor hardware selection, or when the vehicle has no
+navigation/estimation need. Bind the gnc-autonomy/estimation-filtering
+cluster.
+
+## Deliverable contract
+
+The role produces the **Navigation State Estimator Design Report** for a
+reference item (an INS/GPS or attitude estimator), containing:
+
+1. **Architecture** — estimator class, channels (attitude complementary
+   filter; position/velocity Kalman recursion; nonlinear EKF/UKF
+   updates), sensor set, frames, sample rates, and design inputs
+   (noise model: process intensity q, measurement variance r).
+2. **Design numbers** — complementary-filter gains and drift/lag
+   anchors; discrete constant-velocity Kalman covariance/gain recursion
+   results; alpha-beta companion gains (Benedict-Bordner, Kalata);
+   EKF linearization (Jacobian, innovation, gain, corrected state);
+   NEES and particle ESS verification figures; RTS smoother covariance
+   reduction; observability determinant/rank.
+3. **Verification evidence + open items** — evidence-gate summary and
+   what the human navigation engineer must still resolve before
+   implementation.
+
+## Workflow (stages → bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Architecture + noise model | (all estimation-filtering leaves) | estimator class, channels, design inputs |
+| 2. Attitude channel | complementary-filter | gains, drift/lag anchors, innovation tolerance |
+| 3. Navigation channel | rts-smoother + interacting-multiple-model-filter | CV Kalman recursion numbers, model matrices |
+| 4. Fixed-gain companion | alpha-beta-filter | Benedict-Bordner + Kalata gains from the tracking index |
+| 5. Nonlinear updates | extended-kalman-filter + unscented-kalman-filter | linearized Jacobian, innovation, gain, corrected state, NEES |
+| 6. Fallbacks | particle-filter + interacting-multiple-model-filter | SIR ESS rule, IMM maneuvering bank |
+| 7. Offline post-processing | rts-smoother | fixed-interval smoothing covariance reduction |
+| 8. Observability | (all) | observability matrix rank/verdict, bias-observability note |
+| 9. Report | (all above) | the Navigation State Estimator Design Report |
+
+## Evidence gates
+
+- Stage 2 done = complementary-filter gains numeric + drift/lag anchors
+  present.
+- Stage 3 done = Kalman recursion produced gains and covariances over
+  the design horizon.
+- Stage 4 done = alpha-beta gains computed from the tracking index and
+  consistent with the converged Kalman gain.
+- Stage 5 done = EKF Jacobian/innovation/gain present and NEES finite.
+- Stage 8 done = observability determinant/rank computed with a verdict.
+- FINAL = every section has a number from the role core grounded in the
+  bound leaf equations or the leaf documentation; nothing asserted
+  without a checkable basis; output marked DRAFT.
+
+## Boundary / forbidden
+
+- NEVER release navigation or flight software, and NEVER authorize
+  flight — implementation and flight release are human engineering
+  decisions.
+- NEVER claim certification or regulatory approval.
+- NEVER assert estimator performance without a checkable noise model
+  (the report's noise values are inputs that trace to sensor
+  datasheets).
+- NEVER reproduce proprietary standard text (summary-not-copy).
+- Output is a DRAFT for human review — mark it draft.
+
+## Verification
+
+The role runs STANDALONE: `core/state_estimation_core.py` is an
+executable engine that computes the complementary-filter design anchors,
+runs the discrete constant-velocity Kalman recursion (same F/Q/H model
+as the bound rts-smoother and IMM leaves), the alpha-beta
+(Benedict-Bordner/Kalata) gains, the EKF linearization, NEES/ESS
+consistency metrics, the RTS smoother reduction, and the observability
+analysis, BUILDS the report, and gate-checks deliverables. No AeroSkills
+checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out report.md                      # example item
+python3 cli.py build --out report.md --bundle             # + evidence bundle
+python3 cli.py build --dt 0.5 --steps 120 --r 1.0         # variant facts
+python3 cli.py build --profile program.json               # program header
+python3 cli.py check --file report.md                     # gate-check
+```
+
+Tests:
+- tests/test_state_estimation_engineer_core.py: domain rules (gains,
+  recursion, linearization, metrics, observability) + builder + gates +
+  standalone (no skills repo)
+- tests/test_role_state_estimation_engineer.py: bound-skill resolution
+  (skips if the skills repo is absent) + workflow + template + boundaries
+- tests/test_bundle_protocol.py: build --bundle emits the evidence
+  bundle, gates all pass, dispatch cross-checks agree when AeroSkills
+  is present, standalone is honest
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (attitude filter logic, Kalman recursion,
+alpha-beta gains, EKF Jacobian, NEES, ESS); the core engine does not
+depend on them. With the library present, `--bundle` dispatches the
+bound leaf logic and records core/skill agreement (delta) in
+provenance.json — two independent implementations of the same
+equations agreeing.
+
+## Compliance
+
+- arp4754a TIER-2 reference-only per standards-map; no verbatim.
+- SOURCES.md records acquisition/extraction/verification status.
+- Estimator mathematics referenced in SOURCES.md are public-domain
+  educational texts and the bound leaf logic files.

package/roles/state-estimation-engineer/SOURCES.md

@@ -0,0 +1,27 @@
+# SOURCES.md - State Estimation Engineer
+
+Standards and references this role draws on. Summary-not-copy: see
+[STANDARDS.md](../../STANDARDS.md) for the full rule and purchase links.
+No proprietary text is reproduced anywhere in this role.
+
+| Source | Role use | Gated |
+|---|---|---|
+| SAE ARP4754A | development-assurance context for aircraft systems (reference-only; the estimator supports system functions whose assurance is managed at system level) | true |
+| gnc-autonomy/estimation-filtering leaves (AeroSkills) | the role's equations are grounded in the leaf logic files: alpha-beta-filter (Benedict-Bordner beta = alpha^2/(2-alpha); Kalata gains from tracking index lambda = sigma_w*dt^2/sigma_v), rts-smoother (CV model F = [[1, dt],[0, 1]], discretized Q; forward Kalman recursion; backward smoothing gain G_k = P_filt F^T P_pred^-1; covariance-reduction verdict), extended-kalman-filter (central-difference Jacobians; EKF predict/update recursion; bearing/range measurement model), unscented-kalman-filter (scaled unscented transform; NEES = (x-p)^T P^-1 (x-p) with expected value n), particle-filter (bootstrap/SIR; ESS = (sum w)^2 / sum(w^2); resample when ESS < n/2), complementary-filter (Mahony-style explicit complementary filter on SO(3): cross-product innovation e = m x v, corrected rate omega_c = omega_m - b + k_p*e, bias step b <- b - k_i*e*dt, RK4 quaternion kinematics + renormalization; module gain defaults k_p = 2.0 1/s, k_i = 0.4 1/s^2; trailing-window innovation-norm tolerance 1e-3 rad), interacting-multiple-model-filter (two-mode CV/CA bank, Markov mode mixing, Bayesian mode-probability refresh) | false |
+| Kalman, R. E., "A New Approach to Linear Filtering and Prediction Problems", ASME J. Basic Engineering 82 (1960) | the linear Kalman recursion the report is built on (public) | false |
+| R. G. Brown & P. Y. C. Hwang, Introduction to Random Signals and Applied Kalman Filtering (Wiley) | discrete CV/CA modeling, Q discretization, steady-state behavior (public educational text) | false |
+| Mahony, Hamel & Pflimlin, "Nonlinear Complementary Filters on the Special Orthogonal Group", IEEE Trans. Automatic Control 53(5), 2008 | explicit complementary filter / bias observability with two non-parallel reference vectors (public) | false |
+| Kalata, P. R., "The Tracking Index: A Generalized Parameter for alpha-beta and alpha-beta-gamma Target Trackers", IEEE Trans. AES 20(2), 1984 | tracking-index gain selection (public) | false |
+
+The complementary-filter gain defaults (k_p = 2.0 1/s, k_i = 0.4
+1/s^2), the steady-state innovation tolerance (1e-3 rad), the
+uncompensated-bias drift anchor |b|*t, the discrete sampling-lag bound
+|omega|*dt, the SIR ESS threshold n/2, and the NEES expected-value n
+criterion are documented module defaults and worked-example anchors of
+the bound leaf SKILL.md files - reproduced as numbers, not as text.
+Noise-model values in the report (q, r, bias vector, rates) are DESIGN
+INPUTS that trace to the item's sensor datasheets; the report labels
+them as inputs.
+
+The report template in `templates/` is an original structure produced
+by the role core for the reference item.