Merge PR #223: Implement MDS039 build directive rule

Author: merge-queue-bot

.github/copilot-instructions.md

@@ -34,6 +34,7 @@ row: "- [{summary}](../{filename})"
 - [Build commands, project layout, code style, test fixtures, coverage gate, and merge conflicts.](../docs/development/index.md)
 - [Label-driven merge queue workflow using jeduden/merge-queue-action.](../docs/development/merge-queue.md)
 - [Rebase, CI monitoring, and review comment resolution.](../docs/development/pr-fixup-workflow.md)
+- [How to use the build directive to declare artifact outputs, keep generated bodies in sync, and configure user-declared recipes.](../docs/guides/directives/build.md)
 - [How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames.](../docs/guides/directives/enforcing-structure.md)
 - [How to use catalog and include directives to generate and embed content in Markdown files.](../docs/guides/directives/generating-content.md)
 - [Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.](../docs/guides/directives/hugo-migration.md)

AGENTS.md

@@ -40,6 +40,7 @@ row: "- [{summary}]({filename})"
 - [Build commands, project layout, code style, test fixtures, coverage gate, and merge conflicts.](docs/development/index.md)
 - [Label-driven merge queue workflow using jeduden/merge-queue-action.](docs/development/merge-queue.md)
 - [Rebase, CI monitoring, and review comment resolution.](docs/development/pr-fixup-workflow.md)
+- [How to use the build directive to declare artifact outputs, keep generated bodies in sync, and configure user-declared recipes.](docs/guides/directives/build.md)
 - [How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames.](docs/guides/directives/enforcing-structure.md)
 - [How to use catalog and include directives to generate and embed content in Markdown files.](docs/guides/directives/generating-content.md)
 - [Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.](docs/guides/directives/hugo-migration.md)

CLAUDE.md

@@ -26,6 +26,7 @@ row: "- [{summary}]({filename})"
 - [Build commands, project layout, code style, test fixtures, coverage gate, and merge conflicts.](docs/development/index.md)
 - [Label-driven merge queue workflow using jeduden/merge-queue-action.](docs/development/merge-queue.md)
 - [Rebase, CI monitoring, and review comment resolution.](docs/development/pr-fixup-workflow.md)
+- [How to use the build directive to declare artifact outputs, keep generated bodies in sync, and configure user-declared recipes.](docs/guides/directives/build.md)
 - [How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames.](docs/guides/directives/enforcing-structure.md)
 - [How to use catalog and include directives to generate and embed content in Markdown files.](docs/guides/directives/generating-content.md)
 - [Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.](docs/guides/directives/hugo-migration.md)

PLAN.md

@@ -17,7 +17,7 @@ footer: |
 | ID  | Status | Model  | Title                                                                                                |
 |-----|--------|--------|------------------------------------------------------------------------------------------------------|
 | 100 | ✅     | sonnet | [build config block and MDS040 recipe-safety rule](plan/100_build-config-and-mds040.md)              |
-| 101 | 🔲     | sonnet | [build directive and MDS039 lint rule](plan/101_build-directive-mds039.md)                           |
+| 101 | ✅     | sonnet | [build directive and MDS039 lint rule](plan/101_build-directive-mds039.md)                           |
 | 102 | 🔲     | opus   | [Builder interface and mdsmith build subcommand](plan/102_build-subcommand.md)                       |
 | 103 | 🔲     | opus   | [Build target staleness and dependency tracking](plan/103_build-staleness-and-deps.md)               |
 | 104 | 🔲     | sonnet | [Build lifecycle hooks (before/after)](plan/104_build-lifecycle-hooks.md)                            |

cmd/mdsmith/main.go

@@ -28,6 +28,7 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundfencedcode"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundheadings"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundlists"
+	_ "github.com/jeduden/mdsmith/internal/rules/build"
 	_ "github.com/jeduden/mdsmith/internal/rules/catalog"
 	_ "github.com/jeduden/mdsmith/internal/rules/concisenessscoring"
 	_ "github.com/jeduden/mdsmith/internal/rules/crossfilereferenceintegrity"

docs/guides/directives/build.md

