@personaxis/spec 0.11.0

package/schema/policy.schema.json

@@ -0,0 +1,192 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://personaxis.com/schemas/persona/0.10/policy.schema.json",
+  "title": "policy.yaml v0.10",
+  "description": "Schema for the sibling policy.yaml file that lives next to personaxis.md inside .personaxis/[personas/<slug>/]. Encodes the operational policy the Personaxis platform enforces over a persona-version: behavioral assertions, runtime constraints, evaluation suites, and improvement_policy (mutation governance). policy.yaml is consumed by the Personaxis backend and dashboard; it is NEVER inlined into an LLM system prompt. v0.7 is a layout-only change (moved from repo-root to .personaxis/); v0.6 introduced the autonomous mode and explicit scope allowlist/blocklist for spec self-edits.",
+  "type": "object",
+  "required": ["spec_version", "applies_to", "improvement_policy"],
+  "additionalProperties": false,
+  "properties": {
+    "spec_version": {
+      "type": "string",
+      "enum": ["1.0.0", "0.10.0", "0.9.0", "0.8.0", "0.7.0", "0.6.0", "0.5.0"],
+      "description": "Schema version, forward-compatible with the spec minors (policy.yaml has had no field changes since 0.6.0; 0.7.0 was layout-only). Accepts 0.6.0-0.10.0; 0.5.0 accepted for backward compatibility (auto-migrated)."
+    },
+    "applies_to": {
+      "type": "object",
+      "required": ["persona_name"],
+      "additionalProperties": false,
+      "description": "Reference to the personaxis.md this policy governs. Lets a registry hold multiple policy.yaml siblings for different version ranges of the same persona (rare, but supported).",
+      "properties": {
+        "persona_name": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]*$",
+          "description": "Must match the metadata.name of the personaxis.md in the same directory."
+        },
+        "persona_version_range": {
+          "type": "string",
+          "description": "Optional semver range (e.g. '>=1.0.0 <2.0.0'). When omitted, policy applies to all versions of the persona. Validator rejects when two policy.yaml files in the same registry have overlapping ranges for the same persona_name."
+        }
+      }
+    },
+    "improvement_policy": {
+      "type": "object",
+      "required": ["mode"],
+      "additionalProperties": false,
+      "description": "Mutation governance. Controls whether the Personaxis platform may suggest or apply changes to the persona-version based on observed drift. Default mode 'locked' is the only safe choice for production-critical personas.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["locked", "suggesting", "autonomous", "auto"],
+          "description": "locked (default; safest): PERSONA.md is immutable at runtime. state.json mutations within envelopes are still allowed. Drift alerts only. suggesting: actor MAY call propose_self_edit; proposals queued in dashboard for human approval; approval mints a new PersonaVersion. autonomous (high-risk): actor MAY call apply_self_edit directly; each applied edit creates a new PersonaVersion. Bound by universal invariants, governance.per_layer_edit_policy, hard_limits, and autonomous_scope_allowlist/blocklist. 'auto' is a deprecated alias for 'autonomous' (v0.5 compatibility)."
+        },
+        "autonomous_scope_allowlist": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Dot-notation paths the actor MAY auto-edit when mode='autonomous'. Wildcards allowed (e.g., 'persona.task_modes.*'). Required when mode='autonomous'."
+        },
+        "autonomous_scope_blocklist": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Dot-notation paths always blocked, even when mode='autonomous'. Wildcards allowed. Recommended to always include identity.*, character.virtues.*.enforcement, reflexive_self_regulation.*, values_and_drives.values.safety.*, governance.*, security.*."
+        },
+        "approved_by": {
+          "type": "string",
+          "description": "User id or org id that authorized non-locked modes. Required by validator when mode != 'locked'."
+        },
+        "last_approval_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp of the last human approval for non-locked modes. Required by validator when mode != 'locked'."
+        },
+        "approval_expires_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Optional. If set, the platform reverts mode to 'locked' automatically after this timestamp. Encourages re-affirmation rather than indefinite consent."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "mode": { "enum": ["suggesting", "autonomous", "auto"] } }
+          },
+          "then": {
+            "required": ["mode", "approved_by", "last_approval_at"]
+          }
+        },
+        {
+          "if": {
+            "properties": { "mode": { "enum": ["autonomous", "auto"] } }
+          },
+          "then": {
+            "required": ["mode", "approved_by", "last_approval_at", "autonomous_scope_allowlist"]
+          }
+        }
+      ]
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Runtime constraints declared by the spec author. Consumed by the Personaxis runtime and observability layer; opaque to the LLM actor.",
+      "properties": {
+        "min_consistency": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Drift status becomes 'regressed' if a layer's consistencyScore falls below this floor. Default 0.7 when omitted."
+        },
+        "drift_alert_channels": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(slack|email|webhook|linear|pagerduty):"
+          },
+          "description": "Channel URIs (e.g. 'slack:#observability', 'webhook:https://...'). Resolved by the Personaxis dashboard, not by the spec runtime."
+        },
+        "allowed_consumers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["agent", "human", "mcp"]
+          },
+          "description": "Who may open a runtime session against this persona. Defaults to all three when omitted."
+        },
+        "compiled_prompt_cache_ttl_seconds": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Hint for the compiler's prompt-cache TTL (seconds). The compiler keys cached compiled prompts by (spec_hash, state_hash, context_hash). Default 300s. New in v0.6."
+        }
+      }
+    },
+    "evaluation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Higher-order eval suites the persona-version must satisfy. Distinct from per-trace 'assertions': evaluation suites are batch runs over canonical prompt datasets (CI/CD gating, see Phase 2).",
+      "properties": {
+        "required_suites": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Named suites that must be present and passing for the version to be considered shippable. Suite definitions live in the registry."
+        }
+      }
+    },
+    "assertions": {
+      "type": "array",
+      "description": "Behavioral expectations evaluated at runtime by the Personaxis observability layer. Each assertion declares which spec layer it covers and how it is checked. The judge worker reads this block directly from the registry; it is NEVER inlined into the LLM system prompt.",
+      "items": {
+        "type": "object",
+        "required": ["layer", "name", "type", "definition", "severity"],
+        "additionalProperties": false,
+        "properties": {
+          "layer": {
+            "type": "string",
+            "enum": [
+              "identity",
+              "character",
+              "personality",
+              "values_and_drives",
+              "values_drives",
+              "affect",
+              "cognition",
+              "memory",
+              "metacognition",
+              "reflexive_self_regulation",
+              "persona",
+              "cross_layer"
+            ],
+            "description": "One of the 10 canonical personaxis.md layers. The v0.6 canonical name for Layer 4 is 'values_and_drives'; 'values_drives' is accepted for backward compatibility with v0.5 policies. 'cross_layer' is for assertions that span multiple layers."
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120,
+            "description": "Human-readable label shown in the dashboard."
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 1000
+          },
+          "type": {
+            "type": "string",
+            "enum": ["regex", "semantic", "llm_judge", "activation_projection"],
+            "description": "Evaluation strategy. v0.5 runtime supports 'regex' and 'llm_judge' fully; 'semantic' and 'activation_projection' are reserved (no-op pass at evaluation time)."
+          },
+          "definition": {
+            "type": "object",
+            "description": "Type-specific configuration. Schema by type is documented in docs/personaxis-docs/architecture/observability-model.mdx.",
+            "additionalProperties": true
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["info", "warn", "block"],
+            "description": "Drift weight: info=0.5, warn=1.0, block=2.0."
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Defaults to true. Set false to retain the assertion in policy.yaml but skip evaluation."
+          }
+        }
+      }
+    }
+  }
+}

