@shenlee/devcrew 0.1.3 → 0.1.4

package/docs/workflow.md

@@ -42,11 +42,20 @@ The implementation-plan approval advances the run to `execution`. With the defau
 
 Apply requires Git and a clean requester worktree both when execution starts and when the reviewed patch is promoted. The requester repository remains unchanged until testing approval. A failed verification enters `awaiting_input`, rather than a promotable testing gate; it can be revised with `devcrew_answer` or deliberately reopened only through `devcrew_waive_verification` with a non-empty risk reason. If testing is rejected, `devcrew_answer` records the response and returns the run to `execution/ready` with the isolated worktree intact.
 
+`devcrew_abort` stops a nonterminal run with a required reason. It preserves the
+run state and artifacts for audit, removes its isolated worktree when possible,
+and clears the active-run pointer only when it refers to that run. An aborted
+run cannot continue. `devcrew_recover` never runs an agent: it explicitly
+clears only a confirmed stale repository lock and retries cleanup for a
+terminal run that retained an isolated worktree.
+
 The execution review is also structured: the architect must return either
 `Decision: approved` or `Decision: changes_required` in its
 `architecture-review` artifact. A `changes_required` decision rejects the
-implementation-review gate and keeps the run at `awaiting_input`; it cannot
-enter testing until the feedback is addressed and a later review approves it.
+implementation-review gate and keeps the run at `awaiting_input`. Submitting
+`devcrew_answer` then returns the run to `execution/ready` in the same
+isolated worktree, resets that review gate, and requires a new implementation
+pass followed by a later approving review before testing can start.
 
 `devcrew_start` records the created run as the active run for the repository.
 Subsequent MCP calls can omit `runId`; DevCrew resolves it from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenlee/devcrew",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Multi-host agent workflow service for Codex and Claude Code.",
   "type": "module",
   "license": "Apache-2.0",

package/packages/adapters/src/index.ts

