fix(util): remove legacy frontmatter fields next/confidence/artifacts/scope (#544)

BREAKING CHANGE: AgentFrontmatter now only has status field.
FrontmatterScope type removed. STANDARD_KEYS reduced to ['status'].
defaultCandidate returns only { status }. validateFrontmatter only validates status.

packages/cli-workflow/src/__tests__/step-show-json.test.ts

@@ -0,0 +1,363 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrap, type Hash, type JSONSchema, putSchema } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, StepNodePayload } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdStepShow } from "../commands/step.js";
+import { formatOutput } from "../format.js";
+import { registerUwfSchemas } from "../schemas.js";
+
+const TURN_SCHEMA: JSONSchema = {
+  title: "test-turn",
+  type: "object",
+  required: ["index", "role", "content"],
+  properties: {
+    index: { type: "integer" },
+    role: { type: "string", enum: ["assistant", "tool"] },
+    content: { type: "string" },
+    toolCalls: {
+      anyOf: [
+        {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["name", "args"],
+            properties: {
+              name: { type: "string" },
+              args: { type: "string" },
+            },
+            additionalProperties: false,
+          },
+        },
+        { type: "null" },
+      ],
+    },
+  },
+  additionalProperties: false,
+};
+
+const DETAIL_SCHEMA: JSONSchema = {
+  title: "test-detail",
+  type: "object",
+  required: ["turns"],
+  properties: {
+    turns: {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+    },
+  },
+  additionalProperties: false,
+};
+
+type TestSetup = {
+  store: ReturnType<typeof createFsStore>;
+  schemas: {
+    workflow: Hash;
+    startNode: Hash;
+    stepNode: Hash;
+    text: Hash;
+  };
+  turnType: Hash;
+  detailType: Hash;
+};
+
+async function setupTest(casDir: string): Promise<TestSetup> {
+  const store = createFsStore(casDir);
+  await bootstrap(store);
+  const schemas = await registerUwfSchemas(store);
+  const [turnType, detailType] = await Promise.all([
+    putSchema(store, TURN_SCHEMA),
+    putSchema(store, DETAIL_SCHEMA),
+  ]);
+  return { store, schemas, turnType, detailType };
+}
+
+async function createTestStep(
+  setup: TestSetup,
+  turnPayloads: Array<{
+    index: number;
+    role: string;
+    content: string;
+    toolCalls: Array<{ name: string; args: string }> | null;
+  }>,
+): Promise<CasRef> {
+  const { store, schemas, turnType, detailType } = setup;
+
+  // Create turn nodes
+  const turnHashes: CasRef[] = [];
+  for (const payload of turnPayloads) {
+    const turnHash = await store.put(turnType, payload);
+    turnHashes.push(turnHash);
+  }
+
+  // Create detail node
+  const detailHash = await store.put(detailType, { turns: turnHashes });
+
+  // Create dummy start node
+  const startHash = await store.put(schemas.startNode, {
+    workflow: "0000000000000" as CasRef,
+    prompt: "test prompt",
+    cwd: "/tmp",
+  });
+
+  // Create dummy output node
+  const outputHash = await store.put(schemas.text, { $status: "done" });
+
+  // Create step node
+  const stepPayload: StepNodePayload = {
+    prev: null,
+    start: startHash,
+    role: "test-role",
+    agent: "test-agent",
+    output: outputHash,
+    detail: detailHash,
+    edgePrompt: "",
+    startedAtMs: Date.now(),
+    completedAtMs: Date.now() + 1000,
+    cwd: "/tmp",
+  };
+  return store.put(schemas.stepNode, stepPayload);
+}
+
+describe("cmdStepShow JSON serialization", () => {
+  let testDir: string;
+  let casDir: string;
+
+  beforeEach(async () => {
+    testDir = await mkdtemp(join(tmpdir(), "uwf-test-"));
+    casDir = join(testDir, "cas");
+    await mkdir(casDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("escapes newlines in tool call args", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "Running command",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "echo 'line1'\necho 'line2'",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    expect(jsonOutput).toContain("\\n");
+
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns[0].toolCalls[0].args).toContain("\n");
+  });
+
+  test("escapes tabs in tool call args", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "cat <<EOF\nfield1\tfield2\tfield3\nEOF",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    expect(jsonOutput).toContain("\\t");
+  });
+
+  test("escapes carriage returns", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "Committing changes",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: 'git commit -m "First line\r\nSecond line"',
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    expect(jsonOutput).toContain("\\r\\n");
+  });
+
+  test("escapes backslashes and quotes", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: 'echo "He said \\"hello\\""',
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toBeDefined();
+  });
+
+  test("handles Unicode control characters", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "echo '\u0001\u001F'",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+  });
+
+  test("handles nested CAS refs with control characters", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "First turn\nwith newline",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "cmd1\nline2",
+          },
+        ],
+      },
+      {
+        index: 1,
+        role: "assistant",
+        content: "Second turn\twith tab",
+        toolCalls: null,
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toHaveLength(2);
+  });
+
+  test("YAML output format is unaffected", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "Running command",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "echo 'line1'\necho 'line2'",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const yamlOutput = formatOutput(result, "yaml");
+
+    expect(yamlOutput).toContain("turns:");
+    expect(yamlOutput.length).toBeGreaterThan(0);
+  });
+
+  test("handles empty and null values", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: null,
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toBeDefined();
+  });
+
+  test("handles large step with multiple tool calls", async () => {
+    const setup = await setupTest(casDir);
+
+    const turns = [];
+    for (let i = 0; i < 25; i++) {
+      turns.push({
+        index: i,
+        role: "assistant" as const,
+        content: `Turn ${i}\nwith newline`,
+        toolCalls: [
+          {
+            name: "Bash",
+            args: `command${i}\nline2\tfield${i}`,
+          },
+          {
+            name: "Read",
+            args: `/path/to/file${i}`,
+          },
+        ],
+      });
+    }
+
+    const stepHash = await createTestStep(setup, turns);
+
+    const startTime = Date.now();
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+    const duration = Date.now() - startTime;
+
+    expect(duration).toBeLessThan(2000);
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toHaveLength(25);
+  });
+});

packages/cli-workflow/src/__tests__/thread-show-status.test.ts

