aero-agent-roles 1.0.0

package/roles/engineering-analysis-engineer/ROLE.md

@@ -0,0 +1,154 @@
+---
+type: role
+name: engineering-analysis-engineer
+title: "Engineering Analysis and Data Engineer"
+status: draft
+domain: cross-cutting
+deliverable_type: "analysis verification + engineering report"
+standards_bound:
+  - id: asme-y14-5
+    tier: TIER-2
+    reference-only: true
+skills_bound:
+  - cross-cutting/units-atmos/isa-atmosphere
+  - cross-cutting/units-atmos/density-altitude
+  - cross-cutting/units-atmos/airspeed-conversion
+  - cross-cutting/units-atmos/unit-conversion
+  - cross-cutting/units-atmos/dimensional-analysis
+  - cross-cutting/units-atmos/temperature-conversion
+  - cross-cutting/numerics/finite-difference-derivatives
+  - cross-cutting/numerics/numerical-integration
+  - cross-cutting/numerics/ode-solvers
+  - cross-cutting/numerics/root-finding
+  - cross-cutting/numerics/interpolation
+  - cross-cutting/numerics/least-squares-regression
+  - cross-cutting/numerics/optimization-algorithms
+  - cross-cutting/numerics/eigenvalue-decomposition
+  - cross-cutting/numerics/singular-value-decomposition
+  - cross-cutting/numerics/matrix-operations
+  - cross-cutting/numerics/complex-number-algebra
+  - cross-cutting/numerics/quaternion-algebra
+  - cross-cutting/numerics/fast-fourier-transform
+  - cross-cutting/numerics/fir-filter-design
+  - cross-cutting/numerics/digital-filter-design
+  - cross-cutting/numerics/power-spectral-density
+  - cross-cutting/numerics/uncertainty-propagation
+  - cross-cutting/numerics/monte-carlo-sampling
+  - cross-cutting/numerics/probability-distributions
+  - cross-cutting/numerics/confidence-interval-estimation
+  - cross-cutting/numerics/hypothesis-testing
+  - cross-cutting/numerics/descriptive-statistics
+  - cross-cutting/numerics/cross-correlation-analysis
+  - cross-cutting/numerics/information-entropy
+  - cross-cutting/numerics/convergence-verification
+  - cross-cutting/numerics/grubbs-outlier-test
+  - cross-cutting/numerics/runs-test
+  - cross-cutting/numerics/rank-based-hypothesis-testing
+  - cross-cutting/tolerancing/gdandt-basics
+  - cross-cutting/tolerancing/datum-reference-frames
+  - cross-cutting/tolerancing/position-tolerance-calc
+  - cross-cutting/tolerancing/tolerance-stackup
+  - cross-cutting/documentation/engineering-report
+  - cross-cutting/documentation/engineering-margins
+  - cross-cutting/data-sources/aeronautical-data-sources
+  - cross-cutting/export-control/export-control-awareness
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "issue engineering approval"
+  - "declare compliance"
+  - "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+"
+---
+
+# Engineering Analysis and Data Engineer
+
+## Role identity
+
+Owns the cross-cutting analysis layer every aerospace deliverable
+depends on: unit/atmosphere discipline, numerical methods with
+verification, statistical treatment of data, tolerance analysis, and
+the engineering-report/margin conventions that make results
+auditable. Use when a calculation, dataset, or report needs to be
+correct, verifiable, and presented with margins. Do NOT use for
+domain-specific design (use the domain roles).
+
+## Deliverable contract
+
+1. **Analysis verification memo** - numerical convergence/verification,
+   unit consistency, uncertainty/statistics treatment, tolerance result,
+   and the engineering report with margins.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Unit/atmosphere | isa-atmosphere + density-altitude + airspeed-conversion + unit-conversion + dimensional-analysis + temperature-conversion | consistent units, ISA conditions |
+| 2. Numerics | finite-difference-derivatives + numerical-integration + ode-solvers + root-finding + interpolation | validated numerical result |
+| 3. Regression/opt | least-squares-regression + optimization-algorithms | fitted/optimized result |
+| 4. Linear algebra | eigenvalue-decomposition + singular-value-decomposition + matrix-operations + complex-number-algebra + quaternion-algebra | matrix/rotation results |
+| 5. Signal | fast-fourier-transform + fir-filter-design + digital-filter-design + power-spectral-density + cross-correlation-analysis | signal analysis |
+| 6. Uncertainty | uncertainty-propagation + monte-carlo-sampling + probability-distributions + confidence-interval-estimation | uncertainty bands |
+| 7. Statistics | hypothesis-testing + descriptive-statistics + grubbs-outlier-test + runs-test + rank-based-hypothesis-testing + information-entropy | statistical verdicts |
+| 8. Convergence | convergence-verification | mesh/step convergence evidence |
+| 9. Tolerancing | gdandt-basics + datum-reference-frames + position-tolerance-calc + tolerance-stackup | tolerance stack result |
+| 10. Data sourcing | aeronautical-data-sources | sourced data with citation |
+| 11. Export control | export-control-awareness | classification of output |
+| 12. Report | engineering-report + engineering-margins | the analysis memo |
+
+## Evidence gates
+
+- Stage 1 done = every quantity unit-consistent with the ISA basis
+  stated.
+- Stage 8 done = convergence/verification evidence accompanies any
+  numerical result.
+- Stage 12 done = margins stated per engineering-margins convention;
+  report follows the report standard.
+
+## Boundary / forbidden
+
+- NEVER issue engineering approval or declare compliance.
+- The memo is analysis support; design release is a human decision.
+- Export-control awareness is applied; no controlled data is included.
+
+## Verification
+
+The role runs STANDALONE: `core/engineering_analysis_engineer_core.py` is an
+executable engine that computes ISA atmosphere reference values, propagates
+measurement uncertainty (GUM first-order law), builds Student t confidence
+intervals, runs worst-case + RSS tolerance stack-ups, verifies numerical
+convergence (Richardson extrapolation + GCI), states margins per the
+engineering-margins convention, BUILDS the Analysis Verification Memo, and
+gate-checks deliverables. No AeroSkills checkout required
+(`AEROSKILLS_DEV=/nonexistent` still builds correctly).
+
+Run the role:
+```bash
+python3 cli.py build --out memo.md                              # example chain
+python3 cli.py build --altitude 6000 --out memo.md              # other test point
+python3 cli.py build --pressure 70100 --temperature 270.5       # override inputs
+python3 cli.py check --file memo.md                             # gate-check a memo
+```
+
+Tests:
+- tests/test_engineering_analysis_engineer_core.py (36 tests): ISA model,
+  uncertainty propagation, t confidence intervals, tolerance stack-up,
+  convergence verification, margins, memo builder, gates, standalone
+  (no skills repo), and the filled template byte-matches the core example.
+- tests/test_role_engineering_analysis_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 (atmosphere leaves, uncertainty/statistics leaves, tolerance and
+numerics leaves); the core engine does not depend on them.
+
+## Compliance
+
+- asme-y14-5 TIER-2 reference-only (GD&T). References summary-not-copy.
+- SOURCES.md records standards referenced.

