fix(review): address review 2792 feedback

- Document nodeCount overcounting as intentional conservative behavior
  (bounds total validation work, not unique nodes)
- Improve TestYAMLDeeplyNestedRejection comment with concrete depth trace
- Replace outdated gopkg.in/yaml.v3 pseudocode in design doc with
  reference to authoritative implementation
- Update PR description to clarify pre-approval via issue #57

review/persona.go

@@ -224,7 +224,11 @@ func checkYAMLDepth(node ast.Node, depth, maxDepth, maxNodes int, validated map[
 	}
 
 	// Track total nodes visited as defense-in-depth against wide-but-shallow attacks.
-	// Placed after cycle detection to avoid over-counting cyclic references.
+	// Placed after cycle detection but before the depth-aware short-circuit. This means
+	// nodes revisited at shallower depths (via aliases) are counted each time they are
+	// encountered — intentional conservative overcounting. This bounds the total work
+	// performed during validation rather than tracking unique nodes, which is the safer
+	// security posture for untrusted YAML input.
 	*nodeCount++
 	if *nodeCount > maxNodes {
 		return fmt.Errorf("YAML node count exceeds maximum (%d)", maxNodes)

review/persona_test.go

@@ -459,8 +459,13 @@ func TestYAMLDeeplyNestedRejection(t *testing.T) {
 	path := filepath.Join(dir, "deeply-nested.yaml")
 
 	// Build a deeply nested YAML structure that exceeds MaxYAMLDepth (20).
-	// Each nested mapping key generates a MappingValueNode, incrementing depth
-	// by 1 per level in the AST walk. With 25 levels, we exceed MaxYAMLDepth (20).
+	// Depth accumulation trace for "nested: \n  level0: \n    level1: ...":
+	//   - Document root parsed at depth 0
+	//   - Root MappingNode children (MappingValueNodes) visited at depth 1
+	//   - "nested" MappingValueNode: key at depth 2, value at depth 2
+	//   - Each levelN mapping adds +1 depth (MappingNode → MappingValueNode → value)
+	//   - After 25 levels: effective depth reaches ~27, well past MaxYAMLDepth (20)
+	// The test uses 25 levels to provide a comfortable margin above the limit.
 	var sb strings.Builder
 	sb.WriteString("name: test\nidentity: test\nnested:\n")
 	indent := "  "