aero-agent-roles 1.0.0

package/roles/gnc-engineer/ROLE.md

@@ -0,0 +1,141 @@
+---
+type: role
+name: gnc-engineer
+title: "Guidance, Navigation and Control (GNC) Engineer"
+status: draft
+domain: gnc-autonomy
+deliverable_type: "control design + guidance/navigation analysis report"
+standards_bound:
+  - id: mil-std-1797a
+    tier: TIER-1
+    reference-only: false
+skills_bound:
+  - gnc-autonomy/control/pid-control-design
+  - gnc-autonomy/control/lead-lag-compensation
+  - gnc-autonomy/control/frequency-response-design
+  - gnc-autonomy/control/digital-control-design
+  - gnc-autonomy/control/observer-design
+  - gnc-autonomy/control/control-allocation
+  - gnc-autonomy/control/gain-scheduling
+  - gnc-autonomy/control/adaptive-control
+  - gnc-autonomy/navigation/navigation-frames
+  - gnc-autonomy/navigation/inertial-navigation
+  - gnc-autonomy/navigation/kalman-filter-design
+  - gnc-autonomy/navigation/gnss-pseudorange-positioning
+  - gnc-autonomy/navigation/gnss-raim-fde
+  - gnc-autonomy/navigation/dilution-of-precision
+  - gnc-autonomy/guidance/pursuit-guidance
+  - gnc-autonomy/optimal-control/lqr-design
+  - gnc-autonomy/optimal-control/model-predictive-control
+  - gnc-autonomy/optimal-control/bang-bang-control
+  - gnc-autonomy/optimal-control/dymos-trajectory
+  - gnc-autonomy/space/attitude-dynamics
+  - gnc-autonomy/space/orbit-dynamics
+  - gnc-autonomy/space/orbit-determination
+  - gnc-autonomy/space/rendezvous-phasing
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "claim certification approval"
+  - "release flight software"
+  - "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+"
+---
+
+# Guidance, Navigation and Control (GNC) Engineer
+
+## Role identity
+
+Owns the GNC chain for a vehicle: navigation state estimation (INS,
+GNSS, filtering), guidance law selection, and control law design
+(inner/outer loops) with stability margins and handling-qualities
+context; plus attitude/orbit dynamics for space applications. Use when
+a vehicle needs a designed, analyzed control system or a navigation/
+guidance architecture with quantified performance. Do NOT use for
+aerodynamic/structural analysis or avionics software certification
+(DO-178C role).
+
+## Deliverable contract
+
+1. **GNC design report** (per templates/gnc-report-template.md, a FILLED
+   worked example generated by the core for the reference autopilot
+   item) - control architecture, plant model, loop gains, stability
+   margins, disturbance response, navigation error budget, guidance
+   performance, and (for space) attitude/orbit control.
+2. **Analysis evidence set** - the design calculations, frequency
+   responses, covariance runs, and Monte Carlo results, delivered as
+   the report's "Calculation traceability" appendix plus the computed
+   tables (gains, margins, budgets) in each section.
+
+The core engine computes every number from the domain rules of the
+bound leaves; nothing is asserted without a calculation.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Frames + plant | navigation-frames + space/attitude-dynamics + space/orbit-dynamics | reference frames, plant dynamics |
+| 2. Navigation filter | kalman-filter-design + inertial-navigation + gnss-pseudorange-positioning + gnss-raim-fde + dilution-of-precision | nav architecture + error budget |
+| 3. Inner loop | pid-control-design + lead-lag-compensation + frequency-response-design | inner loop gains + margins |
+| 4. Digital implementation | digital-control-design | discrete design |
+| 5. State estimation | observer-design | observer gains |
+| 6. Allocation/scheduling | control-allocation + gain-scheduling + adaptive-control | allocator + schedule |
+| 7. Guidance | pursuit-guidance | guidance law |
+| 8. Optimal control | lqr-design + model-predictive-control + bang-bang-control + dymos-trajectory | optimal/trajectory solution |
+| 9. Space GNC | space/orbit-determination + space/rendezvous-phasing | orbit determination, rendezvous |
+| 10. Report | (all above) | the GNC design report |
+
+## Evidence gates
+
+- Stage 1 done = plant + frames documented; states/inputs defined.
+- Stage 2 done = navigation error budget with sensor noise assumptions.
+- Stage 3 done = gain/phase margins meet the stated requirement.
+- Stage 5 done = observer poles placed with a rationale.
+- FINAL = every gain and margin traces to a calculation; Monte Carlo/
+  covariance results stated where relevant.
+
+## Boundary / forbidden
+
+- NEVER claim certification approval or release flight software (that is
+  the software/hardware cert + program authority).
+- Margins are design predictions; flight test and formal verification
+  are separate.
+- Navigation/guidance results assume the stated sensor models.
+
+## Verification
+
+The role runs STANDALONE: `core/gnc_core.py` is an executable engine
+that computes PID/LQR/observer gains, phase and gain margins from the
+loop gains, Kalman steady-state covariance and gain, PN guidance
+commands, sample-rate and discrete-design checks, and a seeded Monte
+Carlo robustness pass, then BUILDS the GNC design report and
+gate-checks deliverables. No AeroSkills checkout required.
+
+Run the role:
+```bash
+python3 cli.py build --out gnc-report.md              # example item
+python3 cli.py build --vehicle "My UAV" --bandwidth 4 # override facts
+python3 cli.py check --file gnc-report.md             # gate-check a report
+```
+
+Tests:
+- tests/test_gnc_engineer_core.py (20 tests): domain rules (pole
+  placement anchors, bandwidth factor, margins, Riccati, Kalman,
+  observer, PN), builder correctness, gate pass/fail, standalone mode
+  (no skills repo).
+- tests/test_role_gnc_engineer.py: bound-skill resolution (skips if
+  the skills repo is absent) + workflow + filled template + boundaries.
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (navigation leaves, guidance leaves, space GNC);
+the core engine does not depend on them.
+
+## Compliance
+
+- mil-std-1797a context where HQ applies. References summary-not-copy.
+- SOURCES.md records standards referenced.

