aero-agent-roles 1.0.0

package/roles/do254-hardware-engineer/ROLE.md

@@ -0,0 +1,127 @@
+---
+type: role
+name: do254-hardware-engineer
+title: "DO-254 Airborne Electronic Hardware Engineer"
+status: draft
+domain: avionics
+deliverable_type: "Plan for Hardware Aspects of Certification (PHAC) + design assurance evidence set"
+standards_bound:
+  - id: do-254
+    tier: TIER-2
+    reference-only: true
+  - id: arp4754a
+    reference-only: true
+skills_bound:
+  - avionics/do254/hardware-planning
+  - avionics/do254/requirements-capture
+  - avionics/do254/verification
+  - avionics/do254/configuration-management
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "issue certification approval"
+  - "claim regulatory sign-off"
+  - "reproduce proprietary RTCA/EUROCAE text"
+  - "assert DAL without evidence"
+sign_off_required: true
+license: Apache-2.0
+compatibility: "agentskills.io ROLE.md; any SKILL.md host"
+metadata:
+  version: 0.1.0
+  author: ashfordeOU
+  skills_release: "v1.3.0+"
+---
+
+# DO-254 Airborne Electronic Hardware Engineer
+
+## Role identity
+
+This role drives the DO-254 design assurance workflow for an airborne
+electronic hardware (AEH) item: from classification (simple vs complex
+AEH) and planning through requirements capture, verification,
+configuration management, and the Plan for Hardware Aspects of
+Certification (PHAC). Use when a project must produce DO-254-compliant
+hardware evidence for CPLD/FPGA/ASIC-based items or other AEH. Do NOT
+use for software-only items (see DO-178C role) or when no cert basis
+exists.
+
+## Deliverable contract
+
+The role produces:
+
+1. **PHAC (Plan for Hardware Aspects of Certification)** — original
+   skeleton per templates/phac-template.md: hardware design assurance
+   level (DAL A-E per function failure), AEH class, life cycle data,
+   verification strategy with coverage ratios and independence, CM
+   approach, liaison with airworthiness.
+2. **Design assurance evidence set** — requirement traceability health
+   (allocated vs derived), verification coverage vs the level's ratio,
+   configuration index input.
+3. **Gap report** — what is missing before the human hardware cert
+   engineer signs.
+
+## Workflow (stages → bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Hardware planning | do254/hardware-planning | AEH class (simple/complex), PHAC scope, artifact set |
+| 2. Requirements capture | do254/requirements-capture | requirement issue list, derived-vs-allocated classification, readiness verdict |
+| 3. Verification strategy | do254/verification | verification methods, coverage ratio (0.98 A/B, 0.95 C/D), independence |
+| 4. Configuration management | do254/configuration-management | change class, ECR/ECO path, HCI entries, baseline control |
+| 5. Process assurance | core engine | process assurance records plan |
+| 6. Certification liaison | core engine | PHAC input, open items for the cert authority |
+
+## Evidence gates
+
+- Stage 1 done = item classified with evidence, DAL identified WITH the
+  system-safety output (FHA/PSSA), PHAC skeleton filled.
+- Stage 2 done = every allocated requirement traced upward, every
+  derived requirement identified AND justified, readiness score >= 0.7.
+- Stage 3 done = verification methods + coverage ratio + independence
+  stated for the item's class and level.
+- Stage 4 done = change-class rule and HCI format applied.
+- FINAL = every section of the deliverable has a source (skill +
+  standard reference); nothing asserted without a checkable basis.
+
+## Boundary / forbidden
+
+- NEVER issue certification approval — the DER/regulator signs.
+- NEVER reproduce DO-254 text (proprietary, RTCA/EUROCAE). Summaries and
+  original structure only.
+- NEVER assert a DAL without the system-safety evidence trail.
+- Output is a DRAFT for human review — mark it draft.
+
+## Verification
+
+The role runs STANDALONE: `core/do254_hardware_core.py` is an executable
+engine that determines DAL from failure severity, classifies AEH,
+computes verification expectations, CM depth, requirement traceability,
+BUILDS the PHAC, and gate-checks deliverables. No AeroSkills checkout
+required. When the AeroSkills library is present, the CLI dispatches the
+four bound do254 leaves' logic files and cross-checks 8 computations
+(classification, coverage, methods, independence, change class, HCI
+entry, readiness, derived classification).
+
+Run the role:
+```bash
+python3 cli.py build --out phac.md                     # example item (DAL B, complex AEH)
+python3 cli.py build --failure-condition catastrophic  # DAL A variant
+python3 cli.py build --out phac.md --bundle            # + evidence/{model,gates,provenance}.json
+python3 cli.py check --file phac.md --dal B            # gate-check a PHAC
+```
+
+Tests:
+- tests/test_do254_hardware_core.py: domain rules + PHAC builder +
+  gates + standalone (no skills repo)
+- tests/test_role_do254_hardware.py: bound-skill resolution (skips if
+  the skills repo is absent) + workflow + template present + boundaries
+- tests/test_do254_bundle_profile.py: --bundle evidence protocol +
+  --profile + dispatch cross-checks + standalone honesty
+
+Bound skills in Aero Skills deepen individual stages when the library
+is present (verification logic, CM, requirements capture); the core
+engine does not depend on them.
+
+## Compliance
+
+- do-254 TIER-2 reference-only per standards-map; no verbatim.
+- SOURCES.md records acquisition/extraction/verification status.

