aero-agent-roles 1.0.0

package/roles/numerical-analysis-engineer/tests/test_role_numerical_analysis_engineer.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Role test: Numerical Analysis Engineer.
+
+Verifies (offline, no network):
+1. Every skill bound in ROLE.md frontmatter RESOLVES to a real leaf in
+   the aero-agent-skills repo (the pinned skills_release band).
+2. The workflow stage order is deterministic and complete.
+3. The filled deliverable template is present with no blanks and the
+   boundary markers.
+"""
+import os
+import re
+import unittest
+
+ROLES_REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(
+    os.path.abspath(__file__)))))          # repo root (4 up from tests/)
+# Bound-skill resolution requires the Aero Agent Skills checkout. It is a
+# cross-repo dev check: when the skills repo is absent (fresh public clone),
+# skip resolution rather than fail - the role's bound list is verified in CI.
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+HAS_SKILLS = os.path.isdir(os.path.join(AEROSKILLS, "skills"))
+ROLE_DIR = os.path.join(ROLES_REPO, "roles", "numerical-analysis-engineer")
+TEMPLATE = os.path.join(ROLE_DIR, "templates", "verification-memo-template.md")
+
+EXPECTED_BOUND = [
+    "cross-cutting/numerics/numerical-integration",
+    "cross-cutting/numerics/root-finding",
+    "cross-cutting/numerics/convergence-verification",
+    "cross-cutting/numerics/finite-difference-derivatives",
+    "cross-cutting/numerics/ode-solvers",
+    "cross-cutting/numerics/interpolation",
+    "cross-cutting/numerics/least-squares-regression",
+    "cross-cutting/numerics/matrix-operations",
+    "cross-cutting/numerics/singular-value-decomposition",
+    "cross-cutting/numerics/uncertainty-propagation",
+]
+
+EXPECTED_STAGES = [
+    "Integration", "Root finding", "Derivatives", "ODE paths",
+    "Interpolation paths", "Regression paths", "Linear solve",
+    "Convergence", "Error budget", "Memo build",
+]
+
+
+def read_role_md():
+    p = os.path.join(ROLE_DIR, "ROLE.md")
+    if not os.path.exists(p):
+        return None
+    return open(p).read()
+
+
+class TestNumericalAnalysisEngineerRole(unittest.TestCase):
+
+    def test_bound_skills_resolve_in_aeroskills(self):
+        if not HAS_SKILLS:
+            self.skipTest("Aero Agent Skills checkout not present "
+                          "(cross-repo dev check)")
+        for leaf in EXPECTED_BOUND:
+            sk = os.path.join(AEROSKILLS, "skills", leaf, "SKILL.md")
+            self.assertTrue(
+                os.path.exists(sk),
+                f"bound skill not found in aero-agent-skills: {leaf}")
+            logic = os.path.join(AEROSKILLS, "skills", leaf, "scripts")
+            self.assertTrue(
+                any(f.endswith("_logic.py")
+                    for f in os.listdir(logic)),
+                f"bound leaf ships no logic file: {leaf}")
+
+    def test_bound_skills_listed_in_frontmatter(self):
+        role = read_role_md()
+        self.assertIsNotNone(role)
+        for leaf in EXPECTED_BOUND:
+            self.assertIn(leaf, role,
+                          f"missing in ROLE.md skills_bound: {leaf}")
+
+    def test_workflow_stages_deterministic(self):
+        role = read_role_md()
+        # every expected stage appears in order (indexes ascending)
+        idx = [role.find(stage) for stage in EXPECTED_STAGES]
+        self.assertTrue(all(i >= 0 for i in idx), "a stage is missing")
+        self.assertEqual(idx, sorted(idx), "stage order not deterministic")
+
+    def test_deliverable_template_complete(self):
+        if not os.path.exists(TEMPLATE):
+            self.fail("verification-memo-template.md missing")
+        with open(TEMPLATE) as fh:
+            text = fh.read()
+        # all 6 numbered sections present
+        for n in range(1, 7):
+            self.assertTrue(
+                re.search(rf"^## {n}\. ", text, re.M),
+                f"section {n} missing")
+        self.assertIn("DRAFT", text)
+        low = text.lower()
+        self.assertIn("not an approval", low)
+        self.assertIn("Numerical Methods Verification Memo", text)
+        self.assertNotIn("___", text)   # filled deliverable, zero blanks
+
+    def test_forbidden_lines_present(self):
+        role = read_role_md()
+        for phrase in ["issue engineering approval", "declare compliance",
+                       "sign_off_required: true", "reproduce proprietary"]:
+            self.assertIn(phrase, role, f"missing boundary: {phrase}")
+
+    def test_sources_register_exists(self):
+        p = os.path.join(ROLE_DIR, "SOURCES.md")
+        self.assertTrue(os.path.exists(p), "SOURCES.md missing for role")
+
+    def test_core_engine_exists(self):
+        """100% standard: every role ships an executable core + cli."""
+        for f in ["core", "cli.py"]:
+            self.assertTrue(os.path.exists(os.path.join(ROLE_DIR, f)),
+                            f"{f} missing - role is not executable")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/propulsion-engineer/ROLE.md

@@ -0,0 +1,163 @@
+---
+type: role
+name: propulsion-engineer
+title: "Propulsion Engineer"
+status: draft
+domain: propulsion
+deliverable_type: "propulsion system design + cycle analysis report"
+standards_bound:
+  - id: far-33
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - propulsion/gas-turbine-cycle/gas-turbine-cycle
+  - propulsion/gas-turbine-cycle/real-cycle-effects
+  - propulsion/gas-turbine-cycle/afterburner-cycle
+  - propulsion/gas-turbine-cycle/regenerative-cycle
+  - propulsion/gas-turbine-cycle/propelling-nozzle
+  - propulsion/gas-turbine-cycle/subsonic-inlet-recovery
+  - propulsion/gas-turbine-cycle/combustor-design
+  - propulsion/turbofan/turbofan-cycle
+  - propulsion/turbofan/bypass-ratio-trade
+  - propulsion/turbofan/turbofan-off-design
+  - propulsion/turboprop/turboprop-cycle
+  - propulsion/turboprop/free-turbine
+  - propulsion/axial-compressor/axial-compressor-stage
+  - propulsion/axial-compressor/compressor-map
+  - propulsion/axial-compressor/multi-stage-compressor
+  - propulsion/axial-compressor/turbine-stage
+  - propulsion/axial-compressor/turbine-blade-cooling
+  - propulsion/engine-airframe/engine-airframe-integration
+  - propulsion/rocket/rocket-engine-cycle
+  - propulsion/rocket/nozzle-design
+  - propulsion/rocket/combustion-chamber-design
+  - propulsion/rocket/injector-design
+  - propulsion/rocket/propellant-selection
+  - propulsion/rocket/solid-rocket-motor
+  - propulsion/rocket/hybrid-rocket-motor
+  - propulsion/rocket/thrust-chamber-cooling
+  - propulsion/rocket/thrust-vector-control
+  - propulsion/rocket/cold-gas-thruster
+  - propulsion/combustion/cea-rocket-combustion
+  - propulsion/electric/hall-thruster
+  - propulsion/electric/gridded-ion-thruster
+  - propulsion/electric/electrothermal-thruster
+  - propulsion/ramjet/ramjet-cycle
+  - propulsion/ramjet/ramjet-inlet
+tools_allowed: [stdlib, offline-file-processing, cea-cli]
+forbidden:
+  - "claim certification approval"
+  - "release an engine for production"
+  - "reproduce proprietary standard text"
+sign_off_required: true
+license: Apache-2.0
+compatibility: "agentskills.io ROLE.md; any SKILL.md host"
+metadata:
+  version: 1.0.0
+  author: Aero Agent Roles
+  skills_release: "v1.3.0+"
+---
+
+# Propulsion Engineer
+
+## Role identity
+
+Owns propulsion system selection and cycle design: gas turbine cycle
+analysis (turbofan/turboprop/turbojet), component matching (compressor,
+turbine, combustor, nozzle), engine-airframe integration, and the rocket
+or electric propulsion trades for non-airbreathing applications. Use
+when a vehicle needs a propulsion solution with a defensible cycle,
+specific fuel consumption, thrust, and integration answer. Do NOT use
+for structural or certification workflow (separate roles).
+
+## Deliverable contract
+
+1. **Propulsion design report** - selected cycle + rationale, on-design
+   and off-design performance, component choices, fuel burn, integration
+   notes (inlet, nozzle, nacelle), or rocket/electric trade for space.
+2. **Cycle analysis evidence** - the thermodynamic calculations,
+   component maps, and trade studies supporting the selection.
+
+The filled deliverable for the reference item (a BPR-8 / OPR-30 /
+TIT-1650 K high-bypass turbofan at M0.78 / FL350) is
+`templates/propulsion-report-template.md` - generated by the core,
+zero blanks: station state table, net thrust, TSFC/SFC, efficiencies,
+off-design envelope, component table, integration, and the bypass
+trade. Rocket-cycle evidence for space items is generated the same way
+with the `--engine rocket` variant.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Airbreathing cycle | gas-turbine-cycle + real-cycle-effects + turbofan-cycle + turboprop-cycle | cycle on-design: thrust, SFC, thermal efficiency |
+| 2. Bypass/regenerative/AB trades | bypass-ratio-trade + regenerative-cycle + afterburner-cycle | configuration trade |
+| 3. Off-design | turbofan-off-design | performance across envelope |
+| 4. Components | compressor-map + multi-stage-compressor + turbine-stage + combustor-design + propelling-nozzle + subsonic-inlet-recovery + free-turbine | component maps + matching |
+| 5. Turbine cooling | turbine-blade-cooling | cooling flow requirement |
+| 6. Integration | engine-airframe-integration | installation + ram drag + bleed |
+| 7. Rocket cycle | rocket-engine-cycle + nozzle-design + combustion-chamber-design + injector-design + propellant-selection | rocket cycle, Isp, chamber conditions |
+| 8. Solid/hybrid | solid-rocket-motor + hybrid-rocket-motor | motor option |
+| 9. Cooling/TVC | thrust-chamber-cooling + thrust-vector-control + cold-gas-thruster | cooling + control solution |
+| 10. Combustion | cea-rocket-combustion | equilibrium products |
+| 11. Electric | hall-thruster + gridded-ion-thruster + electrothermal-thruster | electric propulsion trade |
+| 12. Ramjet | ramjet-cycle + ramjet-inlet | ramjet option |
+| 13. Report | (all above) | the propulsion design report |
+
+## Evidence gates
+
+- Stage 1 done = cycle state points complete (T, p, efficiency), SFC +
+  thrust with the input assumptions stated.
+- Stage 3 done = off-design map covers the operating envelope.
+- Stage 7 done = Isp and chamber conditions from an equilibrium or
+  accepted method; propellant choice has a rationale.
+- FINAL = every performance claim traces to a calculation.
+
+The core's `check_report` gate applies these: requirement present,
+cycle identified, station state points complete, net thrust computed,
+TSFC/SFC computed, assumptions stated, and the document marked
+draft-for-review.
+
+## Boundary / forbidden
+
+- NEVER claim certification approval or release an engine.
+- Component maps are representative input, not vendor data unless the
+  vendor source is cited.
+- Electric/rocket performance assumes stated inputs (Isp, efficiency,
+  chamber Tc/gamma/R to be confirmed by equilibrium CEA); never assert a
+  vendor product spec without a source.
+- Output is a DRAFT for human review - mark it draft.
+
+## Verification
+
+The role runs STANDALONE: `core/propulsion_core.py` is an executable
+engine that computes the ISA atmosphere, the ideal/real gas-turbine
+relations, the separate-stream turbofan on-design cycle (station state
+table, net thrust F = sum mdot*(V9-V0) + (P9-P0)*A9, TSFC, efficiency
+decomposition), the off-design envelope with corrected-flow matching
+and compressor-map verdicts, the bypass-ratio trade, and the rocket
+feed-cycle/nozzle analysis. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out report.md                 # turbofan report
+python3 cli.py build --engine rocket --out rocket.md # rocket option
+python3 cli.py build --bpr 6 --opr 25 --tit 1600     # cycle variants
+python3 cli.py check --file report.md                # gate-check
+```
+
+Tests:
+- tests/test_propulsion_engineer_core.py (26 tests): domain rules +
+  on-design builder + off-design + rocket + gates + standalone (no
+  skills repo)
+- tests/test_role_propulsion_engineer.py: bound-skill resolution
+  (skips if the skills repo is absent) + workflow + template + boundaries
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (component maps, CEA equilibrium, turbine cooling,
+TVC); the core engine does not depend on them.
+
+## Compliance
+
+- far-33 TIER-1 context. Data references summary-not-copy.
+- SOURCES.md records standards referenced.

package/roles/propulsion-engineer/SOURCES.md

@@ -0,0 +1,15 @@
+# SOURCES.md - Propulsion Engineer
+
+| Source | Role use | Gated |
+|---|---|---|
+| 14 CFR Part 33 | engine certification context | false |
+| Mattingly, Aircraft Engine Design | cycle analysis methodology (book) | true |
+| Hill & Peterson, Mechanics and Thermodynamics of Propulsion | propulsion fundamentals (book) | true |
+| Sutton, Rocket Propulsion Elements | rocket propulsion reference (book) | true |
+| NASA CEA documentation | equilibrium combustion tooling | false |
+| AeroSkills propulsion leaves (gas-turbine-cycle, real-cycle-effects, turbofan-cycle, bypass-ratio-trade, turbofan-off-design, compressor-map, propelling-nozzle, rocket-engine-cycle, nozzle-design) | domain rules and reference-typical values encoded in core/propulsion_core.py: Brayton/real-cycle relations and anchors, choked-flow and area-Mach relations, standard-day corrections, surge-margin definitions, throttle bands, rocket propellant table (LOX/RP-1, LOX/LH2, N2O4/MMH, hydrazine) and feed-cycle chamber-pressure bounds | false (offline mirrors) |
+
+Summary-not-copy per STANDARDS.md. The core encodes the *relations*
+(summary of common propulsion methodology) with reference-typical
+values used in the bound leaves; no leaf script is imported and no
+proprietary text is reproduced.

package/roles/propulsion-engineer/cli.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""cli.py - run the Propulsion Engineer role.
+
+Usage:
+  python3 cli.py build --out <file.md>                # turbofan design report
+  python3 cli.py build --engine rocket --out r.md     # rocket option report
+  python3 cli.py build --engine turbofan --bpr 6 --opr 25  # parameter sweep
+  python3 cli.py build --out <file.md> --bundle       # + evidence/{model,gates,provenance}.json
+  python3 cli.py build --out <file.md> --profile profiles/example-airframer.json --bundle
+  python3 cli.py check --file <file.md>               # gate-check a report
+
+The role ENGINE (core/propulsion_core.py) does the work standalone; bound
+skills in Aero Agent Skills deepen individual stages when present. With
+--bundle the CLI also writes the PROTOCOL.md v1 evidence bundle
+(evidence/{model,gates,provenance}.json) next to the deliverable. With
+--profile <profile.json> the program context header
+(docs/PROFILE-SCHEMA.md) is prepended to the report and profile.* is
+recorded in the bundle model.
+"""
+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 propulsion_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "propulsion-engineer"
+
+
+def _provenance(model):
+    """Provenance for the evidence bundle (PROTOCOL.md v1).
+
+    The propulsion role core computes every number standalone (cycle,
+    envelope, trade, rocket sizing); no bound skill logic is dispatched,
+    so the skills list is empty and the bundle is not cross-checked.
+    """
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/propulsion_core.py",
+            "functions": ["turbofan_design_point", "off_design_envelope",
+                          "bpr_trend", "rocket_engine_cycle_analysis",
+                          "rocket_nozzle_sizing"],
+            "version": "0.1.0",
+        },
+        "skills": [],
+        "cross_checked": False,
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+def _apply_overrides(item, args):
+    if args.bpr is not None:
+        item.bpr = args.bpr
+    if args.opr is not None:
+        item.opr = args.opr
+    if args.tit is not None:
+        item.tit_k = args.tit
+    if args.fpr is not None:
+        item.fpr = args.fpr
+    if args.thrust is not None:
+        item.thrust_requirement_n = args.thrust * 1000.0
+    if args.engine == "rocket":
+        if args.thrust is not None:
+            item.thrust_vac_n = args.thrust * 1000.0
+    return item
+
+
+def cmd_build(args):
+    if args.engine == "rocket":
+        item = core.example_rocket_item()
+    else:
+        item = core.example_turbofan_item()
+    item = _apply_overrides(item, args)
+    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)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md)
+        kind = model["engine_kind"]
+        print(f"built {kind} design report -> {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:
+            prov = _provenance(model)
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG, "propulsion design report",
+                model, dict(gates, checker="check_report"), prov)
+            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="Propulsion 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("--engine", default="turbofan",
+                   choices=["turbofan", "rocket"],
+                   help="engine class for the reference item")
+    b.add_argument("--bpr", type=float, default=None, help="bypass ratio")
+    b.add_argument("--opr", type=float, default=None, help="overall pressure ratio")
+    b.add_argument("--tit", type=float, default=None, help="turbine inlet temp (K)")
+    b.add_argument("--fpr", type=float, default=None, help="fan pressure ratio")
+    b.add_argument("--thrust", type=float, default=None,
+                   help="thrust requirement (kN)")
+    b.add_argument("--bundle", action="store_true",
+                   help="emit evidence/{model,gates,provenance}.json "
+                        "(PROTOCOL.md v1, requires --out)")
+    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="report markdown to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()