Support standalone runners and complete app-folder reviews (#172)

* Document standalone review runner contract

Keep model selection and scheduling outside BCQuality while allowing orchestrators to run isolated review leaves concurrently with deterministic rollup semantics.

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

* Support complete app folder reviews

Define folder-path as a current-state review scope and accept it across the standalone adapter, broad coordinator, and every AL review leaf.

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

* Add walk-up app review quick start

Put the complete app-folder installation and prompt flow directly in the README so partners can discover the standalone experience without reading integration details first.

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

* Organize conceptual guides under docs

Move architecture and standalone runner documentation out of the repository root, add a documentation index, and update all inbound links.

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

---------

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

README.md

@@ -60,11 +60,12 @@ Skills define how agents consume knowledge. They come in three flavors:
 
 ### Agent bootstrapping
 
-An orchestrator (such as AL-Go) points the agent at BCQuality's URL and provides a task context. The agent's first call is `/skills/entry.md`, which returns a dispatch record naming the action skill(s) to invoke. The agent then invokes each dispatched skill in turn, reading READ and DO on demand. No prior knowledge of BCQuality's structure is baked into the orchestrator — only the convention *"invoke `/skills/entry.md` first."*
+An orchestrator (such as AL-Go) points the agent at BCQuality's URL and provides a task context. The agent's first call is `/skills/entry.md`, which returns a dispatch record naming the action skill(s) to invoke. The agent then invokes the dispatched skills, reading READ and DO on demand. No prior knowledge of BCQuality's structure is baked into the orchestrator — only the convention *"invoke `/skills/entry.md` first."*
 
 ### Standalone plugin installation
 
-BCQuality can also be installed directly as a plugin. The plugin registers one
+BCQuality can also be installed directly as a plugin to review a complete AL
+app folder, a change set, or an individual file. The plugin registers one
 host-native skill,
 [`al-code-review`](skills/al-code-review/SKILL.md), which adapts the caller's
 request to the same Entry protocol used by orchestrators.
@@ -75,6 +76,24 @@ For GitHub Copilot CLI:
 copilot plugin install microsoft/BCQuality
 ```
 
+#### Review a complete app folder
+
+1. Open the Business Central app folder in GitHub Copilot and start a fresh
+   session after installing the plugin.
+2. Ask:
+
+   > Use the installed `al-code-review` skill to review the complete Business
+   > Central app in this folder. Execute every dispatched review domain and
+   > return the complete BCQuality findings report.
+
+That is the complete walk-up flow. The folder does not need to be a Git
+repository; BCQuality reviews `app.json` and the AL source below it. To pick up
+a newer BCQuality release later, run:
+
+```shell
+copilot plugin update bcquality
+```
+
 Plugin version `0.2.0` renamed the former `bcquality-al-review` skill to
 `al-code-review`; explicit invocations and allowlists using the old skill name
 must be updated. The name remains distinct from BC-ALAgents' public
@@ -108,6 +127,12 @@ formats. Their paths make the boundary explicit. The adapter lives under
 `skills/al-code-review/SKILL.md`; the internal Microsoft-layer coordinator
 lives at `microsoft/skills/review/al-code-review.md`.
 
+Partners that want model selection, parallel leaf execution, retries, or usage
+telemetry can add a thin runner outside BCQuality. See
+[Build a lightweight standalone review runner](docs/standalone-runner.md) for the
+integration contract and a minimal implementation checklist. Architecture and
+partner guides are collected in the [documentation index](docs/README.md).
+
 ## Knowledge file format
 
 Every knowledge file is a markdown file with mandatory YAML frontmatter. Files target under 100 lines (ideal under 50). If two ideas would share a file, split them.
@@ -153,16 +178,17 @@ Action skills follow a four-step pattern:
 
 Every action skill produces output in a common format that orchestrators can consume without skill-specific parsing. The format is JSON and includes an `outcome` (so a clean run, a not-applicable skill, and a partial failure are all distinguishable), `findings` (what the skill observed), structured `references` back to the knowledge files that informed each finding, per-finding `confidence`, and a `suppressed` list recording any knowledge files overridden by layer precedence. This contract is defined in the Action Skill meta-skill so that orchestrators and action skills remain independently evolvable.
 
-BCQuality is an **additive** knowledge layer: it augments the agent's review judgement, it does not replace it. Super-skills (such as `al-code-review`) run a self-review pass alongside their sub-skills and surface concerns the agent identified on its own, marked with `from-sub-skill: "agent"` and an empty `references: []` so consumers can render them distinctly from knowledge-backed findings. See [agent-consumption.md](agent-consumption.md) and [`skills/do.md`](skills/do.md) for the full contract.
+BCQuality is an **additive** knowledge layer: it augments the agent's review judgement, it does not replace it. Super-skills (such as `al-code-review`) run a self-review pass alongside their sub-skills and surface concerns the agent identified on its own, marked with `from-sub-skill: "agent"` and an empty `references: []` so consumers can render them distinctly from knowledge-backed findings. See [How agents consume BCQuality](docs/agent-consumption.md) and [`skills/do.md`](skills/do.md) for the full contract.
 
 The meta-skills in `/skills/` define this pattern. Every concrete action skill follows it.
 
-For the end-to-end flow — from orchestrator trigger through to how output reaches developers — see [agent-consumption.md](agent-consumption.md).
+For the end-to-end flow — from orchestrator trigger through to how output reaches developers — see [How agents consume BCQuality](docs/agent-consumption.md).
 
 ## Repository structure
 
 ```
 ├── /skills/              # Global: entry-point skill + meta-skill contracts (READ, DO, WRITE)
+├── /docs/                # Architecture and partner integration guides
 ├── /evaluation/          # Neutral good/bad review fixtures and scoring contract
 ├── /.github/             # Actions and workflows
 ├── /microsoft/           # Microsoft-endorsed layer

docs/README.md

@@ -0,0 +1,8 @@
+# Documentation
+
+- [How agents consume BCQuality](agent-consumption.md) explains the operational
+  flow from Entry dispatch through structured findings and integration.
+- [Build a lightweight standalone review runner](standalone-runner.md) explains
+  the walk-up app-folder flow and how an external runner can add model
+  selection, concurrency, retries, and telemetry without moving orchestration
+  into BCQuality.

docs/agent-consumption.md

@@ -2,7 +2,8 @@
 
 BCQuality is content — knowledge files and skills. It is consumed by agents that live elsewhere (AL-Go, a VS Code extension, a GitHub Agent invocation, etc.). This document explains the end-to-end flow, so that skill authors, orchestrator maintainers, and contributors share one mental model.
 
-For the high-level framing and repo structure, start with the [README](README.md). This document is the operational view.
+For the high-level framing and repo structure, start with the
+[README](../README.md). This document is the operational view.
 
 ## The actors
 

docs/standalone-runner.md

@@ -0,0 +1,103 @@
+# Build a lightweight standalone review runner
+
+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.
+
+## Keep BCQuality current
+
+Install or update the plugin with GitHub Copilot CLI:
+
+```shell
+copilot plugin install microsoft/BCQuality
+copilot plugin update bcquality
+```
+
+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.
+
+With the standalone plugin installed, start a fresh Copilot session in the app
+folder and ask:
+
+> Use the installed `al-code-review` skill to review the complete Business
+> Central app in this folder. Execute every dispatched review domain and return
+> the complete BCQuality findings report.
+
+The adapter maps this request to `folder-path`; Entry routes it to the broad
+review super-skill. Because a folder is a current-state snapshot, the review
+must not invent a previous app version when evaluating comparison-only rules.
+
+## 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.
+
+BC-ALAgents, AL-Go, a Copilot custom agent, or a small host-native plugin can
+all implement this runner contract. They remain optional consumers:
+BCQuality's knowledge and skills stay independent of their orchestration
+choices.

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

@@ -4,7 +4,7 @@ id: al-appsource-review
 version: 1
 title: AL AppSource review
 description: Performs an AL AppSource review against source and app metadata guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source and app metadata changes against the `appsource` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). AppSource findings are narrow by design — they apply when the diff touches AppSourceCop configuration, AL object or extension-member names, or AppSource-facing `app.json` metadata. The skill returns `not-applicable` when none of those apply.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. AppSource findings are narrow by design — they apply when the review scope contains AppSourceCop configuration, AL object or extension-member names, or AppSource-facing `app.json` metadata. The skill returns `not-applicable` when none of those apply.
 
 ## Source
 

