Skip to content

Commit f4e6adf

Browse files
huangyiireneclaude
huangyiirene
and
claude
authored
docs(spec): mark PromptTemplate.system/.user [EXPERIMENTAL — not enforced] (#16548)
* 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> * fix(dogfood): move the D7 template-prompt row's tracker ids out of its runtime string `check:doc-authoring`'s cross-package prose-id leg reds on a tracker id inside a non-test string under packages/: the ledger `note` is runtime prose that reaches authors, operators and generated surfaces, none of whom can resolve one. The ruling id and its decision-batch number now live in an adjacent `//` comment — the gate's own prescribed remedy; ADR-0049 stays in the string as a customer-resolvable reference. No baseline entry: that file is maintainer-only and shrink-only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent ac9376a commit f4e6adf

4 files changed

Lines changed: 43 additions & 7 deletions

File tree

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

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

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -171,8 +171,8 @@ const result = ModelCapabilitySchema.parse(data);
171171
| **id** | `string` | ✅ | Unique template identifier |
172172
| **name** | `string` | ✅ | Template name (snake_case) |
173173
| **label** | `string` | ✅ | Display name |
174-
| **system** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | optional | System prompt — supports `{{var}}` interpolation |
175-
| **user** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | ✅ | User prompt template — supports `{{var}}` interpolation |
174+
| **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. |
175+
| **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. |
176176
| **assistant** | `string` | optional | Assistant message prefix |
177177
| **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; defaultValue?: any; … }[]` | optional | Template variables |
178178
| **modelId** | `string` | optional | Recommended model ID |
@@ -260,8 +260,8 @@ const result = ModelCapabilitySchema.parse(data);
260260
| **id** | `string` | ✅ | Unique template identifier |
261261
| **name** | `string` | ✅ | Template name (snake_case) |
262262
| **label** | `string` | ✅ | Display name |
263-
| **system** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | optional | System prompt — supports `{{var}}` interpolation |
264-
| **user** | `string \| { dialect: 'template'; source?: string; ast?: any; meta?: object }` | ✅ | User prompt template — supports `{{var}}` interpolation |
263+
| **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. |
264+
| **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. |
265265
| **assistant** | `string` | optional | Assistant message prefix |
266266
| **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; defaultValue?: any; … }[]` | optional | Template variables |
267267
| **modelId** | `string` | optional | Recommended model ID |

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,9 @@ export const EXPRESSION_SURFACE: ExprSurface[] = [
382382
'ai/model-registry.zod.ts:PromptTemplateSchema.system',
383383
'ai/model-registry.zod.ts:PromptTemplateSchema.user',
384384
],
385-
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.',
385+
// Ruling: #15954 (decision batch #56, option B for the template family). The tracker ids live
386+
// here, not in the string: `note` is runtime prose (check:doc-authoring, cross-package prose-id leg).
387+
note: 'EXPERIMENTAL — declared prompt templates with no runtime evaluator (ADR-0049), and MARKED as such at the declaration under the marking ruling (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.',
386388
},
387389
{
388390
id: 'template-title-format',

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,8 @@ export const PromptTemplateSchema = lazySchema(() => z.object({
118118
label: z.string().describe('Display name'),
119119

120120
/** Template Content */
121-
system: TemplateExpressionInputSchema.optional().describe('System prompt — supports {{var}} interpolation'),
122-
user: TemplateExpressionInputSchema.describe('User prompt template — supports {{var}} interpolation'),
121+
system: TemplateExpressionInputSchema.optional().describe('[EXPERIMENTAL — not enforced] System prompt — supports {{var}} interpolation. No runtime renders or executes the template today.'),
122+
user: TemplateExpressionInputSchema.describe('[EXPERIMENTAL — not enforced] User prompt template — supports {{var}} interpolation. No runtime renders or executes the template today.'),
123123
assistant: z.string().optional().describe('Assistant message prefix'),
124124

125125
/** Variables */

0 commit comments

Comments
 (0)