Integrate current review domains

Merge current main because it added four active AL review leaves, then extend the findings domain contract across all 15 leaves, generic composition guidance, plugin documentation, and the self-review knowledge-upgrade path.

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

Copilot-Session: 77d0a40e-8bf5-40ac-a450-40eb0255db03

skills/bcquality-al-review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: bcquality-al-review
+description: Review Business Central AL code changes using the BCQuality knowledge base. Use when reviewing an AL pull request, a working-tree diff, or a single AL file, and you want findings backed by BCQuality's curated, BC-specific quality rules.
+---
+
+# BCQuality AL review
+
+This skill drives the BCQuality **Entry protocol** over the knowledge base that ships
+inside this plugin. It is the plugin entry point for consumers (orchestrators, CLIs)
+that do not already know BCQuality's internal conventions — the only convention they
+need is "invoke this skill for an AL review."
+
+BCQuality itself is orchestrator-agnostic content: knowledge files plus routing and
+action skills. This bridge is the thin consumer glue that lets a plugin host run that
+content without hardcoding BCQuality's layout.
+
+## When to use
+
+- Reviewing an AL pull request or an uncommitted working-tree diff.
+- Reviewing a single AL file.
+- Any task whose goal is "review Business Central / AL code for quality issues."
+
+Do **not** use this skill to *generate* AL code — it only reviews.
+
+## Plugin root
+
+Resolve `PLUGIN_ROOT` to the directory that contains this plugin's
+`.claude-plugin/plugin.json`. This skill lives at
+`PLUGIN_ROOT/skills/bcquality-al-review/SKILL.md`, so `PLUGIN_ROOT` is two levels up
+from this file. All paths below are relative to `PLUGIN_ROOT`. If the host exposes a
+plugin-root environment variable, prefer it.
+
+## Steps
+
+1. **Refresh the knowledge index (best effort).** If `pwsh` is available, run
+   `pwsh PLUGIN_ROOT/tools/Build-KnowledgeIndex.ps1` from `PLUGIN_ROOT` to (re)generate
+   `PLUGIN_ROOT/knowledge-index.json` over the installed tree. This is a discovery
+   accelerator only — if `pwsh` is missing or the build fails, continue; the review
+   skills fall back to path-based discovery.
+
+2. **Run Entry.** Read `PLUGIN_ROOT/skills/entry.md` and execute it against a
+   task context describing the review:
+
+   ```yaml
+   task-context:
+     goal: "Review the AL changes for quality issues"
+     inputs-available: [pr-diff]        # or [file-path] for single-file review
+     technologies: [al]
+     enabled-layers: [microsoft, community, custom]   # see "Layer selection" below
+   ```
+
+   **Layer selection.** `enabled-layers` defaults to all three layers. A host can
+   narrow it by setting the `BCQUALITY_ENABLED_LAYERS` environment variable to a
+   comma-separated subset (e.g. `microsoft` or `microsoft,community`); when set, pass
+   exactly those layers instead of the default. This is the plugin path's only knob
+   for layer policy — see the limitation in Notes.
+
+   Fill `bc-version`, `countries`, and `application-area` only when the caller
+   supplies them; omit them otherwise (an omitted dimension is unconstrained).
+
+3. **Follow the dispatch record.** Entry returns a dispatch record naming the action
+   skill(s) to invoke — for a PR review this is normally
+   `microsoft/skills/review/al-code-review.md`. For each dispatched skill, read the
+   file and execute its Source → Relevance → Worklist → Action steps, reading
+   `PLUGIN_ROOT/skills/read.md` and `PLUGIN_ROOT/skills/do.md` on demand.
+
+4. **Emit findings.** Produce the rolled-up findings report in the DO output contract,
+   including each review finding's producer-supplied `domain` label (`outcome`,
+   `findings`, `references`, `confidence`, `suppressed`). Do not invent a different
+   shape; downstream consumers parse the DO contract without skill-specific logic.
+
+If Entry returns `no-match` or `failed`, return the dispatch record unchanged so the
+caller can log the reason.
+
+## Notes
+
+- This skill adds nothing to BCQuality's knowledge or routing logic; it only bootstraps
+  the existing Entry protocol from a plugin host. Knowledge and skill changes belong in
+  the layers under `PLUGIN_ROOT/microsoft/`, `PLUGIN_ROOT/community/`, and
+  `PLUGIN_ROOT/custom/`, not here.
+- **Layer pruning is coarser than the URL/clone model.** In the clone model a consumer
+  prunes its checkout to policy *before* the agent runs, and the knowledge index is
+  rebuilt over the pruned tree, so a denied layer can never leak into discovery. A
+  plugin install ships the whole tree, so this bridge can only *narrow discovery* via
+  `enabled-layers` (`BCQUALITY_ENABLED_LAYERS`) — the denied layers' files still exist on
+  disk. Treat `enabled-layers` as a selection filter, not a hard security boundary. A
+  future revision could add a genuine deny mechanism (e.g. pruning the installed tree).
+- **Manifest location.** This plugin uses `.claude-plugin/plugin.json`, which both
+  Claude Code and Copilot CLI accept (verified with Copilot CLI: `plugin install`
+  reports the bridge skill loaded). Copilot CLI also accepts a root `plugin.json`; if a
+  future host only reads the root form, dual-home the manifest.