microsoft/skills/review/al-breaking-changes-review.md

@@ -4,7 +4,7 @@ id: al-breaking-changes-review
 version: 1
 title: AL breaking changes review
 description: Reviews AL source changes against breaking-changes guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `breaking-changes` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-code-review
 version: 1
 title: AL code review
 description: Reviews AL source changes by composing the AL review leaf skills, one per knowledge domain.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -35,7 +35,7 @@ Reviews AL source changes by composing the leaf AL review skills. This is the ca
 
 `al-code-review` does not evaluate knowledge files directly. It invokes each of its sub-skills against the same task input, collects their findings-reports, and then performs its own **self-review pass** over the diff using the agent's built-in BC and AL knowledge. BCQuality knowledge is an additive layer: anything the sub-skills found is cited from BCQuality, and anything the agent finds on its own is validated against BCQuality (cited if matched, suppressed if contradicted, surfaced as an **agent finding** otherwise). The result is a single rolled-up findings-report that mixes knowledge-backed and agent findings, each clearly tagged via `from-sub-skill`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract, extended with `sub-results` and — when applicable — `skipped-sub-skills`.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract, extended with `sub-results` and — when applicable — `skipped-sub-skills`.
 
 ## Source
 
@@ -63,18 +63,18 @@ The worklist is the list of sub-skills judged relevant by the previous step. Eve
 
 ### Execution discipline (mandatory)
 