package/roles/engineering-analysis-engineer/SOURCES.md

@@ -0,0 +1,15 @@
+# SOURCES.md - Engineering Analysis and Data Engineer
+
+| Source | Role use | Gated |
+|---|---|---|
+| ASME Y14.5 | GD&T conventions (dimensioning/tolerancing basis for stacks) | true |
+| ISO 2533 / ICAO Doc 7488 | Standard atmosphere: ISA constants and lapse model (sea level 288.15 K / 101325 Pa / 1.225 kg/m3, 6.5 K/km to 11 km) | false |
+| JCGM 100:2008 (GUM) | Measurement uncertainty: first-order law u_c = sqrt(sum((df/dx_i * u_i)^2)), coverage factor k, expanded uncertainty | false |
+| JCGM 101 (GUM Supp. 1) | Monte Carlo uncertainty evaluation context (bound leaf monte-carlo-sampling) | false |
+| Student t distribution (standard statistics) | Small-sample confidence intervals: xbar +/- t_{1-alpha/2, n-1} * s/sqrt(n) | false |
+| Richardson extrapolation / GCI (AIAA V&V practice) | Numerical convergence verification: observed order p, grid convergence index, Fs = 1.25 | false |
+| MIL-STD-810 / DO-160 (context) | Data context where applicable | true |
+
+Summary-not-copy per STANDARDS.md: public standards (ISO 2533, JCGM 100)
+are used as common-knowledge method summaries, never reproduced verbatim;
+ASME Y14.5 and MIL-STD-810 / DO-160 are reference-only.

