@deftai/directive-core 0.92.0 → 0.93.0

package/dist/xbrief/styles.js

@@ -0,0 +1,235 @@
+/**
+ * P0 xBRIEF style templates and markdown section maps (#3057).
+ *
+ * One schema spine (xBRIEF v0.8); markdown is a dense render of the same plan,
+ * not a second dialect.
+ */
+/** Required H2 section titles in the markdown form per style. */
+export const MD_REQUIRED_SECTIONS = {
+    scope: ["Title", "Status", "Overview", "Items"],
+    playbook: ["Title", "Status", "Overview", "Steps"],
+    mission: ["Title", "Status", "Outcome", "Evidence"],
+    project: ["Title", "Status", "Overview", "TechStack"],
+};
+function isoNow(now) {
+    return now.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function defaultStatus(style) {
+    switch (style) {
+        case "scope":
+            return "draft";
+        case "playbook":
+            return "approved";
+        case "mission":
+            return "completed";
+        case "project":
+            return "approved";
+    }
+}
+function defaultNarratives(style, title) {
+    switch (style) {
+        case "scope":
+            return {
+                Overview: `Scope brief for ${title}.`,
+                Description: "",
+            };
+        case "playbook":
+            return {
+                Overview: `Playbook for ${title}.`,
+                Steps: "1. Inspect\n2. Act\n3. Verify",
+            };
+        case "mission":
+            return {
+                Outcome: `Mission outcome for ${title}.`,
+                Evidence: "",
+            };
+        case "project":
+            return {
+                Overview: `Project identity for ${title}.`,
+                TechStack: "",
+            };
+    }
+}
+function defaultItems(style) {
+    if (style === "playbook") {
+        return [
+            {
+                title: "Inspect",
+                status: "proposed",
+                narrative: { Acceptance: "Context is loaded and preconditions hold." },
+            },
+            {
+                title: "Act",
+                status: "proposed",
+                narrative: { Acceptance: "Primary steps complete." },
+            },
+            {
+                title: "Verify",
+                status: "proposed",
+                narrative: { Acceptance: "Checks pass or failures are recorded." },
+            },
+        ];
+    }
+    return [];
+}
+/** Build a minimal valid xBRIEF v0.8 document for the given P0 style. */
+export function buildStyleDocument(input) {
+    const now = input.now ?? new Date();
+    const stamp = isoNow(now);
+    const status = input.status ?? defaultStatus(input.style);
+    const baseNarratives = defaultNarratives(input.style, input.title);
+    const narratives = { ...baseNarratives, ...(input.narratives ?? {}) };
+    const items = input.items ?? defaultItems(input.style);
+    const plan = {
+        title: input.title,
+        status,
+        narratives,
+        items,
+        metadata: {
+            kind: input.style,
+            xbriefCreate: true,
+        },
+    };
+    if (input.id !== undefined && input.id.length > 0) {
+        plan.id = input.id;
+    }
+    return {
+        xBRIEFInfo: {
+            version: "0.8",
+            description: input.description ?? `xBRIEF ${input.style} artifact (on-demand create)`,
+            created: stamp,
+            updated: stamp,
+        },
+        plan,
+    };
+}
+function sectionBody(doc, key) {
+    const narratives = doc.plan.narratives ?? {};
+    // Prefer exact key, then case-insensitive match.
+    if (typeof narratives[key] === "string")
+        return narratives[key];
+    const lower = key.toLowerCase();
+    for (const [k, v] of Object.entries(narratives)) {
+        if (k.toLowerCase() === lower && typeof v === "string")
+            return v;
+    }
+    return "";
+}
+function renderItemsList(doc, heading) {
+    const lines = [`## ${heading}`, ""];
+    const items = Array.isArray(doc.plan.items) ? doc.plan.items : [];
+    if (items.length === 0) {
+        lines.push("_(none)_", "");
+        return lines.join("\n");
+    }
+    for (const raw of items) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            lines.push(`- ${String(raw)}`);
+            continue;
+        }
+        const item = raw;
+        const title = typeof item.title === "string" ? item.title : "(untitled)";
+        const status = typeof item.status === "string" ? item.status : "unknown";
+        lines.push(`- **${title}** (${status})`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/** Render dense markdown from the JSON spine (one dialect). */
+export function renderMarkdown(doc, style) {
+    const idLine = typeof doc.plan.id === "string" && doc.plan.id.length > 0 ? `id: ${doc.plan.id}\n` : "";
+    const header = [
+        "---",
+        "xbrief: 0.8",
+        `style: ${style}`,
+        idLine.trimEnd() === "" ? null : idLine.trimEnd(),
+        "---",
+        "",
+        `# ${doc.plan.title}`,
+        "",
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+    const sections = MD_REQUIRED_SECTIONS[style];
+    const parts = [header];
+    for (const section of sections) {
+        if (section === "Title") {
+            parts.push("## Title", "", doc.plan.title, "");
+            continue;
+        }
+        if (section === "Status") {
+            parts.push("## Status", "", String(doc.plan.status), "");
+            continue;
+        }
+        if (section === "Items" || section === "Steps") {
+            parts.push(renderItemsList(doc, section));
+            // Also include narrative Steps when present for playbook density.
+            if (section === "Steps") {
+                const stepsNarrative = sectionBody(doc, "Steps");
+                if (stepsNarrative.length > 0) {
+                    parts.push("### Steps narrative", "", stepsNarrative, "");
+                }
+            }
+            continue;
+        }
+        const body = sectionBody(doc, section);
+        parts.push(`## ${section}`, "", body.length > 0 ? body : "_(empty)_", "");
+    }
+    return `${parts
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd()}\n`;
+}
+/**
+ * Lightweight parse of md form for verify: extract title, status, id, and H2 sections.
+ * Not a full reverse dialect — verify uses it for required-section + consistency checks.
+ */
+export function parseMarkdownMeta(md) {
+    const sections = new Set();
+    let title = null;
+    let status = null;
+    let id = null;
+    let style = null;
+    const lines = md.split(/\r?\n/);
+    let inFront = false;
+    let afterTitleH2 = false;
+    let afterStatusH2 = false;
+    for (const line of lines) {
+        if (line.trim() === "---") {
+            inFront = !inFront;
+            continue;
+        }
+        if (inFront) {
+            const idMatch = /^id:\s*(.+)\s*$/.exec(line);
+            if (idMatch?.[1] !== undefined)
+                id = idMatch[1].trim();
+            const styleMatch = /^style:\s*(.+)\s*$/.exec(line);
+            if (styleMatch?.[1] !== undefined)
+                style = styleMatch[1].trim();
+            continue;
+        }
+        const h1 = /^#\s+(.+)$/.exec(line);
+        if (h1?.[1] !== undefined && title === null) {
+            title = h1[1].trim();
+        }
+        const h2 = /^##\s+(.+)$/.exec(line);
+        if (h2?.[1] !== undefined) {
+            const name = h2[1].trim();
+            sections.add(name);
+            afterTitleH2 = name === "Title";
+            afterStatusH2 = name === "Status";
+            continue;
+        }
+        if (afterTitleH2 && line.trim().length > 0 && !line.startsWith("#")) {
+            // Prefer ## Title body over H1 when present.
+            title = line.trim();
+            afterTitleH2 = false;
+        }
+        if (afterStatusH2 && line.trim().length > 0 && !line.startsWith("#")) {
+            status = line.trim();
+            afterStatusH2 = false;
+        }
+    }
+    return { title, status, id, style, sections };
+}
+//# sourceMappingURL=styles.js.map

package/dist/xbrief/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared types for on-demand xBRIEF create/verify (#3057).
+ *
+ * create/verify write or check shaped SoT artifacts at an explicit path.
+ * They are NOT scope lifecycle verbs (scope:promote / activate / complete).
+ */
+export declare const XBRIEF_FORMATS: readonly ["json", "md", "both"];
+export type XbriefFormat = (typeof XBRIEF_FORMATS)[number];
+export declare const XBRIEF_STYLES: readonly ["scope", "playbook", "mission", "project"];
+export type XbriefStyle = (typeof XBRIEF_STYLES)[number];
+/** Default size cap for create/verify payloads (bytes). */
+export declare const DEFAULT_XBRIEF_SIZE_CAP_BYTES: number;
+export interface XbriefCliResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface XbriefPaths {
+    /** Absolute project root used for containment. */
+    readonly projectRoot: string;
+    /** Absolute stem path (no .xbrief.json / .xbrief.md suffix). */
+    readonly stemAbs: string;
+    /** Absolute JSON path when format includes json. */
+    readonly jsonAbs: string | null;
+    /** Absolute MD path when format includes md. */
+    readonly mdAbs: string | null;
+}
+export interface XbriefDocument {
+    readonly xBRIEFInfo: {
+        readonly version: "0.8";
+        readonly description?: string;
+        readonly created?: string;
+        readonly updated?: string;
+        readonly author?: string;
+        readonly [key: string]: unknown;
+    };
+    readonly plan: {
+        readonly title: string;
+        readonly status: string;
+        readonly id?: string;
+        readonly narratives?: Record<string, string>;
+        readonly items: unknown[];
+        readonly metadata?: Record<string, unknown>;
+        readonly [key: string]: unknown;
+    };
+    readonly [key: string]: unknown;
+}
+export declare function isXbriefFormat(value: string): value is XbriefFormat;
+export declare function isXbriefStyle(value: string): value is XbriefStyle;
+//# sourceMappingURL=types.d.ts.map

package/dist/xbrief/types.js

@@ -0,0 +1,17 @@
+/**
+ * Shared types for on-demand xBRIEF create/verify (#3057).
+ *
+ * create/verify write or check shaped SoT artifacts at an explicit path.
+ * They are NOT scope lifecycle verbs (scope:promote / activate / complete).
+ */
+export const XBRIEF_FORMATS = ["json", "md", "both"];
+export const XBRIEF_STYLES = ["scope", "playbook", "mission", "project"];
+/** Default size cap for create/verify payloads (bytes). */
+export const DEFAULT_XBRIEF_SIZE_CAP_BYTES = 512 * 1024;
+export function isXbriefFormat(value) {
+    return XBRIEF_FORMATS.includes(value);
+}
+export function isXbriefStyle(value) {
+    return XBRIEF_STYLES.includes(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/xbrief/verify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * xbrief:verify — fail-closed check of an xBRIEF artifact at --out (#3057).
+ *
+ * Required: --format (json|md|both), --out
+ * Checks: schema/parse, required fields, size cap, md sections per style,
+ * and stem/title/id consistency when format=both.
+ *
+ * Does NOT move lifecycle folders.
+ */
+import { type XbriefCliResult, type XbriefFormat, type XbriefStyle } from "./types.js";
+export declare const VERIFY_USAGE: string;
+export interface VerifyOptions {
+    format: XbriefFormat;
+    out: string;
+    style?: XbriefStyle;
+    projectRoot: string;
+    sizeCapBytes?: number;
+    cwd?: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** Parse verify CLI argv into options (or error string). */
+export declare function parseVerifyArgv(argv: readonly string[]): VerifyOptions | {
+    error: string;
+};
+/** Core verify implementation (testable). */
+export declare function verifyXbrief(options: VerifyOptions): XbriefCliResult;
+/** CLI entry for dispatch wrapper. */
+export declare function runXbriefVerifyCli(argv: string[]): XbriefCliResult;
+//# sourceMappingURL=verify.d.ts.map

package/dist/xbrief/verify.js

@@ -0,0 +1,251 @@
+/**
+ * xbrief:verify — fail-closed check of an xBRIEF artifact at --out (#3057).
+ *
+ * Required: --format (json|md|both), --out
+ * Checks: schema/parse, required fields, size cap, md sections per style,
+ * and stem/title/id consistency when format=both.
+ *
+ * Does NOT move lifecycle folders.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { validateVbriefSchema } from "../vbrief-validate/schema.js";
+import { resolveXbriefOutPaths, XbriefPathError } from "./paths.js";
+import { MD_REQUIRED_SECTIONS, parseMarkdownMeta } from "./styles.js";
+import { DEFAULT_XBRIEF_SIZE_CAP_BYTES, isXbriefFormat, isXbriefStyle, } from "./types.js";
+export const VERIFY_USAGE = "Usage: deft xbrief:verify -- --format <json|md|both> --out <path> [--style <scope|playbook|mission|project>] [--project-root <dir>]\n" +
+    "  Verify a dense xBRIEF artifact at --out. Required: --format and --out.\n" +
+    "  verify ≠ lifecycle: does not promote/activate/complete (use scope:* for lifecycle).\n";
+function fail(stderr, exitCode = 1) {
+    return { exitCode, stdout: "", stderr };
+}
+function parseFlagValue(argv, i, name) {
+    const eq = argv[i]?.startsWith(`${name}=`) ? argv[i].slice(name.length + 1) : undefined;
+    if (eq !== undefined) {
+        if (eq.length === 0)
+            return { error: `argument ${name}: expected one argument\n` };
+        return { value: eq, next: i };
+    }
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("-")) {
+        return { error: `argument ${name}: expected one argument\n` };
+    }
+    return { value: next, next: i + 1 };
+}
+/** Parse verify CLI argv into options (or error string). */
+export function parseVerifyArgv(argv) {
+    let format;
+    let out;
+    let style;
+    let projectRoot = process.cwd();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "-h" || arg === "--help") {
+            return { error: VERIFY_USAGE };
+        }
+        if (arg === "--format" || arg.startsWith("--format=")) {
+            const parsed = parseFlagValue(argv, i, "--format");
+            if ("error" in parsed)
+                return parsed;
+            format = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--out" || arg.startsWith("--out=")) {
+            const parsed = parseFlagValue(argv, i, "--out");
+            if ("error" in parsed)
+                return parsed;
+            out = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--style" || arg.startsWith("--style=")) {
+            const parsed = parseFlagValue(argv, i, "--style");
+            if ("error" in parsed)
+                return parsed;
+            style = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--project-root" || arg.startsWith("--project-root=")) {
+            const parsed = parseFlagValue(argv, i, "--project-root");
+            if ("error" in parsed)
+                return parsed;
+            projectRoot = parsed.value;
+            i = parsed.next;
+            continue;
+        }
+        if (arg === "--")
+            continue;
+        return { error: `unrecognized argument: ${arg}\n${VERIFY_USAGE}` };
+    }
+    if (format === undefined) {
+        return { error: `missing required --format (json|md|both)\n${VERIFY_USAGE}` };
+    }
+    if (!isXbriefFormat(format)) {
+        return { error: `invalid --format ${format} (expected json|md|both)\n${VERIFY_USAGE}` };
+    }
+    if (out === undefined || out.length === 0) {
+        return { error: `missing required --out\n${VERIFY_USAGE}` };
+    }
+    if (style !== undefined && !isXbriefStyle(style)) {
+        return {
+            error: `invalid --style ${style} (expected scope|playbook|mission|project)\n${VERIFY_USAGE}`,
+        };
+    }
+    return {
+        format,
+        out,
+        style: style,
+        projectRoot,
+    };
+}
+function readText(path, sizeCap) {
+    if (!existsSync(path)) {
+        return { error: `missing file: ${path}\n` };
+    }
+    try {
+        const st = statSync(path);
+        if (!st.isFile()) {
+            return { error: `not a file: ${path}\n` };
+        }
+        if (st.size > sizeCap) {
+            return { error: `file exceeds size cap (${sizeCap} bytes): ${path}\n` };
+        }
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `failed to read ${path}: ${msg}\n` };
+    }
+}
+function parseJsonDoc(text, label) {
+    try {
+        const data = JSON.parse(text);
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            return { ok: false, error: `${label}: JSON root must be an object\n` };
+        }
+        return { ok: true, doc: data };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `${label}: invalid JSON (${msg})\n` };
+    }
+}
+function resolveStyle(explicit, doc, mdStyle) {
+    if (explicit !== undefined)
+        return explicit;
+    if (doc !== null) {
+        const meta = doc.plan.metadata;
+        if (typeof meta === "object" && meta !== null && !Array.isArray(meta)) {
+            const kind = meta.kind;
+            if (typeof kind === "string" && isXbriefStyle(kind))
+                return kind;
+        }
+    }
+    if (mdStyle !== null && isXbriefStyle(mdStyle))
+        return mdStyle;
+    return "scope";
+}
+/** Core verify implementation (testable). */
+export function verifyXbrief(options) {
+    let paths;
+    try {
+        paths = resolveXbriefOutPaths({
+            projectRoot: options.projectRoot,
+            out: options.out,
+            format: options.format,
+            cwd: options.cwd,
+            home: options.home,
+            env: options.env,
+        });
+    }
+    catch (err) {
+        if (err instanceof XbriefPathError) {
+            return fail(`${err.message}\n`, 1);
+        }
+        throw err;
+    }
+    const sizeCap = options.sizeCapBytes ?? DEFAULT_XBRIEF_SIZE_CAP_BYTES;
+    const errors = [];
+    let doc = null;
+    let mdMeta = null;
+    if (paths.jsonAbs !== null) {
+        const text = readText(paths.jsonAbs, sizeCap);
+        if (typeof text !== "string") {
+            errors.push(text.error.trimEnd());
+        }
+        else {
+            const parsed = parseJsonDoc(text, paths.jsonAbs);
+            if (!parsed.ok) {
+                errors.push(parsed.error.trimEnd());
+            }
+            else {
+                doc = parsed.doc;
+                const schemaErrors = validateVbriefSchema(doc, paths.jsonAbs);
+                for (const e of schemaErrors)
+                    errors.push(e);
+            }
+        }
+    }
+    if (paths.mdAbs !== null) {
+        const text = readText(paths.mdAbs, sizeCap);
+        if (typeof text !== "string") {
+            errors.push(text.error.trimEnd());
+        }
+        else {
+            mdMeta = parseMarkdownMeta(text);
+            const style = resolveStyle(options.style, doc, mdMeta.style);
+            const required = MD_REQUIRED_SECTIONS[style];
+            for (const section of required) {
+                if (!mdMeta.sections.has(section)) {
+                    errors.push(`${paths.mdAbs}: missing required markdown section '## ${section}' (style=${style})`);
+                }
+            }
+            if (mdMeta.title === null || mdMeta.title.length === 0) {
+                errors.push(`${paths.mdAbs}: missing title`);
+            }
+            if (mdMeta.status === null || mdMeta.status.length === 0) {
+                errors.push(`${paths.mdAbs}: missing status`);
+            }
+        }
+    }
+    // both: stem/title/id consistency between json + md
+    if (options.format === "both" && doc !== null && mdMeta !== null) {
+        if (mdMeta.title !== null && mdMeta.title !== doc.plan.title) {
+            errors.push(`title mismatch: json=${JSON.stringify(doc.plan.title)} md=${JSON.stringify(mdMeta.title)}`);
+        }
+        if (mdMeta.status !== null && mdMeta.status !== String(doc.plan.status)) {
+            errors.push(`status mismatch: json=${JSON.stringify(doc.plan.status)} md=${JSON.stringify(mdMeta.status)}`);
+        }
+        const jsonId = typeof doc.plan.id === "string" ? doc.plan.id : null;
+        if (jsonId !== null && mdMeta.id !== null && jsonId !== mdMeta.id) {
+            errors.push(`id mismatch: json=${JSON.stringify(jsonId)} md=${JSON.stringify(mdMeta.id)}`);
+        }
+    }
+    if (errors.length > 0) {
+        return fail(`xbrief:verify failed:\n${errors.map((e) => `  - ${e}`).join("\n")}\n`, 1);
+    }
+    const checked = [paths.jsonAbs, paths.mdAbs].filter((p) => p !== null);
+    const lines = [
+        `OK xbrief:verify format=${options.format}`,
+        ...checked.map((p) => `  checked ${p}`),
+        "  note: verify is not a lifecycle move (scope:* handles promote/activate/complete)",
+    ];
+    return { exitCode: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+}
+/** CLI entry for dispatch wrapper. */
+export function runXbriefVerifyCli(argv) {
+    const parsed = parseVerifyArgv(argv);
+    if ("error" in parsed) {
+        const isHelp = parsed.error === VERIFY_USAGE;
+        return {
+            exitCode: isHelp ? 0 : 2,
+            stdout: isHelp ? VERIFY_USAGE : "",
+            stderr: isHelp ? "" : parsed.error,
+        };
+    }
+    return verifyXbrief(parsed);
+}
+//# sourceMappingURL=verify.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.92.0",
+  "version": "0.93.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,10 @@
       "types": "./dist/story-ready/index.d.ts",
       "default": "./dist/story-ready/index.js"
     },
+    "./slash": {
+      "types": "./dist/slash/index.d.ts",
+      "default": "./dist/slash/index.js"
+    },
     "./branch": {
       "types": "./dist/branch/index.d.ts",
       "default": "./dist/branch/index.js"
@@ -55,6 +59,10 @@
       "types": "./dist/xbrief-migrate/index.d.ts",
       "default": "./dist/xbrief-migrate/index.js"
     },
+    "./xbrief": {
+      "types": "./dist/xbrief/index.d.ts",
+      "default": "./dist/xbrief/index.js"
+    },
     "./category-b-namespace": {
       "types": "./dist/category-b-namespace/index.d.ts",
       "default": "./dist/category-b-namespace/index.js"
@@ -334,8 +342,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.92.0",
-    "@deftai/directive-types": "^0.92.0",
+    "@deftai/directive-content": "^0.93.0",
+    "@deftai/directive-types": "^0.93.0",
     "archiver": "^8.0.0"
   },
   "scripts": {