dna-sdk 0.4.0 → 0.5.0

package/dist/extensions/helix.js

@@ -13,6 +13,33 @@ import { readSpecString, readSpecStringArray } from "../kernel/spec-access.js";
 import { SettingKind, ThemeKind, UserProfileKind, CanvasKind } from "./helix_extras.js";
 import { registerWriteGuards } from "./helix/write-guards.js";
 const MOD_URL = import.meta.url;
+// ── Named composition layouts (s-dx-named-layouts) ─────────────────────
+//
+// An author orders persona-vs-instruction by NAME (`layout:` in the Agent
+// spec) instead of hand-writing raw Mustache with internal section names.
+// Each preset resolves to one of these embedded templates via
+// `AgentKind.layoutTemplate()`. 1:1 with Python `dna.extensions.helix`.
+//
+// The guardrails block is shared verbatim — guardrails are hard policy and
+// always land LAST, after both the instruction and the soul, regardless of
+// their relative order. (Aligns TS composition to Python, closing the
+// pre-existing i-213/i-011 divergence where TS omitted the guardrails block.)
+const GUARDRAILS_BLOCK = "{{#guardrails-guardrail}}" +
+    "## Guardrail: {{name}} ({{severity}})\n" +
+    "{{#description}}_{{description}}_\n\n{{/description}}" +
+    "{{#rules}}- {{{.}}}\n{{/rules}}\n" +
+    "{{/guardrails-guardrail}}";
+// instruction-first (a.k.a. "default") — historic order: instruction, soul,
+// guardrails. IS the kind default template.
+const LAYOUT_INSTRUCTION_FIRST = "{{{agent.instruction}}}\n\n{{{soul_content}}}\n\n" + GUARDRAILS_BLOCK;
+// persona-first — Soul leads, then instruction, then guardrails.
+const LAYOUT_PERSONA_FIRST = "{{{soul_content}}}\n\n{{{agent.instruction}}}\n\n" + GUARDRAILS_BLOCK;
+const AGENT_LAYOUTS = {
+    default: LAYOUT_INSTRUCTION_FIRST,
+    "instruction-first": LAYOUT_INSTRUCTION_FIRST,
+    "persona-first": LAYOUT_PERSONA_FIRST,
+};
+const AGENT_LAYOUT_NAMES = ["default", "instruction-first", "persona-first"];
 // GenomeKind — Phase 16 (scope segregation)
 //
 // Replaces ModuleKind as the scope-root identity Kind. Carries catalog
@@ -253,6 +280,13 @@ class AgentKind extends KindBase {
         },
         objective: { widget: "textarea", label: "Objective", order: 15 },
         model: { widget: "text", label: "Model", order: 20 },
+        layout: {
+            widget: "select",
+            label: "Layout",
+            options: ["default", "instruction-first", "persona-first"],
+            help: "Named composition order — 'persona-first' puts the Soul before the instruction. Leave empty for the default. A raw promptTemplate, if set, overrides this.",
+            order: 25,
+        },
         soul: { widget: "text", label: "Soul", help: "Name of the Soul doc to flatten into the prompt.", order: 30 },
         skills: { widget: "tags", label: "Skills", order: 40 },
         actors: { widget: "tags", label: "Actors this agent serves", order: 50 },
