docs(spec): mark PromptTemplate.system/.user [EXPERIMENTAL — not enforced]

Under the #15954 ruling (decision batch #56, option B) the template-typed
pair is marked, not retired. Both .describe() strings on PromptTemplateSchema
now carry the repo's existing [EXPERIMENTAL — not enforced] prefix and state
that no runtime renders or executes the template today.

The model site is ai/agent.zod.ts (four uses of the identical prefix); the
card named ai/knowledge-source.zod.ts, which carries no such marking at all
(zero hits for the bare token EXPERIMENTAL, positive control lit).

Prose only. .user remains required and .system remains optional — the schema
shape is untouched. The ADR-0058 D7 ledger row `template-prompt` records the
marking for both positions it covers, and the generated reference page is
regenerated with the repo's own tooling.

Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/prompt-template-experimental-marking.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): mark `PromptTemplate.system` / `.user` `[EXPERIMENTAL — not enforced]` (#15954, #16321)
+
+Prose only. `Clause-②: no` — no accept-set change, no new/narrowed authorable
+key, no matrix declaration. Every value that parsed before parses now, and
+every value refused before is refused identically.
+
+Under the #15954 ruling (decision batch #56, option B) the template-typed pair
+is **marked, not retired**. Both `.describe()` strings on
+`ai/PromptTemplateSchema` now carry the repo's existing
+`[EXPERIMENTAL — not enforced]` prefix and state that no runtime renders or
+executes the template today:
+
+```ts
+system: TemplateExpressionInputSchema.optional().describe('[EXPERIMENTAL — not enforced] System prompt — supports {{var}} interpolation. No runtime renders or executes the template today.'),
+user:   TemplateExpressionInputSchema.describe('[EXPERIMENTAL — not enforced] User prompt template — supports {{var}} interpolation. No runtime renders or executes the template today.'),
+```
+
+**Why an author sees this.** `PromptTemplateSchema` has no consumer outside
+`packages/spec`, so the `{{var}}` holes are never interpolated and the declared
+`variables` are never checked against them. The ADR-0058 D7 conformance ledger
+already recorded that verdict (`template-prompt`, `state: 'experimental'`,
+`PARSE ONLY — NO EVALUATOR FOUND`); until now nothing said it at the
+declaration, so the generated reference page advertised a capability the
+runtime does not deliver.
+
+**What does NOT change.** `.user` remains **required** and `.system` remains
+optional — the schema shape is untouched. Optionalising or retiring a required
+key is a parse-breaking change and is deliberately left to its own card. No
+tombstone and no ADR-0087 entry is owed: nothing is renamed, retired or
+re-typed.

content/docs/references/ai/model-registry.mdx

@@ -171,8 +171,8 @@ const result = ModelCapabilitySchema.parse(data);
 | **id** | `string` | ✅ | Unique template identifier |
 | **name** | `string` | ✅ | Template name (snake_case) |
 | **label** | `string` | ✅ | Display name |
-| **system** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | optional | System prompt — supports `{{var}}` interpolation |
-| **user** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | ✅ | User prompt template — supports `{{var}}` interpolation |
+| **system** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | optional | [EXPERIMENTAL — not enforced] System prompt — supports `{{var}}` interpolation. No runtime renders or executes the template today. |
+| **user** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | ✅ | [EXPERIMENTAL — not enforced] User prompt template — supports `{{var}}` interpolation. No runtime renders or executes the template today. |
 | **assistant** | `string` | optional | Assistant message prefix |
 | **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; defaultValue?: any; … }[]` | optional | Template variables |
 | **modelId** | `string` | optional | Recommended model ID |
@@ -260,8 +260,8 @@ const result = ModelCapabilitySchema.parse(data);
 | **id** | `string` | ✅ | Unique template identifier |
 | **name** | `string` | ✅ | Template name (snake_case) |
 | **label** | `string` | ✅ | Display name |
-| **system** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | optional | System prompt — supports `{{var}}` interpolation |
-| **user** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | ✅ | User prompt template — supports `{{var}}` interpolation |
+| **system** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | optional | [EXPERIMENTAL — not enforced] System prompt — supports `{{var}}` interpolation. No runtime renders or executes the template today. |
+| **user** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | ✅ | [EXPERIMENTAL — not enforced] User prompt template — supports `{{var}}` interpolation. No runtime renders or executes the template today. |
 | **assistant** | `string` | optional | Assistant message prefix |
 | **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; defaultValue?: any; … }[]` | optional | Template variables |
 | **modelId** | `string` | optional | Recommended model ID |

packages/qa/dogfood/test/expression-conformance.ledger.ts

@@ -382,7 +382,7 @@ export const EXPRESSION_SURFACE: ExprSurface[] = [
       'ai/model-registry.zod.ts:PromptTemplateSchema.system',
       'ai/model-registry.zod.ts:PromptTemplateSchema.user',
     ],
-    note: 'EXPERIMENTAL — declared prompt templates with no runtime evaluator (ADR-0049). Ownership was checked before classifying rather than assumed: the card that appeared to own these keys is closed as completed, and its delivered diff (`d355c361157`) touched exactly one file, `skills/objectstack-ai/SKILL.md` — it corrected a prose clause that called these keys CEL, and never owned a ledger row. No open card owns them.',
+    note: 'EXPERIMENTAL — declared prompt templates with no runtime evaluator (ADR-0049), and MARKED as such at the declaration under the #15954 ruling (decision batch #56, option B: this pair is marked, NOT retired). Both positions this row covers — `PromptTemplateSchema.system` and `PromptTemplateSchema.user` — now carry the `[EXPERIMENTAL — not enforced]` prefix in their own `.describe()`, stating that no runtime renders or executes the template today, so an author reading the generated reference page gets the same verdict this row records instead of having to find this ledger. The marking is PROSE ONLY: `.user` remains REQUIRED (no `.optional()`) and `.system` keeps the `.optional()` it already had — optionalising or retiring a required key is parse-breaking and is its own card. Ownership was checked before classifying rather than assumed: the card that appeared to own these keys is closed as completed, and its delivered diff (`d355c361157`) touched exactly one file, `skills/objectstack-ai/SKILL.md` — it corrected a prose clause that called these keys CEL, and never owned a ledger row. No open card owns them.',
   },
   {
     id: 'template-title-format',

packages/spec/src/ai/model-registry.zod.ts

@@ -118,8 +118,8 @@ export const PromptTemplateSchema = lazySchema(() => z.object({
   label: z.string().describe('Display name'),
 
   /** Template Content */
-  system: TemplateExpressionInputSchema.optional().describe('System prompt — supports {{var}} interpolation'),
-  user: TemplateExpressionInputSchema.describe('User prompt template — supports {{var}} interpolation'),
+  system: TemplateExpressionInputSchema.optional().describe('[EXPERIMENTAL — not enforced] System prompt — supports {{var}} interpolation. No runtime renders or executes the template today.'),
+  user: TemplateExpressionInputSchema.describe('[EXPERIMENTAL — not enforced] User prompt template — supports {{var}} interpolation. No runtime renders or executes the template today.'),
   assistant: z.string().optional().describe('Assistant message prefix'),
 
   /** Variables */