gigsmart
diff --git a/‎packages/haiku/src/orchestrator.ts‎
Lines changed: 57 additions & 16 deletions b/‎packages/haiku/src/orchestrator.ts‎
Lines changed: 57 additions & 16 deletions
diff --git a/‎packages/haiku/src/state-tools.ts‎
Lines changed: 96 additions & 57 deletions b/‎packages/haiku/src/state-tools.ts‎
Lines changed: 96 additions & 57 deletions
@@ -38,10 +38,10 @@ import { validateIdentifier } from "./prompts/helpers.js"
 import { reportError } from "./sentry.js"
 import { getSessionIntent, logSessionEvent } from "./session-metadata.js"
 import {
-	deriveIntentTitle,
 	findHaikuRoot,
 	gitCommitState,
 	intentDir,
+	intentTitleNeedsRepair,
 	isGitRepo,
 	parseFrontmatter,
 	readJson,
@@ -3390,18 +3390,24 @@ export const orchestratorToolDefs = [
 	{
 		name: "haiku_intent_create",
 		description:
-			"Create a new H·AI·K·U intent. Studio selection happens separately via haiku_select_studio.",
+			'Create a new H·AI·K·U intent. Studio selection happens separately via haiku_select_studio. You must provide BOTH a crisp `title` (3–8 words, ≤80 chars, single line, no trailing punctuation — e.g. "Add archivable intents") AND a richer `description` (2–5 sentences covering scope, motivation, and constraints). The title is NOT derived from the description — write it deliberately as a human-readable summary.',
 		inputSchema: {
 			type: "object" as const,
 			properties: {
+				title: {
+					type: "string",
+					description:
+						'Short human-readable title (3–8 words, max 80 chars, single line, no trailing period). Must be a deliberate summary — NOT the first 80 chars of the description. Good: "Add archivable intents". Bad: "Add archivable intents to H·AI·K·U. Users need a way to soft-hide…".',
+				},
 				description: {
 					type: "string",
-					description: "What the intent is about",
+					description:
+						"Full description of what the intent is about (2–5 sentences covering scope, motivation, and constraints). Stored verbatim in the intent body.",
 				},
 				slug: {
 					type: "string",
 					description:
-						"URL-friendly slug for the intent (auto-generated from description if not provided)",
+						"URL-friendly slug for the intent (auto-generated from title if not provided)",
 				},
 				context: {
 					type: "string",
@@ -3421,7 +3427,7 @@ export const orchestratorToolDefs = [
 						"Explicit stage list — overrides the studio's default stages. Use to run a subset of stages (e.g. just ['development'] for quick tasks).",
 				},
 			},
-			required: ["description"],
+			required: ["title", "description"],
 		},
 	},
 	{
@@ -4052,11 +4058,45 @@ export async function handleOrchestratorTool(
 
 	if (name === "haiku_intent_create") {
 		const description = args.description as string
+		const titleInput = args.title as string | undefined
 		let slug = args.slug as string | undefined
 
-		// Generate slug from description if not provided
+		// Title is required: must be a crisp, human-readable summary the agent
+		// writes deliberately. We do NOT derive it by truncating the description.
+		if (!titleInput || typeof titleInput !== "string") {
+			return text(
+				JSON.stringify({
+					error: "missing_title",
+					message:
+						'haiku_intent_create requires a `title` parameter — a crisp 3–8 word summary (≤80 chars, single line, no trailing period). Write it deliberately; do NOT pass a truncated description. Example: title: "Add archivable intents".',
+				}),
+			)
+		}
+		// Reject newlines explicitly before normalization — otherwise `\s+` would
+		// collapse them to spaces and hide the intent (a multi-line title input
+		// is a sign the agent pasted a paragraph, not wrote a title).
+		if (/[\r\n]/.test(titleInput)) {
+			return text(
+				JSON.stringify({
+					error: "invalid_title",
+					message:
+						"`title` must be a single line — got newlines. Rewrite as a crisp 3–8 word summary (≤80 chars) and call again.",
+				}),
+			)
+		}
+		const title = titleInput.trim().replace(/\s+/g, " ")
+		if (intentTitleNeedsRepair(title)) {
+			return text(
+				JSON.stringify({
+					error: "invalid_title",
+					message: `\`title\` must be non-empty and ≤80 chars after trimming. Got ${title.length} chars. Rewrite as a 3–8 word summary and call again.`,
+				}),
+			)
+		}
+
+		// Generate slug from title if not provided
 		if (!slug) {
-			slug = description
+			slug = title
 				.toLowerCase()
 				.replace(/[^a-z0-9\s-]/g, "")
 				.replace(/\s+/g, "-")
@@ -4102,14 +4142,13 @@ export async function handleOrchestratorTool(
 		mkdirSync(join(iDir, "knowledge"), { recursive: true })
 		mkdirSync(join(iDir, "stages"), { recursive: true })
 
-		// Build intent.md with frontmatter + body (no studio — selected separately)
-		// Title is derived as a short one-liner; the full description lives in the body.
+		// Build intent.md with frontmatter + body (no studio — selected separately).
+		// Title and description are distinct: title is a short human-readable summary
+		// the agent wrote deliberately; description is the full narrative body.
 		const context = args.context as string | undefined
 		const mode = (args.mode as string) || "continuous"
 		const stagesOverride = args.stages as string[] | undefined
-		const title = deriveIntentTitle(description)
-		const descriptionBody = description.trim()
-		const bodyHasDescription = descriptionBody && descriptionBody !== title
+		const descriptionBody = (description || "").trim()
 		const intentContent = [
 			"---",
 			`title: "${title.replace(/"/g, '\\"')}"`,
@@ -4124,7 +4163,7 @@ export async function handleOrchestratorTool(
 			"",
 			`# ${title}`,
 			"",
-			...(bodyHasDescription ? [descriptionBody, ""] : []),
+			...(descriptionBody ? [descriptionBody, ""] : []),
 			...(context ? [context, ""] : []),
 		].join("\n")
 
@@ -4460,11 +4499,12 @@ export async function handleOrchestratorTool(
 			}
 		}
 
-		// Read the description before deleting
+		// Read the title and description before deleting
 		const raw = readFileSync(intentFile, "utf8")
 		const { data, body } = parseFrontmatter(raw)
 		const title = (data.title as string) || ""
-		const description = title || body.replace(/^#\s+.*\n/, "").trim()
+		// Description = body minus the H1 heading, trimmed
+		const description = body.replace(/^#\s+.*\n+/, "").trim() || title
 
 		// Ask for confirmation via elicitation
 		if (_elicitInput) {
@@ -4526,9 +4566,10 @@ export async function handleOrchestratorTool(
 				{
 					action: "intent_reset",
 					slug,
+					title,
 					description,
 					context: conversationContext,
-					message: `Intent '${slug}' has been reset. Call haiku_intent_create { description: "${description.replace(/"/g, '\\"')}", slug: "${slug}"${conversationContext ? ', context: "<preserved context>"' : ""} } to recreate it.`,
+					message: `Intent '${slug}' has been reset. Call haiku_intent_create { title: "${title.replace(/"/g, '\\"')}", description: "${description.replace(/"/g, '\\"').replace(/\n/g, "\\n")}", slug: "${slug}"${conversationContext ? ', context: "<preserved context>"' : ""} } to recreate it.`,
 				},
 				null,
 				2,
 
@@ -47,38 +47,6 @@ import { MCP_VERSION, getPluginVersion } from "./version.js"
  *  description that needs summarizing. */
 export const INTENT_TITLE_MAX_LENGTH = 80
 
-/** Derive a short, one-line title from an arbitrary input string.
- *  - Collapses whitespace and newlines to single spaces
- *  - If it fits in the limit, returns the collapsed input verbatim
- *  - Otherwise truncates at a word boundary and appends an ellipsis
- *  - Strips trailing periods (titles don't end in a period)
- *
- *  Intentionally does NOT try to detect sentence boundaries: regex-based
- *  detection false-truncates on abbreviation periods ("e.g.", "i.e.", "Mr.",
- *  version strings like "v1.0", etc.). Word-boundary truncation with an
- *  ellipsis is deterministic and correct for all inputs.
- *
- *  Exported so both intent creation and repair use the same logic. */
-export function deriveIntentTitle(input: string): string {
-	if (!input) return ""
-	const collapsed = input.replace(/\s+/g, " ").trim()
-	if (!collapsed) return ""
-
-	if (collapsed.length <= INTENT_TITLE_MAX_LENGTH) {
-		return collapsed.replace(/\.$/, "")
-	}
-
-	// Too long — truncate at a word boundary and append ellipsis
-	const hardLimit = INTENT_TITLE_MAX_LENGTH - 1 // leave room for ellipsis
-	const truncated = collapsed.slice(0, hardLimit)
-	const lastSpace = truncated.lastIndexOf(" ")
-	return `${
-		lastSpace > INTENT_TITLE_MAX_LENGTH / 2
-			? truncated.slice(0, lastSpace)
-			: truncated
-	}…`
-}
-
 /** Whether a title value needs repair (too long, multiline, or empty). */
 export function intentTitleNeedsRepair(title: unknown): boolean {
 	if (typeof title !== "string") return true
@@ -121,42 +89,38 @@ export function applyAutoFixes(
 	const raw = readFileSync(intentPath, "utf8")
 	const parsed = matter(raw)
 	const data = parsed.data
-	let body = parsed.content
+	const body = parsed.content
 	let changed = false
 	const applied: AppliedFix[] = []
 	const remaining: RepairIssue[] = []
 
 	for (const issue of issues) {
 		let fixedHere = false
 
-		// Title: overlong, multiline, or otherwise non-conforming
+		// Title: overlong, multiline, or otherwise non-conforming.
+		// We do NOT auto-truncate — mechanical truncation produces mid-sentence
+		// fragments that aren't real titles. Instead we flag it for agent rewrite
+		// with instructions to produce a crisp 3–8 word summary. The full
+		// original is preserved as-is so the agent has it to work from.
 		if (
 			issue.field === "title" &&
 			typeof data.title === "string" &&
 			intentTitleNeedsRepair(data.title)
 		) {
-			const oldTitle = data.title as string
-			const newTitle = deriveIntentTitle(oldTitle)
-			data.title = newTitle
-			// Update H1 in body if it matches the old title; otherwise prepend
-			const h1Re = /^#\s+(.+?)\s*$/m
-			const h1Match = body.match(h1Re)
-			const oldDescription = oldTitle.replace(/\s+/g, " ").trim()
-			if (
-				h1Match &&
-				h1Match[1].replace(/\s+/g, " ").trim() === oldDescription
-			) {
-				body = body.replace(h1Re, `# ${newTitle}\n\n${oldDescription}`)
-			} else if (!h1Match) {
-				body = `${`# ${newTitle}\n\n${oldDescription}\n\n${body}`.trimEnd()}\n`
-			}
-			applied.push({
+			const oldTitle = (data.title as string).replace(/\s+/g, " ").trim()
+			const preview =
+				oldTitle.length > 120 ? `${oldTitle.slice(0, 117)}...` : oldTitle
+			remaining.push({
 				intent: slug,
 				field: "title",
-				description: `Trimmed title from ${oldTitle.length} chars to ${newTitle.length} chars; full description preserved in body`,
+				severity: "error",
+				message: `Title is ${oldTitle.length} chars — looks auto-truncated or is a full description, not a title`,
+				fix: `Rewrite as a crisp 3–8 word summary (≤80 chars, single line, no trailing period). Preserve the current text as a paragraph in the body under the H1 if it isn't there already. Original: "${preview}"`,
 			})
+			// Not "fixed" here — the rewritten issue was already pushed to `remaining` above.
+			// This flag just suppresses the end-of-loop fallthrough that would re-push the
+			// original (unmodified) issue. All other branches in this loop genuinely fix things.
 			fixedHere = true
-			changed = true
 		}
 
 		// Legacy `created` field → `created_at`
@@ -306,9 +270,85 @@ export function applyAutoFixes(
 		}
 	}
 
-	// Second pass: fix stage-level state.json issues (completion synthesis)
-	const stageRemaining: RepairIssue[] = []
+	// Second pass: auto-apply unit `inputs:` from the fix instructions.
+	// The scanner has already resolved upstream artifact paths per stage; we
+	// just write them into each unit's frontmatter. For first-stage units with
+	// no upstream (the "intent doc and discovery docs" fallback), we link the
+	// intent.md and any existing knowledge/*.md as a sensible default.
+	const inputsRemaining: RepairIssue[] = []
+	const unitInputsRe = /^stages\/([^/]+)\/units\/([^/]+):inputs$/
 	for (const issue of remaining) {
+		const m = issue.field.match(unitInputsRe)
+		if (
+			!m ||
+			!issue.message.includes("Unit has no `inputs:`") ||
+			typeof issue.fix !== "string"
+		) {
+			inputsRemaining.push(issue)
+			continue
+		}
+		const stageName = m[1]
+		const unitFile = m[2]
+		const unitPath = join(
+			intentRoot,
+			slug,
+			"stages",
+			stageName,
+			"units",
+			unitFile,
+		)
+		if (!existsSync(unitPath)) {
+			inputsRemaining.push(issue)
+			continue
+		}
+
+		// Resolve the inputs to write
+		let inputsToWrite: string[] = []
+		const upstreamMatch = issue.fix.match(/upstream paths:\s*(.+?)\s*$/)
+		if (upstreamMatch) {
+			inputsToWrite = upstreamMatch[1]
+				.split(",")
+				.map((s) => s.trim())
+				.filter(Boolean)
+		} else {
+			// Fallback: link intent.md and any discoverable knowledge/*.md
+			const fallback: string[] = ["intent.md"]
+			const knowledgeDir = join(intentRoot, slug, "knowledge")
+			if (existsSync(knowledgeDir)) {
+				for (const f of readdirSync(knowledgeDir)) {
+					if (f.endsWith(".md")) fallback.push(`knowledge/${f}`)
+				}
+			}
+			inputsToWrite = fallback
+		}
+
+		if (inputsToWrite.length === 0) {
+			inputsRemaining.push(issue)
+			continue
+		}
+
+		const unitRaw = readFileSync(unitPath, "utf8")
+		const unitParsed = matter(unitRaw)
+		const existing = (unitParsed.data.inputs as string[]) || []
+		if (existing.length > 0) {
+			// Already has inputs (race or stale issue list) — drop the issue
+			continue
+		}
+		unitParsed.data.inputs = inputsToWrite
+		writeFileSync(
+			unitPath,
+			matter.stringify(unitParsed.content, unitParsed.data),
+		)
+		applied.push({
+			intent: slug,
+			field: issue.field,
+			description: `Linked ${inputsToWrite.length} input(s): ${inputsToWrite.join(", ")}`,
+		})
+	}
+
+	// Third pass: fix stage-level state.json issues (completion synthesis)
+	const stageRemaining: RepairIssue[] = []
+	for (const issue of inputsRemaining) {
 		let fixedHere = false
 
 		// Synthesize or update stage completion records for stages before active_stage
@@ -466,16 +506,15 @@ function scanOneIntent(
 		intentTitleNeedsRepair(repairData.title)
 	) {
 		const current = repairData.title as string
-		const derived = deriveIntentTitle(current)
 		const reason = /\n/.test(current)
 			? "title contains newlines"
 			: `title is ${current.length} chars (max ${INTENT_TITLE_MAX_LENGTH})`
 		issues.push({
 			intent: slug,
 			field: "title",
-			severity: "warning",
+			severity: "error",
 			message: `Title should be a short one-liner — ${reason}`,
-			fix: `Replace \`title\` with: "${derived.replace(/"/g, '\\"')}". Move the full description into the intent body as a paragraph under the H1.`,
+			fix: "Rewrite `title` as a crisp 3–8 word summary (≤80 chars, single line, no trailing period). Do NOT truncate the current value — write a deliberate human-readable summary. Preserve the original text as a paragraph in the body under the H1 if it isn't there already.",
 		})
 	}