aero-agent-roles 1.0.0

package/roles/state-estimation-engineer/templates/nav-state-estimator-design-template.md

@@ -0,0 +1,76 @@
+# Navigation State Estimator Design Report
+
+**Item:** UAV navigation state estimator (INS/GNSS + AHRS)
+**Estimator class:** attitude (complementary filter) + loosely-coupled GNSS/INS
+**Vehicle / platform:** small fixed-wing UAV (autopilot reference design)
+**Intended use:** design analysis for the navigation state estimator before implementation on the flight computer
+**Status:** draft-for-review
+
+## 1. Scope
+
+This report produces the navigation state estimator design for UAV navigation state estimator (INS/GNSS + AHRS). Loosely-coupled GNSS/INS navigation filter with a complementary-filter attitude channel for a small fixed-wing UAV autopilot. The estimator architecture is attitude (complementary filter) + loosely-coupled GNSS/INS: an attitude channel (complementary filter) plus a loosely-coupled GNSS position/velocity channel (linear constant-velocity Kalman recursion with an EKF nonlinear-update option). Outputs are DRAFT design numbers for a human navigation engineer to review before implementation on the target computer.
+
+## 2. Design inputs (noise model)
+
+- Navigation update interval dt = 1 s over a 60-step design horizon.
+- Process noise intensity q = 0.01 m^2/s^3 -> sigma_w = 0.1 m/s^2.
+- Measurement variance r = 4 m^2 (GNSS position, sigma_v = 2.0 m).
+- Initial covariance P0 = diag(100 m^2, 25 (m/s)^2).
+- IMU/attitude rate dt = 0.01 s; attitude design horizon 100 s.
+- Particle fallback count n = 1000.
+
+## 3. Attitude channel (complementary filter)
+
+- Filter: Mahony-style explicit complementary filter (SO(3)).
+- Gains: k_p = 2 1/s, k_i = 0.4 1/s^2 (leaf module defaults); corrected rate omega_c = omega_m - b + k_p*e with bias step b <- b - k_i*e*dt.
+- Gyro bias input b = [0.001, -0.0008, 0.0006] rad/s per axis, |b| = 0.001414 rad/s.
+- Drift anchor: uncompensated bias integrates to |b|*t = 0.014142 rad after 10 s and 0.141421 rad (8.103 deg) after 100 s - the error the bias estimate removes.
+- Discrete-integration lag bound |omega|*dt = 0.000229 rad/step (0.013121 deg/step) at the example body rate.
+- Steady-state acceptance: trailing-window innovation norm below 0.001 rad (leaf steady_state_verdict).
+- Observability note: gyro bias is observable when at least two non-parallel reference vectors (accelerometer + magnetometer) are fused; a single reference leaves the bias along its axis unobservable (Mahony et al. 2008 nonlinear complementary filter on SO(3)).
+
+## 4. Navigation channel (Kalman recursion)
+
+- Model: discrete constant-velocity, H = [1 0], per axis.
+- Transition F = [1.0, 1.0] / [0.0, 1.0]; discretized process covariance Q = [0.0025, 0.005] / [0.005, 0.01].
+- Alpha-beta design companion (fixed-gain alternative for the smoothing stage): alpha = 0.5, Benedict-Bordner critical-damping beta = alpha^2/(2-alpha) = 0.166667; tracking index lambda = sigma_w*dt^2/sigma_v = 0.05 gives Kalata gains alpha = 0.270867, beta = 0.042695.
+- First update: gain K = [0.968992849, 0.193833453], innovation variance S = 129.0025, position variance after 3.875971396 m^2.
+- Mid-horizon (step 30): gain K = [0.270963014, 0.042713764], S = 5.486690082, position variance 1.083852057 m^2.
+- Final (step 60): gain K = [0.270867122, 0.042694639], S = 5.4859685, position variance 1.083468489 m^2, velocity variance variance 0.058442889 (m/s)^2 - the steady-state covariance the design reports. The converged gain equals the Kalata alpha-beta pair above within the recursion tolerance, confirming the fixed-gain design is a faithful steady-state approximation of the full recursion.
+- Residual RMS over the deterministic design run: 0.087482 m.
+
+## 5. Nonlinear update design (EKF linearization)
+
+- Measurement model: range + bearing (nonlinear) h(x) = [hypot(px,py), atan2(py,px)].
+- Operating point x = [300.0, 40.0, 12.0, 0.0] (true measurement [302.6549, 0.132552]).
+- Linearized measurement Jacobian (central differences) H = [0.991227893, 0.132163706, 0.0, 0.0] / [-0.000436681, 0.003275109, 0.0, 0.0].
+- Deterministic measurement z = [305.6549, 0.132552] (range biased +3 m input).
+- Innovation y = [3.0, 0.0]; innovation covariance diag(S) = [108.99999803, 0.00139632].
+- Gain first row K = [0.909383403, -31.273707682].
+- Corrected state x+ = [302.72815, 40.363753, 12.0, 0.0].
+
+## 6. Consistency and fallback verification
+
+- NEES = 0.9174 against the 2-state position subspace (expected value n = 2 for a consistent filter).
+- SIR particle fallback: uniform ensemble of 1000 particles gives ESS = 1000; resample when ESS < n/2 (SIR, particle-filter leaf) (threshold 500).
+- IMM two-mode bank (two-mode CV/CA IMM bank with Markov mode mixing for maneuvering flight).
+- UKF option (scaled-unscented-transform alternative to EKF linearization for strongly nonlinear updates).
+
+## 7. Offline post-processing (RTS smoothing)
+
+- Method: fixed-interval RTS smoother over stored forward run.
+- Smoothed position variance at the final boundary equals the filtered value (True); every interior smoothed variance at or below the filtered (True).
+- Maximum covariance reduction: 82.946% (smoothed final position variance 1.083468489 m^2).
+
+## 8. Observability analysis
+
+- Discrete observability matrix rows [1.0, 0.0] / [1.0, 1.0] with determinant 1.0.
+- Verdict: rank 2, fully observable for dt > 0: the velocity state is observable through the dynamics between position samples.
+
+## 9. Verification evidence and open items
+
+- Evidence gates (see cli.py check): architecture stated, attitude + navigation channels designated, alpha-beta and Kalman/EKF numbers present, observability checked, consistency metrics present.
+- Open items for the human navigation engineer: final sensor datasheet noise values, lever-arm and time-tagging alignment, flight-computer numerical format, and the in-flight consistency monitoring policy.
+
+---
+*Generated by Aero Agent Roles state-estimation-engineer core (2026-09-05). DRAFT for human navigation engineer review. Not an approval document. Not flight software release.*