package/roles/engineering-analysis-engineer/cli.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""cli.py - run the Engineering Analysis and Data Engineer role.
+
+Usage:
+  python3 cli.py build [--out <file.md>] [--altitude 3000] [--pressure 70050]
+                       [--pressure-unc 35] [--temperature 271]
+                       [--temperature-unc 1.2] [--bundle]
+                       # build the Analysis Verification Memo for the example
+                       # measurement chain (overrides optional)
+                       # --bundle  also emit evidence/{model,gates,provenance}.json
+                       #           (docs/PROTOCOL.md v1)
+  python3 cli.py check --file <file.md>   # gate-check an existing memo
+
+The role ENGINE (core/engineering_analysis_engineer_core.py) does the work
+standalone; bound 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 engineering_analysis_engineer_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "engineering-analysis-engineer"
+
+
+def cmd_build(args):
+    chain = core.example_chain()
+    if args.altitude is not None:
+        chain.altitude_m = args.altitude
+    if args.pressure is not None:
+        chain.pressure_pa = args.pressure
+    if args.pressure_unc is not None:
+        chain.pressure_unc_pa = args.pressure_unc
+    if args.temperature is not None:
+        chain.temperature_k = args.temperature
+    if args.temperature_unc is not None:
+        chain.temperature_unc_k = args.temperature_unc
+    model = core.build_memo(chain)
+    md = core.render_memo_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_memo(model)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md)
+        print(f"built Analysis Verification Memo -> {args.out}")
+        print(f"density {model['density_kgm3']:.6g} +/- "
+              f"{model['expanded_U']:.6g} kg/m3; "
+              f"gates: all_pass={gates['all_pass']}")
+        if profile:
+            print(f"profile: {profile.get('customer')} / "
+                  f"{profile.get('program')}")
+        if args.bundle:
+            prov = {
+                "role": ROLE_SLUG,
+                "core": {
+                    "file": "core/engineering_analysis_engineer_core.py",
+                    "functions": ["isa_reference_values",
+                                  "combined_standard_uncertainty",
+                                  "confidence_interval_mean",
+                                  "rss_total", "convergence_verdict",
+                                  "density_altitude_m", "margin_of_safety"],
+                    "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,
+                "Analysis Verification Memo", 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(f"file not found: {args.file}")
+        return 1
+    md = open(args.file).read()
+    gates = core.check_memo_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="Engineering Analysis and Data 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("--altitude", type=float, default=None,
+                   help="test point geometric altitude in m")
+    b.add_argument("--pressure", type=float, default=None,
+                   help="measured static pressure in Pa")
+    b.add_argument("--pressure-unc", type=float, default=None,
+                   help="static pressure 1-sigma uncertainty in Pa")
+    b.add_argument("--temperature", type=float, default=None,
+                   help="measured temperature in K")
+    b.add_argument("--temperature-unc", type=float, default=None,
+                   help="temperature 1-sigma uncertainty in K")
+    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="memo markdown file")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()