fix: address Copilot review comments on yamlutil PR

- Fix broken doc link: docs/security/adversarial-markdown.md →
  docs/security/2026-04-05-adversarial-markdown.md
- convention.go: revert validateConventionScalar to plain
  yaml.Unmarshal; node parsing never expands aliases so
  UnmarshalNodeSafe's alias scan was redundant
- requiredstructure: remove double alias check in front-matter
  path; keep explicit RejectYAMLAliases + yaml.Unmarshal to
  preserve distinct error messages with a single decode pass
- plan/121: correct UnmarshalNodeSafe signature (value not
  pointer), document validateConventionScalar exception and
  front-matter error-message split, fix test-migration note

https://claude.ai/code/session_01WnJMsRhRBvtMHQX1seKaQW

Author: claude

internal/config/convention.go

@@ -7,7 +7,6 @@ import (
 	"gopkg.in/yaml.v3"
 
 	"github.com/jeduden/mdsmith/internal/rules/markdownflavor"
-	"github.com/jeduden/mdsmith/internal/yamlutil"
 )
 
 // applyConvention reads the top-level Convention selector from the
@@ -98,10 +97,11 @@ func copyConventionPreset(p map[string]RuleCfg) map[string]RuleCfg {
 // clean type error. Inspecting the raw node tag is the only way to
 // catch the type mismatch before that coercion happens.
 func validateConventionScalar(data []byte) error {
-	node, err := yamlutil.UnmarshalNodeSafe(data)
-	if err != nil {
-		// A YAML parse error is reported by Load's yaml.Unmarshal
-		// call already; do not double-report.
+	// yaml.Unmarshal into yaml.Node does not expand aliases, so this
+	// is safe without an alias-rejection pre-check. Errors are swallowed
+	// because Load's subsequent UnmarshalSafe call will surface them.
+	var node yaml.Node
+	if err := yaml.Unmarshal(data, &node); err != nil {
 		return nil
 	}
 	if node.Kind != yaml.DocumentNode || len(node.Content) == 0 {

internal/rules/requiredstructure/rule.go

@@ -19,6 +19,7 @@ import (
 	rulesettings "github.com/jeduden/mdsmith/internal/rules/settings"
 	"github.com/jeduden/mdsmith/internal/yamlutil"
 	"github.com/yuin/goldmark/ast"
+	"gopkg.in/yaml.v3"
 )
 
 func init() {
@@ -1089,7 +1090,7 @@ func readDocFrontMatterRaw(f *lint.File) (map[string]any, []lint.Diagnostic) {
 			fmt.Sprintf("front matter: %v", err))}
 	}
 	var raw map[string]any
-	if err := yamlutil.UnmarshalSafe(yamlBytes, &raw); err != nil {
+	if err := yaml.Unmarshal(yamlBytes, &raw); err != nil {
 		return nil, []lint.Diagnostic{makeDiag(f.Path, 1,
 			fmt.Sprintf("front matter: invalid YAML: %v", err))}
 	}

internal/yamlutil/yamlutil.go

@@ -13,7 +13,7 @@
 //   - [Marshal] — thin wrapper around yaml.Marshal for consistency; safe for
 //     output marshaling where data originates from trusted Go values.
 //
-// See docs/security/adversarial-markdown.md for threat model context.
+// See docs/security/2026-04-05-adversarial-markdown.md for threat model context.
 package yamlutil
 
 import (

plan/121_yaml-handling-review.md

@@ -82,7 +82,7 @@ File: `internal/corpus/config.go`
 
   - `UnmarshalSafe(data []byte, v any) error` — combines
      alias rejection + unmarshal
-  - `UnmarshalNodeSafe(data []byte) (*yaml.Node, error)` —
+  - `UnmarshalNodeSafe(data []byte) (yaml.Node, error)` —
      for node-based parsing
   - `Marshal(v any) ([]byte, error)` — thin wrapper for
      consistency
@@ -92,13 +92,16 @@ File: `internal/corpus/config.go`
 2. Update all 13+ `yaml.Unmarshal` call sites to use
    `yamlutil.UnmarshalSafe`:
 
-  - `internal/config/load.go` (3 sites: load, topLevelKeySet,
-     validateConventionScalar)
+  - `internal/config/load.go` (2 sites: load, topLevelKeySet;
+     validateConventionScalar uses plain yaml.Unmarshal since
+     node parsing does not expand aliases)
   - `internal/lint/frontmatter.go` (1 site)
   - `internal/archetype/gensection/parse.go` (1 site)
   - `internal/rules/catalog/rule.go` (1 site)
-  - `internal/rules/requiredstructure/rule.go` (4 sites:
-     require, include, schema, allow-empty-section)
+  - `internal/rules/requiredstructure/rule.go` (3 sites via
+     UnmarshalSafe: require, include, schema; front-matter
+     read uses explicit RejectYAMLAliases + yaml.Unmarshal
+     to preserve distinct error messages per error type)
   - `internal/corpus/config.go` (2 sites)
   - `cmd/mdsmith/main.go` (check if front-matter parsing
      needs update)
@@ -121,8 +124,10 @@ File: `internal/corpus/config.go`
 
 6. Update tests:
 
-  - Move `yamlsafe_test.go` to `yamlutil_test.go`
-  - Add tests for new wrapper functions
+  - Add `internal/yamlutil/yamlutil_test.go` with tests for
+    new wrapper functions and alias rejection
+  - Repurpose `internal/lint/yamlsafe_test.go` to verify
+    alias rejection through the front-matter parsing path
   - Ensure coverage of error paths
 
 7. Run full test suite: `go test ./...`