Define mandatory suggested-code classes

Follow-up to BCQuality#22. The previous contract made suggested-code
expected for mechanical findings, but still left too much judgement to
the model. In the synthetic benchmark, BCQ produced omission reasons
for 11 mechanical-looking findings instead of suggestions.

Add explicit must-suggest classes where omission is not allowed when
location points to the affected line/range and the replacement can be
expressed as one contiguous block:
- missing OptionCaption
- missing ToolTip
- formatter-only casing/spacing defects
- Count() existence/repeated-count fixes
- unreachable/dead contiguous blocks
- over-broad permission tokens with an obvious narrower token
- obvious DataClassification additions
- local Label moves when the target range includes both old and new
  declaration locations

Update all AL leaf skills and al-code-review to reference these
must-suggest classes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

microsoft/skills/review/al-code-review.md

@@ -104,7 +104,7 @@ Leaf-level agent findings (those with `references: []` inside a sub-skill's repo
 
 ### Suggested-code guidance
 
-For both knowledge-backed findings rolled up from sub-skills and agent findings emitted in the self-review pass, populate `findings[].suggested-code` whenever a concrete code replacement is unambiguous from the diff context. This is a MUST for small, local, mechanical fixes. The payload MUST be a literal replacement for the source lines covered by `location` (typically a single line, or the line range in `location.range`) — no diff markers, fences, or commentary. Examples of good candidates: deleting dead code after `exit`, replacing `Count() > 0` with `not IsEmpty()`, moving an inline `Label` declaration to a codeunit-level `var` block, adding a missing property, replacing string-concatenated `Error`, changing an over-broad permission token, fixing whitespace or keyword casing. Skip `suggested-code` only when the fix requires choosing between multiple defensible alternatives, when the fix spans non-contiguous code, or when the surrounding context the agent cannot see could change the answer. If a mechanical-looking finding omits `suggested-code`, set `suggested-code-omission-reason`.
+For both knowledge-backed findings rolled up from sub-skills and agent findings emitted in the self-review pass, populate `findings[].suggested-code` whenever a concrete code replacement is unambiguous from the diff context. This is a MUST for small, local, mechanical fixes. The payload MUST be a literal replacement for the source lines covered by `location` (typically a single line, or the line range in `location.range`) — no diff markers, fences, or commentary. Examples of good candidates: deleting dead code after `exit`, replacing `Count() > 0` with `not IsEmpty()`, moving an inline `Label` declaration to a codeunit-level `var` block, adding a missing property, replacing string-concatenated `Error`, changing an over-broad permission token, fixing whitespace or keyword casing. The must-suggest classes from `skills/do.md` are mandatory here too: missing `OptionCaption`, missing `ToolTip`, formatter-only defects, simple `Count()`/`IsEmpty` replacements, unreachable contiguous blocks, obvious permission-token narrowing, obvious `DataClassification` additions, and local `Label` moves when the target range includes both the old and new declaration locations. Outside those must-suggest classes, skip `suggested-code` only when the fix requires choosing between multiple defensible alternatives, when the fix spans non-contiguous code, or when the surrounding context the agent cannot see could change the answer. If a mechanical-looking finding omits `suggested-code`, set `suggested-code-omission-reason`.
 
 Sub-skills MAY also emit `suggested-code` when their knowledge file unambiguously implies the replacement (the `.good.al` and `.bad.al` companion examples are useful here). The super-skill copies the field through unchanged.
 
@@ -314,3 +314,4 @@ The empty-corpus case — BCQuality's state until knowledge files land — rolls
 }
 ```
 
+

microsoft/skills/review/al-performance-review.md

@@ -64,8 +64,9 @@ Set `confidence` to:
 After evaluating each worklist entry, also consider whether the diff exhibits a performance defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). The scope is strictly performance; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract.
 
 For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace `Count() > 0` with `not IsEmpty()`; move a local `Label` to object scope; add a missing `ToolTip`, `OptionCaption`, or `DataClassification`; replace a string-concatenated `Error` with a Label-backed call; change an over-broad permission token; or add an obvious `else`/guard branch). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`.
+For must-suggest classes, omission is not allowed when `location` points to the affected line/range and the replacement can be expressed as one contiguous block. Must-suggest classes are: missing `OptionCaption`; missing `ToolTip`; formatter-only casing/spacing defects; `Count() > 0` / repeated `Count()` existence checks; unreachable code after an unconditional terminator; over-broad permission tokens with an obvious narrower token; obvious `DataClassification` additions; and local `Label` moves when the target range includes both the local declaration and the object-level insertion point.
 
-Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
+Outside the must-suggest classes, omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
 
 Outcome selection:
 
