aero-agent-roles 1.0.0

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

@@ -0,0 +1,70 @@
+# Guidance Law Design and Assessment Report
+
+**Item:** Interceptor terminal homing loop (guided UAV class)
+**Vehicle:** Air-to-air interceptor (UAV class)
+**Status:** draft-for-review
+
+## 1. Scope and engagement definition
+
+This report designs and assesses the terminal guidance law for Interceptor terminal homing loop (guided UAV class) (Air-to-air interceptor (UAV class)). Terminal guidance law design and assessment for a guided interceptor engaging an aerial target on a constant-velocity terminal segment.
+The engagement-level requirements and sizing facts are stated project facts (verify against vehicle and target data):
+- Required miss distance: <= 10.000 m.
+- Vehicle lateral acceleration limit: 30 g (294.20 m/s^2).
+- Target maneuver estimate for augmentation sizing: 20.000 m/s^2.
+- Navigation constant band: 3 to 5 (4 baseline).
+
+## 2. Engagement geometry at terminal handover
+
+The assessment opens at terminal handover with the interceptor at the origin at 300.000 m/s along +x and the target at 100.000 m/s along +x (project facts). Relative state: position (1000, 100) m, velocity (-200, 0) m/s.
+- Range: 1004.988 m.
+- Closing velocity: 199.007 m/s.
+- Line-of-sight rate: 0.019802 rad/s.
+- Line-of-sight angle: 5.711 deg.
+
+## 3. Guidance law candidates and commands
+
+- **Proportional navigation** (terminal law): a_c = N * Vc * lam_dot = 15.763 m/s^2 (1.607 g) at N = 4.
+- **Augmented proportional navigation** (maneuvering target): a_apn = N * (Vc * lam_dot + a_T/2) = 55.763 m/s^2 (5.686 g).
+- **Pursuit family** (comparison): LOS angle 5.711 deg, heading error 5.711 deg; pure pursuit capture requires Vi > Vt (satisfied, Vi = 300 m/s vs Vt = 100 m/s).
+- Pursuit lead for a collision triangle: -1.901 deg; tail-chase intercept time 5.025 s.
+
+## 4. Guidance gain selection
+
+The navigation constant is N = 4, the common baseline within the 3-to-5 band used by the bound leaves. Augmented PN uses the same effective ratio N' = 4. Gain selection is a project decision; this report records the command levels produced at the design point.
+
+## 5. Acceleration limit check
+
+- PN command utilization: 5.4% of the 30 g limit (within limit).
+- APN command utilization: 19.0% of the 30 g limit (within limit).
+
+## 6. Miss-distance estimate
+
+Zero-effort miss at the handover state (both vehicles hold velocity): 100.000 m at t_go = 5.000 s, against the 10.000 m requirement (10.0x the requirement). Guidance authority is required; proportional navigation commands acceleration proportional to the LOS rate and drives it to zero (the collision-course condition).
+
+## 7. Midcourse waypoint steering check
+
+- Desired course to waypoint: 26.565 deg; course error 26.565 deg.
+- Turn-rate limit 5 deg/s at 1.000 s steps: commanded turn clamped to 5.000 deg per step.
+- Velocity to be gained along the desired course: 31.672 m/s.
+
+## 8. Findings and open items
+
+Findings:
+- PN command is 5.4% of the 30 g lateral-acceleration limit at the terminal handover design point (no saturation margin concern for the PN law).
+- The unguided zero-effort miss is 100 m against the 10 m requirement; guidance authority is required and the PN/APN command levels are consistent with nulling the LOS rate.
+- Augmented PN (APN) raises the command by N*a_T/2 = 40 m/s^2 for the 20 m/s^2 target-maneuver estimate; both laws remain inside the 30 g limit at this design point.
+- Midcourse waypoint steering is turn-rate-limited at 5 deg/s: a 26.6 deg course error is applied at 5 deg per guidance step.
+
+Open items before the human guidance lead closes this assessment:
+- Seeker noise and LOS-rate filtering effects on effective navigation ratio (not modeled here).
+- Autopilot lag and airframe response in the homing loop.
+- Target maneuver beyond the 20 m/s^2 sizing estimate.
+
+## 9. Compliance and sign-off boundary
+
+- Recommended law: proportional navigation (N = 4), with augmentation (recommended) for the maneuvering-target case.
+- Guidance laws encoded here are paraphrases of the classical laws carried by the bound Aero Agent Skills leaves (gnc-autonomy/guidance); ARP4754A and FAR/CS-25 frame development assurance context (reference only).
+- This document is a DRAFT for human review by the guidance lead. It is not an approval document and not flight software release.
+
+---
+*Generated by Aero Agent Roles guidance-engineer core (2026-09-05). DRAFT for human guidance lead review. Not an approval document. Not flight software release.*

package/roles/guidance-engineer/tests/test_guidance_engineer_core.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Test guidance_core: the executable engine of the Guidance Engineer role.
+
+Proves the role can DO its job standalone (no AeroSkills needed):
+PN/APN commands, pursuit geometry, waypoint steering, acceleration
+limits, zero-effort miss, report generation, evidence-gate checks, and
+the cli build --bundle + --profile evidence bundle. Every domain anchor
+is the real anchor asserted by the bound leaf gate-3 contract tests.
+"""
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                "..", "core"))
+from guidance_core import (  # noqa: E402
+    G0, accel_limit_m_s2, accel_utilization, accel_within_limit,
+    apn_command, build_report, capture_possible, check_report,
+    check_report_markdown, closing_velocity, commanded_acceleration,
+    commanded_accel_g, commanded_heading, course_error, desired_heading,
+    example_project, example_report_markdown, guidance_command,
+    handover_check, heading_error, intercept_time, lead_angle,
+    line_of_sight_angle, line_of_sight_rate, miss_within_requirement,
+    render_report_markdown, velocity_to_be_gained, zero_effort_miss,
+)
+
+# Real leaf anchors (proportional-navigation leaf gate-3 test):
+#   rx=1000, ry=100, vx=-200, vy=0, N=4
+PN_RANGE = 1004.987562112089
+PN_VC = 199.007438042
+PN_LAM = 0.0198019801980198
+PN_ACC = 15.762965390
+
+ROLE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ROLES_REPO = os.path.dirname(os.path.dirname(ROLE_DIR))
+
+
+class TestGuidanceLawRules(unittest.TestCase):
+
+    def test_closing_velocity_anchor(self):
+        self.assertAlmostEqual(
+            closing_velocity(1000.0, 100.0, -200.0, 0.0), PN_VC, places=4)
+
+    def test_closing_velocity_pure(self):
+        self.assertAlmostEqual(
+            closing_velocity(1000.0, 0.0, -200.0, 0.0), 200.0, places=4)
+
+    def test_los_rate_anchor(self):
+        self.assertAlmostEqual(
+            line_of_sight_rate(1000.0, 100.0, -200.0, 0.0), PN_LAM, places=4)
+
+    def test_pn_command_anchor(self):
+        a = commanded_acceleration(1000.0, 100.0, -200.0, 0.0, 4.0)
+        self.assertAlmostEqual(a, PN_ACC, places=4)
+
+    def test_pn_linear_in_nav_constant(self):
+        a4 = commanded_acceleration(1000.0, 100.0, -200.0, 0.0, 4.0)
+        a6 = commanded_acceleration(1000.0, 100.0, -200.0, 0.0, 6.0)
+        self.assertAlmostEqual(a6 / a4, 1.5, places=4)
+
+    def test_pn_zero_on_collision_course(self):
+        # Pure closing: lam_dot = 0 -> no lateral command
+        self.assertAlmostEqual(
+            commanded_acceleration(1000.0, 0.0, -200.0, 0.0, 4.0), 0.0,
+            places=6)
+
+    def test_pn_invalid_inputs_raise(self):
+        with self.assertRaises(ValueError):
+            commanded_acceleration(0.0, 0.0, -200.0, 0.0, 4.0)
+        with self.assertRaises(ValueError):
+            commanded_acceleration(1000.0, 100.0, -200.0, 0.0, 0.0)
+        with self.assertRaises(ValueError):
+            commanded_acceleration(1000.0, 100.0, -200.0, 0.0, -2.0)
+
+    def test_guidance_command_bundle(self):
+        cmd = guidance_command(1000.0, 100.0, -200.0, 0.0, n_nav=4.0)
+        self.assertAlmostEqual(cmd["range"], PN_RANGE, places=4)
+        self.assertAlmostEqual(cmd["accel_cmd"], PN_ACC, places=4)
+        self.assertEqual(cmd["n_nav"], 4.0)
+
+    def test_apn_augmentation_term(self):
+        # a_apn = a_pn + N*a_T/2: with N=4, a_T=20 -> +40 m/s^2
+        vc = closing_velocity(1000.0, 100.0, -200.0, 0.0)
+        lam = line_of_sight_rate(1000.0, 100.0, -200.0, 0.0)
+        apn = apn_command(4.0, vc, lam, 20.0)
+        self.assertAlmostEqual(apn, PN_ACC + 40.0, places=4)
+
+    def test_accel_in_g(self):
+        self.assertAlmostEqual(commanded_accel_g(PN_ACC), PN_ACC / G0,
+                               places=6)
+
+
+class TestPursuitGeometry(unittest.TestCase):
+
+    def test_los_angle(self):
+        lam = line_of_sight_angle(1000.0, 100.0)
+        self.assertAlmostEqual(lam, 0.09966865249, places=6)  # 5.7106 deg
+
+    def test_heading_error(self):
+        eta = heading_error(0.0, 1000.0, 100.0)
+        self.assertAlmostEqual(eta, 0.09966865249, places=6)
+
+    def test_lead_angle_speed_ratio(self):
+        # beta = -5.7106 deg, Vt/Vi = 1/3 -> lead ~ -1.9007 deg
+        lead = lead_angle(100.0, 300.0, -0.09966865249)
+        self.assertAlmostEqual(lead, -0.03317399, places=6)
+
+    def test_capture_condition(self):
+        self.assertTrue(capture_possible(300.0, 100.0))
+        self.assertFalse(capture_possible(90.0, 100.0))
+
+    def test_tail_chase_intercept_time(self):
+        # r = 1000, Vi = 300, Vt = 250 -> t = 20 s exactly
+        self.assertAlmostEqual(intercept_time(1000.0, 300.0, 250.0), 20.0,
+                               places=6)
+        with self.assertRaises(ValueError):
+            intercept_time(1000.0, 100.0, 300.0)  # never closes
+
+
+class TestWaypointSteering(unittest.TestCase):
+
+    def test_desired_heading_anchor(self):
+        # (0,0) -> (1000,500) = 26.565 deg (leaf anchor)
+        psi_d = desired_heading((0.0, 0.0), (1000.0, 500.0))
+        self.assertAlmostEqual(psi_d, 0.4636476090, places=6)
+        self.assertAlmostEqual(psi_d, 26.5650511771 * 0.0174532925, places=3)
+
+    def test_course_error_wraps(self):
+        # heading 45 deg vs 26.565 deg course -> -18.435 deg (leaf anchor)
+        e = course_error((0.0, 0.0), (1000.0, 500.0), 0.7853981634)
+        self.assertAlmostEqual(e, -0.3217505544, places=6)
+
+    def test_turn_rate_limit_clamps(self):
+        # 5 deg/s, 1 s step: 26.565 deg error applied at 5 deg/step
+        psi_c = commanded_heading((0.0, 0.0), (1000.0, 500.0), 0.0,
+                                  0.0872664626, 1.0)
+        self.assertAlmostEqual(psi_c, 0.0872664626, places=6)
+
+    def test_turn_rate_full_error_passes(self):
+        # 30 deg/s, 1 s step: full error passes -> psi_c = psi_d
+        psi_c = commanded_heading((0.0, 0.0), (1000.0, 500.0), 0.0,
+                                  0.5235987756, 1.0)
+        self.assertAlmostEqual(psi_c, 0.4636476090, places=6)
+
+    def test_velocity_to_be_gained_anchor(self):
+        # leaf anchor: V=250, e=20 deg, V_target=300 -> 65.08 m/s
+        vgo = velocity_to_be_gained(250.0, 0.3490658504, 300.0)
+        self.assertAlmostEqual(vgo, 65.0768, places=2)
+
+
+class TestMissDistanceAndLimits(unittest.TestCase):
+
+    def test_zem_leaf_anchor(self):
+        # interceptor (0,0) at 300 m/s +x vs stationary target (6000,150)
+        # -> t_go = 20 s, ZEM = 150 m (leaf anchor)
+        zem = zero_effort_miss((0.0, 0.0), (300.0, 0.0),
+                               (6000.0, 150.0), (0.0, 0.0))
+        self.assertAlmostEqual(zem["time_to_go"], 20.0, places=6)
+        self.assertAlmostEqual(zem["zem"], 150.0, places=6)
+
+    def test_zem_zero_on_collision(self):
+        zem = zero_effort_miss((0.0, 0.0), (300.0, 0.0),
+                               (9000.0, 0.0), (100.0, 0.0))
+        self.assertAlmostEqual(zem["zem"], 0.0, places=6)
+
+    def test_handover_check(self):
+        self.assertTrue(handover_check((0.0, 0.0), (8000.0, 0.0), 8000.0))
+        self.assertFalse(handover_check((0.0, 0.0), (9000.0, 0.0), 8000.0))
+
+    def test_accel_limit_and_utilization(self):
+        self.assertAlmostEqual(accel_limit_m_s2(30.0), 30.0 * G0, places=6)
+        # example PN command 15.763 m/s^2 -> 5.36% of a 30 g limit
+        util = accel_utilization(15.76296539, 30.0)
+        self.assertAlmostEqual(util, 0.0535792, places=6)
+        self.assertTrue(accel_within_limit(15.76296539, 30.0))
+        self.assertFalse(accel_within_limit(5000.0, 30.0))
+
+    def test_miss_requirement(self):
+        self.assertTrue(miss_within_requirement(5.0, 10.0))
+        self.assertFalse(miss_within_requirement(100.0, 10.0))
+
+
+class TestReportBuilder(unittest.TestCase):
+
+    def test_example_report_model(self):
+        model = build_report(example_project())
+        self.assertEqual(model["recommended_law"], "proportional navigation")
+        self.assertEqual(model["n_nav"], 4.0)
+        self.assertEqual(model["status"], "draft-for-review")
+        self.assertAlmostEqual(model["pn"]["accel_pn_m_s2"], PN_ACC, places=4)
+        self.assertAlmostEqual(model["pn"]["accel_apn_m_s2"],
+                               PN_ACC + 40.0, places=4)
+        self.assertAlmostEqual(model["miss"]["zem_m"], 100.0, places=4)
+        self.assertAlmostEqual(model["miss"]["time_to_go_s"], 5.0, places=4)
+
+    def test_example_has_all_sections(self):
+        md = example_report_markdown()
+        for n in range(1, 10):
+            self.assertIn("## %d. " % n, md, "section %d missing" % n)
+        self.assertIn("not an approval", md.lower())
+        self.assertIn("not flight software release", md.lower())
+
+    def test_core_gates_all_pass(self):
+        model = build_report(example_project())
+        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_standalone_no_skills_repo(self):
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = build_report(example_project())
+        self.assertEqual(model["status"], "draft-for-review")
+        md = render_report_markdown(model)
+        self.assertGreater(len(md), 1000)
+
+    def test_cli_build_bundle_standalone(self):
+        """cli build --bundle exits 0 and emits valid evidence (PROTOCOL)."""
+        with tempfile.TemporaryDirectory() as td:
+            out = os.path.join(td, "report.md")
+            env = dict(os.environ, AEROSKILLS_DEV="/nonexistent")
+            r = subprocess.run(
+                [sys.executable, os.path.join(ROLE_DIR, "cli.py"), "build",
+                 "--out", out, "--bundle"],
+                cwd=ROLE_DIR, env=env, capture_output=True, text=True)
+            self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+            ev = os.path.join(td, "evidence")
+            for name in ("model.json", "gates.json", "provenance.json"):
+                self.assertTrue(os.path.exists(os.path.join(ev, name)),
+                                name + " missing")
+            gates = json.load(open(os.path.join(ev, "gates.json")))
+            self.assertTrue(gates["all_pass"])
+            self.assertEqual(gates["exit_code"], 0)
+            model = json.load(open(os.path.join(ev, "model.json")))
+            self.assertEqual(model["status"], "draft-for-review")
+            self.assertEqual(model["miss"]["zem_m"], 100.0)
+            prov = json.load(open(os.path.join(ev, "provenance.json")))
+            self.assertGreaterEqual(len(prov["skills"]), 1)
+            # standalone: every row reports no dispatch, no crash
+            for row in prov["skills"]:
+                self.assertFalse(row["dispatched"])
+
+    def test_cli_build_with_profile(self):
+        """--profile tailors the deliverable and still passes gates."""
+        profile = os.path.join(ROLES_REPO, "profiles", "example-airframer.json")
+        if not os.path.exists(profile):
+            self.skipTest("example profile not present")
+        with tempfile.TemporaryDirectory() as td:
+            out = os.path.join(td, "report.md")
+            env = dict(os.environ, AEROSKILLS_DEV="/nonexistent")
+            r = subprocess.run(
+                [sys.executable, os.path.join(ROLE_DIR, "cli.py"), "build",
+                 "--out", out, "--profile", profile],
+                cwd=ROLE_DIR, env=env, capture_output=True, text=True)
+            self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+            md = open(out).read()
+            self.assertIn("Program context (profile)", md)
+            gates = check_report_markdown(md)
+            self.assertTrue(gates["all_pass"], gates)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/guidance-engineer/tests/test_role_guidance_engineer.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Role test: Guidance Engineer.
+
+Verifies (offline, no network):
+1. Every skill bound in ROLE.md frontmatter RESOLVES to a real leaf in
+   the aero-agent-skills repo (the pinned skills_release band).
+2. The workflow stage order is deterministic and complete.
+3. The deliverable template is the FILLED worked example for the
+   reference item (zero blanks, draft markers) and passes the engine's
+   own markdown gates.
+"""
+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__)))))          # repo root (4 up from tests/)
+# Bound-skill resolution requires the Aero Agent Skills checkout. It is a
+# cross-repo dev check: when the skills repo is absent (fresh public clone),
+# skip resolution rather than fail - the role's bound list is verified in CI.
+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", "guidance-engineer")
+TEMPLATE = os.path.join(ROLE_DIR, "templates", "guidance-report-template.md")
+CORE_DIR = os.path.join(ROLE_DIR, "core")
+
+sys.path.insert(0, CORE_DIR)
+import guidance_core  # noqa: E402
+
+EXPECTED_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",
+]
+
+STAGES = [
+    "1. Engagement definition",
+    "2. Law trade space",
+    "3. Gain sizing",
+    "4. Acceleration limit check",
+    "5. Miss-distance estimate",
+    "6. Midcourse steering",
+    "7. Report and gates",
+]
+
+
+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 TestGuidanceEngineerRole(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")),
+                "bound skill missing: %s" % 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, 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(r"^## %d\. " % n, text, re.M),
+                "report section %d missing" % n)
+        self.assertNotIn("___", text)
+        low = text.lower()
+        self.assertIn("draft", low)
+        self.assertIn("not an approval", low)
+        self.assertIn("not flight software release", low)
+        # key computed numbers of the worked example are present
+        self.assertIn("15.763", text)    # PN command m/s^2
+        self.assertIn("100.000", text)   # zero-effort miss m
+        self.assertIn("26.565", text)    # waypoint desired course deg
+
+    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 = guidance_core.check_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,
+                                                    "guidance_core.py")),
+                        "core/guidance_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 = guidance_core.build_report(guidance_core.example_project())
+        gates = guidance_core.check_report(model)
+        self.assertTrue(gates["all_pass"], gates)
+        md = guidance_core.example_report_markdown()
+        mgates = guidance_core.check_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)
+        for phrase in ["declare the weapon or vehicle ready for guided "
+                       "release", "approve flight of the guidance software",
+                       "claim certification approval"]:
+            self.assertIn(phrase, role, "missing boundary: %s" % phrase)
+
+    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/high-speed-aerodynamics-engineer/ROLE.md

@@ -0,0 +1,161 @@
+---
+type: role
+name: high-speed-aerodynamics-engineer
+title: "High-Speed Aerodynamics Engineer"
+status: draft
+domain: aerodynamics
+deliverable_type: "High-Speed Aerodynamic Analysis Memo"
+standards_bound:
+  - id: naca-tr-824
+    tier: TIER-2
+    reference-only: true
+skills_bound:
+  - aerodynamics/high-speed/isentropic-flow-relations
+  - aerodynamics/high-speed/normal-shock
+  - aerodynamics/high-speed/oblique-shock
+  - aerodynamics/high-speed/prandtl-meyer
+  - aerodynamics/high-speed/regular-shock-reflection
+  - aerodynamics/high-speed/shock-expansion-airfoil
+  - aerodynamics/high-speed/transonic-similarity
+  - aerodynamics/high-speed/swept-wing-aerodynamics
+  - aerodynamics/high-speed/supercritical-airfoil
+  - aerodynamics/high-speed/wave-drag-area-rule
+  - aerodynamics/high-speed/bow-shock-standoff
+  - aerodynamics/high-speed/aerodynamic-heating
+  - aerodynamics/high-speed/flat-plate-skin-friction-heating
+  - aerodynamics/high-speed/hypersonic-flow
+  - aerodynamics/boundary-layer/boundary-layer-theory
+  - aerodynamics/boundary-layer/boundary-layer-transition
+  - aerodynamics/boundary-layer/boundary-layer-separation
+  - aerodynamics/boundary-layer/rough-wall-skin-friction
+  - aerodynamics/boundary-layer/stagnation-flow-boundary-layer
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "claim certification approval"
+  - "declare a compliance finding"
+  - "reproduce proprietary standard text"
+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+"
+---
+
+# High-Speed Aerodynamics Engineer
+
+## Role identity
+
+Owns the compressible-flow analysis of a transonic/supersonic vehicle
+at a flight condition: isentropic total conditions, Mach-area and
+inlet capture, Prandtl-Glauert / Karman-Tsien compressibility
+corrections, normal and oblique shock systems, Prandtl-Meyer
+expansion, shock-expansion section analysis, transonic drag
+divergence and wave drag, boundary-layer thickness/transition/skin
+friction at high speed, stagnation-line heating, and bow-shock
+standoff. Use when a high-speed vehicle's flight condition must
+demonstrate its compressible-flow behavior with numbers (total
+pressure recovery, shock attachment margins, critical/divergence
+Mach, boundary-layer state, heating screen). Do NOT use for
+subsonic airfoil/wing design (see aerodynamics-engineer), engine
+thermodynamics (see propulsion-engineer), or aeroelastic clearance
+(see structures/loads roles).
+
+## Deliverable contract
+
+1. **High-Speed Aerodynamic Analysis Memo** - one flight condition of
+   a transonic/supersonic vehicle: flow state, total conditions,
+   shock-system geometry and losses, transonic limits, boundary
+   layer, and heating screen with the real compressible-flow numbers.
+2. **Margin summary** - each margin (intake recovery, shock
+   attachment, drag-divergence, critical Mach, kinetic-heating) with
+   the workflow stage that produced its source numbers.
+3. **Evidence bundle** - model/gates/provenance JSON when run with
+   `--bundle` (docs/PROTOCOL.md); dispatch cross-checks the core
+   against the bound AeroSkills leaf logic when AeroSkills is present.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Flow-state setup | (ISA, offline) | atmosphere, V, q, Reynolds environment |
+| 2. Isentropic relations | isentropic-flow-relations | T0/T, p0/p, rho0/rho, A/A*, M-from-area, choked flow |
+| 3. Compressibility corrections | transonic-similarity + swept-wing-aerodynamics | P-G and Karman-Tsien Cp, Cp*, section M_cr, M_eff = M cos(Lambda) |
+| 4. Shock system | normal-shock + oblique-shock + regular-shock-reflection | nose normal shock, ramp oblique shock, reflection verdict |
+| 5. Expansion | prandtl-meyer | aft-body/nozzle expansion state |
+| 6. Supersonic section | shock-expansion-airfoil | diamond-airfoil cl/cd_wave/cm_le |
+| 7. Transonic limit | supercritical-airfoil + wave-drag-area-rule | Korn M_DD, terminating shock, Sears-Haack zero-lift wave drag |
+| 8. Boundary layer | boundary-layer-theory + boundary-layer-transition | flat-plate delta/delta*/theta/Cf, transition x_tr |
+| 9. BL separation screen | boundary-layer-separation | Thwaites/Stratford margin when a pressure history is given |
+| 10. Surface state | rough-wall-skin-friction + stagnation-flow-boundary-layer | k+ regime, Hiemenz attachment-line layer |
+| 11. Heating screen | aerodynamic-heating + flat-plate-skin-friction-heating + bow-shock-standoff + hypersonic-flow | Sutton-Graves flux, T_aw, cold-wall flux, nose standoff |
+| 12. Memo | (all above) | the High-Speed Aerodynamic Analysis Memo |
+
+## Evidence gates
+
+- Stage 2 done = total conditions and the Mach-area relation produce
+  real numbers with a documented isentropic anchor (p0/p and A/A* at
+  the flight Mach).
+- Stage 4 done = normal shock decelerates to subsonic (M2 < 1), the
+  intake ramp oblique shock is attached (theta < theta_max), and the
+  reflection verdict (regular/mach) is stated.
+- Stage 7 done = drag-divergence Mach (Korn) and the wave drag area
+  are stated for the vehicle's section and equivalent body.
+- Stage 8 done = flat-plate boundary-layer thickness, skin friction
+  and transition location are stated at the cruise station.
+- FINAL = every margin in the memo traces to a stage output and the
+  memo is DRAFT for human review (never an approval).
+
+## Boundary / forbidden
+
+- NEVER claim certification approval or a compliance finding.
+- NEVER reproduce proprietary standard text (data references are
+  summary + cite).
+- Heating numbers are a screening input for thermal-structures work;
+  kinetic-heating margins use recovery-temperature ceilings, not a
+  materials approval. Drag-divergence and sweep numbers are
+  section-level engineering estimates (Korn/Karman-Tsien/Blasius
+  class), not CFD or wind-tunnel results.
+
+## Verification
+
+The role runs STANDALONE: `core/high_speed_aero_core.py` is an
+executable engine that computes the memo numbers with the real
+compressible-flow formulas of the bound AeroSkills leaves (isentropic
+relations, Prandtl-Glauert/Karman-Tsien, normal/oblique shock,
+Prandtl-Meyer, shock-expansion airfoil, Korn rule, Sears-Haack,
+flat-plate boundary layer, Michel transition, Hiemenz attachment
+line, Sutton-Graves heating, Billig standoff), BUILDS the memo, and
+gate-checks deliverables. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out memo.md              # reference flight condition
+python3 cli.py build --mach 2.20 --altitude 18288  # Mach override
+python3 cli.py check --file memo.md             # gate-check a memo
+```
+
+Tests:
+- tests/test_high_speed_aero_core.py: formula correctness vs known
+  leaf anchors (isentropic ratios at M2, A/A* = 1.6875, normal shock
+  at M2, oblique shock at (M2, 10 deg), Prandtl-Meyer nu(2), KT
+  correction, Korn M_DD, boundary-layer thickness/transition,
+  stagnation heating), memo builder + gates + markdown completeness +
+  STANDALONE (no skills repo)
+- tests/test_role_high_speed_aerodynamics.py: bound-skill resolution
+  (skips if the skills repo is absent) + workflow + template +
+  boundaries
+
+Templates: templates/high-speed-memo-template.md is the FILLED
+generated memo for the reference supersonic cruiser flight condition
+(zero blank fields) - exactly what `cli.py build` produces.
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present; the core engine does not depend on them.
+
+## Compliance
+
+- naca-tr-824 TIER-2 reference-only for the compressible-flow data
+  relations; data references summary-not-copy per STANDARDS.md.
+- SOURCES.md records standards referenced.

package/roles/high-speed-aerodynamics-engineer/SOURCES.md

@@ -0,0 +1,18 @@
+# SOURCES.md - High-Speed Aerodynamics Engineer
+
+| Source | Role use | Gated |
+|---|---|---|
+| NACA TR-824 | compressible-flow relations data source (reference-only) | true |
+| Anderson, Modern Compressible Flow (textbook) | shock/expansion anchors (M2: p2/p1 4.5, oblique (M2,10deg) example) | true |
+| Korn rule (supercritical airfoil practice) | drag-divergence Mach estimate | false |
+| Whitcomb area rule / Sears-Haack (NACA Report 1273) | zero-lift wave drag estimate | false |
+| Blasius / Schlichting flat-plate boundary layer | laminar/turbulent thickness and skin friction | false |
+| Michel transition criterion / Thwaites method | transition location estimate | false |
+| Sutton-Graves stagnation heating correlation | stagnation-point heat flux screen | false |
+| Billig bow-shock standoff correlations | nose standoff estimate | false |
+| ISA standard atmosphere | flight-condition state | false |
+
+Summary-not-copy per STANDARDS.md. Data references cite sources, never
+reproduce them. All numbers in the memo are engineering estimates
+from these methods - screening inputs, not CFD/wind-tunnel results and
+never an approval.