Skip to content

Polish documentation for keynote readiness #236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jesper Schulz-Wedde (JesperSchulz) merged 1 commit into from
Oct 20, 2026
Merged

Polish documentation for keynote readiness #236

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/scripts/validate_frontmatter.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -743,6 +743,8 @@ def main(argv: list[str] | None = None) -> int:
report = run(root)

gha = os.environ.get("GITHUB_ACTIONS") == "true"
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
for d in report.diagnostics:
line = d.format_gha(root) if gha else d.format_plain(root)
print(line)
Expand Down
53 changes: 21 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,46 +93,35 @@ the review can still discover knowledge by reading the folders.

## Scope

Today's curated content covers **technical AL code review** and a focused
**Supply Chain Management (SCM)** functional domain. It augments
Today's curated content covers **technical AL code review** and focused
**Supply Chain Management (SCM)** and **Finance** functional domains. It augments
the agent's judgment; it is not an exhaustive BC manual or a substitute for
compilation, analyzers, tests, or human review. See
[coverage and limits](docs/using-bcquality.md#coverage-and-limits) for the
available domains and the difference between a folder review and a comparison.
Mechanical issues already enforced by the AL compiler or standard analyzers are
intentionally left to those deterministic tools rather than duplicated here.

BCQuality defines a provisional internal, read-only `al-development-plan`
action-skill contract that selects relevant constraints before a consumer
implements its own existing plan. It is not registered as a standalone plugin
skill and does not change the plugin version. Consumer-owner agreement and a
runtime pilot are required before treating it as a stable public surface.

Repository-specific orchestrators retain planning, implementation, approvals,
tests, environment, propagation, and delivery ownership. The intended flow is
consumer analysis and normalized plan -> read-only BCQuality guidance ->
existing implementation phases -> independent final BCQuality review ->
delivery. Consumer uptake and a real runtime pilot are follow-up work, not
implemented integrations or demonstrated authoring improvements.

`no-knowledge` means no additional applicable BCQuality constraints, with empty
`knowledge`; it does not make a plan unsafe or prevent the consumer from using
its ordinary gates. Retrieval failures and materially unresolved conditional
guidance are distinct outcomes, not empty knowledge. Do not add generic advice
just to avoid a `no-knowledge` result.

The [SCM domain](microsoft/knowledge/scm/) covers selected inventory, costing,
reservation, tracking, and warehouse/posting workflows, not exhaustive supply
chain validation. Broader functional coverage such as Finance, Manufacturing,
Jobs, and Service, and technologies such as PowerShell, pipelines, and Power
Platform, remain valid future scope, **not current coverage claims**.

## Plan-enrichment follow-up scope

Consumer agreement, consumer-owned persistence and phase injection, a pinned
baseline comparison, and a runtime pilot remain follow-up work. BCQuality does
not claim improved repairs or authoring effectiveness from this provisional
contract alone.
reservation, tracking, and warehouse/posting workflows. The
[Finance domain](microsoft/knowledge/finance/) covers selected journal posting,
financial ledger, application, VAT, and posting-dimension workflows. Neither is
exhaustive functional validation. Broader functional coverage such as
Manufacturing, Jobs, and Service, and technologies such as PowerShell,
pipelines, and Power Platform, remain valid future scope, **not current
coverage claims**.

### Preview: guidance before implementation

BCQuality can also apply its knowledge **before code is written**. The
read-only `al-development-plan` skill takes an existing AL development plan
and returns the BCQuality constraints and validation considerations that apply
to it. Your workflow keeps ownership of planning, implementation, tests,
approvals, and delivery, and should still review the completed change.

This capability is a preview for explicit integrations. It is not yet exposed
by the standalone plugin, and its contract may change based on pilot feedback.
See [plan guidance integration](docs/agent-consumption.md#plan-guidance-integration-preview).

## What's in this repo

Expand Down
1 change: 1 addition & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ prerequisites for using the plugin.
| --- | --- |
| [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. |
| [Plan guidance integration (preview)](agent-consumption.md#plan-guidance-integration-preview) | Apply BCQuality constraints to an existing development plan before implementation. |
| [Standalone runner](standalone-runner.md) | Optional model selection, scheduling, retries, and telemetry. |
| [SARIF export](standalone-runner.md#publish-findings-as-sarif) | Show accepted findings as code scanning annotations in GitHub or Azure DevOps. |
| [Global skills](../skills/README.md) | Host adapters versus internal protocol files. |
Expand Down
18 changes: 10 additions & 8 deletions docs/agent-consumption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,12 @@ at Entry.
| `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. |
| `<layer>/skills/` | Layer-owned review and plan-guidance action skills. |
| `schemas/` | JSON Schemas for the skill index and report contracts. |
| `plugin.json`, `.claude-plugin/` | Host plugin and marketplace manifests. |
| `docs/` | Partner guides and integration references. |
| `evaluation/` | Neutral review fixtures and scoring contract. |
| `tools/` | Knowledge-index and evaluation tooling. |
| `tools/` | Knowledge discovery and retrieval, skill resolution, report validation, SARIF export, and evaluation tooling. |
| `.github/` | Validation and repository workflows. |

Layers are `microsoft`, `community`, and `custom`; Custom is a template for
Expand Down Expand Up @@ -184,12 +186,12 @@ 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.

## Provisional repository-specific development integration
## Plan guidance integration (preview)

A repository-specific workflow can consume this read-only foundation before
authoring while retaining its independent final review. This is the intended
integration boundary proposed by `al-development-plan`, not a shipped consumer
integration or a stable plugin surface:
integration boundary for the preview `al-development-plan` skill, not a shipped
consumer integration or a stable plugin surface:

1. Investigate and produce the consumer's normal initial plan. Normalize any
consumer-specific format outside BCQuality. A full serialized plan document
Expand All @@ -204,9 +206,9 @@ integration or a stable plugin surface:
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
4. Inject relevant constraints and validation considerations into the
workflow's existing test, implementation, propagation, 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
Expand Down
Loading