@majeanson/lac 3.2.0 → 3.3.0

package/dist/lsp.mjs

@@ -8906,6 +8906,7 @@ const FeatureSchema = object({
 	superseded_from: array(string().regex(FEATURE_KEY_PATTERN, "each superseded_from entry must be a valid featureKey")).optional(),
 	merged_into: string().regex(FEATURE_KEY_PATTERN, "merged_into must be a valid featureKey").optional(),
 	merged_from: array(string().regex(FEATURE_KEY_PATTERN, "each merged_from entry must be a valid featureKey")).optional(),
+	userGuide: string().optional(),
 	componentFile: string().optional(),
 	npmPackages: array(string()).optional(),
 	publicInterface: array(PublicInterfaceEntrySchema).optional(),

package/dist/mcp.mjs

@@ -3784,6 +3784,7 @@ const FeatureSchema$1 = object$1({
 	superseded_from: array$1(string$2().regex(FEATURE_KEY_PATTERN$1, "each superseded_from entry must be a valid featureKey")).optional(),
 	merged_into: string$2().regex(FEATURE_KEY_PATTERN$1, "merged_into must be a valid featureKey").optional(),
 	merged_from: array$1(string$2().regex(FEATURE_KEY_PATTERN$1, "each merged_from entry must be a valid featureKey")).optional(),
+	userGuide: string$2().optional(),
 	componentFile: string$2().optional(),
 	npmPackages: array$1(string$2()).optional(),
 	publicInterface: array$1(PublicInterfaceEntrySchema$1).optional(),
@@ -8052,6 +8053,7 @@ const FeatureSchema = object({
 	superseded_from: array(string().regex(FEATURE_KEY_PATTERN, "each superseded_from entry must be a valid featureKey")).optional(),
 	merged_into: string().regex(FEATURE_KEY_PATTERN, "merged_into must be a valid featureKey").optional(),
 	merged_from: array(string().regex(FEATURE_KEY_PATTERN, "each merged_from entry must be a valid featureKey")).optional(),
+	userGuide: string().optional(),
 	componentFile: string().optional(),
 	npmPackages: array(string()).optional(),
 	publicInterface: array(PublicInterfaceEntrySchema).optional(),
@@ -8243,6 +8245,10 @@ Return ONLY a valid JSON array — no other text:
 		system: `You are a software engineering analyst. Write a plain-language success criteria statement for this feature — "how do we know it's done and working?" Be specific and testable. 1-3 sentences. Return only the text, no JSON wrapper, no heading.`,
 		userSuffix: "Write the success criteria for this feature."
 	},
+	userGuide: {
+		system: `You are a technical writer writing for end users — not developers. Given a feature.json, write a plain-language user guide for this feature. Explain what it does and how to use it in everyday language. Avoid technical terms, implementation details, and acceptance-criteria framing. Write from the user's perspective: what they will see, what they can do, and why it helps them. 2-5 sentences or a short bullet list. Return only the guide text, no JSON wrapper, no heading.`,
+		userSuffix: "Write a plain-language user guide for this feature."
+	},
 	domain: {
 		system: `You are a software engineering analyst. Identify the primary technical domain for this feature from its code and problem statement. Return a single lowercase word or short hyphenated phrase (e.g. "auth", "payments", "notifications", "data-pipeline"). Return only the domain value — nothing else.`,
 		userSuffix: "Identify the domain for this feature."
@@ -8312,6 +8318,7 @@ const ALL_FILLABLE_FIELDS = [
 	"knownLimitations",
 	"tags",
 	"successCriteria",
+	"userGuide",
 	"domain",
 	"componentFile",
 	"npmPackages",
@@ -8325,7 +8332,7 @@ function getMissingFields(feature) {
 		const val = feature[field];
 		if (val === void 0 || val === null) return true;
 		if (typeof val === "string") return val.trim().length === 0;
-		if (Array.isArray(val)) return val.length === 0;
+		if (Array.isArray(val)) return false;
 		return false;
 	});
 }
@@ -8392,7 +8399,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [
 	},
 	{
 		name: "create_feature",
-		description: "Create a new feature.json in the specified directory.",
+		description: "Create a new feature.json in the specified directory. After creating, immediately call read_feature_context on the same path to analyze surrounding code and fill all required fields before calling advance_feature.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -8870,6 +8877,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 					if (raw.superseded_by && !featureKeys.has(String(raw.superseded_by))) issues.push(`broken superseded_by ref: "${raw.superseded_by}" not found`);
 					if (raw.merged_into && !featureKeys.has(String(raw.merged_into))) issues.push(`broken merged_into ref: "${raw.merged_into}" not found`);
 					for (const key of raw.merged_from ?? []) if (!featureKeys.has(key)) issues.push(`broken merged_from ref: "${key}" not found`);
+					if (feature.status === "active" || feature.status === "draft") {
+						const preFreeze = getMissingForTransition(feature, "frozen");
+						if (preFreeze.length > 0) warnings.push(`will block freeze — missing: ${preFreeze.join(", ")}`);
+					}
 					if (raw.superseded_by && feature.status !== "deprecated") warnings.push(`superseded_by set but status is "${feature.status}" — consider deprecating`);
 					if (raw.merged_into && feature.status !== "deprecated") warnings.push(`merged_into set but status is "${feature.status}" — consider deprecating`);
 					const hasRevisions = Array.isArray(raw.revisions) && raw.revisions.length > 0;
@@ -8961,6 +8972,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 				const feature = result.data;
 				const contextStr = contextToString(buildContext(featureDir, feature));
 				const missingFields = getMissingFields(feature);
+				let componentFileWarning = "";
+				if (feature.componentFile) {
+					const notFound = feature.componentFile.split(",").map((s) => s.trim()).filter(Boolean).filter((p) => {
+						return [path.resolve(featureDir, p), path.resolve(workspaceRoot, p)].every((c) => !fs.existsSync(c));
+					});
+					if (notFound.length > 0) componentFileWarning = `\n## ⚠ componentFile drift\nThese paths do not exist on disk — update componentFile to match actual source files:\n${notFound.map((p) => `  - ${p}`).join("\n")}\n`;
+				}
 				const fieldInstructions = missingFields.map((field) => {
 					const prompt = FILL_PROMPTS[field];
 					const isJson = JSON_FIELDS.has(field);
@@ -8968,9 +8986,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 				}).join("\n\n");
 				const staleAnnotation = feature.annotations?.find((ann) => ann.type === "stale-review");
 				const staleWarning = staleAnnotation ? `## ⚠ Stale fields (feature was reopened)\n${staleAnnotation.body}\nReview and rewrite these fields against the current code, then call write_feature_fields.\n\n` : "";
+				const instructions = missingFields.length === 0 ? staleWarning || "All fillable fields are already populated. No generation needed." : `${staleWarning}## Missing fields to fill (${missingFields.join(", ")})\n\nGenerate each field described below, then call write_feature_fields with all values at once. Fill ALL missing fields before calling advance_feature.\n\n${fieldInstructions}`;
 				return { content: [{
 					type: "text",
-					text: `${missingFields.length === 0 ? staleWarning || "All fillable fields are already populated. No generation needed." : `${staleWarning}## Missing fields to fill (${missingFields.join(", ")})\n\nGenerate each field described below, then call write_feature_fields with all values at once. After writing, call advance_feature to check if the feature is ready to transition.\n\n${fieldInstructions}`}\n\n## Context\n\n${contextStr}`
+					text: `${componentFileWarning}${instructions}\n\n## Context\n\n${contextStr}`
 				}] };
 			}
 			case "write_feature_fields": {
@@ -9009,6 +9028,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 					...existing,
 					...fields
 				};
+				updated.lastVerifiedDate = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
 				const revisionInput = a.revision;
 				let revisionWarning = "";
 				if (changingCritical.length > 0) if (revisionInput?.author && revisionInput?.reason) {
@@ -9019,6 +9039,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 						fields_changed: changingCritical,
 						reason: revisionInput.reason
 					}];
+					updated.annotations = (existing.annotations ?? []).filter((ann) => ann.type !== "stale-review");
 				} else revisionWarning = `\n\n⚠ Intent-critical fields changed (${changingCritical.join(", ")}) without a revision entry. Pass a "revision" object with author and reason to attribute this change.`;
 				fs.writeFileSync(featurePath, JSON.stringify(updated, null, 2) + "\n", "utf-8");
 				const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -9034,7 +9055,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 				const writtenKeys = Object.keys(fields);
 				const afterResult = validateFeature(JSON.parse(fs.readFileSync(featurePath, "utf-8")));
 				const stillMissing = afterResult.success ? getMissingFields(afterResult.data) : [];
-				const nextHint = stillMissing.length > 0 ? `${stillMissing.length} field(s) still missing: ${stillMissing.join(", ")}. Continue filling or call advance_feature to check if the current fields are sufficient to transition.` : `All AI fields filled. Call advance_feature to transition status when ready.`;
+				const nextHint = stillMissing.length > 0 ? `${stillMissing.length} field(s) still missing: ${stillMissing.join(", ")}. Fill all remaining fields with write_feature_fields before calling advance_feature.` : `All AI fields filled. Call advance_feature to transition status when ready.`;
 				return { content: [{
 					type: "text",
 					text: `✓ Wrote ${writtenKeys.length} field(s) to ${featurePath}: ${writtenKeys.join(", ")}\n\n${nextHint}${revisionWarning}`
@@ -9093,6 +9114,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 					...parsed,
 					status: to
 				};
+				if (to === "frozen") updated.lastVerifiedDate = today;
 				updated.statusHistory = [...updated.statusHistory ?? [], {
 					from,
 					to,
@@ -9891,7 +9913,9 @@ const REQUIRED_FOR_FROZEN = [
 	"implementation",
 	"successCriteria",
 	"knownLimitations",
-	"tags"
+	"tags",
+	"userGuide",
+	"componentFile"
 ];
 function getMissingForTransition(feature, to) {
 	const required$2 = to === "active" ? REQUIRED_FOR_ACTIVE : to === "frozen" ? REQUIRED_FOR_FROZEN : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@majeanson/lac",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "CLI for life-as-code — feature provenance tracking from the terminal",
   "license": "MIT",
   "repository": {