@jamesaphoenix/tx-core 0.11.1 → 0.12.0

package/dist/internal/doc-service-impl.js

@@ -1,26 +1,26 @@
 /**
  * DocService — business logic for docs-as-primitives (DD-023).
  *
- * Manages doc lifecycle (create/update/lock/version), rendering (YAML→MD),
+ * Manages doc lifecycle (create/update/lock/version), markdown validation,
  * linking (doc-doc, task-doc), invariant sync, drift detection, and graph data.
  *
- * YAML content lives on disk (.tx/docs/); DB stores metadata + links only.
+ * Markdown content lives on disk (specs/); DB stores metadata + links only.
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, } from "node:fs";
 import { resolve, dirname, join } from "node:path";
-import { Cause, Context, Effect, Layer, Option } from "effect";
+import { Cause, Context, Effect, Either, Layer, Option, Schema } from "effect";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { DocRepository } from "../repo/doc-repo.js";
 import { ValidationError, DocNotFoundError, DocLockedError, InvalidDocYamlError, InvariantNotFoundError, } from "../errors.js";
 import { computeDocHash } from "../utils/doc-hash.js";
-import { renderDocToMarkdown, renderIndexToMarkdown, } from "../utils/doc-renderer.js";
+import { renderIndexToMarkdown } from "../utils/doc-renderer.js";
 import { formatEarsValidationErrors, validateEarsRequirements, } from "../utils/ears-validator.js";
+import { parseMdDocSync, MdDocParseError } from "../utils/md-doc-parser.js";
 import { readTxConfig } from "../utils/toml-config.js";
 import { resolvePathWithin } from "../utils/file-path.js";
-import { DOC_KINDS, INVARIANT_ENFORCEMENT_TYPES, EARS_PATTERNS, renderEarsRule, } from "@jamesaphoenix/tx-types";
+import { DOC_KINDS, DOC_CONTENT_SCHEMAS, EARS_PATTERNS, renderEarsRule, } from "@jamesaphoenix/tx-types";
 // Local string arrays for .includes() (avoids readonly cast)
 const docKindStrings = DOC_KINDS;
-const enforcementStrings = INVARIANT_ENFORCEMENT_TYPES;
 /** Infer link type from doc kinds (from → to). */
 const inferLinkType = (fromKind, toKind) => {
     if (fromKind === "overview" && toKind === "prd")
@@ -44,15 +44,15 @@ const kindSubdir = (kind) => {
     if (kind === "overview")
         return "";
     if (kind === "requirement")
-        return "requirement";
+        return "requirements";
     if (kind === "system_design")
-        return "system_design";
+        return "system-design";
     return kind;
 };
-/** Resolve the YAML file path for a doc. */
-const resolveYamlPath = (docsPath, kind, name) => {
+/** Resolve the markdown file path for a doc. */
+const resolveDocPath = (docsPath, kind, name) => {
     const sub = kindSubdir(kind);
-    const relativeDocPath = sub ? join(sub, `${name}.yml`) : `${name}.yml`;
+    const relativeDocPath = sub ? join(sub, `${name}.md`) : `${name}.md`;
     const resolvedDocPath = resolvePathWithin(docsPath, relativeDocPath, {
         useRealpath: true,
     });
@@ -63,19 +63,14 @@ const resolveYamlPath = (docsPath, kind, name) => {
     }
     return resolvedDocPath;
 };
-/** Resolve the MD file path for a doc. */
-const resolveMdPath = (docsPath, kind, name) => {
-    const sub = kindSubdir(kind);
-    const relativeDocPath = sub ? join(sub, `${name}.md`) : `${name}.md`;
-    const resolvedDocPath = resolvePathWithin(docsPath, relativeDocPath, {
-        useRealpath: true,
-    });
-    if (!resolvedDocPath) {
-        throw new ValidationError({
-            reason: `Invalid doc path for name '${name}'`,
+const parseSpecTypeAsDocKind = (name, specType) => {
+    if (!docKindStrings.includes(specType)) {
+        throw new InvalidDocYamlError({
+            name,
+            reason: `Unsupported spec_type '${specType}' for docs service.`,
         });
     }
-    return resolvedDocPath;
+    return specType;
 };
 const collectLegacyRequirements = (value) => {
     const normalize = (item) => {
@@ -112,8 +107,123 @@ const collectLegacyRequirements = (value) => {
 };
 /** EARS is a hard requirement for PRDs — not configurable. */
 const isEarsRequiredForLegacyPrds = () => true;
+const nullableYamlStringKeys = new Set([
+    "name",
+    "title",
+    "problem_definition",
+    "subsystems",
+    "object_model",
+    "user_specific_content",
+    "problem",
+    "solution",
+    "overview",
+    "scope",
+    "design",
+    "architecture",
+    "data_model",
+    "open_questions",
+    "functional_requirements",
+    "id",
+    "statement",
+    "category",
+    "rationale",
+    "condition",
+    "impact",
+    "handling",
+    "expected_behavior",
+    "description",
+    "actor",
+    "trigger",
+    "outcome",
+    "target",
+    "reason",
+    "decision",
+    "consequence",
+    "requirement_id",
+    "verification",
+    "success_criteria",
+    "system",
+    "response",
+    "feature",
+    "state",
+    "test_hint",
+    "constraints",
+    "acceptance_criteria",
+    "non_goals",
+    "requirements",
+    "out_of_scope",
+    "goals",
+    "non_functional_requirements",
+]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const normalizeNullYamlStrings = (value, currentKey) => {
+    if (value === null) {
+        return currentKey && nullableYamlStringKeys.has(currentKey) ? "" : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeNullYamlStrings(item, currentKey));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const normalized = {};
+    for (const [key, entry] of Object.entries(value)) {
+        normalized[key] = normalizeNullYamlStrings(entry, key);
+    }
+    return normalized;
+};
+const normalizeLegacyEarsRequirements = (parsed) => {
+    const raw = parsed.ears_requirements;
+    if (!Array.isArray(raw))
+        return;
+    for (const entry of raw) {
+        if (!isRecord(entry))
+            continue;
+        if (typeof entry.statement === "string" && entry.statement.trim().length > 0) {
+            continue;
+        }
+        const patternValue = entry.pattern;
+        const systemValue = entry.system;
+        const responseValue = entry.response;
+        if (typeof patternValue !== "string" ||
+            !EARS_PATTERNS.includes(patternValue) ||
+            typeof systemValue !== "string" ||
+            typeof responseValue !== "string") {
+            continue;
+        }
+        entry.statement = renderEarsRule({
+            pattern: patternValue,
+            system: systemValue,
+            response: responseValue,
+            trigger: typeof entry.trigger === "string" ? entry.trigger : undefined,
+            state: typeof entry.state === "string" ? entry.state : undefined,
+            condition: typeof entry.condition === "string" ? entry.condition : undefined,
+            feature: typeof entry.feature === "string" ? entry.feature : undefined,
+        });
+    }
+};
+const normalizeForSchemaValidation = (kind, parsed) => {
+    const normalized = normalizeNullYamlStrings(parsed);
+    if (kind === "prd" || kind === "requirement") {
+        normalizeLegacyEarsRequirements(normalized);
+    }
+    return normalized;
+};
+const collectSchemaWarnings = (kind, parsed) => {
+    if (kind !== "prd")
+        return [];
+    const warnings = [];
+    if (parsed.requirements !== undefined) {
+        warnings.push("Deprecated field 'requirements' detected in PRD YAML; use 'ears_requirements' instead.");
+    }
+    if (parsed.out_of_scope !== undefined) {
+        warnings.push("Deprecated field 'out_of_scope' detected in PRD YAML; use 'non_goals' instead.");
+    }
+    return warnings;
+};
 /** Validate YAML content and return parsed object. */
-const validateYaml = (name, content, expectedKind) => {
+const _validateYaml = (name, content, expectedKind, options) => {
+    const enforceContentSchema = options?.enforceContentSchema === true;
     let parsed;
     try {
         parsed = parseYaml(content);
@@ -135,6 +245,24 @@ const validateYaml = (name, content, expectedKind) => {
         ? parsedObject.kind
         : null;
     const effectiveKind = expectedKind ?? yamlKind;
+    const warnings = collectSchemaWarnings(effectiveKind, parsedObject);
+    if (enforceContentSchema && effectiveKind && effectiveKind in DOC_CONTENT_SCHEMAS) {
+        const contentSchema = DOC_CONTENT_SCHEMAS[effectiveKind];
+        const normalizedForDecode = normalizeForSchemaValidation(effectiveKind, parsedObject);
+        const decoded = Schema.decodeUnknownEither(contentSchema)(normalizedForDecode);
+        if (Either.isLeft(decoded)) {
+            const detail = typeof decoded.left === "object" &&
+                decoded.left !== null &&
+                "message" in decoded.left &&
+                typeof decoded.left.message === "string"
+                ? decoded.left.message
+                : String(decoded.left);
+            throw new InvalidDocYamlError({
+                name,
+                reason: `YAML schema validation failed for kind '${effectiveKind}': ${detail}`,
+            });
+        }
+    }
     if (effectiveKind === "prd" && parsedObject.ears_requirements !== undefined) {
         if (!Array.isArray(parsedObject.ears_requirements)) {
             throw new InvalidDocYamlError({
@@ -162,10 +290,10 @@ const validateYaml = (name, content, expectedKind) => {
                 "'ears_requirements' array. EARS-structured requirements are mandatory for all PRDs.",
         });
     }
-    return parsedObject;
+    return { parsed: parsedObject, warnings };
 };
 /** Validate doc kind from YAML. */
-const validateKind = (name, parsed, expectedKind) => {
+const _validateKind = (name, parsed, expectedKind) => {
     const yamlKind = parsed.kind;
     if (yamlKind && typeof yamlKind === "string" && yamlKind !== expectedKind) {
         throw new InvalidDocYamlError({
@@ -174,151 +302,54 @@ const validateKind = (name, parsed, expectedKind) => {
         });
     }
 };
-const normalizeInvariantSegment = (value) => {
-    const normalized = value
-        .toUpperCase()
-        .replace(/[^A-Z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .replace(/-+/g, "-");
-    return normalized.length > 0 ? normalized : "DOC";
-};
-const collectStringList = (value) => {
-    return collectLegacyRequirements(value);
-};
-const extractSubsystemFromEarsId = (id) => {
-    const match = /^EARS-([A-Z0-9]+)-\d{3}$/.exec(id);
-    return match?.[1]?.toLowerCase();
-};
-const extractExplicitInvariants = (raw) => {
-    if (!Array.isArray(raw))
-        return [];
-    const candidates = [];
-    for (const item of raw) {
-        if (typeof item !== "object" || item === null)
-            continue;
-        const inv = item;
-        const id = typeof inv.id === "string" ? inv.id : null;
-        const rule = typeof inv.rule === "string" ? inv.rule : null;
-        const enforcement = typeof inv.enforcement === "string" ? inv.enforcement : null;
-        if (!id || !rule || !enforcement)
-            continue;
-        if (!enforcementStrings.includes(enforcement))
-            continue;
-        candidates.push({
-            id,
-            rule,
-            enforcement,
-            subsystem: typeof inv.subsystem === "string"
-                ? inv.subsystem
-                : inv.subsystem === null
-                    ? null
-                    : undefined,
-            testRef: typeof inv.test_ref === "string" ? inv.test_ref : undefined,
-            lintRule: typeof inv.lint_rule === "string" ? inv.lint_rule : undefined,
-            promptRef: typeof inv.prompt_ref === "string" ? inv.prompt_ref : undefined,
-            // Provenance
-            source: typeof inv.source === "string" ? inv.source : undefined,
-            sourceRef: typeof inv.source_ref === "string" ? inv.source_ref : undefined,
-            // EARS fields (explicit invariants may include these)
-            pattern: typeof inv.pattern === "string" ? inv.pattern : undefined,
-            triggerText: typeof inv.trigger === "string" ? inv.trigger : undefined,
-            stateText: typeof inv.state === "string" ? inv.state : undefined,
-            conditionText: typeof inv.condition === "string" ? inv.condition : undefined,
-            feature: typeof inv.feature === "string" ? inv.feature : undefined,
-            systemName: typeof inv.system === "string" ? inv.system : undefined,
-            response: typeof inv.response === "string" ? inv.response : undefined,
-            rationale: typeof inv.rationale === "string" ? inv.rationale : undefined,
-            testHint: typeof inv.test_hint === "string" ? inv.test_hint : undefined,
-        });
-    }
-    return candidates;
+const mapInvariantSeverityToEnforcement = (_severity) => {
+    return "integration_test";
 };
-const deriveEarsInvariants = (doc, parsed) => {
-    if (doc.kind !== "prd" && doc.kind !== "requirement")
-        return [];
-    const raw = parsed.ears_requirements;
-    if (!Array.isArray(raw))
-        return [];
-    const candidates = [];
-    for (const item of raw) {
-        if (typeof item !== "object" || item === null)
-            continue;
-        const req = item;
-        const earsId = typeof req.id === "string" ? req.id : null;
-        const system = typeof req.system === "string" ? req.system.trim() : "";
-        const response = typeof req.response === "string" ? req.response.trim() : "";
-        if (!earsId || !system || !response)
-            continue;
-        const pattern = typeof req.pattern === "string" ? req.pattern : "ubiquitous";
-        const trigger = typeof req.trigger === "string" ? req.trigger : undefined;
-        const state = typeof req.state === "string" ? req.state : undefined;
-        const condition = typeof req.condition === "string" ? req.condition : undefined;
-        const feature = typeof req.feature === "string" ? req.feature : undefined;
-        const rationale = typeof req.rationale === "string" ? req.rationale : undefined;
-        const testHint = typeof req.test_hint === "string" ? req.test_hint : undefined;
-        // Validate pattern against known EARS patterns
-        const earsPatternStrings = EARS_PATTERNS;
-        const validPattern = earsPatternStrings.includes(pattern)
-            ? pattern
-            : "ubiquitous";
-        const rule = renderEarsRule({
-            pattern: validPattern,
-            system,
-            response,
-            trigger,
-            state,
-            condition,
-            feature,
-        });
-        candidates.push({
-            id: `INV-${earsId}`,
-            rule,
-            enforcement: "integration_test",
-            subsystem: extractSubsystemFromEarsId(earsId),
-            testRef: testHint ?? null,
-            source: "explicit",
-            // EARS fields
-            pattern: validPattern,
-            triggerText: trigger ?? null,
-            stateText: state ?? null,
-            conditionText: condition ?? null,
-            feature: feature ?? null,
-            systemName: system,
-            response,
-            rationale: rationale ?? null,
-            testHint: testHint ?? null,
-        });
+const mapMdEarsKindToLegacyPattern = (kind) => {
+    switch (kind) {
+        case "event-driven":
+            return "event_driven";
+        case "state-driven":
+            return "state_driven";
+        case "unwanted":
+            return "unwanted";
+        case "optional":
+            return "optional";
+        case "complex":
+            return "complex";
+        default:
+            return "ubiquitous";
     }
-    return candidates;
 };
-const derivePrdRequirementInvariants = (doc, parsed) => {
-    if (doc.kind !== "prd")
+const deriveEmbeddedInvariantCandidates = (doc, rawInvariants) => {
+    if (!rawInvariants || rawInvariants.length === 0)
         return [];
-    const requirements = collectStringList(parsed.requirements);
-    if (requirements.length === 0)
-        return [];
-    const docSegment = normalizeInvariantSegment(doc.name);
-    return requirements.map((rule, index) => ({
-        id: `INV-PRD-${docSegment}-REQ-${String(index + 1).padStart(3, "0")}`,
-        rule,
-        enforcement: "integration_test",
-        subsystem: "prd",
+    return rawInvariants.map((inv) => ({
+        id: inv.id,
+        rule: inv.statement,
+        enforcement: mapInvariantSeverityToEnforcement(inv.severity),
+        subsystem: doc.kind,
+        testRef: inv.verified_by[0] ?? null,
         source: "explicit",
+        sourceRef: "blocks.invariants",
     }));
 };
-const deriveDesignGoalInvariants = (doc, parsed) => {
-    if (doc.kind !== "design")
+const deriveEmbeddedEarsInvariantCandidates = (doc, rawRequirements) => {
+    if (!rawRequirements || rawRequirements.length === 0)
         return [];
-    const goals = collectStringList(parsed.goals);
-    if (goals.length === 0)
-        return [];
-    const docSegment = normalizeInvariantSegment(doc.name);
-    return goals.map((rule, index) => ({
-        id: `INV-DESIGN-${docSegment}-GOAL-${String(index + 1).padStart(3, "0")}`,
-        rule,
+    return rawRequirements.map((req) => ({
+        id: `INV-${req.id}`,
+        rule: req.statement,
         enforcement: "integration_test",
-        subsystem: "design",
-        source: "goals",
+        subsystem: doc.kind,
+        source: "explicit",
+        sourceRef: "blocks.ears_requirements",
+        pattern: mapMdEarsKindToLegacyPattern(req.kind),
+        triggerText: req.when ?? null,
+        stateText: req.while ?? null,
+        conditionText: req.if ?? null,
+        feature: req.where ?? null,
+        rationale: req.rationale ?? null,
     }));
 };
 export class DocService extends Context.Tag("DocService")() {
@@ -335,19 +366,47 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             mkdirSync(dir, { recursive: true });
         }
     };
-    /** Render a single doc and return its MD file path. */
-    const renderSingleDoc = (doc, docsPath) => {
-        const yamlPath = resolveYamlPath(docsPath, doc.kind, doc.name);
-        if (!existsSync(yamlPath)) {
+    const parseMarkdownSpecDocContent = (name, content) => {
+        const parsedResult = parseMdDocSync(content);
+        if (Either.isLeft(parsedResult)) {
+            const reason = parsedResult.left instanceof MdDocParseError
+                ? parsedResult.left.reason
+                : String(parsedResult.left);
+            throw new InvalidDocYamlError({
+                name,
+                reason: `Markdown validation failed: ${reason}`,
+            });
+        }
+        if (parsedResult.right.kind !== "spec") {
+            throw new InvalidDocYamlError({
+                name,
+                reason: "Markdown docs managed by DocService must have frontmatter kind: spec.",
+            });
+        }
+        return parsedResult.right;
+    };
+    /** Validate a single markdown doc and return its canonical file path. */
+    const validateDocFile = (doc, docsPath) => {
+        const docPath = resolveDocPath(docsPath, doc.kind, doc.name);
+        if (!existsSync(docPath)) {
             throw new DocNotFoundError({ name: doc.name });
         }
-        const yamlContent = readFileSync(yamlPath, "utf8");
-        const parsed = validateYaml(doc.name, yamlContent, doc.kind);
-        const md = renderDocToMarkdown(parsed, doc.kind);
-        const mdPath = resolveMdPath(docsPath, doc.kind, doc.name);
-        ensureDir(mdPath);
-        writeFileSync(mdPath, md, "utf8");
-        return mdPath;
+        const content = readFileSync(docPath, "utf8");
+        const parsed = parseMarkdownSpecDocContent(doc.name, content);
+        const parsedKind = parseSpecTypeAsDocKind(doc.name, parsed.frontmatter.spec_type);
+        if (parsed.frontmatter.name !== doc.name) {
+            throw new InvalidDocYamlError({
+                name: doc.name,
+                reason: `Frontmatter name '${parsed.frontmatter.name}' does not match doc name '${doc.name}'.`,
+            });
+        }
+        if (parsedKind !== doc.kind) {
+            throw new InvalidDocYamlError({
+                name: doc.name,
+                reason: `Frontmatter spec_type '${parsed.frontmatter.spec_type}' does not match doc kind '${doc.kind}'.`,
+            });
+        }
+        return docPath;
     };
     /** Generate index.yml and index.md from all docs in DB. */
     function generateIndexEffect(docsPath) {
@@ -463,22 +522,31 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             writeFileSync(indexMdPath, indexMd, "utf8");
         });
     }
-    /** Sync invariants from a single doc's YAML into DB. */
+    /** Sync invariants from a single markdown doc into DB. */
     function syncInvariantsForDoc(doc) {
         return Effect.gen(function* () {
             const docsPath = getDocsPath();
-            const yamlPath = resolveYamlPath(docsPath, doc.kind, doc.name);
-            if (!existsSync(yamlPath)) {
+            const docPath = resolveDocPath(docsPath, doc.kind, doc.name);
+            if (!existsSync(docPath)) {
                 return [];
             }
-            const yamlContent = readFileSync(yamlPath, "utf8");
-            const parsed = validateYaml(doc.name, yamlContent, doc.kind);
-            const explicit = extractExplicitInvariants(parsed.invariants);
-            const derived = [
-                ...deriveEarsInvariants(doc, parsed),
-                ...derivePrdRequirementInvariants(doc, parsed),
-                ...deriveDesignGoalInvariants(doc, parsed),
-            ];
+            const content = readFileSync(docPath, "utf8");
+            const parsed = parseMarkdownSpecDocContent(doc.name, content);
+            const parsedKind = parseSpecTypeAsDocKind(doc.name, parsed.frontmatter.spec_type);
+            if (parsed.frontmatter.name !== doc.name) {
+                throw new InvalidDocYamlError({
+                    name: doc.name,
+                    reason: `Frontmatter name '${parsed.frontmatter.name}' does not match doc name '${doc.name}'.`,
+                });
+            }
+            if (parsedKind !== doc.kind) {
+                throw new InvalidDocYamlError({
+                    name: doc.name,
+                    reason: `Frontmatter spec_type '${parsed.frontmatter.spec_type}' does not match doc kind '${doc.kind}'.`,
+                });
+            }
+            const explicit = deriveEmbeddedInvariantCandidates(doc, parsed.blocks.invariants);
+            const derived = deriveEmbeddedEarsInvariantCandidates(doc, parsed.blocks.ears_requirements);
             const candidates = [];
             const seen = new Set();
             for (const candidate of [...explicit, ...derived]) {
@@ -526,7 +594,7 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
     }
     return {
         create: (input) => Effect.gen(function* () {
-            const { kind, name, title, yamlContent, metadata } = input;
+            const { kind, name, title, content, metadata } = input;
             if (!docKindStrings.includes(kind)) {
                 return yield* Effect.fail(new ValidationError({ reason: `Invalid doc kind: ${kind}` }));
             }
@@ -535,37 +603,49 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
                     reason: `Invalid doc name: ${name}. Use alphanumeric with dashes/dots.`,
                 }));
             }
-            const parsed = validateYaml(name, yamlContent, kind);
-            validateKind(name, parsed, kind);
-            const existing = yield* docRepo.findByName(name);
+            const parsedDoc = parseMarkdownSpecDocContent(name, content);
+            const frontmatter = parsedDoc.frontmatter;
+            const parsedKind = parseSpecTypeAsDocKind(name, frontmatter.spec_type);
+            if (frontmatter.name !== name) {
+                return yield* Effect.fail(new ValidationError({
+                    reason: `Frontmatter name '${frontmatter.name}' does not match input name '${name}'.`,
+                }));
+            }
+            if (frontmatter.title !== title) {
+                return yield* Effect.fail(new ValidationError({
+                    reason: `Frontmatter title '${frontmatter.title}' does not match input title '${title}'.`,
+                }));
+            }
+            if (parsedKind !== kind) {
+                return yield* Effect.fail(new ValidationError({
+                    reason: `Frontmatter spec_type '${frontmatter.spec_type}' does not match input kind '${kind}'.`,
+                }));
+            }
+            const existing = yield* docRepo.findByName(frontmatter.name);
             if (existing) {
                 return yield* Effect.fail(new ValidationError({
-                    reason: `Doc '${name}' already exists (v${existing.version})`,
+                    reason: `Doc '${frontmatter.name}' already exists (v${existing.version})`,
                 }));
             }
-            const hash = computeDocHash(yamlContent);
+            const hash = computeDocHash(content);
             const docsPath = getDocsPath();
-            const filePath = resolveYamlPath(docsPath, kind, name);
+            const filePath = resolveDocPath(docsPath, parsedKind, frontmatter.name);
             ensureDir(filePath);
-            writeFileSync(filePath, yamlContent, "utf8");
-            const sub = kindSubdir(kind);
-            const relPath = sub ? join(sub, `${name}.yml`) : `${name}.yml`;
+            writeFileSync(filePath, content, "utf8");
+            const sub = kindSubdir(parsedKind);
+            const relPath = sub
+                ? join(sub, `${frontmatter.name}.md`)
+                : `${frontmatter.name}.md`;
             const doc = yield* docRepo.insert({
                 hash,
-                kind,
-                name,
-                title,
+                kind: parsedKind,
+                name: frontmatter.name,
+                title: frontmatter.title,
                 version: 1,
                 filePath: relPath,
                 parentDocId: null,
                 metadata: metadata ? JSON.stringify(metadata) : undefined,
             });
-            try {
-                renderSingleDoc(doc, docsPath);
-            }
-            catch {
-                /* non-fatal */
-            }
             yield* generateIndexEffect(docsPath);
             return doc;
         }),
@@ -576,7 +656,7 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             }
             return doc;
         }),
-        update: (name, yamlContent) => Effect.gen(function* () {
+        update: (name, content) => Effect.gen(function* () {
             const doc = yield* docRepo.findByName(name);
             if (!doc) {
                 return yield* Effect.fail(new DocNotFoundError({ name }));
@@ -584,25 +664,32 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             if (doc.status === "locked") {
                 return yield* Effect.fail(new DocLockedError({ name, version: doc.version }));
             }
-            const parsed = validateYaml(name, yamlContent, doc.kind);
-            validateKind(name, parsed, doc.kind);
-            const hash = computeDocHash(yamlContent);
+            const parsedDoc = parseMarkdownSpecDocContent(name, content);
+            const frontmatter = parsedDoc.frontmatter;
+            const parsedKind = parseSpecTypeAsDocKind(name, frontmatter.spec_type);
+            if (frontmatter.name !== name) {
+                return yield* Effect.fail(new InvalidDocYamlError({
+                    name,
+                    reason: `Frontmatter name '${frontmatter.name}' does not match doc '${name}'.`,
+                }));
+            }
+            if (parsedKind !== doc.kind) {
+                return yield* Effect.fail(new InvalidDocYamlError({
+                    name,
+                    reason: `Frontmatter spec_type '${frontmatter.spec_type}' does not match existing kind '${doc.kind}'.`,
+                }));
+            }
+            const hash = computeDocHash(content);
             const docsPath = getDocsPath();
-            const filePath = resolveYamlPath(docsPath, doc.kind, name);
+            const filePath = resolveDocPath(docsPath, doc.kind, name);
             ensureDir(filePath);
-            writeFileSync(filePath, yamlContent, "utf8");
-            const title = typeof parsed.title === "string" ? parsed.title : doc.title;
+            writeFileSync(filePath, content, "utf8");
+            const title = frontmatter.title;
             yield* docRepo.update(doc.id, { hash, title });
             const updated = yield* docRepo.findById(doc.id);
             if (!updated) {
                 return yield* Effect.fail(new DocNotFoundError({ name }));
             }
-            try {
-                renderSingleDoc(updated, docsPath);
-            }
-            catch {
-                /* non-fatal */
-            }
             yield* generateIndexEffect(docsPath);
             return updated;
         }),
@@ -620,14 +707,7 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             if (!locked) {
                 return yield* Effect.fail(new DocNotFoundError({ name }));
             }
-            const docsPath = getDocsPath();
-            try {
-                renderSingleDoc(locked, docsPath);
-            }
-            catch {
-                /* non-fatal */
-            }
-            yield* generateIndexEffect(docsPath);
+            yield* generateIndexEffect(getDocsPath());
             return locked;
         }),
         list: (filter) => docRepo.findAll(filter),
@@ -641,18 +721,10 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             }
             yield* docRepo.remove(doc.id);
             const docsPath = getDocsPath();
-            const yamlPath = resolveYamlPath(docsPath, doc.kind, name);
-            const mdPath = resolveMdPath(docsPath, doc.kind, name);
+            const docPath = resolveDocPath(docsPath, doc.kind, name);
             try {
-                if (existsSync(yamlPath))
-                    unlinkSync(yamlPath);
-            }
-            catch {
-                /* non-fatal */
-            }
-            try {
-                if (existsSync(mdPath))
-                    unlinkSync(mdPath);
+                if (existsSync(docPath))
+                    unlinkSync(docPath);
             }
             catch {
                 /* non-fatal */
@@ -667,16 +739,16 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
                 if (!doc) {
                     return yield* Effect.fail(new DocNotFoundError({ name }));
                 }
-                rendered.push(renderSingleDoc(doc, docsPath));
+                rendered.push(validateDocFile(doc, docsPath));
             }
             else {
                 const allDocs = yield* docRepo.findAll();
                 for (const doc of allDocs) {
                     try {
-                        rendered.push(renderSingleDoc(doc, docsPath));
+                        rendered.push(validateDocFile(doc, docsPath));
                     }
                     catch {
-                        /* skip docs with missing YAML */
+                        /* skip docs with invalid or missing markdown */
                     }
                 }
             }
@@ -694,17 +766,19 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
                 }));
             }
             const docsPath = getDocsPath();
-            const yamlPath = resolveYamlPath(docsPath, doc.kind, name);
-            if (!existsSync(yamlPath)) {
+            const docPath = resolveDocPath(docsPath, doc.kind, name);
+            if (!existsSync(docPath)) {
                 return yield* Effect.fail(new ValidationError({
-                    reason: `YAML file not found for '${name}'`,
+                    reason: `Markdown file not found for '${name}'`,
                 }));
             }
-            const yamlContent = readFileSync(yamlPath, "utf8");
-            const hash = computeDocHash(yamlContent);
+            const content = readFileSync(docPath, "utf8");
+            const hash = computeDocHash(content);
             const newVersion = doc.version + 1;
             const versionSub = kindSubdir(doc.kind);
-            const relPath = versionSub ? join(versionSub, `${name}.yml`) : `${name}.yml`;
+            const relPath = versionSub
+                ? join(versionSub, `${name}.md`)
+                : `${name}.md`;
             const newDoc = yield* docRepo.insert({
                 hash,
                 kind: doc.kind,
@@ -714,12 +788,6 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
                 filePath: relPath,
                 parentDocId: doc.id,
             });
-            try {
-                renderSingleDoc(newDoc, docsPath);
-            }
-            catch {
-                /* non-fatal */
-            }
             yield* generateIndexEffect(docsPath);
             return newDoc;
         }),
@@ -757,21 +825,31 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
                     reason: `Patches can only be created on design docs, got '${parentDoc.kind}'`,
                 }));
             }
-            const patchYaml = stringifyYaml({
-                kind: "design",
+            const today = new Date().toISOString().slice(0, 10);
+            const patchFrontmatter = stringifyYaml({
+                kind: "spec",
+                spec_type: "design",
                 name: patchName,
                 title: patchTitle,
-                status: "changing",
+                status: "draft",
                 version: 1,
+                owners: ["docs-team"],
+                summary: `Patch for ${parentDoc.name}: ${patchTitle}`,
+                domain: "docs",
+                tags: ["patch"],
+                depends_on: [parentDoc.name],
+                supersedes: [],
                 implements: parentDoc.name,
-                problem_definition: `Patch for ${parentDoc.name}: ${patchTitle}`,
+                last_reviewed_at: today,
             });
-            const hash = computeDocHash(patchYaml);
+            const patchContent = `---\n${patchFrontmatter}---\n\n# Summary\nPatch for ${parentDoc.name}: ${patchTitle}\n\n# Architecture\nPatch architecture details.\n\n# Interfaces\n\`\`\`yaml\ninterfaces: []\n\`\`\`\n\n# Data Model\nNo data model changes.\n\n# Invariants\n\`\`\`yaml\ninvariants: []\n\`\`\`\n\n# Failure Modes\n\`\`\`yaml\nfailure_modes: []\n\`\`\`\n\n# Verification\n\`\`\`yaml\nverification: []\n\`\`\`\n`;
+            parseMarkdownSpecDocContent(patchName, patchContent);
+            const hash = computeDocHash(patchContent);
             const docsPath = getDocsPath();
-            const filePath = resolveYamlPath(docsPath, "design", patchName);
+            const filePath = resolveDocPath(docsPath, "design", patchName);
             ensureDir(filePath);
-            writeFileSync(filePath, patchYaml, "utf8");
-            const relPath = join("design", `${patchName}.yml`);
+            writeFileSync(filePath, patchContent, "utf8");
+            const relPath = join("design", `${patchName}.md`);
             const patchDoc = yield* docRepo.insert({
                 hash,
                 kind: "design",
@@ -782,12 +860,6 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
                 parentDocId: null,
             });
             yield* docRepo.createLink(patchDoc.id, parentDoc.id, "design_patch");
-            try {
-                renderSingleDoc(patchDoc, docsPath);
-            }
-            catch {
-                /* non-fatal */
-            }
             yield* generateIndexEffect(docsPath);
             return patchDoc;
         }),
@@ -806,16 +878,16 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             }
             const warnings = [];
             const docsPath = getDocsPath();
-            const yamlPath = resolveYamlPath(docsPath, doc.kind, name);
-            if (existsSync(yamlPath)) {
-                const content = readFileSync(yamlPath, "utf8");
+            const docPath = resolveDocPath(docsPath, doc.kind, name);
+            if (existsSync(docPath)) {
+                const content = readFileSync(docPath, "utf8");
                 const currentHash = computeDocHash(content);
                 if (currentHash !== doc.hash) {
                     warnings.push(`Content hash mismatch: DB has ${doc.hash.slice(0, 8)}..., file has ${currentHash.slice(0, 8)}...`);
                 }
             }
             else {
-                warnings.push(`YAML file missing: ${yamlPath}`);
+                warnings.push(`Markdown file missing: ${docPath}`);
             }
             const taskLinks = yield* docRepo.getTaskLinksForDoc(doc.id);
             if (taskLinks.length === 0 && doc.kind === "design") {
@@ -837,7 +909,7 @@ export const DocServiceLive = Layer.effect(DocService, Effect.gen(function* () {
             else {
                 const allDocs = yield* docRepo.findAll();
                 for (const doc of allDocs) {
-                    // Keep whole-repo sync resilient: one malformed YAML file should not
+                    // Keep whole-repo sync resilient: one malformed markdown file should not
                     // prevent invariants from being refreshed for every other doc.
                     const result = yield* syncInvariantsForDoc(doc).pipe(Effect.catchAllCause((cause) => {
                         const defect = Cause.dieOption(cause);