markform 0.1.8 → 0.1.9

package/dist/{src-kUggXhN1.mjs → src-DFsC5wwy.mjs}

@@ -1,6 +1,6 @@
 
-import { L as PatchSchema, V as RunModeSchema } from "./coreTypes-DJtu8OOp.mjs";
-import { C as DEFAULT_ROLES, I as getWebSearchConfig, S as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, _ as DEFAULT_MAX_PATCHES_PER_TURN, b as DEFAULT_PRIORITY, d as serialize, g as DEFAULT_MAX_ISSUES_PER_TURN, i as inspect, m as AGENT_ROLE, r as getFieldsForRoles, t as applyPatches, v as DEFAULT_MAX_TURNS, w as DEFAULT_ROLE_INSTRUCTIONS, x as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN } from "./apply-BUU2QcJ2.mjs";
+import { L as PatchSchema, V as RunModeSchema } from "./coreTypes-B1oI7qvV.mjs";
+import { C as DEFAULT_RESEARCH_MAX_PATCHES_PER_TURN, L as getWebSearchConfig, S as DEFAULT_RESEARCH_MAX_ISSUES_PER_TURN, T as DEFAULT_ROLE_INSTRUCTIONS, _ as DEFAULT_MAX_ISSUES_PER_TURN, d as serialize, i as inspect, m as AGENT_ROLE, r as getFieldsForRoles, t as applyPatches, v as DEFAULT_MAX_PATCHES_PER_TURN, w as DEFAULT_ROLES, x as DEFAULT_PRIORITY, y as DEFAULT_MAX_TURNS } from "./apply-B2kt6C2z.mjs";
 import { z } from "zod";
 import Markdoc from "@markdoc/markdoc";
 import YAML from "yaml";
@@ -528,6 +528,10 @@ function isValueEmpty(value) {
 		case "multi_select": return value.selected.length === 0;
 		case "checkboxes": return Object.values(value.values).every((v) => v === "todo" || v === "unfilled");
 		case "table": return value.rows.length === 0;
+		default: {
+			const _exhaustive = value;
+			throw new Error(`Unhandled field value kind: ${_exhaustive.kind}`);
+		}
 	}
 }
 /**
@@ -1751,6 +1755,10 @@ function fieldToJsonSchema(field, docs, options, groupId) {
 		case "multi_select": return multiSelectFieldToJsonSchema(field, docs, opts, groupId);
 		case "checkboxes": return checkboxesFieldToJsonSchema(field, docs, opts, groupId);
 		case "table": return tableFieldToJsonSchema(field, docs, opts, groupId);
+		default: {
+			const _exhaustive = field;
+			throw new Error(`Unhandled field kind: ${_exhaustive.kind}`);
+		}
 	}
 }
 /**
@@ -2387,6 +2395,10 @@ function coerceToFieldPatch(form, fieldId, rawValue) {
 		case "date": return coerceToDate(fieldId, rawValue);
 		case "year": return coerceToYear(fieldId, rawValue);
 		case "table": return coerceToTable(fieldId, rawValue);
+		default: {
+			const _exhaustive = field;
+			throw new Error(`Unhandled field kind: ${_exhaustive.kind}`);
+		}
 	}
 }
 /**
@@ -2523,9 +2535,10 @@ var FormHarness = class {
 	* @param issues - Issues that were shown to the agent (for recording)
 	* @param llmStats - Optional LLM stats for session logging
 	* @param context - Optional context prompts sent to LLM (for session logging)
+	* @param wire - Optional wire format for comprehensive session logging
 	* @returns StepResult after applying patches
 	*/
