aero-agent-roles 1.0.0

package/roles/space-systems-engineer/SOURCES.md

@@ -0,0 +1,49 @@
+# SOURCES.md - Space Systems Engineer
+
+Standards and documents this role references. Summary-not-copy: see
+[STANDARDS.md](../../STANDARDS.md) for the full rule and purchase links.
+
+## Standards / references
+
+| Source | Role use | Gated |
+|---|---|---|
+| ECSS-E-ST-10, E-ST-32, E-ST-33, E-ST-40, Q-ST-80 | systems/software engineering + product assurance context | true |
+| Wertz et al., Space Mission Analysis and Design (SMAD) | mission design, margin policy, disturbance model (book) | true |
+| Vallado, Fundamentals of Astrodynamics and Applications | astrodynamics methods: vis-viva, Hohmann, Kepler (book) | true |
+| Larson & Wertz, Space Mission Analysis and Design | subsystem sizing conventions (book) | true |
+| NASA GEVS / NPR | environment and test practice (informational) | false |
+
+## Domain rules encoded in core/space_systems_core.py
+
+Every number the engine produces follows a REAL relation exercised by
+the bound AeroSkills space-systems leaves (same formulas, reimplemented
+stdlib-only so the role is standalone). Anchor values in
+tests/test_space_systems_engineer_core.py are the leaves' own worked
+examples.
+
+| Rule | Formula | Source leaf |
+|---|---|---|
+| Circular orbit velocity | v = sqrt(mu/r) | space-systems/orbit-mechanics/hohmann-transfer |
+| Orbit period | T = 2*pi*sqrt(r^3/mu) | hohmann-transfer / kepler-orbit-propagation |
+| Hohmann transfer delta-v | dv = dv1 + dv2 (two burns, vis-viva) | hohmann-transfer |
+| Disposal perigee-lowering burn | single retrograde burn, vis-viva | hohmann-transfer pattern, ECSS-E-ST-33 disposal practice |
+| Delta-v budget + margin | sum contributions; dv*(1+margin) | mission-design/mission-delta-v-budget |
+| Propellant mass (rocket equation) | m_prop = m_dry*(exp(dv/(Isp*g0)) - 1) | mission-delta-v-budget |
+| Eclipse fraction/time (beta = 0) | f = asin(Re/r)/pi; t = f*T | orbit-mechanics/eclipse-time |
+| Battery capacity | C = P*T_ecl/(DoD*efficiency) | subsystems/power-thermal-budget, spacecraft-battery-sizing |
+| Solar array daylight power | P/(eff*(1-f))*(1+margin) | power-thermal-budget |
+| Array EOL specific power + area | p_eol = G*eta*PF*(1-r)^n; A = P/p_eol | subsystems/solar-array-sizing |
+| Radiator area | A = Q/(eps*sigma*(T^4 - T_sink^4)) | subsystems/thermal-design |
+| Reaction wheel momentum sizing | h_slew = J*omega; h_wheel = J_w*omega_max | adcs/reaction-wheel-control, attitude-control-sizing |
+| Pointing error budget | RSS of 3-sigma contributors vs requirement | adcs/pointing-error-budget |
+| Link budget (Friis) | L_fs, EIRP, C/N0, Eb/N0 margin | subsystems/communication-link-budget |
+| Tank sizing | V = m/rho, ullage, t = p*r/(2*sigma) | subsystems/propellant-tank-sizing |
+
+Conservative stated inputs (margin 15% on delta-v, 20% array margin, 30%
+battery DoD, 3 dB link requirement, 0.1 deg 3-sigma pointing) follow SMAD
+margin practice and are cited as design inputs in the report; the engine
+does not invent an allowable or a factor.
+
+The template in `templates/space-systems-template.md` is the generated
+worked example (Aurora-1, 600 km SSO): REAL delta-v, propellant, wheel,
+array, battery, radiator, and link numbers - zero blanks.

