aero-agent-roles 1.0.0

package/roles/do160-environmental-engineer/ROLE.md

@@ -0,0 +1,136 @@
+---
+type: role
+name: do160-environmental-engineer
+title: "DO-160G Environmental Qualification Engineer"
+status: draft
+domain: avionics
+deliverable_type: "equipment environmental qualification plan/report"
+standards_bound:
+  - id: do-160
+    tier: TIER-2
+    reference-only: true
+skills_bound:
+  - avionics/do160/environmental-qualification
+  - avionics/do160/lightning-protection
+  - avionics/do160/electrostatic-discharge
+  - avionics/do160/power-input
+  - avionics/do160/radio-frequency-susceptibility
+  - avionics/do160/radio-frequency-emissions
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "issue qualification approval"
+  - "claim regulatory sign-off"
+  - "reproduce proprietary RTCA/EUROCAE text"
+  - "assert test levels or limit tables without the current revision"
+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+"
+---
+
+# DO-160G Environmental Qualification Engineer
+
+## Role identity
+
+This role drives the RTCA DO-160G / EUROCAE ED-14G environmental
+qualification workflow for an airborne equipment item (an LRU): from
+installation-driven category selection through the test-condition
+matrix, ESD and lightning test parameters, power-input quality
+margins, RF susceptibility calibration budgets, RF emission margins,
+and the artifacts that support the Equipment Environmental
+Qualification Plan/Report. Use when a project must qualify an LRU
+against DO-160 environmental test conditions. Do NOT use for software
+certification (see DO-178C role), system safety / certification
+planning (see airworthiness role), or when no environmental test basis
+exists.
+
+## Deliverable contract
+
+The role produces:
+
+1. **Equipment Environmental Qualification Plan/Report** — original
+   skeleton per templates/environmental-qualification-plan-template.md:
+   scope and item identification, environmental categories per
+   installation, the DO-160 test-condition matrix with completeness
+   check, ESD Section 25 test parameters (15 kV air discharge,
+   generator model, waveform currents), lightning Sections 22/23 test
+   level and waveform selection, power input Section 16 margins, RF
+   susceptibility Section 20 amplifier/calibration budget, RF emission
+   Section 21 margins and verdicts.
+2. **Verdict summary** — per-domain pass/fail from the leaf logic
+   criteria (no damage/upset/latch-up, within-band margins, emission
+   margins >= 0 dB).
+3. **Gap report** — open items before the human environmental
+   qualification engineer signs.
+
+## Workflow (stages → bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Environmental scope | avionics/do160/environmental-qualification | equipment category, test-condition section matrix, completeness check |
+| 2. Lightning plan | avionics/do160/lightning-protection | Section 22 level (1-5) + waveform set (A-H), 22/23 pass criteria |
+| 3. ESD levels | avionics/do160/electrostatic-discharge | Section 25 category A, 15 kV air discharge, discharge waveform currents |
+| 4. Power input quality | avionics/do160/power-input | Section 16 steady-state/sag/surge/frequency margins, ripple, emergency classification |
+| 5. RF immunity | avionics/do160/radio-frequency-susceptibility | RS103 field + amplifier budget, CS114 limits and margins |
+| 6. RF emissions | avionics/do160/radio-frequency-emissions | RE102/CE102 margins, worst case frequency, emission verdicts |
+
+## Evidence gates
+
+- Stage 1 done = temperature category selected WITH the location's
+  expected extremes inside the category typical range, matrix has no
+  missing required section.
+- Stage 3 done = ESD plan uses category A, 15 kV air discharge, 10
+  positive / 10 negative discharges per test point.
+- Stage 4 done = steady-state voltage within the normal band with
+  margins; transient envelope and recovery checked.
+- FINAL = every section of the deliverable has a source (skill + DO-160
+  section reference); nothing asserted without a checkable basis; all
+  verdicts pass before the report is submitted.
+
+## Boundary / forbidden
+
+- NEVER issue qualification approval — the design approval holder /
+  regulator signs.
+- NEVER reproduce DO-160G text or limit tables (proprietary,
+  RTCA/EUROCAE). Summaries, typical reference data, and original
+  structure only; verify every level/waveform/limit value against the
+  current revision before freezing a plan.
+- NEVER assert a category, level, or verdict without the underlying
+  computation trail (this report's model + gates).
+- Output is a DRAFT for human review — mark it draft.
+
+## Verification
+
+The role runs STANDALONE: `core/do160_environmental_core.py` is an
+executable engine that selects the temperature category from expected
+extremes, builds the full test-condition matrix, computes ESD
+parameters, lightning verdicts, power-input margins, RF amplifier
+budgets and emission margins, BUILDS the qualification report, and
+gate-checks deliverables. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out eqpr.md                     # example LRU
+python3 cli.py build --out eqpr.md --bundle            # + evidence JSON
+python3 cli.py build --out eqpr.md --profile ../profiles/example-airframer.json
+python3 cli.py check --file eqpr.md --category B1      # gate-check
+```
+
+Tests:
+- tests/test_do160_environmental_core.py: domain rules + report
+  builder + gates + standalone (no skills repo)
+- tests/test_role_do160_environmental_engineer.py: bound-skill
+  resolution (skips if the skills repo is absent) + workflow +
+  template present + boundaries
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (environmental scope, lightning, ESD, power input,
+RF immunity/emissions); the core engine does not depend on them.
+
+## Compliance
+
+- do-160 TIER-2 reference-only per standards-map; no verbatim.
+- SOURCES.md records acquisition/extraction/verification status.

package/roles/do160-environmental-engineer/SOURCES.md

@@ -0,0 +1,30 @@
+# SOURCES.md - DO-160G Environmental Qualification 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-160G / EUROCAE ED-14G | environmental test conditions and procedures for airborne equipment (sections 4-11, 16, 19-25); category and level selection | true |
+| IEC 61000-4-2 | electrostatic discharge human-body model (150 pF / 330 ohm) referenced by DO-160 Section 25 practice | true |
+
+## Grounding notes
+
+- The role's executable core mirrors the domain rules encoded in the
+  bound AeroSkills leaves under `avionics/do160/`
+  (environmental-qualification, lightning-protection,
+  electrostatic-discharge, power-input, radio-frequency-susceptibility,
+  radio-frequency-emissions), which encode summary reference practice
+  only. Their `scripts/*_logic.py` files are the arithmetic contracts
+  the core mirrors; every worked anchor (15 kV air discharge, 56.25 A
+  first peak, 49.5 ns RC constant, 25% sag / 15% surge anchors, CS114
+  10 dBuA category steps, CE102/RE102 reference floors) is checked
+  against those files in the role tests when the skills checkout is
+  present.
+- DO-160G section level/waveform/limit TABLES are standard data in the
+  current revision and are NOT reproduced here; typical reference
+  values are flagged as such and must be verified against the current
+  revision before a plan is frozen.
+- The qualification report template in `templates/` is an original
+  structure informed by public summary process knowledge. No
+  proprietary text is reproduced.

package/roles/do160-environmental-engineer/cli.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""cli.py - run the DO-160G Environmental Qualification Engineer role.
+
+Usage:
+  python3 cli.py build --out <file.md>   # build the qualification report
+                                          # for the example LRU
+  python3 cli.py check --file <file.md>  # gate-check an existing report
+
+The role ENGINE (core/do160_environmental_core.py) does the work
+standalone; bound avionics/do160 skills in Aero Agent Skills deepen
+individual stages when present.
+"""
+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 do160_environmental_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "do160-environmental-engineer"
+DELIVERABLE = "Equipment Environmental Qualification Plan/Report"
+
+
+def _provenance() -> dict:
+    """Provenance for the report bundle: role core, no skill dispatch."""
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/do160_environmental_core.py",
+            "functions": ["build_qualification_report",
+                          "render_qualification_report_markdown",
+                          "check_qualification_report"],
+            "version": "0.1.0",
+        },
+        "skills": [],
+        "cross_checked": False,
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+def cmd_build(args):
+    item = core.example_item()
+    # allow overriding the temperature category / lightning level from CLI
+    if args.temperature_category:
+        item.temperature_category = args.temperature_category
+    if args.lightning_level:
+        item.lightning_level = args.lightning_level
+    try:
+        model = core.build_qualification_report(item)
+    except ValueError as e:
+        print(f"error: bad item facts: {e}")
+        return 1
+    md = core.render_qualification_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_qualification_report(model)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md)
+        cat = model["temperature_category"]
+        print(f"built qualification report (category {cat}, "
+              f"item {model['item']}) -> {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, DELIVERABLE, 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_qualification_report_markdown(
+        md, args.category or "")
+    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="DO-160G Environmental Qualification 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("--temperature-category", default="",
+                   help="equipment category A1..D2 (default: auto-select "
+                        "from expected extremes)")
+    b.add_argument("--lightning-level", type=int, default=0,
+                   help="Section 22 test level 1-5 (default: 3)")
+    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="qualification report markdown to gate-check")
+    c.add_argument("--category", default="",
+                   help="expected temperature category (e.g. B1)")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()