package/roles/gnc-engineer/SOURCES.md

@@ -0,0 +1,35 @@
+# SOURCES.md - GNC Engineer
+
+| Source | Role use | Gated |
+|---|---|---|
+| MIL-STD-1797A | handling qualities context (Level-1 margins/bandwidth context where HQ applies) | false |
+| Stevens & Lewis, Aircraft Control and Simulation | control methods (book) | true |
+| Tewari, Modern Control Design | control reference (book) | true |
+| Groves, Principles of GNSS, Inertial, and Multisensor Navigation | navigation reference (book) | true |
+| Vallado, Fundamentals of Astrodynamics | orbit methods (book) | true |
+
+Summary-not-copy per STANDARDS.md.
+
+## Encoded domain rules (computed by core/gnc_core.py)
+
+The engine's numbers come from the textbook methods carried by the
+bound Aero Agent Skills leaves (which encode the books above as
+practice); no standard text is reproduced:
+
+| Rule | Formula | Bound leaf |
+|---|---|---|
+| Second-order bandwidth | w_bw = f(z) wn, f(z) = sqrt(1-2z^2+sqrt(2-4z^2+4z^4)) | control/frequency-response-design |
+| PID pole placement | match (s^2+2zwn s+wn^2)(s+p3) to plant b/(s^2+a1 s+a0) | control/pid-control-design |
+| Type-1 loop margins | L = K/(s(s+a)): PM = 90-atan(wc/a), GM = inf | control/pid-control-design |
+| Loop margins (general) | |L(jw)| and root-sum unwrapped phase on jw | control/frequency-response-design |
+| LQR | K = R^-1 B' P from the ARE closed form | optimal-control/lqr-design |
+| Kalman steady state | P = Riccati root, K = hP/(h^2P+r) | navigation/kalman-filter-design |
+| Observer | L = phi(A) O^-1 e_n (Ackermann, 2-state) | control/observer-design |
+| Guidance | a_c = N Vc lam_dot | guidance/pursuit-guidance |
+| Digital | 10-20 samples per closed-loop cycle; velocity-form PID | control/digital-control-design |
+
+Margins requirements (PM >= 45 deg, GM >= 6 dB) are the conventional
+flight-control design targets recorded as project requirements in the
+example; MIL-STD-1797A adds handling-qualities context where the
+program requires it. All example plant/sensor numbers are stated
+project facts (verify against the vehicle data).

package/roles/gnc-engineer/cli.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""cli.py - run the GNC Engineer role.
+
+Usage:
+  python3 cli.py build [--out <file.md>] [--bandwidth <rad/s>] \
+      [--phase-margin <deg>] [--gain-margin <dB>] [--bundle]
+    # build the GNC design report
+    # --bundle      also emit evidence/{model,gates,provenance}.json (PROTOCOL.md)
+  python3 cli.py check --file <file.md>             # gate-check a report
+
+The role ENGINE (core/gnc_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 gnc_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "gnc-engineer"
+
+
+def cmd_build(args):
+    proj = core.example_project()
+    # allow overriding requirements / vehicle from the CLI
+    if args.vehicle:
+        proj.vehicle = args.vehicle
+    if args.bandwidth:
+        proj.req_bandwidth_rad_s = float(args.bandwidth)
+    if args.phase_margin:
+        proj.req_phase_margin_deg = float(args.phase_margin)
+    if args.gain_margin:
+        proj.req_gain_margin_db = float(args.gain_margin)
+    model = core.build_gnc_report(proj)
+    md = core.render_gnc_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("error: bad profile: %s" % 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_gnc_report(model)
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md)
+        print("built GNC design report (%s) -> %s"
+              % (model["vehicle"], args.out))
+        if profile:
+            print("profile: %s / %s" % (profile.get("customer"),
+                                        profile.get("program")))
+        print("gates: all_pass=%s %s" % (gates["all_pass"], gates))
+        if args.bundle:
+            prov = {
+                "role": ROLE_SLUG,
+                "core": {
+                    "file": "core/gnc_core.py",
+                    "functions": ["pid_gains_second_order", "loop_margins",
+                                  "type1_margins", "riccati_solution",
+                                  "kalman_steady_state", "observer_gain_2state",
+                                  "pn_acceleration", "sample_rate_rule",
+                                  "monte_carlo_outer_margins",
+                                  "build_gnc_report"],
+                    "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, "GNC design report", 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("file not found: %s" % args.file)
+        return 1
+    md = open(args.file).read()
+    gates = core.check_gnc_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="GNC 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("--vehicle", default="", help="vehicle / project name")
+    b.add_argument("--bandwidth", default="",
+                   help="attitude bandwidth requirement (rad/s)")
+    b.add_argument("--phase-margin", default="",
+                   help="phase margin requirement (deg)")
+    b.add_argument("--gain-margin", default="",
+                   help="gain margin requirement (dB)")
+    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="GNC design report markdown to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()