feat: freeze REQUIRED_FRONTMATTER_FIELDS and add readonly tuple type

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

src/paths.d.mts

@@ -50,8 +50,11 @@ export declare const MIN_CONTENT_LENGTH: number
  */
 export declare const REQUIRED_KEYWORDS: readonly ["agent", "task"]
 
-/** Required fields in YAML frontmatter */
-export declare const REQUIRED_FRONTMATTER_FIELDS: string[]
+/**
+ * Required fields in YAML frontmatter.
+ * Frozen to prevent accidental mutation.
+ */
+export declare const REQUIRED_FRONTMATTER_FIELDS: readonly ["version", "requires"]
 
 /**
  * Get the package root directory from a module's import.meta.url

src/paths.mjs

@@ -56,8 +56,11 @@ export const MIN_CONTENT_LENGTH = 100
  */
 export const REQUIRED_KEYWORDS = ["agent", "task"]
 
-/** Required fields in YAML frontmatter */
-export const REQUIRED_FRONTMATTER_FIELDS = ["version", "requires"]
+/**
+ * Required fields in YAML frontmatter.
+ * Frozen to prevent accidental mutation.
+ */
+export const REQUIRED_FRONTMATTER_FIELDS = Object.freeze(["version", "requires"])
 
 /**
  * Get the package root directory from a module's import.meta.url

tests/paths.test.ts

@@ -571,6 +571,34 @@ This is a test agent that handles various tasks for you.
 				expect(result.error).toContain("version")
 				expect(result.error).toContain("requires")
 			})
+
+			it("should be frozen (immutable)", () => {
+				expect(Object.isFrozen(REQUIRED_FRONTMATTER_FIELDS)).toBe(true)
+			})
+
+			it("should prevent push to REQUIRED_FRONTMATTER_FIELDS", () => {
+				const originalLength = REQUIRED_FRONTMATTER_FIELDS.length
+				expect(() => {
+					;(REQUIRED_FRONTMATTER_FIELDS as unknown as string[]).push("new-field")
+				}).toThrow()
+				expect(REQUIRED_FRONTMATTER_FIELDS.length).toBe(originalLength)
+			})
+
+			it("should prevent modification of REQUIRED_FRONTMATTER_FIELDS elements", () => {
+				const originalFirst = REQUIRED_FRONTMATTER_FIELDS[0]
+				expect(() => {
+					;(REQUIRED_FRONTMATTER_FIELDS as unknown as string[])[0] = "modified"
+				}).toThrow()
+				expect(REQUIRED_FRONTMATTER_FIELDS[0]).toBe(originalFirst)
+			})
+
+			it("should prevent pop from REQUIRED_FRONTMATTER_FIELDS", () => {
+				const originalLength = REQUIRED_FRONTMATTER_FIELDS.length
+				expect(() => {
+					;(REQUIRED_FRONTMATTER_FIELDS as unknown as string[]).pop()
+				}).toThrow()
+				expect(REQUIRED_FRONTMATTER_FIELDS.length).toBe(originalLength)
+			})
 		})
 
 		it("should export TRANSIENT_ERROR_CODES as an array", () => {