@@ -0,0 +1,227 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { createMarker, deleteMarker } from "../background/index.js";
+import { cmdThreadShow, cmdThreadStart } from "../commands/thread.js";
+import { appendThreadHistory, loadThreadsIndex } from "../store.js";
+
+const TEST_WORKFLOW_YAML = `
+name: test-status
+description: Test workflow for status field
+roles:
+  planner:
+    description: Plans the work
+    goal: Plan implementation
+    capabilities: ["planning"]
+    procedure: Plan
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: planner
+      prompt: "Plan the work"
+      location: null
+  planner:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+describe("thread show status field", () => {
+  let tmpDir: string;
+  let storageRoot: string;
+
+  async function setupTestEnv() {
+    tmpDir = join(tmpdir(), `uwf-test-status-${Date.now()}`);
+    storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+  }
+
+  async function teardown() {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  test("active idle thread shows status 'idle'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+
+    // Show the thread (should be idle)
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("idle");
+    expect(result.done).toBe(false);
+    expect(result.background).toBe(null);
+    expect(result.thread).toBe(threadId);
+
+    await teardown();
+  });
+
+  test("active running thread shows status 'running'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Create a running marker
+    await createMarker(storageRoot, {
+      thread: threadId,
+      workflow,
+      pid: process.pid,
+      startedAt: Date.now(),
+    });
+
+    try {
+      const result = await cmdThreadShow(storageRoot, threadId);
+
+      expect(result.status).toBe("running");
+      expect(result.done).toBe(false);
+      expect(result.background).toBe(null);
+      expect(result.thread).toBe(threadId);
+    } finally {
+      // Cleanup: delete marker
+      await deleteMarker(storageRoot, threadId);
+      await teardown();
+    }
+  });
+
+  test("completed thread shows status 'completed'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Get the head hash before moving to history
+    const index = await loadThreadsIndex(storageRoot);
+    const head = index[threadId];
+    if (!head) throw new Error("Thread not found in index");
+
+    // Move thread to history with reason 'completed'
+    const { saveThreadsIndex } = await import("../store.js");
+    const newIndex = { ...index };
+    delete newIndex[threadId];
+    await saveThreadsIndex(storageRoot, newIndex);
+
+    await appendThreadHistory(storageRoot, {
+      thread: threadId,
+      workflow,
+      head,
+      completedAt: Date.now(),
+      reason: "completed",
+    });
+
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("completed");
+    expect(result.done).toBe(true);
+    expect(result.background).toBe(null);
+    expect(result.thread).toBe(threadId);
+
+    await teardown();
+  });
+
+  test("cancelled thread shows status 'cancelled'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Get the head hash before moving to history
+    const index = await loadThreadsIndex(storageRoot);
+    const head = index[threadId];
+    if (!head) throw new Error("Thread not found in index");
+
+    // Move thread to history with reason 'cancelled'
+    const { saveThreadsIndex } = await import("../store.js");
+    const newIndex = { ...index };
+    delete newIndex[threadId];
+    await saveThreadsIndex(storageRoot, newIndex);
+
+    await appendThreadHistory(storageRoot, {
+      thread: threadId,
+      workflow,
+      head,
+      completedAt: Date.now(),
+      reason: "cancelled",
+    });
+
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("cancelled");
+    expect(result.done).toBe(true);
+    expect(result.background).toBe(null);
+    expect(result.thread).toBe(threadId);
+
+    await teardown();
+  });
+
+  test("legacy completed thread without reason shows status 'completed'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Get the head hash before moving to history
+    const index = await loadThreadsIndex(storageRoot);
+    const head = index[threadId];
+    if (!head) throw new Error("Thread not found in index");
+
+    // Move thread to history with reason null (legacy format)
+    const { saveThreadsIndex } = await import("../store.js");
+    const newIndex = { ...index };
+    delete newIndex[threadId];
+    await saveThreadsIndex(storageRoot, newIndex);
+
+    await appendThreadHistory(storageRoot, {
+      thread: threadId,
+      workflow,
+      head,
+      completedAt: Date.now(),
+      reason: null,
+    });
+
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("completed");
+    expect(result.done).toBe(true);
+    expect(result.background).toBe(null);
+
+    await teardown();
+  });
+});

packages/cli-workflow/src/__tests__/thread-start-cwd-cli.test.ts

@@ -0,0 +1,148 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, StartNodePayload, ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { cmdThreadStart } from "../commands/thread.js";
+import { createUwfStore, loadThreadsIndex } from "../store.js";
+
+describe("thread start --cwd CLI option", () => {
+  let tmpDir: string;
+  let storageRoot: string;
+
+  async function setupTestEnv() {
+    tmpDir = join(tmpdir(), `uwf-test-cwd-cli-${Date.now()}`);
+    storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+  }
+
+  async function teardown() {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  async function createTestWorkflow(): Promise<string> {
+    const workflowYaml = `
+name: test-cwd-cli
+description: Test workflow for CLI cwd option
+roles:
+  planner:
+    description: Plans the work
+    goal: Plan implementation
+    capabilities: ["planning"]
+    procedure: Plan
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: planner
+      prompt: "Plan the work"
+      location: null
+  planner:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+    const workflowPath = join(tmpDir, "test-cwd-cli.yaml");
+    await writeFile(workflowPath, workflowYaml, "utf8");
+    return workflowPath;
+  }
+
+  async function getStartNodeCwd(threadId: string): Promise<string> {
+    const uwf = await createUwfStore(storageRoot);
+    const index = await loadThreadsIndex(storageRoot);
+    const headHash = index[threadId as ThreadId];
+    expect(headHash).toBeDefined();
+
+    const startNode = uwf.store.get(headHash as CasRef);
+    expect(startNode).not.toBe(null);
+    expect(startNode?.type).toBe(uwf.schemas.startNode);
+
+    const startPayload = startNode?.payload as StartNodePayload;
+    return startPayload.cwd;
+  }
+
+  test("thread start with custom cwd via cmdThreadStart", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+    const testCwd = "/test/custom/path";
+
+    const result = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir, testCwd);
+
+    expect(result.thread).toBeDefined();
+    const actualCwd = await getStartNodeCwd(result.thread);
+    expect(actualCwd).toBe(testCwd);
+
+    await teardown();
+  });
+
+  test("thread start without cwd defaults to process.cwd()", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+
+    // Call without cwd parameter (it defaults to process.cwd())
+    const result = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+
+    expect(result.thread).toBeDefined();
+    const actualCwd = await getStartNodeCwd(result.thread);
+    expect(actualCwd).toBe(process.cwd());
+
+    await teardown();
+  });
+
+  test("thread start with relative path fails", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+
+    await expect(
+      cmdThreadStart(storageRoot, workflowPath, "test", tmpDir, "relative/path"),
+    ).rejects.toThrow();
+
+    await teardown();
+  });
+
+  test("CLI accepts --cwd option without error", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+    const testCwd = "/test/cli/path";
+    const uwfBin = join(process.cwd(), "dist", "cli.js");
+
+    // Register the workflow
+    execFileSync("node", [uwfBin, "workflow", "add", workflowPath], {
+      env: { ...process.env, UWF_STORAGE_ROOT: storageRoot },
+      encoding: "utf8",
+    });
+
+    // Verify CLI accepts --cwd option (no error thrown)
+    const output = execFileSync(
+      "node",
+      [uwfBin, "thread", "start", "test-cwd-cli", "-p", "test prompt", "--cwd", testCwd],
+      {
+        env: { ...process.env, UWF_STORAGE_ROOT: storageRoot },
+        encoding: "utf8",
+      },
+    );
+
+    const result = JSON.parse(output);
+    expect(result.thread).toBeDefined();
+    expect(result.workflow).toBeDefined();
+
+    // The fact that we got here without throwing means CLI accepted the --cwd option
+    // The actual cwd functionality is tested by the other tests using cmdThreadStart directly
+    await teardown();
+  });
+});

