planning/design: dialect-select and scope-label the existing per-scope artifacts

[kyle-sexton]

Parent

Refs #3799

Agent Brief

Type: Feature
Summary: The design skill selects a dialect for the per-scope artifacts it already emits, and labels each with its scope.

Amended 2026-09-06, after the planning slice #3805 found the brief described work that partly exists. plugins/planning/skills/design/SKILL.md already ships a "Scope-specific artifacts" table mapping every scope to named artifacts: data to entity-relationships.md and schema-decisions.md, integration to contract-spec.md and sequence-flows.md, system to component-map.md and communication-patterns.md, with design-threads.md common to all. A brief reading as though it introduced per-scope artifacts invited a worker to create a parallel second set beside the existing one. This slice therefore types and dialect-selects the artifacts that exist; it introduces no new artifact family. The brief also covered only three of the five scopes; library and module are now explicitly addressed.

Current behavior:
The design skill emits its per-scope artifacts as prose plus whatever diagrams the session happens to produce. Nothing fixes the diagram syntax those artifacts use, and nothing records which scope produced an artifact, so a downstream consumer cannot tell.

Desired behavior:
Each existing per-scope artifact gains a declared dialect and a scope label.

Scope	Artifact this slice types	Dialect
data	entity-relationships.md	mermaid erDiagram by default, DBML when the convention's data dialect selects it
integration	sequence-flows.md, contract-spec.md	mermaid sequenceDiagram, plus an OpenAPI 3.1 sketch for the contract spec
system	component-map.md	a C4 container view in LikeC4 or C4-PlantUML, only when the convention names one; nothing when unset
library, module	none	out of scope; these emit no typed artifact and therefore no scope label

The system row emits nothing under zero-config, and that is deliberate. The system dialect key has no default because giving it one would make a consumer who never opted in start emitting a C4 view they did not ask for. Mermaid's C4 support is experimental and is not offered for this scope.

Every emitted typed artifact carries a scope label naming the scope that produced it. That label is the contract #3823 consumes to inline the artifact into the container body, and it exists so the match is a lookup rather than an inference over prose.

Artifacts land in the topic's contract slice, where the design skill already writes them, beside design-threads.md.

For mermaid craft — layout, readability, syntax idiom — the skill cites an installed diagram capability rather than teaching it. The citation names its target explicitly, because an unnamed collaborator cannot be presence-gated, and it follows the convention governing that target's class: the seam-phrasing convention for a marketplace plugin, or the native-references convention for a bundled skill. The skill produces its artifact when the target is absent.

The skill restates the authoring-formats resolution ladder rather than deferring to it, because an installed plugin cannot read this repository's docs/conventions/ at runtime.

Key interfaces:

• The existing per-scope artifacts — gain a declared dialect and a scope label. No new artifact family.
• The diagram dialect convention key — read per artifact kind to select the emitted dialect.
• The scope label — written here, read by work-items/decompose: inline the design artifact into the container body #3823.
• The diagram-craft citation — named target, presence-gated, with a fallback.

Acceptance criteria:

• A data-scope session emits its entity-relationships artifact as a mermaid erDiagram with no convention present, and as DBML when the convention selects it.
• An integration-scope session emits a mermaid sequenceDiagram and an OpenAPI 3.1 sketch.
• A system-scope session emits a C4 container view in the named dialect when the convention names one, emits no C4 view when it does not, and never emits a mermaid C4 diagram.
• Every typed artifact carries a scope label naming its producing scope.
• The body states that library and module emit no typed artifact.
• No new artifact family is introduced; the existing Scope-specific artifacts table is the one that gains dialects.
• The diagram-craft citation names its target, is presence-gated per the convention governing that target's class, and the skill still produces its artifact when the target is absent.
• The body restates the authoring-formats resolution ladder rather than pointing at the convention document.
• /skill-quality:check passes for the design skill.
• markdownlint passes on the changed files.
• The planning plugin version is bumped per repo convention.
• The planning plugin README and any reference doc listing its skills reflect the change.

Out of scope:

• Authoring mermaid craft guidance in-house.
• Introducing any new artifact file beyond the ones the skill already emits.
• Reconciling an emitted data model against a runtime data model. That is the deferred question on the container.

Blocked by

#3814

[kyle-sexton]