skills/do.md

@@ -190,7 +190,7 @@ The first reference is the **primary** reference: the knowledge file the finding
 
 **`findings[].from-sub-skill`** — optional. Set only by super-skills. The `skill.id` of the sub-skill that produced the finding, or the literal string `"agent"` for an agent finding the super-skill produced from its own cross-cutting reasoning. Absent on findings emitted directly by a leaf skill — including agent findings the leaf emits within its own domain, which appear in the leaf's own report without this field.
 
-**`findings[].domain`** — optional. A short, human-readable display label for the review domain that produced the finding (for example, `Security`, `Performance`, `Accessibility`). Set by the leaf skill on every finding it emits. The super-skill preserves it verbatim when rolling a sub-skill's finding into its top-level `findings[]`, and sets it to `"Agent"` for the agent findings it emits about cross-cutting concerns. Consumers SHOULD render it verbatim and MUST tolerate its absence (older producers may not emit it).
+**`findings[].domain`** — optional in the shared schema for backward compatibility and for non-review findings. It is a short, human-readable display label for the review domain that produced the finding (for example, `Security`, `Performance`, `Accessibility`). A review leaf skill MUST set it on every finding it emits. A review super-skill MUST preserve it verbatim when rolling a leaf finding into its top-level `findings[]`, including preserving its absence from older producers, and MUST set it to `"Agent"` for agent findings it emits about cross-cutting concerns. Consumers SHOULD render a non-empty value verbatim and MUST tolerate its absence.
 
 **`findings[].suggested-code`** — optional in the schema but **expected for mechanical findings**. It is a concrete code-replacement payload for the lines indicated by `location`. When present, the string MUST be a literal replacement for the source lines covered by `location.line` (or `location.range` if set) — i.e., what the file would contain after the fix, with no surrounding diff markers, fences, or commentary. Consumers MAY render it as a one-click suggestion in the delivery surface (for example, a GitHub ```` ```suggestion ```` block).
 
@@ -229,7 +229,7 @@ The five required sections still apply. Their meaning shifts from knowledge file
 - `## Source` — names the sub-skills invoked (mirrors `sub-skills` in frontmatter).
 - `## Relevance` — rules for deciding which sub-skills apply to the current task. A sub-skill is relevant when its declared `inputs` are satisfied by the orchestrator's provided inputs and the orchestrator has not disabled it via configuration. The super-skill MUST NOT filter sub-skills by task content (for example, by inspecting the diff or the file). Task-level applicability is the sub-skill's own responsibility; sub-skills signal non-applicability by returning `outcome: "not-applicable"` or `outcome: "no-knowledge"`.
 - `## Worklist` — the final list of sub-skills to invoke; the rest go to `skipped-sub-skills`.
-- `## Action` — invoke each worklisted sub-skill with the appropriate subset of inputs, collect its findings-report verbatim into `sub-results`, and copy its `findings[]` into the super-skill's top-level `findings[]` with `from-sub-skill` set. Findings from a sub-skill with `outcome: "failed"` MUST NOT be copied into the super-skill's top-level `findings[]` and MUST NOT contribute to the super-skill's `summary.counts` (their report is still preserved in `sub-results` for traceability, consistent with DO's rule that consumers ignore a failed skill's findings).
+- `## Action` — invoke each worklisted sub-skill with the appropriate subset of inputs, collect its findings-report verbatim into `sub-results`, and copy its `findings[]` into the super-skill's top-level `findings[]` with `from-sub-skill` set. All finding fields, including the optional `domain`, are preserved verbatim unless this contract explicitly requires a transformation. Findings from a sub-skill with `outcome: "failed"` MUST NOT be copied into the super-skill's top-level `findings[]` and MUST NOT contribute to the super-skill's `summary.counts` (their report is still preserved in `sub-results` for traceability, consistent with DO's rule that consumers ignore a failed skill's findings).
 - `## Output` — the super-skill's output contract, including `sub-results` and, if any, `skipped-sub-skills`.
 
 ### Outcome rollup
@@ -292,4 +292,3 @@ Conforms to the DO output contract.
 
 An orchestrator invokes an action skill with an input appropriate to the skill's declared `inputs`, receives the JSON output, and maps findings to its delivery surface (PR comments, build gates, IDE diagnostics). The orchestrator MUST NOT interpret skill-specific fields beyond the schema above. Skills that need richer semantics MUST encode them within the schema (for example, by adding structured `message` text) rather than extending the output shape.
 
-

skills/read.md

@@ -115,7 +115,7 @@ Consumers MUST NOT silently treat missing context as a match.
 
 ## Citing a knowledge file
 
-A consumer that produces output referencing a knowledge file MUST cite it by its repo-relative path (for example, `microsoft/knowledge/performance/filter-before-find.md`). Line numbers are not stable references; use the file path only. If a commit SHA is available to the consumer, it SHOULD be included alongside the path.
+A consumer that produces output referencing a knowledge file MUST cite it by its repo-relative path (for example, `microsoft/knowledge/performance/apply-filters-before-iterating.md`). Line numbers are not stable references; use the file path only. If a commit SHA is available to the consumer, it SHOULD be included alongside the path.
 
 ## Sample files
 

skills/write.md

@@ -65,6 +65,17 @@ Knowledge files do not contain code. Samples live as **sibling files** next to t
 - **`/community/knowledge/<domain>/`** — shared community patterns. The default layer for contributions from outside the platform team. Content here can be promoted to `/microsoft/` once it proves itself.
 - **`/custom/knowledge/<domain>/`** — partner or customer overrides. Generally does not appear in the BCQuality repository itself; `/custom/` lives in consumer repositories.
 
+### Writing to `/custom/` — fork precondition
+
+The `/custom/` layer is **empty by default** in the upstream `microsoft/BCQuality` repository — it ships as a template (`README.md` plus `.gitkeep` placeholders) and is meant to be populated only inside a **fork or consumer clone** that an organization controls. Custom content is partner- or customer-specific by definition and is never accepted upstream.
+
+Before authoring or scaffolding any file under `/custom/knowledge/` or `/custom/skills/`, an author — human or agent — MUST confirm the working repository is **not** `microsoft/BCQuality`:
+
+- Check the `origin` remote: `git remote get-url origin`. If it points at `github.com/microsoft/BCQuality`, stop — you are in the upstream repo, not a fork.
+- If you are in the upstream repo, do not write the file. Either fork the repository (or clone it into your organization's own repo) and add the custom content there, or — if the guidance is genuinely shareable — author it in `/community/knowledge/` instead.
+
+A pull request that adds `/custom/` content to `microsoft/BCQuality` will be **automatically closed** by the `Guard custom layer` workflow. Validate the fork precondition first so authoring effort is not wasted on a PR that cannot be merged.
+
 ## Pre-PR checklist
 
 Before opening a pull request: