fix(spec): the Permission Set, Position and view form help texts Setup shows are plain admin copy

.changeset/23853-form-help-texts-plain.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/spec': patch
+'@objectstack/platform-objects': patch
+---
+
+Clause-②: no
+
+Six help texts an administrator reads in Setup no longer carry ADR numbers. On the Permission Sets edit form,
+`isDefault`, `managedBy` and `packageId` are rewritten as plain sentences that say what the field does, and
+`adminScope` drops its "(ADR-0090 D12)" prefix. On the Positions edit form, `delegatable` drops "(ADR-0091 D3)".
+The view form's End-user controls description drops "(ADR-0047, Airtable Interface parity)".
+
+The ADR references moved to the comments beside the form rows. The generated metadata-forms translations carry
+the new wording in en, zh-CN, ja-JP and es-ES. No key, type or accept/refuse result changes.

packages/platform-objects/src/apps/setup-copy-vocabulary.test.ts

@@ -23,9 +23,11 @@
  *   2. every leaf of the four committed `objects` bundles;
  *   3. the type-level `label` / `description` of the four `metadataForms`
  *      bundles — the sentence a Setup metadata page (Positions, Capabilities,
- *      Permission Sets) shows under its title. Section descriptions and field
- *      `helpText` of those forms are the spec's form copy and are not judged
- *      here;
+ *      Permission Sets) shows under its title, plus the six form leaves named
+ *      in `FORM_HELP_LEAVES` (the Permission Sets and Positions help texts and
+ *      the view form's End-user controls description). The other section
+ *      descriptions and field `helpText` of those forms are the spec's form
+ *      copy and are not judged here;
  *   4. `SETUP_APP` and this package's `SETUP_NAV_CONTRIBUTIONS`, and the
  *      hand-authored `apps.setup` subtree of each locale.
  *
@@ -172,6 +174,55 @@ describe('Setup copy carries no design-record vocabulary', () => {
     expect(offenders(strings)).toEqual([]);
   });
 
+  // The help texts an admin reads on Setup's Permission Sets and Positions edit
+  // forms, and the view form's End-user controls section. Each one carried a
+  // decision-record reference until the spec form source moved it into the
+  // comment beside the row; `en` is regenerated from that source, so judging
+  // the four bundles judges the source too.
+  const FORM_HELP_LEAVES = [
+    ['permission', 'fields', 'isDefault', 'helpText'],
+    ['permission', 'fields', 'managedBy', 'helpText'],
+    ['permission', 'fields', 'packageId', 'helpText'],
+    ['permission', 'fields', 'adminScope', 'helpText'],
+    ['position', 'fields', 'delegatable', 'helpText'],
+    ['view', 'sections', 'end_user_controls', 'description'],
+  ] as const;
+
+  function formHelpLeaves(bundle: unknown, locale: string): Array<[string, string]> {
+    return FORM_HELP_LEAVES.map((path) => {
+      const value = path.reduce<unknown>((node, key) => (node as Record<string, unknown> | undefined)?.[key], bundle);
+      const at = `${locale}.metadataForms.${path.join('.')}`;
+      expect(value, `${at} is in the population`).toBeTypeOf('string');
+      return [at, value as string];
+    });
+  }
+
+  it.each(Object.keys(FORM_BUNDLES))('the Permission Set, Position and view form help texts of the %s metadataForms bundle', (locale) => {
+    const strings = formHelpLeaves(FORM_BUNDLES[locale as keyof typeof FORM_BUNDLES], locale);
+    expect(strings).toHaveLength(FORM_HELP_LEAVES.length);
+    expect(offenders(strings)).toEqual([]);
+  });
+
+  it('the form help-text assertion fires on the prose it replaced', () => {
+    // Dark leg: the same walk over a bundle carrying the replaced wording must
+    // name every leaf, so a walk that reaches nothing cannot pass above.
+    const replaced = {
+      permission: { fields: {
+        isDefault: { helpText: 'App baseline for the everyone position (ADR-0090 D5): an app-level set is auto-bound at boot.' },
+        managedBy: { helpText: 'Record provenance (ADR-0086 D3): who owns this set across upgrades.' },
+        packageId: { helpText: 'Owning package id for a package-shipped set (ADR-0086 D3).' },
+        adminScope: { helpText: 'Delegated administration (ADR-0090 D12): lets holders of this set administer one business-unit subtree.' },
+      } },
+      position: { fields: {
+        delegatable: { helpText: 'Holders may delegate this position themselves, time-boxed and with a reason (ADR-0091 D3).' },
+      } },
+      view: { sections: {
+        end_user_controls: { description: 'What end users can do on this view (ADR-0047, Airtable Interface parity).' },
+      } },
+    };
+    expect(offenders(formHelpLeaves(replaced, 'replaced'))).toHaveLength(FORM_HELP_LEAVES.length);
+  });
+
   it('the Setup app, its nav contributions, and every locale\'s apps.setup translations', () => {
     const strings: Array<[string, string]> = [];
     copyStrings(SETUP_APP, 'SETUP_APP', strings);

packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts

@@ -1012,7 +1012,7 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       },
       end_user_controls: {
         label: "End-user controls",
-        description: "What end users can do on this view — quick filters, filter tabs, visualization switching (ADR-0047, Airtable Interface parity)."
+        description: "What end users can do on this view — quick filters, filter tabs, visualization switching."
       },
       navigation_sharing: {
         label: "Navigation & sharing",
@@ -2323,23 +2323,23 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       },
       isDefault: {
         label: "Is Default",
-        helpText: "App baseline for the everyone position (ADR-0090 D5): an app-level set is auto-bound at boot; a package-level set becomes an install-time suggestion an admin confirms. Default false."
+        helpText: "Gives this set to everyone who signs in, through the built-in everyone position. A set the app itself declares is granted at startup; a set from an installed package becomes a suggestion an admin confirms in Setup. A set with high-privilege permissions is never granted this way. Default false."
       },
       managedBy: {
         label: "Managed By",
-        helpText: "Record provenance (ADR-0086 D3): who owns this set across upgrades."
+        helpText: "Who owns this set: Package means it ships with a package and package upgrades update it; Platform and User mean it was created in this environment and upgrades leave it alone."
       },
       packageId: {
         label: "Package Id",
-        helpText: "Owning package id for a package-shipped set (ADR-0086 D3). Leave empty for an environment-authored set."
+        helpText: "The package that ships this set; a value naming any other package is refused. Leave empty for a set created in this environment."
       },
       systemPermissions: {
         label: "System Permissions",
         helpText: "List of system capability keys"
       },
       adminScope: {
         label: "Admin Scope",
-        helpText: "Delegated administration (ADR-0090 D12): lets holders of this set administer one business-unit subtree. businessUnit is the subtree root (sys_business_unit.name) and is required, non-blank; includeSubtree defaults to true; manageAssignments defaults to false and lets the holder assign people to positions, and grant sets directly, inside that subtree; a delegate may hand out only the sets named in assignablePermissionSets. Leave empty for a set that delegates nothing."
+        helpText: "Delegated administration: lets holders of this set administer one business-unit subtree. businessUnit is the subtree root (sys_business_unit.name) and is required, non-blank; includeSubtree defaults to true; manageAssignments defaults to false and lets the holder assign people to positions, and grant sets directly, inside that subtree; a delegate may hand out only the sets named in assignablePermissionSets. Leave empty for a set that delegates nothing."
       },
       objects: {
         label: "Objects",
@@ -2384,7 +2384,7 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       },
       delegatable: {
         label: "Delegatable",
-        helpText: "Holders may delegate this position themselves, time-boxed and with a reason (ADR-0091 D3). Default false — delegation is admin-only."
+        helpText: "Holders may delegate this position themselves, time-boxed and with a reason. Default false — delegation is admin-only."
       }
     }
   },

packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts

@@ -1012,7 +1012,7 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       end_user_controls: {
         label: "Controles de usuario final",
-        description: "Lo que los usuarios finales pueden hacer en esta vista: filtros rápidos, pestañas de filtro, cambio de visualización (ADR-0047, paridad con Airtable Interface)."
+        description: "Lo que los usuarios finales pueden hacer en esta vista: filtros rápidos, pestañas de filtro, cambio de visualización."
       },
       navigation_sharing: {
         label: "Navegación y uso compartido",
@@ -2323,23 +2323,23 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       isDefault: {
         label: "Predeterminado",
-        helpText: "Línea base de la aplicación para la posición everyone (ADR-0090 D5): un conjunto de nivel de aplicación se vincula automáticamente al arrancar; uno de nivel de paquete se convierte en una sugerencia que el administrador confirma al instalar. false por defecto."
+        helpText: "Concede este conjunto a todos los que inician sesión, mediante la posición integrada everyone. Un conjunto que declara la propia aplicación se concede al arrancar; uno de un paquete instalado se convierte en una sugerencia que un administrador confirma en Setup. Un conjunto con permisos de alto privilegio nunca se concede así. false por defecto."
       },
       managedBy: {
         label: "Gestionado por",
-        helpText: "Procedencia del registro (ADR-0086 D3): quién es el propietario de este conjunto entre actualizaciones."
+        helpText: "Quién es el propietario de este conjunto: Package indica que se distribuye con un paquete y que las actualizaciones del paquete lo modifican; Platform y User indican que se creó en este entorno y que las actualizaciones no lo tocan."
       },
       packageId: {
         label: "ID de paquete",
-        helpText: "Id del paquete propietario de un conjunto distribuido con un paquete (ADR-0086 D3). Déjalo vacío para un conjunto creado en el entorno."
+        helpText: "El paquete que distribuye este conjunto; un valor que nombra otro paquete se rechaza. Déjalo vacío para un conjunto creado en este entorno."
       },
       systemPermissions: {
         label: "Permisos del sistema",
         helpText: "Lista de claves de capacidades del sistema"
       },
       adminScope: {
         label: "Ámbito de administración delegada",
-        helpText: "Administración delegada (ADR-0090 D12): permite a quienes tienen este conjunto administrar un subárbol de unidades de negocio. businessUnit es la raíz del subárbol (sys_business_unit.name), es obligatorio y no puede estar en blanco; includeSubtree vale true por defecto; manageAssignments vale false por defecto y permite al titular asignar personas a puestos, y conceder conjuntos directamente, dentro de ese subárbol; un delegado solo puede asignar los conjuntos nombrados en assignablePermissionSets. Déjalo vacío en un conjunto que no delega nada."
+        helpText: "Administración delegada: permite a quienes tienen este conjunto administrar un subárbol de unidades de negocio. businessUnit es la raíz del subárbol (sys_business_unit.name), es obligatorio y no puede estar en blanco; includeSubtree vale true por defecto; manageAssignments vale false por defecto y permite al titular asignar personas a puestos, y conceder conjuntos directamente, dentro de ese subárbol; un delegado solo puede asignar los conjuntos nombrados en assignablePermissionSets. Déjalo vacío en un conjunto que no delega nada."
       },
       objects: {
         label: "Permisos de objeto",
@@ -2384,7 +2384,7 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       delegatable: {
         label: "Delegable",
-        helpText: "Quienes la ocupan pueden delegar esta posición por sí mismos, con un plazo y un motivo (ADR-0091 D3). false por defecto: la delegación es solo para administradores."
+        helpText: "Quienes la ocupan pueden delegar esta posición por sí mismos, con un plazo y un motivo. false por defecto: la delegación es solo para administradores."
       }
     }
   },

packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts

@@ -1012,7 +1012,7 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       end_user_controls: {
         label: "エンドユーザー操作",
-        description: "このビューでエンドユーザーが行える操作——クイックフィルター、フィルタータブ、可視化切り替え（ADR-0047、Airtable Interface 互換）。"
+        description: "このビューでエンドユーザーが行える操作——クイックフィルター、フィルタータブ、可視化切り替え。"
       },
       navigation_sharing: {
         label: "ナビゲーションと共有",
@@ -2323,23 +2323,23 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       isDefault: {
         label: "既定の権限セット",
-        helpText: "everyone ポジション向けのアプリ基準です（ADR-0090 D5）。アプリレベルのセットは起動時に自動でバインドされ、パッケージレベルのセットはインストール時に管理者が確認する提案になります。既定は false です。"
+        helpText: "組み込みの everyone ポジションを通じて、サインインするすべてのユーザーにこのセットを付与します。アプリ自身が宣言したセットは起動時に付与され、インストールしたパッケージのセットは管理者が Setup で確認する提案になります。高権限を含むセットはこの方法では付与されません。既定は false です。"
       },
       managedBy: {
         label: "管理元",
-        helpText: "レコードの由来（ADR-0086 D3）。アップグレードをまたいで、このセットを誰が所有するかを示します。"
+        helpText: "このセットの所有者です。Package はパッケージに同梱され、パッケージのアップグレードで更新されることを示します。Platform と User はこの環境で作成され、アップグレードで変更されないことを示します。"
       },
       packageId: {
         label: "所属パッケージ ID",
-        helpText: "パッケージ同梱のセットが属するパッケージ id（ADR-0086 D3）。環境側で作成したセットでは空のままにします。"
+        helpText: "このセットを同梱しているパッケージです。別のパッケージを指す値は拒否されます。この環境で作成したセットでは空のままにします。"
       },
       systemPermissions: {
         label: "システム権限",
         helpText: "システム機能キーのリスト"
       },
       adminScope: {
         label: "委任管理スコープ",
-        helpText: "委任管理（ADR-0090 D12）: この権限セットの保持者が 1 つのビジネスユニットのサブツリーを管理できるようにします。businessUnit はサブツリーのルート（sys_business_unit.name）で、必須かつ空白不可です。includeSubtree の既定値は true です。manageAssignments の既定値は false で、有効にすると保持者はそのサブツリー内でユーザーをポジションに割り当て、権限セットを直接付与できます。委任先が付与できるのは assignablePermissionSets に挙げた権限セットだけです。何も委任しない権限セットでは空のままにしてください。"
+        helpText: "委任管理: この権限セットの保持者が 1 つのビジネスユニットのサブツリーを管理できるようにします。businessUnit はサブツリーのルート（sys_business_unit.name）で、必須かつ空白不可です。includeSubtree の既定値は true です。manageAssignments の既定値は false で、有効にすると保持者はそのサブツリー内でユーザーをポジションに割り当て、権限セットを直接付与できます。委任先が付与できるのは assignablePermissionSets に挙げた権限セットだけです。何も委任しない権限セットでは空のままにしてください。"
       },
       objects: {
         label: "オブジェクト権限",
@@ -2384,7 +2384,7 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       },
       delegatable: {
         label: "セルフ委任を許可",
-        helpText: "保有者が自分でこのポジションを委任できるようにします。期間を区切り、理由の記入が必要です（ADR-0091 D3）。既定は false で、委任は管理者のみです。"
+        helpText: "保有者が自分でこのポジションを委任できるようにします。期間を区切り、理由の記入が必要です。既定は false で、委任は管理者のみです。"
       }
     }
   },