@@ -135,3 +136,4 @@ The empty-corpus case — BCQuality's state until performance knowledge files la
 }
 ```
 
+

microsoft/skills/review/al-privacy-review.md

@@ -64,8 +64,9 @@ Set `confidence` to:
 After evaluating each worklist entry, also consider whether the diff exhibits a privacy defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). The scope is strictly privacy; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract.
 
 For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace `Count() > 0` with `not IsEmpty()`; move a local `Label` to object scope; add a missing `ToolTip`, `OptionCaption`, or `DataClassification`; replace a string-concatenated `Error` with a Label-backed call; change an over-broad permission token; or add an obvious `else`/guard branch). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`.
+For must-suggest classes, omission is not allowed when `location` points to the affected line/range and the replacement can be expressed as one contiguous block. Must-suggest classes are: missing `OptionCaption`; missing `ToolTip`; formatter-only casing/spacing defects; `Count() > 0` / repeated `Count()` existence checks; unreachable code after an unconditional terminator; over-broad permission tokens with an obvious narrower token; obvious `DataClassification` additions; and local `Label` moves when the target range includes both the local declaration and the object-level insertion point.
 
-Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
+Outside the must-suggest classes, omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
 
 Outcome selection:
 
@@ -107,3 +108,4 @@ Output conforms to the DO output contract. A populated example:
 }
 ```
 
+

microsoft/skills/review/al-security-review.md

@@ -64,8 +64,9 @@ Set `confidence` to:
 After evaluating each worklist entry, also consider whether the diff exhibits a security defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). The scope is strictly security; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract.
 
 For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace `Count() > 0` with `not IsEmpty()`; move a local `Label` to object scope; add a missing `ToolTip`, `OptionCaption`, or `DataClassification`; replace a string-concatenated `Error` with a Label-backed call; change an over-broad permission token; or add an obvious `else`/guard branch). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`.
+For must-suggest classes, omission is not allowed when `location` points to the affected line/range and the replacement can be expressed as one contiguous block. Must-suggest classes are: missing `OptionCaption`; missing `ToolTip`; formatter-only casing/spacing defects; `Count() > 0` / repeated `Count()` existence checks; unreachable code after an unconditional terminator; over-broad permission tokens with an obvious narrower token; obvious `DataClassification` additions; and local `Label` moves when the target range includes both the local declaration and the object-level insertion point.
 
-Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
+Outside the must-suggest classes, omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
 
 Outcome selection:
 
@@ -135,3 +136,4 @@ The empty-corpus case — BCQuality's state until security knowledge files land
 }
 ```
 
+

microsoft/skills/review/al-style-review.md

@@ -62,8 +62,9 @@ Set `confidence` to:
 After evaluating each worklist entry, also consider whether the diff exhibits a style defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). The scope is strictly style; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract.
 
 For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace `Count() > 0` with `not IsEmpty()`; move a local `Label` to object scope; add a missing `ToolTip`, `OptionCaption`, or `DataClassification`; replace a string-concatenated `Error` with a Label-backed call; change an over-broad permission token; or add an obvious `else`/guard branch). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`.
+For must-suggest classes, omission is not allowed when `location` points to the affected line/range and the replacement can be expressed as one contiguous block. Must-suggest classes are: missing `OptionCaption`; missing `ToolTip`; formatter-only casing/spacing defects; `Count() > 0` / repeated `Count()` existence checks; unreachable code after an unconditional terminator; over-broad permission tokens with an obvious narrower token; obvious `DataClassification` additions; and local `Label` moves when the target range includes both the local declaration and the object-level insertion point.
 
-Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
+Outside the must-suggest classes, omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
 
 Outcome selection:
 
@@ -104,3 +105,4 @@ Output conforms to the DO output contract. A populated example:
 }
 ```
 
+

microsoft/skills/review/al-ui-review.md

@@ -62,8 +62,9 @@ Set `confidence` to:
 After evaluating each worklist entry, also consider whether the diff exhibits a UI defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). The scope is strictly UI; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract.
 
 For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace `Count() > 0` with `not IsEmpty()`; move a local `Label` to object scope; add a missing `ToolTip`, `OptionCaption`, or `DataClassification`; replace a string-concatenated `Error` with a Label-backed call; change an over-broad permission token; or add an obvious `else`/guard branch). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`.
+For must-suggest classes, omission is not allowed when `location` points to the affected line/range and the replacement can be expressed as one contiguous block. Must-suggest classes are: missing `OptionCaption`; missing `ToolTip`; formatter-only casing/spacing defects; `Count() > 0` / repeated `Count()` existence checks; unreachable code after an unconditional terminator; over-broad permission tokens with an obvious narrower token; obvious `DataClassification` additions; and local `Label` moves when the target range includes both the local declaration and the object-level insertion point.
 
-Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
+Outside the must-suggest classes, omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
 
 Outcome selection:
 
@@ -104,3 +105,4 @@ Output conforms to the DO output contract. A populated example:
 }
 ```
 
+

microsoft/skills/review/al-upgrade-review.md

@@ -64,8 +64,9 @@ Set `confidence` to:
 After evaluating each worklist entry, also consider whether the diff exhibits a upgrade defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). The scope is strictly upgrade; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract.
 
 For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: delete unreachable lines; replace `Count() > 0` with `not IsEmpty()`; move a local `Label` to object scope; add a missing `ToolTip`, `OptionCaption`, or `DataClassification`; replace a string-concatenated `Error` with a Label-backed call; change an over-broad permission token; or add an obvious `else`/guard branch). For mechanical findings, emit `findings[].suggested-code` with the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, adapt the `.good.al` replacement into `suggested-code`.
+For must-suggest classes, omission is not allowed when `location` points to the affected line/range and the replacement can be expressed as one contiguous block. Must-suggest classes are: missing `OptionCaption`; missing `ToolTip`; formatter-only casing/spacing defects; `Count() > 0` / repeated `Count()` existence checks; unreachable code after an unconditional terminator; over-broad permission tokens with an obvious narrower token; obvious `DataClassification` additions; and local `Label` moves when the target range includes both the local declaration and the object-level insertion point.
 
-Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
+Outside the must-suggest classes, omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit `suggested-code`, set `findings[].suggested-code-omission-reason` to a short explanation. See `skills/do.md` for the full contract.
 
 Outcome selection:
 
@@ -106,3 +107,4 @@ Output conforms to the DO output contract. A populated example:
 }
 ```
 
+

skills/do.md

@@ -179,7 +179,18 @@ The first reference is the **primary** reference: the knowledge file the finding
 
 Emit `suggested-code` whenever the fix is small, local, and mechanical: deleting unreachable code; replacing one expression (`Count() > 0` → `not IsEmpty()`); moving a local `Label` to object scope; adding a missing property such as `ToolTip`, `OptionCaption`, or `DataClassification`; replacing a string-concatenated `Error` with a Label-backed call; changing a permission token; or adding a missing `else`/guard branch whose replacement is unambiguous from the surrounding diff. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, prefer adapting the `.good.al` replacement into `suggested-code`.
 
-Omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but `suggested-code` is omitted, set `findings[].suggested-code-omission-reason` to a short explanation (for example, `requires choosing a real event id` or `fix spans multiple non-contiguous locations`). The `suggested-code` payload supplements `message`; it does not replace the explanation in `message`.
+For the following **must-suggest classes**, omission is not allowed when `location` points to the affected line/range and the replacement can be expressed as one contiguous block:
+
+- missing `OptionCaption` on an `Option` field: add `OptionCaption` matching the existing members;
+- missing `ToolTip` on a page field/control: add a concise `ToolTip` property for that control;
+- uppercase reserved keywords or simple formatter-only whitespace/casing defects: emit the formatted line/range;
+- `Count() > 0` or repeated `Count()` used only for existence: replace with `not IsEmpty()` or cache the count in a local variable when the return value is also needed;
+- unreachable/dead code after an unconditional terminator (`exit`, `Error`, `break`, `continue`): remove the unreachable contiguous block;
+- over-broad AL permission tokens where the required token is obvious (`rimd` on read-only access -> `r`): replace the permission token or permission line;
+- missing `DataClassification` where the correct value is explicit in the same knowledge article or obvious from the field (`SystemMetadata` for setup flags/keys, `CustomerContent` for customer-entered content): add the property;
+- local `Label` declaration that can be moved to object scope without renaming or changing text: emit the replacement only when the target range includes both the local declaration and the object-level insertion point; otherwise use `suggested-code-omission-reason`.
+
+Outside the must-suggest classes, omit `suggested-code` only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but `suggested-code` is omitted, set `findings[].suggested-code-omission-reason` to a short explanation (for example, `requires choosing a real event id` or `fix spans multiple non-contiguous locations`). The `suggested-code` payload supplements `message`; it does not replace the explanation in `message`.
 
 **`findings[].suggested-code-omission-reason`** — optional. Required when a finding is mechanical-looking but `suggested-code` is omitted. Short, human-readable reason explaining why no safe one-click replacement was emitted. Consumers MAY use this for telemetry or diagnostics; they do not have to render it in review comments.