diff --git a/agent-consumption.md b/agent-consumption.md index 0d2e5b4..8db80d6 100644 --- a/agent-consumption.md +++ b/agent-consumption.md @@ -21,7 +21,7 @@ flowchart LR E -->|3 dispatch record| A A -->|4 invoke dispatched skill| S[Action skill
e.g. al-code-review] S -->|5 execute| P[Source → Relevance
→ Worklist → Action
reading READ · DO on demand] - P -->|6 emit| R[Findings · References
· Confidence] + P -->|6 emit| R[Findings · Domain labels
· References · Confidence] R -->|7 integrate| O ``` @@ -65,6 +65,7 @@ The output contract is defined in the DO meta-skill so that every action skill - **Outcome** — `completed`, `not-applicable`, `no-knowledge`, `partial`, or `failed`. An orchestrator can distinguish a clean run from a no-op from a failure without guessing. - **Findings** — what the skill observed (severity, message, optional location). +- **Domain** — the producer-owned, human-readable display label on each review finding. - **References** — structured objects (`path` plus optional commit `sha`) pointing to the knowledge files that informed each finding. - **Confidence** — per-finding evidence strength. - **Suppressed** — knowledge files that were discarded by layer precedence or configuration, so reviewers can see what was overridden. @@ -78,12 +79,12 @@ The orchestrator turns findings into PR comments, build gates, or IDE diagnostic 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. These are produced by leaf sub-skills and rolled up by super-skills. -- **Agent findings** are surfaced by a super-skill from its own self-review pass when no BCQuality knowledge file backs the concern. They are tagged with `from-sub-skill: "agent"`, carry an empty `references: []`, use a slug `id` prefixed `agent:`, and have `confidence` capped at `medium`. Their `message` is self-contained because there is no knowledge-file footer to fall back on. +- **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 super-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 the relevant sub-skill output); a contradicting file suppresses the candidate. Only candidates with no BCQuality coverage become agent findings. +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 MAY render the two kinds differently — for example, by labelling agent findings or routing them to a separate review domain — and MAY apply independent severity floors. The `from-sub-skill: "agent"` marker is the contract. +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 diff --git a/microsoft/skills/review/al-appsource-review.md b/microsoft/skills/review/al-appsource-review.md index 14af7bf..cf09619 100644 --- a/microsoft/skills/review/al-appsource-review.md +++ b/microsoft/skills/review/al-appsource-review.md @@ -82,7 +82,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"AppSource"`. A populated example: ```json { @@ -105,6 +105,7 @@ Output conforms to the DO output contract. A populated example: { "path": "microsoft/knowledge/appsource/object-affixes-prevent-collisions.md" } ], "confidence": "high", + "domain": "AppSource", "suggested-code": "field(50100; \"Loyalty Points ABC\"; Integer)" } ], diff --git a/microsoft/skills/review/al-breaking-changes-review.md b/microsoft/skills/review/al-breaking-changes-review.md index 4238bca..0af5abc 100644 --- a/microsoft/skills/review/al-breaking-changes-review.md +++ b/microsoft/skills/review/al-breaking-changes-review.md @@ -77,7 +77,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Breaking Changes"`. A populated example: ```json { @@ -100,7 +100,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/breaking-changes/do-not-change-published-procedure-signatures.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Breaking Changes" }, { "id": "microsoft/knowledge/breaking-changes/choose-access-modifiers-deliberately.md", @@ -113,7 +114,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/breaking-changes/choose-access-modifiers-deliberately.md" } ], - "confidence": "medium" + "confidence": "medium", + "domain": "Breaking Changes" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-code-review.md b/microsoft/skills/review/al-code-review.md index df25e4d..a7cb8d9 100644 --- a/microsoft/skills/review/al-code-review.md +++ b/microsoft/skills/review/al-code-review.md @@ -76,7 +76,7 @@ For each sub-skill in the worklist, executed one at a time per the discipline ab 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`. 3. If the sub-skill's `outcome` is `failed`, stop here for this sub-skill: its findings are not reliable per the DO contract and MUST NOT be copied into the super-skill's top-level `findings[]` or counted in `summary.counts`. -4. Otherwise, append each entry from the sub-skill's `findings[]` to the super-skill's top-level `findings[]`, setting `from-sub-skill` to the sub-skill's `skill.id`. For non-citation findings (those whose `id` is a skill-defined slug rather than a reference path), prefix `id` with `:` to prevent collisions across sub-skills. Other finding fields are preserved. +4. Otherwise, append each entry from the sub-skill's `findings[]` to the super-skill's top-level `findings[]`, setting `from-sub-skill` to the sub-skill's `skill.id` and preserving each finding's optional `domain` field verbatim, including its absence. For non-citation findings (those whose `id` is a skill-defined slug rather than a reference path), prefix `id` with `:` to prevent collisions across sub-skills. Other finding fields are preserved. ### Agent self-review pass @@ -89,11 +89,12 @@ Frame the pass by cross-cutting concerns — architecture, error handling, resou For every candidate the agent identifies in this pass: 1. **Validate against BCQuality knowledge.** Check the candidate against the knowledge files the sub-skills have already loaded for this task (visible via their `references` and `suppressed` lists in `sub-results`). - - If a BCQuality knowledge file matches the candidate, upgrade it to a knowledge-backed finding: cite the file in `references`, set `id` to the file's path, set `from-sub-skill` to the sub-skill that owns that knowledge domain, and merge with or deduplicate against any sub-skill finding that already covers the same concern at the same location. + - If a BCQuality knowledge file matches the candidate, upgrade it to a knowledge-backed finding: cite the file in `references`, set `id` to the file's path, set `from-sub-skill` to the sub-skill that owns that knowledge domain, set `domain` to the human-readable label required by that sub-skill's Output contract, and merge with or deduplicate against any sub-skill finding that already covers the same concern at the same location. - If a BCQuality knowledge file **explicitly contradicts** the candidate (its `## Best Practice` or `## Anti Pattern` says the opposite of what the agent flagged), suppress the candidate and do not surface it. - Otherwise the candidate has no BCQuality coverage; emit it as a super-skill agent finding. 2. **Emit agent finding.** Per DO's *Agent findings* rules: - `from-sub-skill: "agent"` (the super-skill itself produced it) + - `domain: "Agent"` (the display label for super-skill cross-cutting findings) - `references: []` - `id` is a skill-defined slug prefixed with `agent:` (for example, `agent:missing-error-handling-on-http-call`). - `confidence` capped at `medium`. @@ -143,7 +144,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip { "path": "microsoft/knowledge/performance/apply-filters-before-iterating.md" } ], "confidence": "high", - "from-sub-skill": "al-performance-review" + "from-sub-skill": "al-performance-review", + "domain": "Performance" }, { "id": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md", @@ -157,7 +159,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip { "path": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md" } ], "confidence": "high", - "from-sub-skill": "al-performance-review" + "from-sub-skill": "al-performance-review", + "domain": "Performance" }, { "id": "microsoft/knowledge/security/secrettext-for-credentials.md", @@ -172,7 +175,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip { "path": "microsoft/knowledge/security/secrettext-for-credentials.md" } ], "confidence": "high", - "from-sub-skill": "al-security-review" + "from-sub-skill": "al-security-review", + "domain": "Security" }, { "id": "microsoft/knowledge/security/secrets-isolated-storage.md", @@ -186,7 +190,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip { "path": "microsoft/knowledge/security/secrets-isolated-storage.md" } ], "confidence": "medium", - "from-sub-skill": "al-security-review" + "from-sub-skill": "al-security-review", + "domain": "Security" }, { "id": "agent:missing-error-handling-on-http-client", @@ -199,7 +204,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip }, "references": [], "confidence": "medium", - "from-sub-skill": "agent" + "from-sub-skill": "agent", + "domain": "Agent" } ], "suppressed": [], @@ -224,7 +230,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip "references": [ { "path": "microsoft/knowledge/performance/apply-filters-before-iterating.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Performance" }, { "id": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md", @@ -237,7 +244,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip "references": [ { "path": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Performance" } ], "suppressed": [] @@ -262,7 +270,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip "references": [ { "path": "microsoft/knowledge/security/secrettext-for-credentials.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Security" }, { "id": "microsoft/knowledge/security/secrets-isolated-storage.md", @@ -275,7 +284,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip "references": [ { "path": "microsoft/knowledge/security/secrets-isolated-storage.md" } ], - "confidence": "medium" + "confidence": "medium", + "domain": "Security" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-data-modeling-review.md b/microsoft/skills/review/al-data-modeling-review.md index 7cbe48d..ca10e73 100644 --- a/microsoft/skills/review/al-data-modeling-review.md +++ b/microsoft/skills/review/al-data-modeling-review.md @@ -85,7 +85,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Data Modeling"`. A populated example: ```json { @@ -108,6 +108,7 @@ Output conforms to the DO output contract. A populated example: { "path": "microsoft/knowledge/data-modeling/set-last-date-modified-in-onmodify-and-onrename.md" } ], "confidence": "high", + "domain": "Data Modeling", "suggested-code": "trigger OnRename()\nbegin\n \"Last Date Modified\" := Today();\nend;" } ], diff --git a/microsoft/skills/review/al-error-handling-review.md b/microsoft/skills/review/al-error-handling-review.md index eaf252b..3b7d6cf 100644 --- a/microsoft/skills/review/al-error-handling-review.md +++ b/microsoft/skills/review/al-error-handling-review.md @@ -78,7 +78,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Error Handling"`. A populated example: ```json { @@ -101,7 +101,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/error-handling/prefer-errorinfo-for-actionable-errors.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Error Handling" }, { "id": "microsoft/knowledge/error-handling/errortype-internal-vs-client-for-diagnostics.md", @@ -114,7 +115,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/error-handling/errortype-internal-vs-client-for-diagnostics.md" } ], - "confidence": "medium" + "confidence": "medium", + "domain": "Error Handling" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-events-review.md b/microsoft/skills/review/al-events-review.md index 2d7a76d..ef4be0e 100644 --- a/microsoft/skills/review/al-events-review.md +++ b/microsoft/skills/review/al-events-review.md @@ -96,7 +96,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Events"`. A populated example: ```json { @@ -119,7 +119,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/events/publish-thin-onbefore-onafter-integration-events.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Events" }, { "id": "microsoft/knowledge/events/use-ishandled-to-make-base-behaviour-overridable.md", @@ -132,7 +133,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/events/use-ishandled-to-make-base-behaviour-overridable.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Events" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-interfaces-review.md b/microsoft/skills/review/al-interfaces-review.md index 65db35e..a52d451 100644 --- a/microsoft/skills/review/al-interfaces-review.md +++ b/microsoft/skills/review/al-interfaces-review.md @@ -85,7 +85,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Interfaces"`. A populated example: ```json { @@ -108,7 +108,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/interfaces/prefer-interface-over-case-branching.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Interfaces" }, { "id": "microsoft/knowledge/interfaces/set-defaultimplementation-on-enum.md", @@ -121,7 +122,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/interfaces/set-defaultimplementation-on-enum.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Interfaces" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-performance-review.md b/microsoft/skills/review/al-performance-review.md index 9bd23dc..f27beb3 100644 --- a/microsoft/skills/review/al-performance-review.md +++ b/microsoft/skills/review/al-performance-review.md @@ -85,7 +85,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Performance"`. A populated example: ```json { @@ -108,7 +108,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/performance/apply-filters-before-iterating.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Performance" }, { "id": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md", @@ -121,7 +122,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Performance" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-privacy-review.md b/microsoft/skills/review/al-privacy-review.md index 2cd4005..0988622 100644 --- a/microsoft/skills/review/al-privacy-review.md +++ b/microsoft/skills/review/al-privacy-review.md @@ -79,7 +79,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Privacy"`. A populated example: ```json { @@ -102,7 +102,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/privacy/data-classification-required-on-pii-fields.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Privacy" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-security-review.md b/microsoft/skills/review/al-security-review.md index e6ee82b..23a93cf 100644 --- a/microsoft/skills/review/al-security-review.md +++ b/microsoft/skills/review/al-security-review.md @@ -77,7 +77,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Security"`. A populated example: ```json { @@ -100,7 +100,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/security/secrettext-for-credentials.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Security" }, { "id": "microsoft/knowledge/security/secrets-isolated-storage.md", @@ -113,7 +114,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/security/secrets-isolated-storage.md" } ], - "confidence": "medium" + "confidence": "medium", + "domain": "Security" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-style-review.md b/microsoft/skills/review/al-style-review.md index 68f9834..37b9a15 100644 --- a/microsoft/skills/review/al-style-review.md +++ b/microsoft/skills/review/al-style-review.md @@ -77,7 +77,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Style"`. A populated example: ```json { @@ -99,7 +99,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/style/label-suffix-approved-list.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Style" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-telemetry-review.md b/microsoft/skills/review/al-telemetry-review.md index 3cad1c2..e4169a2 100644 --- a/microsoft/skills/review/al-telemetry-review.md +++ b/microsoft/skills/review/al-telemetry-review.md @@ -77,7 +77,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. The empty-corpus case produces: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Telemetry"`. The empty-corpus case produces: ```json { diff --git a/microsoft/skills/review/al-testing-review.md b/microsoft/skills/review/al-testing-review.md index 54aeded..01f8f16 100644 --- a/microsoft/skills/review/al-testing-review.md +++ b/microsoft/skills/review/al-testing-review.md @@ -84,7 +84,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Testing"`. A populated example: ```json { @@ -107,6 +107,7 @@ Output conforms to the DO output contract. A populated example: { "path": "microsoft/knowledge/testing/asserterror-needs-expectederror-and-code.md" } ], "confidence": "high", + "domain": "Testing", "suggested-code": "asserterror PostInvalidOrder();\nAssert.ExpectedError(ExpectedPostingErr);" } ], diff --git a/microsoft/skills/review/al-ui-review.md b/microsoft/skills/review/al-ui-review.md index ef22fa3..19f03c9 100644 --- a/microsoft/skills/review/al-ui-review.md +++ b/microsoft/skills/review/al-ui-review.md @@ -77,7 +77,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Accessibility"`. A populated example: ```json { @@ -99,7 +99,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/ui/show-caption-on-editable-fields.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Accessibility" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-upgrade-review.md b/microsoft/skills/review/al-upgrade-review.md index c087585..2cecf0c 100644 --- a/microsoft/skills/review/al-upgrade-review.md +++ b/microsoft/skills/review/al-upgrade-review.md @@ -80,7 +80,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Upgrade"`. A populated example: ```json { @@ -102,7 +102,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/upgrade/enum-values-additive-at-end.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Upgrade" } ], "suppressed": [] diff --git a/microsoft/skills/review/al-web-services-review.md b/microsoft/skills/review/al-web-services-review.md index 1136a4d..551dce5 100644 --- a/microsoft/skills/review/al-web-services-review.md +++ b/microsoft/skills/review/al-web-services-review.md @@ -80,7 +80,7 @@ Outcome selection: ## Output -Output conforms to the DO output contract. A populated example: +Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Web Services"`. A populated example: ```json { @@ -103,7 +103,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/web-services/set-required-api-page-properties.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Web Services" }, { "id": "microsoft/knowledge/web-services/expose-systemid-as-the-api-key.md", @@ -116,7 +117,8 @@ Output conforms to the DO output contract. A populated example: "references": [ { "path": "microsoft/knowledge/web-services/expose-systemid-as-the-api-key.md" } ], - "confidence": "high" + "confidence": "high", + "domain": "Web Services" } ], "suppressed": [] diff --git a/skills/bcquality-al-review/SKILL.md b/skills/bcquality-al-review/SKILL.md index 937e06a..a11f891 100644 --- a/skills/bcquality-al-review/SKILL.md +++ b/skills/bcquality-al-review/SKILL.md @@ -64,10 +64,10 @@ plugin-root environment variable, prefer it. file and execute its Source → Relevance → Worklist → Action steps, reading `PLUGIN_ROOT/skills/read.md` and `PLUGIN_ROOT/skills/do.md` on demand. -4. **Emit findings.** Produce the rolled-up findings report in the DO output contract - (`outcome`, `findings`, `references`, `confidence`, `suppressed`). Do not invent a - different shape; downstream consumers parse the DO contract without skill-specific - logic. +4. **Emit findings.** Produce the rolled-up findings report in the DO output contract, + including each review finding's producer-supplied `domain` label (`outcome`, + `findings`, `references`, `confidence`, `suppressed`). Do not invent a different + shape; downstream consumers parse the DO contract without skill-specific logic. If Entry returns `no-match` or `failed`, return the dispatch record unchanged so the caller can log the reason. diff --git a/skills/do.md b/skills/do.md index 777f89f..bc7780e 100644 --- a/skills/do.md +++ b/skills/do.md @@ -95,6 +95,7 @@ Every action skill emits a single JSON document that conforms to this schema: ], "confidence": "high | medium | low", "from-sub-skill": "string", + "domain": "string", "suggested-code": "string", "suggested-code-omission-reason": "string" } @@ -189,6 +190,10 @@ The first reference is the **primary** reference: the knowledge file the finding **`findings[].from-sub-skill`** — optional. Set only by super-skills. The `skill.id` of the sub-skill that produced the finding, or the literal string `"agent"` for an agent finding the super-skill produced from its own cross-cutting reasoning. Absent on findings emitted directly by a leaf skill — including agent findings the leaf emits within its own domain, which appear in the leaf's own report without this field. +**`findings[].domain`** — optional in the shared schema for backward compatibility and for non-review findings. It is a short, human-readable display label for the review domain that produced the finding (for example, `Security`, `Breaking Changes`, `API & Web Services`). A review leaf skill MUST set it on every finding it emits. The value MUST be a non-empty, single-line string with no leading or trailing whitespace or control characters. Internal whitespace, punctuation, case, and non-ASCII characters are valid and significant. + +A review super-skill MUST preserve `domain` verbatim when rolling a leaf finding into its top-level `findings[]`, including preserving its absence from older producers, and MUST set it to `"Agent"` for agent findings it emits about cross-cutting concerns. Consumers MUST tolerate its absence. When rendering a present value, consumers MUST preserve the complete display text, escaping only as required by the output format; they MUST NOT split it on whitespace or restrict it to identifier characters. `domain` is display text, not a stable machine identifier. If a consumer embeds it in metadata or uses it in a deduplication key, it MUST retain the exact string, use a lossless encoding, or use a collision-resistant digest; it MUST NOT rely on lowercasing or lossy slugification as the sole identity. + **`findings[].suggested-code`** — optional in the schema but **expected for mechanical findings**. It is a concrete code-replacement payload for the lines indicated by `location`. When present, the string MUST be a literal replacement for the source lines covered by `location.line` (or `location.range` if set) — i.e., what the file would contain after the fix, with no surrounding diff markers, fences, or commentary. Consumers MAY render it as a one-click suggestion in the delivery surface (for example, a GitHub ```` ```suggestion ```` block). Emit `suggested-code` whenever the fix is small, local, and mechanical: deleting unreachable code; replacing one expression (`Count() > 0` → `not IsEmpty()`); moving a local `Label` to object scope; adding a missing property such as `ToolTip`, `OptionCaption`, or `DataClassification`; replacing a string-concatenated `Error` with a Label-backed call; changing a permission token; or adding a missing `else`/guard branch whose replacement is unambiguous from the surrounding diff. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, prefer adapting the `.good.al` replacement into `suggested-code`. @@ -226,7 +231,7 @@ The five required sections still apply. Their meaning shifts from knowledge file - `## Source` — names the sub-skills invoked (mirrors `sub-skills` in frontmatter). - `## Relevance` — rules for deciding which sub-skills apply to the current task. A sub-skill is relevant when its declared `inputs` are satisfied by the orchestrator's provided inputs and the orchestrator has not disabled it via configuration. The super-skill MUST NOT filter sub-skills by task content (for example, by inspecting the diff or the file). Task-level applicability is the sub-skill's own responsibility; sub-skills signal non-applicability by returning `outcome: "not-applicable"` or `outcome: "no-knowledge"`. - `## Worklist` — the final list of sub-skills to invoke; the rest go to `skipped-sub-skills`. -- `## Action` — invoke each worklisted sub-skill with the appropriate subset of inputs, collect its findings-report verbatim into `sub-results`, and copy its `findings[]` into the super-skill's top-level `findings[]` with `from-sub-skill` set. Findings from a sub-skill with `outcome: "failed"` MUST NOT be copied into the super-skill's top-level `findings[]` and MUST NOT contribute to the super-skill's `summary.counts` (their report is still preserved in `sub-results` for traceability, consistent with DO's rule that consumers ignore a failed skill's findings). +- `## Action` — invoke each worklisted sub-skill with the appropriate subset of inputs, collect its findings-report verbatim into `sub-results`, and copy its `findings[]` into the super-skill's top-level `findings[]` with `from-sub-skill` set. All finding fields, including the optional `domain`, are preserved verbatim unless this contract explicitly requires a transformation. Findings from a sub-skill with `outcome: "failed"` MUST NOT be copied into the super-skill's top-level `findings[]` and MUST NOT contribute to the super-skill's `summary.counts` (their report is still preserved in `sub-results` for traceability, consistent with DO's rule that consumers ignore a failed skill's findings). - `## Output` — the super-skill's output contract, including `sub-results` and, if any, `skipped-sub-skills`. ### Outcome rollup @@ -288,5 +293,3 @@ Conforms to the DO output contract. ## How orchestrators consume output An orchestrator invokes an action skill with an input appropriate to the skill's declared `inputs`, receives the JSON output, and maps findings to its delivery surface (PR comments, build gates, IDE diagnostics). The orchestrator MUST NOT interpret skill-specific fields beyond the schema above. Skills that need richer semantics MUST encode them within the schema (for example, by adding structured `message` text) rather than extending the output shape. - -