@joshski/dust 0.1.112 → 0.1.113

package/README.md

@@ -40,6 +40,23 @@ npx dust loop claude
 
 This runs Claude Code in a [ralph loop](https://ghuntley.com/loop/), picking up tasks until they are all done.
 
+## Codex Hook (Optional)
+
+For [Codex](https://github.com/openai/codex) 0.125.0 or newer, you can replace the `AGENTS.md` instruction with a `SessionStart` hook that loads dust's instructions directly into the model's context — once per session, with no extra agent commands. Add this to `~/.codex/config.toml` (or your project's Codex config):
+
+```toml
+[features]
+codex_hooks = true
+
+[[hooks.SessionStart]]
+matcher = "^startup$"
+
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "bunx dust codex hook"
+statusMessage = "Loading dust agent instructions"
+```
+
 ## Learn More
 
 Details live in the [.dust/facts](./.dust/facts) directory:

package/dist/cli/shared/agent-shared.d.ts

@@ -16,7 +16,7 @@ export interface TemplateVars {
     isClaudeCodeWeb: boolean;
     hasIdeaFile: boolean;
 }
-export interface TemplateVarsWithInstructions extends TemplateVars {
+interface TemplateVarsWithInstructions extends TemplateVars {
     agentInstructions: string;
 }
 /**
@@ -33,6 +33,13 @@ export declare function templateVariables(settings: DustSettings, hooksInstalled
 export declare function templateVariablesWithInstructions(cwd: string, fileSystem: FileReader, settings: DustSettings, hooksInstalled: boolean, env: NodeJS.ProcessEnv, options?: {
     hasIdeaFile?: boolean;
 }): Promise<TemplateVarsWithInstructions>;
+/**
+ * Renders the dust agent greeting text.
+ *
+ * Used by both `dust agent` (printed to the user) and `dust codex hook`
+ * (injected as `additionalContext` into the model's session context).
+ */
+export declare function agentGreeting(vars: TemplateVarsWithInstructions): string;
 /**
  * Manages git hook installation for agent commands.
  * Automatically installs pre-push hooks if:
@@ -42,3 +49,4 @@ export declare function templateVariablesWithInstructions(cwd: string, fileSyste
  * Returns whether hooks are installed.
  */
 export declare function manageGitHooks(dependencies: CommandDependencies): Promise<boolean>;
+export {};

package/dist/dust.js

@@ -7,7 +7,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@joshski/dust",
-    version: "0.1.112",
+    version: "0.1.113",
     description: "Flow state for AI coding agents",
     type: "module",
     bin: {
@@ -731,7 +731,7 @@ async function loadSettings(cwd, fileSystem, runtime) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.112";
+var DUST_VERSION = "0.1.113";
 
 // lib/cli/middleware.ts
 function applyMiddleware(middlewares, execute) {
@@ -783,16 +783,6 @@ function createDefaultTracingOptions() {
   };
 }
 
-// lib/cli/dedent.ts
-function dedent(strings, ...values) {
-  const result = strings.reduce((acc, part, index) => acc + part + (values[index] ?? ""), "");
-  const lines = result.split(`
-`);
-  const indent = lines.filter((line) => line.trim()).reduce((min, line) => Math.min(min, line.match(/^\s*/)[0].length), Number.POSITIVE_INFINITY);
-  return lines.map((line) => line.slice(indent)).join(`
-`).trim();
-}
-
 // lib/cli/shared/agent-shared.ts
 import { join as join4 } from "node:path";
 
@@ -939,6 +929,16 @@ ${newHookContent}
   };
 }
 
+// lib/cli/dedent.ts
+function dedent(strings, ...values) {
+  const result = strings.reduce((acc, part, index) => acc + part + (values[index] ?? ""), "");
+  const lines = result.split(`
+`);
+  const indent = lines.filter((line) => line.trim()).reduce((min, line) => Math.min(min, line.match(/^\s*/)[0].length), Number.POSITIVE_INFINITY);
+  return lines.map((line) => line.slice(indent)).join(`
+`).trim();
+}
+
 // lib/cli/shared/agent-shared.ts
 async function loadAgentInstructions(cwd, fileSystem, agentType) {
   const instructionsPath = join4(cwd, ".dust", "config", "agents", `${agentType}.md`);
@@ -979,25 +979,6 @@ async function templateVariablesWithInstructions(cwd, fileSystem, settings, hook
     agentInstructions
   };
 }
-async function manageGitHooks(dependencies) {
-  const { context, fileSystem, settings } = dependencies;
-  const hooks = createHooksManager(context.cwd, fileSystem, settings);
-  if (!hooks.isGitRepo()) {
-    return false;
-  }
-  const isInstalled = await hooks.isHookInstalled();
-  if (!isInstalled) {
-    await hooks.installHook();
-    return true;
-  }
-  const hookBinaryPath = await hooks.getHookBinaryPath();
-  if (hookBinaryPath && hookBinaryPath !== settings.dustCommand) {
-    await hooks.updateHookBinaryPath(settings.dustCommand);
-  }
-  return true;
-}
-
-// lib/cli/commands/agent.ts
 function agentGreeting(vars) {
   const instructions = vars.agentInstructions ? `
 ---
@@ -1035,6 +1016,25 @@ ${vars.agentInstructions}` : "";
     Do NOT proceed without running one of these commands.${instructions}
   `;
 }
+async function manageGitHooks(dependencies) {
+  const { context, fileSystem, settings } = dependencies;
+  const hooks = createHooksManager(context.cwd, fileSystem, settings);
+  if (!hooks.isGitRepo()) {
+    return false;
+  }
+  const isInstalled = await hooks.isHookInstalled();
+  if (!isInstalled) {
+    await hooks.installHook();
+    return true;
+  }
+  const hookBinaryPath = await hooks.getHookBinaryPath();
+  if (hookBinaryPath && hookBinaryPath !== settings.dustCommand) {
+    await hooks.updateHookBinaryPath(settings.dustCommand);
+  }
+  return true;
+}
+
+// lib/cli/commands/agent.ts
 async function agent(dependencies, env = process.env) {
   const { context, fileSystem, settings } = dependencies;
   if (env[DUST_SKIP_AGENT] === "1") {
@@ -6420,6 +6420,7 @@ async function parseCaptureIdeaTask(fileSystem, dustPath, taskSlug) {
 }
 
 // lib/lint/validators/content-validator.ts
+var FRONT_MATTER_DELIMITER = "---";
 var REQUIRED_TASK_HEADINGS = ["Task Type", "Blocked By", "Definition of Done"];
 var ALLOWED_TASK_TYPES = new Set(VALID_TASK_TYPES);
 var MAX_OPENING_SENTENCE_LENGTH = 150;
@@ -6437,6 +6438,18 @@ var NON_IMPERATIVE_STARTERS = new Set([
   "you",
   "i"
 ]);
+function validateNoFrontMatter(artifact) {
+  const firstLine = artifact.rawContent.split(`
+`)[0];
+  if (firstLine.trim() === FRONT_MATTER_DELIMITER) {
+    return {
+      file: artifact.filePath,
+      line: 1,
+      message: "Artifact must not contain front matter. The title must be the first line."
+    };
+  }
+  return null;
+}
 function validateOpeningSentence(artifact) {
   if (!artifact.openingSentence) {
     return {
@@ -6897,6 +6910,40 @@ async function executeTask(task, runParameters, onAgentEvent, context, agentName
     return "claude_error";
   }
 }
+function selectShellRunner(spawnFn, options, loopDeps) {
+  if (options.docker && options.containerRuntime) {
+    return buildContainerShellRunner(spawnFn, options.containerRuntime, options.docker);
+  }
+  return loopDeps.shellRunner ?? defaultShellRunner;
+}
+function buildContainerShellRunner(spawnFn, containerRuntime, docker) {
+  const runConfig = {
+    imageTag: docker.imageTag,
+    repoPath: docker.repoPath,
+    homeDir: docker.homeDir,
+    gitProxyUrl: docker.gitProxyUrl
+  };
+  const baseArgs = containerRuntime.buildRunArgs(runConfig);
+  return {
+    run: (command, _cwd) => new Promise((resolve) => {
+      const proc = spawnFn(containerRuntime.runCommand, [
+        ...baseArgs,
+        "sh",
+        "-c",
+        command
+      ]);
+      const chunks = [];
+      proc.stdout?.on("data", (data) => chunks.push(data.toString()));
+      proc.stderr?.on("data", (data) => chunks.push(data.toString()));
+      proc.on("close", (code) => {
+        resolve({ exitCode: code ?? 1, output: chunks.join("") });
+      });
+      proc.on("error", (error) => {
+        resolve({ exitCode: 1, output: error.message });
+      });
+    })
+  };
+}
 async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAgentEvent, options = {}) {
   const { context, fileSystem, settings } = dependencies;
   const { spawn: spawn2, run: run2 } = loopDependencies;
@@ -6946,7 +6993,7 @@ async function runOneIteration(dependencies, loopDependencies, onLoopEvent, onAg
   const taskTitle = task.title ?? task.path;
   log2(`found ${tasks.length} task(s), picking: ${taskTitle}`);
   onLoopEvent({ type: "loop.tasks_found" });
-  const shellRunner = loopDependencies.shellRunner ?? defaultShellRunner;
+  const shellRunner = selectShellRunner(spawn2, options, loopDependencies);
   const preflightResult = await runPreflightChecks(context.cwd, settings.dustCommand, settings.installCommand, shellRunner, onLoopEvent, onAgentEvent, taskTitle);
   if (preflightResult.failed) {
     return handleCheckFailure(preflightResult.output, settings.dustCommand, { run: run2, prompt: "", spawnOptions, onRawEvent }, onAgentEvent, context, agentName, agentType, logger);
@@ -11440,6 +11487,8 @@ function validateIdeaOpenQuestions(artifact) {
   const topLevelStructureMessage = "Open Questions must use `### Question?` headings and `#### Option` headings at the top level. Put supporting markdown (including lists and code blocks) under an option heading. Run `dust new idea` to see the expected format.";
   let inOpenQuestions = false;
   let currentQuestionLine = null;
+  let currentQuestionText = null;
+  let currentQuestionOptionNames = new Set;
   let inOption = false;
   let inCodeBlock = false;
   for (let i = 0;i < lines.length; i++) {
@@ -11463,6 +11512,8 @@ function validateIdeaOpenQuestions(artifact) {
       violations.push(...validateH2Heading(filePath, line, i + 1, inOpenQuestions, currentQuestionLine));
       inOpenQuestions = line === "## Open Questions";
       currentQuestionLine = null;
+      currentQuestionText = null;
+      currentQuestionOptionNames = new Set;
       inOption = false;
       inCodeBlock = false;
       continue;
@@ -11478,6 +11529,7 @@ function validateIdeaOpenQuestions(artifact) {
           line: currentQuestionLine
         });
       }
+      currentQuestionOptionNames = new Set;
       if (!trimmedLine.endsWith("?")) {
         violations.push({
           file: filePath,
@@ -11485,12 +11537,24 @@ function validateIdeaOpenQuestions(artifact) {
           line: i + 1
         });
         currentQuestionLine = null;
+        currentQuestionText = null;
       } else {
         currentQuestionLine = i + 1;
+        currentQuestionText = trimmedLine.slice(4);
       }
       continue;
     }
     if (line.startsWith("#### ")) {
+      const optionName = trimmedLine.slice(5);
+      if (currentQuestionOptionNames.has(optionName)) {
+        violations.push({
+          file: filePath,
+          message: `Duplicate option "${optionName}" under question "${currentQuestionText}" — each option must have a unique name`,
+          line: i + 1
+        });
+      } else {
+        currentQuestionOptionNames.add(optionName);
+      }
       currentQuestionLine = null;
       inOption = true;
       continue;
@@ -11866,6 +11930,9 @@ function validateArtifacts(context) {
   }
   for (const artifacts of Object.values(byType)) {
     for (const artifact of artifacts) {
+      const frontMatterViolation = validateNoFrontMatter(artifact);
+      if (frontMatterViolation)
+        violations.push(frontMatterViolation);
       const openingSentenceViolation = validateOpeningSentence(artifact);
       if (openingSentenceViolation)
         violations.push(openingSentenceViolation);
@@ -12214,6 +12281,75 @@ async function check(dependencies, shellRunner, clock, _setInterval, _clearInter
   return { exitCode };
 }
 
+// lib/cli/commands/codex-hook.ts
+var KNOWN_HOOK_EVENTS = [
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "SessionStart",
+  "UserPromptSubmit",
+  "Stop"
+];
+async function readStdinUtf8() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+var defaultCodexHookDependencies = {
+  readStdin: readStdinUtf8
+};
+function isKnownEvent(value) {
+  return typeof value === "string" && KNOWN_HOOK_EVENTS.includes(value);
+}
+async function handleSessionStart(dependencies) {
+  const { context, fileSystem, settings } = dependencies;
+  const agentInstructions = await loadAgentInstructions(context.cwd, fileSystem, "codex");
+  const additionalContext = agentGreeting({
+    bin: settings.dustCommand,
+    agentName: "Codex",
+    hooksInstalled: false,
+    isClaudeCodeWeb: false,
+    hasIdeaFile: true,
+    agentInstructions
+  });
+  return JSON.stringify({
+    continue: true,
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext
+    },
+    systemMessage: "dust agent loaded"
+  });
+}
+function handleNoOp() {
+  return JSON.stringify({ continue: true });
+}
+async function codexHook(dependencies, hookDependencies = defaultCodexHookDependencies) {
+  const { context } = dependencies;
+  const raw = await hookDependencies.readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    context.stderr("dust codex hook: failed to parse stdin as JSON");
+    return { exitCode: 1 };
+  }
+  if (!payload || typeof payload !== "object") {
+    context.stderr("dust codex hook: stdin payload must be a JSON object");
+    return { exitCode: 1 };
+  }
+  const eventName = payload.hook_event_name;
+  if (!isKnownEvent(eventName)) {
+    context.stderr(`dust codex hook: unknown hook_event_name: ${JSON.stringify(eventName)}`);
+    return { exitCode: 1 };
+  }
+  const response = eventName === "SessionStart" ? await handleSessionStart(dependencies) : handleNoOp();
+  context.stdout(response);
+  return { exitCode: 0 };
+}
+
 // lib/bundled-core-principles.ts
 var BUNDLED_PRINCIPLES = [
   {
@@ -13857,16 +13993,15 @@ async function init(dependencies) {
       throw error;
     }
   }
-  const runner = dustCommand.split(" ")[0];
   context.stdout("");
   context.stdout(`${colors.bold}\uD83D\uDE80 Next steps:${colors.reset} Commit the changes if you are happy, then get planning!`);
   context.stdout("");
   context.stdout(`${colors.dim}If this is a new repository, you can start adding ideas or tasks right away:${colors.reset}`);
-  context.stdout(`   ${colors.cyan}>${colors.reset} ${runner} claude "Idea: friendly UI for non-technical users"`);
-  context.stdout(`   ${colors.cyan}>${colors.reset} ${runner} codex "Task: set up code coverage"`);
+  context.stdout(`   ${colors.cyan}>${colors.reset} claude "Idea: friendly UI for non-technical users"`);
+  context.stdout(`   ${colors.cyan}>${colors.reset} codex "Task: set up code coverage"`);
   context.stdout("");
   context.stdout(`${colors.dim}If this is an existing codebase, you might want to backfill principles and facts:${colors.reset}`);
-  context.stdout(`   ${colors.cyan}>${colors.reset} ${runner} claude "Add principles and facts based on the code in this repository"`);
+  context.stdout(`   ${colors.cyan}>${colors.reset} claude "Add principles and facts based on the code in this repository"`);
   return { exitCode: 0 };
 }
 
@@ -14377,7 +14512,8 @@ async function runLoop(dependencies, loopDependencies) {
   let completedIterations = 0;
   const iterationOptions = {
     hooksInstalled,
-    docker: dockerConfig
+    docker: dockerConfig,
+    containerRuntime
   };
   if (eventsUrl) {
     iterationOptions.onRawEvent = createHeartbeatThrottler(onAgentEvent, loopDependencies.agentType ?? "claude");
@@ -14861,6 +14997,9 @@ function runLoopClaude(commandDependencies) {
 function runLoopCodex(commandDependencies) {
   return loopCodex(commandDependencies, createCodexDependencies());
 }
+function runCodexHook(commandDependencies) {
+  return codexHook(commandDependencies, defaultCodexHookDependencies);
+}
 var commandRegistry = {
   init,
   lint: lintMarkdown,
@@ -14875,6 +15014,7 @@ var commandRegistry = {
   audit,
   "bucket worker": bucketWorker,
   "bucket tool": bucketTool,
+  "codex hook": runCodexHook,
   "core principle": corePrinciple,
   focus,
   "new task": newTask,

package/dist/lint/validators/content-validator.d.ts

@@ -3,6 +3,7 @@
  */
 import type { ParsedArtifact } from '../../artifacts/parsed-artifact';
 import type { Violation } from './types';
+export declare function validateNoFrontMatter(artifact: ParsedArtifact): Violation | null;
 export declare function validateOpeningSentence(artifact: ParsedArtifact): Violation | null;
 export declare function validateOpeningSentenceLength(artifact: ParsedArtifact): Violation | null;
 export declare function validateImperativeOpeningSentence(artifact: ParsedArtifact): Violation | null;

package/dist/loop/iteration.d.ts

@@ -1,6 +1,7 @@
 import { spawn as nodeSpawn } from 'node:child_process';
 import type { BoundRunFn, DockerSpawnConfig } from '../claude/types';
 import type { DockerDependencies } from '../docker/docker-agent';
+import type { ContainerRuntime } from '../container/runtime';
 import { type SessionConfig } from '../env-config';
 import { type ShellRunner } from '../cli/process-runner';
 import type { CommandDependencies } from '../cli/types';
@@ -40,11 +41,14 @@ export interface IterationOptions {
     branch?: string;
     /** Trace ID for correlating events across processes */
     traceId?: string;
+    /** Container runtime to use for container-aware pre-flight checks */
+    containerRuntime?: ContainerRuntime | null;
 }
 export declare function findAvailableTasks(dependencies: CommandDependencies): Promise<{
     tasks: UnblockedTask[];
     invalidTasks: InvalidTask[];
 }>;
+export declare function buildContainerShellRunner(spawnFn: typeof nodeSpawn, containerRuntime: ContainerRuntime, docker: DockerSpawnConfig): ShellRunner;
 export declare function runOneIteration(dependencies: CommandDependencies, loopDependencies: LoopDependencies, onLoopEvent: LoopEmitFn, onAgentEvent?: SendAgentEventFn, options?: IterationOptions): Promise<IterationResult>;
 export declare function buildTaskPrompt(taskPath: string, taskContent: string, instructions: string, toolsSection: string, dustCommand: string, branch?: string): string;
 export {};

package/dist/patch.js

@@ -251,6 +251,7 @@ function validateAuditHeadings(artifact) {
 }
 
 // lib/lint/validators/content-validator.ts
+var FRONT_MATTER_DELIMITER = "---";
 var REQUIRED_TASK_HEADINGS = ["Task Type", "Blocked By", "Definition of Done"];
 var ALLOWED_TASK_TYPES = new Set(VALID_TASK_TYPES);
 var MAX_OPENING_SENTENCE_LENGTH = 150;
@@ -268,6 +269,18 @@ var NON_IMPERATIVE_STARTERS = new Set([
   "you",
   "i"
 ]);
+function validateNoFrontMatter(artifact) {
+  const firstLine = artifact.rawContent.split(`
+`)[0];
+  if (firstLine.trim() === FRONT_MATTER_DELIMITER) {
+    return {
+      file: artifact.filePath,
+      line: 1,
+      message: "Artifact must not contain front matter. The title must be the first line."
+    };
+  }
+  return null;
+}
 function validateOpeningSentence(artifact) {
   if (!artifact.openingSentence) {
     return {
@@ -453,6 +466,8 @@ function validateIdeaOpenQuestions(artifact) {
   const topLevelStructureMessage = "Open Questions must use `### Question?` headings and `#### Option` headings at the top level. Put supporting markdown (including lists and code blocks) under an option heading. Run `dust new idea` to see the expected format.";
   let inOpenQuestions = false;
   let currentQuestionLine = null;
+  let currentQuestionText = null;
+  let currentQuestionOptionNames = new Set;
   let inOption = false;
   let inCodeBlock = false;
   for (let i = 0;i < lines.length; i++) {
@@ -476,6 +491,8 @@ function validateIdeaOpenQuestions(artifact) {
       violations.push(...validateH2Heading(filePath, line, i + 1, inOpenQuestions, currentQuestionLine));
       inOpenQuestions = line === "## Open Questions";
       currentQuestionLine = null;
+      currentQuestionText = null;
+      currentQuestionOptionNames = new Set;
       inOption = false;
       inCodeBlock = false;
       continue;
@@ -491,6 +508,7 @@ function validateIdeaOpenQuestions(artifact) {
           line: currentQuestionLine
         });
       }
+      currentQuestionOptionNames = new Set;
       if (!trimmedLine.endsWith("?")) {
         violations.push({
           file: filePath,
@@ -498,12 +516,24 @@ function validateIdeaOpenQuestions(artifact) {
           line: i + 1
         });
         currentQuestionLine = null;
+        currentQuestionText = null;
       } else {
         currentQuestionLine = i + 1;
+        currentQuestionText = trimmedLine.slice(4);
       }
       continue;
     }
     if (line.startsWith("#### ")) {
+      const optionName = trimmedLine.slice(5);
+      if (currentQuestionOptionNames.has(optionName)) {
+        violations.push({
+          file: filePath,
+          message: `Duplicate option "${optionName}" under question "${currentQuestionText}" — each option must have a unique name`,
+          line: i + 1
+        });
+      } else {
+        currentQuestionOptionNames.add(optionName);
+      }
       currentQuestionLine = null;
       inOption = true;
       continue;
@@ -879,6 +909,9 @@ function validateArtifacts(context) {
   }
   for (const artifacts of Object.values(byType)) {
     for (const artifact of artifacts) {
+      const frontMatterViolation = validateNoFrontMatter(artifact);
+      if (frontMatterViolation)
+        violations.push(frontMatterViolation);
       const openingSentenceViolation = validateOpeningSentence(artifact);
       if (openingSentenceViolation)
         violations.push(openingSentenceViolation);

package/dist/validation.js

@@ -248,6 +248,7 @@ function validateAuditHeadings(artifact) {
 }
 
 // lib/lint/validators/content-validator.ts
+var FRONT_MATTER_DELIMITER = "---";
 var REQUIRED_TASK_HEADINGS = ["Task Type", "Blocked By", "Definition of Done"];
 var ALLOWED_TASK_TYPES = new Set(VALID_TASK_TYPES);
 var MAX_OPENING_SENTENCE_LENGTH = 150;
@@ -265,6 +266,18 @@ var NON_IMPERATIVE_STARTERS = new Set([
   "you",
   "i"
 ]);
+function validateNoFrontMatter(artifact) {
+  const firstLine = artifact.rawContent.split(`
+`)[0];
+  if (firstLine.trim() === FRONT_MATTER_DELIMITER) {
+    return {
+      file: artifact.filePath,
+      line: 1,
+      message: "Artifact must not contain front matter. The title must be the first line."
+    };
+  }
+  return null;
+}
 function validateOpeningSentence(artifact) {
   if (!artifact.openingSentence) {
     return {
@@ -450,6 +463,8 @@ function validateIdeaOpenQuestions(artifact) {
   const topLevelStructureMessage = "Open Questions must use `### Question?` headings and `#### Option` headings at the top level. Put supporting markdown (including lists and code blocks) under an option heading. Run `dust new idea` to see the expected format.";
   let inOpenQuestions = false;
   let currentQuestionLine = null;
+  let currentQuestionText = null;
+  let currentQuestionOptionNames = new Set;
   let inOption = false;
   let inCodeBlock = false;
   for (let i = 0;i < lines.length; i++) {
@@ -473,6 +488,8 @@ function validateIdeaOpenQuestions(artifact) {
       violations.push(...validateH2Heading(filePath, line, i + 1, inOpenQuestions, currentQuestionLine));
       inOpenQuestions = line === "## Open Questions";
       currentQuestionLine = null;
+      currentQuestionText = null;
+      currentQuestionOptionNames = new Set;
       inOption = false;
       inCodeBlock = false;
       continue;
@@ -488,6 +505,7 @@ function validateIdeaOpenQuestions(artifact) {
           line: currentQuestionLine
         });
       }
+      currentQuestionOptionNames = new Set;
       if (!trimmedLine.endsWith("?")) {
         violations.push({
           file: filePath,
@@ -495,12 +513,24 @@ function validateIdeaOpenQuestions(artifact) {
           line: i + 1
         });
         currentQuestionLine = null;
+        currentQuestionText = null;
       } else {
         currentQuestionLine = i + 1;
+        currentQuestionText = trimmedLine.slice(4);
       }
       continue;
     }
     if (line.startsWith("#### ")) {
+      const optionName = trimmedLine.slice(5);
+      if (currentQuestionOptionNames.has(optionName)) {
+        violations.push({
+          file: filePath,
+          message: `Duplicate option "${optionName}" under question "${currentQuestionText}" — each option must have a unique name`,
+          line: i + 1
+        });
+      } else {
+        currentQuestionOptionNames.add(optionName);
+      }
       currentQuestionLine = null;
       inOption = true;
       continue;
@@ -876,6 +906,9 @@ function validateArtifacts(context) {
   }
   for (const artifacts of Object.values(byType)) {
     for (const artifact of artifacts) {
+      const frontMatterViolation = validateNoFrontMatter(artifact);
+      if (frontMatterViolation)
+        violations.push(frontMatterViolation);
       const openingSentenceViolation = validateOpeningSentence(artifact);
       if (openingSentenceViolation)
         violations.push(openingSentenceViolation);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joshski/dust",
-  "version": "0.1.112",
+  "version": "0.1.113",
   "description": "Flow state for AI coding agents",
   "type": "module",
   "bin": {