feat(workspace): the role card's objectives in plain words — owned first, supported folded, no metric code names (abilityai/trinity-enterprise#843)

[dolho]

Summary

The Workspace role card's Objectives now answer a client's question, "what is this agent for, and is it on track?", in plain words. Before, it showed canon objectives as written: metric code names (finance_ar_overdue_usd), "supports · quarter", "— / 1", and the same yellow "another agent measures this one" warning under every metric of every supported objective (nine times on one card in the operator's 2026-10-08 test).

• Owned first, under "What this agent is responsible for". Each metric is one line: "Runway: 7.2 months (target 12 months) · updated 2h ago", or "not measured yet". A stale number drops the time and shows not updated recently.

• Supported objectives sit in a separate group, collapsed by default with a count ("Also contributes to · N"), headings only: no metric rows and no per-metric warning.

  • "Tracked by " appears once per objective, in neutral text. The agent is named only when one agent this one holds a read grant on (served_by) serves every number; otherwise it says "Tracked by another agent".
  • An agent that only supports objectives still shows the folded group.

• Readable metric names. role_card.fill_metric_labels takes, in order:

  1. the declared label;
  2. the label every active declaration of that name agrees on (db.agreed_metric_labels), so a metric another agent tracks shows by that agent's label;
  3. the code name in words (runway_months → "Runway (months)", finance_ar_overdue_usd → "Finance AR overdue (USD)").

  A raw snake_case name never reaches the card, and a failed lookup still falls back to words.

• Warning colour only for real problems: stale, behind or off target, an unread file, an incomplete list. Remaining findings are neutral notes; "not measured" and "tracked elsewhere" aren't repeated under a metric.

• Horizons read "this quarter", "this month" and so on.

• client_heading: an optional plain heading for client screens on a canon objective, parsed by the join and used by the card, falling back to statement. The convention half (documenting the field in the canon objective format) is in trinity-pm.

• Unchanged: the operator agent page keeps the full canon detail. The objective ↔ metric join (fix(monitoring): degrade fleet-status to 'unknown' on NULL status row (#669) #676) logic and honest status (principle 15) are as before.

Disclosure

PortalRoleMetric gains label. PortalRoleObjective gains client_heading, tracked_elsewhere and tracked_by. The literal key-set pins in test_ent676_role_card_join.py are updated with a note. tracked_by names only an agent this one already reads from under a grant. agreed_metric_labels returns labels only, never which agent declared them.

Tests

• tests/unit/test_ent843_role_card_plain_words.py (new, 17), covering:
  • readable names, including that a declared label wins and the join's code-name fallback is ignored;
  • fill_metric_labels: agreed label, words, and a failed lookup;
  • agreed_labels on a real database: agreement, conflict, blank and retired rows;
  • "tracked elsewhere" once, named only for a single serving agent;
  • client_heading through the join.
• src/frontend/tests/unit/portalAgentRole.spec.js: 42 pass (35 existing, updated to the plain-words lines; 7 new). The new ones cover:
  • owned-first ordering;
  • the collapsed supported group, with headings only, one neutral note and no warning colour;
  • the plain heading and "this quarter";
  • no snake_case anywhere on the card;
  • the group folding again on an agent switch.
• Locally:
  • ent#527, fix(monitoring): degrade fleet-status to 'unknown' on NULL status row (#669) #676, fix(agent-server): make drain_reader_threads async to prevent event-loop deadlock (#657) #666 and fix(SUB-003): subscription rate-limit — persist reset time, skip retries on 429, default max_retries=0 (#476) #477 suites: 183 passed;
  • facade parity, the registry guard and root-placement lint pass;
  • raw-colour and loading-gate ratchets pass.

Not yet done

A visual check in the browser, light and dark (contract principle 29). The local instance is set up for today's demo, so I'll do it after.

Fixes abilityai/trinity-enterprise#843

🤖 Generated with Claude Code

[dolho]

[vybe]

merge-train: ejected from this batch — rides the next train once fixed. CI is green and the tests do execute the changed path; these need a decision, not a mechanical fix.

1. "Tracked by " is unreachable in production. build_role_card calls objective_join_service.read_objective_join(agent_name, template=template, client=client) (src/backend/client_portal/role_card.py:450) without can_view, and resolve_served_metrics returns {} when can_view is None (src/backend/services/objective_join_service.py:1026). So no row carries served_by, tracked_by (role_card.py:242) is always None, and every supported objective reads "Tracked by another agent". test_ent676_role_card_join.py::test_the_card_never_resolves_another_agents_metric already pins "served_by" not in row. The Tracked by ${o.tracked_by} branch in PortalAgentRole.vue, the spec asserting "Tracked by finance-agent" (a hand-built row), and the new docs/memory/requirements/core-agent.md text describe behaviour the card cannot produce. It fails closed, so nothing leaks. Either pass a portal-principal can_view (which is a decision to name another agent to an external client) or drop the field, the branch and the claim.

2. agreed_labels reads labels fleet-wide. src/backend/db/metric_definitions.py:110 filters on name and active status only, with no owner or grant scoping. When the card's own agent does not declare the metric, the label an external client sees is authored entirely by other agents; on a multi-owner install any agent declaring the same metric name puts up to 120 characters on another owner's client-facing card. Vue escapes it, so this is a content/disclosure question, not XSS. Scoping to the same owner, or to agents the card's agent holds a grant on, would close it.

Smaller, for the same push if you agree:

• New text (section heading, horizon line, toggle, "Tracked by" note, finding sentences) uses text-gray-400, which the design-system contract says is not a text colour. It matches the file's existing pattern, so the ratchet does not grow.
• findingText's metric_undeclared / metric_not_declared_here strings are unreachable now that findingLine filters both codes.
• declared_elsewhere = (not definition) and (not owned) is also true when no agent declares the metric, so "Tracked by another agent" can be false.

After merge, status-in-dev on abilityai/trinity-enterprise#843 is set by hand (cross-tracker keyword).

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[github-actions]

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

[vybe]

merge-train (2026-10-10): ejected — nothing has been pushed since the 2026-10-08 ejection, so both criticals stand: (1) tracked_by is unreachable in production (client_portal/role_card.py:450 calls read_objective_join without can_view, so served_by is never set and the Vue "Tracked by …" branch, the spec row and the requirements text describe output the card cannot produce — test_ent676_role_card_join.py:686 pins the opposite); (2) db/metric_definitions.py:250 agreed_labels is fleet-wide, never scoped by agent_name/owner. Also now conflicts with #3423 on dev: five files are mechanical, but PortalAgentRole.vue needs a decision on where the Guard badge lives once the supported-objective metric rows are gone. Rides the next train once fixed.