aero-agent-roles 1.0.0

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

@@ -0,0 +1,162 @@
+---
+type: role
+name: flight-mechanics-engineer
+title: "Flight Mechanics Engineer"
+status: draft
+domain: flight-mechanics
+deliverable_type: "performance + stability and control analysis report"
+standards_bound:
+  - id: far-25
+    tier: TIER-1
+    reference-only: false
+  - id: mil-std-1797a
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - flight-mechanics/performance/breguet-range
+  - flight-mechanics/performance/breguet-endurance
+  - flight-mechanics/performance/specific-range
+  - flight-mechanics/performance/climb-performance
+  - flight-mechanics/performance/descent-performance
+  - flight-mechanics/performance/glide-performance
+  - flight-mechanics/performance/takeoff-performance
+  - flight-mechanics/performance/landing-performance
+  - flight-mechanics/performance/turn-performance
+  - flight-mechanics/performance/thrust-required
+  - flight-mechanics/performance/oei-climb-gradient
+  - flight-mechanics/performance/energy-height
+  - flight-mechanics/performance/speed-stability
+  - flight-mechanics/performance/wind-effects
+  - flight-mechanics/performance/windshear-analysis
+  - flight-mechanics/performance/rotorcraft-hover-performance
+  - flight-mechanics/performance/rotorcraft-forward-flight-performance
+  - flight-mechanics/performance/rotorcraft-blade-element-hover-performance
+  - flight-mechanics/performance/rotorcraft-autorotative-descent
+  - flight-mechanics/performance/rotorcraft-tail-rotor-sizing
+  - flight-mechanics/performance/rotorcraft-vertical-climb-performance
+  - flight-mechanics/stability-control/longitudinal-stability
+  - flight-mechanics/stability-control/lateral-directional-stability
+  - flight-mechanics/stability-control/dynamic-stability
+  - flight-mechanics/stability-control/short-period-mode-analysis
+  - flight-mechanics/stability-control/phugoid-mode-analysis
+  - flight-mechanics/stability-control/trim-analysis
+  - flight-mechanics/stability-control/stability-derivatives-avl
+  - flight-mechanics/stability-control/control-surface-effectiveness
+  - flight-mechanics/stability-control/aileron-reversal
+  - flight-mechanics/stability-control/deep-stall-analysis
+  - flight-mechanics/stability-control/spin-recovery
+  - flight-mechanics/handling-qualities/cooper-harper-rating
+  - flight-mechanics/handling-qualities/mil-std-1797a
+  - flight-mechanics/handling-qualities/pilot-induced-oscillation
+  - flight-mechanics/handling-qualities/pitch-bandwidth-criteria
+  - flight-mechanics/flight-dynamics-sim/point-mass-trajectory
+  - flight-mechanics/flight-dynamics-sim/six-dof-simulation
+tools_allowed: [stdlib, offline-file-processing, avl-cli, jsbsim-cli]
+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: Aero Agent Roles
+  skills_release: "v1.3.0+"
+---
+
+# Flight Mechanics Engineer
+
+## Role identity
+
+Owns aircraft performance and stability/control analysis: range,
+endurance, climb, takeoff/landing, turn, OEI gradients, static/dynamic
+stability, mode characteristics, handling qualities, and trajectory
+simulation (fixed-wing and rotorcraft). Use when a vehicle must show it
+can meet performance requirements and behave acceptably across the
+envelope. Do NOT use for control LAW design (GNC role), aero shape
+(aero role), or loads (structures role).
+
+## Deliverable contract
+
+1. **Performance + S&C report** - mission performance numbers, stability
+   derivatives, mode characteristics, handling qualities assessment,
+   trim conditions, and trajectory results. The worked example
+   (templates/perf-sc-report-template.md) is the complete generated
+   deliverable for the example transport: range, endurance, ROC,
+   takeoff/landing field, static margin, and short-period/phugoid/Dutch
+   roll mode numbers all computed from real domain rules with their
+   input basis stated.
+2. **Analysis evidence set** - the calculations, derivative builds, and
+   simulation runs behind the results (per-section equations and input
+   basis in the report; open items name the deeper bound-skill stages).
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Range/endurance | breguet-range + breguet-endurance + specific-range | range/endurance vs payload |
+| 2. Mission performance | climb-performance + descent-performance + glide-performance + takeoff-performance + landing-performance + turn-performance + thrust-required | segment performance |
+| 3. Safety performance | oei-climb-gradient + energy-height + speed-stability + wind-effects + windshear-analysis | OEI/climb margins |
+| 4. Rotorcraft performance | rotorcraft-hover-performance + rotorcraft-forward-flight-performance + rotorcraft-blade-element-hover-performance + rotorcraft-autorotative-descent + rotorcraft-tail-rotor-sizing + rotorcraft-vertical-climb-performance | rotorcraft numbers |
+| 5. Static stability | longitudinal-stability + lateral-directional-stability + trim-analysis + stability-derivatives-avl | static margins, derivatives |
+| 6. Dynamic stability | dynamic-stability + short-period-mode-analysis + phugoid-mode-analysis | mode frequencies/damping |
+| 7. Control effectiveness | control-surface-effectiveness + aileron-reversal + deep-stall-analysis + spin-recovery | control checks |
+| 8. Handling qualities | cooper-harper-rating + mil-std-1797a + pilot-induced-oscillation + pitch-bandwidth-criteria | HQR assessment |
+| 9. Simulation | point-mass-trajectory + six-dof-simulation | trajectory/6DOF runs |
+| 10. Report | (all above) | the performance + S&C report |
+
+## Evidence gates
+
+- Stage 1 done = range/endurance with the Breguet assumptions stated.
+- Stage 6 done = short-period/phugoid damping within MIL-STD/FAR
+  context or with a stated rationale.
+- FINAL = every result has a stated input basis (mass, CG, altitude);
+  the computed numbers are present (range, ROC, takeoff field, static
+  margin, mode damping) and the document is marked draft, not approval.
+  The core `check_*` functions verify all of this on the deliverable.
+
+## Boundary / forbidden
+
+- NEVER claim certification approval or compliance findings.
+- Handling qualities conclusions are assessments (HQR scale), not
+  certification findings.
+- Derivatives come from AVL or stated data; never invent stability data
+  without a source.
+- The rendered deliverable ALWAYS carries the DRAFT + human-review +
+  not-an-approval marker (enforced by the core renderer and gate checks).
+
+## Verification
+
+The role runs STANDALONE: `core/flight_mechanics_core.py` is an
+executable engine that encodes the domain rules from the bound
+flight-mechanics leaves (Breguet range/endurance, specific range,
+ROC/time-to-climb, takeoff/landing field estimates, static margin and
+neutral point, short period / phugoid / Dutch roll / spiral / roll
+modes, MIL-STD-1797A summary level bands), computes the example
+transport numbers, BUILDS the report, and gate-checks deliverables.
+No AeroSkills checkout required (`AEROSKILLS_DEV=/nonexistent` works).
+
+Run the role:
+```bash
+python3 cli.py build --out perf-sc-report.md   # build the example report
+python3 cli.py check --file perf-sc-report.md  # gate-check a report
+```
+
+Tests:
+- tests/test_flight_mechanics_core.py (34 tests): domain rules +
+  builder + gates + standalone (no skills repo)
+- tests/test_role_flight_mechanics_engineer.py: bound-skill resolution
+  (skips if the skills repo is absent) + workflow + filled template +
+  boundaries + core/cli presence
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (per the workflow table); the core engine does not
+depend on them.
+
+## Compliance
+
+- far-25 + mil-std-1797a TIER-1 context (quotable with citation);
+  standards-map summary only, no verbatim regulation text.
+- SOURCES.md records the standards and the bound leaves whose rules the
+  core encodes.

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