@@ -6,6 +6,7 @@ import type {
   ExecutionPolicy,
   Host,
   Phase,
+  StructuredRoleData,
   RoleResult,
   RunState,
   WorkflowMode,
@@ -18,7 +19,7 @@ export interface BackendResolutionInput {
 
 export interface RoleRunInput {
   backend: BackendName;
-  role: RoleResult["role"];
+  role: Exclude<RoleResult["role"], "conductor">;
   phase: Phase;
   request: string;
   mode: WorkflowMode;
@@ -101,6 +102,156 @@ export function extractArchitectureReviewDecision(markdown: string): "approved"
   return match?.[1] as "approved" | "changes_required" | undefined;
 }
 
+const STRUCTURED_RESULT_MARKER = "<!-- devcrew-role-result -->";
+const STRUCTURED_RESULT_BLOCK = /<!--\s*devcrew-role-result\s*-->\s*```json\s*\r?\n([\s\S]*?)\r?\n```/g;
+
+function structuredOutputError(role: RoleResult["role"], reason: string): RoleOutputValidationError {
+  return new RoleOutputValidationError(role, [`marked structured role result: ${reason}`]);
+}
+
+function asRecord(value: unknown, role: RoleResult["role"], field: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw structuredOutputError(role, `${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asNonEmptyString(value: unknown, role: RoleResult["role"], field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw structuredOutputError(role, `${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function asStringArray(value: unknown, role: RoleResult["role"], field: string): string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+    throw structuredOutputError(role, `${field} must be an array of non-empty strings`);
+  }
+  return value.map((entry) => (entry as string).trim());
+}
+
+function asEvidence(value: unknown, role: RoleResult["role"]): StructuredRoleData["evidence"] {
+  if (!Array.isArray(value)) {
+    throw structuredOutputError(role, "evidence must be an array");
+  }
+  return value.map((entry, index) => {
+    const evidence = asRecord(entry, role, `evidence[${index}]`);
+    const command = asNonEmptyString(evidence.command, role, `evidence[${index}].command`);
+    if (!Number.isInteger(evidence.exitCode)) {
+      throw structuredOutputError(role, `evidence[${index}].exitCode must be an integer`);
+    }
+    if (evidence.output !== undefined && typeof evidence.output !== "string") {
+      throw structuredOutputError(role, `evidence[${index}].output must be a string`);
+    }
+    return { command, exitCode: evidence.exitCode as number, output: evidence.output as string | undefined };
+  });
+}
+
+function asQuestions(value: unknown, role: RoleResult["role"]): NonNullable<StructuredRoleData["questions"]> {
+  if (!Array.isArray(value)) {
+    throw structuredOutputError(role, "questions must be an array");
+  }
+  const ids = new Set<string>();
+  return value.map((entry, index) => {
+    const question = asRecord(entry, role, `questions[${index}]`);
+    const id = asNonEmptyString(question.id, role, `questions[${index}].id`);
+    if (ids.has(id)) {
+      throw structuredOutputError(role, `questions[${index}].id must be unique`);
+    }
+    ids.add(id);
+    const prompt = asNonEmptyString(question.prompt, role, `questions[${index}].prompt`);
+    if (question.context !== undefined && typeof question.context !== "string") {
+      throw structuredOutputError(role, `questions[${index}].context must be a string`);
+    }
+    return { id, prompt, context: question.context as string | undefined };
+  });
+}
+
+function parseStructuredRoleData(
+  role: Exclude<RoleResult["role"], "conductor">,
+  phase: Phase,
+  raw: unknown,
+): StructuredRoleData {
+  const value = asRecord(raw, role, "result");
+  if (value.schemaVersion !== 1) {
+    throw structuredOutputError(role, "schemaVersion must be 1");
+  }
+  if (value.role !== role) {
+    throw structuredOutputError(role, `role must be ${role}`);
+  }
+  const data: StructuredRoleData = {
+    schemaVersion: 1,
+    role,
+    summary: asNonEmptyString(value.summary, role, "summary"),
+    risks: asStringArray(value.risks, role, "risks"),
+    evidence: asEvidence(value.evidence, role),
+  };
+  if (role === "pm") {
+    data.questions = asQuestions(value.questions, role);
+  } else if (role === "architect") {
+    data.decisions = asStringArray(value.decisions, role, "decisions");
+    if (phase === "review") {
+      if (value.reviewDecision !== "approved" && value.reviewDecision !== "changes_required") {
+        throw structuredOutputError(role, "reviewDecision must be approved or changes_required");
+      }
+      data.reviewDecision = value.reviewDecision;
+    }
+  } else if (role === "implementer") {
+    data.changedFiles = asStringArray(value.changedFiles, role, "changedFiles");
+  } else {
+    if (!Array.isArray(value.testCases)) {
+      throw structuredOutputError(role, "testCases must be an array");
+    }
+    data.testCases = value.testCases.map((entry, index) => {
+      const testCase = asRecord(entry, role, `testCases[${index}]`);
+      const type = testCase.type;
+      if (type !== "happy" && type !== "edge" && type !== "failure" && type !== "regression") {
+        throw structuredOutputError(role, `testCases[${index}].type is invalid`);
+      }
+      return {
+        id: asNonEmptyString(testCase.id, role, `testCases[${index}].id`),
+        scenario: asNonEmptyString(testCase.scenario, role, `testCases[${index}].scenario`),
+        type,
+        expected: asNonEmptyString(testCase.expected, role, `testCases[${index}].expected`),
+      };
+    });
+  }
+  return data;
+}
+
+export function parseRoleResultOutput(
+  role: Exclude<RoleResult["role"], "conductor">,
+  phase: Phase,
+  output: string,
+): Pick<RoleResult, "format" | "markdown" | "structured" | "questions" | "reviewDecision"> {
+  if (!output.includes(STRUCTURED_RESULT_MARKER)) {
+    return {
+      format: "legacy",
+      markdown: output,
+      questions: role === "pm" ? extractOpenQuestions(output) : undefined,
+      reviewDecision: phase === "review" ? extractArchitectureReviewDecision(output) : undefined,
+    };
+  }
+  const blocks = [...output.matchAll(STRUCTURED_RESULT_BLOCK)];
+  if (blocks.length !== 1) {
+    throw structuredOutputError(role, blocks.length === 0 ? "must use a JSON fenced block" : "must appear exactly once");
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(blocks[0]?.[1] ?? "");
+  } catch {
+    throw structuredOutputError(role, "contains invalid JSON");
+  }
+  const structured = parseStructuredRoleData(role, phase, raw);
+  return {
+    format: "structured",
+    markdown: output.slice(0, blocks[0]?.index).concat(output.slice((blocks[0]?.index ?? 0) + (blocks[0]?.[0].length ?? 0))).trim(),
+    structured,
+    questions: structured.questions?.map((question) => question.prompt),
+    reviewDecision: structured.reviewDecision,
+  };
+}
+
 export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">): string {
   const executionMode = input.executionMode ?? "plan";
   const answers = input.answers ?? [];
@@ -148,6 +299,13 @@ export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">):
     "Keep scope aligned with the approved gates and the selected DevCrew execution policy.",
     permissionInstruction,
     "",
+    "Return this protocol block first:",
+    STRUCTURED_RESULT_MARKER,
+    "```json",
+    `{\"schemaVersion\":1,\"role\":\"${input.role}\",\"summary\":\"...\",\"risks\":[],\"evidence\":[]}`,
+    "```",
+    "Then return the required Markdown H2 sections. Do not include a second marked result block.",
+    "",
     "Required Sections:",
     ...roleGuidance(input.role),
   );
@@ -410,6 +568,7 @@ function fallbackResult(
     summary,
     markdown: `# ${title}\n\n${summary}\n`,
     usedFallback: true,
+    format: "legacy",
   };
 }
 
@@ -443,18 +602,21 @@ export async function runRole(input: RoleRunInput, deps: RunRoleDeps = {}): Prom
       input.backend === "codex"
         ? await runWithCodex(input, prompt, loadModule)
         : await runWithClaude(input, prompt, loadModule);
-    assertRoleSections(input.role, markdown);
-    const reviewDecision = input.phase === "review" ? extractArchitectureReviewDecision(markdown) : undefined;
+    const parsed = parseRoleResultOutput(input.role, input.phase, markdown);
+    assertRoleSections(input.role, parsed.markdown);
+    const reviewDecision = parsed.reviewDecision;
     if (input.phase === "review" && !reviewDecision) {
       throw new RoleOutputValidationError(input.role, ["Review Decision"]);
     }
     return {
       role: input.role,
       backend: input.backend,
-      summary: `${input.role} produced ${title} using the ${input.backend} SDK.`,
-      markdown,
+      summary: parsed.structured?.summary ?? `${input.role} produced ${title} using the ${input.backend} SDK.`,
+      markdown: parsed.markdown,
       usedFallback: false,
-      questions: input.role === "pm" ? extractOpenQuestions(markdown) : undefined,
+      format: parsed.format,
+      structured: parsed.structured,
+      questions: parsed.questions,
       reviewDecision,
     };
   } catch (error) {

package/packages/core/src/active-run.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, unlink, writeFile } from "node:fs/promises";
 
 import { activeRunPath, ensureProjectDirectories } from "./paths.js";
 