package/roles/do254-hardware-engineer/SOURCES.md

@@ -0,0 +1,19 @@
+# SOURCES.md - DO-254 Airborne Electronic Hardware Engineer
+
+Standards and documents this role references. Summary-not-copy: see
+[STANDARDS.md](../../STANDARDS.md) for the full rule and purchase links.
+
+| Source | Role use | Gated |
+|---|---|---|
+| RTCA DO-254 / EUROCAE ED-80 | design assurance of airborne electronic hardware: DAL, AEH classes, life cycle data, verification objectives | true |
+| SAE ARP4754A | development assurance level derivation from failure conditions (shared with systems safety) | true |
+| RTCA DO-178C | hardware/software integration boundary with hosted software | true |
+| FAA AC 20-152A | FAA acceptance of DO-254 for AEH; simple vs complex guidance | false |
+
+Bound AeroSkills leaves under `avionics/do254/` (hardware-planning,
+requirements-capture, verification, configuration-management) encode
+paraphrased common-knowledge summaries of DO-254 practice and are
+dispatched for cross-check by `cli.py` when present. The PHAC template
+in `templates/` is an original structure informed by public-domain
+guidance (AC 20-152A) and summary process knowledge. No proprietary
+text is reproduced.

package/roles/do254-hardware-engineer/cli.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""cli.py - run the DO-254 Airborne Electronic Hardware Engineer role.
+
+Usage:
+  python3 cli.py build --out <file.md>          # build PHAC for the example item
+  python3 cli.py build --out <file.md> --bundle # + evidence/{model,gates,provenance}.json
+  python3 cli.py build --out <file.md> --bundle --profile <profile.json>
+  python3 cli.py check --file <file.md>         # gate-check an existing PHAC
+
+The role ENGINE (core/do254_hardware_core.py) does the work standalone;
+bound avionics/do254 skills in Aero Skills deepen individual stages
+when present and are dispatched for cross-check.
+"""
+import argparse
+import importlib.util
+import json
+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 do254_hardware_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+ROLE_SLUG = "do254-hardware-engineer"
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+HAS_SKILLS = os.path.isdir(os.path.join(AEROSKILLS, "skills"))
+
+# Bound avionics/do254 leaves and their logic files.
+DO254_LEAVES = {
+    "hardware-planning": "avionics/do254/hardware-planning",
+    "verification": "avionics/do254/verification",
+    "configuration-management": "avionics/do254/configuration-management",
+    "requirements-capture": "avionics/do254/requirements-capture",
+}
+
+
+def _load_leaf(leaf: str):
+    """Import a bound leaf's *logic.py module (or None when unavailable)."""
+    if not HAS_SKILLS:
+        return None
+    logic_dir = os.path.join(AEROSKILLS, "skills", DO254_LEAVES[leaf], "scripts")
+    if not os.path.isdir(logic_dir):
+        return None
+    logic_files = sorted(f for f in os.listdir(logic_dir)
+                         if f.endswith("_logic.py"))
+    if not logic_files:
+        return None
+    for lf in logic_files:
+        path = os.path.join(logic_dir, lf)
+        spec = importlib.util.spec_from_file_location(
+            "do254_skill_" + leaf, path)
+        mod = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(mod)
+            return mod
+        except Exception:
+            continue
+    return None
+
+
+def _dispatch_rows(item) -> list:
+    """Dispatch the bound do254 skill logics and compare with the core.
+
+    Cross-check points (each leaf that ships a logic file):
+    1. hardware-planning: classify_aeh -> 'complex' for a programmable
+       logic item (AEH classification).
+    2. verification: coverage ratio adequate at the item's DAL (0.98 at B)
+       and methods required for complex AEH at level B.
+    3. configuration-management: change class for a class-1 change
+       (functional change on complex hardware) + HCI entry format.
+    4. requirements-capture: capture readiness score for the example
+       requirements set.
+    """
+    rows = []
+    item = item or core.example_item()
+    dal = item.assurance_level()
+
+    def add(leaf, function, core_value, skill_value, extra=None):
+        if not isinstance(core_value, (int, float)) or \
+           not isinstance(skill_value, (int, float)):
+            agrees = str(core_value) == str(skill_value)
+            delta = None
+        else:
+            delta = abs(float(core_value) - float(skill_value))
+            agrees = delta <= 1e-6
+        row = {
+            "leaf": DO254_LEAVES[leaf],
+            "skill_md": "SKILL.md",
+            "logic_file": "scripts/" + os.path.basename(
+                _leaf_logic_file(leaf) or ""),
+            "function": function,
+            "dispatched": True,
+            "core_value": core_value if isinstance(core_value, (int, float))
+                          else str(core_value),
+            "skill_value": skill_value if isinstance(skill_value, (int, float))
+                           else str(skill_value),
+            "agrees": agrees,
+            "skills_release": "v1.3.0+",
+        }
+        if delta is not None:
+            row["delta"] = round(delta, 9)
+            row["tolerance"] = 1e-6
+        if extra:
+            row["cross_check_point"] = extra
+        rows.append(row)
+        return row
+
+    hp = _load_leaf("hardware-planning")
+    if hp is not None and hasattr(hp, "classify_aeh"):
+        add("hardware-planning", "classify_aeh",
+            core.classify_aeh(item.has_programmable_logic,
+                              item.has_internal_state,
+                              item.fully_verifiable_from_top_data,
+                              item.safety_significant),
+            hp.classify_aeh(item.has_programmable_logic,
+                            item.has_internal_state,
+                            item.fully_verifiable_from_top_data,
+                            item.safety_significant),
+            "complex AEH classification for programmable-logic item")
+
+    ver = _load_leaf("verification")
+    if ver is not None and hasattr(ver, "requirements_based_coverage_ok"):
+        # 196 of 200 requirements tested at DAL B -> 0.98 ratio met
+        tested, total = 196, 200
+        add("verification", "requirements_based_coverage_ok",
+            int(core.coverage_adequate(dal, tested / total)),
+            int(ver.requirements_based_coverage_ok(tested, total, dal,
+                                                   min_ratio=0.98)),
+            "requirements-based coverage 196/200 at DAL %s" % dal)
+    if ver is not None and hasattr(ver, "verification_methods_for"):
+        core_methods = sorted(core.verification_methods_for("complex", dal))
+        skill_methods = sorted(ver.verification_methods_for("complex", dal))
+        add("verification", "verification_methods_for",
+            ",".join(core_methods), ",".join(skill_methods),
+            "method set for complex AEH at DAL %s" % dal)
+    if ver is not None and hasattr(ver, "independence_required"):
+        add("verification", "independence_required",
+            int(core.independence_required(dal)),
+            int(ver.independence_required(dal)),
+            "independence expectation at DAL %s" % dal)
+
+    cm = _load_leaf("configuration-management")
+    if cm is not None and hasattr(cm, "change_class"):
+        change = {"hardware_class": "complex", "safety_effect": "major",
+                  "functional_change": True}
+        add("configuration-management", "change_class",
+            core.hw_change_class(change)["class"],
+            cm.change_class(change)["class"],
+            "class-1 change on complex hardware")
+    if cm is not None and hasattr(cm, "hci_entry"):
+        add("configuration-management", "hci_entry",
+            core.hci_entry("HW-ITEM-001", "Rev C", "BL-2.0"),
+            cm.hci_entry("HW-ITEM-001", "Rev C", "BL-2.0"),
+            "HCI entry format")
+
+    rc = _load_leaf("requirements-capture")
+    if rc is not None and hasattr(rc, "capture_readiness"):
+        reqs = item.requirements or core.example_requirements()
+        core_ready, core_score = core.capture_readiness(reqs)
+        skill_ready, skill_score = rc.capture_readiness(reqs)
+        add("requirements-capture", "capture_readiness",
+            round(core_score, 6), round(skill_score, 6),
+            "capture readiness score on example requirements")
+        add("requirements-capture", "classify_derived",
+            core.classify_derived(True), rc.classify_derived(True),
+            "allocated-vs-derived classification")
+
+    return rows
+
+
+def _leaf_logic_file(leaf: str) -> str:
+    """Return the basename of a leaf's logic file (best effort)."""
+    if not HAS_SKILLS:
+        return ""
+    logic_dir = os.path.join(AEROSKILLS, "skills", DO254_LEAVES[leaf], "scripts")
+    if os.path.isdir(logic_dir):
+        files = sorted(f for f in os.listdir(logic_dir)
+                       if f.endswith("_logic.py"))
+        if files:
+            return files[0]
+    return ""
+
+
+def _provenance(item, rows):
+    dispatched_rows = [r for r in rows if r.get("dispatched")]
+    all_agree = bool(dispatched_rows) and all(
+        r.get("agrees") for r in dispatched_rows)
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/do254_hardware_core.py",
+            "functions": ["classify_aeh", "coverage_adequate",
+                          "verification_methods_for", "independence_required",
+                          "hw_change_class", "hci_entry",
+                          "capture_readiness", "build_phac", "check_phac"],
+            "version": "0.1.0",
+        },
+        "skills": rows,
+        "cross_checked": all_agree,
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+def cmd_build(args):
+    item = core.example_item()
+    # allow overriding the failure condition from CLI for different DALs
+    if args.failure_condition:
+        item.failure_condition = args.failure_condition
+        item.system_safety_ref = args.safety_ref or item.system_safety_ref
+    model = core.build_phac(item)
+    md = core.render_phac_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_phac(model)
+    rows = _dispatch_rows(item)
+
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md)
+        print(f"built PHAC (level {model['assurance_level']}, "
+              f"{model['aeh_class']} AEH) -> {args.out}")
+        if profile:
+            print(f"profile: {profile.get('customer')} / "
+                  f"{profile.get('program')}")
+        print(f"gates: all_pass={gates['all_pass']} {gates}")
+        if rows:
+            n_agree = sum(1 for r in rows if r.get("agrees"))
+            print(f"skill dispatch: {n_agree}/{len(rows)} cross-checks agree")
+        else:
+            print("skill dispatch: no AeroSkills logic available "
+                  "(standalone)")
+        if args.bundle:
+            prov = _provenance(item, rows)
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG,
+                "Plan for Hardware Aspects of Certification",
+                model, gates, 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()
+    dal = (args.dal or "B").upper()
+    gates = core.check_phac_markdown(md, dal)
+    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="DO-254 Hardware 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("--failure-condition", default="",
+                   help="hazardous/major/minor/...")
+    b.add_argument("--safety-ref", default="", help="system safety reference")
+    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="PHAC markdown file to gate-check")
+    c.add_argument("--dal", default="", help="expected design assurance level")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()