Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 14:46:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Merge main into AL development guidance

Browse source 
Reconcile the read-only plan-enrichment contracts with main's folder-review
inputs and documentation structure. Record Windows alternate streams in
runner evidence and clear the regression harness exit status after expected
negative probes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 638b66d2-9f06-4f60-8781-808709e1485c
This commit is contained in:
Jesper Schulz-Wedde 2026-09-11 09:35:59 +02:00
commit 332947bcdb
298 changed files with 1818 additions and 780 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/README.md Normal file
View file

@ -0,0 +1,34 @@
# BCQuality documentation
**New to BCQuality? Start with the [quick start](../README.md#quick-start).**
Install the plugin, discover its skills, and try an app review. No knowledge
of BCQuality's internal protocol is needed.
## Partner guides
| Goal | Guide |
| --- | --- |
| Choose direct reading, a supplied skill, or my own agent | [Ways to use BCQuality](using-bcquality.md#choose-how-to-use-bcquality) |
| Review an app, file, changes, or branch | [Using BCQuality](using-bcquality.md) |
| Understand a report and its limitations | [Reading your results](using-bcquality.md#reading-your-results) |
| Find a particular rule or example | [Knowledge by domain](using-bcquality.md#knowledge-by-domain) |
| Fix setup problems or report an incorrect finding | [Troubleshooting and support](troubleshooting.md) |
| Select layers, add company rules, or maintain a fork | [Customizing BCQuality](customizing-bcquality.md) |
| Add or improve shared knowledge | [Your first contribution](contributing.md#your-first-contribution) |
## Integration and technical reference
These pages are for people building integrations or maintaining skills, not
prerequisites for using the plugin.
| Reference | Purpose |
| --- | --- |
| [Minimal integration example](agent-consumption.md#try-a-minimal-integration) | A bootstrap prompt connecting your agent to a BCQuality checkout and an app folder. |
| [How agents consume BCQuality](agent-consumption.md) | Architecture, repository structure, routing, and delivery of findings. |
| [Standalone runner](standalone-runner.md) | Optional model selection, scheduling, retries, and telemetry. |
| [Global skills](../skills/README.md) | Host adapters versus internal protocol files. |
| [Entry](../skills/entry.md) | Task context and skill dispatch. |
| [READ](../skills/read.md) | Knowledge schema, applicability, and precedence. |
| [DO](../skills/do.md) | Action-skill format and structured output contract. |
| [WRITE](../skills/write.md) | Knowledge-authoring rules. |
| [Review evaluation](../evaluation/README.md) | Sample conventions, fixture preparation, and scoring. |

274
docs/agent-consumption.md Normal file
View file

@ -0,0 +1,274 @@
# How agents consume BCQuality
BCQuality is content — knowledge files and skills. It is consumed by agents
supplied by a host or orchestrator. This document explains the end-to-end flow
so that skill authors, orchestrator maintainers, and contributors share one
mental model.
[Documentation](README.md) | [Partner quick start](../README.md#quick-start) | [Runner contract](standalone-runner.md)
This is the operational reference for integration authors. Partners using
the installed plugin do not need to implement this flow themselves.
## Try a minimal integration
**"Invoke `skills/entry.md`" means ask your agent to read and follow that
instruction document.** It is not a shell command, HTTP endpoint, or executable
library. Your host must be able to read files, enumerate directories, and
execute the selected skills as instructed. Merely mentioning BCQuality does
not make its content available to the model.
For a first integration, create or reuse a dedicated BCQuality checkout.
For example, in PowerShell:
```powershell
git clone https://github.com/microsoft/BCQuality.git "C:\Knowledge\BCQuality"
```
Give the host access to **both** that content directory and your own app
directory. The plugin is not required for this route. Replace the paths and
BC version below with your actual values, then send this prompt to the agent:
```text
BCQuality root: C:\Knowledge\BCQuality
Review input: folder-path = C:\Repos\MyBusinessCentralApp
Read BCQuality's skills\entry.md and follow it with this task context:
task-context:
goal: Review the complete AL app without changing its source files.
inputs-available: [folder-path]
technologies: [al]
bc-version: 28
enabled-layers: [microsoft, community, custom]
disabled-skills: []
Resolve BCQuality instructions, knowledge, and index preparation against the
BCQuality root, not the app directory. Pass the actual review-input path above
when a dispatched skill accepts folder-path.
Follow Entry's preparation and dispatch instructions. Execute every dispatched
action skill with its exact input subset, reading READ and DO on demand.
Return each complete findings report unchanged. If Entry returns no-match or
failed, return that dispatch record unchanged instead of inventing a review.
```
`inputs-available` lists input **types**; the `Review input` line binds the type
to the actual app directory. It is not an extra Entry schema field. Omit
`bc-version` when unknown rather than guessing it; add localization or
application-area context only when known. Keep the two roots distinct so index
preparation operates on BCQuality, not your app.
Expect Entry to select the action skills and the agent to execute them.
A broad review normally returns the Microsoft coordinator's report with
domain `sub-results`, plus any separately dispatched reports. Each report
must retain its outcome, including incomplete or failed work; see
[reading results](using-bcquality.md#reading-your-results). A dispatch record
alone is not a completed review.
This prompt delegates the existing protocol rather than implementing new
routing logic. For repeatable runs, [pin the checkout](customizing-bcquality.md#updates-and-versions).
Add scheduling, retries, and rendering only when needed, using the
[runner contract](standalone-runner.md).
## The actors
- **Orchestrator** — the tool that triggers work. Lives *outside* BCQuality. Knows *when* to run something, not *what* to run.
- **Agent** — an LLM-driven process supplied by the host. It brings its own coding knowledge and tools; BCQuality adds curated guidance and execution contracts.
- **BCQuality repo** — two kinds of content:
- **Global skills** in `/skills/` — the `entry.md` entry-point skill plus the READ · DO · WRITE contracts that govern the rest of the repo.
- **Layer content** in `/microsoft/`, `/community/`, and `/custom/` — knowledge files and action skills grouped by authority.
When BCQuality is installed as a standalone plugin, it additionally exposes
`skills/al-code-review/SKILL.md` and
`skills/al-development-plan/SKILL.md`. These are host-format adapters, not
additional action skills: each creates the task context and enters the same
flow at Entry.
## Repository structure
| Path | Purpose |
| --- | --- |
| `skills/entry.md` | Routes a task to action skills. |
| `skills/read.md`, `skills/do.md`, `skills/write.md` | Stable knowledge, action-skill, and authoring contracts. |
| `skills/al-code-review/SKILL.md` | Host-format plugin adapter. |
| `<layer>/knowledge/<domain>/` | Atomic articles and optional sibling samples. |
| `<layer>/skills/` | Layer-owned action skills. |
| `docs/` | Partner guides and integration references. |
| `evaluation/` | Neutral review fixtures and scoring contract. |
| `tools/` | Knowledge-index and evaluation tooling. |
| `.github/` | Validation and repository workflows. |
Layers are `microsoft`, `community`, and `custom`; Custom is a template for
consumer forks. An action skill either evaluates knowledge directly (a leaf)
or composes declared leaves (a super-skill). See [global skills](../skills/README.md)
for the distinction between host-native packaging and these internal formats.
## The flow
```mermaid
flowchart LR
O[Host or orchestrator] -->|1 trigger + task context| A[Agent]
A -->|2 invoke entry.md| E[Entry<br/>routing skill]
E -->|3 dispatch record| A
A -->|4 invoke dispatched skill| S[Action skill<br/>e.g. al-code-review]
S -->|5 execute| P[Source → Relevance<br/>→ Worklist → Action<br/>reading READ · DO on demand]
P -->|6 emit| R[Findings report<br/>or read-only guidance report]
R -->|7 integrate| O
```
### 1. Orchestrator triggers
The orchestrator has a URL setting that points at BCQuality (default: `github.com/microsoft/BCQuality`) and a task to perform. It hands the agent a **task context** — goal, inputs available (`pr-diff`, `file-path`, …), technologies, BC version, enabled layers — and says: *your source of truth lives at that URL; start by invoking `/skills/entry.md`*.
### 2. Agent invokes Entry
The agent reads `/skills/entry.md` and runs it against the task context. Entry applies its Source → Relevance → Worklist → Action steps over the action skills under `*/skills/**/*.md` and returns a **dispatch record**: the set of action skills to invoke, plus a list of candidates it skipped (with reasons). Routing is a skill, not orchestrator logic.
For a standalone plugin installation, the host activates the matching adapter
first. The adapter preserves the caller's actual goal, constructs the task
context, and invokes Entry. It does not select the internal review or
plan-enrichment action skill itself or duplicate Entry's preparation, routing, and
failure semantics.
### 3. Agent consumes the dispatch record
The dispatch record names one or more action skills, the subset of inputs each
should receive, and each skill's output kind. The output kind distinguishes
findings from read-only plan guidance before invocation; it is not proof of
runtime side effects. If the outcome is `no-match` or `failed`, the agent returns
the record to the orchestrator unchanged.
### 4. Agent invokes each dispatched action skill
Action skills live inside the layers — `/microsoft/skills/`, `/community/skills/`, `/custom/skills/` — so their authority is carried by their location. For a PR review, Entry typically dispatches `microsoft/skills/review/al-code-review.md`. The agent reads the file and executes it.
### 5. Action skill executes the four-step pattern
Each action skill is a markdown file that specifies what to do at each step. The template is always the same:
| Step | What happens |
| --- | --- |
| **Source** | Declare which knowledge folders and tags to search. |
| **Relevance** | Filter by frontmatter — `bc-version`, `technologies`, `countries`, `application-area`. |
| **Worklist** | Narrow from N candidates to the M that apply to this specific task. |
| **Action** | Apply the relevant knowledge and produce structured output. |
Example: the Microsoft-owned performance review skill selects `performance` entries across every enabled layer, filters to `bc-version: 26` and `technologies: [al]`, narrows the candidate files to those that apply to the changed objects, and then evaluates each file against the diff. Its canonical corpus lives beside it under `/microsoft/knowledge/performance/`; cross-layer entries are limited to custom overrides or short-lived promotion work.
At this point the agent reads READ and DO on demand — it needs READ to interpret each knowledge file's frontmatter and sections, and DO to shape its output. Those contracts are fetched when first needed, not as part of bootstrap.
### 5a. The knowledge index (Source acceleration)
Discovering candidates at the Source step naively means opening every file under a domain folder just to read its frontmatter `keywords` — on a large corpus that is hundreds of file reads per review. To avoid this, BCQuality maintains a **knowledge index**: a single artifact (`knowledge-index.json`) that lists every article surviving the consumer's layer/allow-deny filtering and carries, per article, the exact inputs the Source/Worklist steps consume — `path`, `layer`, `domain`, frontmatter dimensions, `keywords`, `title`, and a one-line `description` hint.
The index is **owned and produced by BCQuality**, not reimplemented by each
consumer. Its generator, `tools/Build-KnowledgeIndex.ps1`, ships here alongside
the content. Entry ensures the index reflects the live tree before routing
and regenerates it when absent or not known to be current. BCQuality CI
validates that the generator is healthy and deterministic.
Consumers with allow/deny policy must prune their content copy **before**
Entry runs. Building over that pruned tree prevents removed articles from
entering discovery. A standalone plugin normally ships the whole tree:
`enabled-layers` filters discovery but does not remove files or enforce a
security boundary. See [layer selection](customizing-bcquality.md#select-layers-or-disable-a-review).
The index changes only *how candidates are discovered*, never *which are selected*. The Worklist predicate is unchanged — `keywords` still drive selection — and the agent still opens each worklisted article **in full** to read its `## Best Practice` / `## Anti Pattern` rule bodies; the index is discovery metadata only and never substitutes for the article body. When no index is present, skills fall back to path-based discovery (collect by domain folder), so review still works.
### 6. Agent emits structured output
The output contracts are defined in the DO meta-skill:
- A **findings report** carries review findings, domain labels, references, confidence, and suppressions.
- A **development guidance report** carries read-only knowledge constraints and validation considerations for an existing plan.
The orchestrator parses this **without skill-specific logic**. This is the point of the contract: orchestrators and action skills evolve independently.
For plan enrichment, the skill reads the existing plan and target repository,
selects applicable knowledge, and returns constraints without changing the
target. It does not generate a replacement plan, run tests, implement code, or
drive a review/fix loop. Implementation stays in the consuming workflow.
### 7. Orchestrator integrates
The orchestrator turns findings into PR comments, build gates, or IDE diagnostics. It can feed read-only guidance into its own implementation phases, preserving all existing approvals and delivery gates.
## Repository-specific development orchestrators
A repository-specific workflow can consume this read-only foundation before
authoring while retaining its independent final review. This is the intended
integration boundary, not a shipped consumer integration:
1. Investigate and produce the consumer's normal initial plan. Normalize any
consumer-specific format outside BCQuality. A full serialized plan document
containing metadata plus a markdown body (root cause or design intent,
proposed changes, affected files, test strategy, acceptance criteria) is a
valid boundary. A continuation/checkpoint payload is not a substitute for
initial-plan coverage; workflow identifiers and state stay with the consumer.
2. Resolve and record an immutable BCQuality checkout and filtering policy.
Invoke Entry with a read-only enrichment goal, the existing
`development-plan`, `repository`, and established applicability dimensions.
Keep index, guidance, and runner artifacts outside the target repository.
3. Execute the dispatched `al-development-plan` skill. Persist the unchanged
report and provenance **after** any consumer state initialization or cleanup
that could erase them. BCQuality does not own the state directory or lifecycle.
4. Inject relevant constraints and validation considerations into the existing
Baseline, Implement, propagation (such as MiApp), and Critique phases, or
equivalents. Re-enrich on material plan or applicability changes; preserve
the relationship between plan version, guidance, and implementation attempt.
5. Run an independent final BCQuality review against the completed diff using
the **same recorded immutable checkout** used for enrichment. Review the
actual changes, not the guidance report as proof of correctness, then apply
the consumer's ordinary delivery gates.
The consumer owns analysis, normalization, persistence, per-phase injection,
approvals, TDD and runtime execution, propagation, retries, commits, and PR
delivery. BCQuality supplies additional referenced product knowledge, not a
replacement orchestrator.
### Outcomes are additive, not a universal coding gate
`no-knowledge` with empty `knowledge` means no additional applicable BCQuality
constraints. The consumer may proceed under its ordinary gates. It must not be
conflated with failed retrieval/reference integrity (`failed`), incomplete
evaluation or materially unresolved conditional guidance (`partial`), or absent
required inputs (`not-applicable`). Consumers own the policy for handling those
outcomes and recorded unknowns: seek missing context, re-enrich, escalate, or
apply their existing risk controls without relabeling the report as successful.
Do not fill gaps with generic articles simply to unlock implementation.
### Pinning and pilot evidence
A configured tag or ref alone does not establish runtime pinning. Record the
resolved commit and actual checkout/content identity used at invocation, along
with enabled layers, pruning policy, index identity, plan version, and runner
provenance. Verify that identity at both enrichment and final review; fetching
default HEAD into an explicitly supplied checkout can bypass a configured ref.
Use an isolated checkout that cannot drift during the run.
Consumer rollout and an external pilot remain follow-up work. A pilot must
compare a pinned independent baseline run of the existing workflow without
enrichment against a matched enriched run, keeping starting code, task, model,
tools, runtime, and gates controlled and recording the actual BCQuality
checkout. Retain external logs, diffs, test/compile outcomes, and independent
final reviews, including failures and unresolved results. Credential-free
fixture preparation and scorer regressions do not demonstrate improved repair
quality, compilation, runtime success, or production integration.
## Knowledge-backed and agent findings
BCQuality is an **additive** knowledge layer. The agent surfaces two kinds of findings, both shaped to the same DO output contract:
- **Knowledge-backed findings** carry one or more entries in `references[]` pointing at BCQuality knowledge files. Their `id` is the primary file's repo-relative path. Leaf sub-skills set `domain` to their human-readable display label, and super-skills preserve it verbatim during rollup.
- **Agent findings** carry an empty `references: []`, use a slug `id` prefixed `agent:`, and have `confidence` capped at `medium`. A leaf can emit one strictly within its own domain and uses that leaf's display label. A super-skill can emit a cross-cutting agent finding with `from-sub-skill: "agent"` and `domain: "Agent"`. Their `message` is self-contained because there is no knowledge-file footer to fall back on.
Before a skill emits an agent finding, it validates the candidate against the BCQuality knowledge already loaded for the task: a matching file upgrades the candidate to a knowledge-backed finding (and merges or deduplicates against relevant existing output); a contradicting file suppresses the candidate. Only candidates with no BCQuality coverage become agent findings.
Orchestrators MUST tolerate an absent `domain` in reports from older producers. When it is present, treat it as display text rather than an identifier: preserve the full string and its case, whitespace, punctuation, and non-ASCII characters, escaping only for the target rendering format. Do not tokenize it on spaces or use a lowercased or slugified form as the sole metadata or deduplication key, because distinct labels can collapse to the same slug. Retain the exact string, use a lossless encoding, or use a collision-resistant digest instead. Orchestrators MAY render knowledge-backed and agent findings differently and MAY apply independent severity floors; `references: []` and the `agent:` id prefix distinguish agent findings, while `from-sub-skill: "agent"` identifies those emitted by the super-skill itself.
## Why this architecture
- **Entry is the only hardcoded thing.** Orchestrators ship with one convention — *"invoke `/skills/entry.md` first"* — and nothing else. New action skills and new knowledge files are picked up automatically because Entry discovers them at dispatch time.
- **Standalone installation adds an adapter, not another policy layer.** The
plugin's host-format `al-code-review` skill only translates the invocation
into Entry's task context. Entry and the dispatched action skills remain
authoritative.
- **Layers decide authority, not code.** The agent sees `/microsoft/` and `/community/` together; if two files conflict, the precedence rule defined in READ resolves it. A partner fork can disable `/community/` — that's a config choice, not a code change.
- **Knowledge and skills evolve independently within their owning layer.** A new knowledge file requires no skill changes because existing skills pick it up via frontmatter filters. Layer placement still follows skill ownership, so promoting a skill also promotes its canonical corpus.
## The mental model, in one sentence
The orchestrator knows **when** to run; Entry decides **which skill** to run; the action skills define **what** to do; the meta-skills teach the agent **how** to behave; the knowledge files are **what** the agent knows.

179
docs/contributing.md Normal file
View file

@ -0,0 +1,179 @@
# Contributing to BCQuality
[Documentation](README.md) | [Knowledge by domain](using-bcquality.md#knowledge-by-domain) | [Authoring reference](../skills/write.md)
Partners are welcome to contribute shared knowledge, examples, skills, and
documentation. To report an incorrect finding without preparing a change,
use the [support guide](troubleshooting.md#reporting-a-problem).
## Your first contribution
You can propose shared guidance without write access to the upstream
repository. Use this path for a correction or a new article:
1. Search the [existing knowledge](using-bcquality.md#knowledge-by-domain) and
[open issues](https://github.com/microsoft/BCQuality/issues). Correct or
extend an existing article when it already owns the concern; add a new
article only for a distinct concern that meets the admission test below.
2. [Fork BCQuality](https://github.com/microsoft/BCQuality/fork) into your GitHub
account or organization, clone your fork, and create a working branch from
the current upstream `main`. Make edits in that branch, not the plugin cache.
3. Choose the [owning layer and domain](#choose-the-right-destination), then
edit the article or use the [shared-article starter](#shared-article-starter).
A contribution intended for everyone does not belong in `custom/`.
4. Add supporting sources and relevant good/bad samples. For a false positive,
explain the valid pattern and the mistaken finding the rule should prevent.
5. Run the [documented checks](#before-opening-a-pr), then commit and push
your branch to your fork.
6. On GitHub, open a pull request with **base repository
`microsoft/BCQuality`, base branch `main`**, and your fork's working branch
as the head. Explain why the change is needed and respond to review by
pushing further commits to the same branch.
Merged content is not automatically loaded into an existing agent session.
Consumers must pick up the updated content through their installation or
checkout; see [updates and versions](customizing-bcquality.md#updates-and-versions).
## What belongs here
BCQuality is a remedial knowledge base. A knowledge file exists because a
capable LLM **would get something wrong, or miss something, without it**, not
simply because the topic is important. Apply this admission test:
> If this file did not exist, would a modern LLM reviewing or generating BC
> code make a mistake this file would have prevented?
Good candidates encode a BC-specific mechanic that models get wrong, a
version-dependent behavior, or a misleading interpretation of an analyzer
rule. For example:
- [SetLoadFields and filters can be called in either order](../microsoft/knowledge/performance/use-setloadfields-for-partial-records.md): their relative order does not change the projection. This prevents an incorrect performance finding.
- [Boolean page record triggers default to true](../microsoft/knowledge/error-handling/page-boolean-triggers-default-to-true.md): omitting an explicit `exit(true)` is not itself a defect.
- [Page fields can inherit captions](../microsoft/knowledge/style/caption-required-on-page-fields.md): an omitted page-level property is not sufficient evidence that a caption is missing.
Generic advice such as "use HTTPS," "do not hardcode secrets," or "keep
transactions short" does not earn a separate knowledge file merely by being
sound advice. Negative clarifications that prevent false positives are as
valuable as rules that catch defects.
**Skills hold discovery and execution mechanics; knowledge files hold BC
facts.** Correct or extend a knowledge article when a BC fact is missing or
wrong. Do not hide that fact in a skill's instructions. A genuine routing,
input, or output-contract problem belongs in the skill instead.
## Choose the right destination
| Change | Destination |
| --- | --- |
| Knowledge in a Microsoft-owned review domain | `microsoft/knowledge/<domain>/` |
| Knowledge accompanying a Community-owned skill | `community/knowledge/<domain>/` |
| Company-specific policy or an override | `custom/` in your own fork; never an upstream contribution |
| Partner instructions or how-to guidance | `docs/`, linked from the documentation index |
Layer ownership follows the skill and domain, **not your employer**. For
example, a partner's performance clarification belongs beside the Microsoft
performance skill's corpus. Do not use Community as a staging area for an
already Microsoft-owned domain. A split may exist briefly during promotion,
but the skill and its canonical corpus should move together.
Upstream automatically closes PRs adding custom content. Follow
[Customizing BCQuality](customizing-bcquality.md) for organization-only rules.
Do not introduce a new shared domain without the action skill that consumes
it and the matching evaluation samples.
## Author a knowledge article
Read [READ](../skills/read.md) for the schema and
[WRITE](../skills/write.md) for the authoring rules. Use an existing article
in the same domain as a starting point, then remove unrelated guidance.
Every article has six required frontmatter fields: `bc-version`, `domain`,
`keywords`, `technologies`, `countries`, and `application-area`.
`domain` must match its containing directory. Keep one concern per file,
ideally under 50 lines and no more than 100.
`Description` is required. Put recommendations in `Best Practice` and mistakes
to catch in `Anti Pattern`; those are the normative sections. Explain
legitimate exceptions so a reviewer does not turn a useful rule into a false
positive. Code fences are not allowed in knowledge articles.
### Shared-article starter
Use [caption-required-on-page-fields.md](../microsoft/knowledge/style/caption-required-on-page-fields.md)
as a complete shared-knowledge example. It demonstrates all six metadata
fields, a clear concern, normative guidance and exceptions, linked good/bad
samples, and authoritative sources.
For a new concern, follow that structure but choose your own descriptive
filename, domain, applicability, keywords, and guidance. Replace its sources
and sample links with ones supporting your concern; do not duplicate the
caption rule. If you are correcting caption guidance itself, edit the
existing article instead. Use a company-only rule only in your fork's Custom
layer, following the separate [customization example](customizing-bcquality.md#add-an-organization-specific-rule).
### Sources and examples
When adding or changing a platform claim, link the authoritative source that
supports it, preferably the specific Microsoft Learn API/property page or a
public source definition. State version constraints when they matter. Avoid
"upstream guidance says" without a link. If the source is unavailable or the
guidance is organization policy or empirical observation, say so explicitly
rather than presenting it as an official platform guarantee.
Place source links in a short `References` section or beside the relevant
claim. References do not replace the rule: keep all load-bearing guidance in
the normative sections. This adds traceability without adding frontmatter
fields or changing the schema.
Put demonstration code in sibling files:
```text
<slug>.md
<slug>.good.al
<slug>.bad.al
```
Reference each sample with a clickable link whose label retains the filename,
for example `` [`<slug>.good.al`](<slug>.good.al) `` with your actual slug.
One or both samples are optional for an individual article; every review
domain must have at least one complete good/bad pair for evaluation. Samples
are self-contained demonstrations, not copied Base Application source and
not a deployable or compiled application.
## Before opening a PR
From your BCQuality checkout, use the existing validators. The Python
validator needs Python and PyYAML; the fixture harness needs PowerShell 7.
If PyYAML is not installed in your development environment, install it with
`python -m pip install pyyaml`.
```powershell
python .github\scripts\validate_frontmatter.py --root .
pwsh .\tools\Test-ReviewFixtures.ps1 -Root .
```
The first command checks schema, sections, naming, sample references, and
skill registration. The second checks that every review leaf has a valid
positive/clean sample pair. Neither proves a model will find every defect.
See [evaluation](../evaluation/README.md) for optional model-based scoring.
In the PR description, explain the mistake being prevented, supporting
evidence, applicable BC versions, and why the chosen domain owns it. For a
false positive, include the valid pattern and the incorrect finding being
prevented. Check that links and samples open from the rendered article.
Schema and stable protocol changes require approval from both maintainers.
Avoid repeating schema or contract definitions in new guides: link the
canonical READ, DO, WRITE, or Entry section instead.
## Content releases
Maintainers cut content releases on demand, roughly monthly, using the
`Release version` workflow on `main`. It tags the selected commit as
`v{major}.{minor}`; it does not update the plugin manifest.
Use a minor bump for normal content updates and a major bump for breaking
changes. The minor is a monotonic counter: it increments across releases and
does **not** reset on a major bump. See
[updates and versions](customizing-bcquality.md#updates-and-versions) for the
separate plugin, content, and skill version identifiers.

173
docs/customizing-bcquality.md Normal file
View file

@ -0,0 +1,173 @@
# Customizing BCQuality
[Documentation](README.md) | [Using BCQuality](using-bcquality.md) | [Contributing](contributing.md)
**No customization is required to get started.** Use the upstream plugin
unless you need a different review selection or organization-specific rules.
Model choice, concurrency, retries, and billing belong to your host, not
BCQuality. A [standalone runner](standalone-runner.md) is an advanced option.
## Select layers or disable a review
The standalone adapter reads these environment variables from the process
that starts your host:
| Variable | Default | Meaning |
| --- | --- | --- |
| `BCQUALITY_ENABLED_LAYERS` | `microsoft,community,custom` | Comma-separated layer names to discover. |
| `BCQUALITY_DISABLED_SKILLS` | None | Comma-separated **BCQuality repo-relative skill paths** to exclude, not display names or knowledge-article paths. |
For example, in PowerShell, enable only Microsoft knowledge and omit the
dedicated style review:
```powershell
$env:BCQUALITY_ENABLED_LAYERS = "microsoft"
$env:BCQUALITY_DISABLED_SKILLS = "microsoft/skills/review/al-style-review.md"
copilot
```
Set the variables **before** starting a new session. They apply to that
terminal and its child processes; use your host's environment configuration
if it starts elsewhere. Review selection is not a guarantee that another
domain or the agent will never mention a related concern.
To return to defaults, remove those variables from the environment before
starting the host again (or use a fresh terminal if you only set them there).
Do not use an empty comma-separated value as a substitute for the default.
All layers are enabled by default. Where relevant articles have overlapping
applicability and **contradictory guidance**, precedence is:
**Custom > Community > Microsoft.**
Otherwise the layers are additive. A matching filename alone does not suppress
an article; the [READ contract](../skills/read.md#layer-precedence) governs
knowledge conflicts. Review reports record displaced knowledge in `suppressed`.
Layer selection is **not an access-control boundary**. A plugin installation
still contains excluded layers on disk. An integration requiring genuine
exclusion must remove denied files from its own content copy before the agent
reads it; the [adapter](../skills/al-code-review/SKILL.md#layer-selection-is-not-a-deny-mechanism)
explains this distinction.
## Add an organization-specific rule
Keep custom content in a fork or organization-controlled copy of BCQuality,
not in your AL app's `custom` folder and not in the installed plugin cache.
Editing the cache is not durable across updates.
1. Fork BCQuality into a repository your organization controls, or create an
organization-controlled copy if a public fork is unsuitable for your policy.
2. Clone that repository and run `git remote get-url origin`. Confirm it is
your repository, **not** `microsoft/BCQuality`.
3. Add the article under `custom/knowledge/<existing-domain>/`, using the
[knowledge format](../skills/read.md). Keep your company's content out of
upstream pull requests.
For example, suppose your company deliberately names one page "ACME Inventory
Workbench" while showing stockkeeping units, and already makes the row type
clear in its UI. You want a narrow exception to the shared page-naming rule.
Create `custom/knowledge/style/page-name-must-match-source-table.md` in your
copy with this content:
```markdown
---
bc-version: [all]
domain: style
keywords: [page-name, source-table, inventory, workbench]
technologies: [al]
countries: [w1]
application-area: [all]
---
# Allow the ACME Inventory Workbench task name
## Description
Our approved page "ACME Inventory Workbench" shows stockkeeping units. Its UI
identifies the row type explicitly; its task-oriented name is company policy.
## Best Practice
Do not report that page solely because its name differs from its source-table
entity. Keep the shared naming guidance for other pages.
## Anti Pattern
Renaming the approved page solely to repeat the source-table entity, or
applying this exception to an unrelated page.
```
This is an **illustrative company policy**, not a new Microsoft recommendation.
Choose your actual domain, applicability, and policy; do not broaden an
exception merely to silence a valid defect. The shared rule is
[page-name-must-match-source-table.md](../microsoft/knowledge/style/page-name-must-match-source-table.md).
Guidance in `Best Practice` and `Anti Pattern` drives conflict resolution, so
do not put the exception only in a non-normative notes section.
Follow the [contribution checks](contributing.md#before-opening-a-pr) locally,
then commit your change in your repository. A new knowledge domain also needs
an action skill that discovers it; adding an arbitrary folder does not create
a review.
## Use your fork
Adding custom content does not change the upstream plugin you already
installed. Point the host at your copy.
For a pushed fork, replace `YOUR-ORG` with its owner. These commands replace
the upstream installation, since both manifests use the name `bcquality`:
```powershell
copilot plugin uninstall bcquality
copilot plugin install YOUR-ORG/BCQuality
copilot plugin list
```
For local development, install your copy's absolute path instead:
```powershell
copilot plugin install "C:\Repos\CompanyBCQuality"
```
Direct local installs are cached by the CLI; reinstall that path after edits,
then start a new session. See the host's
[local-plugin instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating).
Do not assume the currently running session has reloaded the content.
Confirm the plugin list points at the intended source and that the Custom
layer is enabled. Review a small example relevant to your rule. Ask the host
which custom article it read and inspect `suppressed` for an actual conflict.
The negative-rule example should produce no naming finding for the approved
page; do not add an information-only finding just to prove the article was
loaded. The absence of a finding alone does not prove your fork was used.
An external runner should likewise read from your fork or local copy rather
than the upstream URL. It must still start at [Entry](../skills/entry.md).
## Updates and versions
| Identifier | What it identifies |
| --- | --- |
| Plugin `version` in `plugin.json` | The host-facing package version. It is separate from content-release tags. `copilot plugin list` shows the installed plugin; inspect the resolved source when reproducing a run. |
| Content tag such as `v1.6` | A release of the repository's knowledge and skills. Available tags are listed on [GitHub](https://github.com/microsoft/BCQuality/tags). |
| Skill `version` in frontmatter | That skill's contract version, carried in reports. It does not identify the complete knowledge snapshot. |
| Git commit SHA | The exact repository snapshot. Record this for reproducibility when using a checkout. |
For the upstream plugin, run `copilot plugin update bcquality`, then start a
new session. The unpinned installation command does not promise a particular
content-release tag. For a fork, updating the plugin reads your fork; it does
not merge upstream changes into it.
To maintain a fork, commit your custom work first, add an `upstream` remote
pointing to `https://github.com/microsoft/BCQuality.git` once, fetch upstream,
and merge the desired upstream branch or content tag. Resolve conflicts and
review the resulting policy before publishing or reinstalling your fork.
Do not overwrite the fork wholesale with an upstream download.
For repeatable CI or runner use, select a tag or commit in a dedicated clean
checkout and record `git rev-parse HEAD`. Upgrade deliberately, compare the
old and new content, and rerun representative reviews. To roll back, select
the previously recorded snapshot in that checkout and reinstall it if your
host caches local plugins. Retain organization-specific rules in the chosen
snapshot rather than reverting to an upstream-only tag.

101
docs/standalone-runner.md Normal file
View file

@ -0,0 +1,101 @@
# Build a lightweight standalone review runner
[Documentation](README.md) | [Architecture](agent-consumption.md)
BCQuality provides review knowledge, routing, execution instructions, and
structured output contracts. It intentionally does not choose models, schedule
agents, retry failures, or collect usage telemetry. A standalone runner can add
those host-specific capabilities without copying Business Central rules out of
BCQuality.
Use the built-in standalone plugin when the host's default execution is
sufficient. Build a runner when you need explicit control over cost, latency,
concurrency, or integration with another review surface.
Start with the [minimal integration example](agent-consumption.md#try-a-minimal-integration)
to connect your agent to the content before adding runner-specific behavior.
## Keep BCQuality current
For plugin installation, use the [quick start](../README.md#quick-start).
For version identifiers, forks, and reproducible snapshots, see
[updates and versions](customizing-bcquality.md#updates-and-versions).
A runner that reads BCQuality from a checkout should pin a commit or release
and upgrade it deliberately. Do not copy knowledge files or action-skill prose
into the runner; doing so creates a second, drifting quality policy.
## Review a complete app folder
For a committed app, generated fixture, or source tree that has no meaningful
diff, supply the app's root directory as `folder-path`. The review scope is
every relevant file below that directory, including `app.json` and AL source.
The folder does not need to be a Git repository.
The [app-review example](../README.md#example-review-a-complete-app-folder)
uses this input through the standalone adapter. Because a folder is a
current-state snapshot, the review must not invent a previous app version
when evaluating comparison-only rules. Entry can return more than one
top-level skill; preserve all reports, including separately dispatched
Community reviews, rather than assuming the Microsoft coordinator is the
only result.
## Minimal runner flow
1. Give the agent the review input and a task context containing the user's
actual goal, available input types, and any known BC applicability
dimensions.
2. Invoke `skills/entry.md`. Entry prepares the knowledge index and returns the
action skills to run. Do not reproduce its routing logic.
3. Execute every dispatched action skill with the exact input subset in its
dispatch record. Read `skills/read.md` and `skills/do.md` on demand.
4. When an action skill declares `sub-skills`, execute every relevant leaf as a
discrete invocation. Leaves are independent and may be scheduled serially
or concurrently.
5. Collect each complete findings-report into `sub-results` in the declared
`sub-skills` order, not completion order. Run the super-skill self-review
only after all leaves have finished.
6. Apply the DO composition, failure, deduplication, reference-integrity, and
outcome rules. Return strict JSON before rendering it for people or another
system.
The runner must never inspect the diff to skip a review domain. A leaf decides
its own task-level applicability and reports `not-applicable` or
`no-knowledge`.
## Runner-owned choices
Keep these settings and behaviors outside BCQuality:
- coordinator and leaf models;
- serial or concurrent scheduling and maximum concurrency;
- retries, timeouts, and rate-limit handling;
- token, cost, duration, and actual-concurrency telemetry;
- conversion of the findings report into Markdown, annotations, or PR
comments.
Model selection and requested concurrency are deployment choices, not review
rules. Evaluate them against representative applications before making them a
default. Report actual usage and concurrency only when the host exposes native
evidence; do not infer them from the requested profile.
## Failure and output checklist
A compatible runner:
- invokes every worklisted leaf exactly once unless a documented retry replaces
a failed attempt;
- keeps leaf contexts isolated and passes only the inputs they declare;
- preserves every leaf report, including failed reports, in `sub-results`;
- excludes unreliable findings from failed leaves and returns `partial` when
only part of the review is reliable;
- orders `sub-results` by the declared worklist and orders rendered findings
deterministically;
- calculates top-level severity counts from deduplicated top-level findings,
not by summing leaf counts;
- preserves knowledge paths verbatim and verifies references before publishing;
- records the BCQuality commit or release used for the run.
A CI integration, custom agent, or small host-native plugin can implement this
runner contract. These remain optional consumers: BCQuality's knowledge and
skills stay independent of their orchestration choices.

59
docs/troubleshooting.md Normal file
View file

@ -0,0 +1,59 @@
# Troubleshooting and support
[Documentation](README.md) | [Quick start](../README.md#quick-start) | [Using BCQuality](using-bcquality.md)
## Setup and skill discovery
Run terminal commands outside the interactive Copilot prompt unless they
start with `/`.
| Symptom | What to do |
| --- | --- |
| `copilot` is not recognized | [Install Copilot CLI](https://docs.github.com/en/copilot/get-started/cli-quickstart), then open a new terminal. Installing Copilot Chat in an editor is not the same step. |
| The CLI has no `plugin` command | Update Copilot CLI using its installation method. Confirm `copilot plugin --help` works. |
| Sign-in, entitlement, or organization-policy error | Start `copilot`, use `/login`, and confirm your account is allowed to use Copilot CLI. Ask your administrator about organization restrictions; BCQuality cannot override them. |
| Plugin installation cannot reach the repository | Confirm access to `https://github.com/microsoft/BCQuality` and follow your organization's proxy/network guidance. Do not disable certificate checks. |
| The plugin installed, but the skill is missing | Run `copilot plugin list` in the terminal. Enable it with `copilot plugin enable bcquality` if disabled, then start a new session. In the session, use `/skills list` and look for `al-code-review`. |
| The agent performs a generic review | Name the **installed `al-code-review` skill** explicitly, as in the quick start. Ask which skill and BCQuality source it used. Another plugin or host may expose a similarly named operation. |
| Installation works in the terminal, but not in the editor | Plugin discovery is host-specific. Follow the editor's installation instructions; a CLI installation is not proof that another host loaded the plugin. |
| `pwsh` is missing, or index generation fails | The index is an accelerator, not required knowledge. The review can fall back to discovery from folders. For faster discovery, install [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell), or resolve the reported filesystem error. |
| An update or local edit is not visible | Run `copilot plugin update bcquality` for a repository-installed plugin, then start a fresh session. For a directly installed local folder, reinstall that folder to refresh the cached copy; see [customizing](customizing-bcquality.md#use-your-fork). |
## Review results
| Symptom | What to do |
| --- | --- |
| `partial`, a timeout, or an unfinished review | Read `outcome-reason` and domain reports. Retry the incomplete scope in a fresh session, use smaller app folders or a focused review, or select a host/model with sufficient capacity. Keep the limited scope visible; do not relabel it a complete app review. |
| `failed` | Resolve the stated problem, such as inaccessible input, a failed invocation, or an unverifiable reference, before using that report. A failed domain's findings are not reliable. |
| `no-match` or `not-applicable` | Confirm you supplied AL source, the intended folder/file/diff, and an appropriate goal. Check [disabled skills and layers](customizing-bcquality.md#select-layers-or-disable-a-review). |
| `no-knowledge` | Check the target BC version, selected domain, enabled layers, and whether the relevant knowledge files are present. No applicable rules is different from no defects. |
| `completed` with no findings | This can be a valid clean result for the selected scope. Confirm the intended files and domain reports are included. If you have a concrete missed defect, report it with a minimal example. |
| JSON rather than a readable summary | JSON is the shared output format. Ask the host to summarize the existing reports, preserving outcomes, locations, severity, confidence, and references. |
| A surprising finding | Open its guidance and samples, inspect surrounding code, and confirm version/localization assumptions. Ask the agent to explain the evidence; do not apply a suggestion solely because it has high confidence. |
| The Agents domain is absent | Agents is a separate Community review, not a child of the Microsoft broad review. Explicitly request an Agent SDK review and confirm the Community layer is enabled. |
| A missing base branch or unavailable source definition | Supply the real baseline or dependency definition. Without it, do not accept claims that rely on invented history or assumed dependency behavior. |
| Slow or expensive review | A broad review makes separate passes over multiple domains. Verify index generation succeeded, use a focused task when appropriate, and inspect usage in your host. BCQuality does not choose models, promise runtimes, or meter charges. |
## Reporting a problem
For incorrect BC guidance, missed findings, documentation gaps, or skill
behavior, [search existing issues](https://github.com/microsoft/BCQuality/issues)
and [open a BCQuality issue](https://github.com/microsoft/BCQuality/issues/new/choose)
if needed. You do not have to author a knowledge file before asking for help.
Host installation, authentication, billing, or policy problems belong with the
host's support channel or your organization administrator.
Include:
- The host and version, selected model if known, and BCQuality source/version
or commit. See [version identifiers](customizing-bcquality.md#updates-and-versions).
- The prompt, scope (folder/file/diff and comparison base), target BC version,
and relevant layer/skill settings.
- Expected versus actual behavior, the outcome/reason, and the exact rule
reference for a disputed finding.
- A **minimal, sanitized** AL example or report excerpt that reproduces the
problem. Remove secrets, customer data, and proprietary content you cannot share.
For security vulnerabilities, follow [SECURITY.md](../SECURITY.md) instead of
opening a public issue. To contribute a correction yourself, follow the
[contribution guide](contributing.md).

235
docs/using-bcquality.md Normal file
View file

@ -0,0 +1,235 @@
# Using BCQuality
[Documentation](README.md) | [Quick start](../README.md#quick-start) | [Troubleshooting](troubleshooting.md)
BCQuality is knowledge you can read and reuse, plus skills that tell an agent
how to apply it. You do not need an AI tool to read the articles. When using
an agent, your host supplies authentication, model access, tools, permissions,
and rendering; BCQuality does not install a BC extension or an agent.
## Choose how to use BCQuality
| Path | What to do |
| --- | --- |
| Read the knowledge yourself | Browse [knowledge by domain](#knowledge-by-domain), or search the repository for an AL concept. Read the article and its samples. No installation required. |
| Use a supplied skill | Follow the [plugin quick start](../README.md#quick-start). The currently exposed skill, `al-code-review`, performs reviews and returns findings. |
| Use your own agent or workflow | Supply selected articles as context, as described below, or use the [integration bootstrap](agent-consumption.md#try-a-minimal-integration) to execute BCQuality action skills without the plugin. |
### Read and reuse an article
Start with a concern, such as `SetLoadFields`, and search within
`microsoft/BCQuality` on GitHub or open its domain folder. For example,
[partial-record guidance](../microsoft/knowledge/performance/use-setloadfields-for-partial-records.md)
explains the concern and links good/bad samples.
Before applying an article, read its frontmatter, the small metadata block at
the top:
| Field | How to read it |
| --- | --- |
| `bc-version` | `[24..]` means BC 24 and later; `[26..28]` means BC 26 through 28; `[all]` means every version. Use your target BC major version, not your extension's version. |
| `technologies` | `[al]` means the guidance applies to AL; multiple values identify the technologies the article covers. |
| `countries` | `[w1]` means worldwide; a code such as `[dk]` limits the guidance to that localization. |
| `application-area` | `[all]` means any application area; a named area narrows applicability. |
| `domain` and `keywords` | Help you find the topic; they are not instructions or additional requirements. |
Read `Description` for context, then `Best Practice` and `Anti Pattern` for the
rule and its exceptions. Follow any sample and source links. Do not turn a
sample into a production implementation without considering your own context.
The [READ reference](../skills/read.md) defines the precise matching rules.
To use an article with your own agent, give it access to the full article and
relevant samples, not just a title or index row. For example, replace the
bracketed values in this prompt:
> Read [article URL or local path] and its linked samples. Apply the relevant
> guidance while implementing [task] for BC [major version]. Explain which
> guidance you used, cite the article, and identify any missing context.
A URL only works if the host can retrieve it; otherwise provide the files
directly. This is ordinary reuse of knowledge for explanation or code writing,
**not a packaged code-generation skill or a complete BCQuality review**.
For the structured review process, invoke a supplied skill or follow the
integration protocol. The remaining sections describe the review workflow.
## Hosts and prerequisites
The [quick start](../README.md#quick-start) documents GitHub Copilot CLI. Use a
current CLI release with plugin support and sign in to an account allowed to
use it. In an interactive CLI session, `/skills list` should include
`al-code-review`; in the terminal, `copilot plugin list` should include
`bcquality`.
Do not assume a CLI installation also installs the plugin into VS Code,
another editor, or another agent host. Follow that host's plugin instructions
and confirm it discovers `skills/al-code-review/SKILL.md`. Hosts without
compatible plugin discovery need an [integration](agent-consumption.md).
Source review needs access to your files, not a running BC environment.
Include `app.json` and any relevant surrounding source. Dependency symbols or
a historical baseline may be needed to substantiate particular findings; a
review must not invent missing definitions or an earlier version of your app.
PowerShell 7 (`pwsh`) accelerates discovery by generating the knowledge index.
Without it, folder-based discovery is available and may take longer.
## Common review requests
Start a new host session after installing or updating the plugin. Use the
skill name explicitly and say what is in scope. Replace example paths and
branch names with ones in your project.
| Task | Example prompt |
| --- | --- |
| Complete app | Use the installed al-code-review skill to review the complete Business Central app in this folder without changing my source files. Return the complete BCQuality findings report. |
| One file | Use the installed al-code-review skill to review `src\CustomerMgt.Codeunit.al` without changing it. Return the complete BCQuality findings report. |
| Uncommitted changes | Use the installed al-code-review skill to review my staged and unstaged tracked changes against HEAD, without changing files. Identify any untracked AL files not included in that diff. |
| Branch changes | Use the installed al-code-review skill to review changes on this branch since its merge base with `origin/main`. Exclude uncommitted changes and do not edit files. |
| Focused review | Use the installed al-code-review skill to review performance in the app in this folder, without changing files. Return the complete performance findings report. |
| Agent SDK code | Use the installed al-code-review skill to review Agent SDK implementation and usage in this app folder, without changing files. Return the complete Agents findings report. |
For Git comparisons, the named base ref must exist locally. If it is missing,
fetch the intended branch first. A PR review also requires the host to have
the PR's changes and repository access; installing the plugin does not
automatically connect it to your PR workflow.
A complete-folder review considers relevant files recursively, not just
modified files. Start in a single app's root for the clearest scope. For a
repository containing several apps, name each app folder and review them
separately when their target versions or dependencies differ.
If known, add the target BC major version and localization to the request.
Do not use your extension's own `version` as the BC version. Missing
applicability context can reduce a finding's confidence or leave a rule out.
## Reading your results
The skill returns structured reports. A host may render them as text, a table,
or annotations, or show the JSON directly. You can ask the host to explain the
returned report without rerunning the review or changing files.
For example, a performance report could contain this finding:
| Field | Illustrative value |
| --- | --- |
| Outcome | `completed` |
| Location | `src\CustomerExport.Codeunit.al`, line 42 |
| Severity / confidence | `major` / `high` |
| Finding | A country filter is evaluated inside the customer loop, so rows that will be discarded are still read. Apply the filter before iterating. |
| Guidance | [Apply filters before iterating](../microsoft/knowledge/performance/apply-filters-before-iterating.md), with linked good/bad samples. |
This illustrates a report, not a guaranteed finding or host screen. Read the
referenced article and the surrounding source before accepting a fix.
### Outcomes
| Outcome | Meaning and action |
| --- | --- |
| `completed` | The selected review finished. An empty `findings` list means it found nothing to flag in that scope, not that the app is certified defect-free. |
| `not-applicable` | The review did not apply to the supplied input. It is not a clean-review result. |
| `no-knowledge` | No applicable knowledge was available. Check scope, target context, and enabled layers. |
| `partial` | Some work did not finish. Read `outcome-reason` and the individual reports; do not treat the result as a full pass. |
| `failed` | No reliable result from that review. Resolve the reported error before relying on it. |
| `no-match` | Routing found no suitable skill. Check the request, input type, and disabled skills. |
A broad review includes individual domain reports in `sub-results`. Separately
dispatched skills return separate reports, so do not mistake the first report
for the whole run. Coverage counts describe selected knowledge items evaluated,
not a percentage of all possible defects or every rule in the repository.
For example, this completed **domain** report evaluated one selected knowledge
item and found nothing to flag:
```json
{
"skill": { "id": "al-performance-review", "version": 1 },
"outcome": "completed",
"summary": {
"counts": { "blocker": 0, "major": 0, "minor": 0, "info": 0 },
"coverage": { "worklist-size": 1, "items-evaluated": 1 }
},
"findings": [],
"suppressed": []
}
```
This is not evidence that other domains ran; their reports must also be present
when requested.
### Severity, confidence, and references
| Severity | Meaning |
| --- | --- |
| `blocker` | A platform-level guarantee is violated; the work cannot proceed as-is. |
| `major` | A significant defect that should be addressed before merge. |
| `minor` | A quality concern; advisory rather than a gate. |
| `info` | Concrete context or an observation, not an instruction to change code. |
Confidence (`high`, `medium`, or `low`) describes the strength of the evidence,
not the impact. Missing version or localization context must be disclosed in
the finding when conditionally applicable knowledge is used.
Knowledge-backed findings link to the articles that informed them. Findings
from the agent's own reasoning have no knowledge reference (`references: []`);
these are advisory, with severity capped at `minor` and confidence at `medium`.
The display domain `Agents` means Agent SDK guidance; it is different from
`Agent`, the label for the broad coordinator's own cross-cutting observations.
Any `suppressed` entries explain knowledge overridden by configuration or
layer precedence.
A report can include a code suggestion. **A suggestion is not an applied
change.** Review the explanation first, then request any edits explicitly,
for example: "Apply only the filter fix at line 42 from this report." Continue
using your normal compilation, analyzer, test, and human-review workflow.
## Coverage and limits
The Microsoft broad review composes the 16 Microsoft domains listed below.
The Community Agents review is a separate skill selected by the request, not
a nested part of that coordinator. All current review leaves accept app
folders, files, and diffs; request an Agent SDK review explicitly when that
coverage matters and look for its separate report.
Available knowledge is **not** a promise that every rule will run. Selection
depends on the task, target context, enabled layers, and source evidence.
A whole-folder review is a current-state snapshot: detecting a published API
removal or another comparison-only regression requires an actual baseline.
The corpus is technical AL guidance, not exhaustive functional validation or
AppSource certification.
### Knowledge by domain
Each article describes one concern. Where samples exist, use its linked
`.good.al` and `.bad.al` files. Samples are demonstrations, not a deployable app.
| Domain | Browse knowledge |
| --- | --- |
| Agent SDK | [Agents (Community)](../community/knowledge/agents/) |
| AppSource | [AppSource](../microsoft/knowledge/appsource/) |
| Compatibility | [Breaking changes](../microsoft/knowledge/breaking-changes/) |
| Data modeling | [Data modeling](../microsoft/knowledge/data-modeling/) |
| Error handling | [Error handling](../microsoft/knowledge/error-handling/) |
| Events | [Events](../microsoft/knowledge/events/) |
| Interfaces | [Interfaces](../microsoft/knowledge/interfaces/) |
| Performance | [Performance](../microsoft/knowledge/performance/) |
| Privacy | [Privacy](../microsoft/knowledge/privacy/) |
| Query objects | [Query](../microsoft/knowledge/query/) |
| Security | [Security](../microsoft/knowledge/security/) |
| Style | [Style](../microsoft/knowledge/style/) |
| Telemetry | [Telemetry](../microsoft/knowledge/telemetry/) |
| Testing | [Testing](../microsoft/knowledge/testing/) |
| User interface | [UI](../microsoft/knowledge/ui/) |
| Upgrades | [Upgrade](../microsoft/knowledge/upgrade/) |
| APIs and web services | [Web services](../microsoft/knowledge/web-services/) |
## Permissions and data
The review instructions produce findings, not source edits or deployment.
The host still controls tool permissions: keep approval prompts enabled and
do not grant blanket write or deployment access just to run a review.
BCQuality may write its generated `knowledge-index.json` into its own installed
directory; that is separate from your app's source.
BCQuality is content, not an AI service. Your chosen host and model determine
where source code is processed, what usage is billed, and which data policies
apply. Review those policies before supplying proprietary or customer code.
Installing the plugin does not make an online host run locally or offline.