aero-agent-roles 1.0.0

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

@@ -0,0 +1,160 @@
+---
+type: role
+name: flight-management-engineer
+title: "Flight Management Engineer"
+status: draft
+domain: avionics
+deliverable_type: "flight plan and RNAV/RNP route assessment"
+standards_bound:
+  - id: do-236c
+    tier: TIER-2
+    reference-only: true
+  - id: do-283a
+    tier: TIER-2
+    reference-only: true
+  - id: ac-90-105a
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - avionics/flight-management/flight-planning
+  - avionics/flight-management/lateral-navigation
+  - avionics/flight-management/vertical-navigation
+  - avionics/flight-management/holding-pattern-entry
+  - avionics/flight-management/dme-arc-leg
+  - avionics/flight-management/radius-to-fix-leg
+  - avionics/flight-management/rhumb-line-leg
+  - avionics/flight-management/radio-navigation-aids
+  - avionics/flight-management/rnp-anp-containment
+  - avionics/flight-management/performance-computation
+  - avionics/flight-management/rta-time-control
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "approve the flight plan or issue a clearance"
+  - "claim route eligibility without computed ANP evidence"
+  - "reproduce proprietary RTCA/ICAO text"
+  - "pass the assessment off as an approved filing"
+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+"
+---
+
+# Flight Management Engineer
+
+## Role identity
+
+This role is the flight management engineer for an aircraft program or
+flight operations analysis: it takes a candidate route and produces a
+Flight Plan and RNAV/RNP Route Assessment with computed geometry and
+verdicts - great-circle leg tracks and distances, radius-to-fix (RF)
+leg construction, DME arc checks, RNP/ANP containment, holding pattern
+entry classification, RTA time-control feasibility, vertical (VNAV)
+profile compliance, ECON cruise performance, and radio navaid geometry.
+Use when a route must be checked for RNAV/RNP flyability and navigation
+performance containment before operational dispatch review. Do NOT use
+for general route "shortest path" travel planning (non-avionics), for
+aircraft performance certification (see flight-mechanics roles), or
+when no route facts (waypoints, RNP value, procedure legs) exist.
+
+## Deliverable contract
+
+The role produces:
+
+1. **Flight Plan and RNAV/RNP Route Assessment** - per the filled
+   `templates/route-assessment-template.md`: waypoint/leg inventory with
+   computed tracks and distances, RF arc geometry, the ANP-versus-RNP
+   verdict with margin, the hold entry result, RTA verdict,
+   VNAV/performance numbers, and a findings list. The example route in
+   the template is a synthetic 4-leg illustration (waypoints are not
+   from a published navigation database and the flight is not a filed
+   plan).
+2. **Evidence bundle** (with `--bundle`) - model/gates/provenance JSON
+   per `docs/PROTOCOL.md`, including cross-check rows when the bound
+   AeroSkills leaves are present.
+3. **Findings** - constraint violations and required corrections for
+   the human dispatcher/flight operations reviewer.
+
+## Workflow (stages → bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Route structure & constraints | avionics/flight-management/flight-planning | waypoint/leg inventory, total track distance, vertical band constraint checks |
+| 2. Lateral track geometry | avionics/flight-management/lateral-navigation | great-circle TF leg tracks and distances |
+| 3. RF leg construction | avionics/flight-management/radius-to-fix-leg | RF turn centre, swept angle, arc length, exit track, chord, validity |
+| 4. Rhumb line legs | avionics/flight-management/rhumb-line-leg | rhumb vs great-circle distance delta for the track-distance method |
+| 5. RNP containment | avionics/flight-management/rnp-anp-containment | ANP (95% = 2 x sigma), required margin, PASS/FAIL containment verdict |
+| 6. Holding entry | avionics/flight-management/holding-pattern-entry | 70/110 sector entry type, outbound timing, 1-in-60 wind-corrected heading |
+| 7. DME arc legs | avionics/flight-management/dme-arc-leg | arc length, chord, bank angle to hold the arc, turn radius |
+| 8. Navaid geometry | avionics/flight-management/radio-navigation-aids | DME slant range, VOR bearing/radial conversions |
+| 9. RTA control | avionics/flight-management/rta-time-control | ETA, achievable window, required Mach, feasibility verdict |
+| 10. VNAV & performance | avionics/flight-management/vertical-navigation + performance-computation | top of descent, gradient/FPA, crossing altitudes, ECON cruise Mach |
+| 11. Findings & sign-off | all bound leaves | findings list, DRAFT assessment for dispatch review |
+
+## Evidence gates
+
+Every produced assessment is gate-checked (`check_report`):
+
+| Gate | Meaning |
+|---|---|
+| route_stated | the route has >= 2 waypoints and >= 1 leg with computed geometry |
+| rnp_present | an RNP value > 0 is stated for the assessed segment |
+| containment_checked | ANP-vs-RNP verdict computed (ANP = 2 x sigma, 95% containment) |
+| entries_correct | holding entry classified as direct/teardrop/parallel by the 70/110 rule |
+| sign_off_honest | document marked draft-for-review, never an approval |
+
+- A stage is done when its computed numbers are in the model and
+  rendered in the deliverable.
+- FINAL = every gate passes AND every finding is recorded; the route
+  may still carry open findings (the assessment surfaces them).
+
+## Boundary / forbidden
+
+- NEVER approve the flight plan and NEVER issue a clearance - the
+  dispatcher, flight crew, and operator retain operational authority.
+- NEVER claim RNP/route eligibility without the computed ANP
+  containment evidence trail.
+- NEVER reproduce proprietary RTCA (DO-236C/DO-283A) or ICAO text.
+  Summaries and original structure only; public FAA advisory circulars
+  (AC 90-105A) are quotable with citation but paraphrase is preferred.
+- The assessment is a DRAFT for human review, not a filed plan and not
+  an approval document.
+
+## Verification
+
+The role runs STANDALONE: `core/flight_management_core.py` is an
+executable engine that computes route geometry (great-circle, RF, DME
+arc, rhumb), RNP containment, holding entry, RTA control, VNAV, ECON
+performance, navaid geometry, BUILDS the assessment, and gate-checks
+deliverables. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out assessment.md                # example route
+python3 cli.py build --out assessment.md --bundle       # + evidence JSON
+python3 cli.py build --rnp-nm 0.5 --sigma 250 --bundle  # other facts
+python3 cli.py build --profile program-profile.json     # customer context
+python3 cli.py check --file assessment.md               # gate-check a doc
+```
+
+With `--bundle`, `cli.py` dispatches the bound rnp-anp-containment and
+holding-pattern-entry leaf logic when the AeroSkills checkout is
+present (AEROSKILLS_DEV or ~/AeroSkills) and records the cross-check
+(agrees/delta) in `evidence/provenance.json`; absent the library the
+role core still produces the complete assessment.
+
+Tests:
+- tests/test_flight_management_core.py (offline): domain rules with
+  real anchors (2-sigma ANP, 70/110 boundaries, RF geometry, DME arc,
+  RTA law, VNAV, ECON), builder + gates + standalone (no skills repo).
+- tests/test_role_flight_management_engineer.py: bound-skill
+  resolution (skips when the skills repo is absent) + workflow order +
+  filled template + boundaries + SOURCES presence.
+
+## Compliance
+
+- do-236c / do-283a TIER-2 reference-only per standards-map; summaries
+  only, never verbatim. ac-90-105a is public FAA guidance (TIER-1).
+- SOURCES.md records acquisition/extraction/verification status.

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

@@ -0,0 +1,30 @@
+# SOURCES.md - Flight Management Engineer
+
+Standards and documents this role references. Summary-not-copy: see
+[STANDARDS.md](../../STANDARDS.md) for the full rule and purchase links.
+
+| Source | Role use | Gated |
+|---|---|---|
+| RTCA DO-236C | RNAV/RNP system and FMS functional requirements, RNP containment and alerting concepts (95% containment basis) | true |
+| RTCA DO-283A | RNP AR procedure design criteria (RF leg context) | true |
+| FAA AC 90-105A | public approval guidance for RNP operations and baro-VNAV in the U.S. NAS, oceanic and remote airspace | false |
+| FAA AC 90-101A | public approval guidance for RNP AR procedures (RF legs, containment) | false |
+| FAA AIM / Instrument Flying Handbook | holding pattern entry sectors and timing (operational procedure, paraphrased) | false |
+| 14 CFR Part 25 | airworthiness context for the FMS procedure function | false |
+| ICAO Doc 9613 (PBN Manual) | performance-based navigation framework (reference only) | true |
+
+Acquisition status: DO-236C/DO-283A are purchased RTCA documents -
+referenced summary-only, never quoted. AC 90-105A, AC 90-101A, the AIM
+and 14 CFR Part 25 are public FAA documents (available from faa.gov);
+paraphrase preferred, short attributed quotes allowed.
+
+The role's numeric rules are public geometric/physical equations
+(spherical great-circle geometry, coordinated-turn radius
+V^2/(g tan(bank)), the 1-in-60 rule, ISA atmosphere) and the documented
+leaf models of the bound AeroSkills avionics/flight-management leaves:
+RNP containment (ANP = 2 x 1-sigma, 95% containment), the 70/110
+holding-entry sector rule, outbound leg timing (60 s at or below
+14000 ft, 90 s above), DME arc/radius-to-fix geometry, and the
+documented simplified mid-size-transport drag/fuel model (calibrate per
+aircraft against the FMS performance manual). No proprietary table or
+standard text is reproduced anywhere in this role.

package/roles/flight-management-engineer/cli.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""cli.py - run the Flight Management Engineer role.
+
+Usage:
+  python3 cli.py build [--out <file.md>] [--rnp-nm <nm>] [--sigma <m>]
+                       [--bundle] [--profile <p.json>]
+    # build the flight plan + RNAV/RNP route assessment for the example
+    # route; --rnp-nm / --sigma re-run the containment check with other
+    # facts; --bundle emits evidence/{model,gates,provenance}.json
+  python3 cli.py check --file <file.md>
+    # gate-check an existing assessment document
+
+The role ENGINE (core/flight_management_core.py) does the work standalone:
+route structure (great-circle/RF/DME-arc/rhumb geometry), RNP containment,
+holding entry, RTA speed control, VNAV profile, ECON performance, radio
+navaid checks, and the evidence gates. When AeroSkills is present
+(AEROSKILLS_DEV or ~/AeroSkills), the CLI dispatches the bound
+rnp-anp-containment and holding-pattern-entry leaf logic and cross-checks
+it against the core's computation - two independent implementations
+agreeing is recorded in provenance.json.
+"""
+import argparse
+import importlib.util
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                "core"))
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                "..", "..", "scripts"))
+import flight_management_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "flight-management-engineer"
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+_LEAF_PREFIX = os.path.join(AEROSKILLS, "skills", "avionics",
+                            "flight-management")
+
+
+def _load_leaf_logic(leaf, logic_name):
+    """Import a bound leaf's *logic.py if present; else None."""
+    path = os.path.join(_LEAF_PREFIX, leaf, "scripts", logic_name)
+    if not os.path.exists(path):
+        return None
+    spec = importlib.util.spec_from_file_location("aeroskills_" + leaf.replace("-", "_"),
+                                                  path)
+    mod = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(mod)
+        return mod
+    except Exception:
+        return None
+
+
+def _dispatch_crosschecks(model):
+    """Cross-check core numbers against the bound AeroSkills leaf logic.
+
+    Row 1: RNP containment margin (rnp-anp-containment leaf
+    margin_available_m vs core margin_available_m).
+    Row 2: holding entry lap time (holding-pattern-entry leaf
+    entry_lap_time_seconds vs core holding_entry_lap_seconds).
+    Rows are None when the skills checkout (or a leaf) is absent; the
+    role then simply ran standalone.
+    """
+    rows = []
+    rnp = model.get("rnp", {}).get("containment", {})
+    rnp_mod = _load_leaf_logic("rnp-anp-containment",
+                               "rnp_anp_containment_logic.py")
+    if rnp_mod is not None and rnp.get("anp_m") is not None:
+        try:
+            core_margin = core.margin_available_m(
+                rnp["anp_m"], rnp["rnp_m"], 0.0)
+            skill_margin = rnp_mod.margin_available_m(
+                anp_m=rnp["anp_m"], rnp_m=rnp["rnp_m"], margin_fraction=0.0)
+            delta = abs(core_margin - skill_margin)
+            rows.append({
+                "leaf": "avionics/flight-management/rnp-anp-containment",
+                "skill_md": "SKILL.md",
+                "logic_file": "scripts/rnp_anp_containment_logic.py",
+                "function": "margin_available_m",
+                "dispatched": True,
+                "cross_check_point": "ANP %.1f m vs RNP %.1f m, margin %.0f %%"
+                                     % (rnp["anp_m"], rnp["rnp_m"],
+                                        model["rnp"].get("rnp_margin_fraction",
+                                                         0.0) * 100),
+                "core_value": round(float(core_margin), 6),
+                "skill_value": round(float(skill_margin), 6),
+                "delta": round(delta, 9),
+                "agrees": delta <= 1e-6,
+                "tolerance": 1e-6,
+                "skills_release": "v1.3.0+",
+            })
+        except Exception as e:
+            rows.append({"leaf": "avionics/flight-management/"
+                                 "rnp-anp-containment",
+                         "dispatched": True, "error": str(e), "agrees": False})
+    hold = model.get("hold", {})
+    hold_mod = _load_leaf_logic("holding-pattern-entry",
+                                "holding_pattern_entry_logic.py")
+    if hold_mod is not None and hold.get("entry"):
+        try:
+            core_lap = core.holding_entry_lap_seconds(hold["entry"],
+                                                      hold["outbound_leg_s"])
+            skill_lap = hold_mod.entry_lap_time_seconds(hold["entry"],
+                                                        hold["outbound_leg_s"])
+            delta = abs(core_lap - skill_lap)
+            rows.append({
+                "leaf": "avionics/flight-management/holding-pattern-entry",
+                "skill_md": "SKILL.md",
+                "logic_file": "scripts/holding_pattern_entry_logic.py",
+                "function": "entry_lap_time_seconds",
+                "dispatched": True,
+                "cross_check_point": ("%s entry, %.0f s outbound leg"
+                                      % (hold["entry"], hold["outbound_leg_s"])),
+                "core_value": round(float(core_lap), 6),
+                "skill_value": round(float(skill_lap), 6),
+                "delta": round(delta, 9),
+                "agrees": delta <= 1e-6,
+                "tolerance": 1e-6,
+                "skills_release": "v1.3.0+",
+            })
+        except Exception as e:
+            rows.append({"leaf": "avionics/flight-management/"
+                                 "holding-pattern-entry",
+                         "dispatched": True, "error": str(e), "agrees": False})
+    return rows
+
+
+def _provenance(model, dispatch_rows):
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/flight_management_core.py",
+            "functions": ["containment_analysis", "hold_entry_analysis",
+                          "rf_leg_geometry", "rhumb_vs_great_circle",
+                          "dme_arc_geometry", "rta_speed_command",
+                          "vnav_tod_distance_nm", "perf_econ_summary"],
+            "version": "0.1.0",
+        },
+        "skills": dispatch_rows,
+        "cross_checked": bool(dispatch_rows),
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+def cmd_build(args):
+    item = core.example_item()
+    if args.rnp_nm:
+        item.rnp_nm = float(args.rnp_nm)
+    if args.sigma:
+        item.sigma_lateral_m = float(args.sigma)
+    model = core.build_report(item)
+    md = core.render_report_markdown(model)
+
+    # program profile (customer tailoring): load + apply context header
+    profile = None
+    try:
+        profile = evidence.load_profile(args.profile)
+    except ValueError as e:
+        print("error: bad profile: %s" % e)
+        return 1
+    if profile:
+        model["profile"] = {
+            "customer": profile.get("customer"),
+            "program": profile.get("program"),
+            "basis": profile.get("basis"),
+            "authority": profile.get("authority"),
+            "der": profile.get("der"),
+            "document_prefix": profile.get("document_prefix"),
+            "revision": profile.get("revision"),
+        }
+        md = evidence.profile_header_block(profile) + md
+
+    gates = core.check_report(model)
+    dispatch_rows = [] if args.no_dispatch else _dispatch_crosschecks(model)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md if md.endswith("\n") else md + "\n")
+        print("built flight plan + RNAV/RNP route assessment -> %s" % args.out)
+        print("route: %s" % model["route_id"])
+        print("total distance: %.2f NM | RNP %.1f | containment: %s | "
+              "hold entry: %s | RTA: %s"
+              % (model["total_distance_nm"], model["rnp"]["rnp_nm"],
+                 model["rnp"]["containment"]["verdict"], model["hold"]["entry"],
+                 model["rta"]["verdict"]))
+        print("gates: all_pass=%s %s" % (gates["all_pass"], gates))
+        if args.bundle:
+            prov = _provenance(model, dispatch_rows)
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG,
+                "flight plan and RNAV/RNP route assessment",
+                model, gates, prov)
+            print("bundle: model=%s" % paths["model"])
+            print("        gates=%s" % paths["gates"])
+            print("        provenance=%s" % paths["provenance"])
+            if dispatch_rows:
+                for row in dispatch_rows:
+                    if "error" in row:
+                        print("cross-check: %s error: %s"
+                              % (row["leaf"], row["error"]))
+                    else:
+                        print("cross-check: %s core=%.6f skill=%.6f "
+                              "delta=%.9f agrees=%s"
+                              % (row["leaf"], row["core_value"],
+                                 row["skill_value"], row["delta"],
+                                 row["agrees"]))
+            else:
+                print("cross-check: not dispatched (no AeroSkills logic)")
+    else:
+        print(md)
+    return 0 if gates["all_pass"] else 1
+
+
+def cmd_check(args):
+    if not os.path.exists(args.file):
+        print("file not found: %s" % args.file)
+        return 1
+    md = open(args.file).read()
+    gates = core.check_report_markdown(md)
+    for name, ok in gates.items():
+        if name != "all_pass":
+            print("%s  %s" % ("PASS" if ok else "FAIL", name))
+    print("RESULT: %s" % ("PASS" if gates["all_pass"] else "FAIL"))
+    return 0 if gates["all_pass"] else 1
+
+
+def main():
+    p = argparse.ArgumentParser(
+        description="Flight Management Engineer role")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    b = sub.add_parser("build")
+    b.add_argument("--out", default="",
+                   help="output file (default: stdout)")
+    b.add_argument("--rnp-nm", default="",
+                   help="RNP for the segment in NM (default: example 0.3)")
+    b.add_argument("--sigma", default="",
+                   help="1-sigma lateral position error in m (default: example)")
+    b.add_argument("--bundle", action="store_true",
+                   help="emit evidence/{model,gates,provenance}.json")
+    b.add_argument("--no-dispatch", action="store_true",
+                   help="skip dispatching bound AeroSkills logic")
+    b.add_argument("--profile", default="",
+                   help="program profile JSON (customer tailoring, "
+                        "docs/PROFILE-SCHEMA.md)")
+    b.set_defaults(fn=cmd_build)
+
+    c = sub.add_parser("check")
+    c.add_argument("--file", required=True,
+                   help="route assessment markdown to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()