@shenlee/devcrew 0.1.3 → 0.1.5

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.5";
 export const DEVCREW_NPM_PACKAGE = "@shenlee/devcrew";

package/packages/core/src/workflow.ts

@@ -22,6 +22,7 @@ import {
 } from "./validation.js";
 import type {
   AnswerWorkflowInput,
+  AbortWorkflowInput,
   ApproveWorkflowInput,
   ArtifactName,
   ArtifactReadResult,
@@ -187,7 +188,8 @@ export async function continueWorkflow(input: RunRef): Promise<RunState> {
     state.status === "awaiting_approval" ||
     state.status === "awaiting_input" ||
     state.status === "awaiting_execution" ||
-    state.status === "complete"
+    state.status === "complete" ||
+    state.status === "aborted"
   ) {
     return state;
   }
@@ -220,6 +222,23 @@ export async function continueWorkflow(input: RunRef): Promise<RunState> {
   return saveState(state);
 }
 
+export async function abortWorkflow(input: AbortWorkflowInput): Promise<RunState> {
+  const state = await getWorkflowStatus(input);
+  if (state.status === "aborted") {
+    return state;
+  }
+  if (state.status === "complete") {
+    throw new Error("Completed DevCrew runs cannot be aborted");
+  }
+  state.abort = {
+    reason: parseWaiverReason(input.reason),
+    abortedAt: now(),
+  };
+  delete state.executionInstruction;
+  state.status = "aborted";
+  return saveState(state);
+}
+
 export async function validateWorkflowApproval(input: ApproveWorkflowInput): Promise<RunState> {
   const state = await getWorkflowStatus(input);
   const gate = parseGate(input.gate);
@@ -301,9 +320,9 @@ export async function waiveVerificationWorkflow(input: WaiveVerificationInput):
     state.phase !== "testing" ||
     state.status !== "awaiting_input" ||
     state.gates.testing !== "rejected" ||
-    state.verificationStatus !== "failed"
+    (state.verificationStatus !== "failed" && state.verificationStatus !== "not_run")
   ) {
-    throw new Error("A verification waiver is only available after failed apply-mode testing");
+    throw new Error("A verification waiver is only available after failed or missing apply-mode verification");
   }
   state.verificationWaiver = {
     reason: parseWaiverReason(input.reason),

package/packages/orchestrator/src/index.ts

@@ -5,6 +5,7 @@ import { dirname } from "node:path";
 import { runRole } from "../../adapters/src/index.js";
 import type { RoleRunInput } from "../../adapters/src/index.js";
 import {
+  abortWorkflow,
   answerWorkflow,
   approveWorkflow,
   artifactForPhase,
@@ -24,6 +25,7 @@ import {
   validateWorkflowApproval,
   waiveVerificationWorkflow,
   type AnswerWorkflowInput,
+  type AbortWorkflowInput,
   type ApproveWorkflowInput,
   type ArtifactName,
   type CompleteExecutionInput,
@@ -49,9 +51,10 @@ import {
 const COMMAND_TIMEOUT_MS = 300_000;
 
 type RoleRunner = (input: RoleRunInput) => Promise<RoleResult>;
+type ExecutingRole = Exclude<RoleResult["role"], "conductor">;
 
-function roleForPhase(phase: Phase): RoleResult["role"] | undefined {
-  const roles: Partial<Record<Phase, RoleResult["role"]>> = {
+function roleForPhase(phase: Phase): ExecutingRole | undefined {
+  const roles: Partial<Record<Phase, ExecutingRole>> = {
     requirements: "pm",
     architecture: "architect",
     implementation: "implementer",
@@ -70,6 +73,7 @@ function conductorDecision(state: RunState, role: RoleResult["role"], gate: stri
     summary,
     markdown: `# Conductor Decision\n\n${summary}\n`,
     usedFallback: false,
+    format: "legacy",
   };
 }
 
@@ -239,12 +243,15 @@ function verificationStatusFor(results: VerificationResult[]): VerificationStatu
 }
 
 function setTestingGateFromVerification(state: RunState): void {
-  if (state.verificationStatus === "failed") {
+  if (state.verificationStatus !== "passed") {
     state.gates.testing = "rejected";
     state.status = "awaiting_input";
     state.feedback.push({
       gate: "testing",
-      message: "Automated verification failed. Inspect the test report, revise the implementation, or record an explicit verification waiver with its reason.",
+      message:
+        state.verificationStatus === "failed"
+          ? "Automated verification failed. Inspect the test report, revise the implementation, or record an explicit verification waiver with its reason."
+          : "No verification evidence was recorded. Configure or run validation, revise the implementation, or record an explicit verification waiver with its reason.",
       createdAt: now(),
     });
     return;
@@ -269,6 +276,7 @@ function hostCompletionResult(state: RunState, summary: string): RoleResult {
     summary: `${role} completed through the native ${state.host} host: ${summary}`,
     markdown: `${renderArtifact(artifact, state).trim()}\n\n## Native Host Summary\n\n${summary}\n`,
     usedFallback: false,
+    format: "legacy",
   };
 }
 
@@ -309,16 +317,57 @@ function parseCompletionVerification(value: unknown): VerificationResult[] {
   });
 }
 
-function appendExecutionSections(artifact: ArtifactName, markdown: string, state: RunState): string {
+function structuredRoleResultBlock(result: RoleResult): string {
+  if (result.format !== "structured" || !result.structured) {
+    return "";
+  }
+  const data = result.structured;
+  const sections = [
+    "## Structured Role Result",
+    "",
+    `Schema Version: ${data.schemaVersion}`,
+    `Summary: ${data.summary}`,
+  ];
+  if (data.questions?.length) {
+    sections.push("", "### Questions", "", ...data.questions.map((question) => `- ${question.id}: ${question.prompt}`));
+  }
+  if (data.decisions?.length) {
+    sections.push("", "### Decisions", "", ...data.decisions.map((decision) => `- ${decision}`));
+  }
+  if (data.changedFiles?.length) {
+    sections.push("", "### Changed Files", "", ...data.changedFiles.map((file) => `- ${file}`));
+  }
+  if (data.evidence.length) {
+    sections.push("", "### Command Evidence", "");
+    for (const evidence of data.evidence) {
+      sections.push(`- \`${evidence.command}\` — exit code ${evidence.exitCode}`);
+      if (evidence.output) {
+        sections.push("", "```text", evidence.output, "```");
+      }
+    }
+  }
+  if (data.testCases?.length) {
+    sections.push("", "### Test Cases", "", "| ID | Scenario | Type | Expected |", "| --- | --- | --- | --- |");
+    sections.push(...data.testCases.map((testCase) => `| ${testCase.id} | ${testCase.scenario} | ${testCase.type} | ${testCase.expected} |`));
+  }
+  if (data.risks.length) {
+    sections.push("", "### Risks", "", ...data.risks.map((risk) => `- ${risk}`));
+  }
+  return `\n\n${sections.join("\n")}`;
+}
+
+function appendExecutionSections(artifact: ArtifactName, markdown: string, state: RunState, result?: RoleResult): string {
+  let content = markdown.trim();
+  if (result?.format === "structured" && !content.includes("## Structured Role Result")) {
+    content += structuredRoleResultBlock(result);
+  }
   if (artifact === "architecture-review" && state.architectureReview) {
-    let content = markdown.trim();
     if (!content.includes("## Review Decision")) {
       content += `\n\n## Review Decision\n\nDecision: ${state.architectureReview.decision}\n\nSummary: ${state.architectureReview.summary}`;
     }
     return `${content}\n`;
   }
   if (artifact === "test-report") {
-    let content = markdown.trim();
     if (!content.includes("## Acceptance Evidence")) {
       content += `\n\n## Acceptance Evidence\n\n${verificationBlock(state.verification)}`;
     }
@@ -330,7 +379,7 @@ function appendExecutionSections(artifact: ArtifactName, markdown: string, state
     }
     return `${content}\n`;
   }
-  return markdown;
+  return `${content}\n`;
 }
 
 async function writeImplementationReview(state: RunState): Promise<void> {
@@ -451,11 +500,12 @@ async function runCurrentPhaseRole(state: RunState, runner: RoleRunner = runRole
   }
 
   if (state.phase === "review") {
-    if (!result.reviewDecision) {
+    const reviewDecision = result.format === "structured" ? result.structured?.reviewDecision : result.reviewDecision;
+    if (!reviewDecision) {
       throw new Error("DevCrew architecture review must return a structured review decision");
     }
     state.architectureReview = {
-      decision: result.reviewDecision,
+      decision: reviewDecision,
       summary: result.summary,
       reviewedAt: now(),
     };
@@ -464,12 +514,15 @@ async function runCurrentPhaseRole(state: RunState, runner: RoleRunner = runRole
   // When the backend cannot run a real SDK we keep a single deterministic
   // artifact source by rendering the rich phase template from the core layer.
   const baseMarkdown = result.usedFallback ? `${fallbackNotice(result)}${renderArtifact(artifact, state)}` : result.markdown;
-  const markdown = appendExecutionSections(artifact, baseMarkdown, state);
+  const markdown = appendExecutionSections(artifact, baseMarkdown, state, result);
   state.roles.push({ ...result, markdown });
   state.artifacts[artifact] = await writeMarkdownArtifact(state, artifact, markdown);
   state.executionInstruction = undefined;
-  if (state.phase === "requirements" && result.questions && result.questions.length > 0) {
-    state.pendingQuestions = result.questions;
+  const questions = result.format === "structured"
+    ? result.structured?.questions?.map((question) => question.prompt) ?? []
+    : result.questions ?? [];
+  if (state.phase === "requirements" && questions.length > 0) {
+    state.pendingQuestions = questions;
     state.gates.requirements = "not_started";
     state.status = "awaiting_input";
     return saveState(state);
@@ -512,7 +565,8 @@ export async function continueOrchestratedWorkflow(input: RunRef, runner: RoleRu
     state.status === "awaiting_approval" ||
     state.status === "awaiting_input" ||
     state.status === "awaiting_execution" ||
-    state.status === "complete"
+    state.status === "complete" ||
+    state.status === "aborted"
   ) {
     return state;
   }
@@ -552,8 +606,8 @@ export async function approveOrchestratedWorkflow(input: ApproveWorkflowInput):
     return cleanupAfterApproval(before);
   }
   if (promotingTesting) {
-    if (before.verificationStatus === "failed" && !before.verificationWaiver) {
-      throw new Error("Failed verification cannot be promoted without an explicit verification waiver");
+    if (before.verificationStatus !== "passed" && !before.verificationWaiver) {
+      throw new Error("Verification must pass before promotion or have an explicit verification waiver");
     }
     await promoteExecutionChanges(before);
     let approved: RunState;
@@ -627,7 +681,7 @@ export async function completeOrchestratedExecution(input: CompleteExecutionInpu
   await writeImplementationReview(state);
   const result = hostCompletionResult(state, summary);
   const artifact = artifactForPhase(state.phase);
-  const markdown = appendExecutionSections(artifact, result.markdown, state);
+  const markdown = appendExecutionSections(artifact, result.markdown, state, result);
   state.roles.push({ ...result, markdown });
   state.artifacts[artifact] = await writeMarkdownArtifact(state, artifact, markdown);
   state.executionInstruction = undefined;
@@ -639,6 +693,33 @@ export async function rejectOrchestratedWorkflow(input: RejectWorkflowInput): Pr
   return rejectWorkflow(input);
 }
 
+export async function abortOrchestratedWorkflow(input: AbortWorkflowInput): Promise<RunState> {
+  const state = await abortWorkflow(input);
+  if (!state.executionWorkspace) {
+    return state;
+  }
+  try {
+    await cleanupExecutionWorkspace(state);
+  } catch {
+    return state;
+  }
+  state.executionWorkspace = undefined;
+  return saveState(state);
+}
+
+export async function recoverOrchestratedWorkflow(input: RunRef): Promise<RunState> {
+  const state = await getWorkflowStatus(input);
+  if (state.status !== "aborted" && state.status !== "complete") {
+    throw new Error("Only terminal DevCrew runs can be recovered");
+  }
+  if (!state.executionWorkspace) {
+    return state;
+  }
+  await cleanupExecutionWorkspace(state);
+  state.executionWorkspace = undefined;
+  return saveState(state);
+}
+
 export async function answerOrchestratedWorkflow(input: AnswerWorkflowInput, runner: RoleRunner = runRole): Promise<RunState> {
   const before = await getWorkflowStatus(input);
   const state = await answerWorkflow(input, { skipArtifactWrite: true });
@@ -652,6 +733,17 @@ export async function answerOrchestratedWorkflow(input: AnswerWorkflowInput, run
     state.gates.testing = "not_started";
     return saveState(state);
   }
+  if (
+    before.executionMode === "apply" &&
+    before.phase === "review" &&
+    before.gates["implementation-review"] === "rejected" &&
+    before.architectureReview?.decision === "changes_required"
+  ) {
+    state.phase = "execution";
+    state.status = "ready";
+    state.gates["implementation-review"] = "not_started";
+    return saveState(state);
+  }
 
   const role = roleForPhase(state.phase);
   if (!role) {

package/packages/service/src/tools.ts

@@ -1,17 +1,22 @@
 import {
+  clearActiveRunIfMatches,
   getArtifact,
   getActiveRunId,
   getWorkflowStatus,
+  recoverRepositoryLock,
   setActiveRun,
+  withRepositoryLock,
   type Host,
   type RunState,
 } from "../../core/src/index.js";
 import {
+  abortOrchestratedWorkflow,
   answerOrchestratedWorkflow,
   approveOrchestratedWorkflow,
   completeOrchestratedExecution,
   continueOrchestratedWorkflow,
   rejectOrchestratedWorkflow,
+  recoverOrchestratedWorkflow,
   startOrchestratedWorkflow,
   waiveOrchestratedVerification,
 } from "../../orchestrator/src/index.js";
@@ -58,8 +63,24 @@ function withInferredHost(args: Record<string, unknown>): Record<string, unknown
   return { ...args, host: inferHost() };
 }
 
+async function withMutationLock<T>(args: Record<string, unknown>, action: () => Promise<T>): Promise<T> {
+  if (typeof args.cwd !== "string" || !args.cwd.trim()) {
+    return action();
+  }
+  return withRepositoryLock(args.cwd, action);
+}
+
 export function listDevCrewTools(): DevCrewTool[] {
   return [
+    {
+      name: "devcrew_abort",
+      description: "Abort a nonterminal run, preserve its audit evidence, and clean its isolated worktree when possible.",
+      inputSchema: {
+        type: "object",
+        required: ["cwd", "reason"],
+        properties: { cwd: cwdProperty, runId: runIdProperty, reason: { type: "string" } },
+      },
+    },
     {
       name: "devcrew_start",
       description: "Create a new gated DevCrew workflow run.",
@@ -85,6 +106,15 @@ export function listDevCrewTools(): DevCrewTool[] {
         },
       },
     },
+    {
+      name: "devcrew_recover",
+      description: "Explicitly clear a confirmed stale lock and retry cleanup for a terminal run without executing an agent.",
+      inputSchema: {
+        type: "object",
+        required: ["cwd"],
+        properties: { cwd: cwdProperty, runId: runIdProperty },
+      },
+    },
     {
       name: "devcrew_status",
       description: "Read the status of a DevCrew workflow run.",
@@ -190,7 +220,8 @@ function summarizeState(state: RunState): string {
   const role = state.roles.at(-1);
   const roleFallback =
     role?.usedFallback === true ? (role.backend === "local" ? "local" : "sdk") : role ? "none" : "none";
-  return `Run ${state.runId}: phase=${state.phase}, status=${state.status}, execution_mode=${state.executionMode}, pending_gate=${pendingGate}, role_fallback=${roleFallback}`;
+  const roleFormat = role?.format ?? "none";
+  return `Run ${state.runId}: phase=${state.phase}, status=${state.status}, execution_mode=${state.executionMode}, pending_gate=${pendingGate}, role_fallback=${roleFallback}, role_format=${roleFormat}`;
 }
 
 function success(text: string, structuredContent?: Record<string, unknown>): ToolResult {
@@ -213,37 +244,76 @@ function failure(error: unknown): ToolResult {
 export async function callDevCrewTool(name: string, args: Record<string, unknown>): Promise<ToolResult> {
   try {
     if (name === "devcrew_start") {
-      const state = await startOrchestratedWorkflow(withInferredHost(args) as never);
-      await setActiveRun(state.cwd, state.runId);
-      return success(`${summarizeState(state)}. Review ${state.artifacts.requirements}`, { state });
+      return await withMutationLock(args, async () => {
+        const state = await startOrchestratedWorkflow(withInferredHost(args) as never);
+        await setActiveRun(state.cwd, state.runId);
+        return success(`${summarizeState(state)}. Review ${state.artifacts.requirements}`, { state });
+      });
+    }
+    if (name === "devcrew_abort") {
+      return await withMutationLock(args, async () => {
+        const runArgs = await withActiveRun(args);
+        const state = await abortOrchestratedWorkflow(runArgs as never);
+        await clearActiveRunIfMatches(state.cwd, state.runId);
+        return success(`${summarizeState(state)}. Run aborted.`, { state });
+      });
+    }
+    if (name === "devcrew_recover") {
+      if (typeof args.cwd !== "string" || !args.cwd.trim()) {
+        throw new Error("cwd must be a non-empty string");
+      }
+      const recoveredLock = await recoverRepositoryLock(args.cwd);
+      if (typeof args.runId !== "string" || !args.runId.trim()) {
+        return success(
+          recoveredLock ? "Repository lock recovery completed." : "No stale repository lock was present.",
+          { recoveredLock },
+        );
+      }
+      return await withMutationLock(args, async () => {
+        const runArgs = await withActiveRun(args);
+        const state = await recoverOrchestratedWorkflow(runArgs as never);
+        return success(`${summarizeState(state)}. Recovery cleanup completed.`, { state });
+      });
     }
     if (name === "devcrew_status") {
       const state = await getWorkflowStatus((await withActiveRun(args)) as never);
       return success(summarizeState(state), { state });
     }
     if (name === "devcrew_answer") {
-      const state = await answerOrchestratedWorkflow((await withActiveRun(args)) as never);
-      return success(`${summarizeState(state)}. Answer recorded.`, { state });
+      return await withMutationLock(args, async () => {
+        const state = await answerOrchestratedWorkflow((await withActiveRun(args)) as never);
+        return success(`${summarizeState(state)}. Answer recorded.`, { state });
+      });
     }
     if (name === "devcrew_approve") {
-      const state = await approveOrchestratedWorkflow((await withActiveRun(args)) as never);
-      return success(`${summarizeState(state)}. Gate approved.`, { state });
+      return await withMutationLock(args, async () => {
+        const state = await approveOrchestratedWorkflow((await withActiveRun(args)) as never);
+        return success(`${summarizeState(state)}. Gate approved.`, { state });
+      });
     }
     if (name === "devcrew_reject") {
-      const state = await rejectOrchestratedWorkflow((await withActiveRun(args)) as never);
-      return success(`${summarizeState(state)}. Gate rejected.`, { state });
+      return await withMutationLock(args, async () => {
+        const state = await rejectOrchestratedWorkflow((await withActiveRun(args)) as never);
+        return success(`${summarizeState(state)}. Gate rejected.`, { state });
+      });
     }
     if (name === "devcrew_continue") {
-      const state = await continueOrchestratedWorkflow((await withActiveRun(args)) as never);
-      return success(`${summarizeState(state)}.`, { state });
+      return await withMutationLock(args, async () => {
+        const state = await continueOrchestratedWorkflow((await withActiveRun(args)) as never);
+        return success(`${summarizeState(state)}.`, { state });
+      });
     }
     if (name === "devcrew_complete_execution") {
-      const state = await completeOrchestratedExecution((await withActiveRun(args)) as never);
-      return success(`${summarizeState(state)}. Native host completion recorded.`, { state });
+      return await withMutationLock(args, async () => {
+        const state = await completeOrchestratedExecution((await withActiveRun(args)) as never);
+        return success(`${summarizeState(state)}. Native host completion recorded.`, { state });
+      });
     }
     if (name === "devcrew_waive_verification") {
-      const state = await waiveOrchestratedVerification((await withActiveRun(args)) as never);
-      return success(`${summarizeState(state)}. Verification waiver recorded.`, { state });
+      return await withMutationLock(args, async () => {
+        const state = await waiveOrchestratedVerification((await withActiveRun(args)) as never);
+        return success(`${summarizeState(state)}. Verification waiver recorded.`, { state });
+      });
     }
     if (name === "devcrew_artifact") {
       const artifact = await getArtifact((await withActiveRun(args)) as never);

package/plugins/devcrew-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "devcrew",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "DevCrew gated multi-role workflow service for Codex.",
   "author": {
     "name": "DevCrew Contributors",

package/plugins/devcrew-codex/.mcp.json

@@ -6,7 +6,7 @@
         "exec",
         "--silent",
         "--yes",
-        "--package=@shenlee/devcrew@0.1.3",
+        "--package=@shenlee/devcrew@0.1.5",
         "--",
         "node",
         "-e",

package/scripts/smoke-codex-plugin.mjs

@@ -298,7 +298,7 @@ async function main() {
       await client.request("initialize", {
         protocolVersion: "2025-03-26",
         capabilities: {},
-        clientInfo: { name: "devcrew-codex-plugin-smoke", version: "0.1.3" },
+        clientInfo: { name: "devcrew-codex-plugin-smoke", version: "0.1.5" },
       });
       client.notify("notifications/initialized", {});
       const tools = await client.request("tools/list", {});