-The Action step is a sequence of **discrete iterations**, not one combined generation. The contract requires the super-skill to invoke each sub-skill in turn and then perform a self-review pass. Concretely this means:
+The Action step consists of **discrete leaf invocations**, not one combined generation. Invocation scheduling belongs to the orchestrator: independent leaves may run serially or concurrently, but their evaluation contexts and findings-reports remain isolated. Concretely this means:
 
 - **Isolate leaf invocations when the host supports it.** For fast/small models, each sub-skill SHOULD run in a fresh model call or child context containing only the task input, READ/DO contracts, the leaf instructions, a domain-filtered slice of the current knowledge index, and articles that leaf worklists. Preserve each index row's exact `path`; the leaf must copy references from that slice. The coordinator then collects the resulting JSON. This is the preferred fast-model profile: it bounds context, prevents later leaves from being skipped as attention is exhausted, and removes any reason to synthesize article paths.
-- Treat each sub-skill in the worklist as its own pass: read the sub-skill's instructions, apply its Source → Relevance → Worklist → Action steps to the orchestrator-supplied inputs, and produce that sub-skill's complete findings-report before moving on.
+- Treat each sub-skill in the worklist as its own pass: read the sub-skill's instructions, apply its Source → Relevance → Worklist → Action steps to the orchestrator-supplied inputs, and produce that sub-skill's complete findings-report independently.
 - Do not collapse multiple sub-skills into one shared reasoning step. Each sub-skill has a distinct knowledge subset and a distinct evaluation procedure; sharing one rolled-up scan dilutes per-skill attention and causes leaves to silently underreport (this has been observed in production: leaf skills returned empty `findings[]` while their standalone runs against the same diff produced multiple matches).
 - The agent self-review pass is its own final iteration. Begin it only after every sub-skill in the worklist has completed and its sub-result is recorded.
-- Sub-skills are independent: re-walking the diff once per sub-skill is correct and expected. The output schema accommodates this — `sub-results` carries one entry per sub-skill, each a complete findings-report.
+- Sub-skills are independent: re-walking the diff once per sub-skill is correct and expected. The output schema accommodates this — `sub-results` carries one entry per sub-skill, each a complete findings-report, in the frontmatter `sub-skills` order regardless of completion order.
 - When isolated calls are unavailable and the current model cannot finish every leaf within its budget, return `partial` with completed `sub-results` and name the first unevaluated sub-skill in `outcome-reason`. Never silently mark the remaining leaves clean.
 
 ### Roll up sub-skill findings
 
-For each sub-skill in the worklist, executed one at a time per the discipline above:
+For each sub-skill in the worklist:
 
 1. Invoke the sub-skill with the orchestrator's inputs, passing only the subset each sub-skill declares in its `inputs`.
 2. Capture the sub-skill's complete findings-report verbatim and append it to `sub-results`.
@@ -116,7 +116,7 @@ Sub-skills MAY also emit `suggested-code` when their knowledge file unambiguousl
 
 ### Summary and rollup
 
-Aggregate `summary.counts` and `summary.coverage` as the sums across invoked sub-skills whose `outcome` is not `failed`. Agent findings emitted by the super-skill itself contribute to `summary.counts` but not to `summary.coverage` (coverage is a sub-skill worklist metric and is undefined for self-review).
+Calculate `summary.counts` from the final top-level `findings[]`, after failed sub-results have been excluded and duplicates have been merged. Aggregate `summary.coverage` as the sums across invoked sub-skills whose `outcome` is not `failed`. Agent findings emitted by the super-skill itself contribute to `summary.counts` but not to `summary.coverage` (coverage is a sub-skill worklist metric and is undefined for self-review).
 
 `suppressed[]` at the super-skill level remains empty. Knowledge-file-level suppression is reported by each sub-skill within its own entry in `sub-results`.
 