packages/cli-workflow/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import type { CasRef, ThreadId, ThreadStatus } from "@uncaged/workflow-protocol";
 import { Command } from "commander";
 import {
   cmdCasGet,
@@ -38,7 +38,6 @@ import {
   cmdThreadStart,
   cmdThreadStop,
   THREAD_READ_DEFAULT_QUOTA,
-  type ThreadStatus,
 } from "./commands/thread.js";
 import { parseTimeInput } from "./commands/thread-time-parser.js";
 import { cmdWorkflowAdd, cmdWorkflowList, cmdWorkflowShow } from "./commands/workflow.js";
@@ -118,10 +117,17 @@ thread
   .description("Create a thread without executing")
   .argument("<workflow>", "Workflow name or hash")
   .requiredOption("-p, --prompt <text>", "User prompt")
-  .action((workflow: string, opts: { prompt: string }) => {
+  .option("--cwd <path>", "Working directory for thread execution (default: process.cwd())")
+  .action((workflow: string, opts: { prompt: string; cwd: string | undefined }) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt, process.cwd());
+      const result = await cmdThreadStart(
+        storageRoot,
+        workflow,
+        opts.prompt,
+        process.cwd(),
+        opts.cwd ?? process.cwd(),
+      );
       writeOutput(result);
     });
   });

packages/cli-workflow/src/commands/thread.ts