package/schema/state.schema.json

@@ -0,0 +1,150 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://personaxis.com/schemas/state/1.0/state.schema.json",
+  "title": "state.json v1.0",
+  "description": "Mutable runtime state of an AI Persona. Sibling of personaxis.md inside .personaxis/[personas/<slug>/]. Holds current trait/affect/mood values, active context, and the mutation log. Mutations occur via the canonical adjust_persona_state tool, clamped to envelopes declared in personaxis.md. State mutations DO NOT modify personaxis.md or the compiled PERSONA.md/<slug>.md; they are operational, not spec edits. v1.0 (D4): the mutable surface is EXACTLY the set of fields that declare a {mean, range} envelope in personaxis.md; values keys are FULL dot-paths into the spec; and state.json is a CHECKPOINT derived from mutation_log — a conforming runtime can rebuild values by replaying the log from the envelope means.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "persona_id",
+    "persona_version",
+    "values"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "enum": ["1.0.0", "0.9.0", "0.8.0", "0.7.0", "0.6.0"],
+      "description": "state.json schema version. 1.0.0 is current (values keys are full dot-paths; state is a replayable checkpoint of mutation_log). 0.x accepted during the 1.x read-compat window."
+    },
+    "persona_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]*$",
+      "description": "Must match metadata.name in personaxis.md."
+    },
+    "persona_version": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$",
+      "description": "Must match metadata.version in personaxis.md at compile time. Used by the compiler to detect spec/state mismatch."
+    },
+    "session_id": {
+      "type": "string",
+      "description": "Optional session identifier. Useful when state is per-session rather than persisted across sessions."
+    },
+    "values": {
+      "type": "object",
+      "description": "Current values for all mutable fields. v1.0: keys are FULL dot-notation paths into personaxis.md ('personality.traits.openness', 'affect.baseline.core_affect.valence', 'affect.baseline.mood.tone', 'values_and_drives.drives.complete_task') and the key set is exactly the fields that declare a {mean, range} envelope. The short ≤0.10 forms ('traits.openness', 'affect.valence', 'mood.tone', 'drives.x') are legacy; conforming runtimes accept them as read-aliases during the 1.x window (the CLI's `migrate 0.10-to-1.0` renames them). Each value is a number that must lie within the envelope declared at the corresponding path; the runtime clamps any out-of-envelope value at mutation time.",
+      "additionalProperties": {
+        "type": "number"
+      }
+    },
+    "active_context": {
+      "type": "object",
+      "description": "Current contextual selectors that drive cold-slice injection in the compiled prompt.",
+      "additionalProperties": false,
+      "properties": {
+        "task_mode": {
+          "type": ["string", "null"],
+          "description": "Active task mode key. Must match a key in persona.task_modes, or null when no specific task is detected."
+        },
+        "audience": {
+          "type": ["string", "null"],
+          "description": "Active audience key. Must match a key in persona.audience_adaptation, or null when audience is undetermined."
+        },
+        "additional_context_flags": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Per-persona context flags (e.g., 'high_pressure', 'creative_review'). Used by the compiler to optionally inject extra cold slices."
+        }
+      }
+    },
+    "memory_anchors_active": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of active memory anchor IDs. The compiler uses these to inject high-priority memory references into the compiled prompt. Maintained by the runtime via retrieval policies."
+    },
+    "mutation_log": {
+      "type": "array",
+      "description": "Append-only log of every state mutation. Provides audit trail. The runtime trims old entries based on retention policy.",
+      "items": {
+        "type": "object",
+        "required": ["ts", "field", "from", "to", "actor"],
+        "additionalProperties": false,
+        "properties": {
+          "ts": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp of the mutation."
+          },
+          "field": {
+            "type": "string",
+            "description": "Dot-notation path of the mutated field (matches a key in values)."
+          },
+          "from": {
+            "type": "number",
+            "description": "Previous value."
+          },
+          "to": {
+            "type": "number",
+            "description": "New value (post-clamp)."
+          },
+          "delta_requested": {
+            "type": "number",
+            "description": "Original delta requested. May differ from (to - from) if clamping occurred."
+          },
+          "clamped": {
+            "type": "boolean",
+            "description": "True if the requested mutation was clamped to envelope. The actor receives clamped=true to signal the floor/ceiling was reached."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Human-readable rationale for the mutation."
+          },
+          "actor": {
+            "type": "string",
+            "enum": ["actor-llm", "runtime-decay", "runtime-context", "human-operator", "judge-correction"],
+            "description": "Which subsystem triggered the mutation."
+          },
+          "tool_call_id": {
+            "type": "string",
+            "description": "ID of the adjust_persona_state tool call that produced this mutation, if applicable."
+          },
+          "governance_blocked": {
+            "type": "boolean",
+            "description": "True if the mutation was rejected by governance (e.g., hard-enforced virtue, hard limit, scope blocklist). When true, from === to and reason explains the block."
+          },
+          "origin_node": {
+            "type": "string",
+            "description": "v0.8: stable id of the machine/instance that produced this mutation. Makes cross-OS reconciliation of a portable persona deterministic (last-writer-wins per field across machines)."
+          },
+          "session_id": {
+            "type": "string",
+            "description": "v0.8: id of the runtime session that produced this mutation, for traceability."
+          }
+        }
+      }
+    },
+    "last_compiled_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp of the last compilation that consumed this state. Used by cache invalidation."
+    },
+    "last_compiled_hash": {
+      "type": "string",
+      "description": "Hash of the inputs that produced the last compiled prompt. Used by cache invalidation."
+    },
+    "agent_session": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "v0.9: live agent-loop session tracking. Lets a task resume across runs and records budget spend + why the loop stopped.",
+      "properties": {
+        "active_task": { "type": ["string", "null"], "description": "The task currently being executed, or null when idle." },
+        "started_at": { "type": ["string", "null"], "format": "date-time" },
+        "step_count": { "type": "integer", "minimum": 0 },
+        "token_count": { "type": "integer", "minimum": 0 },
+        "cost_usd": { "type": "number", "minimum": 0 },
+        "stop_reason": { "type": ["string", "null"], "description": "Why the last run stopped (goal_met, max_steps, max_tokens, verification_failed, …)." }
+      }
+    }
+  }
+}