microsoft/skills/review/al-data-modeling-review.md

@@ -4,7 +4,7 @@ id: al-data-modeling-review
 version: 1
 title: AL data-modeling review
 description: Performs an AL data-modeling review against guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `data-modeling` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). Data-modeling findings are narrow by design — they apply when the diff touches setup or master tables, their card pages, primary keys, number-series assignment, block enforcement, or audit fields. The skill returns `not-applicable` when none of those apply.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Data-modeling findings are narrow by design — they apply when the review scope contains setup or master tables, their card pages, primary keys, number-series assignment, block enforcement, or audit fields. The skill returns `not-applicable` when none of those apply.
 
 ## Source
 

microsoft/skills/review/al-error-handling-review.md

@@ -4,7 +4,7 @@ id: al-error-handling-review
 version: 1
 title: AL error handling review
 description: Reviews AL source changes against error-handling guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `error-handling` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-events-review
 version: 1
 title: AL events review
 description: Reviews AL source changes against events-and-subscribers guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `events` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-interfaces-review
 version: 1
 title: AL interfaces review
 description: Reviews AL source changes against interface and enum-with-implementation guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `interfaces` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-performance-review
 version: 1
 title: AL performance review
 description: Reviews AL source changes against performance guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `performance` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-privacy-review
 version: 1
 title: AL privacy review
 description: Reviews AL source changes against privacy and data-classification guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `privacy` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-query-review
 version: 1
 title: AL Query review
 description: Reviews AL Query objects and Query instance usage against BCQuality guidance.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]

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

@@ -4,7 +4,7 @@ id: al-security-review
 version: 1
 title: AL security review
 description: Reviews AL source changes against security guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `security` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-style-review
 version: 1
 title: AL style review
 description: Reviews AL source changes against naming, labelling, and code-convention guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -18,7 +18,7 @@ Reviews AL source changes against the `style` knowledge domain in BCQuality and
 
 Style findings cover AL conventions that CodeCop and similar analyzers partially enforce — label suffixes, API page naming, temporary-variable prefixes, label properties, named invocations, `FieldCaption`/`TableCaption` in user messages, `OptionCaption` pairing, Error-parameter passing, `this` keyword, required parentheses, file-naming. Use together with a formal analyzer; this skill adds BCQuality's remedial-knowledge explanations of why each rule exists.
 
-An orchestrator invokes this skill with either a `pr-diff` or a `file-path`. The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-telemetry-review
 version: 1
 title: AL telemetry review
 description: Performs an AL telemetry review against guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `telemetry` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). Telemetry findings are narrow by design — they apply when the diff emits, wraps, or changes custom telemetry through `Session.LogMessage`, `Session.LogError`, `FeatureTelemetry`, or related telemetry helpers. The skill returns `not-applicable` when none of those apply.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Telemetry findings are narrow by design — they apply when the review scope emits, wraps, or changes custom telemetry through `Session.LogMessage`, `Session.LogError`, `FeatureTelemetry`, or related telemetry helpers. The skill returns `not-applicable` when none of those apply.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-testing-review
 version: 1
 title: AL testing review
 description: Performs an AL testing review against guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `testing` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). Testing findings are narrow by design — they apply when the diff touches test codeunits, test runners, test methods, handlers, assertions, or fixture construction. The skill returns `not-applicable` when none of those apply.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Testing findings are narrow by design — they apply when the review scope contains test codeunits, test runners, test methods, handlers, assertions, or fixture construction. The skill returns `not-applicable` when none of those apply.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-ui-review
 version: 1
 title: AL UI and accessibility review
 description: Reviews AL page and control add-in UI files against UI text, caption, tooltip, and accessibility guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al, javascript]
@@ -18,7 +18,7 @@ Reviews AL page source and control add-in UI files against the `ui` knowledge do
 
 UI findings apply to page files — files that declare `PageType = ...`, including `*.Page.al` under the standard file-naming convention — and to JavaScript/CSS/HTML files that implement Business Central control add-ins, including their client-service communication. The skill returns `not-applicable` when the diff contains no page or control add-in changes.
 
-An orchestrator invokes this skill with either a `pr-diff` or a `file-path`. The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

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

@@ -4,7 +4,7 @@ id: al-upgrade-review
 version: 1
 title: AL upgrade review
 description: Reviews AL source changes against upgrade-code and migration guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `upgrade` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). Upgrade findings are narrow by design — they apply when the diff touches upgrade codeunits, install codeunits, table schema, enums, or objects under migration namespaces. The skill returns `not-applicable` when none of those apply.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. Upgrade findings are narrow by design — they apply when the review scope contains upgrade codeunits, install codeunits, table schema, enums, or objects under migration namespaces. The skill returns `not-applicable` when none of those apply.
 
 ## Source
 

microsoft/skills/review/al-web-services-review.md

@@ -4,7 +4,7 @@ id: al-web-services-review
 version: 1
 title: AL web services review
 description: Reviews AL API surfaces and webhook integration handlers against web-services guidance from BCQuality.
-inputs: [pr-diff, file-path]
+inputs: [pr-diff, file-path, folder-path]
 outputs: [findings-report]
 bc-version: [all]
 technologies: [al, javascript]
@@ -16,7 +16,7 @@ application-area: [all]
 
 Reviews AL source changes against the `web-services` knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by `al-code-review`.
 
-An orchestrator invokes this skill with either a `pr-diff` (the standard PR-review entry point) or a `file-path` (single-file review). The skill produces a single JSON document conforming to the DO output contract.
+An orchestrator invokes this skill with a `pr-diff`, `file-path`, or `folder-path`. The skill produces a single JSON document conforming to the DO output contract.
 
 ## Source
 

skills/README.md

@@ -57,4 +57,4 @@ each review domain to run in an isolated context.
 
 These contracts are stable. Changes require a PR approved by both maintainers.
 
-For the end-to-end flow — from orchestrator trigger through to findings integration — see [`../agent-consumption.md`](../agent-consumption.md). For the high-level project framing, see [`../README.md`](../README.md).
+For the end-to-end flow — from orchestrator trigger through to findings integration — see [How agents consume BCQuality](../docs/agent-consumption.md). For the high-level project framing, see [`../README.md`](../README.md).

skills/al-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: al-code-review
-description: Review Business Central AL code changes using BCQuality's curated rules. Use for an AL pull request, working-tree diff, branch, or individual AL file when BCQuality is installed as a standalone plugin.
+description: Review Business Central AL code using BCQuality's curated rules. Use for an AL app folder, pull request, working-tree diff, branch, or individual AL file when BCQuality is installed as a standalone plugin.
 ---
 
 # AL code review
@@ -21,8 +21,11 @@ context and execute the resulting dispatch.
    - Copy the caller's actual request verbatim into `goal`; do not replace a
      focused request such as "review performance" with a generic full-review
      goal.
-   - Set `inputs-available` to the inputs actually available to the review,
+   - Set `inputs-available` to the inputs actually available to the review:
-     normally `pr-diff` for changes or `file-path` for one file.
+     `folder-path` for an app or source folder, `pr-diff` for changes, or
+     `file-path` for one file. Pass the caller's actual path with the selected
+     input type; for a whole-app request in the current working directory, use
+     that directory as the `folder-path`.
    - Set `technologies: [al]` when the input is known to be AL.
    - Pass `bc-version`, `countries`, and `application-area` only when supplied
      or reliably determined.
@@ -66,4 +69,3 @@ where a consumer prunes its checkout to policy before the agent runs and the
 index is rebuilt over the pruned tree. Treat `BCQUALITY_ENABLED_LAYERS` as a
 selection filter, never as a security boundary. A host that needs a genuine
 deny mechanism must prune the installed tree itself.
-

skills/do.md

@@ -56,7 +56,24 @@ application-area: [all]
 
 `bc-version`, `technologies`, `countries`, `application-area` are optional filters that let an orchestrator pre-select applicable skills for a task. They follow the same semantics as in READ.
 
