feat(objectives): guard metrics in the objective join (abilityai/trinity-enterprise#731)

[obasilakis]

Fixes abilityai/trinity-enterprise#731.

What

An objective may list guard_metrics:: numbers that must not move while the objective's own metrics are pursued. The objective join ignored that key, so the 18 guards in the live canon were never checked or shown.

• Parse. Each guard is appended to the objective's metrics list with role: "guard" (primaries get role: "primary"). One list means guards are fetched, and served through a grant (ent#727), by the existing code. Guards have their own per-objective cap; a name in both lists keeps the primary.
• Judge. A guard always resolves to neutral / direction_source: objective, no mismatch, whatever the registry or its own direction: says. It is on_target within tolerance (default exact) or off_target, never behind / ahead. The same metric as a primary of another objective keeps its normal direction there.
• Count. summary.guards = {total, on_target, off_target, not_computable, stale}. Every other summary bucket counts primaries only, so an objective without guards reports exactly what it did before. One summary factory serves the join and the empty answer.
• Findings. guard_metrics_invalid (section not a list), guard_target_unset (no numeric target; 11 of the 18 live guards), guard_direction_invalid (a direction other than hold).
• Workspace role card. PortalRoleMetric.role crosses as the fixed value guard | primary. A guard row shows a neutral "Guard" badge; guard_target_unset reads "Target not set".
• MCP. get_objectives describes guards in one line. That line replaces a sentence describing a neutral / direction_source: "none" pair the join never returns, which keeps the description inside the 2048-char budget.
• Docs. Requirements (lifecycle-observability §50.11, findings table, response shape), both feature flows, the agent guide.

Tests

• tests/unit/test_ent731_guard_metrics.py (45): parse shapes and malformed input, the always-hold rule against every registry/declared pair, never behind/ahead, exact hold without tolerance, a metric that is a guard in one objective and a primary in another, served / stale / retired / undeclared / supporting-only guards, summary separation and empty-path parity, a guard fetched through the whole read_objective_join, and the portal role as a fixed value.
• Mutation: with the guard branch in resolve_direction removed, 20 of those tests go red.
• Existing tests updated for the new role key where they pin exact row contents (test_ent527_role_card, test_ent666_objective_join, test_ent676_role_card_join METRIC_KEYS).
• portalAgentRole.spec.js: Guard badge mounted, and the two new finding sentences.
• Full backend unit suite: 24669 passed. Frontend unit: 5076 passed with an English locale. MCP: 42 passed, including the description budget.

Security

/cso --diff: 0 findings (docs/security-reports/cso-diff-2026-10-09-ent731-guard-metrics.md). No new endpoint, auth change, read path, dependency or workflow. Guard names reach other agents' numbers only through the existing can_view grant check.

Conflict note

#3271 edits the same summary block in join_objectives; whichever lands second rebases.

🤖 Generated with Claude Code

[vybe]

merge-train (2026-10-09): validated at 80825916 — /validate-pr and /review found no criticals; the tests execute the changed path and every new value has a live consumer. Merge with dev (after #3411) is clean. OSS-core placement approved by the operator.