package/roles/space-systems-engineer/cli.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""cli.py - run the Space Systems Engineer role.
+
+Usage:
+  python3 cli.py build --out <file.md>              # build the mission +
+                                                    # subsystem design report
+  python3 cli.py build --out alt.md --altitude 500  # variant orbit
+  python3 cli.py build --out r.md --bundle          # also write
+                                                    # evidence/{model,gates,
+                                                    # provenance}.json
+                                                    # (docs/PROTOCOL.md v1)
+  python3 cli.py build --out r.md --bundle \
+      --profile profiles/example-airframer.json     # program profile context
+                                                    # header (customer
+                                                    # tailoring, docs/
+                                                    # PROFILE-SCHEMA.md)
+  python3 cli.py check --file <file.md>             # gate-check a report
+
+The role ENGINE (core/space_systems_core.py) does the work standalone;
+bound AeroSkills space-systems leaves deepen individual stages when
+present, but the core never depends on them.
+"""
+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 space_systems_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "space-systems-engineer"
+
+
+def cmd_build(args):
+    mission = core.example_mission()
+    if args.altitude:
+        mission.altitude_km = args.altitude
+    if args.name:
+        mission.name = args.name
+    if args.dry_mass:
+        mission.dry_mass_kg = args.dry_mass
+    if args.isp:
+        mission.isp_s = args.isp
+    if args.dv_margin:
+        mission.dv_margin_fraction = args.dv_margin
+    model = core.build_report(mission)
+    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)
+        dv = model["delta_v"]
+        print(f"built report -> {args.out}")
+        if profile:
+            print(f"profile: {profile.get('customer')} / "
+                  f"{profile.get('program')}")
+        print(f"  orbit: {mission.altitude_km:.0f} km circular, "
+              f"period {model['power']['eclipse']['period_min']:.1f} min")
+        print(f"  delta-v: {dv['nominal_dv_m_s']:.1f} m/s nominal / "
+              f"{dv['budgeted_dv_m_s']:.1f} m/s budgeted; "
+              f"propellant {dv['propellant_mass_kg']:.1f} kg")
+        print(f"  wheel: {model['adcs']['wheel_momentum_capacity_nms']:.1f} N m s "
+              f"at {model['adcs']['wheel_speed_max_rpm']:.0f} rpm; "
+              f"array {model['power']['array_area_m2']:.2f} m^2; "
+              f"battery {model['power']['battery_sized_wh']:.0f} Wh")
+        print(f"  pointing {model['pointing']['rss_deg']:.3f} deg; "
+              f"link down {model['comms']['downlink']['margin_db']:.1f} dB / "
+              f"up {model['comms']['uplink']['margin_db']:.1f} dB")
+        print(f"  gates: all_pass={gates['all_pass']}")
+        if args.bundle:
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG,
+                "Spacecraft Mission and Subsystem Design Report",
+                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 _provenance():
+    """PROTOCOL.md v1 provenance row.
+
+    The role core computed every number in the model standalone; no
+    bound-skill logic file was dispatched, so skills is honestly empty
+    and cross_checked is False.
+    """
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/space_systems_core.py",
+            "functions": ["build_report", "mission_delta_v_budget",
+                          "power_and_thermal", "reaction_wheel_sizing",
+                          "comms_link_budget", "check_report"],
+            "version": "0.1.0",
+        },
+        "skills": [],
+        "cross_checked": False,
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+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="Space Systems 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("--name", default="", help="spacecraft/mission name")
+    b.add_argument("--altitude", type=float, default=0.0,
+                   help="circular orbit altitude in km (default 600)")
+    b.add_argument("--dry-mass", type=float, default=0.0,
+                   help="spacecraft dry mass in kg (default 150)")
+    b.add_argument("--isp", type=float, default=0.0,
+                   help="propulsion specific impulse in s (default 220)")
+    b.add_argument("--dv-margin", type=float, default=0.0,
+                   help="delta-v margin fraction (default 0.15)")
+    b.add_argument("--bundle", action="store_true",
+                   help="also write evidence/{model,gates,provenance}.json "
+                        "(docs/PROTOCOL.md v1)")
+    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 file to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()