@@ -305,7 +339,17 @@ class AgentKind extends KindBase {
         return { skills: skills.length, soul: readSpecString(doc, "soul") ?? null };
     }
     promptTemplate() {
-        return "{{{agent.instruction}}}\n\n{{{soul_content}}}";
+        // IS the `instruction-first` / `default` named layout — the kind default
+        // template and the `default` layout are one string, so an agent with no
+        // `layout:` composes identically. (Now includes the guardrails block,
+        // matching Python — see the layout-constants comment above.)
+        return LAYOUT_INSTRUCTION_FIRST;
+    }
+    layoutTemplate(name) {
+        return AGENT_LAYOUTS[name] ?? null;
+    }
+    layoutNames() {
+        return [...AGENT_LAYOUT_NAMES];
     }
     preview(doc) {
         const spec = (doc.spec ?? {});

package/dist/extensions/sdlc.js

@@ -27,6 +27,7 @@
 import { KindBase } from "../kernel/kind_base.js";
 import { SD, TenantScope } from "../kernel/protocols.js";
 import { loadDescriptors } from "../kernel/descriptor-loader.js";
+import { HtmlArtifactSchema } from "../kernel/models.js";
 const API_VERSION = "github.com/ruinosus/dna/sdlc/v1";
 // v1.3: MILESTONE_STATUSES → EPIC_STATUSES (Jira/ADO alignment).
 const EPIC_STATUSES = ["planning", "in-progress", "done", "cancelled", "deprecated"];
@@ -1280,6 +1281,161 @@ const JOURNEY_METHODOLOGIES = [
 // the old class is frozen in sdk-py tests/test_kaizen_descriptor_equivalence.py
 // + tests/sdlc.test.ts.
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// HtmlArtifact — an HTML page as a first-class work-item output (record plane)
+//
+// s-dx-html-artifact-kind. 1:1 parity with Python HtmlArtifactKind. Bundle
+// Kind: ARTIFACT.html holds the raw HTML VERBATIM (byte-faithful round-trip —
+// no frontmatter injection), plus an optional artifact.json companion with
+// structured metadata (title, description, source, created_at) — the same
+// mechanic as a Soul (SOUL.md + soul.json). Custom reader/writer (not the
+// generic marker-frontmatter path) because the marker is arbitrary HTML.
+// ---------------------------------------------------------------------------
+class HtmlArtifactKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "HtmlArtifact";
+    // alias GENERATED = "<owner>-<kebab(kind)>" = "sdlc-html-artifact".
+    // s-alias-generated-not-typed: new Kinds must NOT type an explicit alias
+    // (EXPLICIT_ALIAS_ALLOWLIST ratchet is shrink-only). Empty here + aliasOwner
+    // triggers generation at load time (Py twin sets alias=None + alias_owner).
+    alias = "";
+    aliasOwner = "sdlc";
+    origin = "github.com/ruinosus/dna/sdlc";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    plane = "record";
+    storage = SD.bundle("html-artifacts", "ARTIFACT.html");
+    graphStyle = { fill: "#EA580C", stroke: "#C2410C", textColor: "#fff" };
+    asciiIcon = "📄";
+    displayLabel = "HTML Artifacts";
+    uiSchema = {
+        html: {
+            widget: "code",
+            language: "html",
+            label: "ARTIFACT.html",
+            help: "The raw HTML page (stored byte-faithful).",
+            height: 520,
+            order: 10,
+        },
+        artifact_json: {
+            widget: "code",
+            language: "json",
+            label: "artifact.json",
+            help: "Structured metadata (title, description, source, created_at).",
+            height: 220,
+            order: 20,
+        },
+    };
+    docs = "An HtmlArtifact stores an HTML page as a first-class, linkable output " +
+        "of a work item (Story/Feature/Epic/Spike). Bundle: ARTIFACT.html holds " +
+        "the raw HTML verbatim (byte-faithful round-trip) plus an optional " +
+        "artifact.json companion with structured metadata (title, description, " +
+        "source, created_at) — the same shape as a Soul's SOUL.md + soul.json. " +
+        "Attach one with `dna sdlc produces add <WiKind>/<wi> HtmlArtifact/<name>`.";
+    schema() {
+        return {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                html: { type: "string", description: "The raw HTML document (byte-faithful)." },
+                artifact_json: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Structured metadata: title, description, source, created_at.",
+                },
+            },
+        };
+    }
+    parse(raw) {
+        return HtmlArtifactSchema.parse(raw);
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        const aj = spec.artifact_json ?? {};
+        return {
+            title: aj.title ?? null,
+            source: aj.source ?? null,
+            created_at: aj.created_at ?? null,
+            html_bytes: (spec.html ?? "").length,
+        };
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const blocks = [];
+        if (typeof spec.html === "string" && spec.html) {
+            blocks.push({ kind: "code", title: "ARTIFACT.html", body: spec.html, language: "html" });
+        }
+        if (spec.artifact_json && typeof spec.artifact_json === "object") {
+            blocks.push({
+                kind: "code",
+                title: "artifact.json",
+                body: JSON.stringify(spec.artifact_json, null, 2),
+                language: "json",
+            });
+        }
+        if (blocks.length === 0) {
+            return [{ kind: "empty", title: "HtmlArtifact (empty)" }];
+        }
+        return blocks;
+    }
+}
+class HtmlArtifactReader {
+    async detect(bundle) {
+        return bundle.exists("ARTIFACT.html");
+    }
+    async read(bundle) {
+        const spec = {};
+        const metadata = {};
+        // ARTIFACT.html — read verbatim (byte-faithful; no frontmatter parse).
+        if (await bundle.exists("ARTIFACT.html")) {
+            spec.html = await bundle.readText("ARTIFACT.html");
+        }
+        // artifact.json companion — structured metadata.
+        if (await bundle.exists("artifact.json")) {
+            const aj = JSON.parse(await bundle.readText("artifact.json"));
+            if (aj && typeof aj === "object" && !Array.isArray(aj)) {
+                spec.artifact_json = aj;
+                const desc = aj.description;
+                if (typeof desc === "string" && desc && !metadata.description) {
+                    metadata.description = desc;
+                }
+            }
+        }
+        if (metadata.name == null)
+            metadata.name = bundle.name;
+        return {
+            apiVersion: API_VERSION,
+            kind: "HtmlArtifact",
+            metadata,
+            spec,
+        };
+    }
+}
+class HtmlArtifactWriter {
+    canWrite(raw) {
+        return raw.kind === "HtmlArtifact";
+    }
+    serialize(raw) {
+        const files = [];
+        const spec = raw.spec ?? {};
+        // ARTIFACT.html — verbatim HTML (byte-faithful).
+        files.push({ relativePath: "ARTIFACT.html", content: spec.html ?? "" });
+        // artifact.json — canonical JSON companion. metadata.description is a
+        // DERIVED promotion of artifact_json.description on read, so it is NOT
+        // re-emitted separately (no phantom frontmatter — F3 market-fidelity).
+        const aj = spec.artifact_json;
+        if (aj && typeof aj === "object") {
+            files.push({ relativePath: "artifact.json", content: JSON.stringify(aj, null, 2) });
+        }
+        return files;
+    }
+    async write(bundle, raw) {
+        for (const f of this.serialize(raw)) {
+            await bundle.writeText(f.relativePath, f.content ?? "");
+        }
+    }
+}
 export class SdlcExtension {
     name = "sdlc";
     // v1.14.0 — s-consolidate-cognitive-policies: the 9 cognitive policy
@@ -1302,6 +1458,12 @@ export class SdlcExtension {
         // v1.10.0 — f-reference-citation-kind (ported from Python for
         // s-alias-generated-not-typed: Spike.depFilters → "sdlc-reference").
         kernel.kind(new ReferenceKind());
+        // s-dx-html-artifact-kind — HTML page as a first-class work-item output.
+        // Bundle Kind with a custom reader/writer for byte-faithful HTML,
+        // mirroring the Soul (SOUL.md + soul.json) mechanic.
+        kernel.kind(new HtmlArtifactKind());
+        kernel.reader(new HtmlArtifactReader());
+        kernel.writer(new HtmlArtifactWriter());
         // expr batch B: PromptTemplate is a descriptor now — registered via the
         // loadDescriptors loop below. s-consolidate-cognitive-policies: the
         // cognitive policy family is ONE descriptor (cognitive-policy.kind.yaml).

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { ReportBuilder } from "./kernel/reports.js";
 export { serializeRawToFiles } from "./kernel/serialize-to-files.js";
 export * from "./viz/index.js";
 export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
-export { AgentNotFound } from "./kernel/errors.js";
+export { AgentNotFound, UnknownLayout } from "./kernel/errors.js";
 export { PromptLibrary, loadPrompts } from "./prompts.js";
 export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
 export type { DnaConfig, SearchMode, EmbeddingMode } from "./config.js";

package/dist/index.js

@@ -27,7 +27,7 @@ export * from "./viz/index.js";
 export { createKernelWithBuiltins, quickInstance, createRuntimeWithBuiltins, quickManifest, fromConfig } from "./bootstrap.js";
 // DX consumer surface (s-dx-*): fail-loud prompt building + the collapse-the-
 // shim helper + declarative port wiring.
-export { AgentNotFound } from "./kernel/errors.js";
+export { AgentNotFound, UnknownLayout } from "./kernel/errors.js";
 export { PromptLibrary, loadPrompts } from "./prompts.js";
 export { loadConfig, findConfig, CONFIG_FILENAME } from "./config.js";
 export { sourceFromUrl, resolveDefaultFsUrl, UnsupportedSourceScheme } from "./adapters/source-url.js";

package/dist/kernel/errors.d.ts

@@ -31,6 +31,23 @@ export declare class AgentNotFound extends Error {
     readonly agent: string | null;
     constructor(agent: string | null);
 }
+/**
+ * `buildPrompt` hit an Agent whose `layout:` names a preset the Kind does not
+ * offer (s-dx-named-layouts).
+ *
+ * Fail-loud DX: a typo'd layout (`persona_first` for `persona-first`) must not
+ * silently fall through to the Kind default and compose in the wrong order —
+ * it throws with the valid names listed.
+ *
+ * 1:1 parity with python `dna.UnknownLayout` (a `ValueError` subclass).
+ * Exported publicly from the package root.
+ */
+export declare class UnknownLayout extends Error {
+    readonly layout: string;
+    readonly available: string[];
+    readonly agent: string | null;
+    constructor(layout: string, available?: string[], agent?: string | null);
+}
 /** Base class for kernel registration validation failures. */
 export declare class KernelRegistrationError extends Error {
     constructor(message?: string);

package/dist/kernel/errors.js

@@ -36,6 +36,32 @@ export class AgentNotFound extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * `buildPrompt` hit an Agent whose `layout:` names a preset the Kind does not
+ * offer (s-dx-named-layouts).
+ *
+ * Fail-loud DX: a typo'd layout (`persona_first` for `persona-first`) must not
+ * silently fall through to the Kind default and compose in the wrong order —
+ * it throws with the valid names listed.
+ *
+ * 1:1 parity with python `dna.UnknownLayout` (a `ValueError` subclass).
+ * Exported publicly from the package root.
+ */
+export class UnknownLayout extends Error {
+    layout;
+    available;
+    agent;
+    constructor(layout, available = [], agent = null) {
+        const where = agent ? ` on agent '${agent}'` : "";
+        const hint = available.length ? ` — available: ${available.join(", ")}` : "";
+        super(`Unknown layout '${layout}'${where}${hint}`);
+        this.name = "UnknownLayout";
+        this.layout = layout;
+        this.available = available;
+        this.agent = agent;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /** Base class for kernel registration validation failures. */
 export class KernelRegistrationError extends Error {
     constructor(message) {

package/dist/kernel/kind_base.d.ts

@@ -94,6 +94,19 @@ export declare abstract class KindBase implements Omit<KindPort, "apiVersion" |
     describe(_doc: Document): string | null;
     summary(doc: Document): Record<string, unknown> | null;
     promptTemplate(): string | null;
+    /**
+     * Resolve a NAMED composition layout to an embedded template
+     * (s-dx-named-layouts). Prompt-target Kinds override this to expose
+     * author-friendly presets (persona-first, instruction-first) so the common
+     * case never hand-writes Mustache. Returns null for an unknown name (the
+     * prompt builder fails loud). Twin of Python ``KindBase.layout_template``.
+     */
+    layoutTemplate(_name: string): string | null;
+    /**
+     * Public layout names this Kind offers (s-dx-named-layouts) — powers
+     * discovery + fail-loud error messages. Twin of Python ``layout_names``.
+     */
+    layoutNames(): string[];
     protected canonicalSpec(spec: Record<string, unknown>): Record<string, unknown>;
     /** Stable SHA-256 of the doc's authored identity — basis for source
      *  diff/sync. Invariant to key order, formatting, volatile stamps, and

package/dist/kernel/kind_base.js

@@ -215,6 +215,23 @@ export class KindBase {
     promptTemplate() {
         return null;
     }
+    /**
+     * Resolve a NAMED composition layout to an embedded template
+     * (s-dx-named-layouts). Prompt-target Kinds override this to expose
+     * author-friendly presets (persona-first, instruction-first) so the common
+     * case never hand-writes Mustache. Returns null for an unknown name (the
+     * prompt builder fails loud). Twin of Python ``KindBase.layout_template``.
+     */
+    layoutTemplate(_name) {
+        return null;
+    }
+    /**
+     * Public layout names this Kind offers (s-dx-named-layouts) — powers
+     * discovery + fail-loud error messages. Twin of Python ``layout_names``.
+     */
+    layoutNames() {
+        return [];
+    }
     // ---- Source-sync digest (s-sync-s1; twin of Python canonical_digest) ----
     canonicalSpec(spec) {
         const out = {};

package/dist/kernel/models.d.ts

@@ -384,6 +384,7 @@ export declare const AgentSpecSchema: z.ZodObject<{
     tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     guardrails: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     promptTemplate: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodString>;
     tool_groups: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     mcp_servers: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
         ref: z.ZodString;
@@ -481,6 +482,7 @@ export declare const AgentSpecSchema: z.ZodObject<{
     reads: Record<string, Record<string, any>>;
     type?: string | undefined;
     promptTemplate?: string | undefined;
+    layout?: string | undefined;
     model?: string | undefined;
     instruction_file?: string | undefined;
     soul?: string | undefined;
@@ -517,6 +519,7 @@ export declare const AgentSpecSchema: z.ZodObject<{
     guardrails?: string[] | undefined;
     instruction?: string | undefined;
     promptTemplate?: string | undefined;
+    layout?: string | undefined;
     model?: string | undefined;
     instruction_file?: string | undefined;
     tags?: string[] | undefined;
@@ -601,6 +604,7 @@ export declare const AgentSchema: z.ZodObject<{
         tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         guardrails: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         promptTemplate: z.ZodOptional<z.ZodString>;
+        layout: z.ZodOptional<z.ZodString>;
         tool_groups: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         mcp_servers: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodObject<{
             ref: z.ZodString;
@@ -698,6 +702,7 @@ export declare const AgentSchema: z.ZodObject<{
         reads: Record<string, Record<string, any>>;
         type?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         soul?: string | undefined;
@@ -734,6 +739,7 @@ export declare const AgentSchema: z.ZodObject<{
         guardrails?: string[] | undefined;
         instruction?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         tags?: string[] | undefined;
@@ -810,6 +816,7 @@ export declare const AgentSchema: z.ZodObject<{
         reads: Record<string, Record<string, any>>;
         type?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         soul?: string | undefined;
@@ -860,6 +867,7 @@ export declare const AgentSchema: z.ZodObject<{
         guardrails?: string[] | undefined;
         instruction?: string | undefined;
         promptTemplate?: string | undefined;
+        layout?: string | undefined;
         model?: string | undefined;
         instruction_file?: string | undefined;
         tags?: string[] | undefined;
@@ -1551,6 +1559,83 @@ export declare const SoulSchema: z.ZodObject<{
     } | undefined;
 }>;
 export type TypedSoul = z.output<typeof SoulSchema>;
+export declare const HtmlArtifactSpecSchema: z.ZodObject<{
+    html: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    artifact_json: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    html: string;
+    artifact_json?: Record<string, unknown> | undefined;
+}, {
+    html?: string | undefined;
+    artifact_json?: Record<string, unknown> | undefined;
+}>;
+export declare const HtmlArtifactSchema: z.ZodObject<{
+    apiVersion: z.ZodLiteral<"github.com/ruinosus/dna/sdlc/v1">;
+    kind: z.ZodLiteral<"HtmlArtifact">;
+    metadata: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        version: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        icon: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        group: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        labels: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        version: string;
+        icon: string;
+        group: string;
+        labels: Record<string, string>;
+    }, {
+        name: string;
+        description?: string | undefined;
+        version?: string | undefined;
+        icon?: string | undefined;
+        group?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    }>;
+    spec: z.ZodDefault<z.ZodObject<{
+        html: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        artifact_json: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        html: string;
+        artifact_json?: Record<string, unknown> | undefined;
+    }, {
+        html?: string | undefined;
+        artifact_json?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    metadata: {
+        name: string;
+        description: string;
+        version: string;
+        icon: string;
+        group: string;
+        labels: Record<string, string>;
+    };
+    spec: {
+        html: string;
+        artifact_json?: Record<string, unknown> | undefined;
+    };
+    apiVersion: "github.com/ruinosus/dna/sdlc/v1";
+    kind: "HtmlArtifact";
+}, {
+    metadata: {
+        name: string;
+        description?: string | undefined;
+        version?: string | undefined;
+        icon?: string | undefined;
+        group?: string | undefined;
+        labels?: Record<string, string> | undefined;
+    };
+    apiVersion: "github.com/ruinosus/dna/sdlc/v1";
+    kind: "HtmlArtifact";
+    spec?: {
+        html?: string | undefined;
+        artifact_json?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+export type TypedHtmlArtifact = z.output<typeof HtmlArtifactSchema>;
 export declare const AgentDefinitionSpecSchema: z.ZodObject<{
     content: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {

package/dist/kernel/models.js

@@ -128,6 +128,12 @@ export const AgentSpecSchema = z.object({
     tags: z.array(z.string()).default([]),
     guardrails: z.array(z.string()).default([]),
     promptTemplate: z.string().optional(),
+    // s-dx-named-layouts — pick the composition ORDER by name instead of
+    // hand-writing raw Mustache. "persona-first" puts the Soul before the
+    // instruction; "instruction-first" (a.k.a. "default") keeps the historic
+    // order. Resolved by the Kind's layoutTemplate() into an embedded preset.
+    // A raw promptTemplate still wins over layout when both are set.
+    layout: z.string().optional(),
     // Phase 14x — tool-group specialization (TS parity with Python).
     tool_groups: z.array(z.string()).default([]),
     // s-mcp-servers-on-agent (2026-07-07, spec
@@ -393,6 +399,19 @@ export const SoulSchema = z.object({
     spec: SoulSpecSchema.default({}),
 });
 // ---------------------------------------------------------------------------
+// HtmlArtifact (github.com/ruinosus/dna/sdlc/v1)
+// ---------------------------------------------------------------------------
+export const HtmlArtifactSpecSchema = z.object({
+    html: z.string().optional().default(""),
+    artifact_json: z.record(z.unknown()).optional(),
+});
+export const HtmlArtifactSchema = z.object({
+    apiVersion: z.literal("github.com/ruinosus/dna/sdlc/v1"),
+    kind: z.literal("HtmlArtifact"),
+    metadata: MetadataSchema,
+    spec: HtmlArtifactSpecSchema.default({}),
+});
+// ---------------------------------------------------------------------------
 // AgentDefinition (agents.md/v1)
 // ---------------------------------------------------------------------------
 export const AgentDefinitionSpecSchema = z.object({

package/dist/kernel/prompt-builder.js

@@ -10,7 +10,7 @@
  */
 import Mustache from "mustache";
 import { stripPromptBlock } from "./_text.js";
-import { AgentNotFound } from "./errors.js";
+import { AgentNotFound, UnknownLayout } from "./errors.js";
 // ---------------------------------------------------------------------------
 // PromptBuilder
 // ---------------------------------------------------------------------------
@@ -206,22 +206,33 @@ export class PromptBuilder {
     async _renderPrompt(ctx, agentDoc) {
         const agentSpec = agentDoc.spec;
         const kinds = this.host._kinds;
-        // 1. Agent-level template override
+        // 1. Agent-level raw template override (poweruser escape hatch).
         const agentTemplate = agentSpec.promptTemplate ??
             agentSpec.prompt_template ??
             null;
         if (agentTemplate) {
             return await this._mustacheRender(agentTemplate, ctx);
         }
-        // 2. Kind default template
         const agentKp = kinds.get(`${agentDoc.apiVersion}\0${agentDoc.kind}`);
+        // 2. Named layout preset (s-dx-named-layouts) — author picks the
+        // composition order by NAME; the kernel resolves it to an embedded
+        // template so the common case never hand-writes Mustache.
+        const layout = agentSpec.layout;
+        if (layout && agentKp) {
+            const layoutTmpl = agentKp.layoutTemplate(layout);
+            if (layoutTmpl == null) {
+                throw new UnknownLayout(layout, agentKp.layoutNames(), agentDoc.name);
+            }
+            return await this._mustacheRender(layoutTmpl, ctx);
+        }
+        // 3. Kind default template
         if (agentKp) {
             const kindTemplate = agentKp.promptTemplate();
             if (kindTemplate) {
                 return await this._mustacheRender(kindTemplate, ctx);
             }
         }
-        // 3. Fallback: agent instruction as plain text
+        // 4. Fallback: agent instruction as plain text
         const agent = ctx.agent;
         return agent?.instruction ?? "";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dna-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",