aero-agent-roles 1.0.0

package/roles/structures-loads-engineer/ROLE.md

@@ -0,0 +1,171 @@
+---
+type: role
+name: structures-loads-engineer
+title: "Structures and Loads Engineer"
+status: draft
+domain: structures
+deliverable_type: "loads + strength/stability analysis report"
+standards_bound:
+  - id: far-25
+    tier: TIER-1
+    reference-only: false
+  - id: mmpsd
+    tier: TIER-2
+    reference-only: true
+skills_bound:
+  - structures/loads/gust-maneuver-loads
+  - structures/loads/landing-ground-loads
+  - structures/loads/random-vibration-analysis
+  - structures/loads/shock-response-spectrum
+  - structures/fem/beam-frame-analysis
+  - structures/fem/truss-analysis
+  - structures/fem/calculix-linear
+  - structures/fem/calculix-nonlinear
+  - structures/fem/buckling-analysis
+  - structures/fem/plate-buckling
+  - structures/fem/cylindrical-shell-buckling
+  - structures/fem/modal-analysis
+  - structures/fem/beam-vibration
+  - structures/fem/lug-joint-analysis
+  - structures/fem/contact-analysis
+  - structures/fem/pressure-bulkhead
+  - structures/materials/material-selection
+  - structures/materials/mmpsd-allowables
+  - structures/materials/ramberg-osgood
+  - structures/materials/creep-rupture
+  - structures/materials/fracture-toughness
+  - structures/fatigue/goodman-diagram
+  - structures/fatigue/stress-life-curve
+  - structures/fatigue/strain-life-fatigue
+  - structures/fatigue/miner-damage
+  - structures/fatigue/notch-sensitivity
+  - structures/fatigue/load-spectrum-counting
+  - structures/damage-tolerance/crack-growth
+  - structures/damage-tolerance/residual-strength
+  - structures/damage-tolerance/bird-strike
+  - structures/damage-tolerance/widespread-fatigue-damage
+  - structures/composites/laminate-stiffness
+  - structures/composites/laminate-first-ply-failure
+  - structures/composites/failure-criteria
+  - structures/composites/sandwich-panels
+  - structures/composites/composite-repair
+  - structures/thermal-structures/thermal-stress-analysis
+  - structures/thermal-structures/thermal-buckling
+tools_allowed: [stdlib, offline-file-processing, calculix-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+"
+---
+
+# Structures and Loads Engineer
+
+## Role identity
+
+Owns structural loads and strength/stability analysis: derive design
+loads (gust, maneuver, landing, ground), build the internal load path
+(FEM), check strength/stability against allowables, assess fatigue and
+damage tolerance, and screen composite/thermal behavior. Use when a
+structure must show margin against its limit/ultimate loads. Do NOT use
+for aerodynamic shape (aero role) or certification plan workflow.
+
+## Deliverable contract
+
+1. **Loads + strength report** - limit/ultimate loads, V-n envelope,
+   FEM stress results, margins of safety per critical component,
+   fatigue life, damage tolerance conclusions, composite/thermal notes.
+2. **Analysis evidence set** - the models, load cases, and allowable
+   sources behind every margin.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Design loads | gust-maneuver-loads + landing-ground-loads + random-vibration-analysis + shock-response-spectrum | V-n envelope, limit loads, spectra |
+| 2. Global FEM | beam-frame-analysis + truss-analysis + calculix-linear | internal loads, deflections |
+| 3. Nonlinear/buckling | calculix-nonlinear + buckling-analysis + plate-buckling + cylindrical-shell-buckling | stability margins |
+| 4. Detail joints | lug-joint-analysis + contact-analysis + pressure-bulkhead | joint/bulkhead margins |
+| 5. Dynamics | modal-analysis + beam-vibration | natural frequencies, dynamic response |
+| 6. Materials | material-selection + mmpsd-allowables + ramberg-osgood + creep-rupture + fracture-toughness | allowables (Ftu/Fty/Fcy, fracture) |
+| 7. Fatigue | goodman-diagram + stress-life-curve + strain-life-fatigue + miner-damage + notch-sensitivity + load-spectrum-counting | fatigue life |
+| 8. Damage tolerance | crack-growth + residual-strength + bird-strike + widespread-fatigue-damage | inspection intervals, residual strength |
+| 9. Composites | laminate-stiffness + laminate-first-ply-failure + failure-criteria + sandwich-panels + composite-repair | composite margins |
+| 10. Thermal | thermal-stress-analysis + thermal-buckling | thermal stresses |
+| 11. Report | (all above) | the loads + strength report |
+
+## Evidence gates
+
+- Stage 1 done = limit loads from the envelope + spectra with FAR
+  context; units and load factors stated.
+- Stage 3 done = every compression-critical component has a buckling
+  margin; mesh/BC documented.
+- Stage 7 done = fatigue life stated with the S-N/Gaertner basis + Miner
+  sum.
+- FINAL = every margin of safety has a load, an allowable, and a source.
+
+## Boundary / forbidden
+
+- NEVER claim certification approval or declare compliance findings.
+- Allowables: use MMPDS values with citation or a stated test basis;
+  never invent allowables.
+- FEM results are as-good-as-the-model; state idealizations.
+- Output is a DRAFT for human stress-lead review - mark it draft; the
+  report is not an approval document and never claims certification
+  approval or a compliance finding.
+
+## Verification
+
+The role runs STANDALONE: `core/structures_loads_core.py` is an
+executable engine that derives the FAR 25 gust + maneuver envelope
+(FAR 25.341/25.337), converts the design limit condition to ultimate
+loads (FAR 25.303), resolves root internal loads, computes margins of
+safety per critical component from real allowables, runs the fatigue
+screening (S-N basis + Miner sum) and the first-bending-frequency
+check, BUILDS the loads + strength report, and gate-checks
+deliverables. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out report.md                  # example wing report
+python3 cli.py build --out report.md --bundle         # + evidence bundle
+python3 cli.py build --category commuter --weight 18000  # other wing classes
+python3 cli.py check --file report.md                 # gate-check a report
+```
+
+Evidence protocol (docs/PROTOCOL.md): `--bundle` emits
+`evidence/{model.json, gates.json, provenance.json}` next to the
+deliverable — the computed model, gate verdicts, and provenance (which
+core function + which bound skill leaf produced each number). When
+AeroSkills is present, the CLI dispatches the bound gust-maneuver-loads
+logic and cross-checks its VC discrete-gust load factor against the
+core's: two independent implementations agreeing (delta 0) is recorded
+in provenance.json. Any harness can consume the bundle programmatically.
+
+Tests:
+- tests/test_structures_loads_core.py (24 tests): domain rules (gust
+  alleviation, maneuver limits, Euler/plate/lug/fatigue anchors),
+  report builder, evidence gates, standalone (no skills repo).
+- tests/test_bundle_protocol.py (6 tests): bundle emits 3 files, model
+  numbers + status, gates all_pass, dispatch cross-check agrees (when
+  skills present), standalone honest (cross_checked=false).
+- tests/test_role_structures_loads_engineer.py: bound-skill
+  resolution (skips if the skills repo is absent), workflow order,
+  filled template present, boundaries.
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (FEM runs, spectra counting, detail joints); the
+core engine does not depend on them. The filled deliverable template
+(templates/loads-strength-report-template.md) is the generated worked
+example for the example wing - zero blanks.
+
+## Compliance
+
+- far-25 TIER-1; mmpsd TIER-2 reference-only (never reproduce tables).
+- SOURCES.md records standards referenced.

package/roles/structures-loads-engineer/SOURCES.md

@@ -0,0 +1,44 @@
+# SOURCES.md - Structures and Loads Engineer
+
+| Source | Role use | Gated |
+|---|---|---|
+| 14 CFR Part 25 (subpart C/D) | loads and structure requirements | false |
+| 14 CFR 25.341 / 25.337 / 25.303 | discrete gust load factor, alleviation factor, limit maneuvering load factor n = max(2.5, min(3.8, 2.1 + 24000/(W+10000))), 1.5 factor of safety | false |
+| MMPDS | metallic allowables (licensed; never reproduced - screening values cited from bound leaf anchors with basis) | true |
+| CMH-17 | composite allowables (licensed) | true |
+| Bruhn, Analysis and Design of Flight Vehicle Structures | analysis methods (book); elliptic span-load / box-beam idealizations | true |
+| Niu, Airframe Structural Design | airframe methods (book) | true |
+| CalculiX documentation | FEM tooling | false |
+
+Summary-not-copy per STANDARDS.md. Allowables cited with source, never
+reproduced.
+
+## Domain-rule provenance (core/structures_loads_core.py)
+
+Every computation in the executable core mirrors a REAL rule from the
+bound AeroSkills leaves or a quotable public regulation:
+
+- Gust envelope, K_g, mass ratio, V-n diagram, gust-critical margins:
+  bound leaf structures/loads/gust-maneuver-loads (gust_load_logic.py)
+  and FAR 25.341 / 25.337 / 25.333.
+- Landing reactions, braked-roll deceleration: bound leaf
+  structures/loads/landing-ground-loads (level-landing statics, limit
+  vertical inertia factor 2.5 default).
+- Euler column + yield transition (lambda_1), plate buckling (k=4 ssss
+  long plate; k_s shear coefficient): bound leaves
+  structures/fem/buckling-analysis and structures/fem/plate-buckling.
+- Lug bearing / net-section / tearout margins, governing mode: bound
+  leaf structures/fem/lug-joint-analysis (worked example reproduced:
+  7075-T6 Ftu 572 / Fsu 331 / Fbru 1050 MPa -> margins +1.800 / +1.135
+  / +0.926, tearout governs).
+- Fatigue: Basquin S-N (bound stress-life-curve leaf), modified Goodman
+  mean correction (bound goodman-diagram leaf), Palmgren-Miner damage
+  sum (bound miner-damage leaf); 7075-T6 class fatigue constants
+  (sigma_f' ~ 690 MPa, b = -0.10) from the bound strain-life leaf
+  (representative typical, reference-only).
+- First wing bending frequency: bound leaf
+  structures/fem/beam-vibration (cantilever root beta1*L = 1.8751).
+
+Example wing geometry (reference item) is a self-consistent candidate
+design; all margins of safety in the filled template are computed, not
+stated.

package/roles/structures-loads-engineer/cli.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""cli.py - run the Structures and Loads Engineer role.
+
+Usage:
+  python3 cli.py build [--out <file.md>] [--category <normal|commuter|transport>]
+                       [--weight <lb>] [--bundle] [--no-dispatch]
+    # build the loads + strength report
+    # --bundle      also emit evidence/{model,gates,provenance}.json (PROTOCOL.md)
+    # --no-dispatch skip dispatching bound AeroSkills logic for cross-check
+  python3 cli.py check --file <file.md>   # gate-check an existing report
+
+The role ENGINE (core/structures_loads_core.py) does the work standalone:
+FAR 25 gust/maneuver envelope, limit/ultimate loads, root internal loads,
+margins of safety per critical component, fatigue screening with the
+S-N basis and Miner sum, dynamics, and the evidence gates. When
+AeroSkills is present (AEROSKILLS_DEV or ~/AeroSkills), the CLI
+dispatches the bound gust-maneuver-loads leaf logic and cross-checks its
+gust load factor against the core's — two independent implementations
+agreeing is recorded in provenance.json.
+"""
+import argparse
+import importlib.util
+import json
+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 structures_loads_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+GUST_LEAF = os.path.join(AEROSKILLS, "skills", "structures", "loads",
+                         "gust-maneuver-loads", "scripts", "gust_load_logic.py")
+
+ROLE_SLUG = "structures-loads-engineer"
+
+
+def _load_gust_logic():
+    """Import the bound AeroSkills gust logic if present."""
+    if not os.path.exists(GUST_LEAF):
+        return None
+    spec = importlib.util.spec_from_file_location("aeroskills_gust", GUST_LEAF)
+    mod = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(mod)
+        return mod
+    except Exception:
+        return None
+
+
+def _dispatch_crosscheck(item, model):
+    """Run the bound skill's gust logic and compare with the core value.
+
+    Cross-check point: VC discrete-gust load factor. The vn model stores
+    speeds in ft/s EAS and per-region design gust velocities (FAR
+    25.341: 66 fps VB/VC boundary, 50 fps VC, 25 fps VD). Both the core
+    and the AeroSkills leaf implement the same formula:
+      n = 1 + (rho0 * V_e * a * K_g * U_de) / (2 * W/S)
+    Returns a provenance 'skills' row (or None when dispatch unavailable).
+    """
+    gust = _load_gust_logic()
+    vn = model.get("vn", {})
+    ws = vn.get("ws")
+    cbar = vn.get("cbar_ft")
+    a = vn.get("a")
+    vc_fps = vn.get("vc")          # ft/s EAS
+    u_de = vn.get("gust_velocities", {}).get("vc", 50.0)
+    if not (gust and ws and cbar and a and vc_fps):
+        return None
+    try:
+        core_kg = core.gust_alleviation_factor(ws, cbar, a)
+        skill_kg = gust.gust_alleviation_factor(ws, cbar, a, rho=core.RHO0)
+        core_n = core.gust_load_factor(vc_fps, ws, a, u_de, kg=core_kg)
+        skill_n = gust.gust_load_factor(vc_fps, ws, a, u_de, kg=skill_kg)
+        delta = abs(core_n - skill_n)
+        return {
+            "leaf": "structures/loads/gust-maneuver-loads",
+            "skill_md": "SKILL.md",
+            "logic_file": "scripts/gust_load_logic.py",
+            "function": "gust_load_factor",
+            "dispatched": True,
+            "cross_check_point": "VC discrete gust, U_de=%.0f fps EAS" % u_de,
+            "core_value": round(core_n, 6),
+            "skill_value": round(skill_n, 6),
+            "delta": round(delta, 9),
+            "agrees": delta <= 1e-6,
+            "tolerance": 1e-6,
+            "skills_release": "v1.3.0+",
+        }
+    except Exception as e:
+        return {"leaf": "structures/loads/gust-maneuver-loads",
+                "dispatched": True, "error": str(e), "agrees": False}
+
+
+def _provenance(item, model, dispatch_row):
+    vn = model.get("vn", {})
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/structures_loads_core.py",
+            "functions": ["gust_load_factor", "vn_diagram",
+                          "margin_of_safety", "cumulative_damage"],
+            "version": "0.1.0",
+        },
+        "skills": [dispatch_row] if dispatch_row else [],
+        "cross_checked": bool(dispatch_row and dispatch_row.get("dispatched")
+                              and not dispatch_row.get("error")),
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+def cmd_build(args):
+    item = core.example_item()
+    if args.category:
+        item.category = args.category
+    if args.weight:
+        item.resize_for_weight(float(args.weight))
+    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(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(model)
+
+    dispatch_row = None
+    if not args.no_dispatch:
+        dispatch_row = _dispatch_crosscheck(item, model)
+
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md if md.endswith("\n") else md + "\n")
+        print("built loads + strength report -> %s" % args.out)
+        print("design limit: %s, n_limit=%.2f, n_ult=%.2f"
+              % (model["loads_condition"], model["n_limit"], model["n_ult"]))
+        print("gates: all_pass=%s %s" % (gates["all_pass"], gates))
+        if args.bundle:
+            prov = _provenance(item, model, dispatch_row)
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG,
+                "loads + strength report", model, gates, prov)
+            print("bundle: model=%s" % paths["model"])
+            print("        gates=%s" % paths["gates"])
+            print("        provenance=%s" % paths["provenance"])
+            if dispatch_row:
+                print("cross-check: core=%.6f skill=%.6f delta=%.9f agrees=%s"
+                      % (dispatch_row["core_value"],
+                         dispatch_row["skill_value"],
+                         dispatch_row["delta"], dispatch_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="Structures and Loads 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("--category", default="",
+                   help="normal/commuter/transport (default: example)")
+    b.add_argument("--weight", default="",
+                   help="gross weight in lb to re-size the example wing")
+    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="loads + strength report markdown to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()