aero-agent-roles 1.0.0

package/roles/gnc-engineer/templates/gnc-report-template.md

@@ -0,0 +1,105 @@
+# GNC Design Report - Pitch Attitude Hold Autopilot
+
+**Vehicle:** Utility UAV (example cruise condition)
+**Condition:** Cruise, 60 m/s, altitude 3000 m, level flight
+**Mission / item:** Pitch attitude hold autopilot design
+**Status:** draft-for-review
+
+## 1. Architecture and plant
+
+- Control architecture: cascade pitch attitude hold - inner pitch rate (q) loop with PID; outer pitch attitude (theta) loop (proportional). Guidance and navigation layers analyzed in sections 2 and 6.
+- Frames: body-fixed axes (x forward, z down) for the short-period model; stability axes for the longitudinal modes; inertial NED for the guidance geometry.
+- Plant (reduced-order short-period, elevator to pitch rate, at the stated cruise condition):
+
+  G_q(s) = 4.0 / (s^2 + 6.6 s + 36.0)
+
+  with short-period natural frequency 6.0 rad/s, damping 0.55 and elevator effectiveness 4.0 1/s (example trim data; verify against the vehicle aerodynamic database).
+- States: pitch rate q (plant state; the short-period model implicitly includes angle of attack). Input: elevator deflection. Output: pitch rate q. Pitch attitude theta = q/s for the outer loop.
+- Assumptions: rigid airframe (no aeroelastic modes in this band), actuator modeled at >= 40 rad/s in the follow-up stage.
+
+## 2. Navigation
+
+- Sensor suite: rate gyro (pitch axis) and accelerometer-derived pitch measurement; scalar attitude Kalman filter at 100 Hz.
+- Noise models: process noise q = 0.0009 deg^2 per step (integrated gyro drift), measurement noise r = 1.00 deg^2 (accel-derived pitch, non-accelerated-flight assumption).
+- Filter: constant model f = 1, h = 1. Steady-state predicted covariance P = 0.0305 deg^2; steady-state gain K = 0.0296; post-update covariance P+ = 0.0296 deg^2.
+- Attitude (pitch) error budget: 1-sigma = 0.172 deg against a budget of 0.5 deg - MET.
+- Innovation monitor: 1-sigma innovation = 1.015 deg.
+- GNSS/RAIM: not part of this attitude channel; the gnss-pseudorange-positioning / gnss-raim-fde / dilution-of-precision leaves apply when a full position navigation solution is in scope.
+
+## 3. Control design
+
+Inner pitch-rate loop (PID by pole placement on the short-period plant, matched to (s^2 + 2 z_i wn_i s + wn_i^2)(s + p3_i)):
+
+| Loop | Gains | Phase margin | Gain margin | Requirement | Verdict |
+|---|---|---|---|---|---|
+| inner q (PID) | kp=156.60, ki=864.00, kd=9.75 | 76.7 deg | inf dB | PM >= 45 deg, GM >= 6 dB | PASS |
+| outer theta (P) | kp_theta=5.400 1/s | 65.5 deg | inf dB | PM >= 45 deg, GM >= 6 dB | PASS |
+
+Inner loop design: wn_i = 12.0 rad/s (>= 3x the attitude bandwidth requirement of 3.0 rad/s), zeta_i = 0.90, non-dominant pole p3_i = 24.0 rad/s. Inner open loop L(s) = C(s) G_q(s): gain crossover 40.4 rad/s, phase crossover none, phase margin 76.7 deg, gain margin inf dB (type-1 loop, phase recovers above -180 deg so the gain margin is infinite).
+
+Outer loop: the closed inner loop is reduced to the lag a/(s + a) with a = zeta_i * wn_i = 10.8 rad/s, so the outer attitude plant is a/(s(s + a)) (type-1). The proportional gain kp_theta is sized for damping zeta = 0.71 (f(z) = 1 at z = 0.707, so bandwidth = natural frequency):
+
+- Natural frequency from the bandwidth requirement: wn,req = w_bw / f(zeta) = 3.0 / 1.000 = 3.0 rad/s. The natural frequency implied by the damping target (wn = a / (2 zeta)) is 7.64 rad/s and exceeds the requirement.
+- Achieved: wn_theta = 7.64 rad/s, zeta_theta = 0.71, bandwidth w_bw = 7.64 rad/s >= 3.0 rad/s requirement (PASS), phase margin 65.5 deg >= 45 deg (PASS), gain margin inf dB >= 6 dB (PASS).
+
+## 4. Digital implementation
+
+- Sample period T = 0.010 s (100 Hz); closed-loop characteristic frequency wn_i = 12.0 rad/s.
+- Sample-rate rule (10-20 samples per closed-loop cycle): w_s,min = 10 * wn_i = 120.0 rad/s, T_max = 0.0524 s; verdict: ok (T = 0.010 s <= T_max).
+- Inner PID velocity-form coefficients at T = 0.010 s (u(k) = u(k-1) + b0 e(k) + b1 e(k-1) + b2 e(k-2)): b0 = 1140.2400, b1 = -2106.6000, b2 = 975.0000, a1 = -1.
+
+## 5. State estimation (observer)
+
+- Full-order observer (Luenberger/Ackermann) for the comparison state-feedback design; plant theta_ddot = -2 q + u (normalized elevator pitch acceleration), measured state theta (C = [1, 0]).
+- Observer poles: -30 rad/s (double) - about 10x faster than the controller poles (separation principle), settling time 4/sigma = 0.133 s.
+- Observer gain L = [58.0, 784.0].
+
+## 6. Guidance and optimal control
+
+Guidance (terminal approach example, proportional navigation comparison; relative state from the nav estimate):
+
+- Geometry: range r = 2061.6 m, line-of-sight 14.04 deg; heading error 2.58 deg; closing speed Vc = 181.90 m/s; line-of-sight rate 0.00706 rad/s.
+- Commanded lateral acceleration a_c = N * Vc * lam_dot = 4.0 * 181.9 * 0.00706 = 5.14 m/s^2 (0.52 g) with N = 4.0; pure pursuit capture possible (V_i = 182.5 m/s > V_t = 0), tail-chase intercept time ~11.3 s.
+
+Optimal control (LQR comparison on the normalized pitch-axis model x = [theta, q], x_dot = A x + B u with A = [[0,1],[0,-2]], B = [0,1], u = normalized elevator pitch acceleration):
+
+- Weights: Q = diag(10, 1) (state error), R = 0.1 (control effort).
+- Riccati solution P = [[5.831, 1.000],[1.000, 0.383]]; gain K = R^-1 B' P = [10.00, 3.83].
+- Closed loop A - B K stable: yes (poles at -2.92 +/- j1.22 rad/s, wn = 3.16 rad/s, zeta = 0.32). The LQR result is a comparison design on the same axis; the PID cascade of section 3 is the baseline.
+
+## 7. Space GNC
+
+- Not applicable for this aircraft example. The space leaves (attitude-dynamics, orbit-dynamics, orbit-determination, rendezvous-phasing) load when the vehicle is a spacecraft.
+
+## 8. Monte Carlo / robustness
+
+- Monte Carlo on the outer loop (400 draws, seed 7): lag a and gain kp_theta varied uniformly over +/- 15% (a, inner-loop uncertainty) and +/- 10% (kp_theta, implementation tolerance).
+- Result: phase margin min 60.9 deg / mean 65.4 deg / max 69.6 deg; all 400 draws >= 45 deg (PASS); zeta_theta range 0.63-0.79; minimum bandwidth 6.83 rad/s (still >= 3.0 rad/s requirement).
+- Disturbance response: the rate-loop integral gives zero steady-state attitude error to constant pitch disturbances (type-1 loop); transient response and gust loads verified in the full 6-DOF simulation (open item).
+
+## 9. Conclusions
+
+| Gate | Result |
+|---|---|
+| Inner loop margins vs requirement | PASS |
+| Outer loop margins vs requirement | PASS |
+| Attitude bandwidth >= 3.0 rad/s | PASS |
+| Nav error budget (1-sigma <= 0.5 deg) | PASS |
+| Monte Carlo robustness (PM >= 45 deg) | PASS |
+
+- Margins are design predictions from the stated reduced-order model and sensor assumptions.
+- Open items for flight test / formal verification: full 6-DOF nonlinear simulation with actuator and aeroelastic models, sensor-in-the-loop tests, gain-schedule coverage of the flight envelope, and handling-qualities evaluation per MIL-STD-1797A where applicable.
+
+## Appendix A. Calculation traceability
+
+- PID gains: pole placement matching (s^2 + 2 z wn s + wn^2)(s + p3) (pid-control-design).
+- Bandwidth/natural frequency: w_bw = f(z) wn with f(z) = sqrt(1 - 2z^2 + sqrt(2 - 4z^2 + 4z^4)); f(0.707) = 1.
+- Margins: type-1 loop L = K/(s(s + a)) closed form; general loops evaluated on jw with root-sum unwrapped phase (frequency-response-design).
+- LQR: K = R^-1 B' P, ARE closed form (lqr-design).
+- Kalman: steady-state covariance = scalar Riccati root; K = h P/(h^2 P + r) (kalman-filter-design).
+- Observer: Ackermann L = phi(A) O^-1 e_n (observer-design).
+- Guidance: a_c = N Vc lam_dot (pursuit-guidance).
+- Digital: 10-20 samples per closed-loop cycle; velocity-form discrete PID (digital-control-design).
+
+---
+*Generated by Aero Agent Roles gnc-engineer core (2026-09-05). DRAFT - for human GNC lead review. Design predictions only; not flight software release, not a certification finding, not an approval document.*

