Initial Commit

openspec/archive/2026-04-29-templates-spec-conformance/specs/templates/spec.md

@@ -0,0 +1,60 @@
+# Capability Spec Delta: templates (spec-conformance)
+
+**Package**: `@suaveplan/templates`
+**Status**: PROPOSED
+
+This delta records the verification mapping that the conformance script
+(`bun scripts/openspec-conformance.ts @suaveplan/templates`) ingests and
+captures the inline drift fixes (OTel instruments, boundary validation
+of `TemplateEngineOptions` / `ParseOptions`).
+
+## MODIFIED Requirements
+
+(See `openspec/specs/templates/spec.md` for the full requirement bodies;
+this delta only records the verification mapping.)
+
+| Requirement | Verified by |
+|---|---|
+| TPL-01 — Package shape and dependencies | `tests/dep-graph.test.ts` AND `src/__tests__/package-shape.spec-conformance.test.ts` |
+| TPL-02 — Subpath exports | `src/__tests__/package-shape.spec-conformance.test.ts` |
+| TPL-03 — Error hierarchy and code registry | `src/errors/template-error.test.ts` AND `src/errors/template-error.spec-conformance.test.ts` |
+| TPL-04 — Public types and SKIP_PLUGIN sentinel | `src/__tests__/types.spec-conformance.test.ts` |
+| TPL-05 — ParseState API | `src/engine/ParseState.test.ts` AND `src/engine/ParseState.spec-conformance.test.ts` |
+| TPL-06 — Boundary validation of constructor options | `src/engine/TemplateEngine.spec-conformance.test.ts::"rejects invalid options at the boundary (TPL-06)"` |
+| TPL-07 — Plugin registration and ordering | `src/engine/TemplateEngine.test.ts` AND `src/engine/TemplateEngine.spec-conformance.test.ts` |
+| TPL-08 — Sync render, async render, and recursive depth guard | `src/engine/TemplateEngine.test.ts` AND `src/engine/apply-plugin.spec-conformance.test.ts` |
+| TPL-09 — Error-suppression mode | `src/engine/TemplateEngine.spec-conformance.test.ts::"throwOnError=false swallows errors and returns original template (TPL-09)"` |
+| TPL-10 — Variable, transform, dynamic, and control-flow plugins | `src/plugins/plugins.spec-conformance.test.ts` AND the existing `src/plugins/**/*.test.ts` suite |
+| TPL-11 — Preset bundles | `src/presets/presets.spec-conformance.test.ts` |
+| TPL-12 — Utilities | `src/utils/escape.test.ts` AND `src/utils/format.test.ts` AND `src/utils/nested-value.test.ts` |
+| TPL-13 — OpenTelemetry instrumentation | `src/otel/templates-otel.spec-conformance.test.ts` |
+| TPL-14 — Quality gates | `vitest.config.ts` Istanbul thresholds + `bunx turbo test:coverage --filter=@suaveplan/templates` gate |
+
+## Newly added tests in this change
+
+- `src/__tests__/package-shape.spec-conformance.test.ts` — pins
+  `sideEffects: false`, runtime-dep set, and the subpath export map.
+- `src/__tests__/types.spec-conformance.test.ts` — pins the
+  `PluginPriority` numeric enum, the `SKIP_PLUGIN` symbol, and the
+  generic-threading of `TemplateEngine<TContext>` / `Plugin<TContext>`.
+- `src/engine/ParseState.spec-conformance.test.ts` — pins
+  `createParseState` defaults, deep-clone independence, counter / depth
+  helpers.
+- `src/engine/TemplateEngine.spec-conformance.test.ts` — pins
+  constructor-side schema validation, priority-descending ordering,
+  defensive `getPlugins` snapshot, and `throwOnError=false` suppression.
+- `src/engine/apply-plugin.spec-conformance.test.ts` — pins
+  reverse-index splicing and `SKIP_PLUGIN` semantics.
+- `src/errors/template-error.spec-conformance.test.ts` — pins
+  `SuaveplanError` parentage, `pluginName`/`match`/`depth`/`maxDepth`
+  fields, and the `TEMPLATE.*` namespace.
+- `src/otel/templates-otel.spec-conformance.test.ts` — pins the
+  no-op-without-provider behaviour, the `metrics.getMeter` namespace,
+  and that `parse` / `parseAsync` drive the helpers on success / skip /
+  error paths.
+- `src/plugins/plugins.spec-conformance.test.ts` — pins the priority
+  bands and the `Clock` / `Rng` injection contracts on
+  `createDateTimePlugin` / `createUuidPlugin`.
+- `src/presets/presets.spec-conformance.test.ts` — pins the
+  `minimal ⊂ standard ⊂ full ⊂ fullWithLoops` super-set relationships
+  and that each call returns fresh plugin instances.