@@ -12,6 +12,7 @@ import type {
   StepOutput,
   ThreadId,
   ThreadListItem,
+  ThreadStatus,
   ThreadsIndex,
   WorkflowConfig,
   WorkflowPayload,
@@ -315,10 +316,16 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
     if (workflow === null) {
       fail(`failed to resolve workflow from head: ${activeHead}`);
     }
+
+    // Check if thread is running
+    const runningMarker = await isThreadRunning(storageRoot, threadId);
+    const status: ThreadStatus = runningMarker !== null ? "running" : "idle";
+
     return {
       workflow,
       thread: threadId,
       head: activeHead,
+      status,
       done: false,
       background: null,
     };
@@ -326,10 +333,13 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
 
   const hist = await findThreadInHistory(storageRoot, threadId);
   if (hist !== null) {
+    const status: ThreadStatus = hist.reason === "cancelled" ? "cancelled" : "completed";
+
     return {
       workflow: hist.workflow,
       thread: threadId,
       head: hist.head,
+      status,
       done: true,
       background: null,
     };
@@ -338,8 +348,6 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
   fail(`thread not found: ${threadId}`);
 }
 
-export type ThreadStatus = "idle" | "running" | "completed" | "cancelled";
-
 export type ThreadListItemWithStatus = ThreadListItem & {
   status: ThreadStatus;
 };
@@ -947,6 +955,7 @@ async function cmdThreadStepBackground(
       workflow: workflowHash,
       thread: threadId,
       head: headHash,
+      status: "running",
       done: false,
       background: true,
     },
@@ -989,6 +998,7 @@ async function cmdThreadStepOnce(
       workflow: workflowHash,
       thread: threadId,
       head: headHash,
+      status: "completed",
       done: true,
       background: null,
     };
@@ -1041,10 +1051,14 @@ async function cmdThreadStepOnce(
     await archiveThread(storageRoot, threadId, workflowHash, newHead);
   }
 
+  // Determine status based on whether thread is done and running state
+  const status: ThreadStatus = done ? "completed" : "idle";
+
   return {
     workflow: workflowHash,
     thread: threadId,
     head: newHead,
+    status,
     done,
     background: null,
   };

packages/cli-workflow/src/moderator/__tests__/evaluate.test.ts

@@ -1,6 +1,97 @@
 import { describe, expect, test } from "vitest";
 import { evaluate } from "../evaluate.js";
 
+describe("Edge prompt template variable resolution", () => {
+  test("returns error when rendered prompt is empty string", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("prompt");
+      expect(result.error.message).toContain("empty");
+    }
+  });
+
+  test("returns error when rendered prompt is whitespace-only", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "  {{{userPrompt}}}  ", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("prompt");
+      expect(result.error.message).toContain("empty");
+    }
+  });
+
+  test("succeeds when all template variables resolve to non-empty values", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", { userPrompt: "Fix the bug" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Fix the bug");
+    }
+  });
+
+  test("succeeds with static (no-variable) prompt", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "Classify this input", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Classify this input");
+    }
+  });
+
+  test("succeeds when prompt has mix of static text and unresolved variables", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "Please handle: {{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Please handle: ");
+    }
+  });
+
+  test("returns error when ALL variables missing and no static text remains", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{a}}}{{{b}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+  });
+});
+
 describe("Moderator location resolution", () => {
   test("returns null location when edge has no location field", () => {
     const graph = {

packages/cli-workflow/src/moderator/evaluate.ts

@@ -43,6 +43,14 @@ export function evaluate(
 
   try {
     const prompt = mustache.render(target.prompt, lastOutput);
+    if (prompt.trim() === "") {
+      return {
+        ok: false,
+        error: new Error(
+          `edge prompt resolved to empty string for role "${target.role}" (template: "${target.prompt}"). Check that upstream output includes required variables.`,
+        ),
+      };
+    }
     const location = target.location !== null ? mustache.render(target.location, lastOutput) : null;
     return { ok: true, value: { role: target.role, prompt, location } };
   } catch (error) {

packages/workflow-protocol/src/index.ts

@@ -29,6 +29,7 @@ export type {
   ThreadForkOutput,
   ThreadId,
   ThreadListItem,
+  ThreadStatus,
   ThreadStepsOutput,
   ThreadsIndex,
   WorkflowConfig,

packages/workflow-protocol/src/types.ts

@@ -76,17 +76,27 @@ export type ModeratorContext = {
 
 // ── 4.5 CLI 输出 ────────────────────────────────────────────────────
 
+/** Thread status — unified status representation */
+export type ThreadStatus = "idle" | "running" | "completed" | "cancelled";
+
 /** uwf thread start */
 export type StartOutput = {
   workflow: CasRef;
   thread: ThreadId;
 };
 
-/** uwf thread step / uwf thread show */
+/**
+ * Output from thread show and thread exec commands.
+ *
+ * @property status - Current thread status (idle/running/completed/cancelled)
+ * @property done - @deprecated Use status field instead. True if thread is completed or cancelled.
+ * @property background - @deprecated Use status field instead. Always null in current implementation.
+ */
 export type StepOutput = {
   workflow: CasRef;
   thread: ThreadId;
   head: CasRef;
+  status: ThreadStatus;
   done: boolean;
   background: boolean | null;
 };

packages/workflow-util-agent/__tests__/frontmatter-fast-path.test.ts

@@ -5,17 +5,13 @@ import { tryFrontmatterFastPath } from "../src/frontmatter.js";
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
-/** JSON Schema that exactly matches the AgentFrontmatter fields. */
-const FRONTMATTER_SCHEMA = {
+/** JSON Schema that matches the new status-only AgentFrontmatter. */
+const STATUS_ONLY_SCHEMA = {
   type: "object",
   properties: {
     status: { anyOf: [{ type: "string" }, { type: "null" }] },
-    next: { anyOf: [{ type: "string" }, { type: "null" }] },
-    confidence: { anyOf: [{ type: "number" }, { type: "null" }] },
-    artifacts: { type: "array", items: { type: "string" } },
-    scope: { type: "string" },
   },
-  required: ["status", "next", "confidence", "artifacts", "scope"],
+  required: ["status"],
   additionalProperties: false,
 };
 
@@ -56,24 +52,41 @@ async function makeStoreWithSchema(schema: Record<string, unknown>) {
   return { store, schemaHash };
 }
 
+// ── STANDARD_KEYS ────────────────────────────────────────────────────────────
+
+describe("STANDARD_KEYS contains only status", () => {
+  test("STANDARD_KEYS is ['status']", async () => {
+    // We verify indirectly: defaultCandidate (no schema fields) returns only { status }
+    const { store, schemaHash } = await makeStoreWithSchema({
+      type: "object",
+      properties: {
+        status: { anyOf: [{ type: "string" }, { type: "null" }] },
+      },
+    });
+
+    const raw = "---\nstatus: done\n---\n\nBody.";
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).not.toBeNull();
+
+    const node = store.get(result!.outputHash);
+    expect(node).not.toBeNull();
+    const payload = node!.payload as Record<string, unknown>;
+    expect(payload.status).toBe("done");
+    // Legacy fields must NOT be present
+    expect(payload.next).toBeUndefined();
+    expect(payload.confidence).toBeUndefined();
+    expect(payload.artifacts).toBeUndefined();
+    expect(payload.scope).toBeUndefined();
+  });
+});
+
 // ── Happy path ─────────────────────────────────────────────────────────────────
 
 describe("tryFrontmatterFastPath — happy path", () => {
   test("parses valid frontmatter and returns outputHash + stripped body", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
 
-    const raw = [
-      "---",
-      "status: done",
-      "next: reviewer",
-      "confidence: 0.9",
-      "artifacts: [src/foo.ts]",
-      "scope: role",
-      "---",
-      "",
-      "## Summary",
-      "Work is complete.",
-    ].join("\n");
+    const raw = ["---", "status: done", "---", "", "## Summary", "Work is complete."].join("\n");
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
 
@@ -85,11 +98,10 @@ describe("tryFrontmatterFastPath — happy path", () => {
     expect((result?.outputHash ?? "").length).toBeGreaterThan(0);
   });
 
-  test("stored CAS node payload matches frontmatter fields", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+  test("stored CAS node payload has only status", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
 
-    const raw =
-      "---\nstatus: done\nnext: null\nconfidence: null\nartifacts: []\nscope: role\n---\n\nBody.";
+    const raw = "---\nstatus: done\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).not.toBeNull();
@@ -98,10 +110,29 @@ describe("tryFrontmatterFastPath — happy path", () => {
     expect(node).not.toBeNull();
     const payload = node!.payload as Record<string, unknown>;
     expect(payload.status).toBe("done");
-    expect(payload.next).toBeNull();
-    expect(payload.confidence).toBeNull();
-    expect(payload.artifacts).toEqual([]);
-    expect(payload.scope).toBe("role");
+    expect(Object.keys(payload)).toEqual(["status"]);
+  });
+});
+
+// ── Legacy fields in input are ignored ──────────────────────────────────────
+
+describe("tryFrontmatterFastPath — legacy fields ignored", () => {
+  test("legacy fields in input do not appear in CAS output", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
+
+    const raw =
+      "---\nstatus: done\nnext: reviewer\nconfidence: 0.9\nartifacts: [a.ts]\nscope: thread\n---\n\nBody.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).not.toBeNull();
+
+    const node = store.get(result!.outputHash);
+    const payload = node!.payload as Record<string, unknown>;
+    expect(payload.status).toBe("done");
+    expect(payload.next).toBeUndefined();
+    expect(payload.confidence).toBeUndefined();
+    expect(payload.artifacts).toBeUndefined();
+    expect(payload.scope).toBeUndefined();
   });
 });
 
@@ -109,7 +140,7 @@ describe("tryFrontmatterFastPath — happy path", () => {
 
 describe("tryFrontmatterFastPath — fallback: no frontmatter", () => {
   test("returns null for plain markdown without frontmatter block", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
 
     const result = await tryFrontmatterFastPath(
       "This is plain markdown without any frontmatter.",
@@ -121,35 +152,13 @@ describe("tryFrontmatterFastPath — fallback: no frontmatter", () => {
   });
 });
 
-// ── Fallback: invalid frontmatter ─────────────────────────────────────────────
-
-describe("tryFrontmatterFastPath — fallback: invalid frontmatter", () => {
-  test("returns null when confidence is out of range [0, 1]", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
-
-    const raw = "---\nstatus: done\nconfidence: 1.5\nscope: role\n---\n\nBody.";
-
-    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
-    expect(result).toBeNull();
-  });
-
-  test("returns null when next contains whitespace", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
-
-    const raw = "---\nstatus: done\nnext: some role\nscope: role\n---\n\nBody.";
-
-    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
-    expect(result).toBeNull();
-  });
-});
-
 // ── Fallback: schema mismatch ─────────────────────────────────────────────────
 
 describe("tryFrontmatterFastPath — fallback: schema mismatch", () => {
   test("returns null when outputSchema requires fields not in frontmatter", async () => {
     const { store, schemaHash } = await makeStoreWithSchema(STRICT_SCHEMA);
 
-    const raw = "---\nstatus: done\nscope: role\n---\n\nBody.";
+    const raw = "---\nstatus: done\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).toBeNull();
@@ -194,7 +203,7 @@ describe("tryFrontmatterFastPath — role-specific fields", () => {
   test("returns null when required role-specific field is missing", async () => {
     const { store, schemaHash } = await makeStoreWithSchema(REVIEWER_SCHEMA);
 
-    const raw = "---\nstatus: done\nscope: role\n---\n\nBody.";
+    const raw = "---\nstatus: done\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).toBeNull();

packages/workflow-util-agent/src/__tests__/parseArgv.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+describe("parseArgv empty prompt error message", () => {
+  let stderrOutput: string;
+  let _exitCode: number | null;
+  const originalExit = process.exit;
+  const originalStderrWrite = process.stderr.write;
+
+  beforeEach(() => {
+    stderrOutput = "";
+    _exitCode = null;
+    process.exit = ((code?: number) => {
+      _exitCode = code ?? 1;
+      throw new Error("process.exit called");
+    }) as any;
+    process.stderr.write = ((chunk: string) => {
+      stderrOutput += chunk;
+      return true;
+    }) as any;
+  });
+
+  afterEach(() => {
+    process.exit = originalExit;
+    process.stderr.write = originalStderrWrite;
+  });
+
+  test("empty prompt produces error message mentioning template variables", async () => {
+    const { parseArgv } = await import("../run.js");
+    const argv = [
+      "node",
+      "uwf-hermes",
+      "--thread",
+      "01ABCDEFGHIJKLMNOPQRSTUVWX",
+      "--role",
+      "classifier",
+      "--prompt",
+      "",
+    ];
+
+    expect(() => parseArgv(argv)).toThrow("process.exit called");
+    expect(stderrOutput).toContain("prompt");
+    expect(stderrOutput).toContain("empty");
+    expect(stderrOutput).toContain("template");
+  });
+});

packages/workflow-util-agent/src/frontmatter.ts

@@ -13,7 +13,7 @@ import { extractSchemaFields } from "./build-output-format-instruction.js";
 
 const log = createLogger({ sink: { kind: "stderr" } });
 
-const STANDARD_KEYS = ["status", "next", "confidence", "artifacts", "scope"] as const;
+const STANDARD_KEYS = ["status"] as const;
 
 type StandardKey = (typeof STANDARD_KEYS)[number];
 
@@ -62,10 +62,6 @@ function parseRawFrontmatterFields(raw: string): Record<string, unknown> {
 function defaultCandidate(frontmatter: AgentFrontmatter): Record<string, unknown> {
   return {
     status: frontmatter.status,
-    next: frontmatter.next,
-    confidence: frontmatter.confidence,
-    artifacts: [...frontmatter.artifacts],
-    scope: frontmatter.scope,
   };
 }
 
@@ -73,14 +69,6 @@ function pickStandardField(frontmatter: AgentFrontmatter, key: StandardKey): unk
   switch (key) {
     case "status":
       return frontmatter.status;
-    case "next":
-      return frontmatter.next;
-    case "confidence":
-      return frontmatter.confidence;
-    case "artifacts":
-      return [...frontmatter.artifacts];
-    case "scope":
-      return frontmatter.scope;
   }
 }
 
@@ -98,9 +86,6 @@ function pickFieldValue(
   }
 
   const coerced = pickStandardField(frontmatter, field);
-  if (field === "artifacts" || field === "scope") {
-    return coerced;
-  }
   if (coerced !== null) {
     return coerced;
   }
@@ -110,8 +95,8 @@ function pickFieldValue(
 /**
  * Build a CAS candidate object from schema property keys and parsed frontmatter.
  *
- * When the schema has no inspectable properties, falls back to the five standard
- * agent frontmatter fields for backward compatibility.
+ * When the schema has no inspectable properties, falls back to the standard
+ * agent frontmatter field (status only).
  */
 function buildCandidate(
   frontmatter: AgentFrontmatter,

packages/workflow-util-agent/src/index.ts

@@ -11,7 +11,7 @@ export {
 } from "./extract.js";
 export type { FrontmatterFastPathResult } from "./frontmatter.js";
 export { tryFrontmatterFastPath } from "./frontmatter.js";
-export { createAgent } from "./run.js";
+export { createAgent, parseArgv } from "./run.js";
 export { getCachedSessionId, getCachePath, setCachedSessionId } from "./session-cache.js";
 export { getConfigPath, getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
 export type {

packages/workflow-util-agent/src/run.ts

@@ -32,13 +32,16 @@ function getNamedArg(argv: string[], name: string): string {
   return argv[idx + 1];
 }
 
-function parseArgv(argv: string[]): { threadId: ThreadId; role: string; prompt: string } {
+export function parseArgv(argv: string[]): { threadId: ThreadId; role: string; prompt: string } {
   const threadId = getNamedArg(argv, "--thread");
   const role = getNamedArg(argv, "--role");
   const prompt = getNamedArg(argv, "--prompt");
   if (threadId === "") fail(USAGE);
   if (role === "") fail(USAGE);
-  if (prompt === "") fail(USAGE);
+  if (prompt === "")
+    fail(
+      `--prompt is empty. If this agent was spawned by uwf, the edge prompt template may have unresolved variables. ${USAGE}`,
+    );
   return { threadId: threadId as ThreadId, role, prompt };
 }
 

packages/workflow-util/__tests__/frontmatter-markdown.test.ts

@@ -41,31 +41,13 @@ describe("parseFrontmatterMarkdown", () => {
     });
   });
 
-  describe("full frontmatter document", () => {
-    it("parses all fields from a well-formed document", () => {
-      const raw = `---
-status: done
-next: reviewer
-confidence: 0.9
-artifacts:
-  - src/foo.ts
-  - src/bar.ts
-scope: thread
----
-
-## Summary
-
-Everything looks good.`;
-
+  describe("status-only frontmatter", () => {
+    it("parses status-only frontmatter", () => {
+      const raw = "---\nstatus: done\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter).not.toBeNull();
-      const fm = result.frontmatter!;
-      expect(fm.status).toBe("done");
-      expect(fm.next).toBe("reviewer");
-      expect(fm.confidence).toBe(0.9);
-      expect(fm.artifacts).toEqual(["src/foo.ts", "src/bar.ts"]);
-      expect(fm.scope).toBe("thread");
-      expect(result.body).toBe("## Summary\n\nEverything looks good.");
+      expect(result.frontmatter).toEqual({ status: "done" });
+      expect(result.body).toBe("body");
     });
 
     it("strips leading newline from body", () => {
@@ -87,6 +69,22 @@ Everything looks good.`;
     });
   });
 
+  describe("ignores legacy fields", () => {
+    it("legacy fields next/confidence/artifacts/scope are NOT present on result", () => {
+      const raw =
+        "---\nstatus: done\nnext: reviewer\nconfidence: 0.9\nartifacts:\n  - src/foo.ts\nscope: thread\n---\n\nBody.";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).not.toBeNull();
+      const fm = result.frontmatter!;
+      expect(fm.status).toBe("done");
+      // Legacy fields must not exist on the object at all
+      expect("next" in fm).toBe(false);
+      expect("confidence" in fm).toBe(false);
+      expect("artifacts" in fm).toBe(false);
+      expect("scope" in fm).toBe(false);
+    });
+  });
+
   describe("status field", () => {
     it.each([
       "done",
@@ -106,109 +104,18 @@ Everything looks good.`;
     });
 
     it("returns null status when omitted", () => {
-      const raw = "---\nconfidence: 0.5\n---\nbody";
+      const raw = "---\nfoo: bar\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter?.status).toBeNull();
     });
   });
 
-  describe("confidence field", () => {
-    it("parses integer as number", () => {
-      const raw = "---\nconfidence: 1\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBe(1);
-    });
-
-    it("parses decimal", () => {
-      const raw = "---\nconfidence: 0.75\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBe(0.75);
-    });
-
-    it("returns null when omitted", () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBeNull();
-    });
-
-    it("returns null for non-numeric value", () => {
-      const raw = "---\nconfidence: high\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBeNull();
-    });
-  });
-
-  describe("artifacts field", () => {
-    it("parses block sequence", () => {
-      const raw = "---\nartifacts:\n  - a.ts\n  - b.ts\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual(["a.ts", "b.ts"]);
-    });
-
-    it("parses inline sequence", () => {
-      const raw = "---\nartifacts: [a.ts, b.ts]\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual(["a.ts", "b.ts"]);
-    });
-
-    it("returns empty array when omitted", () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual([]);
-    });
-
-    it("wraps single scalar in array", () => {
-      const raw = "---\nartifacts: only-one.ts\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual(["only-one.ts"]);
-    });
-  });
-
-  describe("scope field", () => {
-    it('parses scope "role"', () => {
-      const raw = "---\nscope: role\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("role");
-    });
-
-    it('parses scope "thread"', () => {
-      const raw = "---\nscope: thread\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("thread");
-    });
-
-    it('defaults to "role" when omitted', () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("role");
-    });
-
-    it('defaults to "role" for unknown scope value', () => {
-      const raw = "---\nscope: global\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("role");
-    });
-  });
-
-  describe("next field", () => {
-    it("parses a role name", () => {
-      const raw = "---\nnext: planner\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.next).toBe("planner");
-    });
-
-    it("returns null when omitted", () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.next).toBeNull();
-    });
-  });
-
   describe("unknown fields", () => {
     it("ignores unknown keys silently", () => {
       const raw = "---\nunknown_field: some_value\nstatus: done\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter?.status).toBe("done");
+      expect(Object.keys(result.frontmatter!)).toEqual(["status"]);
     });
   });
 
@@ -221,123 +128,58 @@ Everything looks good.`;
   });
 
   describe("empty frontmatter block", () => {
-    it("parses empty frontmatter and uses all defaults", () => {
+    it("parses empty frontmatter with status null", () => {
       const raw = "---\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter).not.toBeNull();
       const fm = result.frontmatter!;
       expect(fm.status).toBeNull();
-      expect(fm.next).toBeNull();
-      expect(fm.confidence).toBeNull();
-      expect(fm.artifacts).toEqual([]);
-      expect(fm.scope).toBe("role");
+      expect(Object.keys(fm)).toEqual(["status"]);
       expect(result.body).toBe("body");
     });
   });
+
+  describe("AgentFrontmatter has exactly one field", () => {
+    it("has only status key", () => {
+      const fm: AgentFrontmatter = { status: null };
+      expect(Object.keys(fm)).toEqual(["status"]);
+    });
+  });
+
+  describe("FrontmatterValidationError only has status variant", () => {
+    it("status variant is valid", () => {
+      const err: import("../src/index.js").FrontmatterValidationError = {
+        field: "status",
+        message: "test",
+      };
+      expect(err.field).toBe("status");
+    });
+  });
 });
 
 // ── validateFrontmatter ──────────────────────────────────────────────────────
 
-function validFm(overrides: Partial<AgentFrontmatter> = {}): AgentFrontmatter {
-  return {
-    status: "done",
-    next: null,
-    confidence: null,
-    artifacts: [],
-    scope: "role",
-    ...overrides,
-  };
-}
-
 describe("validateFrontmatter", () => {
-  it("returns no errors for a fully valid frontmatter", () => {
-    const errors = validateFrontmatter(validFm());
+  it("returns no errors for a valid status", () => {
+    const errors = validateFrontmatter({ status: "done" });
     expect(errors).toHaveLength(0);
   });
 
-  it("returns no errors when all nullable fields are null", () => {
-    const fm: AgentFrontmatter = {
-      status: null,
-      next: null,
-      confidence: null,
-      artifacts: [],
-      scope: "role",
-    };
+  it("returns no errors when status is null", () => {
+    const errors = validateFrontmatter({ status: null });
+    expect(errors).toHaveLength(0);
+  });
+
+  it("returns error for invalid status", () => {
+    const errors = validateFrontmatter({ status: "bogus" as never });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]?.field).toBe("status");
+  });
+
+  it("no validation for next/confidence/artifacts/scope — fields do not exist", () => {
+    // AgentFrontmatter only has status — verify at runtime
+    const fm: AgentFrontmatter = { status: "done" };
+    expect(Object.keys(fm)).toEqual(["status"]);
     expect(validateFrontmatter(fm)).toHaveLength(0);
   });
-
-  describe("confidence validation", () => {
-    it("accepts 0.0", () => {
-      expect(validateFrontmatter(validFm({ confidence: 0 }))).toHaveLength(0);
-    });
-
-    it("accepts 1.0", () => {
-      expect(validateFrontmatter(validFm({ confidence: 1 }))).toHaveLength(0);
-    });
-
-    it("rejects value below 0", () => {
-      const errors = validateFrontmatter(validFm({ confidence: -0.1 }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("confidence");
-    });
-
-    it("rejects value above 1", () => {
-      const errors = validateFrontmatter(validFm({ confidence: 1.01 }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("confidence");
-    });
-  });
-
-  describe("next validation", () => {
-    it("accepts a simple role name", () => {
-      expect(validateFrontmatter(validFm({ next: "reviewer" }))).toHaveLength(0);
-    });
-
-    it("accepts kebab-case role name", () => {
-      expect(validateFrontmatter(validFm({ next: "code-reviewer" }))).toHaveLength(0);
-    });
-
-    it("rejects role name with whitespace", () => {
-      const errors = validateFrontmatter(validFm({ next: "role name" }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("next");
-    });
-  });
-
-  describe("artifacts validation", () => {
-    it("accepts non-empty path strings", () => {
-      expect(
-        validateFrontmatter(validFm({ artifacts: ["src/foo.ts", "src/bar.ts"] })),
-      ).toHaveLength(0);
-    });
-
-    it("rejects empty string artifact entries", () => {
-      const errors = validateFrontmatter(validFm({ artifacts: [""] }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("artifacts");
-    });
-
-    it("rejects whitespace-only artifact entries", () => {
-      const errors = validateFrontmatter(validFm({ artifacts: ["   "] }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("artifacts");
-    });
-  });
-
-  describe("multiple errors", () => {
-    it("reports multiple violations at once", () => {
-      const fm: AgentFrontmatter = {
-        status: "done",
-        next: "bad role",
-        confidence: 2,
-        artifacts: [""],
-        scope: "role",
-      };
-      const errors = validateFrontmatter(fm);
-      const fields = errors.map((e) => e.field);
-      expect(fields).toContain("next");
-      expect(fields).toContain("confidence");
-      expect(fields).toContain("artifacts");
-    });
-  });
 });

packages/workflow-util/src/frontmatter-markdown/frontmatter-markdown.ts

@@ -1,6 +1,5 @@
 import type {
   AgentFrontmatter,
-  FrontmatterScope,
   FrontmatterStatus,
   FrontmatterValidationError,
   ParsedFrontmatterMarkdown,
@@ -159,40 +158,12 @@ function parseMinimalYaml(yaml: string): Record<string, YamlValue> {
 
 const VALID_STATUS: readonly FrontmatterStatus[] = ["done", "needs_input", "in_progress", "failed"];
 
-const VALID_SCOPE: readonly FrontmatterScope[] = ["role", "thread"];
-
 function coerceStatus(raw: YamlValue): FrontmatterStatus | null {
   if (raw === null || raw === undefined) return null;
   const s = String(raw).trim().toLowerCase();
   return VALID_STATUS.includes(s as FrontmatterStatus) ? (s as FrontmatterStatus) : null;
 }
 
-function coerceNext(raw: YamlValue): string | null {
-  if (raw === null || raw === undefined) return null;
-  const s = String(raw).trim();
-  return s === "" ? null : s;
-}
-
-function coerceConfidence(raw: YamlValue): number | null {
-  if (raw === null || raw === undefined) return null;
-  const n = typeof raw === "number" ? raw : Number(String(raw).trim());
-  if (Number.isNaN(n)) return null;
-  return n;
-}
-
-function coerceArtifacts(raw: YamlValue): readonly string[] {
-  if (raw === null || raw === undefined) return [];
-  if (Array.isArray(raw)) return raw.map(String).filter((s) => s !== "");
-  const s = String(raw).trim();
-  return s === "" ? [] : [s];
-}
-
-function coerceScope(raw: YamlValue): FrontmatterScope {
-  if (raw === null || raw === undefined) return "role";
-  const s = String(raw).trim().toLowerCase();
-  return VALID_SCOPE.includes(s as FrontmatterScope) ? (s as FrontmatterScope) : "role";
-}
-
 // ── Public API ───────────────────────────────────────────────────────────────
 
 /**
@@ -220,10 +191,6 @@ export function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
 
   const frontmatter: AgentFrontmatter = {
     status: coerceStatus(fields.status ?? null),
-    next: coerceNext(fields.next ?? null),
-    confidence: coerceConfidence(fields.confidence ?? null),
-    artifacts: coerceArtifacts(fields.artifacts ?? null),
-    scope: coerceScope(fields.scope ?? null),
   };
 
   return { frontmatter, body };
@@ -235,11 +202,7 @@ export function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
  * An empty array means the frontmatter is valid.
  *
  * Validated constraints:
- * - `status`     — must be one of the FrontmatterStatus literals (if non-null)
- * - `confidence` — must be in [0.0, 1.0] (if non-null)
- * - `next`       — must be a non-empty string with no whitespace (if non-null)
- * - `artifacts`  — each entry must be a non-empty string
- * - `scope`      — must be one of the FrontmatterScope literals
+ * - `status` — must be one of the FrontmatterStatus literals (if non-null)
  */
 export function validateFrontmatter(
   frontmatter: AgentFrontmatter,
@@ -253,39 +216,5 @@ export function validateFrontmatter(
     });
   }
 
-  if (frontmatter.confidence !== null) {
-    if (frontmatter.confidence < 0 || frontmatter.confidence > 1) {
-      errors.push({
-        field: "confidence",
-        message: `confidence ${frontmatter.confidence} is out of range; must be between 0.0 and 1.0 inclusive`,
-      });
-    }
-  }
-
-  if (frontmatter.next !== null) {
-    if (frontmatter.next.trim() === "") {
-      errors.push({ field: "next", message: "next must be a non-empty string when present" });
-    } else if (/\s/.test(frontmatter.next)) {
-      errors.push({
-        field: "next",
-        message: `next "${frontmatter.next}" must not contain whitespace`,
-      });
-    }
-  }
-
-  for (const artifact of frontmatter.artifacts) {
-    if (artifact.trim() === "") {
-      errors.push({ field: "artifacts", message: "artifact entries must be non-empty strings" });
-      break;
-    }
-  }
-
-  if (!VALID_SCOPE.includes(frontmatter.scope)) {
-    errors.push({
-      field: "scope",
-      message: `invalid scope "${frontmatter.scope}"; must be one of: ${VALID_SCOPE.join(", ")}`,
-    });
-  }
-
   return errors;
 }

packages/workflow-util/src/frontmatter-markdown/index.ts

@@ -1,7 +1,6 @@
 export { parseFrontmatterMarkdown, validateFrontmatter } from "./frontmatter-markdown.js";
 export type {
   AgentFrontmatter,
-  FrontmatterScope,
   FrontmatterStatus,
   FrontmatterValidationError,
   ParsedFrontmatterMarkdown,

packages/workflow-util/src/frontmatter-markdown/types.ts

@@ -1,5 +1,5 @@
 /**
- * Frontmatter Markdown — agent output format (RFC #351 Phase 1).
+ * Frontmatter Markdown — agent output format.
  *
  * An agent response is a Markdown document with an optional YAML frontmatter
  * block at the top.  The frontmatter carries structured signals that the
@@ -9,17 +9,12 @@
  *
  *   ---
  *   status: done
- *   next: reviewer
- *   confidence: 0.9
- *   artifacts:
- *     - src/foo.ts
- *   scope: role
  *   ---
  *
  *   ... free-form markdown body ...
  *
- * All frontmatter fields are optional at the parse level.  `validateFrontmatter`
- * enforces the constraints documented on each field below.
+ * Only `status` is a standard frontmatter field.  All other fields are
+ * role-specific and defined by the output schema.
  */
 
 // ── Vocabulary types ─────────────────────────────────────────────────────────
@@ -34,20 +29,12 @@
  */
 export type FrontmatterStatus = "done" | "needs_input" | "in_progress" | "failed";
 
-/**
- * Scope of frontmatter signals.
- *
- * - `role`   — signals apply to the current role execution only (default)
- * - `thread` — signals are suggestions for the entire thread moderator
- */
-export type FrontmatterScope = "role" | "thread";
-
 // ── Core frontmatter schema ──────────────────────────────────────────────────
 
 /**
  * Parsed and validated frontmatter from an agent response.
  *
- * All fields use explicit `T | null` (no optional `?:` per convention).
+ * Only `status` is a standard field.  All other fields are role-specific.
  */
 export type AgentFrontmatter = {
   /**
@@ -55,32 +42,6 @@ export type AgentFrontmatter = {
    * Null when omitted — engine treats it as "done" for backward compatibility.
    */
   status: FrontmatterStatus | null;
-
-  /**
-   * Suggested next role name for the moderator.
-   * The moderator is NOT obligated to follow this — it is advisory only.
-   * Null when the agent has no preference.
-   */
-  next: string | null;
-
-  /**
-   * Agent's self-assessed confidence in its output (0.0 – 1.0 inclusive).
-   * Null when omitted.
-   */
-  confidence: number | null;
-
-  /**
-   * Relative file paths or CAS hashes the agent considers its primary outputs.
-   * Used for GC ref-tracing and human-readable summaries.
-   * Empty array when omitted (never null — an absent list is an empty list).
-   */
-  artifacts: readonly string[];
-
-  /**
-   * Scope of the frontmatter signals.
-   * Defaults to "role" when omitted.
-   */
-  scope: FrontmatterScope;
 };
 
 // ── Parse output ─────────────────────────────────────────────────────────────
@@ -103,9 +64,4 @@ export type ParsedFrontmatterMarkdown = {
 
 // ── Validation error ─────────────────────────────────────────────────────────
 
-export type FrontmatterValidationError =
-  | { field: "status"; message: string }
-  | { field: "next"; message: string }
-  | { field: "confidence"; message: string }
-  | { field: "artifacts"; message: string }
-  | { field: "scope"; message: string };
+export type FrontmatterValidationError = { field: "status"; message: string };

packages/workflow-util/src/index.ts

@@ -8,7 +8,6 @@ export { generateDeveloperReference } from "./developer-reference.js";
 export { env } from "./env.js";
 export type {
   AgentFrontmatter,
-  FrontmatterScope,
   FrontmatterStatus,
   FrontmatterValidationError,
   ParsedFrontmatterMarkdown,