aero-agent-roles 1.0.0

package/roles/do254-hardware-engineer/templates/phac-template.md

@@ -0,0 +1,87 @@
+# Plan for Hardware Aspects of Certification
+
+**Item:** Autopilot Mode Logic FPGA (complex CPLD/FPGA-based LRU function)
+**Design assurance level:** B (from hazardous failure condition)
+**AEH class:** complex
+**Certification basis:** FAR/CS-25
+**Status:** draft-for-review
+
+## 1. Scope
+
+This plan covers the airborne electronic hardware item Autopilot Mode Logic FPGA (complex CPLD/FPGA-based LRU function). FPGA implementation of the autopilot flight mode selection and engage logic hosted in the flight guidance computer LRU.
+The item is complex AEH per DO-254, technology CPLD/FPGA programmable logic.
+
+## 2. Design assurance level and failure-condition basis
+
+The hardware design assurance level is B based on the hazardous failure condition (system safety reference FHA-FGS-001 / PSSA rev C).
+
+## 3. Hardware life cycle and life cycle data
+
+The waterfall life cycle is used. The hardware life cycle data set for this level is:
+
+- plan for hardware aspects of certification (PHAC)
+- hardware requirements standards
+- hardware design standards
+- hardware validation plan
+- hardware verification plan
+- hardware configuration management plan
+- hardware process assurance plan
+- hardware requirements data
+- hardware design data
+- hardware verification data and results
+- hardware life cycle environment configuration index
+- hardware configuration index (HCI)
+- hardware process assurance records
+- hardware accomplishment summary (HAS)
+
+## 4. Hardware design assurance environment
+
+- Development tools: HDL synthesis tool, static timing analyzer
+- Verification tools: HDL simulator, requirements-based test harness, code coverage tool
+- Tool qualification: criteria-based per DO-254 tool assessment
+
+## 5. Requirements capture and traceability
+
+- Requirements under review: 12 (allocated 10, derived 2).
+- Allocated requirements traced upward: 10 of 10 (complete).
+- Derived requirements justified: 2 of 2 (complete).
+- Capture readiness score: 0.83 (ready).
+- Hardware requirements are reviewed for completeness, correctness, and verifiability with unique identifiers and trace links; vague wording fails the review.
+
+## 6. Design and implementation
+
+- HDL languages: VHDL.
+- Target device: FPGA, flight guidance computer LRU.
+- Conceptual design and detailed design data are produced for complex AEH and reviewed against the requirements.
+
+## 7. Verification strategy
+
+- Verification methods: analysis, review, test.
+- Requirements-based coverage ratio: 0.98 (level B).
+- Verification independence: independent.
+- Hardware/software integration evidence ties the item to the software it hosts.
+
+## 8. Configuration management
+
+The hardware configuration management plan defines baselines, change control (ECR/ECO), and the hardware configuration index (HCI). Class 1 changes (form/fit/function, safety effect, or complex hardware) require baseline update, reverification, and independent review.
+
+## 9. Process assurance
+
+Hardware process assurance monitors conformity of the life cycle data and records objective evidence of process compliance.
+
+## 10. Certification liaison and compliance
+
+Certification authority liaison, means of compliance, and the acceptance basis (AC 20-152A) are addressed with the airworthiness authority. Previously developed hardware, when used, is assessed under the PDS process.
+
+## 11. Objectives summary
+
+- planning
+- requirements
+- design
+- verification
+- cm
+- process-assurance
+- cert-liaison
+
+---
+*Generated by Aero Agent Roles do254-hardware-engineer core (2026-09-05). DRAFT for human hardware certification engineer review. Not an approval document.*

