@forwardimpact/libsyntheticprose 0.1.2 → 0.1.4

package/engine/pathway.js

@@ -18,6 +18,10 @@ import { buildCapabilityPrompt } from "../prompts/pathway/capability.js";
 import { buildDriverPrompt } from "../prompts/pathway/driver.js";
 import { buildDisciplinePrompt } from "../prompts/pathway/discipline.js";
 import { buildTrackPrompt } from "../prompts/pathway/track.js";
+import {
+  PROFICIENCY_LEVELS,
+  MATURITY_LEVELS,
+} from "@forwardimpact/libsyntheticgen/vocabulary.js";
 
 /**
  * Load JSON schemas from the schema directory.
@@ -99,7 +103,10 @@ async function generatePathwayData({
   schemas,
   proseEngine,
 }) {
-  const ctx = { domain, industry };
+  const frameworkName = framework.name || domain;
+  const ctx = { domain, industry, frameworkName };
+  const BASE_TOKENS = 2000;
+  const PER_SKILL_TOKENS = 800;
 
   // 1. Framework metadata
   const fw = await generateEntity(
@@ -107,6 +114,7 @@ async function generatePathwayData({
     "framework",
     buildFrameworkPrompt(framework, ctx, schemas.framework),
     proseEngine,
+    { maxTokens: BASE_TOKENS },
   );
 
   // 2. Levels
@@ -123,15 +131,19 @@ async function generatePathwayData({
     "stages",
     buildStagePrompt(framework.stages, ctx, schemas.stages),
     proseEngine,
+    { maxTokens: BASE_TOKENS },
   );
 
-  // 4. Behaviours (parallel — no cross-references)
+  // Build prior output context for downstream prompts
+  const priorOutput = { levels };
+
+  // 4. Behaviours (parallel — receive level context)
   const behaviours = await Promise.all(
     framework.behaviours.map((b) =>
       generateEntity(
         "behaviour",
         b.id,
-        buildBehaviourPrompt(b, ctx, schemas.behaviour),
+        buildBehaviourPrompt(b, ctx, schemas.behaviour, priorOutput),
         proseEngine,
       ).then((data) => ({
         ...data,
@@ -140,7 +152,9 @@ async function generatePathwayData({
     ),
   );
 
-  // 5. Capabilities with skills (parallel)
+  priorOutput.behaviours = behaviours;
+
+  // 5. Capabilities with skills (parallel — receive level + behaviour context)
   const capabilities = await Promise.all(
     framework.capabilities.map((c, i) =>
       generateEntity(
@@ -150,8 +164,10 @@ async function generatePathwayData({
           { ...c, ordinalRank: i + 1 },
           ctx,
           schemas.capability,
+          priorOutput,
         ),
         proseEngine,
+        { maxTokens: BASE_TOKENS + (c.skills || []).length * PER_SKILL_TOKENS },
       ).then((data) => ({
         ...data,
         _id: c.id,
@@ -159,6 +175,8 @@ async function generatePathwayData({
     ),
   );
 
+  priorOutput.capabilities = capabilities;
+
   // Collect all skill IDs and behaviour IDs from DSL declarations
   // (not from LLM output — these must be available even in no-prose mode)
   const skillIds = framework.capabilities.flatMap((c) => c.skills || []);
@@ -174,6 +192,7 @@ async function generatePathwayData({
       schemas.drivers,
     ),
     proseEngine,
+    { maxTokens: BASE_TOKENS },
   );
 
   // 7. Disciplines (reference skills, behaviours, track IDs from DSL)
@@ -187,6 +206,7 @@ async function generatePathwayData({
           d,
           { ...ctx, skillIds, behaviourIds, trackIds },
           schemas.discipline,
+          priorOutput,
         ),
         proseEngine,
       ).then((data) => ({
@@ -207,6 +227,7 @@ async function generatePathwayData({
           t,
           { ...ctx, capabilityIds, skillIds, behaviourIds },
           schemas.track,
+          priorOutput,
         ),
         proseEngine,
       ).then((data) => ({
@@ -245,12 +266,22 @@ async function generatePathwayData({
  * @param {import('./prose.js').ProseEngine} proseEngine - Prose engine
  * @returns {Promise<object|null>} Parsed JSON data
  */