@@ -29,3 +29,15 @@ export async function getActiveRunId(cwd: string): Promise<string> {
   }
   throw new Error("No active DevCrew run. Pass runId or start a workflow first.");
 }
+
+export async function clearActiveRunIfMatches(cwd: string, runId: string): Promise<boolean> {
+  try {
+    if ((await getActiveRunId(cwd)) !== runId) {
+      return false;
+    }
+    await unlink(activeRunPath(cwd));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/core/src/config.ts

@@ -1,7 +1,8 @@
 import { access, readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 
 import { configPath, ensureProjectDirectories } from "./paths.js";
-import type { DevCrewConfig } from "./types.js";
+import { BACKENDS, EXECUTION_MODES, GATES, type BackendName, type DevCrewConfig, type ExecutionMode, type GateName } from "./types.js";
 
 export const DEFAULT_CONFIG: DevCrewConfig = {
   version: 1,
@@ -25,6 +26,99 @@ async function exists(path: string): Promise<boolean> {
   }
 }
 
+type JsonRecord = Record<string, unknown>;
+
+function asRecord(value: unknown, field: string): JsonRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid .devcrew/config.json: ${field} must be an object`);
+  }
+  return value as JsonRecord;
+}
+
+function assertKnownKeys(value: JsonRecord, field: string, allowed: readonly string[]): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`Invalid .devcrew/config.json: ${field} has unknown key ${key}`);
+    }
+  }
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid .devcrew/config.json: ${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function parseCommandList(value: unknown, field: string): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`Invalid .devcrew/config.json: ${field} must be an array`);
+  }
+  return value.map((entry, index) => requiredString(entry, `${field}[${index}]`));
+}
+
+function parseGates(value: unknown): GateName[] {
+  if (!Array.isArray(value)) {
+    throw new Error("Invalid .devcrew/config.json: workflow.gates must be an array");
+  }
+  const gates: GateName[] = [];
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry !== "string" || !GATES.includes(entry as GateName)) {
+      throw new Error(`Invalid .devcrew/config.json: workflow.gates[${index}] must be a known gate, received ${String(entry)}`);
+    }
+    if (gates.includes(entry as GateName)) {
+      throw new Error(`Invalid .devcrew/config.json: workflow.gates contains duplicate ${entry}`);
+    }
+    gates.push(entry as GateName);
+  }
+  return gates;
+}
+
+function parseArtifactDirectory(cwd: string, value: unknown): string {
+  const artifactDirectory = requiredString(value, "workflow.artifactDirectory");
+  if (isAbsolute(artifactDirectory)) {
+    throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must be relative to the repository");
+  }
+  const projectRoot = resolve(cwd);
+  const target = resolve(projectRoot, artifactDirectory);
+  const fromProject = relative(projectRoot, target);
+  if (fromProject === ".." || fromProject.startsWith(`..${sep}`) || isAbsolute(fromProject)) {
+    throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must resolve inside the repository");
+  }
+  return artifactDirectory;
+}
+
+function parseConfig(cwd: string, value: unknown): DevCrewConfig {
+  const parsed = asRecord(value, "root");
+  assertKnownKeys(parsed, "root", ["version", "defaultBackend", "executionMode", "verifyCommands", "lintCommands", "coverageCommands", "workflow"]);
+  if (parsed.version !== 1) {
+    throw new Error("Unsupported .devcrew/config.json version");
+  }
+  if (typeof parsed.defaultBackend !== "string" || (parsed.defaultBackend !== "host-preferred" && !BACKENDS.includes(parsed.defaultBackend as BackendName))) {
+    throw new Error("Invalid .devcrew/config.json: defaultBackend must be host-preferred, codex, claude, or local");
+  }
+  if (typeof parsed.executionMode !== "string" || !EXECUTION_MODES.includes(parsed.executionMode as ExecutionMode)) {
+    throw new Error("Invalid .devcrew/config.json: executionMode must be plan or apply");
+  }
+  const workflow = asRecord(parsed.workflow, "workflow");
+  assertKnownKeys(workflow, "workflow", ["gates", "artifactDirectory"]);
+  return {
+    version: 1,
+    defaultBackend: parsed.defaultBackend as DevCrewConfig["defaultBackend"],
+    executionMode: parsed.executionMode as ExecutionMode,
+    verifyCommands: parseCommandList(parsed.verifyCommands, "verifyCommands"),
+    lintCommands: parseCommandList(parsed.lintCommands, "lintCommands"),
+    coverageCommands: parseCommandList(parsed.coverageCommands, "coverageCommands"),
+    workflow: {
+      gates: parseGates(workflow.gates),
+      artifactDirectory: parseArtifactDirectory(cwd, workflow.artifactDirectory),
+    },
+  };
+}
+
 export async function ensureConfig(cwd: string): Promise<DevCrewConfig> {
   await ensureProjectDirectories(cwd);
   const path = configPath(cwd);
@@ -37,20 +131,5 @@ export async function ensureConfig(cwd: string): Promise<DevCrewConfig> {
 
 export async function readConfig(cwd: string): Promise<DevCrewConfig> {
   const raw = await readFile(configPath(cwd), "utf8");
-  const parsed = JSON.parse(raw) as DevCrewConfig;
-  if (parsed.version !== 1) {
-    throw new Error("Unsupported .devcrew/config.json version");
-  }
-  return {
-    ...DEFAULT_CONFIG,
-    ...parsed,
-    executionMode: parsed.executionMode ?? "plan",
-    verifyCommands: Array.isArray(parsed.verifyCommands) ? parsed.verifyCommands : [],
-    lintCommands: Array.isArray(parsed.lintCommands) ? parsed.lintCommands : [],
-    coverageCommands: Array.isArray(parsed.coverageCommands) ? parsed.coverageCommands : [],
-    workflow: {
-      ...DEFAULT_CONFIG.workflow,
-      ...parsed.workflow,
-    },
-  };
+  return parseConfig(cwd, JSON.parse(raw) as unknown);
 }

package/packages/core/src/index.ts

@@ -1,6 +1,7 @@
 export * from "./active-run.js";
 export * from "./artifacts.js";
 export * from "./config.js";
+export * from "./lock.js";
 export * from "./paths.js";
 export * from "./standards.js";
 export * from "./store.js";

package/packages/core/src/lock.ts

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+
+import { devcrewDir, repositoryLockPath } from "./paths.js";
+
+interface RepositoryLockMetadata {
+  ownerId: string;
+  pid: number;
+  createdAt: string;
+}
+
+function metadataPath(cwd: string): string {
+  return `${repositoryLockPath(cwd)}/lock.json`;
+}
+
+async function readMetadata(cwd: string): Promise<RepositoryLockMetadata | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(metadataPath(cwd), "utf8")) as Partial<RepositoryLockMetadata>;
+    const pid = parsed.pid;
+    if (
+      typeof parsed.ownerId !== "string" ||
+      typeof pid !== "number" ||
+      !Number.isInteger(pid) ||
+      typeof parsed.createdAt !== "string"
+    ) {
+      return undefined;
+    }
+    return {
+      ownerId: parsed.ownerId,
+      pid,
+      createdAt: parsed.createdAt,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function processIsLive(pid: number): boolean {
+  if (pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+async function releaseRepositoryLock(cwd: string, ownerId: string): Promise<void> {
+  const metadata = await readMetadata(cwd);
+  if (metadata?.ownerId === ownerId) {
+    await rm(repositoryLockPath(cwd), { recursive: true, force: true });
+  }
+}
+
+export async function withRepositoryLock<T>(cwd: string, action: () => Promise<T>): Promise<T> {
+  await mkdir(devcrewDir(cwd), { recursive: true });
+  const ownerId = randomUUID();
+  try {
+    await mkdir(repositoryLockPath(cwd));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+    const metadata = await readMetadata(cwd);
+    if (metadata && processIsLive(metadata.pid)) {
+      throw new Error("A DevCrew operation is already in progress for this repository");
+    }
+    throw new Error("A stale DevCrew repository lock exists; use devcrew_recover for explicit recovery");
+  }
+
+  await writeFile(
+    metadataPath(cwd),
+    `${JSON.stringify({ ownerId, pid: process.pid, createdAt: new Date().toISOString() } satisfies RepositoryLockMetadata, null, 2)}\n`,
+    "utf8",
+  );
+  try {
+    return await action();
+  } finally {
+    await releaseRepositoryLock(cwd, ownerId);
+  }
+}
+
+export async function recoverRepositoryLock(cwd: string): Promise<boolean> {
+  const lockPath = repositoryLockPath(cwd);
+  const metadata = await readMetadata(cwd);
+  if (!metadata) {
+    try {
+      await rm(lockPath, { recursive: true, force: false });
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return false;
+      }
+      throw error;
+    }
+  }
+  if (processIsLive(metadata.pid)) {
+    throw new Error("Cannot recover a DevCrew repository lock held by a live process");
+  }
+  await rm(lockPath, { recursive: true, force: true });
+  return true;
+}

package/packages/core/src/paths.ts

@@ -31,6 +31,10 @@ export function activeRunPath(cwd: string): string {
   return join(devcrewDir(cwd), "active-run.json");
 }
 
+export function repositoryLockPath(cwd: string): string {
+  return join(devcrewDir(cwd), "lock");
+}
+
 export function standardsPath(cwd: string): string {
   return join(devcrewDir(cwd), "standards.md");
 }

package/packages/core/src/store.ts

@@ -2,7 +2,7 @@ import { readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import { ensureRunDirectories, statePath } from "./paths.js";
-import { GATES, type GateName, type RunState } from "./types.js";
+import { GATES, type GateName, type RoleResult, type RunState } from "./types.js";
 
 function enabledGatesFromState(value: unknown): GateName[] {
   const configured = Array.isArray(value)
@@ -11,6 +11,16 @@ function enabledGatesFromState(value: unknown): GateName[] {
   return [...new Set<GateName>([...configured, "implementation-review", "testing"])];
 }
 
+function roleResultsFromState(value: unknown): RoleResult[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((role): role is RoleResult => typeof role === "object" && role !== null).map((role) => ({
+    ...role,
+    format: role.format === "structured" ? "structured" : "legacy",
+  }));
+}
+
 export async function saveState(state: RunState): Promise<RunState> {
   state.updatedAt = new Date().toISOString();
   await ensureRunDirectories(state.cwd, state.runId);
@@ -31,6 +41,7 @@ export async function loadState(cwd: string, runId: string): Promise<RunState> {
     ...parsed,
     executionMode: parsed.executionMode ?? "plan",
     executionPolicy: parsed.executionPolicy ?? "interactive-host",
+    roles: roleResultsFromState(parsed.roles),
     enabledGates: enabledGatesFromState(parsed.enabledGates),
     artifactDirectory: typeof parsed.artifactDirectory === "string" && parsed.artifactDirectory.trim().length > 0
       ? parsed.artifactDirectory

package/packages/core/src/types.ts

@@ -35,13 +35,47 @@ export type Phase = (typeof PHASES)[number];
 export type GateName = (typeof GATES)[number];
 export type ArtifactName = (typeof ARTIFACTS)[number];
 export type GateStatus = "not_started" | "pending" | "approved" | "rejected";
-export type RunStatus = "ready" | "awaiting_input" | "awaiting_approval" | "awaiting_execution" | "complete";
+export type RunStatus = "ready" | "awaiting_input" | "awaiting_approval" | "awaiting_execution" | "complete" | "aborted";
 
 export interface RoleSection {
   heading: string;
   description: string;
 }
 
+export type RoleResultFormat = "legacy" | "structured";
+
+export interface CommandEvidence {
+  command: string;
+  exitCode: number;
+  output?: string;
+}
+
+export interface RoleQuestion {
+  id: string;
+  prompt: string;
+  context?: string;
+}
+
+export interface TestCaseEvidence {
+  id: string;
+  scenario: string;
+  type: "happy" | "edge" | "failure" | "regression";
+  expected: string;
+}
+
+export interface StructuredRoleData {
+  schemaVersion: 1;
+  role: "pm" | "architect" | "implementer" | "tester";
+  summary: string;
+  risks: string[];
+  evidence: CommandEvidence[];
+  questions?: RoleQuestion[];
+  decisions?: string[];
+  reviewDecision?: ArchitectureReviewDecision;
+  changedFiles?: string[];
+  testCases?: TestCaseEvidence[];
+}
+
 export const ROLE_SECTIONS: Record<Exclude<RoleResult["role"], "conductor">, RoleSection[]> = {
   pm: [
     { heading: "Functional Scope", description: "explicit In Scope and Out of Scope lists" },
@@ -94,6 +128,8 @@ export interface RoleResult {
   summary: string;
   markdown: string;
   usedFallback: boolean;
+  format: RoleResultFormat;
+  structured?: StructuredRoleData;
   questions?: string[];
   reviewDecision?: ArchitectureReviewDecision;
 }
@@ -126,6 +162,11 @@ export interface VerificationWaiver {
   createdAt: string;
 }
 
+export interface RunAbort {
+  reason: string;
+  abortedAt: string;
+}
+
 // Reused for both verification and lint results — the command shape is identical.
 export interface VerificationResult {
   command: string;
@@ -179,6 +220,7 @@ export interface RunState {
   verification: VerificationResult[];
   verificationStatus: VerificationStatus;
   verificationWaiver?: VerificationWaiver;
+  abort?: RunAbort;
   // VerificationResult is reused for lint output — same shape, different semantics.
   lintResults: VerificationResult[];
 }
@@ -216,6 +258,10 @@ export interface WaiveVerificationInput extends RunRef {
   reason: string;
 }
 
+export interface AbortWorkflowInput extends RunRef {
+  reason: string;
+}
+
 export interface CompleteExecutionInput extends RunRef {
   summary: string;
   verification?: VerificationResult[];

package/packages/core/src/version.ts

@@ -1,2 +1,2 @@
-export const DEVCREW_VERSION = "0.1.3";
+export const DEVCREW_VERSION = "0.1.4";
 export const DEVCREW_NPM_PACKAGE = "@shenlee/devcrew";