-`inputs` is a list of abstract input types the skill **accepts**. Standard values: `pr-diff`, `object-list`, `file-path`, `repository`, `telemetry-query`. Semantics are any-of: the orchestrator supplies whichever listed input types it has, and the skill is invoked with a non-empty subset of its declared `inputs`. A skill that cannot proceed with the supplied subset MUST return `outcome: "not-applicable"`. `outputs` is always a single-element list naming the output kind; today only `findings-report` is defined.
+`inputs` is a list of abstract input types the skill **accepts**. Standard values:
+`pr-diff`, `object-list`, `file-path`, `folder-path`, `repository`, and
+`telemetry-query`. Semantics are any-of: the orchestrator supplies whichever
+listed input types it has, and the skill is invoked with a non-empty subset of
+its declared `inputs`. A skill that cannot proceed with the supplied subset
+MUST return `outcome: "not-applicable"`. `outputs` is always a single-element
+list naming the output kind; today only `findings-report` is defined.
+
+`file-path` is one file. `folder-path` is a directory whose recursively
+contained files form the complete current-state input, such as a Business
+Central app folder containing `app.json` and AL source. The input value is the
+actual path, not merely the name of the input type. The agent MUST enumerate
+the folder rather than reducing it to one representative file.
+
+Review skills use terms such as "diff", "changed files", and "changed code" as
+shorthand for the supplied review scope. For `folder-path`, every relevant file
+under the folder is in scope. A folder supplies no historical baseline:
+comparison-only rules MUST NOT infer a prior state that was not provided.
 
 `sub-skills` is an optional field. When present and non-empty, the skill is a **super-skill** that composes other action skills; see *Composition* below. Values are repo-relative paths to action-skill files.
 
@@ -231,7 +248,7 @@ Omit `suggested-code` only when the appropriate fix depends on context the skill
 - `reference` — the suppressed file (same object shape as `findings[].references`).
 - `reason` — `layer-precedence` when another layer won under READ's precedence rules; `configuration` when the consumer disabled the file's layer.
 
-**`sub-results`** — super-skills only. Array of complete findings-reports, one per sub-skill that was invoked (i.e., every sub-skill not listed in `skipped-sub-skills`). Each entry MUST itself conform to this output contract. Leaf skills MUST NOT emit `sub-results`.
+**`sub-results`** — super-skills only. Array of complete findings-reports, one per sub-skill that was invoked (i.e., every sub-skill not listed in `skipped-sub-skills`). Each entry MUST itself conform to this output contract. Entries MUST appear in the worklist's declared order, regardless of invocation or completion order. Leaf skills MUST NOT emit `sub-results`.
 
 **`skipped-sub-skills`** — super-skills only. Array of sub-skills that were declared in frontmatter but not invoked. `reason` is `configuration` when the orchestrator disabled the sub-skill, or `not-applicable` when the super-skill's Relevance step ruled it out.
 
@@ -248,6 +265,20 @@ A **super-skill** is an action skill whose frontmatter declares a non-empty `sub
 
 Composition is flat: a super-skill MAY list only leaf skills (skills without their own `sub-skills`). Nested super-skills are not permitted in v1.
 
+### Scheduling boundary
+
+The super-skill defines which leaves must run, the input and output contracts,
+and how their results are composed. It does not prescribe a model, concurrency
+limit, retry policy, or telemetry system. Those choices belong to the
+orchestrator.
+
+Each leaf invocation MUST remain a discrete evaluation with its own complete
+findings-report. An orchestrator MAY execute independent leaves serially or
+concurrently, but MUST invoke every worklisted leaf, preserve `sub-results` in
+the declared worklist order, and wait for every invocation to finish before
+performing any super-skill self-review or final rollup. Scheduling MUST NOT
+change relevance, coverage, failure, reference-integrity, or output semantics.
+
 ### Section interpretation for super-skills
 
 The five required sections still apply. Their meaning shifts from knowledge files to sub-skills:
@@ -274,7 +305,13 @@ When the worklist is empty (every sub-skill was skipped), `outcome` is `not-appl
 
 ### Rolled-up summary
 
-`summary.counts` is the sum of sub-skill counts. `summary.coverage.worklist-size` and `items-evaluated` are the sums across invoked sub-skills.
+`summary.counts` counts the findings in the super-skill's final top-level
+`findings[]`, after failed sub-results have been excluded and duplicates have
+been merged. It MUST NOT be calculated by summing sub-skill counts, because the
+same concern may appear in more than one sub-result.
+
+`summary.coverage.worklist-size` and `items-evaluated` are the sums across
+invoked sub-skills whose outcomes are not `failed`.
 
 ### Suppression scope
 

skills/entry.md

@@ -23,6 +23,7 @@ task-context:
   inputs-available:       # values the orchestrator has ready to pass to a chosen skill
     - pr-diff
     - file-path
+    - folder-path
   technologies: [al]
   bc-version: 28
   countries: [w1]