From e835a78ba739fffb796d75022d56ffc09ed2171e Mon Sep 17 00:00:00 2001
From: Pablo LION <dev@pablolion.com>
Date: Sun, 8 Feb 2026 21:37:47 +0100
Subject: [PATCH] fix: enforce array type for agent principles in schema

Remove string option from principles union type. The template defines
principles as an array (principles: []) and all agent files should use
array format. Block scalar strings that look like lists are a common
source of type confusion.

Adds test fixture for string-format principles (now invalid).

Closes #1594

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../persona/string-principles.agent.yaml      | 26 +++++++++++++++++++
 tools/schema/agent.js                         |  9 +++----
 2 files changed, 29 insertions(+), 6 deletions(-)
 create mode 100644 test/fixtures/agent-schema/invalid/persona/string-principles.agent.yaml

diff --git a/test/fixtures/agent-schema/invalid/persona/string-principles.agent.yaml b/test/fixtures/agent-schema/invalid/persona/string-principles.agent.yaml
new file mode 100644
index 000000000..e03fb3cd5
--- /dev/null
+++ b/test/fixtures/agent-schema/invalid/persona/string-principles.agent.yaml
@@ -0,0 +1,26 @@
+# Test: Principles as block scalar string instead of array
+# Expected: FAIL
+# Error path: agent.persona.principles
+# Error expected: array
+# Error received: string
+
+agent:
+  metadata:
+    id: string-principles
+    name: String Principles
+    title: String Principles
+    icon: ❌
+    hasSidecar: false
+
+  persona:
+    role: Test agent
+    identity: Test identity
+    communication_style: Test style
+    principles: |
+      - This is a string, not an array
+      - Each line is part of one string
+
+  menu:
+    - trigger: help
+      description: Show help
+      action: display_help
diff --git a/tools/schema/agent.js b/tools/schema/agent.js
index b6a36a985..c373286db 100644
--- a/tools/schema/agent.js
+++ b/tools/schema/agent.js
@@ -240,12 +240,9 @@ function buildPersonaSchema() {
       role: createNonEmptyString('agent.persona.role'),
       identity: createNonEmptyString('agent.persona.identity'),
       communication_style: createNonEmptyString('agent.persona.communication_style'),
-      principles: z.union([
-        createNonEmptyString('agent.persona.principles'),
-        z
-          .array(createNonEmptyString('agent.persona.principles[]'))
-          .min(1, { message: 'agent.persona.principles must include at least one entry' }),
-      ]),
+      principles: z
+        .array(createNonEmptyString('agent.persona.principles[]'))
+        .min(1, { message: 'agent.persona.principles must include at least one entry' }),
     })
     .strict();
 }