-	apply(patches, issues, llmStats, context) {
+	apply(patches, issues, llmStats, context, wire) {
 		if (this.state !== "wait") throw new Error(`Cannot apply in state: ${this.state}`);
 		if (patches.length > this.config.maxPatchesPerTurn) throw new Error(`Too many patches: ${patches.length} > ${this.config.maxPatchesPerTurn}`);
 		const applyResult = applyPatches(this.form, patches);
@@ -2534,7 +2547,7 @@ var FormHarness = class {
 		const stepResult = this.computeStepResult(result);
 		stepResult.patchesApplied = patchesActuallyApplied;
 		stepResult.rejectedPatches = applyResult.rejectedPatches;
-		this.recordTurn(issues, patches, result, llmStats, context, applyResult.rejectedPatches);
+		this.recordTurn(issues, patches, result, llmStats, context, applyResult.rejectedPatches, wire);
 		if (stepResult.issues.length === 0 || this.turnNumber >= this.config.maxTurns) this.state = "complete";
 		else this.state = "wait";
 		return stepResult;
@@ -2558,7 +2571,7 @@ var FormHarness = class {
 	/**
 	* Record a turn in the session transcript.
 	*/
-	recordTurn(issues, patches, result, llmStats, context, rejectedPatches) {
+	recordTurn(issues, patches, result, llmStats, context, rejectedPatches, wire) {
 		const hash = sha256(serialize(this.form));
 		const requiredIssueCount = result.issues.filter((i) => i.severity === "required").length;
 		const turn = {
@@ -2577,6 +2590,7 @@ var FormHarness = class {
 		};
 		if (context) turn.context = context;
 		if (llmStats) turn.llm = llmStats;
+		if (wire) turn.wire = wire;
 		this.turns.push(turn);
 	}
 	/**
@@ -2696,14 +2710,14 @@ var MockAgent = class {
 		for (const group of completedForm.schema.groups) for (const field of group.children) this.fieldMap.set(field.id, field);
 	}
 	/**
-	* Generate patches from the completed mock to address issues.
+	* Invoke the fill_form tool using the completed mock to address issues.
 	*
 	* Processes issues in priority order, generating patches for
 	* fields that have values in the completed mock. For fields with no
 	* value (empty optional fields), generates skip_field patches.
 	* Returns AgentResponse with patches but no stats (mock doesn't track LLM usage).
 	*/
-	async generatePatches(issues, _form, maxPatches) {
+	async fillFormTool(issues, _form, maxPatches) {
 		const patches = [];
 		const addressedFields = /* @__PURE__ */ new Set();
 		for (const issue of issues) {
@@ -2750,7 +2764,10 @@ var MockAgent = class {
 			case "date": return value.value !== null;
 			case "year": return value.value !== null;
 			case "table": return value.rows.length > 0;
-			default: return false;
+			default: {
+				const _exhaustive = value;
+				throw new Error(`Unhandled field value kind: ${_exhaustive.kind}`);
+			}
 		}
 	}
 	/**
@@ -2817,7 +2834,10 @@ var MockAgent = class {
 					return patchRow;
 				})
 			};
-			default: return null;
+			default: {
+				const _exhaustive = field;
+				throw new Error(`Unhandled field kind: ${_exhaustive.kind}`);
+			}
 		}
 	}
 };
@@ -7855,11 +7875,14 @@ Guidelines:
 6. For number fields: use appropriate numeric values from verified sources
 7. For single_select: choose one valid option ID
 8. For multi_select: choose one or more valid option IDs
-9. For checkboxes: set appropriate states (done/todo for simple, yes/no for explicit)
+9. For checkboxes: use the appropriate state for the checkbox mode:
+   - Mode "simple": done (checked) or todo (unchecked)
+   - Mode "multi": done, todo, or na (not applicable)
+   - Mode "explicit": yes or no (must explicitly answer)
 
 CRITICAL: Accuracy is more important than completeness. Use skip_field when information cannot be verified.
 
-Always use the generatePatches tool to submit your field values.
+Always use the fill_form tool to submit your field values.
 `;
 /**
 * Web search instructions appended when web search tools are available.
@@ -7878,21 +7901,15 @@ Guidelines:
 5. NEVER fill fields with guessed or assumed information
 `;
 /**
-* Description for the generatePatches tool.
-*
-* This tells the model how to use the patch submission tool.
-*/
-const GENERATE_PATCHES_TOOL_DESCRIPTION = "Generate patches to fill form fields. Each patch sets a field value. Use the field IDs from the issues list. Return patches for all issues you can address.";
-/**
 * Header for the issues section in the context prompt.
 */
 const ISSUES_HEADER = "# Current Form Issues";
 /**
 * Template for the issues intro text.
-* @param maxPatches - Maximum number of patches to generate
+* @param issueCount - Actual number of issues shown
 */
-function getIssuesIntro(maxPatches) {
-	return `You need to address up to ${maxPatches} issues. Here are the current issues:`;
+function getIssuesIntro(issueCount) {
+	return `You need to address ${issueCount} issue${issueCount === 1 ? "" : "s"}. Here are the current issues:`;
 }
 /**
 * Patch format examples by field kind.
@@ -7939,7 +7956,7 @@ function getPatchFormatHint(fieldKind, fieldId, columnIds) {
 */
 const PATCH_FORMAT_INSTRUCTIONS = `# Instructions
 
-Use the generatePatches tool to submit patches for the fields above.
+Use the fill_form tool to submit patches for the fields above.
 Each patch should match the field kind:
 ${Object.entries(PATCH_FORMATS).map(([kind, format]) => `- ${kind}: ${format}`).join("\n")}
 
@@ -7948,6 +7965,16 @@ For table fields, use the column IDs shown in the field schema. Each row is an o
 If you cannot find verifiable information for a field, skip it:
 - skip: { op: "skip_field", fieldId: "...", reason: "Information not available" }`;
 /**
+* Simplified general instructions for use with inline field instructions.
+*
+* When inline field instructions are shown after each issue, we only need
+* general guidance about using the fill_form tool.
+*/
+const GENERAL_INSTRUCTIONS = `# General Instructions
+
+Use the fill_form tool to submit patches for the fields above.
+For table fields, each row is an object with column ID keys.`;
+/**
 * Section headers used when building the composed system prompt.
 */
 const SECTION_HEADERS = {
@@ -7958,6 +7985,19 @@ const SECTION_HEADERS = {
 	additionalContext: "# Additional Context"
 };
 
+//#endregion
+//#region src/harness/toolApi.ts
+/**
+* Tool API Definitions
+*
+* Single source of truth for all LLM tool names, descriptions, and schemas.
+* This file defines the contract between markform and LLM agents.
+*/
+/** The primary tool for filling form fields */
+const FILL_FORM_TOOL_NAME = "fill_form";
+/** Description shown to LLMs for the fill_form tool */
+const FILL_FORM_TOOL_DESCRIPTION = "Fill form fields by submitting patches. Each patch sets a value for one field. Use the field IDs from the issues list. Return patches for all issues you can address.";
+
 //#endregion
 //#region src/harness/liveAgent.ts
 /**
@@ -7989,13 +8029,13 @@ var LiveAgent = class {
 	* Useful for logging what capabilities the agent has.
 	*/
 	getAvailableToolNames() {
-		const tools = ["generatePatches"];
+		const tools = [FILL_FORM_TOOL_NAME];
 		if (this.webSearchTools) tools.push(...Object.keys(this.webSearchTools));
 		tools.push(...Object.keys(this.additionalTools));
 		return [...new Set(tools)];
 	}
 	/**
-	* Generate patches using the LLM.
+	* Invoke the fill_form tool using the LLM.
 	*
 	* Each call is stateless - the full form context is provided fresh each turn.
 	* The form itself carries all state (filled values, remaining issues).
@@ -8006,20 +8046,22 @@ var LiveAgent = class {
 	* @param maxPatches - Maximum patches to generate
 	* @param previousRejections - Rejections from previous turn (helps LLM learn from mistakes)
 	*/
-	async generatePatches(issues, form, maxPatches, previousRejections) {
+	async fillFormTool(issues, form, maxPatches, previousRejections) {
 		const contextPrompt = buildContextPrompt(issues, form, maxPatches, previousRejections);
 		let systemPrompt = buildSystemPrompt(form, this.targetRole, issues);
 		if (this.systemPromptAddition) systemPrompt += "\n\n# Additional Context\n" + this.systemPromptAddition;
 		if (this.enableWebSearch && this.provider && !this.webSearchTools) this.webSearchTools = loadWebSearchTools(this.provider);
 		if (this.webSearchTools && Object.keys(this.webSearchTools).length > 0) systemPrompt += "\n\n" + WEB_SEARCH_INSTRUCTIONS;
-		const tools = wrapToolsWithCallbacks({
-			generatePatches: {
-				description: GENERATE_PATCHES_TOOL_DESCRIPTION,
-				inputSchema: zodSchema(z.object({ patches: z.array(PatchSchema).max(maxPatches).describe("Array of patches. Each patch sets a value for one field.") }))
-			},
+		const fillFormToolDef = {
+			description: FILL_FORM_TOOL_DESCRIPTION,
+			inputSchema: zodSchema(z.object({ patches: z.array(PatchSchema).max(maxPatches).describe("Array of patches. Each patch sets a value for one field.") }))
+		};
+		const rawTools = {
+			[FILL_FORM_TOOL_NAME]: fillFormToolDef,
 			...this.webSearchTools,
 			...this.additionalTools
-		}, this.callbacks);
+		};
+		const tools = wrapToolsWithCallbacks(rawTools, this.callbacks);
 		const modelId = this.model.modelId ?? "unknown";
 		if (this.callbacks?.onLlmCallStart) try {
 			this.callbacks.onLlmCallStart({ model: modelId });
@@ -8043,7 +8085,7 @@ var LiveAgent = class {
 		for (const step of result.steps) for (const toolCall of step.toolCalls) {
 			const count = toolCallCounts.get(toolCall.toolName) ?? 0;
 			toolCallCounts.set(toolCall.toolName, count + 1);
-			if (toolCall.toolName === "generatePatches" && "input" in toolCall) {
+			if (toolCall.toolName === FILL_FORM_TOOL_NAME && "input" in toolCall) {
 				const input = toolCall.input;
 				patches.push(...input.patches);
 			}
@@ -8055,6 +8097,7 @@ var LiveAgent = class {
 		});
 		const requiredRemaining = issues.filter((i) => i.severity === "required").length;
 		const optionalRemaining = issues.filter((i) => i.severity === "recommended").length;
+		const wire = buildWireFormat(systemPrompt, contextPrompt, rawTools, result);
 		const stats = {
 			inputTokens: result.usage?.inputTokens,
 			outputTokens: result.usage?.outputTokens,
@@ -8068,7 +8111,8 @@ var LiveAgent = class {
 			prompts: {
 				system: systemPrompt,
 				context: contextPrompt
-			}
+			},
+			wire
 		};
 		return {
 			patches: patches.slice(0, maxPatches),
@@ -8077,6 +8121,66 @@ var LiveAgent = class {
 	}
 };
 /**
+* Extract tool schemas from tools object for wire format logging.
+* Captures description and inputSchema for each tool.
+*/
+function extractToolSchemas(tools) {
+	const schemas = {};
+	const sortedNames = Object.keys(tools).sort();
+	for (const name$2 of sortedNames) {
+		const tool$1 = tools[name$2];
+		if (tool$1) schemas[name$2] = {
+			description: tool$1.description ?? "",
+			inputSchema: sortObjectKeys(tool$1.inputSchema ?? {})
+		};
+	}
+	return schemas;
+}
+/**
+* Sort object keys recursively for deterministic serialization.
+* This ensures wire format is stable across runs for diffing.
+*/
+function sortObjectKeys(obj) {
+	if (obj === null || typeof obj !== "object") return obj;
+	if (Array.isArray(obj)) return obj.map(sortObjectKeys);
+	const sorted = {};
+	for (const key of Object.keys(obj).sort()) sorted[key] = sortObjectKeys(obj[key]);
+	return sorted;
+}
+/**
+* Build wire format from generateText result.
+* Captures complete request/response for session logging.
+*
+* Uses loose typing to handle AI SDK's complex result structure.
+*/
+function buildWireFormat(systemPrompt, contextPrompt, tools, result) {
+	const steps = result.steps.map((step) => ({
+		toolCalls: step.toolCalls.map((tc) => ({
+			toolName: tc.toolName,
+			input: sortObjectKeys(tc.input)
+		})),
+		toolResults: (step.toolResults ?? []).map((tr) => ({
+			toolName: tr.toolName,
+			result: sortObjectKeys(tr.result)
+		})),
+		text: step.text ?? null
+	}));
+	return {
+		request: {
+			system: systemPrompt,
+			prompt: contextPrompt,
+			tools: extractToolSchemas(tools)
+		},
+		response: {
+			steps,
+			usage: {
+				inputTokens: result.usage?.inputTokens ?? 0,
+				outputTokens: result.usage?.outputTokens ?? 0
+			}
+		}
+	};
+}
+/**
 * Extract doc blocks of a specific tag type for a given ref.
 */
 function getDocBlocks(docs, ref, tag) {
@@ -8147,8 +8251,9 @@ function buildContextPrompt(issues, form, maxPatches, previousRejections) {
 		for (const rejection of previousRejections) {
 			lines.push(`- **Error:** ${rejection.message}`);
 			if (rejection.fieldKind) {
+				lines.push(`  **Correction:** This field is type "${rejection.fieldKind}". Use set_${rejection.fieldKind} instead.`);
 				const hint = getPatchFormatHint(rejection.fieldKind, rejection.fieldId, rejection.columnIds);
-				lines.push(`  **Use instead:** ${hint}`);
+				lines.push(`  **Correct format:** ${hint}`);
 			}
 		}
 		lines.push("");
@@ -8164,7 +8269,7 @@ function buildContextPrompt(issues, form, maxPatches, previousRejections) {
 	lines.push("");
 	lines.push(ISSUES_HEADER);
 	lines.push("");
-	lines.push(getIssuesIntro(maxPatches));
+	lines.push(getIssuesIntro(issues.length));
 	lines.push("");
 	for (const issue of issues) {
 		lines.push(`- **${issue.ref}** (${issue.scope}): ${issue.message}`);
@@ -8178,7 +8283,9 @@ function buildContextPrompt(issues, form, maxPatches, previousRejections) {
 					lines.push(`  Options: ${optionIds}`);
 				}
 				if (field.kind === "checkboxes" && "checkboxMode" in field) lines.push(`  Mode: ${field.checkboxMode ?? "multi"}`);
+				let columnIds;
 				if (field.kind === "table" && "columns" in field && field.columns) {
+					columnIds = field.columns.map((c) => c.id);
 					const columnInfo = field.columns.map((c) => `${c.id}${c.required ? " (required)" : ""}`).join(", ");
 					lines.push(`  Columns: ${columnInfo}`);
 					if (field.minRows !== void 0 || field.maxRows !== void 0) {
@@ -8188,11 +8295,15 @@ function buildContextPrompt(issues, form, maxPatches, previousRejections) {
 						lines.push(`  Rows: ${constraints.join(", ")}`);
 					}
 				}
+				const patchHint = getPatchFormatHint(field.kind, field.id, columnIds);
+				lines.push(`  Set: ${patchHint}`);
+				if (issue.severity === "required") lines.push(`  This field is required.`);
+				else lines.push(`  Skip: { op: "skip_field", fieldId: "${field.id}", reason: "..." }`);
 			}
 		}
 		lines.push("");
 	}
-	lines.push(PATCH_FORMAT_INSTRUCTIONS);
+	lines.push(GENERAL_INSTRUCTIONS);
 	return lines.join("\n");
 }
 /**
@@ -8292,6 +8403,58 @@ function loadWebSearchTools(provider) {
 function createLiveAgent(config) {
 	return new LiveAgent(config);
 }
+/**
+* Build wire format for mock sessions.
+*
+* This captures what WOULD be sent to the LLM in a mock session,
+* enabling git-based testing where prompt changes are visible in diffs.
+*
+* @param form - Current form state
+* @param issues - Issues being addressed
+* @param patches - Patches generated by mock agent
+* @param maxPatches - Max patches per turn
+* @param targetRole - Target role for instructions
+* @param previousRejections - Rejections from previous turn
+*/
+function buildMockWireFormat(form, issues, patches, maxPatches, targetRole = AGENT_ROLE, previousRejections) {
+	const systemPrompt = buildSystemPrompt(form, targetRole, issues);
+	const contextPrompt = buildContextPrompt(issues, form, maxPatches, previousRejections);
+	const tools = { [FILL_FORM_TOOL_NAME]: {
+		description: FILL_FORM_TOOL_DESCRIPTION,
+		inputSchema: sortObjectKeys({
+			type: "object",
+			properties: { patches: {
+				type: "array",
+				items: { $ref: "#/$defs/patch" },
+				description: "Array of patches to apply to the form"
+			} },
+			required: ["patches"],
+			$defs: { patch: { description: "A patch operation (see tool description for full schema)" } }
+		})
+	} };
+	const steps = [{
+		toolCalls: [{
+			toolName: FILL_FORM_TOOL_NAME,
+			input: sortObjectKeys({ patches })
+		}],
+		toolResults: [],
+		text: null
+	}];
+	return {
+		request: {
+			system: systemPrompt,
+			prompt: contextPrompt,
+			tools
+		},
+		response: {
+			steps,
+			usage: {
+				inputTokens: 0,
+				outputTokens: 0
+			}
+		}
+	};
+}
 
 //#endregion
 //#region src/harness/modelResolver.ts
@@ -8566,7 +8729,7 @@ async function fillForm(options) {
 				issues: turnIssues
 			});
 		} catch {}
-		const { patches, stats } = await agent.generatePatches(turnIssues, form, maxPatchesPerTurn, previousRejections);
+		const { patches, stats } = await agent.fillFormTool(turnIssues, form, maxPatchesPerTurn, previousRejections);
 		if (options.callbacks?.onPatchesGenerated) try {
 			options.callbacks.onPatchesGenerated({
 				turnNumber: turnCount + 1,
@@ -8591,7 +8754,7 @@ async function fillForm(options) {
 				contextPrompt: stats.prompts.context
 			};
 		}
-		stepResult = harness.apply(patches, turnIssues, llmStats, context);
+		stepResult = harness.apply(patches, turnIssues, llmStats, context, stats?.wire);
 		const actualPatchesApplied = stepResult.patchesApplied ?? patches.length;
 		totalPatches += actualPatchesApplied;
 		turnCount++;
@@ -8684,7 +8847,7 @@ async function runResearch(form, options) {
 	let totalOutputTokens = 0;
 	let stepResult = harness.step();
 	while (!stepResult.isComplete && !harness.hasReachedMaxTurns()) {
-		const response = await agent.generatePatches(stepResult.issues, harness.getForm(), config.maxPatchesPerTurn);
+		const response = await agent.fillFormTool(stepResult.issues, harness.getForm(), config.maxPatchesPerTurn);
 		if (response.stats?.inputTokens) totalInputTokens += response.stats.inputTokens;
 		if (response.stats?.outputTokens) totalOutputTokens += response.stats.outputTokens;
 		stepResult = harness.apply(response.patches, stepResult.issues);
@@ -8764,7 +8927,7 @@ function validateResearchForm(form) {
 //#endregion
 //#region src/index.ts
 /** Markform version (injected at build time). */
-const VERSION = "0.1.8";
+const VERSION = "0.1.9";
 
 //#endregion
-export { ParseError$1 as A, serializeScopeRef as C, parseCellValue as D, parseForm as E, parseMarkdownTable as O, parseScopeRef as S, formToJsonSchema as T, findFieldById as _, resolveHarnessConfig as a, isFieldRef as b, getProviderNames as c, MockAgent as d, createMockAgent as f, coerceToFieldPatch as g, coerceInputContext as h, runResearch as i, parseRawTable as k, resolveModel as l, createHarness as m, isResearchForm as n, fillForm as o, FormHarness as p, validateResearchForm as r, getProviderInfo as s, VERSION as t, createLiveAgent as u, getFieldId as v, fieldToJsonSchema as w, isQualifiedRef as x, isCellRef as y };
+export { parseRawTable as A, parseScopeRef as C, parseForm as D, formToJsonSchema as E, parseCellValue as O, isQualifiedRef as S, fieldToJsonSchema as T, coerceToFieldPatch as _, resolveHarnessConfig as a, isCellRef as b, getProviderNames as c, createLiveAgent as d, MockAgent as f, coerceInputContext as g, createHarness as h, runResearch as i, ParseError$1 as j, parseMarkdownTable as k, resolveModel as l, FormHarness as m, isResearchForm as n, fillForm as o, createMockAgent as p, validateResearchForm as r, getProviderInfo as s, VERSION as t, buildMockWireFormat as u, findFieldById as v, serializeScopeRef as w, isFieldRef as x, getFieldId as y };

package/docs/markform-spec.md

@@ -1385,12 +1385,12 @@ type IssueReason =
   | 'checkbox_incomplete'    // Required checkboxes with non-terminal states
   | 'min_items_not_met'      // String-list or multi-select below minimum
   // Severity: *recommended* (optional improvements)
-  | 'optional_empty';        // Optional field with no value
+  | 'optional_unanswered';   // Optional field not yet addressed
 
 // Mapping from ValidationIssue to InspectIssue:
 // - ValidationIssue.severity='error' → InspectIssue.severity='required'
 // - ValidationIssue.severity='warning'/'info' → InspectIssue.severity='recommended'
-// - Missing optional fields → severity='recommended', reason='optional_empty'
+// - Unanswered optional fields → severity='recommended', reason='optional_unanswered'
 ```
 
 #### StructureSummary and ProgressSummary
@@ -2695,7 +2695,7 @@ type.
 | `checkbox_incomplete` | 3 (required) / 2 (recommended) |
 | `validation_error` | 2 |
 | `min_items_not_met` | 2 |
-| `optional_empty` | 1 |
+| `optional_unanswered` | 1 |
 
 **Total Score** = Field Priority Weight + Issue Type Score
 

package/examples/movie-research/{movie-research-deep.form.md → movie-deep-research.form.md}

@@ -1,7 +1,7 @@
 ---
 markform:
   spec: MF/0.1
-  title: Movie Research (Deep)
+  title: Movie Deep Research
   description: Comprehensive movie research form with ratings, box office, cast/crew, technical specs, streaming availability, and cultural analysis.
   run_mode: research
   roles:
@@ -40,7 +40,7 @@ markform:
     max_patches_per_turn: 15
 ---
 
-{% form id="movie_research_deep" title="Movie Research (Deep)" %}
+{% form id="movie_research_deep" title="Movie Deep Research" %}
 
 {% description ref="movie_research_deep" %}
 Comprehensive movie research covering ratings from multiple sources, box office performance, full cast and crew, technical specifications, streaming availability, and cultural impact analysis.