package/roles/gnc-engineer/tests/test_gnc_engineer_core.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Test gnc_core: the executable engine of the GNC Engineer role.
+
+Proves the role can DO its job standalone (no AeroSkills needed):
+PID pole placement, bandwidth/natural-frequency rules, margin
+computation, LQR Riccati solution, Kalman steady state, observer
+gains, guidance commands, digital design checks, Monte Carlo
+robustness, report generation, and evidence-gate checks. Anchor
+numbers match the bound AeroSkills leaves (pid-control-design,
+frequency-response-design, lqr-design, kalman-filter-design,
+observer-design, pursuit-guidance, digital-control-design).
+"""
+import math
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                "..", "core"))
+import gnc_core as gnc  # noqa: E402
+
+
+class TestDomainRules(unittest.TestCase):
+
+    def test_bandwidth_factor_anchors(self):
+        # f(0.7071) == 1 exactly (bandwidth = natural frequency at the
+        # classic 0.707 damping); f(0.5) = 1.27201965...
+        self.assertAlmostEqual(gnc.second_order_bandwidth_factor(
+            math.sqrt(2) / 2.0), 1.0, delta=1e-12)
+        self.assertAlmostEqual(gnc.second_order_bandwidth_factor(0.5),
+                               1.272019649514069, delta=1e-12)
+
+    def test_natural_frequency_from_bandwidth(self):
+        # at zeta = 0.707 the required wn equals the bandwidth
+        self.assertAlmostEqual(
+            gnc.natural_frequency_from_bandwidth(3.0, math.sqrt(2) / 2.0),
+            3.0, delta=1e-9)
+        # at zeta = 0.5, wn < bandwidth
+        self.assertLess(gnc.natural_frequency_from_bandwidth(3.0, 0.5), 3.0)
+
+    def test_pid_pole_placement_anchors(self):
+        # leaf anchors (pid-control-design): a=2,b=1,wn=3,zeta=0.7
+        kp, ki = gnc.pid_gains_first_order(2.0, 1.0, 3.0, 0.7)
+        self.assertAlmostEqual(kp, 2.2, delta=1e-9)
+        self.assertAlmostEqual(ki, 9.0, delta=1e-9)
+        # a1=2,a0=1,b=1,wn=3,zeta=0.7,p3=4 -> kp=24.8 ki=36 kd=6.2
+        kp2, ki2, kd2 = gnc.pid_gains_second_order(2.0, 1.0, 1.0, 3.0,
+                                                   0.7, 4.0)
+        self.assertAlmostEqual(kp2, 24.8, delta=1e-6)
+        self.assertAlmostEqual(ki2, 36.0, delta=1e-6)
+        self.assertAlmostEqual(kd2, 6.2, delta=1e-6)
+
+    def test_type1_margins_anchor(self):
+        # leaf anchor: L = 2/(s(s+2)) -> PM 65.5305 deg, GM inf
+        m = gnc.type1_margins(2.0, 2.0)
+        self.assertAlmostEqual(m["crossover_rad_s"], 0.9101797, delta=1e-4)
+        self.assertAlmostEqual(m["phase_margin_deg"], 65.5305, delta=1e-2)
+        self.assertEqual(m["gain_margin"], float("inf"))
+
+    def test_loop_margins_canonical_anchor(self):
+        # frequency-response-design anchor: G = 2/(s(s+1)(s+2)) ->
+        # GM 3.0 (9.5424 dB) at w_pc = sqrt(2), PM ~ 32.61 deg at
+        # w_gc ~ 0.74935 rad/s
+        m = gnc.loop_margins([2.0], [1.0, 3.0, 2.0, 0.0])
+        self.assertAlmostEqual(m["gain_margin"], 3.0, delta=1e-3)
+        self.assertAlmostEqual(m["gain_margin_db"], 9.5424, delta=1e-2)
+        self.assertAlmostEqual(m["phase_crossover_rad_s"],
+                               math.sqrt(2.0), delta=1e-2)
+        self.assertAlmostEqual(m["gain_crossover_rad_s"], 0.74935,
+                               delta=1e-2)
+        self.assertAlmostEqual(m["phase_margin_deg"], 32.61, delta=1e-1)
+
+    def test_riccati_anchor(self):
+        # q1=10, q2=1, r=0.1, a=2 -> P and K closed form
+        r = gnc.riccati_solution([[0, 1], [0, -2]], [0, 1],
+                                 [[10, 0], [0, 1]], 0.1)
+        self.assertAlmostEqual(r["P"][0][0], 5.8310, delta=1e-3)
+        self.assertAlmostEqual(r["P"][1][1], 0.3831, delta=1e-3)
+        self.assertAlmostEqual(r["K"][0], 10.0, delta=1e-9)
+        self.assertAlmostEqual(r["K"][1], 3.8310, delta=1e-3)
+        self.assertTrue(r["stable"])
+
+    def test_kalman_steady_state_anchor(self):
+        # q=1, r=1, f=h=1 -> P_inf = (1+sqrt(5))/2 (golden ratio),
+        # K = P/(P+1) ~ 0.61803
+        k = gnc.kalman_steady_state(1.0, 1.0, 1.0, 1.0)
+        self.assertAlmostEqual(k["p_pred"], (1.0 + math.sqrt(5)) / 2.0,
+                               delta=1e-9)
+        self.assertAlmostEqual(k["gain"], 0.61803398875, delta=1e-9)
+        self.assertAlmostEqual(k["p_apost"],
+                               (1.0 - k["gain"]) * k["p_pred"], delta=1e-12)
+
+    def test_observer_gain_2state_anchor(self):
+        # A = [[0,1],[0,-2]], C = [1,0], poles -30,-30 -> L = [58, 784]
+        o = gnc.observer_gain_2state([[0, 1], [0, -2]], [[1, 0]],
+                                     [-30.0, -30.0])
+        self.assertAlmostEqual(o["L"][0], 58.0, delta=1e-6)
+        self.assertAlmostEqual(o["L"][1], 784.0, delta=1e-6)
+        self.assertAlmostEqual(o["settling_time_s"], 4.0 / 30.0, delta=1e-9)
+
+    def test_pn_acceleration(self):
+        # rx=1000, ry=0, vx=-100, vy=10 -> Vc=100, lam_dot=0.01,
+        # a_c = N * 1.0 for N
+        a = gnc.pn_acceleration(1000.0, 0.0, -100.0, 10.0, 4.0)
+        self.assertAlmostEqual(a["closing_speed_m_s"], 100.0, delta=1e-9)
+        self.assertAlmostEqual(a["los_rate_rad_s"], 0.01, delta=1e-12)
+        self.assertAlmostEqual(a["accel_cmd_m_s2"], 4.0, delta=1e-9)
+
+    def test_discrete_pid_velocity(self):
+        d = gnc.discrete_pid_velocity(2.0, 3.0, 4.0, 0.1)
+        self.assertAlmostEqual(d["b0"], 2.0 + 3.0 * 0.1 + 4.0 / 0.1,
+                               delta=1e-12)
+        self.assertAlmostEqual(d["b1"], -2.0 - 2.0 * 4.0 / 0.1, delta=1e-12)
+        self.assertAlmostEqual(d["b2"], 4.0 / 0.1, delta=1e-12)
+        self.assertEqual(d["a1"], -1.0)
+        # b0 + b1 + b2 == Ki*T (constant-error injection per step)
+        self.assertAlmostEqual(d["b0"] + d["b1"] + d["b2"], 3.0 * 0.1,
+                               delta=1e-12)
+
+    def test_sample_rate_rule(self):
+        r = gnc.sample_rate_rule(10.0, 0.02)     # 50 Hz vs 10 rad/s loop
+        self.assertAlmostEqual(r["w_s_min_rad_s"], 100.0, delta=1e-9)
+        self.assertEqual(r["verdict"], "ok")
+        self.assertEqual(gnc.sample_rate_rule(10.0, 0.1)["verdict"],
+                         "too-slow")
+
+    def test_monte_carlo_deterministic(self):
+        a1 = gnc.monte_carlo_outer_margins(10.0, 5.0, 100, seed=7)
+        a2 = gnc.monte_carlo_outer_margins(10.0, 5.0, 100, seed=7)
+        self.assertEqual(a1["pm_min_deg"], a2["pm_min_deg"])
+        self.assertEqual(a1["pm_max_deg"], a2["pm_max_deg"])
+        self.assertEqual(a1["pm_mean_deg"], a2["pm_mean_deg"])
+
+    def test_invalid_inputs_raise(self):
+        with self.assertRaises(ValueError):
+            gnc.pid_gains_second_order(2, 1, 0.0, 3, 0.7, 4)
+        with self.assertRaises(ValueError):
+            gnc.type1_margins(0.0, 2.0)
+        with self.assertRaises(ValueError):
+            gnc.kalman_steady_state(1.0, 1.0, 1.0, 0.0)
+        with self.assertRaises(ValueError):
+            gnc.riccati_solution([[0, 1], [0, -2]], [0, 1],
+                                 [[10, 0], [0, 1]], 0.0)
+        with self.assertRaises(ValueError):
+            gnc.observer_gain_2state([[0, 1], [0, -2]], [[1, 0]],
+                                     [-30.0, 5.0])   # unstable pole
+        with self.assertRaises(ValueError):
+            gnc.observer_gain_2state([[0, 1], [0, -2]], [[0, 0]],
+                                     [-30.0, -30.0])  # not observable
+        with self.assertRaises(ValueError):
+            gnc.pn_acceleration(0.0, 0.0, -100.0, 10.0, 4.0)  # zero range
+
+
+class TestReportBuilder(unittest.TestCase):
+
+    def test_example_model_values(self):
+        m = gnc.build_gnc_report(gnc.example_project())
+        # inner loop gains from the documented example facts
+        self.assertAlmostEqual(m["inner"]["kp"], 156.6, delta=1e-6)
+        self.assertAlmostEqual(m["inner"]["ki"], 864.0, delta=1e-6)
+        self.assertAlmostEqual(m["inner"]["kd"], 9.75, delta=1e-6)
+        # inner margins: comfortable PM, infinite GM (type-1 loop with
+        # numerator lead)
+        self.assertGreater(m["inner"]["margins"]["pm_deg"], 45.0)
+        self.assertEqual(m["inner"]["margins"]["gm_db"], float("inf"))
+        # outer loop numbers
+        self.assertAlmostEqual(m["outer"]["kp_theta"], 5.4, delta=1e-9)
+        self.assertAlmostEqual(m["outer"]["zeta_theta"],
+                               math.sqrt(2) / 2.0, delta=1e-9)
+        self.assertGreater(m["outer"]["bw_rad_s"], 3.0)
+        # nav budget
+        self.assertLess(m["nav"]["sigma_deg"], m["nav"]["budget_deg"])
+        self.assertAlmostEqual(m["nav"]["gain"], 0.02956, delta=1e-3)
+        # lqr + observer + guidance real
+        self.assertTrue(m["lqr"]["stable"])
+        self.assertAlmostEqual(m["observer"]["L"][0], 58.0, delta=1e-6)
+        self.assertAlmostEqual(m["observer"]["L"][1], 784.0, delta=1e-6)
+        self.assertGreater(m["guidance"]["accel_cmd_m_s2"], 0.0)
+
+    def test_requirements_recorded(self):
+        m = gnc.build_gnc_report(gnc.example_project())
+        self.assertEqual(m["requirements"]["phase_margin_deg"], 45.0)
+        self.assertEqual(m["requirements"]["gain_margin_db"], 6.0)
+        self.assertEqual(m["requirements"]["bandwidth_rad_s"], 3.0)
+        self.assertEqual(m["verdicts"]["inner_margins"], "PASS")
+        self.assertEqual(m["verdicts"]["outer_margins"], "PASS")
+        self.assertEqual(m["verdicts"]["outer_bandwidth"], "PASS")
+        self.assertEqual(m["verdicts"]["nav_budget"], "PASS")
+        self.assertEqual(m["verdicts"]["mc_robustness"], "PASS")
+
+    def test_report_markdown_sections(self):
+        md = gnc.example_report_markdown()
+        for sec in ["## 1. Architecture", "## 2. Navigation",
+                    "## 3. Control design", "## 4. Digital",
+                    "## 5. State estimation", "## 6. Guidance",
+                    "## 7. Space GNC", "## 8. Monte Carlo",
+                    "## 9. Conclusions"]:
+            self.assertIn(sec, md, "missing section %s" % sec)
+        low = md.lower()
+        self.assertIn("not an approval", low)
+        self.assertIn("not flight software release", low)
+        self.assertNotIn("___", md)
+
+    def test_model_gates_all_pass(self):
+        m = gnc.build_gnc_report(gnc.example_project())
+        gates = gnc.check_gnc_report(m)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_markdown_gates_all_pass(self):
+        md = gnc.example_report_markdown()
+        gates = gnc.check_gnc_report_markdown(md)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_gates_fail_on_bad_input(self):
+        # tamper with the model: margins below requirement must fail
+        m = gnc.build_gnc_report(gnc.example_project())
+        m["inner"]["margins"]["pm_deg"] = 20.0
+        gates = gnc.check_gnc_report(m)
+        self.assertFalse(gates["all_pass"])
+        self.assertFalse(gates["margins_meet_requirement"])
+        # tampered markdown: no draft marker must fail
+        md = (gnc.example_report_markdown().replace("draft", "REVIEW")
+              .replace("DRAFT", "REVIEW"))
+        g = gnc.check_gnc_report_markdown(md)
+        self.assertFalse(g["all_pass"])
+        self.assertFalse(g["has_draft_marker"])
+
+    def test_standalone_no_skills_repo(self):
+        # Core must work with no AeroSkills present.
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = gnc.build_gnc_report(gnc.example_project())
+        self.assertTrue(model["inner"]["req_ok"])
+        md = gnc.render_gnc_report_markdown(model)
+        self.assertGreater(len(md), 3000)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/gnc-engineer/tests/test_role_gnc_engineer.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Role test: gnc-engineer."""
+import os
+import re
+import sys
+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", "gnc-engineer")
+TEMPLATE = os.path.join(ROLE_DIR, "templates", "gnc-report-template.md")
+CORE_DIR = os.path.join(ROLE_DIR, "core")
+
+sys.path.insert(0, CORE_DIR)
+import gnc_core  # noqa: E402
+
+EXPECTED_BOUND = [
+    "gnc-autonomy/control/pid-control-design",
+    "gnc-autonomy/control/lead-lag-compensation",
+    "gnc-autonomy/control/frequency-response-design",
+    "gnc-autonomy/control/digital-control-design",
+    "gnc-autonomy/control/observer-design",
+    "gnc-autonomy/control/control-allocation",
+    "gnc-autonomy/control/gain-scheduling",
+    "gnc-autonomy/control/adaptive-control",
+    "gnc-autonomy/navigation/navigation-frames",
+    "gnc-autonomy/navigation/inertial-navigation",
+    "gnc-autonomy/navigation/kalman-filter-design",
+    "gnc-autonomy/navigation/gnss-pseudorange-positioning",
+    "gnc-autonomy/navigation/gnss-raim-fde",
+    "gnc-autonomy/navigation/dilution-of-precision",
+    "gnc-autonomy/guidance/pursuit-guidance",
+    "gnc-autonomy/optimal-control/lqr-design",
+    "gnc-autonomy/optimal-control/model-predictive-control",
+    "gnc-autonomy/optimal-control/bang-bang-control",
+    "gnc-autonomy/optimal-control/dymos-trajectory",
+    "gnc-autonomy/space/attitude-dynamics",
+    "gnc-autonomy/space/orbit-dynamics",
+    "gnc-autonomy/space/orbit-determination",
+    "gnc-autonomy/space/rendezvous-phasing"
+]
+
+STAGES = [
+    "1. Frames + plant",
+          "2. Navigation filter",
+          "3. Inner loop",
+          "4. Digital implementation",
+          "5. State estimation",
+          "6. Allocation/scheduling",
+          "7. Guidance",
+          "8. Optimal control",
+          "9. Space GNC",
+          "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 TestGncEngineerRole(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: template is the FILLED worked example - all 9
+        numbered sections + appendix, zero blank fields, draft markers."""
+        self.assertTrue(os.path.exists(TEMPLATE))
+        with open(TEMPLATE) as f:
+            text = f.read()
+        for n in range(1, 10):
+            self.assertTrue(
+                re.search(rf"^## {n}\. ", text, re.M),
+                f"report section {n} missing")
+        self.assertIn("Appendix A", text)
+        self.assertNotIn("___", text)
+        low = text.lower()
+        self.assertIn("draft", low)
+        self.assertIn("not an approval", low)
+        self.assertIn("not flight software release", low)
+
+    def test_template_passes_core_gates(self):
+        """The shipped template must pass the engine's own markdown
+        evidence gates (standalone core, no skills repo needed)."""
+        with open(TEMPLATE) as f:
+            text = f.read()
+        gates = gnc_core.check_gnc_report_markdown(text)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_core_and_cli_present(self):
+        self.assertTrue(os.path.exists(os.path.join(CORE_DIR,
+                                                    "gnc_core.py")),
+                        "core/gnc_core.py missing (100% standard)")
+        self.assertTrue(os.path.exists(os.path.join(ROLE_DIR, "cli.py")),
+                        "cli.py missing (100% standard)")
+
+    def test_core_standalone_example_gates(self):
+        """Core produces a correct, gate-passing report with no skills."""
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = gnc_core.build_gnc_report(gnc_core.example_project())
+        gates = gnc_core.check_gnc_report(model)
+        self.assertTrue(gates["all_pass"], gates)
+        md = gnc_core.example_report_markdown()
+        mgates = gnc_core.check_gnc_report_markdown(md)
+        self.assertTrue(mgates["all_pass"], mgates)
+
+    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/guidance-engineer/ROLE.md

@@ -0,0 +1,156 @@
+---
+type: role
+name: guidance-engineer
+title: "Guidance Engineer"
+status: draft
+domain: gnc-autonomy
+deliverable_type: "guidance law design and assessment report"
+standards_bound:
+  - id: arp4754a
+    tier: TIER-2
+    reference-only: true
+  - id: far-25
+    tier: TIER-1
+    reference-only: false
+  - id: cs-25
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - gnc-autonomy/guidance/proportional-navigation
+  - gnc-autonomy/guidance/augmented-proportional-navigation
+  - gnc-autonomy/guidance/pursuit-guidance
+  - gnc-autonomy/guidance/collision-course-guidance
+  - gnc-autonomy/guidance/command-to-line-of-sight
+  - gnc-autonomy/guidance/midcourse-guidance
+  - gnc-autonomy/guidance/impact-point-prediction
+  - gnc-autonomy/guidance/dubins-path-planning
+  - gnc-autonomy/guidance/coverage-path-planning
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "declare the weapon or vehicle ready for guided release"
+  - "approve flight of the guidance software"
+  - "claim certification approval"
+  - "assert intercept capability without engagement analysis"
+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+"
+---
+
+# Guidance Engineer
+
+## Role identity
+
+Owns the guidance-law design and assessment for a guided vehicle
+(missile/UAV homing loop, interceptor, guided munition): selecting and
+sizing the terminal law (proportional navigation and its augmented
+variant, pursuit, command-to-line-of-sight), sizing the guidance gains
+(navigation constant), checking the commanded acceleration against the
+vehicle's lateral-acceleration limit, estimating the miss distance
+(zero-effort miss), and checking midcourse waypoint steering before
+terminal handover. Use when a guided engagement needs a quantified
+guidance-law assessment with real command numbers. Do NOT use for
+navigation state estimation or control-law design (see gnc-engineer),
+for trajectory optimization (optimal-control roles), or for
+certification of the guidance software (see do178c-cert-engineer).
+
+## Deliverable contract
+
+The role produces the **Guidance Law Design and Assessment Report** per
+templates/guidance-report-template.md:
+
+1. **Scope and engagement definition** — item, vehicle, stated project
+   facts (miss requirement, acceleration limit, target-maneuver
+   estimate).
+2. **Engagement geometry** — range, closing velocity, LOS rate and LOS
+   angle at terminal handover.
+3. **Law candidates and commands** — PN and augmented-PN commands,
+   pursuit-family comparison (heading error, lead angle, capture
+   condition, tail-chase intercept time).
+4. **Guidance gain selection** — navigation constant N within the
+   3-to-5 band (4 baseline) and the APN effective ratio.
+5. **Acceleration limit check** — command utilization vs the vehicle
+   lateral-acceleration limit.
+6. **Miss-distance estimate** — zero-effort miss at the handover state
+   against the guided-intercept requirement.
+7. **Midcourse waypoint steering check** — turn-rate-limited desired
+   course, commanded turn, velocity to be gained.
+8. **Findings and open items** — what is settled and what remains for
+   the human guidance lead.
+9. **Compliance and sign-off boundary** — recommendation, law sources,
+   DRAFT marker.
+
+## Workflow (stages → bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Engagement definition | guidance/collision-course-guidance, guidance/impact-point-prediction | engagement geometry, required miss distance, stated sizing facts |
+| 2. Law trade space | guidance/proportional-navigation, guidance/pursuit-guidance, guidance/augmented-proportional-navigation, guidance/command-to-line-of-sight | candidate law set with command levels at the design point |
+| 3. Gain sizing | guidance/proportional-navigation, guidance/augmented-proportional-navigation | navigation constant N (3-to-5 band, 4 baseline), APN effective ratio |
+| 4. Acceleration limit check | guidance/proportional-navigation, guidance/augmented-proportional-navigation | commanded-acceleration utilization vs vehicle limit |
+| 5. Miss-distance estimate | guidance/midcourse-guidance | zero-effort miss and time to go vs the requirement |
+| 6. Midcourse steering | guidance/midcourse-guidance, guidance/dubins-path-planning, guidance/coverage-path-planning | waypoint steering check, path feasibility context |
+| 7. Report and gates | guidance (all bound leaves) | assessment report, evidence bundle, gate verdicts |
+
+## Evidence gates
+
+- Stage 2 done = every candidate law produces a real command number at
+  the design point (PN, APN, pursuit geometry).
+- Stage 4 done = command utilization computed against the vehicle
+  limit; saturation flagged.
+- Stage 5 done = zero-effort miss and time to go estimated and compared
+  with the miss requirement.
+- FINAL = every computed number in the report is backed by a guidance
+  law encoded from the bound leaves (gnc-autonomy/guidance *_logic.py);
+  nothing asserted without a checkable basis. The rendered report
+  carries DRAFT + human-review + not-an-approval markers (code-enforced
+  by check_report / check_report_markdown).
+
+## Boundary / forbidden
+
+- NEVER declare the weapon or vehicle ready for guided release, and
+  NEVER approve flight of the guidance software — the human guidance
+  lead and the program's release authority sign.
+- NEVER assert intercept capability beyond what the engagement analysis
+  supports (seeker noise, autopilot lag and out-of-sizing target
+  maneuvers stay open items).
+- NEVER claim certification approval; ARP4754A and FAR/CS-25 are
+  reference-only context and no proprietary standard text is
+  reproduced.
+- Output is a DRAFT for human review — mark it draft.
+
+## Verification
+
+The role runs STANDALONE: `core/guidance_core.py` is an executable
+engine that computes PN/APN commands, pursuit geometry, turn-rate-
+limited waypoint steering, acceleration utilization, zero-effort miss,
+BUILDS the report, and gate-checks deliverables. No AeroSkills checkout
+required. When the library IS present, the bound leaf logic files are
+dispatched on the same inputs and their agreement (delta ~ 0) is
+recorded in provenance.json.
+
+Run the role:
+```bash
+python3 cli.py build --out report.md --bundle      # example item
+python3 cli.py build --n-nav 5 --miss-requirement 5
+python3 cli.py check --file report.md              # gate-check a report
+```
+
+Tests:
+- tests/test_guidance_engineer_core.py: domain rules with the real
+  leaf anchors (PN a_c = 15.762965 m/s^2, ZEM 150 m at t_go 20 s, vgo
+  65.08 m/s, waypoint 26.565 deg) + builder + gates + standalone (no
+  skills repo) + evidence-bundle smoke.
+- tests/test_role_guidance_engineer.py: bound-skill resolution (skips
+  if the skills repo is absent) + workflow order + filled template +
+  boundaries.
+
+## Compliance
+
+- arp4754a TIER-2 reference-only and far-25/cs-25 TIER-1 reference-only
+  per the skills standards map; the laws are common knowledge encoded
+  by the leaves, paraphrased, never copied verbatim.
+- SOURCES.md records the sources and the encoded domain rules.