fix(persona-kit): tags optional + free-form per cloud#553 schema (#114)

* fix(persona-kit): make tags optional + free-form per cloud#553 schema

parseTags rejected free-form strings (only accepted intent-enum values) AND
required the field to be present + non-empty. Both are wrong per the schema
in cloud#553 (`tags text[]` — denorm metadata, not a closed enum).

This broke the canonical reference persona (examples/notion-essay-pr) whose
tags are ['proactive', 'notion', 'github'] — none of which are in the intent
enum. First customer (proactive-agents) hit it deploying today.

- parseTags returns undefined when tags is missing/null/empty
- accepts any string[] with 1..64-char entries, deduped+sorted
- removes the closed-enum constraint
- widens PersonaSpec.tags to readonly string[] (optional)
- regenerates persona.schema.json with the new shape
  (tags items: { type: string, minLength: 1, maxLength: 64 }; tags
   dropped from `required`; PersonaTag enum definition removed)
- emit-schema.mjs gains a post-process for tags-items bounds matching
  the existing tightenWorkspaceServiceAccountName pattern
- cli list/show + local-personas accept any string tag; --filter-tag is
  free-form with built-in tags surfaced as a hint
- tests cover all the optional/free-form/validation paths

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(cli): normalize free-form persona tags

* test(deploy): satisfy persona fixture typing

* test(deploy): fix cloud deployUrl fixture typing

* test(deploy): widen cloud fixture override type

* fix(deploy/cli): satisfy strict typing on cloud test fixture; harden parseOverride null path

- packages/deploy/src/modes/cloud.test.ts: route the PersonaSpec<->{cloud:{deployUrl}} casts through `unknown` at the construct site and at all three deployedUrl(...) call sites so TS no longer rejects the bidirectional conversion (CI typecheck blocker).
- packages/cli/src/local-personas.ts: omit `tags` from the parseOverride return object when no tags were provided, instead of returning `tags: undefined`. Combined with the existing `raw.tags === null` guard, this guarantees `LocalPersonaOverride.tags` is either a trimmed/deduped/sorted PersonaTag[] or absent — never null at runtime, never an empty array, never an explicit-undefined key. Addresses Devin BUG_0002.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Ricky Schema Cascade <ricky@agent-relay.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Miya <khaliqgant+miya@gmail.com>

Author: 4 people

packages/cli/src/cli.ts

@@ -154,7 +154,7 @@ Commands:
                         --filter-harness <harness>    only show this harness
                                                       (${HARNESS_VALUES.join(' | ')})
                         --filter-tag <tag>            only show personas carrying this tag
-                                                      (${PERSONA_TAGS.join(' | ')})
+                                                      (free-form; common built-in tags: ${PERSONA_TAGS.join(' | ')})
                         --no-display-description      hide the DESCRIPTION column
   show <persona>      Print the fully-resolved spec for a single persona,
                       including which cascade layer defined it (cwd, user,
@@ -2010,7 +2010,7 @@ interface PersonaListRow {
   harness: string;
   model: string;
   intent: string;
-  tags: PersonaTag[];
+  tags: readonly PersonaTag[];
   description: string;
 }
 
@@ -2023,7 +2023,7 @@ function collectPersonaRows(): PersonaListRow[] {
       harness: spec.harness,
       model: spec.model,
       intent: spec.intent,
-      tags: spec.tags,
+      tags: spec.tags ?? [],
       description: spec.description
     });
   };
