diff --git a/.github/scripts/validate_frontmatter.py b/.github/scripts/validate_frontmatter.py index f9f300d9..c16b3dc7 100644 --- a/.github/scripts/validate_frontmatter.py +++ b/.github/scripts/validate_frontmatter.py @@ -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) diff --git a/README.md b/README.md index 45893ef0..011561e6 100644 --- a/README.md +++ b/README.md @@ -93,8 +93,8 @@ 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 @@ -102,37 +102,26 @@ 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 diff --git a/docs/README.md b/docs/README.md index 578cbba0..adddaafd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. | diff --git a/docs/agent-consumption.md b/docs/agent-consumption.md index 75e6262d..14fb3db1 100644 --- a/docs/agent-consumption.md +++ b/docs/agent-consumption.md @@ -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. | | `/knowledge//` | Atomic articles and optional sibling samples. | -| `/skills/` | Layer-owned action skills. | +| `/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 @@ -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 @@ -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