package/roles/state-estimation-engineer/tests/test_bundle_protocol.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Test the evidence bundle + skill-dispatch protocol (PROTOCOL.md v1).
+
+Verifies:
+- build --bundle emits evidence/{model,gates,provenance}.json
+- bundle JSON parses, model contains computed numbers, gates all_pass
+- skill dispatch cross-checks the estimator computations against the
+  bound estimation-filtering leaf logic (agreeing within tolerance)
+  when AeroSkills is present
+- standalone (no AeroSkills) emits the bundle honestly with
+  cross_checked=false
+- check --file passes the gate vocabulary
+"""
+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")
+
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+HAS_SKILLS = os.path.isdir(os.path.join(AEROSKILLS, "skills"))
+
+EXPECTED_DISPATCH_FNS = ["steady_state_gains", "gains_from_tracking_index",
+                         "forward_kalman", "jacobian_h", "nees",
+                         "effective_sample_size"]
+
+
+def run_build(outdir, env_extra=None):
+    env = dict(os.environ)
+    if env_extra:
+        env.update(env_extra)
+    args = [sys.executable, CLI, "build", "--out",
+            os.path.join(outdir, "report.md"), "--bundle"]
+    return subprocess.run(args, capture_output=True, text=True, env=env)
+
+
+class TestBundleProtocol(unittest.TestCase):
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    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_numbers_and_status(self):
+        run_build(self.tmp)
+        m = json.load(open(os.path.join(self.tmp, "evidence", "model.json")))
+        self.assertIn("kalman", m)
+        self.assertIn("final", m["kalman"])
+        self.assertIn("gain", m["kalman"]["final"])
+        self.assertEqual(m.get("status"), "draft-for-review")
+        self.assertIn("role", m)
+        self.assertIn("ekf", m)
+
+    def test_gates_all_pass_exit_zero(self):
+        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)
+        self.assertEqual(r.returncode, 0, r.stderr[-500:])
+        p = json.load(open(os.path.join(self.tmp, "evidence",
+                                        "provenance.json")))
+        self.assertTrue(p["cross_checked"])
+        self.assertGreaterEqual(len(p["skills"]), 5)
+        fns = [row["function"] for row in p["skills"]]
+        for fn in EXPECTED_DISPATCH_FNS:
+            self.assertIn(fn, fns, f"dispatch row missing: {fn}")
+        for row in p["skills"]:
+            self.assertTrue(row["dispatched"])
+            self.assertTrue(row["agrees"], "core/skill disagree: %s" % row)
+            self.assertLessEqual(row["delta"], 1e-6)
+
+    def test_standalone_honest_no_skills(self):
+        r = run_build(self.tmp, env_extra={"AEROSKILLS_DEV": "/nonexistent"})
+        self.assertEqual(r.returncode, 0)
+        p = json.load(open(os.path.join(self.tmp, "evidence",
+                                        "provenance.json")))
+        self.assertFalse(p["cross_checked"])
+        self.assertEqual(len(p["skills"]), 0)
+
+    def test_check_still_works(self):
+        run_build(self.tmp)
+        md = os.path.join(self.tmp, "report.md")
+        c = subprocess.run([sys.executable, CLI, "check", "--file", md],
+                           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/state-estimation-engineer/tests/test_role_state_estimation_engineer.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Role test: State Estimation 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 complete (no blanks, draft
+   markers, sections) and the role carries the executable anatomy.
+4. The core engine builds the example deliverable standalone.
+"""
+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/)
+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", "state-estimation-engineer")
+TEMPLATE = os.path.join(ROLE_DIR, "templates",
+                        "nav-state-estimator-design-template.md")
+CORE_DIR = os.path.join(ROLE_DIR, "core")
+
+sys.path.insert(0, CORE_DIR)
+import state_estimation_core  # noqa: E402
+
+EXPECTED_BOUND = [
+    "gnc-autonomy/estimation-filtering/alpha-beta-filter",
+    "gnc-autonomy/estimation-filtering/complementary-filter",
+    "gnc-autonomy/estimation-filtering/extended-kalman-filter",
+    "gnc-autonomy/estimation-filtering/interacting-multiple-model-filter",
+    "gnc-autonomy/estimation-filtering/particle-filter",
+    "gnc-autonomy/estimation-filtering/rts-smoother",
+    "gnc-autonomy/estimation-filtering/unscented-kalman-filter",
+]
+
+EXPECTED_STAGES = [
+    "1. Architecture + noise model", "2. Attitude channel",
+    "3. Navigation channel", "4. Fixed-gain companion",
+    "5. Nonlinear updates", "6. Fallbacks",
+    "7. Offline post-processing", "8. Observability", "9. Report",
+]
+
+
+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 TestStateEstimationEngineerRole(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}")
+
+    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()
+        wf = role[role.find("## Workflow"):role.find("## Evidence gates")]
+        idx = [wf.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):
+        self.assertTrue(os.path.exists(TEMPLATE),
+                        "deliverable template missing")
+        text = open(TEMPLATE).read()
+        for n in range(1, 10):
+            self.assertTrue(
+                re.search(rf"^## {n}\. ", text, re.M),
+                f"report section {n} missing")
+        self.assertIn("Navigation State Estimator Design Report", text)
+        self.assertNotIn("___", text)
+        low = text.lower()
+        self.assertIn("draft", low)
+        self.assertIn("not an approval", low)
+        self.assertIn("estimator class", low)
+
+    def test_forbidden_lines_present(self):
+        role = read_role_md()
+        for phrase in ["release navigation/flight software",
+                       "authorize flight", "claim certification approval",
+                       "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")
+
+    def test_author_attribution(self):
+        role = read_role_md()
+        self.assertIn("author: ashfordeOU", role)
+
+    def test_example_deliverable_builds_and_gates(self):
+        """The engine produces the deliverable standalone and gates pass."""
+        model = state_estimation_core.build_report(
+            state_estimation_core.example_item())
+        md = state_estimation_core.render_report_markdown(model)
+        self.assertGreater(len(md), 3000)
+        self.assertTrue(state_estimation_core.check_report(model)["all_pass"])
+        self.assertTrue(state_estimation_core.check_report_markdown(md)["all_pass"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/roles/state-estimation-engineer/tests/test_state_estimation_engineer_core.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+"""Test state_estimation_core: the executable engine of the role.
+
+Proves the role can DO its job standalone (no AeroSkills needed):
+alpha-beta gain rules (Benedict-Bordner, Kalata), the discrete
+constant-velocity Kalman recursion, EKF linearization, NEES/ESS
+consistency metrics, RTS smoothing, observability, report generation,
+and the 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 state_estimation_core import (  # noqa: E402
+    build_report, check_report, check_report_markdown,
+    effective_sample_size, example_item, example_report_markdown,
+    kalata_gains, nees, numeric_jacobian, observability_rank,
+    render_report_markdown, run_cv_kalman, rts_smooth, steady_state_beta,
+    steady_state_verdict, tracking_index_from_noise,
+)
+
+
+class TestAlphaBetaRules(unittest.TestCase):
+
+    def test_benedict_bordner_beta(self):
+        # beta = alpha^2 / (2 - alpha); at alpha = 0.5 -> 1/6.
+        self.assertAlmostEqual(steady_state_beta(0.5), 0.25 / 1.5)
+        self.assertAlmostEqual(steady_state_beta(0.3),
+                               0.09 / 1.7)
+
+    def test_benedict_bordner_invalid_alpha(self):
+        with self.assertRaises(ValueError):
+            steady_state_beta(2.0)
+        with self.assertRaises(ValueError):
+            steady_state_beta(0.0)
+
+    def test_kalata_gains_zero_index(self):
+        self.assertEqual(kalata_gains(0.0)["alpha"], 0.0)
+        self.assertEqual(kalata_gains(0.0)["beta"], 0.0)
+
+    def test_kalata_gains_match_leaf_example(self):
+        # alpha-beta leaf worked formula: lambda = 0.05 -> alpha~0.270867
+        g = kalata_gains(0.05)
+        self.assertAlmostEqual(g["alpha"], 0.270867119, places=6)
+        self.assertAlmostEqual(g["beta"], 0.042694639, places=6)
+
+    def test_tracking_index_definition(self):
+        # lambda = sigma_w*dt^2/sigma_v (leaf definition)
+        self.assertAlmostEqual(tracking_index_from_noise(0.1, 1.0, 2.0),
+                               0.05)
+        with self.assertRaises(ValueError):
+            tracking_index_from_noise(0.1, 1.0, 0.0)
+
+
+class TestKalmanRecursion(unittest.TestCase):
+
+    def test_recursion_converges_to_kalata_gains(self):
+        # The converged CV-Kalman gain equals the Kalata alpha-beta pair
+        # for the same sigma_w*dt^2/sigma_v tracking index.
+        recs = run_cv_kalman([0.5 * k for k in range(1, 61)], 1.0,
+                             0.01, 4.0, [0.0, 0.0],
+                             [[100.0, 0.0], [0.0, 25.0]])
+        k = kalata_gains(0.05)
+        self.assertAlmostEqual(recs[-1]["gain"][0], k["alpha"], places=6)
+        self.assertAlmostEqual(recs[-1]["gain"][1], k["beta"], places=6)
+
+    def test_covariance_decreases(self):
+        recs = run_cv_kalman([1.0] * 20, 1.0, 0.01, 4.0)
+        self.assertGreater(recs[0]["P_filt"][0][0],
+                           recs[-1]["P_filt"][0][0])
+        self.assertLess(recs[-1]["P_filt"][0][0], 4.0)  # below R
+
+    def test_first_gain_uses_initial_covariance(self):
+        # P_pred = F P0 F^T + Q -> [0][0] = P0_xx + 2*dt*P0_xv +
+        # dt^2*P0_vv + q*dt^4/4 = 125.0025 at the defaults.
+        recs = run_cv_kalman([1.0] * 5, 1.0, 0.01, 4.0,
+                             [0.0, 0.0], [[100.0, 0.0], [0.0, 25.0]])
+        self.assertAlmostEqual(recs[0]["gain"][0], 125.0025 / 129.0025)
+
+    def test_invalid_inputs(self):
+        with self.assertRaises(ValueError):
+            run_cv_kalman([1.0], 0.0, 0.01, 4.0)
+        with self.assertRaises(ValueError):
+            run_cv_kalman([], 1.0, 0.01, 4.0)
+        with self.assertRaises(ValueError):
+            run_cv_kalman([1.0], 1.0, 0.01, 0.0)
+
+
+class TestEKFAndMetrics(unittest.TestCase):
+
+    def test_numeric_jacobian_matches_analytic_range_derivative(self):
+        # dr/dpx = px/hypot(px, py) at the operating point.
+        op = [300.0, 40.0]
+        px, py = op
+        r = (px * px + py * py) ** 0.5
+        j = numeric_jacobian(lambda x: [(x[0] ** 2 + x[1] ** 2) ** 0.5], op)
+        self.assertAlmostEqual(j[0][0], px / r, places=6)
+
+    def test_ekf_correction_reduces_position_uncertainty(self):
+        model = build_report(example_item())
+        ek = model["ekf"]
+        self.assertTrue(ek["x_corrected"][0] > 0.0)
+        # innovation equals the deterministic +3 m range bias
+        self.assertAlmostEqual(ek["innovation"][0], 3.0, places=6)
+
+    def test_nees_zero_for_exact_estimate(self):
+        self.assertAlmostEqual(
+            nees([1.0, 2.0], [[1.0, 0.0], [0.0, 1.0]], [1.0, 2.0]), 0.0)
+
+    def test_nees_matches_ukf_leaf_criterion(self):
+        # 2-state example: NEES of (5, -2) error with P = 100*I is
+        # (25 + 4)/100 = 0.29, well below the expected n = 2.
+        v = nees([300.0, 40.0], [[100.0, 0.0], [0.0, 100.0]],
+                 [295.0, 42.0])
+        self.assertAlmostEqual(v, 0.29, places=6)
+
+    def test_ess_uniform_ensemble(self):
+        # ESS = (sum w)^2/sum(w^2); uniform n=1000 -> 1000.
+        w = [1.0 / 1000.0] * 1000
+        self.assertAlmostEqual(effective_sample_size(w), 1000.0, places=4)
+
+    def test_ess_degenerate(self):
+        w = [1.0, 0.0, 0.0, 0.0]
+        self.assertAlmostEqual(effective_sample_size(w), 1.0, places=9)
+        with self.assertRaises(ValueError):
+            effective_sample_size([])
+
+    def test_steady_state_verdict(self):
+        # Converged: trailing-window (last min(10,n)) mean below tol.
+        norms = [1e-2] + [1e-4] * 10   # transient then 10 quiet steps
+        self.assertTrue(steady_state_verdict(norms, 1e-3))
+        self.assertFalse(steady_state_verdict([1e-2, 2e-3, 3e-3, 2e-3], 1e-3))
+        with self.assertRaises(ValueError):
+            steady_state_verdict([], 1e-3)
+        with self.assertRaises(ValueError):
+            steady_state_verdict([1e-4], 0.0)
+
+
+class TestSmoothingAndObservability(unittest.TestCase):
+
+    def test_smoother_reduces_covariance(self):
+        model = build_report(example_item())
+        sm = model["smoothing"]
+        self.assertTrue(sm["all_reduced"])
+        self.assertTrue(sm["boundary_matches"])
+        self.assertGreater(sm["max_reduction"], 0.0)
+
+    def test_smoother_matches_filter_at_boundary(self):
+        recs = run_cv_kalman([0.5 * k for k in range(1, 11)], 1.0,
+                             0.01, 4.0)
+        out = rts_smooth([dict(r, dt=1.0) for r in recs])
+        self.assertAlmostEqual(out["smoothed_covs"][-1][0][0],
+                               recs[-1]["P_filt"][0][0], places=12)
+        self.assertEqual(len(out["smoothed_states"]), len(recs))
+
+    def test_observability(self):
+        o = observability_rank(1.0)
+        self.assertEqual(o["rank"], 2)
+        self.assertTrue(o["observable"])
+        self.assertAlmostEqual(o["det"], 1.0)
+
+
+class TestReportBuilderAndGates(unittest.TestCase):
+
+    def test_example_builds_complete_model(self):
+        model = build_report(example_item())
+        self.assertEqual(model["status"], "draft-for-review")
+        self.assertEqual(model["document_type"],
+                         "Navigation State Estimator Design Report")
+        self.assertTrue(model["estimator_class"])
+        self.assertIn("kalman", model)
+        self.assertIn("ekf", model)
+        self.assertIn("attitude", model)
+        self.assertIn("alpha_beta", model)
+
+    def test_example_numbers_present(self):
+        model = build_report(example_item())
+        km = model["kalman"]["final"]
+        self.assertGreater(km["gain"][0], 0.0)
+        self.assertGreater(km["pos_var_after"], 0.0)
+        self.assertTrue(model["observability"]["observable"])
+        self.assertIsInstance(model["ekf"]["nees_2d"], float)
+        # attitude drift anchor: |b|*t with the example bias vector
+        self.assertAlmostEqual(model["attitude"]["drift_100s_rad"],
+                               0.141421, places=4)
+
+    def test_core_gates_all_pass(self):
+        model = build_report(example_item())
+        gates = check_report(model)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_markdown_gates_all_pass(self):
+        md = example_report_markdown()
+        gates = check_report_markdown(md)
+        self.assertTrue(gates["all_pass"], gates)
+
+    def test_rendered_has_nine_sections_and_markers(self):
+        md = example_report_markdown()
+        for n in range(1, 10):
+            self.assertIn(f"## {n}. ", md)
+        low = md.lower()
+        self.assertIn("draft", low)
+        self.assertIn("not an approval", low)
+
+    def test_gates_fail_when_tampered(self):
+        model = build_report(example_item())
+        model["status"] = "approved"
+        self.assertFalse(check_report(model)["sign_off_honest"])
+        model2 = build_report(example_item())
+        model2["kalman"] = {}
+        self.assertFalse(check_report(model2)["kalman_numbers_present"])
+
+    def test_model_json_round_trip(self):
+        import json
+        model = build_report(example_item())
+        blob = json.dumps(model)
+        self.assertIn("kalman", json.loads(blob))
+
+    def test_standalone_no_skills_repo(self):
+        # Core must work with no AeroSkills present.
+        os.environ["AEROSKILLS_DEV"] = "/nonexistent"
+        model = build_report(example_item())
+        md = render_report_markdown(model)
+        self.assertGreater(len(md), 3000)
+        self.assertTrue(check_report(model)["all_pass"])
+
+
+if __name__ == "__main__":
+    unittest.main()