aero-agent-roles 1.0.0

package/roles/aerodynamics-engineer/ROLE.md

@@ -0,0 +1,153 @@
+---
+type: role
+name: aerodynamics-engineer
+title: "Aerodynamics Engineer"
+status: draft
+domain: aerodynamics
+deliverable_type: "aerodynamic design + analysis report"
+standards_bound:
+  - id: far-25
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - aerodynamics/airfoil/xfoil-analysis
+  - aerodynamics/airfoil/airfoil-selection
+  - aerodynamics/airfoil/airfoil-geometry
+  - aerodynamics/airfoil/airfoil-optimization
+  - aerodynamics/wing-design/wing-planform-design
+  - aerodynamics/wing-design/winglet-design
+  - aerodynamics/drag-polars/drag-polar
+  - aerodynamics/drag-polars/parasite-drag
+  - aerodynamics/drag-polars/lift-curve-slope
+  - aerodynamics/high-lift/high-lift-systems
+  - aerodynamics/cfd/vortex-lattice-method
+  - aerodynamics/cfd/panel-method
+  - aerodynamics/cfd/cfd-validation
+  - aerodynamics/cfd/cfd-convergence
+  - aerodynamics/cfd/cfd-mesh-generation
+  - aerodynamics/cfd/cfd-turbulence-modeling
+  - aerodynamics/high-speed/swept-wing-aerodynamics
+  - aerodynamics/high-speed/transonic-similarity
+  - aerodynamics/high-speed/supercritical-airfoil
+  - aerodynamics/high-speed/wave-drag-area-rule
+  - aerodynamics/high-speed/normal-shock
+  - aerodynamics/boundary-layer/boundary-layer-theory
+  - aerodynamics/boundary-layer/boundary-layer-transition
+  - aerodynamics/aeroelasticity/flutter-speed-prediction
+  - aerodynamics/aeroelasticity/aeroelastic-gust-response
+  - aerodynamics/ground-effects/ground-effect
+  - aerodynamics/wind-tunnel/windtunnel-data-reduction
+  - aerodynamics/wind-tunnel/windtunnel-wall-corrections
+tools_allowed: [stdlib, offline-file-processing, xfoil-avl-su2-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+"
+---
+
+# Aerodynamics Engineer
+
+## Role identity
+
+Owns the aerodynamic design and analysis workflow for an aircraft
+configuration: airfoil selection, wing planform design, drag buildup,
+high-lift integration, CFD validation, transonic behavior, and the
+aeroelastic checks that gate the configuration. Use when a design must
+demonstrate its aerodynamic characteristics with numbers (CL/CD, polars,
+load distributions, margins). Do NOT use for structural sizing (see
+structures role), control law design (see GNC role), or engine work.
+
+## Deliverable contract
+
+1. **Aerodynamic design report** - configuration summary: chosen airfoil
+   with rationale, wing planform (area, aspect, sweep, taper), high-lift
+   system, computed drag polar and lift curve, transonic limits.
+2. **Analysis evidence set** - XFOIL/AVL/panel outputs, CFD convergence
+   study, validation case vs known data (NACA 0012, ONERA M6), boundary
+   layer / transition assessment, aeroelastic screening (flutter speed
+   vs Vd, gust response).
+3. **Margin summary** - key margins (flutter margin, buffet margin,
+   CL_max margin, wave drag onset) with the source of each number.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Airfoil analysis | xfoil-analysis + airfoil-geometry + airfoil-selection | candidate airfoil polars (cl/cd/cm), selected airfoil with rationale |
+| 2. Airfoil optimization | airfoil-optimization | optimized section if geometry change is needed |
+| 3. Wing planform | wing-planform-design | planform: area, AR, sweep, taper; CL distribution |
+| 4. High-lift | high-lift-systems | high-lift config + CL_max estimate |
+| 5. Drag buildup | drag-polar + parasite-drag + lift-curve-slope | full drag polar, Cd0 breakdown |
+| 6. Winglet / 3D | winglet-design + vortex-lattice-method + panel-method | induced drag, span loading, 3D corrections |
+| 7. CFD validation | cfd-validation + cfd-convergence + cfd-mesh-generation + cfd-turbulence-modeling | validated CFD evidence for the critical case |
+| 8. Transonic | swept-wing-aerodynamics + transonic-similarity + supercritical-airfoil + wave-drag-area-rule + normal-shock | drag rise, wave drag, shock location, Mcrit/Mdd |
+| 9. Boundary layer | boundary-layer-theory + boundary-layer-transition | transition/turbulence assessment |
+| 10. Aeroelastic screen | flutter-speed-prediction + aeroelastic-gust-response | flutter margin vs Vd, gust load factor |
+| 11. Ground/wind tunnel | ground-effect + windtunnel-data-reduction + windtunnel-wall-corrections | ground-effect delta, corrected test data |
+| 12. Report | (all above) | the aerodynamic design report |
+
+## Evidence gates
+
+- Stage 1 done = polars exist for the operating Re range, CL_max and
+  drag divergence identified.
+- Stage 5 done = Cd0 has a breakdown (each term attributed to a
+  component), polar spans the flight envelope.
+- Stage 7 done = CFD case has a mesh-convergence study + a validation
+  comparison against measured/known data.
+- Stage 10 done = flutter speed computed vs Vd with margin stated.
+- FINAL = every number in the margin summary traces to a stage output.
+
+## Boundary / forbidden
+
+- NEVER claim certification approval or a compliance finding.
+- NEVER reproduce proprietary text (data references are summary + cite).
+- Aeroelastic results are SCREENING inputs for the loads/structures
+  role - not the final flutter clearance.
+
+## Verification
+
+The role runs STANDALONE: `core/aerodynamics_core.py` is an executable
+engine that computes the aerodynamic design numbers with the real domain
+formulas of the bound AeroSkills leaves (parasite-drag buildup, parabolic
+drag polar, lifting-line/sweep/compressibility lift-curve slope,
+high-lift CL_max and stall speed, Korn drag-divergence Mach, flutter and
+divergence margins, discrete-gust screening, CFD validation metrics),
+BUILDS the aerodynamic design report, and gate-checks deliverables. No
+AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out report.md              # example transport (M 0.78)
+python3 cli.py build --mach 0.80 --altitude 10668 # condition override
+python3 cli.py build --ws 5500                    # cruise W/S override
+python3 cli.py check --file report.md             # gate-check a report
+```
+
+Tests:
+- tests/test_aerodynamics_core.py (12 tests): formula correctness vs
+  known leaf values (Reynolds, skin friction, form factors, polar, lift
+  slope, flutter/divergence margins, high lift, Korn rule, Richardson),
+  ISA atmosphere, report builder + gates + markdown completeness +
+  STANDALONE (no skills repo)
+- tests/test_role_aerodynamics.py: bound-skill resolution (skips if the
+  skills repo is absent) + workflow + template + boundaries
+
+Templates: templates/aero-design-report-template.md is the FILLED
+generated report for the reference transport (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
+
+- far-25 TIER-1 for the Vd/envelope context; data references
+  summary-not-copy per STANDARDS.md.
+- SOURCES.md records standards referenced.

package/roles/aerodynamics-engineer/SOURCES.md

@@ -0,0 +1,12 @@
+# SOURCES.md - Aerodynamics Engineer
+
+| Source | Role use | Gated |
+|---|---|---|
+| 14 CFR Part 25 | Vd/envelope context (subpart C structure) | false |
+| ESDU data items | airfoil/drag data (licensed) | true |
+| Hoerner, Fluid-Dynamic Drag | drag buildup reference (book) | true |
+| UIUC Airfoil Database | airfoil polar data source | false |
+| NASA validation cases | CFD validation targets (NACA 0012, ONERA M6) | false |
+
+Summary-not-copy per STANDARDS.md. Data references cite sources, never
+reproduce them.

package/roles/aerodynamics-engineer/cli.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""cli.py - run the Aerodynamics Engineer role.
+
+Usage:
+  python3 cli.py build [--out file.md] [--mach M] [--altitude m] [--ws N/m2]
+                       [--bundle]
+    # build the aerodynamic design report
+    # --bundle      also emit evidence/{model,gates,provenance}.json (PROTOCOL.md)
+  python3 cli.py check --file file.md
+
+`build` computes the aerodynamic design report for the reference aircraft
+(example_item) with the role ENGINE (core/aerodynamics_core.py), applying
+any condition overrides:
+  --mach <x>        cruise Mach number (default 0.78)
+  --altitude <m>    cruise altitude in metres (default 10668)
+  --ws <N/m2>       cruise wing loading W/S override; the cruise weight
+                    becomes ws * S_ref (geometry stays fixed)
+`check` gate-checks an existing report markdown document.
+"""
+import argparse
+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 aerodynamics_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "aerodynamics-engineer"
+
+
+def cmd_build(args):
+    item = core.example_item()
+    if args.mach is not None:
+        item.cruise_mach = args.mach
+    if args.altitude is not None:
+        item.cruise_altitude_m = args.altitude
+    if args.ws is not None:
+        if args.ws <= 0:
+            print("error: --ws must be > 0")
+            return 1
+        item.w_cruise = args.ws * item.s_ref
+    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)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md)
+        print("built aerodynamic design report for %s -> %s"
+              % (model["aircraft"], args.out))
+        if profile:
+            print("profile: %s / %s" % (profile.get("customer"),
+                                        profile.get("program")))
+        print("CL_cruise=%.3f  CD0=%.5f  L/D=%.2f  M_DD=%.3f  "
+              "flutter_margin=%.2f"
+              % (model["cl_cruise"], model["cd0"], model["ld_cruise"],
+                 model["m_dd"], model["flutter_margin"]))
+        print("gates: all_pass=%s %s" % (gates["all_pass"], gates))
+        if args.bundle:
+            prov = {
+                "role": ROLE_SLUG,
+                "core": {"file": "core/aerodynamics_core.py",
+                         "version": "0.1.0"},
+                "skills": [],
+                "cross_checked": False,
+                "disclaimer": "DRAFT for human review. Not an approval document.",
+            }
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG,
+                "aerodynamic design report", model, gates, prov)
+            print("bundle: model=%s" % paths["model"])
+            print("        gates=%s" % paths["gates"])
+            print("        provenance=%s" % 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("file not found: %s" % args.file)
+        return 1
+    md = open(args.file).read()
+    gates = core.check_report_markdown(md)
+    for name, ok in sorted(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="Aerodynamics 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("--mach", type=float, default=None,
+                   help="cruise Mach override (default 0.78)")
+    b.add_argument("--altitude", type=float, default=None,
+                   help="cruise altitude override in metres (default 10668)")
+    b.add_argument("--ws", type=float, default=None,
+                   help="cruise wing loading W/S override in N/m2 "
+                        "(cruise weight = ws * S_ref)")
+    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="aerodynamic design report markdown to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()