@@ -2146,10 +2146,11 @@ function parseListArgs(args: readonly string[]): {
       filterHarness = v as Harness;
     } else if (arg === '--filter-tag') {
       const v = valueOf(i++, arg);
-      if (!(PERSONA_TAGS as readonly string[]).includes(v)) {
-        die(`list: invalid --filter-tag "${v}". Must be one of: ${PERSONA_TAGS.join(', ')}`);
+      const trimmed = v.trim();
+      if (!trimmed) {
+        die('list: --filter-tag requires a non-empty value.');
       }
-      filterTag = v as PersonaTag;
+      filterTag = trimmed as PersonaTag;
     } else if (arg === '--display-description') {
       display.description = true;
     } else if (arg === '--no-display-description') {
@@ -2254,7 +2255,7 @@ function formatPersonaShow(spec: PersonaSpec, source: PersonaSource): string {
   lines.push(`PERSONA      ${spec.id}`);
   lines.push(`SOURCE       ${source}`);
   lines.push(`INTENT       ${spec.intent}`);
-  lines.push(`TAGS         ${spec.tags.length ? spec.tags.join(', ') : '(none)'}`);
+  lines.push(`TAGS         ${spec.tags && spec.tags.length ? spec.tags.join(', ') : '(none)'}`);
   lines.push(`DESCRIPTION  ${spec.description}`);
 
   lines.push('');
@@ -3593,15 +3594,15 @@ export function buildPickCandidates(): PickCandidate[] {
     byId.set(spec.id, {
       id: spec.id,
       intent: spec.intent,
-      tags: [...spec.tags],
+      tags: spec.tags ? [...spec.tags] : [],
       description: spec.description
     });
   }
   for (const [id, spec] of local.byId.entries()) {
     byId.set(id, {
       id,
       intent: spec.intent,
-      tags: [...spec.tags],
+      tags: spec.tags ? [...spec.tags] : [],
       description: spec.description
     });
   }

packages/cli/src/local-personas.ts

@@ -6,7 +6,6 @@ import {
   CODEX_APPROVAL_POLICIES,
   CODEX_SANDBOX_MODES,
   HARNESS_VALUES,
-  PERSONA_TAGS,
   SIDECAR_MD_MODES,
   type CodexApprovalPolicy,
   type CodexSandboxMode,
@@ -423,16 +422,24 @@ function parseOverride(value: unknown, context: string): LocalPersonaOverride {
   if (raw.description !== undefined && typeof raw.description !== 'string') {
     throw new Error(`${context}.description must be a string if provided`);
   }
-  if (raw.tags !== undefined) {
-    if (!Array.isArray(raw.tags) || raw.tags.length === 0) {
-      throw new Error(`${context}.tags must be a non-empty array of tags if provided`);
+  let normalizedTags: PersonaTag[] | undefined;
+  if (raw.tags !== undefined && raw.tags !== null) {
+    if (!Array.isArray(raw.tags)) {
+      throw new Error(`${context}.tags must be an array of strings if provided`);
     }
+    const tags = new Set<string>();
     for (const [idx, tag] of raw.tags.entries()) {
-      if (!PERSONA_TAGS.includes(tag as PersonaTag)) {
-        throw new Error(
-          `${context}.tags[${idx}] must be one of: ${PERSONA_TAGS.join(', ')}`
-        );
+      if (typeof tag !== 'string' || !tag.trim()) {
+        throw new Error(`${context}.tags[${idx}] must be a non-empty string`);
       }
+      const trimmed = tag.trim();
+      if (trimmed.length > 64) {
+        throw new Error(`${context}.tags[${idx}] must be ≤64 characters`);
+      }
+      tags.add(trimmed);
+    }
+    if (tags.size > 0) {
+      normalizedTags = Array.from(tags).sort() as PersonaTag[];
     }
   }
 
@@ -489,7 +496,7 @@ function parseOverride(value: unknown, context: string): LocalPersonaOverride {
     id: raw.id,
     extends: raw.extends as string | undefined,
     intent: raw.intent as string | undefined,
-    tags: raw.tags as PersonaTag[] | undefined,
+    ...(normalizedTags !== undefined ? { tags: normalizedTags } : {}),
     description: raw.description as string | undefined,
     skills: raw.skills as PersonaSpec['skills'] | undefined,
     inputs,
@@ -804,7 +811,8 @@ function standaloneSpecFromOverride(
   return {
     id: override.id,
     intent: override.intent,
-    tags: requireStandaloneField(override.tags, `${context}.tags`),
+    // Tags are optional per cloud#553 (denormalized catalog metadata).
+    ...(override.tags ? { tags: override.tags } : {}),
     description: requireStandaloneField(override.description, `${context}.description`),
     skills: override.skills ?? [],
     ...(inputs ? { inputs } : {}),
@@ -1009,10 +1017,11 @@ function mergeOverride(
   const claudeMdMode = override.claudeMdMode ?? base.claudeMdMode;
   const agentsMdMode = override.agentsMdMode ?? base.agentsMdMode;
 
+  const mergedTags = override.tags ?? base.tags;
   return {
     id: override.id,
     intent: base.intent,
-    tags: override.tags ?? base.tags,
+    ...(mergedTags ? { tags: mergedTags } : {}),
     description: override.description ?? base.description,
     skills: override.skills ?? base.skills,
     ...(inputs ? { inputs } : {}),

packages/deploy/src/modes/cloud.test.ts

@@ -31,12 +31,13 @@ const ENV_KEYS = [
   'WORKFORCE_DEPLOY_RETRY_BACKOFF_MS'
 ] as const;
 
-function persona(overrides: Record<string, unknown> = {}): PersonaSpec {
+function persona(overrides: Partial<PersonaSpec> = {}): PersonaSpec {
   return {
     id: 'demo',
     intent: 'documentation',
-    tags: ['documentation'],
+    tags: ['documentation'] as const,
     description: 'test persona',
+    skills: [],
     harness: 'codex',
     model: 'openai-codex/test',
     systemPrompt: 'help',
@@ -45,7 +46,7 @@ function persona(overrides: Record<string, unknown> = {}): PersonaSpec {
     schedules: [{ name: 'daily', cron: '0 9 * * *' }],
     onEvent: './agent.ts',
     ...overrides
-  } as PersonaSpec;
+  };
 }
 
 async function withBundle(): Promise<{ bundle: BundleResult; cleanup: () => Promise<void> }> {
@@ -200,20 +201,21 @@ test('cloud URL precedence is flag env, cloud env, persona deployUrl, then defau
     return calls.find((call) => call.url.endsWith('/deployments'))?.url;
   }
 
-  const personaWithUrl = persona({ cloud: { deployUrl: 'https://persona.example.test/' } as unknown });
+  const personaWithUrl = persona() as unknown as Omit<PersonaSpec, 'cloud'> & { cloud: { deployUrl: string } };
+  personaWithUrl.cloud = { deployUrl: 'https://persona.example.test/' };
   assert.equal(
     await deployedUrl({
       WORKFORCE_DEPLOY_CLOUD_URL: 'https://flag.example.test/',
       WORKFORCE_CLOUD_URL: 'https://env.example.test/'
-    }, personaWithUrl),
+    }, personaWithUrl as unknown as PersonaSpec),
     'https://flag.example.test/api/v1/workspaces/ws-test/deployments'
   );
   assert.equal(
-    await deployedUrl({ WORKFORCE_CLOUD_URL: 'https://env.example.test/' }, personaWithUrl),
+    await deployedUrl({ WORKFORCE_CLOUD_URL: 'https://env.example.test/' }, personaWithUrl as unknown as PersonaSpec),
     'https://env.example.test/api/v1/workspaces/ws-test/deployments'
   );
   assert.equal(
-    await deployedUrl({}, personaWithUrl),
+    await deployedUrl({}, personaWithUrl as unknown as PersonaSpec),
     'https://persona.example.test/api/v1/workspaces/ws-test/deployments'
   );
   assert.equal(

packages/persona-kit/schemas/persona.schema.json

@@ -14,9 +14,11 @@
         "tags": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/PersonaTag"
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
           },
-          "description": "Free-form classification labels (from  {@link  PERSONA_TAGS } ). Every persona has at least one; a persona may carry multiple tags when it spans concerns (e.g. `['testing', 'implementation']`)."
+          "description": "Free-form catalog labels mirroring `tags text[]` in cloud#553. Tags are denormalized metadata for catalog filtering — they are NOT a closed enum and do NOT overlap with  {@link  intent } . Authors are free to label personas with provider names, project codes, or workflow shapes (e.g. `['proactive', 'notion', 'github']`). Optional; omitted, `null`, and empty-array values are treated identically."
         },
         "description": {
           "type": "string"
@@ -130,7 +132,6 @@
       "required": [
         "id",
         "intent",
-        "tags",
         "description",
         "skills",
         "harness",
@@ -160,20 +161,6 @@
         }
       ]
     },
-    "PersonaTag": {
-      "type": "string",
-      "enum": [
-        "planning",
-        "implementation",
-        "review",
-        "testing",
-        "debugging",
-        "documentation",
-        "release",
-        "discovery",
-        "analytics"
-      ]
-    },
     "PersonaSkill": {
       "type": "object",
       "properties": {

packages/persona-kit/scripts/emit-schema.mjs

@@ -80,6 +80,26 @@ function tightenWorkspaceServiceAccountName(node) {
 }
 tightenWorkspaceServiceAccountName(schema);
 
+// Post-process: tighten the persona `tags[]` items to match parseTags
+// (non-empty, ≤64 chars). The TS type widens to `readonly string[]` after
+// cloud#553 — the generator emits a bare `{ "type": "string" }` because
+// the bounds live in the parser. Without this, the schema accepts empty
+// or 1MB tag strings that the parser would then reject. Match the
+// `tightenWorkspaceServiceAccountName` post-process pattern above.
+const PERSONA_TAG_MAX_LEN = 64;
+const personaSpecForTags = schema.definitions?.PersonaSpec;
+if (
+  personaSpecForTags &&
+  personaSpecForTags.properties?.tags?.type === 'array' &&
+  personaSpecForTags.properties.tags.items?.type === 'string'
+) {
+  personaSpecForTags.properties.tags.items = {
+    ...personaSpecForTags.properties.tags.items,
+    minLength: 1,
+    maxLength: PERSONA_TAG_MAX_LEN
+  };
+}
+
 const serialized = `${JSON.stringify(schema, null, 2)}\n`;
 await mkdir(dirname(schemaPath), { recursive: true });
 

packages/persona-kit/src/constants.ts

@@ -1,6 +1,11 @@
 import type { Harness, HarnessSkillTarget } from './types.js';
 
 export const HARNESS_VALUES = ['opencode', 'codex', 'claude'] as const;
+/**
+ * Suggested persona tags used by built-in personas. Tags are free-form
+ * (`tags text[]` in cloud#553) — this tuple is kept only as a UX hint for
+ * built-in catalog filtering. New personas may use any string.
+ */
 export const PERSONA_TAGS = [
   'planning',
   'implementation',

packages/persona-kit/src/parse.test.ts

@@ -325,9 +325,70 @@ test('parseHarnessSettings rejects non-boolean dangerouslyBypassApprovalsAndSand
   );
 });
 
-test('parseTags rejects empty arrays and unknown tags', () => {
-  assert.throws(() => parseTags([], 'tags'), /must be a non-empty array/);
-  assert.throws(() => parseTags(['nonsense-tag'], 'tags'), /tags\[0\] must be one of:/);
+test('parseTags accepts an array of arbitrary string tags', () => {
+  // Free-form per cloud#553 `tags text[]` — no closed-enum check.
+  // Output is deduped and sorted for stable serialization.
+  assert.deepEqual(
+    parseTags(['proactive', 'notion', 'github'], 'tags'),
+    ['github', 'notion', 'proactive']
+  );
+});
+
+test('parseTags returns undefined when tags is missing', () => {
+  assert.equal(parseTags(undefined, 'tags'), undefined);
+});
+
+test('parseTags returns undefined when tags is null', () => {
+  assert.equal(parseTags(null, 'tags'), undefined);
+});
+
+test('parseTags returns undefined when tags is an empty array', () => {
+  // Empty array and "no tags" are semantically identical — both collapse
+  // to undefined so the field stays omitted from the parsed spec.
+  assert.equal(parseTags([], 'tags'), undefined);
+});
+
+test('parseTags rejects non-string entries', () => {
+  assert.throws(
+    () => parseTags(['proactive', 123], 'tags'),
+    /tags\[1\] must be a string/
+  );
+});
+
+test('parseTags rejects empty / whitespace-only strings', () => {
+  assert.throws(
+    () => parseTags(['proactive', '   '], 'tags'),
+    /tags\[1\] must be a non-empty string/
+  );
+  assert.throws(
+    () => parseTags([''], 'tags'),
+    /tags\[0\] must be a non-empty string/
+  );
+});
+
+test('parseTags rejects entries over 64 characters', () => {
+  const tooLong = 'x'.repeat(65);
+  assert.throws(
+    () => parseTags(['proactive', tooLong], 'tags'),
+    /tags\[1\] must be ≤64 characters/
+  );
+});
+
+test('parseTags rejects non-array input', () => {
+  assert.throws(
+    () => parseTags('proactive', 'tags'),
+    /tags must be an array of strings if provided/
+  );
+});
+
+test('parsePersonaSpec omits tags from the spec when the field is missing', () => {
+  // Tags are optional; the parsed spec should not synthesize an empty array
+  // when the input omits the field — the schema treats absence and `[]`
+  // identically per cloud#553's denormalized `tags text[]`.
+  const raw = { ...validSpec() } as Record<string, unknown>;
+  delete raw.tags;
+  const spec = parsePersonaSpec(raw, 'documentation');
+  assert.equal(spec.tags, undefined);
 });
 
 test('parseSkills returns [] for undefined, validates shape per entry', () => {