package/roles/do254-hardware-engineer/tests/test_do254_bundle_profile.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Test the do254-hardware-engineer evidence bundle + profile + dispatch.
+
+Verifies (offline, no network):
+- build --bundle emits evidence/{model,gates,provenance}.json
+- bundle JSON parses, model carries the PHAC numbers, gates all_pass
+- skill dispatch cross-checks the bound do254 leaf logics against the
+  core when AeroSkills is present (all agree)
+- standalone (no AeroSkills) exits 0 with cross_checked=false
+- build --profile prepends the program-context header and records the
+  customer in model.json (PROFILE-SCHEMA.md)
+- malformed profile fails loudly with exit 1
+- cli check PASSes the built PHAC
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+ROLE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+CLI = os.path.join(ROLE_DIR, "cli.py")
+# repo root is 4 up from tests/ (tests -> role -> roles -> repo)
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(
+    os.path.dirname(os.path.abspath(__file__)))))
+PROFILE = os.path.join(REPO_ROOT, "profiles", "example-airframer.json")
+EXPECTED_CUSTOMER = "Example Airframers Ltd"
+
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+HAS_SKILLS = os.path.isdir(os.path.join(AEROSKILLS, "skills"))
+
+
+def run_build(outdir, env_extra=None, extra_args=None):
+    env = dict(os.environ)
+    if env_extra:
+        env.update(env_extra)
+    args = [sys.executable, CLI, "build", "--out",
+            os.path.join(outdir, "phac.md"), "--bundle"]
+    if extra_args:
+        args.extend(extra_args)
+    return subprocess.run(args, capture_output=True, text=True, env=env)
+
+
+class TestDo254BundleProfile(unittest.TestCase):
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def _model(self):
+        return json.load(open(os.path.join(self.tmp, "evidence",
+                                           "model.json")))
+
+    def test_bundle_emits_three_files(self):
+        r = run_build(self.tmp)
+        self.assertEqual(r.returncode, 0, r.stderr[-500:])
+        ev = os.path.join(self.tmp, "evidence")
+        for f in ("model.json", "gates.json", "provenance.json"):
+            self.assertTrue(os.path.exists(os.path.join(ev, f)), f + " missing")
+
+    def test_model_has_phac_content(self):
+        r = run_build(self.tmp)
+        self.assertEqual(r.returncode, 0)
+        m = self._model()
+        self.assertEqual(m["role"], "do254-hardware-engineer")
+        self.assertEqual(m["deliverable_type"],
+                         "Plan for Hardware Aspects of Certification")
+        self.assertIn("assurance_level", m)
+        self.assertIn("aeh_class", m)
+        self.assertEqual(m["aeh_class"], "complex")
+        self.assertEqual(m.get("status"), "draft-for-review")
+
+    def test_gates_all_pass_exit_zero(self):
+        r = run_build(self.tmp)
+        g = json.load(open(os.path.join(self.tmp, "evidence", "gates.json")))
+        self.assertTrue(g["all_pass"])
+        self.assertEqual(g["exit_code"], 0)
+        self.assertGreaterEqual(len(g["gates"]), 5)
+
+    def test_dispatch_crosschecks_when_skills_present(self):
+        if not HAS_SKILLS:
+            self.skipTest("AeroSkills not present")
+        r = run_build(self.tmp)
+        p = json.load(open(os.path.join(self.tmp, "evidence",
+                                        "provenance.json")))
+        self.assertTrue(p["cross_checked"])
+        # all four bound leaves dispatch at least one logic cross-check
+        leaves = {row["leaf"] for row in p["skills"]}
+        for leaf in ("avionics/do254/hardware-planning",
+                     "avionics/do254/verification",
+                     "avionics/do254/configuration-management",
+                     "avionics/do254/requirements-capture"):
+            self.assertIn(leaf, leaves, f"no dispatch row for {leaf}")
+        for row in p["skills"]:
+            self.assertTrue(row["dispatched"])
+            self.assertTrue(row["agrees"], "core/skill disagree: %s" % row)
+
+    def test_standalone_honest_no_skills(self):
+        r = run_build(self.tmp, env_extra={"AEROSKILLS_DEV": "/nonexistent"})
+        self.assertEqual(r.returncode, 0, r.stderr[-500:])
+        p = json.load(open(os.path.join(self.tmp, "evidence",
+                                        "provenance.json")))
+        self.assertFalse(p["cross_checked"])
+        self.assertEqual(len(p["skills"]), 0)
+        g = json.load(open(os.path.join(self.tmp, "evidence", "gates.json")))
+        self.assertTrue(g["all_pass"])
+
+    def test_profile_prepends_context_and_records_customer(self):
+        if not os.path.exists(PROFILE):
+            self.skipTest("profiles/example-airframer.json not present")
+        r = run_build(self.tmp, extra_args=["--profile", PROFILE])
+        self.assertEqual(r.returncode, 0, r.stderr[-500:])
+        md = open(os.path.join(self.tmp, "phac.md")).read()
+        self.assertTrue(md.startswith("## Program context"),
+                        "profile context header must lead the PHAC")
+        self.assertIn("Customer: " + EXPECTED_CUSTOMER, md)
+        m = self._model()
+        self.assertEqual(m["profile"]["customer"], EXPECTED_CUSTOMER)
+        self.assertEqual(m["profile"]["authority"], "FAA")
+        # profiled PHAC still passes the gate-check command
+        c = subprocess.run(
+            [sys.executable, CLI, "check", "--file",
+             os.path.join(self.tmp, "phac.md"), "--dal", "B"],
+            capture_output=True, text=True)
+        self.assertEqual(c.returncode, 0, c.stdout)
+        self.assertIn("RESULT: PASS", c.stdout)
+
+    def test_malformed_profile_fails_loudly(self):
+        bad = os.path.join(self.tmp, "bad-profile.json")
+        with open(bad, "w") as f:
+            json.dump({"program": "no customer here"}, f)
+        r = run_build(self.tmp, extra_args=["--profile", bad])
+        self.assertEqual(r.returncode, 1)
+        self.assertIn("error: bad profile", r.stdout)
+
+    def test_check_still_works(self):
+        r = run_build(self.tmp)
+        self.assertEqual(r.returncode, 0)
+        c = subprocess.run(
+            [sys.executable, CLI, "check", "--file",
+             os.path.join(self.tmp, "phac.md"), "--dal", "B"],
+            capture_output=True, text=True)
+        self.assertEqual(c.returncode, 0, c.stdout)
+        self.assertIn("RESULT: PASS", c.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/do254-hardware-engineer/tests/test_do254_hardware_core.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""Test do254_hardware_core: the executable engine of the DO-254 role.
+
+Proves the role can DO its job standalone (no AeroSkills needed):
+DAL determination, AEH classification, verification expectations,
+configuration management, requirement traceability, PHAC generation,
+and evidence-gate checks.
+"""
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                                "..", "core"))
+from do254_hardware_core import (  # noqa: E402
+    SEVERITY_TO_DAL, build_phac, capture_readiness, check_phac,
+    check_phac_markdown, classify_aeh, classify_derived, cm_actions,
+    coverage_adequate, coverage_ratio, example_item,
+    example_phac_markdown, hci_entry, hw_change_class,
+    independence_required, life_cycle_data, planning_artifacts,
+    render_phac_markdown, req_issues, traceability_summary,
+    verification_complete, verification_methods_for,
+)
+
+
+class TestCoreDomainRules(unittest.TestCase):
+
+    def test_severity_to_dal_mapping(self):
+        self.assertEqual(SEVERITY_TO_DAL["catastrophic"], "A")
+        self.assertEqual(SEVERITY_TO_DAL["hazardous"], "B")
+        self.assertEqual(SEVERITY_TO_DAL["major"], "C")
+        self.assertEqual(SEVERITY_TO_DAL["minor"], "D")
+        self.assertEqual(SEVERITY_TO_DAL["no-safety-effect"], "E")
+
+    def test_aeh_classification_complex(self):
+        # programmable logic / internal state / not fully verifiable from
+        # top data / safety significant => complex (full process)
+        self.assertEqual(classify_aeh(True, False, True, False), "complex")
+        self.assertEqual(classify_aeh(False, True, True, False), "complex")
+        self.assertEqual(classify_aeh(False, False, False, False), "complex")
+        self.assertEqual(classify_aeh(False, False, True, True), "complex")
+        self.assertEqual(classify_aeh(False, False, True, False), "simple")
+
+    def test_planning_artifacts(self):
+        self.assertIn("phac", planning_artifacts("complex"))
+        self.assertNotIn("detailed-design", planning_artifacts("simple"))
+        self.assertIn("verification", planning_artifacts("simple"))
+
+    def test_verification_methods(self):
+        self.assertEqual(verification_methods_for("complex", "B"),
+                         {"test", "analysis", "review"})
+        self.assertEqual(verification_methods_for("simple", "B"),
+                         {"review"})
+
+    def test_coverage_ratios(self):
+        self.assertEqual(coverage_ratio("A"), 0.98)
+        self.assertEqual(coverage_ratio("B"), 0.98)
+        self.assertEqual(coverage_ratio("C"), 0.95)
+        self.assertEqual(coverage_ratio("D"), 0.95)
+        self.assertIsNone(coverage_ratio("E"))
+
+    def test_independence(self):
+        self.assertTrue(independence_required("A"))
+        self.assertTrue(independence_required("B"))
+        self.assertFalse(independence_required("C"))
+        self.assertFalse(independence_required("D"))
+
+    def test_coverage_adequate(self):
+        self.assertTrue(coverage_adequate("A", 0.99))
+        self.assertFalse(coverage_adequate("A", 0.97))
+        self.assertTrue(coverage_adequate("E", 0.0))  # no target
+
+    def test_verification_complete(self):
+        self.assertTrue(verification_complete(
+            ["test", "analysis", "review"], ["test", "review"]))
+        self.assertFalse(verification_complete(["review"], ["test"]))
+
+    def test_life_cycle_scope(self):
+        self.assertGreater(len(life_cycle_data("A")),
+                           len(life_cycle_data("D")))
+        self.assertIn("plan for hardware aspects of certification (PHAC)",
+                      life_cycle_data("B"))
+
+
+class TestConfigManagementRules(unittest.TestCase):
+
+    def test_change_class_1_conditions(self):
+        # functional change => class 1
+        self.assertEqual(hw_change_class(
+            {"hardware_class": "simple", "safety_effect": "none",
+             "functional_change": True})["class"], 1)
+        # safety effect alone forces class 1
+        self.assertEqual(hw_change_class(
+            {"hardware_class": "simple", "safety_effect": "minor",
+             "functional_change": False})["class"], 1)
+        # complex hardware => class 1
+        self.assertEqual(hw_change_class(
+            {"hardware_class": "complex", "safety_effect": "none",
+             "functional_change": False})["class"], 1)
+
+    def test_change_class_2(self):
+        self.assertEqual(hw_change_class(
+            {"hardware_class": "simple", "safety_effect": "none",
+             "functional_change": False})["class"], 2)
+
+    def test_cm_actions_map(self):
+        c1 = cm_actions(1)
+        self.assertTrue(c1["reverification_required"])
+        self.assertTrue(c1["independent_review"])
+        c2 = cm_actions(2)
+        self.assertFalse(c2["reverification_required"])
+        self.assertFalse(c2["independent_review"])
+        self.assertTrue(c2["ecr_required"])  # documented ECR still required
+
+    def test_hci_entry_format(self):
+        self.assertEqual(hci_entry("HW-A", "Rev B", "BL-1"),
+                         "HW-A Rev B BL-1")
+
+
+class TestRequirementsRules(unittest.TestCase):
+
+    def test_vague_wording_flagged(self):
+        self.assertIn("vague", req_issues(
+            {"id": "R1", "text": "The item shall be suitable for flight.",
+             "traceable": True}))
+        self.assertNotIn("vague", req_issues(
+            {"id": "R2", "text": "The item shall assert the output.",
+             "traceable": True}))
+
+    def test_missing_id_and_trace(self):
+        issues = req_issues({"id": "", "text": "Req without id.",
+                             "traceable": False})
+        self.assertIn("missing-id", issues)
+        self.assertIn("not-traceable", issues)
+
+    def test_derived_classification(self):
+        self.assertEqual(classify_derived(True), "allocated")
+        self.assertEqual(classify_derived(False), "derived")
+
+    def test_capture_readiness(self):
+        reqs = [
+            {"id": "R1", "text": "clean requirement one", "traceable": True},
+            {"id": "R2", "text": "clean requirement two", "traceable": True},
+            {"id": "R3", "text": "vague and adequate wording",
+             "traceable": True},
+        ]
+        ready, score = capture_readiness(reqs)
+        self.assertAlmostEqual(score, 2 / 3)
+        self.assertFalse(ready)  # below 0.7 threshold
+
+    def test_traceability_summary(self):
+        item = example_item()
+        t = traceability_summary(item.requirements)
+        self.assertEqual(t["total"], 12)
+        self.assertEqual(t["allocated"], 10)
+        self.assertEqual(t["derived"], 2)
+        self.assertTrue(t["allocated_traced_complete"])
+        self.assertTrue(t["derived_justified_complete"])
+        self.assertTrue(t["ready"])
+
+
+class TestPhacBuilder(unittest.TestCase):
+
+    def test_example_level_b_complex(self):
+        model = build_phac(example_item())
+        self.assertEqual(model["assurance_level"], "B")
+        self.assertEqual(model["aeh_class"], "complex")
+        self.assertEqual(model["coverage_ratio"], 0.98)
+        self.assertEqual(model["status"], "draft-for-review")
+
+    def test_phac_has_required_sections(self):
+        md = example_phac_markdown()
+        for sec in ["## 1. Scope", "## 5. Requirements capture",
+                    "## 7. Verification strategy",
+                    "## 8. Configuration management",
+                    "## 11. Objectives summary"]:
+            self.assertIn(sec, md)
+        self.assertIn("not an approval", md.lower())
+
+    def test_core_gates_all_pass(self):
+        model = build_phac(example_item())
+        gates = check_phac(model)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_markdown_gates_all_pass(self):
+        md = example_phac_markdown()
+        gates = check_phac_markdown(md, "B")
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_standalone_no_skills_repo(self):
+        # Core must work with no AeroSkills present: set env to a bad path.
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = build_phac(example_item())
+        self.assertIn(model["assurance_level"], "ABCDE")
+        md = render_phac_markdown(model)
+        self.assertGreater(len(md), 1000)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/do254-hardware-engineer/tests/test_role_do254_hardware.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Role test: DO-254 Airborne Electronic Hardware 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. Evidence-gate smoke: the example complex CPLD/FPGA LRU item produces
+   a complete PHAC skeleton with no blank sections.
+"""
+import os
+import re
+import sys
+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", "do254-hardware-engineer")
+PHAC_TEMPLATE = os.path.join(ROLE_DIR, "templates", "phac-template.md")
+
+EXPECTED_BOUND = [
+    "avionics/do254/hardware-planning",
+    "avionics/do254/requirements-capture",
+    "avionics/do254/verification",
+    "avionics/do254/configuration-management",
+]
+
+EXPECTED_STAGES = [
+    "Hardware planning", "Requirements capture", "Verification strategy",
+    "Configuration management", "Process assurance",
+    "Certification liaison",
+]
+
+
+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 TestDo254HardwareRole(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}")
+            # every bound leaf ships a logic file the CLI can dispatch
+            scripts = os.path.join(AEROSKILLS, "skills", leaf, "scripts")
+            logic = [f for f in os.listdir(scripts)
+                     if f.endswith("_logic.py")]
+            self.assertTrue(logic, f"bound leaf lacks 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()
+        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(PHAC_TEMPLATE):
+            self.fail("phac-template.md missing")
+        text = open(PHAC_TEMPLATE).read()
+        for n in range(1, 12):
+            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("document", low)
+        self.assertNotIn("___", text)  # zero blanks
+
+    def test_forbidden_lines_present(self):
+        role = read_role_md()
+        for phrase in ["issue certification approval", "regulatory sign-off",
+                       "reproduce proprietary", "sign_off_required: true"]:
+            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()