aero-agent-roles 1.0.0

package/roles/numerical-analysis-engineer/ROLE.md

@@ -0,0 +1,158 @@
+---
+type: role
+name: numerical-analysis-engineer
+title: "Numerical Analysis Engineer"
+status: draft
+domain: cross-cutting
+deliverable_type: "numerical methods verification memo"
+standards_bound:
+  - id: asme-vv-20
+    tier: TIER-2
+    reference-only: true
+skills_bound:
+  - cross-cutting/numerics/numerical-integration
+  - cross-cutting/numerics/root-finding
+  - cross-cutting/numerics/convergence-verification
+  - cross-cutting/numerics/finite-difference-derivatives
+  - cross-cutting/numerics/ode-solvers
+  - cross-cutting/numerics/interpolation
+  - cross-cutting/numerics/least-squares-regression
+  - cross-cutting/numerics/matrix-operations
+  - cross-cutting/numerics/singular-value-decomposition
+  - cross-cutting/numerics/uncertainty-propagation
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "issue engineering approval"
+  - "declare compliance"
+  - "sign off numerical results as released"
+  - "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: ashfordeOU
+  skills_release: "v1.3.0+"
+---
+
+# Numerical Analysis Engineer
+
+## Role identity
+
+This role independently VERIFIES the numerical methods inside an
+engineering code: the integrals, roots, solves, derivatives and
+convergence behavior that the code's results quietly depend on. It
+selects reference methods with real rationale, recomputes every
+reported number with an independent implementation, quantifies the
+discrepancy against the code's own claimed tolerances, and runs a
+three-mesh convergence study plus a conditioning report to bound the
+discretization and rounding error. Use when an engineering deliverable
+rests on a numerical result that must be checked against reference
+methods. Do NOT use for design decisions themselves (use the domain
+roles), for statistical data analysis (see the analysis roles), or to
+approve/release code.
+
+## Deliverable contract
+
+1. **Numerical Methods Verification Memo** — per numerical operation in
+   scope: the reference method selected and why, the independent
+   reference value, the code-reported value, the quantified discrepancy
+   vs the code's claimed tolerance, a PASS/FAIL verdict, and (for any
+   FAIL) an evidence-backed finding with a recommendation. Always
+   includes the convergence study (observed order, Richardson
+   extrapolation, GCI) and the conditioning assessment of any linear
+   solve.
+2. **Evidence bundle** — `evidence/{model,gates,provenance}.json`
+   emitted with `--bundle` per PROTOCOL.md v1, carrying every number in
+   the memo plus the skill-dispatch cross-check rows.
+
+## Workflow (stages -> bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Integration | numerics/numerical-integration | rule selection + reference integral + Richardson error estimate |
+| 2. Root finding | numerics/root-finding | reference root (Newton + bisection bracket cross-check), simple-root check |
+| 3. Derivatives | numerics/finite-difference-derivatives | stencil-selection input when code uses numerical differentiation |
+| 4. ODE paths | numerics/ode-solvers | reference time-marching when the code integrates state equations |
+| 5. Interpolation paths | numerics/interpolation | reference table interpolation checks |
+| 6. Regression paths | numerics/least-squares-regression | reference fit checks |
+| 7. Linear solve | numerics/matrix-operations + numerics/singular-value-decomposition | reference solve, residual, condition number s_max/s_min |
+| 8. Convergence | numerics/convergence-verification | observed order, Richardson extrapolation, GCI (Fs=1.25), verdict |
+| 9. Error budget | numerics/uncertainty-propagation | uncertainty framing for inputs when claimed |
+| 10. Memo build | (report conventions) | the Numerical Methods Verification Memo + evidence bundle |
+
+## Evidence gates
+
+- Stage 1 done = every in-scope integral has a reference rule with
+  rationale and an error estimate; the reference value is a real number.
+- Stage 2 done = every in-scope root has a reference root, a bracket or
+  guess statement, and a residual.
+- Stage 7 done = the solve is checked against a pivoted reference solve
+  and the conditioning report is stated.
+- Stage 8 done = a three-mesh study reports observed order and GCI (or
+  an explicit oscillatory/diverging verdict).
+- FINAL = every check row quantifies discrepancy vs the code's claimed
+  tolerance and carries a PASS/FAIL verdict; findings cite their
+  evidence. Nothing is asserted without a checkable basis.
+
+## Boundary / forbidden
+
+- NEVER issue engineering approval, declare compliance, or sign off
+  numerical results as released — a human numerical-analysis reviewer
+  owns the disposition of findings.
+- NEVER reproduce proprietary standard text (ASME V&V 20-2009 is
+  reference-only); the memo's method descriptions are original
+  paraphrases of classical numerical analysis.
+- The code's claimed tolerances are inputs to the memo, not
+  endorsements.
+- Output is a DRAFT for human review — mark it draft.
+
+## Verification
+
+The role runs STANDALONE: `core/numerical_analysis_core.py` is an
+executable engine that reproduces the bound leaf methods (composite
+trapezoid/Simpson, Richardson error estimate error(2n)=|I_2n-I_n|/3,
+Newton-Raphson and bisection, Gaussian elimination with partial
+pivoting, observed order/GCI with Fs=1.25, condition number s_max/s_min)
+to compute reference values, quantify discrepancies, run the
+convergence study, and gate-check deliverables. No AeroSkills checkout
+required (`AEROSKILLS_DEV=/nonexistent` still builds correctly).
+
+Run the role:
+```bash
+python3 cli.py build --out memo.md                              # example item
+python3 cli.py build --out memo.md --bundle                     # + evidence bundle
+python3 cli.py build --code-integral 50400.0 --code-integral-tol 1.0 \
+                     --out memo.md                              # re-verify a code report
+python3 cli.py build --profile ../../profiles/example-airframer.json \
+                     --out memo.md                              # program tailoring
+python3 cli.py check --file memo.md                             # gate-check a memo
+```
+
+Tests:
+- tests/test_numerical_analysis_core.py: quadrature rules + Richardson
+  error estimate, Newton/bisection root anchors (A/A* = 1.2 subsonic
+  M = 0.59024876099), reference solve, convergence study, conditioning,
+  memo builder, gates, standalone (no skills repo), and the filled
+  template byte-matches the core example.
+- tests/test_role_numerical_analysis_engineer.py: bound-skill
+  resolution (skips if the skills repo is absent) + workflow +
+  template present + boundaries.
+- tests/test_bundle_protocol.py: `build --bundle` emits the three
+  evidence files with all gates PASS; the ten dispatch rows agree with
+  the bound numerics leaves (delta <= 1e-6) when AeroSkills is present;
+  standalone runs honest (`cross_checked: false`); `--profile` and
+  `check` behave per protocol.
+
+Bound skills in Aero Agent Skills deepen individual stages when the
+library is present (integration, root-finding, convergence, matrix and
+SVD leaves); the core engine does not depend on them.
+
+## Compliance
+
+- asme-vv-20 TIER-2 reference-only (discretization-error vocabulary).
+- Classical numerical-analysis methodology (Richardson 1910/1927,
+  Euler-Maclaurin error analysis, Newton/Simpson/Gauss quadrature) is
+  public domain and paraphrased, never copied from any commercial
+  text.
+- SOURCES.md records standards referenced.

package/roles/numerical-analysis-engineer/SOURCES.md

@@ -0,0 +1,19 @@
+# SOURCES.md - Numerical Analysis Engineer
+
+Standards and documents this role references. Summary-not-copy: see
+[STANDARDS.md](../../STANDARDS.md) for the full rule and purchase links.
+The numerical methods themselves (Newton, Simpson/Gauss quadrature,
+Richardson extrapolation, Gaussian elimination, condition numbers) are
+classical analysis and public-domain methodology; the bound AeroSkills
+leaves paraphrase them and anchor their tables.
+
+| Source | Role use | Gated |
+|---|---|---|
+| ASME V&V 20-2009, Standard for Verification and Validation in CFD and Heat Transfer | discretization-error vocabulary (observed order, Richardson extrapolation, grid convergence index, safety factor) used in the memo's convergence section | true |
+| Classical numerical analysis (Newton 1669/1711; Simpson 1743; Gauss 1814; Richardson 1910/1927; Euler-Maclaurin error analysis) | reference methods: quadrature rules, root iterations, error estimates - public domain, paraphrased | false |
+| NACA Report 824 (public-domain anchor of the cross-cutting/numerics leaves) | compressible-flow relation context for the area-Mach inversion anchor used by the root-finding leaf | false |
+
+The verification-memo template in `templates/` is an original
+structure produced by the role's own core engine; it contains no
+reproduced text from any standard. ASME V&V 20-2009 is referenced for
+its methodology vocabulary only (summary-not-copy, TIER-2).

