dna-sdk 0.1.0

package/dist/extensions/research.js

@@ -0,0 +1,292 @@
+/**
+ * ResearchExtension — curated research syntheses with evidence ratings (TS twin).
+ *
+ * 1:1 parity with python/dna/extensions/research/__init__.py.
+ *
+ * Storage layout per doc:
+ *
+ *   .dna/<scope>/research/<name>/
+ *       RESEARCH.md            ← marker (frontmatter = spec)
+ *
+ * A Research synthesizes N Reference docs with objective, methodology,
+ * evidence-rated findings, and priority recommendations — agent-facing
+ * knowledge WITH provenance (the declarative counter to LLM-generated
+ * repo-wiki prose).
+ *
+ * Tenancy: PERMISSIVE — no `scope` attribute declared, so the write
+ * pipeline treats it as permissive (base writes with or without a
+ * tenant). Research is repo-authored knowledge, not per-client data.
+ *
+ * The Reference companion Kind is provided by the sdlc extension
+ * (alias sdlc-reference); it is NOT registered here.
+ */
+import yaml from "js-yaml";
+import { KindBase } from "../kernel/kind_base.js";
+import { SD } from "../kernel/protocols.js";
+import { writeEntriesToHandle } from "../kernel/writer-helpers.js";
+const API_VERSION = "github.com/ruinosus/dna/research/v1";
+export const METHODOLOGIES = [
+    "web-search-curated",
+    "literature-review",
+    "interview",
+    "field-study",
+    "experiment",
+    "synthesis",
+    "other",
+];
+export const EVIDENCE_RATINGS = ["evidence-based", "opinion-practice", "anecdotal"];
+export const STATUSES = ["brief", "ready", "draft", "published", "superseded", "retracted"];
+export const VISIBILITY = ["scope-private", "shared"];
+function parseFrontmatter(text) {
+    const m = text.match(/^---\n([\s\S]*?)---\n?([\s\S]*)$/);
+    if (!m)
+        return { fm: {}, body: text };
+    try {
+        const parsed = yaml.load(m[1]);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return { fm: parsed, body: (m[2] ?? "").replace(/^\n+/, "") };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { fm: {}, body: text };
+}
+// ---------------------------------------------------------------------------
+// Research Kind
+// ---------------------------------------------------------------------------
+class ResearchKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "Research";
+    // alias generated as <owner>-<kebab(kind)> = "research-research" (owner =
+    // extension name). New Kinds must not TYPE an explicit alias (guard:
+    // tests/alias-generation.test.ts, EXPLICIT_ALIAS_ALLOWLIST). Empty here
+    // keeps the KindPort shape while triggering generation at register time.
+    alias = "";
+    aliasOwner = "research";
+    origin = "github.com/ruinosus/dna/research";
+    // PERMISSIVE tenancy — NO `scope` declared (base writes with or without tenant).
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    storage = SD.bundle("research", "RESEARCH.md");
+    graphStyle = { fill: "#7C3AED", stroke: "#5B21B6", textColor: "#fff" };
+    asciiIcon = "🔬";
+    displayLabel = "Research";
+    docs = "A Research is a curated synthesis of N external sources " +
+        "(Reference docs) with objective, methodology, evidence-rated " +
+        "findings, and priority recommendations. Designed for " +
+        "auditability + agent consumption.";
+    dependencies() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["title", "objective", "methodology", "status"],
+            additionalProperties: true,
+            properties: {
+                title: { type: "string" },
+                objective: { type: "string" },
+                executive_summary: { type: "string" },
+                key_takeaways: { type: "array", items: { type: "string" }, default: [] },
+                overall_confidence: { type: "string", enum: ["high", "moderate", "low", "very-low"] },
+                last_reviewed_at: { type: "string", format: "date-time" },
+                next_review_due: { type: "string", format: "date-time" },
+                methodology: { type: "string", enum: [...METHODOLOGIES], default: "web-search-curated" },
+                conducted_by: { type: "string" },
+                conducted_at: { type: "string", format: "date-time" },
+                scope_ref: { type: "string" },
+                visibility: { type: "string", enum: [...VISIBILITY], default: "scope-private" },
+                sources: {
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                },
+                findings: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        required: ["id", "title", "evidence_rating"],
+                        additionalProperties: true,
+                        properties: {
+                            id: { type: "string", pattern: "^f-[a-z0-9-]+$" },
+                            title: { type: "string" },
+                            summary: { type: "string" },
+                            evidence_rating: { type: "string", enum: [...EVIDENCE_RATINGS] },
+                            source_refs: { type: "array", items: { type: "string" }, default: [] },
+                            tags: { type: "array", items: { type: "string" }, default: [] },
+                        },
+                    },
+                    default: [],
+                },
+                recommendations: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        required: ["id", "priority", "summary"],
+                        additionalProperties: true,
+                        properties: {
+                            id: { type: "string", pattern: "^rec-[a-z0-9-]+$" },
+                            priority: { type: "string", enum: ["high", "medium", "low"] },
+                            summary: { type: "string" },
+                            effort_hours: { type: "number" },
+                            clinical_decision: { type: "boolean", default: false },
+                            depends_on: { type: "array", items: { type: "string" }, default: [] },
+                            backed_by_findings: { type: "array", items: { type: "string" }, default: [] },
+                            status: {
+                                type: "string",
+                                enum: ["proposed", "accepted", "rejected", "implemented", "blocked"],
+                                default: "proposed",
+                            },
+                        },
+                    },
+                    default: [],
+                },
+                status: { type: "string", enum: [...STATUSES], default: "draft" },
+                superseded_by: { type: "string" },
+                retracted_reason: { type: "string" },
+                audience_context: { type: "string" },
+                research_blocks: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        additionalProperties: true,
+                        properties: {
+                            title: { type: "string" },
+                            questions: { type: "array", items: { type: "string" } },
+                        },
+                    },
+                    default: [],
+                },
+                output_constraints: { type: "array", items: { type: "string" }, default: [] },
+                reference_baselines: { type: "array", items: { type: "string" }, default: [] },
+                brief_notes: { type: "string" },
+                tags: { type: "array", items: { type: "string" }, default: [] },
+                owner: { type: "string" },
+                created_at: { type: "string", format: "date-time" },
+                updated_at: { type: "string", format: "date-time" },
+            },
+        };
+    }
+    parse(raw) {
+        return raw;
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        const title = spec["title"] ?? "?";
+        const status = spec["status"] ?? "draft";
+        return `${title} [${status}]`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        const findings = spec["findings"] ?? [];
+        const recs = spec["recommendations"] ?? [];
+        const evFindings = findings.filter((f) => f.evidence_rating === "evidence-based").length;
+        return {
+            title: spec["title"] ?? "",
+            methodology: spec["methodology"] ?? "",
+            status: spec["status"] ?? "draft",
+            sources_count: (spec["sources"] ?? []).length,
+            findings_count: findings.length,
+            evidence_based_count: evFindings,
+            recommendations_count: recs.length,
+        };
+    }
+    promptTemplate() { return null; }
+}
+// ---------------------------------------------------------------------------
+// Reader / Writer
+// ---------------------------------------------------------------------------
+class ResearchReader {
+    async detect(bundle) {
+        return bundle.exists("RESEARCH.md");
+    }
+    async read(bundle) {
+        const text = await bundle.readText("RESEARCH.md");
+        const { fm } = parseFrontmatter(text);
+        if (fm &&
+            typeof fm === "object" &&
+            "spec" in fm &&
+            fm["spec"] &&
+            typeof fm["spec"] === "object") {
+            const metadata = fm["metadata"] ?? {};
+            if (!metadata["name"])
+                metadata["name"] = bundle.name;
+            return {
+                apiVersion: fm["apiVersion"] ?? API_VERSION,
+                kind: fm["kind"] ?? "Research",
+                metadata,
+                spec: fm["spec"],
+            };
+        }
+        return {
+            apiVersion: API_VERSION,
+            kind: "Research",
+            metadata: { name: bundle.name },
+            spec: fm,
+        };
+    }
+}
+class ResearchWriter {
+    canWrite(raw) {
+        return raw["kind"] === "Research";
+    }
+    serialize(raw) {
+        const spec = raw["spec"] ?? {};
+        const meta = raw["metadata"] ?? {};
+        const cleanSpec = {};
+        for (const [k, v] of Object.entries(spec)) {
+            if (v === null || v === undefined || v === "")
+                continue;
+            if (Array.isArray(v) && v.length === 0)
+                continue;
+            if (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0)
+                continue;
+            cleanSpec[k] = v;
+        }
+        const cleanMeta = {};
+        for (const [k, v] of Object.entries(meta)) {
+            if (v !== null && v !== undefined)
+                cleanMeta[k] = v;
+        }
+        const envelope = {
+            apiVersion: raw["apiVersion"] ?? API_VERSION,
+            kind: raw["kind"] ?? "Research",
+            metadata: cleanMeta,
+            spec: cleanSpec,
+        };
+        const fmYaml = yaml.dump(envelope, {
+            sortKeys: false,
+            lineWidth: 100,
+            noRefs: true,
+            noCompatMode: true,
+        }).replace(/\n+$/, "");
+        const title = cleanSpec["title"] ?? "?";
+        const method = cleanSpec["methodology"] ?? "synthesis";
+        const nFindings = (cleanSpec["findings"] ?? []).length;
+        const nSources = (cleanSpec["sources"] ?? []).length;
+        const body = `# Research — ${title}\n\n` +
+            `Methodology: ${method} · ${nSources} sources · ${nFindings} findings.\n\n` +
+            `This file's spec (frontmatter above) is the authoritative ` +
+            `data. The prose below is for human reading and is regenerated ` +
+            `on each write.\n`;
+        return [
+            { relativePath: "RESEARCH.md", content: `---\n${fmYaml}\n---\n\n${body}` },
+        ];
+    }
+    async write(bundle, raw) {
+        await writeEntriesToHandle(bundle, this.serialize(raw));
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class ResearchExtension {
+    name = "research";
+    version = "1.2.0";
+    register(kernel) {
+        kernel.kind(new ResearchKind());
+        // Reference companion is provided by the sdlc extension — not here.
+        kernel.reader(new ResearchReader());
+        kernel.writer(new ResearchWriter());
+    }
+}

package/dist/extensions/safety.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SafetyPolicyExtension — SafetyPolicy kind + SafetyPolicyReader + SafetyPolicyWriter.
+ *
+ * Declarative safety enforcement rules. Tier 1 (regex) is built-in;
+ * heavier tiers (ml, api, llm_judge) are opt-in.
+ *
+ * 1:1 parity with Python dna.v3.extensions.safety.
+ */
+import type { BundleHandle } from "../kernel/bundle-handle.js";
+import type { FSLike } from "../kernel/fs.js";
+import type { ExtensionHost, Extension, ReaderPort, SerializedFile, WriterPort } from "../kernel/protocols.js";
+export declare class SafetyPolicyReader implements ReaderPort {
+    private fs;
+    readonly _marker = "SAFETYPOLICY.md";
+    constructor(fs?: FSLike);
+    detect(bundle: BundleHandle): boolean;
+    read(bundle: BundleHandle): Record<string, unknown>;
+}
+export declare class SafetyPolicyWriter implements WriterPort {
+    private fs;
+    readonly _kind = "SafetyPolicy";
+    constructor(fs?: FSLike);
+    canWrite(raw: Record<string, unknown>): boolean;
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+}
+export declare class SafetyPolicyExtension implements Extension {
+    private fs;
+    readonly name = "safety";
+    readonly version = "1.0.0";
+    constructor(fs?: FSLike);
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/safety.js

@@ -0,0 +1,230 @@
+/**
+ * SafetyPolicyExtension — SafetyPolicy kind + SafetyPolicyReader + SafetyPolicyWriter.
+ *
+ * Declarative safety enforcement rules. Tier 1 (regex) is built-in;
+ * heavier tiers (ml, api, llm_judge) are opt-in.
+ *
+ * 1:1 parity with Python dna.v3.extensions.safety.
+ */
+import yaml from "js-yaml";
+import { nodeFS } from "../kernel/fs.js";
+import { KindBase } from "../kernel/kind_base.js";
+import { SafetyPolicySchema, SafetyPolicySpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { SD } from "../kernel/protocols.js";
+// ---------------------------------------------------------------------------
+// SafetyPolicyKind
+// ---------------------------------------------------------------------------
+class SafetyPolicyKind extends KindBase {
+    apiVersion = "github.com/ruinosus/dna/v1";
+    kind = "SafetyPolicy";
+    alias = "helix-safety-policy";
+    isSchemaAffecting = true;
+    origin = "github.com/ruinosus/dna";
+    isPromptTarget = false;
+    promptTargetPriority = 0;
+    flattenInContext = false;
+    descriptionFallbackField = "instruction";
+    storage = SD.bundle("safety", "SAFETYPOLICY.md", "list", "rules");
+    graphStyle = { fill: "#DC2626", stroke: "#B91C1C", textColor: "#fff" };
+    asciiIcon = "🔒";
+    displayLabel = "Safety Policies";
+    _sourceUrl = import.meta.url;
+    docs = "A SafetyPolicy declares runtime enforcement rules for PII masking, " +
+        "content safety, topic restriction, prompt injection detection, and " +
+        "custom regex patterns. Rules are tiered: regex (built-in), ml, api, " +
+        "llm_judge. Stored as a bundle rooted on SAFETYPOLICY.md.";
+    uiSchema = {
+        scope: {
+            widget: "select",
+            label: "Scope",
+            help: "input guards the user prompt; output guards the agent response; both runs on each side.",
+            options: ["input", "output", "both"],
+            order: 1,
+        },
+        action: {
+            widget: "select",
+            label: "Action",
+            help: "mask: redact PII inline; block: reject the message; log: pass through with violation metadata.",
+            options: ["mask", "block", "log"],
+            order: 2,
+        },
+        severity: {
+            widget: "select",
+            label: "Severity",
+            help: "error fails the turn; warn lets the turn continue.",
+            options: ["error", "warn"],
+            order: 3,
+        },
+        rules: {
+            widget: "code",
+            language: "yaml",
+            label: "Rules",
+            help: "YAML list of safety rules (type, tier, entities, patterns, etc.)",
+            height: 300,
+            order: 4,
+        },
+    };
+    depFilters() { return { recognizers: "presidio-recognizer" }; }
+    schema() { return zodSpecToJsonSchema(SafetyPolicySpecSchema); }
+    parse(raw) {
+        return SafetyPolicySchema.parse(raw);
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        return `SafetyPolicy: ${doc.name} (scope=${spec.scope}, action=${spec.action})`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            scope: typeof spec.scope === "string" ? spec.scope : "both",
+            action: typeof spec.action === "string" ? spec.action : "mask",
+            severity: typeof spec.severity === "string" ? spec.severity : "error",
+            rules: Array.isArray(spec.rules) ? spec.rules.length : 0,
+        };
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const blocks = [];
+        // Policy fields
+        const meta = [];
+        if (typeof spec.scope === "string")
+            meta.push({ label: "Scope", value: spec.scope });
+        if (typeof spec.action === "string")
+            meta.push({ label: "Action", value: spec.action });
+        if (typeof spec.severity === "string")
+            meta.push({ label: "Severity", value: spec.severity });
+        if (meta.length > 0) {
+            blocks.push({ kind: "fields", title: "Policy", fields: meta });
+        }
+        // Rules as YAML code block
+        const rules = spec.rules;
+        if (Array.isArray(rules) && rules.length > 0) {
+            blocks.push({
+                kind: "code",
+                title: "Rules",
+                body: yaml.dump(rules, { flowLevel: 3 }).trim(),
+                language: "yaml",
+            });
+        }
+        if (blocks.length === 0) {
+            return [{ kind: "empty", title: "SafetyPolicy (empty)" }];
+        }
+        return blocks;
+    }
+}
+// ---------------------------------------------------------------------------
+// SafetyPolicyReader
+// ---------------------------------------------------------------------------
+function parseFrontmatter(text) {
+    const match = text.match(/^---\n([\s\S]*?)---\n?/);
+    if (!match)
+        return [{}, text];
+    let fm = {};
+    try {
+        const parsed = yaml.load(match[1]);
+        if (typeof parsed === "object" && parsed !== null) {
+            fm = parsed;
+        }
+    }
+    catch { /* ignore */ }
+    const body = text.slice(match[0].length);
+    return [fm, body];
+}
+export class SafetyPolicyReader {
+    fs;
+    _marker = "SAFETYPOLICY.md";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    detect(bundle) {
+        const path = bundle.path ?? "";
+        return this.fs.exists(`${path}/SAFETYPOLICY.md`);
+    }
+    read(bundle) {
+        const path = bundle.path ?? "";
+        const text = this.fs.readFile(`${path}/SAFETYPOLICY.md`);
+        const [fm, body] = parseFrontmatter(text);
+        const name = String(fm.name || "") || path.split("/").pop() || "";
+        const description = String(fm.description || "");
+        const scope = String(fm.scope || "both");
+        const action = String(fm.action || "mask");
+        const severity = String(fm.severity || "error");
+        // Parse body as YAML list of rules
+        let rules = [];
+        const trimmedBody = body.trim();
+        if (trimmedBody) {
+            try {
+                const parsed = yaml.load(trimmedBody);
+                if (Array.isArray(parsed)) {
+                    rules = parsed;
+                }
+            }
+            catch { /* ignore invalid YAML */ }
+        }
+        return {
+            apiVersion: "github.com/ruinosus/dna/v1",
+            kind: "SafetyPolicy",
+            metadata: { name, description },
+            spec: { scope, action, severity, rules },
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// SafetyPolicyWriter
+// ---------------------------------------------------------------------------
+export class SafetyPolicyWriter {
+    fs;
+    _kind = "SafetyPolicy";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    canWrite(raw) {
+        return raw.kind === "SafetyPolicy";
+    }
+    write(bundle, raw) {
+        const path = bundle.path ?? "";
+        this.fs.mkdir(path);
+        for (const f of this.serialize(raw)) {
+            this.fs.writeFile(`${path}/${f.relativePath}`, f.content ?? "");
+        }
+    }
+    serialize(raw) {
+        const meta = (raw.metadata ?? {});
+        const spec = (raw.spec ?? {});
+        const fmParts = [];
+        if (meta.name)
+            fmParts.push(`name: ${meta.name}`);
+        if (meta.description)
+            fmParts.push(`description: ${meta.description}`);
+        fmParts.push(`scope: ${spec.scope ?? "both"}`);
+        fmParts.push(`action: ${spec.action ?? "mask"}`);
+        fmParts.push(`severity: ${spec.severity ?? "error"}`);
+        const frontmatter = fmParts.join("\n");
+        // Serialize rules as YAML list
+        const rules = spec.rules ?? [];
+        let body = "";
+        if (rules.length > 0) {
+            body = yaml.dump(rules, { flowLevel: 3 }).trim();
+        }
+        const content = body
+            ? `---\n${frontmatter}\n---\n\n${body}\n`
+            : `---\n${frontmatter}\n---\n`;
+        return [{ relativePath: "SAFETYPOLICY.md", content }];
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class SafetyPolicyExtension {
+    fs;
+    name = "safety";
+    version = "1.0.0";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    register(kernel) {
+        kernel.kind(new SafetyPolicyKind());
+        kernel.reader(new SafetyPolicyReader(this.fs));
+        kernel.writer(new SafetyPolicyWriter(this.fs));
+    }
+}

package/dist/extensions/sdlc/kinds/adr.kind.yaml

@@ -0,0 +1,136 @@
+# ADR — Architecture Decision Record (Nygard 2011 / MADR), record plane.
+# One ratified architectural decision per doc: context/decision/consequences.
+# Split out from Narrative.decisions[] (Phase 2.2 vocabulary sanitization).
+#
+# F3 lote-2 (spec 2026-06-10-kinds-descriptor-f3): synthesized from this
+# descriptor; the hand-written class twins were deleted. PARITY-CRITICAL
+# package data — byte-identical mirror under packages/sdk-{py,ts};
+# tests/test_descriptor_hash_parity.py enforces. Equivalence vs the extinct
+# class frozen in tests/test_lote2_descriptor_equivalence.py (golden:
+# tests/goldens/lote2/ADR.golden.json). Deltas intencionais (semântica
+# canônica = port): summary curado substitui o eco whole-spec do KindBase
+# default (list endpoints não usam kp.summary()); parse valida contra o
+# schema (classe era pass-through); to_card morto não migrado.
+apiVersion: github.com/ruinosus/dna/core/v1
+kind: KindDefinition
+metadata:
+  name: adr
+spec:
+  target_api_version: github.com/ruinosus/dna/sdlc/v1
+  target_kind: ADR
+  alias: sdlc-adr
+  origin: github.com/ruinosus/dna/sdlc
+  tenant_scope: global
+  plane: record
+  prompt_target: false
+  flatten_in_context: false
+  prompt_target_priority: 0
+  storage:
+    type: bundle
+    container: adrs
+    marker: ADR.md
+    body_field: body
+  dep_filters:
+    superseded_by: sdlc-adr
+    supersedes: sdlc-adr
+    covers_features: sdlc-feature
+  schema:
+    type: object
+    required:
+    - title
+    - status
+    - context
+    - decision
+    properties:
+      title:
+        type: string
+        description: Decision headline — start with imperative verb.
+      status:
+        type: string
+        enum:
+        - proposed
+        - accepted
+        - deprecated
+        - superseded
+        description: 'Lifecycle: proposed → accepted → deprecated|superseded. Use
+          `superseded` (not deprecated) when a newer ADR replaces this one — link
+          via `superseded_by`.'
+      context:
+        type: string
+        description: WHY we needed to decide. What forces are in play? What constraints
+          (technical, business, team) shape the choice? 1-3 paragraphs.
+      decision:
+        type: string
+        description: 'WHAT we decided. Active voice: ''We will X'' or ''We chose X
+          over Y''. 1-2 paragraphs.'
+      consequences:
+        type: string
+        description: What follows from this decision — positive AND negative. Future
+          readers need to see the trade-offs, not just the wins.
+      alternatives_considered:
+        type: array
+        items:
+          type: string
+        description: Other options weighed and rejected, with brief why-not.
+      deciders:
+        type: array
+        items:
+          type: string
+        description: Actor names who participated in the decision.
+      date:
+        type: string
+        format: date
+        description: Date the decision was accepted (ISO-8601).
+      superseded_by:
+        type: string
+        description: ADR slug that supersedes this one (when status=superseded).
+      supersedes:
+        type: array
+        items:
+          type: string
+        description: ADR slugs this one replaces.
+      covers_features:
+        type: array
+        items:
+          type: string
+        description: Feature names this decision affects.
+      narrative_origin:
+        type: string
+        description: When extracted from a Narrative.decisions[] entry during Phase
+          2.2 migration, this points to the source Narrative slug for provenance.
+      tags:
+        type: array
+        items:
+          type: string
+        description: Free-form tags (e.g. 'persistence', 'auth', 'ui').
+      body:
+        type: string
+        description: Optional full markdown body (ADR.md). When present, takes precedence
+          over the structured fields above for rendering. Useful when the ADR predates
+          this schema.
+      created_at:
+        type: string
+        format: date-time
+      updated_at:
+        type: string
+        format: date-time
+  summary:
+    title: ''
+    status: ''
+    date: ''
+    superseded_by: ''
+  embed:
+  - title
+  - context
+  - decision
+  graph_style:
+    fill: '#10B981'
+    stroke: '#047857'
+    text_color: '#fff'
+  ascii_icon: 📐
+  display_label: ADRs
+  docs: 'An ADR captures ONE architectural decision with its context, rationale, and
+    consequences. Convention: one ADR per file, immutable once accepted (subsequent
+    decisions supersede). Follows Nygard / MADR template — Adopt on ThoughtWorks Tech
+    Radar. Studio renders these as the decision log of the project; PMs/architects
+    can scan rationale without reading code.'