@@ -0,0 +1,107 @@
+---
+title: Build directive
+summary: >-
+  How to use the build directive to declare artifact outputs, keep
+  generated bodies in sync, and configure user-declared recipes.
+---
+# Build directive
+
+The `<?build?>` directive declares a build artifact — a file
+produced by a recipe configured in `build.recipes`. `mdsmith fix`
+renders the section body from the recipe's `body-template` and
+keeps it up to date. No external tool runs at lint time.
+
+## Syntax
+
+```text
+<?build
+recipe: RECIPE-NAME
+output: path/to/artifact.ext
+[recipe-specific params]
+?>
+RENDERED BODY
+<?/build?>
+```
+
+The directive uses the same block form as `<?catalog?>` and
+`<?include?>`. Inline form is not supported.
+
+### Common parameters
+
+| Name     | Required | Description                                                   |
+|----------|----------|---------------------------------------------------------------|
+| `recipe` | yes      | Recipe name declared in `build.recipes`                       |
+| `output` | yes      | Relative artifact path; no `..` components; no absolute paths |
+
+`output` accepts any file extension; the rule applies no extension
+filter.
+
+## Declaring recipes
+
+All recipes must be declared in `build.recipes` in `.mdsmith.yml`.
+A `<?build?>` directive can only reference recipes declared there;
+it cannot introduce a new recipe inline.
+
+```yaml
+build:
+  recipes:
+    render:
+      command: "myrenderer {source} -o {output}"
+      body-template: "![{alt}]({output})"
+      params:
+        required: [source]
+        optional: [title, output]
+    vhs:
+      command: "vhs {input}"
+      body-template: "![{alt}]({output})"
+      params:
+        required: [input]
+```
+
+Then in a Markdown file:
+
+```text
+<?build
+recipe: render
+source: diagram.svg
+output: docs/diagram.png
+?>
+![render output: docs/diagram.png](docs/diagram.png)
+<?/build?>
+```
+
+## Generated body
+
+`mdsmith fix` renders the section body from the recipe's
+`body-template`. Two placeholders are available:
+
+| Placeholder | Value                                   |
+|-------------|-----------------------------------------|
+| `{output}`  | The `output` param value                |
+| `{alt}`     | `"{recipe} output: {output}"` (default) |
+
+When `body-template` is omitted from the recipe declaration, the
+default `[{output}]({output})` is used.
+
+## Rule MDS039
+
+MDS039 validates `<?build?>` directives and reports:
+
+- **Error** when `recipe` is missing or not declared in `build.recipes`
+- **Error** when `output` is missing, is an absolute path, or contains `..` components
+- **Error** when a required param for the recipe is absent
+- **Warning** when a param is not in the recipe's `required` or
+  `optional` lists
+- **Error** (`generated section is out of date`) when the body
+  diverges from the rendered `body-template`
+
+Run `mdsmith fix <file>` to regenerate stale bodies.
+
+## Interaction with other rules
+
+- **MDS027**: a missing artifact file fires MDS027 independently;
+  MDS039 does not duplicate it.
+- **MDS040**: validates `build.recipes` command safety at lint time;
+  MDS039 validates `<?build?>` directive usage in Markdown files.
+- **merge-driver**: regenerates `<?build?>` bodies on conflict
+  via `gensection.Engine`; artifact bytes are not regenerated.

docs/guides/index.md

@@ -16,11 +16,12 @@ header: |
   |-------|-------------|
 row: "| [{title}]({filename}) | {summary} |"
 ?>
-| Guide                                                                               | Description                                                                                             |
-|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
-| [Choosing Readability, Conciseness, and Token Budget Metrics](metrics-tradeoffs.md) | Trade-offs and threshold guidance for readability, structure, length, and token budgets.                |
-| [Coming from Hugo](directives/hugo-migration.md)                                    | Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.             |
-| [Enforcing Document Structure with Schemas](directives/enforcing-structure.md)      | How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames. |
-| [File Kinds](file-kinds.md)                                                         | How to declare file kinds, assign files to them, and read the merged rule config that results.          |
-| [Generating Content with Directives](directives/generating-content.md)              | How to use catalog and include directives to generate and embed content in Markdown files.              |
+| Guide                                                                               | Description                                                                                                                     |
+|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
+| [Build directive](directives/build.md)                                              | How to use the build directive to declare artifact outputs, keep generated bodies in sync, and configure user-declared recipes. |
+| [Choosing Readability, Conciseness, and Token Budget Metrics](metrics-tradeoffs.md) | Trade-offs and threshold guidance for readability, structure, length, and token budgets.                                        |
+| [Coming from Hugo](directives/hugo-migration.md)                                    | Key differences between Hugo templates and mdsmith directives for users familiar with Hugo.                                     |
+| [Enforcing Document Structure with Schemas](directives/enforcing-structure.md)      | How to use schemas, require, and allow-empty-section to validate headings, front matter, and filenames.                         |
+| [File Kinds](file-kinds.md)                                                         | How to declare file kinds, assign files to them, and read the merged rule config that results.                                  |
+| [Generating Content with Directives](directives/generating-content.md)              | How to use catalog and include directives to generate and embed content in Markdown files.                                      |
 <?/catalog?>

