feat(ports): typed Ports base classes, ADR-0044, BTND-03-009–011, validate_report pilot

[sei-ahouseholder]

• Closes Adopt py_trees typed Ports: base class, convention, ADR/spec, pilot one subtree #1808

Summary

Implements issue #1808 — adopt py_trees 2.5.0 typed Ports for BT node blackboard contracts.

Changes

• vultron/core/behaviors/helpers.py — adds DataLayerConditionWithPorts and
  DataLayerActionWithPorts base classes. Each declares input_ports() / output_ports(),
  calls setup_ports() with BTBridge flat-key remappings in setup(), and reads injected
  values via get_input() in initialise(). Imports NoDataAvailable for the optional
  trigger_activity_factory guard.
• Pilot migration — four validate_report nodes migrated from DataLayerCondition /
  DataLayerAction to the new bases: CheckRMStateValid, CheckRMStateReceivedOrInvalid,
  EnsureEmbargoExists (conditions.py); TransitionRMtoValid (rm_transitions.py).
• docs/adr/0044-py-trees-typed-ports-adoption.md — new ADR extending ADR-0008; records
  decision, alternatives, constructor-vs-remapping tension, and known consequence (XML authoring
  deferred to spike Spike: assess BehaviorTree XML authoring/export feasibility for Vultron BTs via py_trees Ports #1810).
• specs/behavior-tree-node-design.yaml — adds BTND-03-009, BTND-03-010, BTND-03-011
  (typed port declarations, setup_ports remappings, get_input usage). Uses > folded scalars
  to avoid YAML parse errors from inline {key: value} remapping examples.
• notes/py-trees-ports-adoption.md — adds 6-step migration recipe with code examples.
• test/core/behaviors/report/nodes/test_typed_ports.py — 27 new tests: base-class
  contract tests, isolated NoDataAvailable detection tests, BTTestScenario integration
  tests for all four pilot nodes, sender_actor_id ADR-0022 path, and FAILURE guard path.
• mkdocs.yml — adds ADR-0044 to nav (required by adr-index-sync hook).

Key design decisions

• Port remappings {"datalayer": "/datalayer", "actor_id": "/actor_id"} bridge the Ports
  namespace to the flat keys BTBridge.setup_tree() writes — no changes to BTBridge required.
• trigger_activity_factory is declared as required=False; absence caught narrowly via
  except NoDataAvailable (not broad except Exception).
• NoDataAvailable surfaces in initialise() at the start of the first tick, not during
  setup() — ADR and spec corrected to reflect this (pre-PR review finding).

Deferred

• Full node migration sweep → issue Migrate remaining core/behaviors/ BT nodes to typed py_trees Ports #1809 (blocked-by this PR)
• XML feasibility spike → issue Spike: assess BehaviorTree XML authoring/export feasibility for Vultron BTs via py_trees Ports #1810 (blocked-by Migrate remaining core/behaviors/ BT nodes to typed py_trees Ports #1809)

Test plan

• uv run black vultron/ test/ && uv run flake8 vultron/ test/ — clean
• uv run mypy — no issues in 1114 source files
• uv run pyright — 0 errors, 0 warnings
• uv run pytest test/core/behaviors/report/ test/metadata/specs/ — 620 passed
• Full suite: no regressions introduced by this branch
• All pre-commit hooks pass (including adr-index-sync)

🤖 Generated with Claude Code

[sei-ahouseholder]

PR Triage — 1827

5 findings (all IMPROVE / fix-now); CI is still pending.

---

Phase 3 — PR Body Format

IMPROVE phase3-closes-at-bottom-0 — Closes #1808 is at the bottom of the body (before the Claude footer). The PR body guide requires closing references at the top of the body, one per bullet line, before ## Summary.

IMPROVE phase3-pr-body-missing-changes-section-0 — The body uses ### What changed (a sub-heading under ## Summary) rather than the template's standalone ## Changes section.

---

Phase 9 — Notes Currency

IMPROVE phase9-notes-status-draft-0 — notes/py-trees-ports-adoption.md still has status: draft. The implementation is complete (not just planned), so the status should advance to status: active.

• notes/py-trees-ports-adoption.md line 3

---

Phase 10 — Test Coverage

IMPROVE phase10-sender-actor-id-untested-0 — CheckRMStateValid and CheckRMStateReceivedOrInvalid both accept sender_actor_id which overrides the blackboard actor_id (ADR-0022 single-BT pattern). No test exercises this branch — the path self.sender_actor_id if self.sender_actor_id else self.actor_id is only tested with sender_actor_id=None (default).

• test/core/behaviors/report/nodes/test_typed_ports.py test class TestCheckRMStateValidPorts
• Fix: add a BTTestScenario test passing a non-None sender_actor_id that differs from the blackboard actor_id.

IMPROVE phase10-transition-rm-failure-untested-0 — TransitionRMtoValid has only one happy-path test. The _require_datalayer() FAILURE guard and the actor_id is None check have no test coverage.

• test/core/behaviors/report/nodes/test_typed_ports.py class TestTransitionRMtoValidPorts
• Fix: add a test that runs TransitionRMtoValid without datalayer on the blackboard and asserts FAILURE.

---

Not findings

• Legacy DataLayerCondition / DataLayerAction nodes remaining in conditions.py and rm_transitions.py (e.g. EvaluateReportCredibility, TransitionRMtoInvalid) are pre-existing nodes — BTND-03-009 says "new BT nodes" so the full sweep is correctly scoped to follow-on #1809. ✅
• behavior-tree-integration.yaml not updated — BTBridge still writes the same flat keys; only the reading mechanism changed. AC-3 qualifier "where the bridge/blackboard contract changes" is satisfied by no change needed. ✅
• Test count accurate: 25 new tests in test_typed_ports.py, 618 total in the tested subdirectories. ✅
• Co-authored-by trailers present in all 3 commits. ✅
• ADR-0044 format, mkdocs nav, and spec entries all correct. ✅

---

CI

All linters (black, flake8, mypy, pyright) and CodeQL passed. Tests, docs-build, and demo integration are still pending.

[sei-ahouseholder]

PR Execute — 1827

All 5 triage findings resolved. CI green. Tests passing.

---

Findings addressed (commit 07e3ca81)

ID	Outcome	Notes
phase3-closes-at-bottom-0	✅ fixed	Moved - Closes #1808 to the first line of the PR body
phase3-pr-body-missing-changes-section-0	✅ fixed	Renamed ### What changed → ## Changes (top-level)
phase5-btnd03009-legacy-nodes-conditions-0	✅ no change needed	BTND-03-009 scopes to "new BT nodes"; pre-existing nodes → follow-on #1809
phase5-btnd03009-legacy-nodes-rm-0	✅ no change needed	Same — pre-existing nodes deferred to #1809
phase10-sender-actor-id-untested-0	✅ fixed	Added test_sender_actor_id_checked_instead_of_blackboard_actor (ADR-0022 path)
phase10-transition-rm-failure-untested-0	✅ fixed	Added test_failure_when_datalayer_not_available (FAILURE guard path)
phase9-notes-status-draft-0	✅ fixed	notes/py-trees-ports-adoption.md status: draft → active

CI (07e3ca81)

Check	Status
Python application	✅ success
Spec Check	✅ success
Docs Build and Link Check	✅ success
Demo Integration	✅ success
Lint Markdown	✅ success

Test suite

Full local suite: 5797 passed, 265 skipped, 2 xfailed — no regressions.
New test count in test_typed_ports.py: 27 (up from 25).

🤖 Generated with Claude Code

[sei-ahouseholder]

PR Verify — 1827 ✅ READY-TO-MERGE

All findings confirmed at HEAD. CI green. No gaps.

---

Finding verification

ID	Severity	Outcome	Verdict
phase3-closes-at-bottom-0	IMPROVE	fixed	✅ CONFIRMED
phase3-pr-body-missing-changes-section-0	IMPROVE	fixed	✅ CONFIRMED
phase5-btnd03009-legacy-nodes-conditions-0	IMPROVE	no_change_needed	✅ NOTED — BTND-03-009 scopes to new nodes; pre-existing deferred to #1809
phase5-btnd03009-legacy-nodes-rm-0	IMPROVE	no_change_needed	✅ NOTED — same; deferred to #1809
phase10-sender-actor-id-untested-0	IMPROVE	fixed	✅ CONFIRMED
phase10-transition-rm-failure-untested-0	IMPROVE	fixed	✅ CONFIRMED
phase9-notes-status-draft-0	IMPROVE	fixed	✅ CONFIRMED

CI (commit 07e3ca81)

Check	Status
Python application	✅ success
Spec Check	✅ success
Docs Build and Link Check	✅ success
Demo Integration	✅ success
Lint Markdown	✅ success

Overall verdict

READY-TO-MERGE — all findings resolved, CI green, full test suite clean (5797 passed).

🤖 Generated with Claude Code