package/roles/numerical-analysis-engineer/cli.py

@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""cli.py - run the Numerical Analysis Engineer role.
+
+Usage:
+  python3 cli.py build [--out <file.md>] [--bundle] [--profile <file.json>]
+                       [--no-dispatch]
+                       [--code-integral <N>] [--code-mach <M>]
+                       [--code-solve <c0,c1>]
+    # build the Numerical Methods Verification Memo for the example item
+    # (Loads Post-Processor v2.3.1) and gate-check it
+    # --bundle   also emit evidence/{model,gates,provenance}.json (PROTOCOL.md)
+    # --profile  program profile JSON for customer tailoring
+    #            (docs/PROFILE-SCHEMA.md) -> prepended context header
+    # --no-dispatch skip dispatching bound AeroSkills numerics logic
+    # the --code-* flags re-verify a different code report of the same
+    # operations (integration value, Mach root, linear-solve result)
+  python3 cli.py check --file <file.md>    # gate-check an existing memo
+
+The role ENGINE (core/numerical_analysis_core.py) does the work standalone:
+reference quadrature, Newton/bisection root finding, dense solve,
+convergence study (observed order, Richardson, GCI), conditioning, and
+the evidence gates. When AeroSkills is present (AEROSKILLS_DEV or
+~/AeroSkills), the CLI dispatches the bound cross-cutting/numerics leaf
+logic modules and cross-checks their numbers against the core's - two
+independent implementations agreeing is recorded in provenance.json.
+"""
+import argparse
+import importlib.util
+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 numerical_analysis_core as core  # noqa: E402
+import evidence  # noqa: E402
+
+AEROSKILLS = os.environ.get("AEROSKILLS_DEV", os.path.expanduser("~/AeroSkills"))
+NUMERICS_ROOT = os.path.join(AEROSKILLS, "skills", "cross-cutting", "numerics")
+ROLE_SLUG = "numerical-analysis-engineer"
+SKILLS_RELEASE = "v1.3.0+"
+
+# Bound leaves and their dispatch points (leaf module names as on disk).
+BOUND_LEAVES = [
+    ("numerical-integration", "numerical_integration_logic.py"),
+    ("root-finding", "root_finding_logic.py"),
+    ("convergence-verification", "convergence_verification_logic.py"),
+    ("singular-value-decomposition", "singular_value_decomposition_logic.py"),
+    ("matrix-operations", "matrix_operations_logic.py"),
+]
+
+
+def _load_leaf(leaf, logic_file):
+    """Import a bound leaf's *_logic.py module, or None when unavailable."""
+    path = os.path.join(NUMERICS_ROOT, leaf, "scripts", logic_file)
+    if not os.path.exists(path):
+        return None
+    spec = importlib.util.spec_from_file_location(
+        "numerics_leaf_" + leaf.replace("-", "_"), path)
+    mod = importlib.util.module_from_spec(spec)
+    try:
+        spec.loader.exec_module(mod)
+        return mod
+    except Exception:
+        return None
+
+
+def _row(leaf, logic_file, fn, core_val, skill_val, point, tol=1e-6):
+    delta = abs(float(core_val) - float(skill_val))
+    return {
+        "leaf": "cross-cutting/numerics/" + leaf,
+        "skill_md": "SKILL.md",
+        "logic_file": "scripts/" + logic_file,
+        "function": fn,
+        "dispatched": True,
+        "cross_check_point": point,
+        "core_value": round(float(core_val), 9),
+        "skill_value": round(float(skill_val), 9),
+        "delta": round(delta, 12),
+        "agrees": delta <= tol,
+        "tolerance": tol,
+        "skills_release": SKILLS_RELEASE,
+    }
+
+
+def _row_err(leaf, logic_file, fn, exc):
+    return {"leaf": "cross-cutting/numerics/" + leaf,
+            "logic_file": "scripts/" + logic_file,
+            "function": fn, "dispatched": True,
+            "error": str(exc), "agrees": False}
+
+
+def _run_crosschecks(item, model):
+    """Cross-check core numbers against the five bound numerics leaves.
+
+    Each row compares the same quantity computed two independent ways:
+    the role core implementation and the AeroSkills leaf logic. Rows
+    are empty when the skills library is absent.
+    """
+    rows = []
+    a, b = float(item.interval[0]), float(item.interval[1])
+    f = lambda y: core.lift_intensity(y, item.integrand_w0,
+                                      item.integrand_span)
+    ar, gam = item.area_ratio, item.gamma
+    resid = lambda M: core.area_mach_residual(M, ar, gam)
+    deriv = lambda M: core.area_mach_derivative(M, gam)
+
+    # 1. numerical-integration: trapezoid at the code's panel count
+    mod = _load_leaf("numerical-integration",
+                     "numerical_integration_logic.py")
+    if mod is not None and hasattr(mod, "trapezoid"):
+        try:
+            core_val = core.trapezoid(f, a, b, item.code_integral_n)
+            skill_val = mod.trapezoid(f, a, b, item.code_integral_n)
+            rows.append(_row("numerical-integration",
+                             "numerical_integration_logic.py", "trapezoid",
+                             core_val, skill_val,
+                             "code-panel trapezoid of the spanwise load"))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("numerical-integration",
+                                 "numerical_integration_logic.py",
+                                 "trapezoid", e))
+
+    # 2. numerical-integration: reference Simpson value
+    if mod is not None and hasattr(mod, "simpson"):
+        try:
+            n_ref = max(2 * item.code_integral_n, 64)
+            core_val = core.simpson(f, a, b, n_ref)
+            skill_val = mod.simpson(f, a, b, n_ref)
+            rows.append(_row("numerical-integration",
+                             "numerical_integration_logic.py", "simpson",
+                             core_val, skill_val,
+                             "reference Simpson integral of the spanwise "
+                             "load"))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("numerical-integration",
+                                 "numerical_integration_logic.py",
+                                 "simpson", e))
+
+    # 3. numerical-integration: Richardson error estimate error(2n)
+    if mod is not None and hasattr(mod, "error_estimate_trapezoid"):
+        try:
+            core_val = core.richardson_error_trapezoid(
+                f, a, b, item.code_integral_n)
+            skill_val = mod.error_estimate_trapezoid(
+                f, a, b, item.code_integral_n)
+            rows.append(_row("numerical-integration",
+                             "numerical_integration_logic.py",
+                             "error_estimate_trapezoid", core_val, skill_val,
+                             "Richardson error estimate of the trapezoid "
+                             "result"))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("numerical-integration",
+                                 "numerical_integration_logic.py",
+                                 "error_estimate_trapezoid", e))
+
+    # 4. root-finding: Newton-Raphson subsonic area-Mach root
+    mod = _load_leaf("root-finding", "root_finding_logic.py")
+    if mod is not None and hasattr(mod, "newton_raphson"):
+        try:
+            core_val = core.newton_raphson(resid, deriv, item.newton_guess)
+            skill_val = mod.newton_raphson(resid, deriv, item.newton_guess)
+            rows.append(_row("root-finding", "root_finding_logic.py",
+                             "newton_raphson", core_val, skill_val,
+                             "subsonic root of A/A* = %g, gamma = %g"
+                             % (ar, gam)))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("root-finding", "root_finding_logic.py",
+                                 "newton_raphson", e))
+
+    # 5. root-finding: bisection bracket cross-check
+    if mod is not None and hasattr(mod, "bisection"):
+        try:
+            core_val = core.bisection(resid, item.bracket[0], item.bracket[1])
+            skill_val = mod.bisection(resid, item.bracket[0], item.bracket[1])
+            rows.append(_row("root-finding", "root_finding_logic.py",
+                             "bisection", core_val, skill_val,
+                             "bisection cross-check on [%g, %g]"
+                             % (item.bracket[0], item.bracket[1])))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("root-finding", "root_finding_logic.py",
+                                 "bisection", e))
+
+    # 6. convergence-verification: grid-study order + GCI
+    mod = _load_leaf("convergence-verification",
+                     "convergence_verification_logic.py")
+    if mod is not None and hasattr(mod, "convergence_verdict"):
+        try:
+            meshes = model["convergence"]["meshes"]
+            f1, f2, f3 = (m["f"] for m in meshes)
+            r = model["convergence"]["refinement_ratio"]
+            core_cv = core.convergence_verdict(f1, f2, f3, r)
+            skill_cv = mod.convergence_verdict(f1, f2, f3, r)
+            if core_cv["order"] is not None and skill_cv["order"] is not None:
+                rows.append(_row("convergence-verification",
+                                 "convergence_verification_logic.py",
+                                 "convergence_verdict.order",
+                                 core_cv["order"], skill_cv["order"],
+                                 "observed order of the three-mesh study"))
+                rows.append(_row("convergence-verification",
+                                 "convergence_verification_logic.py",
+                                 "convergence_verdict.gci",
+                                 core_cv["gci"], skill_cv["gci"],
+                                 "grid convergence index of the study"))
+            rows.append(_row("convergence-verification",
+                             "convergence_verification_logic.py",
+                             "convergence_verdict.verdict",
+                             1.0 if core_cv["verdict"] == skill_cv["verdict"]
+                             else 0.0,
+                             1.0,
+                             "convergence verdict classification"))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("convergence-verification",
+                                 "convergence_verification_logic.py",
+                                 "convergence_verdict", e))
+
+    # 7. singular-value-decomposition: condition number of the solve
+    mod = _load_leaf("singular-value-decomposition",
+                     "singular_value_decomposition_logic.py")
+    if mod is not None and hasattr(mod, "condition_number"):
+        try:
+            sv = model["linear_solve"]["conditioning"]["singular_values"]
+            core_val = core.condition_number(sv)
+            skill_val = mod.condition_number(sv)
+            rows.append(_row("singular-value-decomposition",
+                             "singular_value_decomposition_logic.py",
+                             "condition_number", core_val, skill_val,
+                             "2-norm condition number s_max/s_min of A"))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("singular-value-decomposition",
+                                 "singular_value_decomposition_logic.py",
+                                 "condition_number", e))
+
+    # 8. matrix-operations: reference dense solve of A c = b
+    mod = _load_leaf("matrix-operations", "matrix_operations_logic.py")
+    if mod is not None and hasattr(mod, "solve"):
+        try:
+            core_val = core.solve(item.system_A, item.system_b)[0]
+            skill_val = mod.solve(item.system_A, item.system_b)[0]
+            rows.append(_row("matrix-operations", "matrix_operations_logic.py",
+                             "solve", core_val, skill_val,
+                             "first component of c = A^-1 b"))
+        except Exception as e:  # pragma: no cover
+            rows.append(_row_err("matrix-operations",
+                                 "matrix_operations_logic.py", "solve", e))
+    return rows
+
+
+def _provenance(rows):
+    ok_rows = [r for r in rows if r.get("dispatched") and not r.get("error")]
+    return {
+        "role": ROLE_SLUG,
+        "core": {
+            "file": "core/numerical_analysis_core.py",
+            "functions": ["trapezoid", "simpson",
+                          "richardson_error_trapezoid", "newton_raphson",
+                          "bisection", "convergence_verdict", "solve",
+                          "condition_number", "build_report",
+                          "check_report"],
+            "version": "0.1.0",
+        },
+        "skills": rows,
+        "cross_checked": bool(ok_rows) and all(r.get("agrees")
+                                               for r in ok_rows),
+        "disclaimer": "DRAFT for human review. Not an approval document.",
+    }
+
+
+def _parse_csv_floats(text):
+    return [float(t) for t in str(text).split(",") if t.strip()]
+
+
+def cmd_build(args):
+    item = core.example_item()
+    # allow re-verifying different code reports from the CLI
+    if args.code_integral is not None:
+        item.code_integral = args.code_integral
+    if args.code_integral_tol is not None:
+        item.code_integral_tol = args.code_integral_tol
+    if args.code_mach is not None:
+        item.code_mach = args.code_mach
+    if args.code_mach_tol is not None:
+        item.code_mach_tol = args.code_mach_tol
+    if args.code_solve:
+        vals = _parse_csv_floats(args.code_solve)
+        if len(vals) != len(item.system_b):
+            print("error: --code-solve needs %d comma-separated values"
+                  % len(item.system_b))
+            return 1
+        item.code_solution = vals
+    if args.code_solve_tol is not None:
+        item.code_solve_tol = args.code_solve_tol
+
+    model = core.build_report(item)
+    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)
+
+    rows = []
+    if not args.no_dispatch:
+        rows = _run_crosschecks(item, model)
+
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(md if md.endswith("\n") else md + "\n")
+        print("built Numerical Methods Verification Memo -> %s" % args.out)
+        for c in model["checks"]:
+            print("  %-12s verdict=%-4s discrepancy=%.6g (tol %g)"
+                  % (c["operation"][:12], c["verdict"], c["discrepancy"],
+                     c["code_tolerance"]))
+        conv = model["convergence"]
+        print("  grid study: p=%s gci=%s verdict=%s"
+              % (conv["observed_order"], conv["gci_fraction"],
+                 conv["verdict"]))
+        print("gates: all_pass=%s %s" % (gates["all_pass"], gates))
+        if profile:
+            print("profile: %s / %s" % (profile.get("customer"),
+                                        profile.get("program")))
+        if args.bundle:
+            prov = _provenance(rows)
+            paths = evidence.write_bundle(
+                args.out, ROLE_SLUG,
+                "Numerical Methods Verification Memo", model, gates, prov)
+            print("bundle: model=%s" % paths["model"])
+            print("        gates=%s" % paths["gates"])
+            print("        provenance=%s" % paths["provenance"])
+            if rows:
+                for r in rows:
+                    if r.get("dispatched") and not r.get("error"):
+                        print("cross-check: %-32s core=%-12s skill=%-12s "
+                              "delta=%s agrees=%s"
+                              % (r["function"], r["core_value"],
+                                 r["skill_value"], r["delta"], r["agrees"]))
+            else:
+                print("cross-check: not dispatched (no AeroSkills logic)")
+    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()
+    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="Numerical Analysis Engineer role: numerical methods "
+                    "verification memo")
+    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("--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.add_argument("--no-dispatch", action="store_true",
+                   help="skip dispatching bound AeroSkills logic")
+    b.add_argument("--code-integral", type=float, default=None,
+                   help="code-reported integral (N) to re-verify")
+    b.add_argument("--code-integral-tol", type=float, default=None,
+                   help="code-claimed integral tolerance (N)")
+    b.add_argument("--code-mach", type=float, default=None,
+                   help="code-reported subsonic Mach root to re-verify")
+    b.add_argument("--code-mach-tol", type=float, default=None,
+                   help="code-claimed root residual tolerance")
+    b.add_argument("--code-solve", default="",
+                   help="code-reported solution as c0,c1 to re-verify")
+    b.add_argument("--code-solve-tol", type=float, default=None,
+                   help="code-claimed solve component tolerance")
+    b.set_defaults(fn=cmd_build)
+
+    c = sub.add_parser("check")
+    c.add_argument("--file", required=True,
+                   help="verification memo markdown to gate-check")
+    c.set_defaults(fn=cmd_check)
+
+    args = p.parse_args()
+    sys.exit(args.fn(args))
+
+
+if __name__ == "__main__":
+    main()