Add optional per-policy help_text appended to label messages

An admin can set help_text on a label policy to append one line of
guidance (for example where to look up valid values) to that key's warn
and enforce messages, without disclosing the allow_list. Empty by
default, so OSS defaults and messages stay deployment-neutral; the
NVIDIA AI Hub pointer lives only in internal ConfigMap values. Validated
as a single line of at most 256 characters.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jiaenren

deployments/charts/service/values.yaml

@@ -480,6 +480,7 @@ services:
       ##   - key: cost-center
       ##     allow_list: [team-a, team-b]   # empty allows any well-formed value
       ##     enforcement: warn              # "off" | warn | enforce
+      ##     help_text: "See the cost-center registry."  # appended to messages
       ## Quote "off" — unquoted YAML off parses as boolean false.
       ##
       labels_config:

src/service/core/workflow/objects.py

@@ -501,8 +501,13 @@ def evaluate_workflow_label_policies(
             outcome = 'missing'
         elif label_policy.allow_list and value not in label_policy.allow_list:
             outcome = 'invalid'
-        message = '' if outcome == 'ok' else _LABEL_POLICY_MESSAGES[
-            outcome, label_policy.enforcement].format(key=label_policy.key)
+        if outcome == 'ok':
+            message = ''
+        else:
+            message = _LABEL_POLICY_MESSAGES[
+                outcome, label_policy.enforcement].format(key=label_policy.key)
+            if label_policy.help_text:
+                message = f'{message} {label_policy.help_text}'
         outcomes.append(WorkflowLabelPolicyOutcome(
             label_policy, outcome, message))
     return outcomes

src/service/core/workflow/tests/test_workflow_labels.py

@@ -32,11 +32,13 @@ def _label_policy(
         key: str,
         enforcement: connectors.LabelEnforcement,
         allow_list: list[str] | None = None,
+        help_text: str = '',
 ) -> connectors.LabelPolicy:
     return connectors.LabelPolicy(
         key=key,
         enforcement=enforcement,
         allow_list=allow_list if allow_list is not None else [],
+        help_text=help_text,
     )
 
 
@@ -296,6 +298,30 @@ def test_enforce_violation_rejects_when_another_policy_only_warns(self):
             '\n'.join(captured.output),
         )
 
+    def test_policy_help_text_is_appended_to_warn_and_enforce_messages(self):
+        help_text = 'Look up valid values in the registry.'
+        warn_info = _submit_info([
+            _label_policy(
+                'project', connectors.LabelEnforcement.WARN, help_text=help_text),
+        ])
+        warnings = warn_info.validate_workflow_label_policy(_rendered_spec({}))
+        self.assertEqual(
+            warnings,
+            ["Workflow is missing label 'project'; add it now to avoid rejected "
+             f'submissions once it is required. {help_text}'],
+        )
+
+        enforce_info = _submit_info([
+            _label_policy(
+                'project', connectors.LabelEnforcement.ENFORCE, help_text=help_text),
+        ])
+        with self.assertRaises(osmo_errors.OSMOUsageError) as raised:
+            enforce_info.validate_workflow_label_policy(_rendered_spec({}))
+        self.assertEqual(
+            raised.exception.message,
+            f"Workflow is missing required label 'project'. {help_text}",
+        )
+
     def test_warn_is_not_persisted_when_later_validation_fails(self):
         submit_info = _submit_info([
             _label_policy('team', connectors.LabelEnforcement.WARN, ['alpha']),

src/utils/connectors/postgres.py

@@ -2950,6 +2950,10 @@ class LabelPolicy(ExtraArgBaseModel):
     key: str
     allow_list: List[str] = []
     enforcement: LabelEnforcement = LabelEnforcement.OFF
+    # Optional single line appended to this key's warn/enforce messages, e.g.
+    # where to look up valid values. Empty by default so the OSS default and
+    # messages stay deployment-neutral.
+    help_text: str = ''
 
     @pydantic.field_validator('key')
     @classmethod
@@ -2961,6 +2965,16 @@ def validate_key(cls, key: str) -> str:
     def validate_allow_list(cls, allow_list: List[str]) -> List[str]:
         return [validation.validate_workflow_label_value(value) for value in allow_list]
 
+    @pydantic.field_validator('help_text')
+    @classmethod
+    def validate_help_text(cls, help_text: str) -> str:
+        help_text = help_text.strip()
+        if len(help_text) > 256:
+            raise ValueError('Label policy help_text must be at most 256 characters.')
+        if any(character in help_text for character in '\r\n'):
+            raise ValueError('Label policy help_text must be a single line.')
+        return help_text
+
 
 class LabelsConfig(ExtraArgBaseModel):
     """Curated workflow label policy; empty by default, so no policy

src/utils/connectors/tests/test_workflow_config.py

@@ -53,6 +53,20 @@ def test_policy_defaults_to_off_and_rejects_unknown_mode(self):
         with self.assertRaises(pydantic.ValidationError):
             connectors.LabelPolicy(key='PPP', enforcement='block')
 
+    def test_help_text_defaults_empty_and_strips(self):
+        self.assertEqual(connectors.LabelPolicy(key='project').help_text, '')
+        self.assertEqual(
+            connectors.LabelPolicy(
+                key='project', help_text='  See the registry.  ').help_text,
+            'See the registry.',
+        )
+
+    def test_help_text_rejects_multiline_and_overlong(self):
+        with self.assertRaisesRegex(pydantic.ValidationError, 'single line'):
+            connectors.LabelPolicy(key='project', help_text='line one\nline two')
+        with self.assertRaisesRegex(pydantic.ValidationError, 'at most 256'):
+            connectors.LabelPolicy(key='project', help_text='x' * 257)
+
     def test_rejects_duplicate_policy_keys(self):
         with self.assertRaisesRegex(pydantic.ValidationError, 'Duplicate label policy key'):
             connectors.WorkflowConfig(labels_config={