-async function generateEntity(entityType, entityId, prompt, proseEngine) {
+async function generateEntity(
+  entityType,
+  entityId,
+  prompt,
+  proseEngine,
+  { maxTokens } = {},
+) {
   const key = `pathway:${entityType}:${entityId}`;
-  const result = await proseEngine.generateJson(key, [
-    { role: "system", content: prompt.system },
-    { role: "user", content: prompt.user },
-  ]);
+  const result = await proseEngine.generateJson(
+    key,
+    [
+      { role: "system", content: prompt.system },
+      { role: "user", content: prompt.user },
+    ],
+    maxTokens ? { maxTokens } : undefined,
+  );
   return result;
 }
 
@@ -302,20 +333,8 @@ function jitter(rng, base, max) {
  * @returns {object[]}
  */
 function generateSelfAssessments(framework, skillIds, behaviourIds) {
-  const proficiencies = framework.proficiencies || [
-    "awareness",
-    "foundational",
-    "working",
-    "practitioner",
-    "expert",
-  ];
-  const maturities = framework.maturities || [
-    "emerging",
-    "developing",
-    "practicing",
-    "role_modeling",
-    "exemplifying",
-  ];
+  const proficiencies = framework.proficiencies || PROFICIENCY_LEVELS;
+  const maturities = framework.maturities || MATURITY_LEVELS;
 
   const seed = framework.seed || 1;
   const rng = createRng(seed);
@@ -325,10 +344,18 @@ function generateSelfAssessments(framework, skillIds, behaviourIds) {
   const assessments = [];
   const levelNames = ["junior", "mid", "senior", "staff", "principal"];
 
+  // Track previous level's indices per skill/behaviour to enforce monotonicity
+  const prevSkillIdx = {};
+  const prevBehIdx = {};
+
   for (let i = 0; i < Math.min(levelNames.length, proficiencies.length); i++) {
     const skillProficiencies = {};
     for (const skillId of skillIds) {
-      skillProficiencies[skillId] = proficiencies[jitter(rng, i, maxP)];
+      const raw = jitter(rng, i, maxP);
+      const floor = prevSkillIdx[skillId] ?? 0;
+      const idx = Math.max(floor, raw);
+      skillProficiencies[skillId] = proficiencies[idx];
+      prevSkillIdx[skillId] = idx;
     }
 
     const behaviourMaturities = {};
@@ -339,8 +366,11 @@ function generateSelfAssessments(framework, skillIds, behaviourIds) {
       if (r < 0.55) offset = 0;
       else if (r < 0.8) offset = 1;
       else offset = -1;
-      behaviourMaturities[behaviourId] =
-        maturities[Math.max(0, Math.min(maxM, i + offset))];
+      const raw = Math.max(0, Math.min(maxM, i + offset));
+      const floor = prevBehIdx[behaviourId] ?? 0;
+      const idx = Math.max(floor, raw);
+      behaviourMaturities[behaviourId] = maturities[idx];
+      prevBehIdx[behaviourId] = idx;
     }
 
     assessments.push({

package/engine/prose.js

@@ -17,7 +17,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 export class ProseEngine {
   /**
    * @param {object} options
-   * @param {string} options.cachePath      Path to .prose-cache.json
+   * @param {string} options.cachePath      Path to prose cache JSON file
    * @param {string} options.mode           "cached" | "generate" | "no-prose"
    * @param {boolean} [options.strict]      Fail on cache miss
    * @param {import('@forwardimpact/libllm').LlmApi} options.llmApi
@@ -108,7 +108,7 @@ export class ProseEngine {
    * @param {object[]} messages - Pre-built messages array [{role, content}]
    * @returns {Promise<string|null>}
    */
-  async generateStructured(key, messages) {
+  async generateStructured(key, messages, { maxTokens = 4000 } = {}) {
     if (this.mode === "no-prose") return null;
 
     const cacheKey = generateHash(key, JSON.stringify(messages));
@@ -127,7 +127,7 @@ export class ProseEngine {
 
     const response = await this.llmApi.createCompletions({
       messages,
-      max_tokens: 4000,
+      max_tokens: maxTokens,
     });
     const content = response.choices?.[0]?.message?.content?.trim() || null;
     this.stats.generated++;
@@ -147,8 +147,8 @@ export class ProseEngine {
    * @param {object[]} messages - Pre-built messages array
    * @returns {Promise<object|null>}
    */
-  async generateJson(key, messages) {
-    const raw = await this.generateStructured(key, messages);
+  async generateJson(key, messages, options) {
+    const raw = await this.generateStructured(key, messages, options);
     if (!raw) return null;
     const cleaned = raw
       .replace(/^```(?:json)?\s*\n?/m, "")
@@ -183,6 +183,7 @@ export class ProseEngine {
       tone: context.tone || "technical",
       length: context.length || "2-3 paragraphs",
       domain: context.domain,
+      orgName: context.orgName,
       role: context.role,
       audience: context.audience,
       scenario: context.scenario,
@@ -209,7 +210,7 @@ export class ProseEngine {
 /**
  * Creates a ProseEngine with real dependencies wired.
  * @param {object} options
- * @param {string} options.cachePath - Path to .prose-cache.json
+ * @param {string} options.cachePath - Path to prose cache JSON file
  * @param {string} options.mode - "cached" | "generate" | "no-prose"
  * @param {boolean} [options.strict] - Fail on cache miss
  * @param {import('@forwardimpact/libllm').LlmApi} [options.llmApi] - LLM client

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libsyntheticprose",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "LLM-based prose and pathway generation for synthetic data",
   "license": "Apache-2.0",
   "repository": {

package/prompts/pathway/behaviour.js

@@ -1,3 +1,6 @@
+import { buildPreamble } from "./preamble.js";
+import { MATURITY_LEVELS } from "@forwardimpact/libsyntheticgen/vocabulary.js";
+
 /**
  * Prompt template for a single behaviour entity.
  *
@@ -6,14 +9,17 @@
  * @param {object} schema - JSON schema for behaviour
  * @returns {{ system: string, user: string }}
  */
-export function buildBehaviourPrompt(skeleton, ctx, schema) {
+export function buildBehaviourPrompt(skeleton, ctx, schema, priorOutput) {
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate a behaviour definition for a career framework.",
@@ -29,13 +35,27 @@ export function buildBehaviourPrompt(skeleton, ctx, schema) {
       "- name: Use the provided name exactly.",
       "- human.description: 2-3 sentences describing this behaviour.",
       "- human.maturityDescriptions: One paragraph per maturity level",
-      "  (emerging, developing, practicing, role_modeling, exemplifying).",
+      `  (${MATURITY_LEVELS.join(", ")}).`,
       '  Use second-person ("You..."). Each level must show clear',
       "  progression in depth, consistency, and influence.",
       "- agent.title: Short title (2-4 words) for how the agent applies this behaviour.",
       "- agent.workingStyle: 1-2 sentences describing how the AI agent should embody",
       "  this behaviour in its work style and communication.",
       "",
+      ...(priorOutput?.levels
+        ? [
+            "",
+            "## Previously generated context",
+            "Level titles and proficiency baselines:",
+            ...(Array.isArray(priorOutput.levels)
+              ? priorOutput.levels.map(
+                  (l) =>
+                    `- ${l.id}: ${l.professionalTitle || l.id} (primary: ${l.baseSkillProficiencies?.primary || "N/A"})`,
+                )
+              : []),
+          ]
+        : []),
+      "",
       "Output a single JSON object for this behaviour file.",
     ].join("\n"),
   };

package/prompts/pathway/capability.js

@@ -1,3 +1,9 @@
+import { buildPreamble } from "./preamble.js";
+import {
+  PROFICIENCY_LEVELS,
+  STAGE_NAMES,
+} from "@forwardimpact/libsyntheticgen/vocabulary.js";
+
 /**
  * Prompt template for a single capability entity (with skills).
  *
@@ -6,14 +12,17 @@
  * @param {object} schema - JSON schema for capability
  * @returns {{ system: string, user: string }}
  */
-export function buildCapabilityPrompt(skeleton, ctx, schema) {
+export function buildCapabilityPrompt(skeleton, ctx, schema, priorOutput) {
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate a capability definition for a career framework.",
@@ -36,14 +45,14 @@ export function buildCapabilityPrompt(skeleton, ctx, schema) {
       `- ordinalRank: ${skeleton.ordinalRank}`,
       "- description: 1-2 sentences describing this capability area.",
       "- professionalResponsibilities: One sentence per proficiency level",
-      "  (awareness through expert) describing IC expectations.",
+      `  (${PROFICIENCY_LEVELS.join(" through ")}) describing IC expectations.`,
       "- managementResponsibilities: Same for management track.",
       "- skills: For each skill ID listed above, generate:",
       "  - id: Use the provided skill ID exactly.",
       "  - name: Human-readable name (title case).",
       "  - human.description: 2-3 sentences.",
       "  - human.proficiencyDescriptions: One paragraph per level",
-      "    (awareness, foundational, working, practitioner, expert).",
+      `    (${PROFICIENCY_LEVELS.join(", ")}).`,
       '    Use second-person ("You..."). Each level must show clear',
       "    progression in scope, autonomy, and complexity.",
       "- For each skill, also generate an agent section:",
@@ -51,19 +60,43 @@ export function buildCapabilityPrompt(skeleton, ctx, schema) {
       "  - agent.description: 1 sentence describing what this agent skill provides.",
       "  - agent.useWhen: 1 sentence describing when/why an agent should use this skill.",
       "  - agent.stages: Object with ONLY the stages where this skill is meaningfully relevant.",
-      "    Not all skills need all 6 stages. Use these criteria:",
-      "      - specify: include if the skill informs what to build or constrains requirements",
-      "      - plan: include if the skill drives architecture or design decisions",
-      "      - onboard: include if the skill requires tooling, dependencies, or env setup",
-      "      - code: include if the skill is directly exercised during implementation",
-      "      - review: include if the skill has quality criteria to verify",
-      "      - deploy: include if the skill has production or operational concerns",
+      `    Not all skills need all ${STAGE_NAMES.length} stages. Use these criteria:`,
+      `      - ${STAGE_NAMES[0]}: include if the skill informs what to build or constrains requirements`,
+      `      - ${STAGE_NAMES[1]}: include if the skill drives architecture or design decisions`,
+      `      - ${STAGE_NAMES[2]}: include if the skill requires tooling, dependencies, or env setup`,
+      `      - ${STAGE_NAMES[3]}: include if the skill is directly exercised during implementation`,
+      `      - ${STAGE_NAMES[4]}: include if the skill has quality criteria to verify`,
+      `      - ${STAGE_NAMES[5]}: include if the skill has production or operational concerns`,
       "    Each skill must have at least 2 stages. Omit stages where the skill has no specific guidance.",
       "    Each stage has:",
       "    - focus: 1 sentence — the primary focus for this skill in this stage.",
       "    - readChecklist: Array of 2-3 items — steps to read/understand before acting.",
       "    - confirmChecklist: Array of 2-3 items — items to verify after completing work.",
       "",
+      ...(priorOutput?.levels || priorOutput?.behaviours
+        ? [
+            "",
+            "## Previously generated context",
+            ...(priorOutput.levels && Array.isArray(priorOutput.levels)
+              ? [
+                  "Level titles and proficiency baselines:",
+                  ...priorOutput.levels.map(
+                    (l) =>
+                      `- ${l.id}: ${l.professionalTitle || l.id} (primary: ${l.baseSkillProficiencies?.primary || "N/A"})`,
+                  ),
+                ]
+              : []),
+            ...(priorOutput.behaviours && Array.isArray(priorOutput.behaviours)
+              ? [
+                  "Behaviour names:",
+                  ...priorOutput.behaviours.map(
+                    (b) => `- ${b._id || b.id}: ${b.name || b._id || b.id}`,
+                  ),
+                ]
+              : []),
+          ]
+        : []),
+      "",
       "Output the JSON object for this single capability file.",
     ].join("\n"),
   };

package/prompts/pathway/discipline.js

@@ -1,3 +1,5 @@
+import { buildPreamble } from "./preamble.js";
+
 /**
  * Prompt template for a single discipline entity.
  *
@@ -6,14 +8,17 @@
  * @param {object} schema - JSON schema for discipline
  * @returns {{ system: string, user: string }}
  */
-export function buildDisciplinePrompt(skeleton, ctx, schema) {
+export function buildDisciplinePrompt(skeleton, ctx, schema, priorOutput) {
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate a discipline definition for a career framework.",
@@ -51,10 +56,45 @@ export function buildDisciplinePrompt(skeleton, ctx, schema) {
       "  Include 2-3 behaviour modifiers relevant to this discipline.",
       "- human.roleSummary: 2-3 sentences describing this role. May use {roleTitle} or {specialization}.",
       "- agent.identity: 1-2 sentences defining the AI coding agent's core identity.",
-      "  Frame as 'You are a {roleTitle} agent that...' May use {roleTitle} or {roleName} placeholder.",
+      "  Frame as 'You are a {roleTitle} agent that...' May use {roleTitle} or {specialization} placeholder.",
       "- agent.priority: 1 sentence stating the agent's top priority (e.g., code quality, system reliability).",
       "- agent.constraints: 2-3 things the agent must avoid or never do.",
       "",
+      ...(priorOutput?.levels ||
+      priorOutput?.behaviours ||
+      priorOutput?.capabilities
+        ? [
+            "",
+            "## Previously generated context",
+            ...(priorOutput.levels && Array.isArray(priorOutput.levels)
+              ? [
+                  "Level titles:",
+                  ...priorOutput.levels.map(
+                    (l) => `- ${l.id}: ${l.professionalTitle || l.id}`,
+                  ),
+                ]
+              : []),
+            ...(priorOutput.behaviours && Array.isArray(priorOutput.behaviours)
+              ? [
+                  "Behaviour names:",
+                  ...priorOutput.behaviours.map(
+                    (b) => `- ${b._id || b.id}: ${b.name || b._id || b.id}`,
+                  ),
+                ]
+              : []),
+            ...(priorOutput.capabilities &&
+            Array.isArray(priorOutput.capabilities)
+              ? [
+                  "Capability names and skill IDs:",
+                  ...priorOutput.capabilities.map(
+                    (c) =>
+                      `- ${c._id || c.id}: ${c.name || c._id || c.id} (skills: ${(c.skills || []).map((s) => s.id || s).join(", ")})`,
+                  ),
+                ]
+              : []),
+          ]
+        : []),
+      "",
       "Output a single JSON object for this discipline.",
     ].join("\n"),
   };

package/prompts/pathway/driver.js

@@ -1,3 +1,5 @@
+import { buildPreamble } from "./preamble.js";
+
 /**
  * Prompt template for drivers.yaml — all drivers in a single call.
  *
@@ -18,12 +20,15 @@ export function buildDriverPrompt(drivers, ctx, schema) {
     .join("\n");
 
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate organizational driver definitions for a career framework.",

package/prompts/pathway/framework.js

@@ -1,19 +1,24 @@
+import { buildPreamble } from "./preamble.js";
+
 /**
  * Prompt template for framework.yaml metadata.
  *
  * @param {object} skeleton - Framework skeleton from DSL
- * @param {object} ctx - Universe context (domain, industry)
+ * @param {object} ctx - Universe context (domain, industry, frameworkName)
  * @param {object} schema - JSON schema for framework entity
  * @returns {{ system: string, user: string }}
  */
 export function buildFrameworkPrompt(skeleton, ctx, schema) {
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate a framework metadata file for an engineering career framework.",
@@ -32,6 +37,7 @@ export function buildFrameworkPrompt(skeleton, ctx, schema) {
       "- entityDefinitions: Provide definitions for these entity types:",
       "  driver, skill, behaviour, discipline, level, track, job, agent, stage, tool.",
       "  Each needs: title, emojiIcon, description (1 sentence).",
+      '  IMPORTANT: A "stage" is a lifecycle phase of work delivery (specify, plan, scaffold, code, review, deploy) — NOT a maturity or progression level.',
       "",
       "Output a single JSON object.",
     ].join("\n"),

package/prompts/pathway/level.js

@@ -1,3 +1,9 @@
+import { buildPreamble } from "./preamble.js";
+import {
+  PROFICIENCY_LEVELS,
+  MATURITY_LEVELS,
+} from "@forwardimpact/libsyntheticgen/vocabulary.js";
+
 /**
  * Prompt template for levels.yaml — all levels in a single call.
  *
@@ -15,12 +21,15 @@ export function buildLevelPrompt(levels, ctx, schema) {
     .join("\n");
 
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate career level definitions for an engineering pathway.",
@@ -44,9 +53,9 @@ export function buildLevelPrompt(levels, ctx, schema) {
       "  - qualificationSummary: 2-3 sentences describing qualifications.",
       "    May use {typicalExperienceRange} placeholder.",
       "  - baseSkillProficiencies: { primary, secondary, broad } using",
-      "    awareness/foundational/working/practitioner/expert.",
-      "    Increase across levels (L1→awareness, L5→expert for primary).",
-      "  - baseBehaviourMaturity: emerging/developing/practicing/role_modeling/exemplifying.",
+      `    ${PROFICIENCY_LEVELS.join("/")}.`,
+      `    Increase across levels (L1→${PROFICIENCY_LEVELS[0]}, L5→${PROFICIENCY_LEVELS.at(-1)} for primary).`,
+      `  - baseBehaviourMaturity: ${MATURITY_LEVELS.join("/")}.`,
       "    Increase across levels.",
       "  - expectations: { impactScope, autonomyExpectation, influenceScope, complexityHandled }.",
       "    Each 1 sentence showing clear progression.",

package/prompts/pathway/preamble.js

@@ -0,0 +1,26 @@
+/**
+ * Shared system preamble for all pathway prompt builders.
+ *
+ * Establishes consistent voice, terminology, and naming conventions
+ * across all 8 entity prompt builders.
+ */
+
+import {
+  PROFICIENCY_LEVELS,
+  MATURITY_LEVELS,
+} from "@forwardimpact/libsyntheticgen/vocabulary.js";
+
+/**
+ * Build a shared system preamble for pathway prompt builders.
+ * @param {string} frameworkName - Name of the framework (or domain fallback)
+ * @returns {string}
+ */
+export function buildPreamble(frameworkName) {
+  return [
+    `You are writing content for the "${frameworkName}" engineering career framework.`,
+    `Use these exact proficiency level names: ${PROFICIENCY_LEVELS.join(", ")}.`,
+    `Use these exact maturity level names: ${MATURITY_LEVELS.join(", ")}.`,
+    `Write in professional, concise, third-person voice.`,
+    `Use consistent terminology across all entities — prefer precise terms over synonyms.`,
+  ].join("\n");
+}

package/prompts/pathway/stage.js

@@ -1,3 +1,5 @@
+import { buildPreamble } from "./preamble.js";
+
 /**
  * Prompt template for stages.yaml — all stages in a single call.
  *
@@ -8,12 +10,15 @@
  */
 export function buildStagePrompt(stageIds, ctx, schema) {
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate engineering lifecycle stage definitions.",
@@ -28,13 +33,15 @@ export function buildStagePrompt(stageIds, ctx, schema) {
       "## Instructions",
       "- Output a JSON array of stage objects.",
       "- For each stage ID, generate:",
-      "  - id: The stage ID (must be one of: specify, plan, onboard, code, review, deploy).",
+      `  - id: The stage ID (must be one of: ${stageIds.join(", ")}).`,
       '  - name: Human-readable name (e.g., "Specify", "Plan").',
       "  - emojiIcon: A single emoji for this stage.",
       '  - description: 2-3 sentences in second person ("You...").',
       "  - summary: 1 sentence in third person.",
       "  - handoffs: Array of transitions to other stages, each with:",
       "    targetStage, label (button text), prompt (instructions for next stage).",
+      `    targetStage in each handoff MUST be one of the stage IDs listed above: ${stageIds.join(", ")}.`,
+      "    Do not invent stage IDs that are not in the provided list.",
       "  - constraints: 2-3 restrictions on behaviour in this stage.",
       "  - readChecklist: 2-4 Read-Then-Do steps.",
       "  - confirmChecklist: 2-4 Do-Then-Confirm items.",

package/prompts/pathway/track.js

@@ -1,3 +1,5 @@
+import { buildPreamble } from "./preamble.js";
+
 /**
  * Prompt template for a single track entity.
  *
@@ -6,14 +8,17 @@
  * @param {object} schema - JSON schema for track
  * @returns {{ system: string, user: string }}
  */
-export function buildTrackPrompt(skeleton, ctx, schema) {
+export function buildTrackPrompt(skeleton, ctx, schema, priorOutput) {
   return {
-    system: [
-      "You are an expert career framework author.",
-      "Output ONLY valid JSON. No markdown fences, no explanations.",
-      `The organization domain is: ${ctx.domain}.`,
-      `Industry: ${ctx.industry}.`,
-    ].join(" "),
+    system:
+      buildPreamble(ctx.frameworkName || ctx.domain) +
+      "\n\n" +
+      [
+        "You are an expert career framework author.",
+        "Output ONLY valid JSON. No markdown fences, no explanations.",
+        `The organization domain is: ${ctx.domain}.`,
+        `Industry: ${ctx.industry}.`,
+      ].join(" "),
 
     user: [
       "Generate a track definition for a career framework.",
@@ -45,6 +50,41 @@ export function buildTrackPrompt(skeleton, ctx, schema) {
       "- agent.priority: 1 sentence stating the track-specific priority.",
       "- agent.constraints: 1-2 additional constraints specific to this track.",
       "",
+      ...(priorOutput?.levels ||
+      priorOutput?.behaviours ||
+      priorOutput?.capabilities
+        ? [
+            "",
+            "## Previously generated context",
+            ...(priorOutput.levels && Array.isArray(priorOutput.levels)
+              ? [
+                  "Level titles:",
+                  ...priorOutput.levels.map(
+                    (l) => `- ${l.id}: ${l.professionalTitle || l.id}`,
+                  ),
+                ]
+              : []),
+            ...(priorOutput.behaviours && Array.isArray(priorOutput.behaviours)
+              ? [
+                  "Behaviour names:",
+                  ...priorOutput.behaviours.map(
+                    (b) => `- ${b._id || b.id}: ${b.name || b._id || b.id}`,
+                  ),
+                ]
+              : []),
+            ...(priorOutput.capabilities &&
+            Array.isArray(priorOutput.capabilities)
+              ? [
+                  "Capability names and skill IDs:",
+                  ...priorOutput.capabilities.map(
+                    (c) =>
+                      `- ${c._id || c.id}: ${c.name || c._id || c.id} (skills: ${(c.skills || []).map((s) => s.id || s).join(", ")})`,
+                  ),
+                ]
+              : []),
+          ]
+        : []),
+      "",
       "Output a single JSON object for this track.",
     ].join("\n"),
   };

package/prompts/prose-user.prompt.md

@@ -1,5 +1,7 @@
-Write {{length}} of {{tone}} prose about: {{topic}}. {{#domain}} Company domain:
-{{domain}}. {{/domain}} {{#role}} Written from the perspective of: {{role}}.
+Write {{length}} of {{tone}} prose about: {{topic}}. {{#orgName}} Company name:
+{{orgName}} (always use this exact capitalization). {{/orgName}} {{#domain}}
+Company domain: {{domain}} (use only in URLs, never as the company name in
+prose). {{/domain}} {{#role}} Written from the perspective of: {{role}}.
 {{/role}} {{#audience}} Target audience: {{audience}}. {{/audience}}
 {{#scenario}} Context: during "{{scenario}}", the {{driver}} driver is
 {{direction}} (magnitude: {{magnitude}}). {{/scenario}} Output the text only, no

package/test/pathway-generator.test.js

@@ -0,0 +1,176 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { PathwayGenerator } from "../engine/pathway.js";
+
+function makeLogger() {
+  return {
+    info: () => {},
+    debug: () => {},
+    warn: () => {},
+    error: () => {},
+  };
+}
+
+/**
+ * Mock ProseEngine that returns fixture data for each entity type.
+ */
+function makeMockProseEngine() {
+  return {
+    generateJson: async (key) => {
+      if (key.includes("framework")) {
+        return { title: "Test", emojiIcon: "🏗️", tag: "#test" };
+      }
+      if (key.includes("levels")) {
+        return [
+          {
+            id: "J040",
+            professionalTitle: "Engineer",
+            baseSkillProficiencies: { primary: "awareness" },
+          },
+        ];
+      }
+      if (key.includes("stages")) {
+        return [{ id: "specify", name: "Specify" }];
+      }
+      if (key.includes("behaviour")) {
+        return { name: "Collaboration" };
+      }
+      if (key.includes("capability")) {
+        return {
+          name: "Coding",
+          skills: [{ id: "python", name: "Python" }],
+        };
+      }
+      if (key.includes("drivers")) {
+        return [{ id: "clear_direction", name: "Clear Direction" }];
+      }
+      if (key.includes("discipline")) {
+        return { roleTitle: "Software Engineer" };
+      }
+      if (key.includes("track")) {
+        return { name: "Backend" };
+      }
+      return null;
+    },
+  };
+}
+
+describe("PathwayGenerator", () => {
+  test("requires proseEngine and logger", () => {
+    assert.throws(() => new PathwayGenerator(null, makeLogger()));
+    assert.throws(() => new PathwayGenerator(makeMockProseEngine(), null));
+  });
+
+  test("generates all entity types", async () => {
+    const generator = new PathwayGenerator(makeMockProseEngine(), makeLogger());
+
+    const framework = {
+      name: "Test",
+      levels: [{ id: "J040", professionalTitle: "Engineer", rank: 1 }],
+      stages: ["specify", "plan"],
+      behaviours: [{ id: "collab", name: "Collaboration" }],
+      capabilities: [{ id: "coding", name: "Coding", skills: ["python"] }],
+      drivers: [
+        { id: "clear_direction", name: "Clear Direction", skills: ["python"] },
+      ],
+      disciplines: [
+        {
+          id: "se",
+          roleTitle: "Software Engineer",
+          core: ["python"],
+          supporting: [],
+          broad: [],
+        },
+      ],
+      tracks: [{ id: "backend", name: "Backend" }],
+      seed: 42,
+    };
+
+    const schemas = {
+      framework: {},
+      levels: {},
+      stages: {},
+      behaviour: {},
+      capability: {},
+      drivers: {},
+      discipline: {},
+      track: {},
+      "self-assessments": {},
+      defs: {},
+    };
+
+    const result = await generator.generate({
+      framework,
+      domain: "test.example",
+      industry: "pharma",
+      schemas,
+    });
+
+    assert.ok(result.framework);
+    assert.ok(result.levels);
+    assert.ok(result.stages);
+    assert.ok(Array.isArray(result.behaviours));
+    assert.ok(Array.isArray(result.capabilities));
+    assert.ok(result.drivers);
+    assert.ok(Array.isArray(result.disciplines));
+    assert.ok(Array.isArray(result.tracks));
+    assert.ok(Array.isArray(result.selfAssessments));
+  });
+
+  test("self-assessments use vocabulary constants", async () => {
+    const generator = new PathwayGenerator(makeMockProseEngine(), makeLogger());
+
+    const framework = {
+      name: "Test",
+      levels: [{ id: "J040", rank: 1 }],
+      stages: ["specify"],
+      behaviours: [{ id: "collab", name: "Collaboration" }],
+      capabilities: [{ id: "coding", name: "Coding", skills: ["python"] }],
+      drivers: [],
+      disciplines: [],
+      tracks: [],
+      seed: 42,
+    };
+    const schemas = {
+      framework: {},
+      levels: {},
+      stages: {},
+      behaviour: {},
+      capability: {},
+      drivers: {},
+      discipline: {},
+      track: {},
+    };
+
+    const result = await generator.generate({
+      framework,
+      domain: "test.example",
+      industry: "pharma",
+      schemas,
+    });
+
+    const validProficiencies = new Set([
+      "awareness",
+      "foundational",
+      "working",
+      "practitioner",
+      "expert",
+    ]);
+    const validMaturities = new Set([
+      "emerging",
+      "developing",
+      "practicing",
+      "role_modeling",
+      "exemplifying",
+    ]);
+
+    for (const sa of result.selfAssessments) {
+      for (const val of Object.values(sa.skillProficiencies)) {
+        assert.ok(validProficiencies.has(val), `Invalid proficiency: ${val}`);
+      }
+      for (const val of Object.values(sa.behaviourMaturities)) {
+        assert.ok(validMaturities.has(val), `Invalid maturity: ${val}`);
+      }
+    }
+  });
+});

package/test/prompt-builders.test.js

@@ -0,0 +1,249 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { buildFrameworkPrompt } from "../prompts/pathway/framework.js";
+import { buildLevelPrompt } from "../prompts/pathway/level.js";
+import { buildStagePrompt } from "../prompts/pathway/stage.js";
+import { buildBehaviourPrompt } from "../prompts/pathway/behaviour.js";
+import { buildCapabilityPrompt } from "../prompts/pathway/capability.js";
+import { buildDriverPrompt } from "../prompts/pathway/driver.js";
+import { buildDisciplinePrompt } from "../prompts/pathway/discipline.js";
+import { buildTrackPrompt } from "../prompts/pathway/track.js";
+
+const CTX = {
+  domain: "test.example",
+  industry: "pharma",
+  frameworkName: "Test Framework",
+};
+
+const SCHEMA = { type: "object", properties: {} };
+
+describe("prompt builders", () => {
+  describe("buildFrameworkPrompt", () => {
+    test("returns system and user strings", () => {
+      const result = buildFrameworkPrompt({}, CTX, SCHEMA);
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("includes preamble in system prompt", () => {
+      const result = buildFrameworkPrompt({}, CTX, SCHEMA);
+      assert.ok(result.system.includes("Test Framework"));
+    });
+
+    test("includes JSON schema in user prompt", () => {
+      const result = buildFrameworkPrompt({}, CTX, SCHEMA);
+      assert.ok(result.user.includes('"type"'));
+    });
+  });
+
+  describe("buildLevelPrompt", () => {
+    const levels = [
+      { id: "J040", professionalTitle: "Engineer", rank: 1, experience: "0-2" },
+      {
+        id: "J050",
+        professionalTitle: "Senior",
+        rank: 2,
+        experience: "2-5",
+      },
+    ];
+
+    test("returns system and user strings", () => {
+      const result = buildLevelPrompt(levels, CTX, SCHEMA);
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("includes level IDs in user prompt", () => {
+      const result = buildLevelPrompt(levels, CTX, SCHEMA);
+      assert.ok(result.user.includes("J040"));
+      assert.ok(result.user.includes("J050"));
+    });
+
+    test("uses vocabulary imports for proficiency names", () => {
+      const result = buildLevelPrompt(levels, CTX, SCHEMA);
+      assert.ok(result.user.includes("awareness"));
+      assert.ok(result.user.includes("expert"));
+    });
+  });
+
+  describe("buildStagePrompt", () => {
+    const stageIds = ["specify", "plan", "code"];
+
+    test("returns system and user strings", () => {
+      const result = buildStagePrompt(stageIds, CTX, SCHEMA);
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("includes stage IDs in user prompt", () => {
+      const result = buildStagePrompt(stageIds, CTX, SCHEMA);
+      for (const id of stageIds) {
+        assert.ok(result.user.includes(id));
+      }
+    });
+
+    test("includes handoff constraint", () => {
+      const result = buildStagePrompt(stageIds, CTX, SCHEMA);
+      assert.ok(result.user.includes("MUST be one of the stage IDs"));
+    });
+  });
+
+  describe("buildBehaviourPrompt", () => {
+    const skeleton = { id: "collaboration", name: "Collaboration" };
+
+    test("returns system and user strings", () => {
+      const result = buildBehaviourPrompt(skeleton, CTX, SCHEMA);
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("includes behaviour ID", () => {
+      const result = buildBehaviourPrompt(skeleton, CTX, SCHEMA);
+      assert.ok(result.user.includes("collaboration"));
+    });
+
+    test("includes prior output when provided", () => {
+      const priorOutput = {
+        levels: [
+          {
+            id: "L1",
+            professionalTitle: "Engineer",
+            baseSkillProficiencies: { primary: "awareness" },
+          },
+        ],
+      };
+      const result = buildBehaviourPrompt(skeleton, CTX, SCHEMA, priorOutput);
+      assert.ok(result.user.includes("Previously generated context"));
+      assert.ok(result.user.includes("Engineer"));
+    });
+  });
+
+  describe("buildCapabilityPrompt", () => {
+    const skeleton = {
+      id: "coding",
+      name: "Coding",
+      skills: ["python", "java"],
+      ordinalRank: 1,
+    };
+
+    test("returns system and user strings", () => {
+      const result = buildCapabilityPrompt(skeleton, CTX, SCHEMA);
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("includes skill IDs", () => {
+      const result = buildCapabilityPrompt(skeleton, CTX, SCHEMA);
+      assert.ok(result.user.includes("python"));
+      assert.ok(result.user.includes("java"));
+    });
+
+    test("includes prior output when provided", () => {
+      const priorOutput = {
+        levels: [{ id: "L1", professionalTitle: "Junior" }],
+        behaviours: [{ _id: "collab", name: "Collaboration" }],
+      };
+      const result = buildCapabilityPrompt(skeleton, CTX, SCHEMA, priorOutput);
+      assert.ok(result.user.includes("Previously generated context"));
+      assert.ok(result.user.includes("Junior"));
+      assert.ok(result.user.includes("Collaboration"));
+    });
+  });
+
+  describe("buildDriverPrompt", () => {
+    const drivers = [
+      { id: "clear_direction", name: "Clear Direction", skills: ["python"] },
+    ];
+
+    test("returns system and user strings", () => {
+      const result = buildDriverPrompt(
+        drivers,
+        { ...CTX, skillIds: ["python"], behaviourIds: ["collab"] },
+        SCHEMA,
+      );
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("includes driver IDs", () => {
+      const result = buildDriverPrompt(
+        drivers,
+        { ...CTX, skillIds: ["python"], behaviourIds: [] },
+        SCHEMA,
+      );
+      assert.ok(result.user.includes("clear_direction"));
+    });
+  });
+
+  describe("buildDisciplinePrompt", () => {
+    const skeleton = {
+      id: "se",
+      roleTitle: "Software Engineer",
+      specialization: "Backend",
+      isProfessional: true,
+      core: ["python"],
+      supporting: [],
+      broad: [],
+      validTracks: [null],
+    };
+
+    test("returns system and user strings", () => {
+      const result = buildDisciplinePrompt(
+        skeleton,
+        { ...CTX, skillIds: ["python"], behaviourIds: [], trackIds: [] },
+        SCHEMA,
+      );
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("does not reference {roleName} placeholder", () => {
+      const result = buildDisciplinePrompt(
+        skeleton,
+        { ...CTX, skillIds: ["python"], behaviourIds: [], trackIds: [] },
+        SCHEMA,
+      );
+      assert.ok(!result.user.includes("{roleName}"));
+    });
+
+    test("includes prior output when provided", () => {
+      const priorOutput = {
+        levels: [{ id: "L1", professionalTitle: "Junior" }],
+        behaviours: [{ _id: "collab", name: "Collaboration" }],
+        capabilities: [
+          { _id: "coding", name: "Coding", skills: [{ id: "python" }] },
+        ],
+      };
+      const result = buildDisciplinePrompt(
+        skeleton,
+        { ...CTX, skillIds: ["python"], behaviourIds: [], trackIds: [] },
+        SCHEMA,
+        priorOutput,
+      );
+      assert.ok(result.user.includes("Previously generated context"));
+    });
+  });
+
+  describe("buildTrackPrompt", () => {
+    const skeleton = { id: "backend", name: "Backend" };
+
+    test("returns system and user strings", () => {
+      const result = buildTrackPrompt(
+        skeleton,
+        { ...CTX, capabilityIds: ["coding"], behaviourIds: ["collab"] },
+        SCHEMA,
+      );
+      assert.ok(typeof result.system === "string");
+      assert.ok(typeof result.user === "string");
+    });
+
+    test("includes track ID", () => {
+      const result = buildTrackPrompt(
+        skeleton,
+        { ...CTX, capabilityIds: [], behaviourIds: [] },
+        SCHEMA,
+      );
+      assert.ok(result.user.includes("backend"));
+    });
+  });
+});

package/test/prose-engine.test.js

@@ -0,0 +1,156 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { ProseEngine } from "../engine/prose.js";
+
+function makeLogger() {
+  return {
+    info: () => {},
+    debug: () => {},
+    warn: () => {},
+    error: () => {},
+  };
+}
+
+function makePromptLoader() {
+  return {
+    load: () => "system prompt",
+    render: () => "rendered prompt",
+  };
+}
+
+function makeLlmApi(response = "test response") {
+  return {
+    createCompletions: async () => ({
+      choices: [{ message: { content: response } }],
+    }),
+  };
+}
+
+describe("ProseEngine", () => {
+  test("returns null in no-prose mode", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "prose-test-"));
+    try {
+      const engine = new ProseEngine({
+        cachePath: join(tmpDir, "cache.json"),
+        mode: "no-prose",
+        promptLoader: makePromptLoader(),
+        logger: makeLogger(),
+      });
+      const result = await engine.generateProse("test-key", { topic: "test" });
+      assert.strictEqual(result, null);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("returns cached result on cache hit", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "prose-test-"));
+    try {
+      const cacheData = {};
+      // Pre-populate cache with a known hash
+      const cachePath = join(tmpDir, "cache.json");
+      writeFileSync(cachePath, JSON.stringify(cacheData));
+
+      const engine = new ProseEngine({
+        cachePath,
+        mode: "generate",
+        llmApi: makeLlmApi("fresh response"),
+        promptLoader: makePromptLoader(),
+        logger: makeLogger(),
+      });
+
+      // Generate first
+      const r1 = await engine.generateProse("key1", { topic: "test" });
+      assert.strictEqual(r1, "fresh response");
+      assert.strictEqual(engine.stats.generated, 1);
+
+      // Save and reload
+      engine.saveCache();
+
+      const engine2 = new ProseEngine({
+        cachePath,
+        mode: "cached",
+        promptLoader: makePromptLoader(),
+        logger: makeLogger(),
+      });
+
+      const r2 = await engine2.generateProse("key1", { topic: "test" });
+      assert.strictEqual(r2, "fresh response");
+      assert.strictEqual(engine2.stats.hits, 1);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("generateStructured respects maxTokens option", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "prose-test-"));
+    let capturedMaxTokens = null;
+    try {
+      const engine = new ProseEngine({
+        cachePath: join(tmpDir, "cache.json"),
+        mode: "generate",
+        llmApi: {
+          createCompletions: async (opts) => {
+            capturedMaxTokens = opts.max_tokens;
+            return {
+              choices: [{ message: { content: '{"test": true}' } }],
+            };
+          },
+        },
+        promptLoader: makePromptLoader(),
+        logger: makeLogger(),
+      });
+
+      await engine.generateStructured(
+        "test-key",
+        [{ role: "user", content: "test" }],
+        { maxTokens: 2000 },
+      );
+      assert.strictEqual(capturedMaxTokens, 2000);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("generateJson strips markdown fences", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "prose-test-"));
+    try {
+      const engine = new ProseEngine({
+        cachePath: join(tmpDir, "cache.json"),
+        mode: "generate",
+        llmApi: makeLlmApi('```json\n{"key": "value"}\n```'),
+        promptLoader: makePromptLoader(),
+        logger: makeLogger(),
+      });
+
+      const result = await engine.generateJson("test-key", [
+        { role: "user", content: "test" },
+      ]);
+      assert.deepStrictEqual(result, { key: "value" });
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  test("generateJson returns null in no-prose mode", async () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "prose-test-"));
+    try {
+      const engine = new ProseEngine({
+        cachePath: join(tmpDir, "cache.json"),
+        mode: "no-prose",
+        promptLoader: makePromptLoader(),
+        logger: makeLogger(),
+      });
+
+      const result = await engine.generateJson("test-key", [
+        { role: "user", content: "test" },
+      ]);
+      assert.strictEqual(result, null);
+    } finally {
+      rmSync(tmpDir, { recursive: true });
+    }
+  });
+});