internal/config/build.go

@@ -121,31 +121,37 @@ func validateCommandPlaceholders(recipeName, command string, allowed map[string]
 	return nil
 }
 
-// InjectBuildConfig copies cfg.Build.Recipes into the recipe-safety
-// rule settings, alongside the config file path. It is called after
-// config loading in main so the rule receives its inputs through the
-// normal ApplySettings path. cfgPath is the path to the loaded
-// .mdsmith.yml; it is set in the config-path setting so MDS040 can
-// report diagnostics against the
-// right file.
+// InjectBuildConfig copies cfg.Build.Recipes into the recipe-safety and
+// build rule settings. It is called after config loading in main so rules
+// receive their inputs through the normal ApplySettings path. cfgPath is
+// the path to the loaded .mdsmith.yml; it is set in the config-path
+// setting so MDS040 can report diagnostics against the right file.
 func InjectBuildConfig(cfg *Config, cfgPath string) {
-	if cfg == nil || len(cfg.Build.Recipes) == 0 {
-		return
-	}
-	const name = "recipe-safety"
-	rc, ok := cfg.Rules[name]
-	if !ok || !rc.Enabled {
+	if cfg == nil {
 		return
 	}
-	if rc.Settings == nil {
-		rc.Settings = make(map[string]any)
+	recipes := serializeRecipes(cfg.Build.Recipes)
+
+	// Inject into recipe-safety (MDS040) with config-path.
+	if rc, ok := cfg.Rules["recipe-safety"]; ok && rc.Enabled {
+		if rc.Settings == nil {
+			rc.Settings = make(map[string]any)
+		}
+		rc.Settings["recipes"] = recipes
+		if cfgPath != "" {
+			rc.Settings["config-path"] = cfgPath
+		}
+		cfg.Rules["recipe-safety"] = rc
 	}
-	// Always overwrite: recipes must come from build:, not user rule settings.
-	rc.Settings["recipes"] = serializeRecipes(cfg.Build.Recipes)
-	if cfgPath != "" {
-		rc.Settings["config-path"] = cfgPath
+
+	// Inject into build directive (MDS039).
+	if rc, ok := cfg.Rules["build"]; ok && rc.Enabled {
+		if rc.Settings == nil {
+			rc.Settings = make(map[string]any)
+		}
+		rc.Settings["recipes"] = recipes
+		cfg.Rules["build"] = rc
 	}
-	cfg.Rules[name] = rc
 }
 
 // serializeRecipes converts RecipeCfg map to map[string]any for transport

internal/config/build_test.go

@@ -173,15 +173,40 @@ func TestInjectBuildConfig_Nil(t *testing.T) {
 	InjectBuildConfig(nil, "")
 }
 
+func TestInjectBuildConfig_EmptyRecipes_ClearsExistingSettings(t *testing.T) {
+	// Even with no build.recipes, InjectBuildConfig must overwrite any
+	// user-supplied recipes setting so rules cannot receive recipes via
+	// rule settings alone.
+	cfg := &Config{
+		Build: BuildConfig{}, // no recipes
+		Rules: map[string]RuleCfg{
+			"build": {
+				Enabled:  true,
+				Settings: map[string]any{"recipes": map[string]any{"sneaky": map[string]any{}}},
+			},
+		},
+	}
+	InjectBuildConfig(cfg, "")
+	rc := cfg.Rules["build"]
+	require.NotNil(t, rc.Settings)
+	recipes, ok := rc.Settings["recipes"].(map[string]any)
+	require.True(t, ok)
+	assert.Empty(t, recipes, "recipes must be cleared when build.recipes is empty")
+}
+
 func TestInjectBuildConfig_NoRecipes(t *testing.T) {
 	cfg := &Config{
 		Rules: map[string]RuleCfg{
 			"recipe-safety": {Enabled: true},
 		},
 	}
 	InjectBuildConfig(cfg, ".mdsmith.yml")
-	// Settings must remain nil/empty — nothing to inject.
-	assert.Nil(t, cfg.Rules["recipe-safety"].Settings)
+	// An empty recipes map is still injected to overwrite any user-supplied settings.
+	rc := cfg.Rules["recipe-safety"]
+	require.NotNil(t, rc.Settings)
+	recipes, ok := rc.Settings["recipes"].(map[string]any)
+	require.True(t, ok)
+	assert.Empty(t, recipes)
 }
 
 func TestInjectBuildConfig_RuleDisabled(t *testing.T) {
@@ -276,6 +301,71 @@ func TestInjectBuildConfig_OverwritesExistingSettings(t *testing.T) {
 	assert.True(t, isMap, "recipes should be overwritten with a map")
 }
 
+func TestInjectBuildConfig_BuildRule(t *testing.T) {
+	cfg := &Config{
+		Build: BuildConfig{
+			Recipes: map[string]RecipeCfg{
+				"render": {
+					Command:      "myrenderer {source} -o {output}",
+					BodyTemplate: "![{alt}]({output})",
+					Params: ParamCfg{
+						Required: []string{"source"},
+						Optional: []string{"output"},
+					},
+				},
+			},
+		},
+		Rules: map[string]RuleCfg{
+			"build": {Enabled: true},
+		},
+	}
+	InjectBuildConfig(cfg, ".mdsmith.yml")
+
+	rc := cfg.Rules["build"]
+	require.NotNil(t, rc.Settings)
+	recipesAny, ok := rc.Settings["recipes"]
+	require.True(t, ok, "recipes key must be present in build rule settings")
+	recipes, ok := recipesAny.(map[string]any)
+	require.True(t, ok)
+	assert.Contains(t, recipes, "render")
+	// config-path must NOT be injected into the build rule (only recipe-safety gets it)
+	_, hasPath := rc.Settings["config-path"]
+	assert.False(t, hasPath)
+}
+
+func TestInjectBuildConfig_BuildRule_NilSettings(t *testing.T) {
+	cfg := &Config{
+		Build: BuildConfig{
+			Recipes: map[string]RecipeCfg{
+				"x": {Command: "tool"},
+			},
+		},
+		Rules: map[string]RuleCfg{
+			"build": {Enabled: true, Settings: nil},
+		},
+	}
+	InjectBuildConfig(cfg, "cfg.yml")
+	rc := cfg.Rules["build"]
+	require.NotNil(t, rc.Settings)
+	_, ok := rc.Settings["recipes"]
+	assert.True(t, ok)
+}
+
+func TestInjectBuildConfig_BuildRule_Disabled(t *testing.T) {
+	cfg := &Config{
+		Build: BuildConfig{
+			Recipes: map[string]RecipeCfg{
+				"x": {Command: "tool"},
+			},
+		},
+		Rules: map[string]RuleCfg{
+			"build": {Enabled: false},
+		},
+	}
+	InjectBuildConfig(cfg, "cfg.yml")
+	assert.Nil(t, cfg.Rules["build"].Settings)
+}
+
 func TestInjectBuildConfig_EmptyCfgPath_NoPathInjected(t *testing.T) {
 	cfg := &Config{
 		Build: BuildConfig{

internal/integration/rules_test.go

@@ -20,6 +20,7 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundfencedcode"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundheadings"
 	_ "github.com/jeduden/mdsmith/internal/rules/blanklinearoundlists"
+	_ "github.com/jeduden/mdsmith/internal/rules/build"
 	_ "github.com/jeduden/mdsmith/internal/rules/catalog"
 	_ "github.com/jeduden/mdsmith/internal/rules/concisenessscoring"
 	_ "github.com/jeduden/mdsmith/internal/rules/crossfilereferenceintegrity"