@@ -0,0 +1,51 @@
+# SOURCES.md - Flight Mechanics Engineer
+
+Summary-not-copy per STANDARDS.md. The core (core/flight_mechanics_core.py)
+encodes the equations of the bound AeroSkills leaves below (paraphrase of
+common flight-mechanics practice); every number in the generated report
+traces to one of these rules or to the stated example input basis.
+
+## Standards / regulations referenced (context, quotable with citation)
+
+| Source | Role use | Gated |
+|---|---|---|
+| 14 CFR Part 25 (FAR/CS 25.121, 25.125, 25.181) | minimum climb gradients; landing field length factor; dynamic stability context | true (gradients, landing factor, heavy-damping context) |
+| MIL-STD-1797A | flying qualities levels, mode criteria tables (summary paraphrase) | true (level bands used by the gates) |
+| MIL-F-8785C style level-1 bands (as summarized by the short-period leaf) | short-period damping/frequency bands | true |
+| ISA atmosphere (public standard model) | density/temperature/speed of sound at altitude | false |
+
+## Bound AeroSkills leaves whose rules the core encodes
+
+| Leaf (rule the core encodes) | Role use | Gated |
+|---|---|---|
+| flight-mechanics/performance/breguet-range | R = (V/(TSFC*g))*(L/D)*ln(m0/m1) | true |
+| flight-mechanics/performance/breguet-endurance | jet loiter endurance | true |
+| flight-mechanics/performance/specific-range | SAR = V*(L/D)/(TSFC*W) | false |
+| flight-mechanics/performance/climb-performance | ROC=(T-D)V/W; gradient; time to climb; service ceiling | true |
+| flight-mechanics/performance/takeoff-performance | Vs, V_LOF=1.2*Vs, ground roll | true |
+| flight-mechanics/performance/landing-performance | Vref=1.3*Vs, air distance, ground roll, 1.67 factor | true |
+| flight-mechanics/performance/glide-performance | glide ratio/angle/sink | false |
+| flight-mechanics/performance/turn-performance | n=1/cos(phi), rate, radius | false |
+| flight-mechanics/performance/oei-climb-gradient | T_oei derate; FAR 25.121 gradients | true |
+| flight-mechanics/performance/energy-height | h_e, kinetic height, Ps | false |
+| flight-mechanics/performance/wind-effects | wind triangle/groundspeed | false |
+| flight-mechanics/stability-control/longitudinal-stability | neutral point, static margin | true |
+| flight-mechanics/stability-control/dynamic-stability | short period/phugoid/lateral mode formulas, criteria | true |
+| flight-mechanics/stability-control/short-period-mode-analysis | SP frequency/damping, level bands | true |
+| flight-mechanics/stability-control/phugoid-mode-analysis | Lanchester phugoid characteristics | true |
+| flight-mechanics/stability-control/lateral-directional-stability | fin/dihedral derivative build, DR/roll/spiral | true |
+| flight-mechanics/stability-control/trim-analysis | CL_trim, elevator to trim | false |
+| flight-mechanics/handling-qualities/mil-std-1797a | category/class/level mode criteria tables | true |
+| flight-mechanics/handling-qualities/cooper-harper-rating | HQR decision tree (flight-test campaign) | false |
+
+## Reference books (method context for the derivative builds)
+
+| Source | Role use | Gated |
+|---|---|---|
+| Stevens & Lewis, Aircraft Control and Simulation | dynamics/derivative conventions | false |
+| Roskam, Airplane Flight Dynamics | S&C methods, class-range derivative data | false |
+
+Example-configuration data (mass, geometry, thrust, polar, derivative
+coefficients) are stated per-run inputs in the class range of a 150-seat
+twin-engine transport and are flagged in the report as open items pending
+project data and the AVL derivative build.

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""cli.py - run the Flight Mechanics Engineer role.
+
+Usage:
+  python3 cli.py build [--out <file.md>] [--bundle] [--profile <file.json>]
+    # build the Performance + S&C report for the example transport
+    # --bundle   also emit evidence/{model,gates,provenance}.json (PROTOCOL.md)
+    # --profile  program profile JSON for customer tailoring
+    #            (docs/PROFILE-SCHEMA.md) -> prepended context header
+  python3 cli.py check --file <file.md>    # gate-check an existing report
+
+The role ENGINE (core/flight_mechanics_core.py) does the work standalone
+(real domain rules -> real numbers); bound flight-mechanics skills in Aero
+Agent Skills deepen individual stages when present.
+"""
+import argparse
+import dataclasses
+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_mechanics_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "flight-mechanics-engineer"
+
+
+def _jsonable(obj):
+    """Recursively convert the content model to plain JSON types.
+
+    The model embeds the ExampleTransport configuration dataclass inside
+    results['aircraft']; the evidence bundle (PROTOCOL.md v1) requires
+    plain JSON that round-trips, so dataclass instances become dicts.
+    """
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return _jsonable(dataclasses.asdict(obj))
+    if isinstance(obj, dict):
+        return {k: _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    return obj
+
+
+def _provenance():
+    """Provenance for the bundle: role core, no skill dispatch in this
+    role yet (core ran standalone), same honesty boundary as the report."""
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/flight_mechanics_core.py",
+            "functions": ["analyze_vehicle", "build_report",
+                          "check_report", "render_report_markdown"],
+            "version": "0.1.0",
+        },
+        "skills": [],
+        "cross_checked": False,
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+def cmd_build(args):
+    results = core.analyze_vehicle(core.example_vehicle())
+    model = core.build_report(core.example_vehicle(), results)
+    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(f"error: bad profile: {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(results)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md)
+        print(f"built Performance + S&C report for {model['aircraft']} "
+              f"-> {args.out}")
+        if profile:
+            print(f"profile: {profile.get('customer')} / "
+                  f"{profile.get('program')}")
+        print(f"gates: all_pass={gates['all_pass']} {gates}")
+        if args.bundle:
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG, "Performance and S&C Analysis Report",
+                _jsonable(model), gates, _provenance())
+            print(f"bundle: model={paths['model']}")
+            print(f"        gates={paths['gates']}")
+            print(f"        provenance={paths['provenance']}")
+    else:
+        print(md)
+    return 0 if gates["all_pass"] else 1
+
+
+def cmd_check(args):
+    if not os.path.exists(args.file):
+        print(f"file not found: {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(f"{'PASS' if ok else 'FAIL'}  {name}")
+    print(f"RESULT: {'PASS' if gates['all_pass'] else 'FAIL'}")
+    return 0 if gates["all_pass"] else 1
+
+
+def main():
+    p = argparse.ArgumentParser(
+        description="Flight Mechanics Engineer role: performance + S&C "
+                    "analysis report")
+    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("--bundle", action="store_true",
+                   help="emit evidence/{model,gates,provenance}.json")
+    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="Performance + S&C report markdown to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()