@shenlee/devcrew 0.1.3 → 0.1.5

package/dist/packages/orchestrator/src/index.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { runRole } from "../../adapters/src/index.js";
-import { answerWorkflow, approveWorkflow, artifactForPhase, artifactPath, ARTIFACTS, discoverCoverageCommands, discoverLintCommands, discoverVerifyCommands, gateForPhase, getWorkflowStatus, nextPhaseAfterGate, readConfig, rejectWorkflow, renderArtifact, saveState, startWorkflow, validateWorkflowApproval, waiveVerificationWorkflow, } from "../../core/src/index.js";
+import { abortWorkflow, answerWorkflow, approveWorkflow, artifactForPhase, artifactPath, ARTIFACTS, discoverCoverageCommands, discoverLintCommands, discoverVerifyCommands, gateForPhase, getWorkflowStatus, nextPhaseAfterGate, readConfig, rejectWorkflow, renderArtifact, saveState, startWorkflow, validateWorkflowApproval, waiveVerificationWorkflow, } from "../../core/src/index.js";
 import { captureExecutionChanges, cleanupExecutionWorkspace, ensureExecutionWorkspace, promoteExecutionChanges, rollbackPromotedExecutionChanges, } from "./worktree.js";
 // Hard cap so a hung apply/verify command cannot block the serialized MCP loop.
 const COMMAND_TIMEOUT_MS = 300_000;
@@ -25,6 +25,7 @@ function conductorDecision(state, role, gate) {
         summary,
         markdown: `# Conductor Decision\n\n${summary}\n`,
         usedFallback: false,
+        format: "legacy",
     };
 }
 function priorArtifactNamesForPhase(phase) {
@@ -170,12 +171,14 @@ function verificationStatusFor(results) {
     return results.every((result) => result.exitCode === 0) ? "passed" : "failed";
 }
 function setTestingGateFromVerification(state) {
-    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;
@@ -198,6 +201,7 @@ function hostCompletionResult(state, summary) {
         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",
     };
 }
 function parseCompletionSummary(value) {
@@ -233,16 +237,56 @@ function parseCompletionVerification(value) {
         };
     });
 }
-function appendExecutionSections(artifact, markdown, state) {
+function structuredRoleResultBlock(result) {
+    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, markdown, state, result) {
+    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)}`;
         }
@@ -254,7 +298,7 @@ function appendExecutionSections(artifact, markdown, state) {
         }
         return `${content}\n`;
     }
-    return markdown;
+    return `${content}\n`;
 }
 async function writeImplementationReview(state) {
     state.artifacts["implementation-review"] = await writeMarkdownArtifact(state, "implementation-review", renderArtifact("implementation-review", state));
@@ -361,11 +405,12 @@ async function runCurrentPhaseRole(state, runner = runRole) {
         await writeImplementationReview(state);
     }
     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(),
         };
@@ -373,12 +418,15 @@ async function runCurrentPhaseRole(state, runner = 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);
@@ -419,7 +467,8 @@ export async function continueOrchestratedWorkflow(input, runner = runRole) {
     if (state.status === "awaiting_approval" ||
         state.status === "awaiting_input" ||
         state.status === "awaiting_execution" ||
-        state.status === "complete") {
+        state.status === "complete" ||
+        state.status === "aborted") {
         return state;
     }
     return runCurrentPhaseRole(state, runner);
@@ -454,8 +503,8 @@ export async function approveOrchestratedWorkflow(input) {
         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;
@@ -524,7 +573,7 @@ export async function completeOrchestratedExecution(input) {
     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;
@@ -534,6 +583,32 @@ export async function completeOrchestratedExecution(input) {
 export async function rejectOrchestratedWorkflow(input) {
     return rejectWorkflow(input);
 }
+export async function abortOrchestratedWorkflow(input) {
+    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) {
+    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, runner = runRole) {
     const before = await getWorkflowStatus(input);
     const state = await answerWorkflow(input, { skipArtifactWrite: true });
@@ -545,6 +620,15 @@ export async function answerOrchestratedWorkflow(input, runner = runRole) {
         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) {
         return state;

package/dist/packages/service/src/tools.js

@@ -1,5 +1,5 @@
-import { getArtifact, getActiveRunId, getWorkflowStatus, setActiveRun, } from "../../core/src/index.js";
-import { answerOrchestratedWorkflow, approveOrchestratedWorkflow, completeOrchestratedExecution, continueOrchestratedWorkflow, rejectOrchestratedWorkflow, startOrchestratedWorkflow, waiveOrchestratedVerification, } from "../../orchestrator/src/index.js";
+import { clearActiveRunIfMatches, getArtifact, getActiveRunId, getWorkflowStatus, recoverRepositoryLock, setActiveRun, withRepositoryLock, } from "../../core/src/index.js";
+import { abortOrchestratedWorkflow, answerOrchestratedWorkflow, approveOrchestratedWorkflow, completeOrchestratedExecution, continueOrchestratedWorkflow, rejectOrchestratedWorkflow, recoverOrchestratedWorkflow, startOrchestratedWorkflow, waiveOrchestratedVerification, } from "../../orchestrator/src/index.js";
 const cwdProperty = { type: "string", description: "Repository working directory." };
 const runIdProperty = { type: "string", description: "DevCrew run id." };
 const hostValues = ["codex", "claude"];
@@ -22,8 +22,23 @@ function withInferredHost(args) {
     }
     return { ...args, host: inferHost() };
 }
+async function withMutationLock(args, action) {
+    if (typeof args.cwd !== "string" || !args.cwd.trim()) {
+        return action();
+    }
+    return withRepositoryLock(args.cwd, action);
+}
 export function listDevCrewTools() {
     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.",
@@ -49,6 +64,15 @@ export function listDevCrewTools() {
                 },
             },
         },
+        {
+            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.",
@@ -152,7 +176,8 @@ function summarizeState(state) {
     const pendingGate = Object.entries(state.gates).find(([, status]) => status === "pending")?.[0] ?? "none";
     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, structuredContent) {
     return {
@@ -172,37 +197,73 @@ function failure(error) {
 export async function callDevCrewTool(name, args) {
     try {
         if (name === "devcrew_start") {
-            const state = await startOrchestratedWorkflow(withInferredHost(args));
-            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));
+                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);
+                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);
+                return success(`${summarizeState(state)}. Recovery cleanup completed.`, { state });
+            });
         }
         if (name === "devcrew_status") {
             const state = await getWorkflowStatus((await withActiveRun(args)));
             return success(summarizeState(state), { state });
         }
         if (name === "devcrew_answer") {
-            const state = await answerOrchestratedWorkflow((await withActiveRun(args)));
-            return success(`${summarizeState(state)}. Answer recorded.`, { state });
+            return await withMutationLock(args, async () => {
+                const state = await answerOrchestratedWorkflow((await withActiveRun(args)));
+                return success(`${summarizeState(state)}. Answer recorded.`, { state });
+            });
         }
         if (name === "devcrew_approve") {
-            const state = await approveOrchestratedWorkflow((await withActiveRun(args)));
-            return success(`${summarizeState(state)}. Gate approved.`, { state });
+            return await withMutationLock(args, async () => {
+                const state = await approveOrchestratedWorkflow((await withActiveRun(args)));
+                return success(`${summarizeState(state)}. Gate approved.`, { state });
+            });
         }
         if (name === "devcrew_reject") {
-            const state = await rejectOrchestratedWorkflow((await withActiveRun(args)));
-            return success(`${summarizeState(state)}. Gate rejected.`, { state });
+            return await withMutationLock(args, async () => {
+                const state = await rejectOrchestratedWorkflow((await withActiveRun(args)));
+                return success(`${summarizeState(state)}. Gate rejected.`, { state });
+            });
         }
         if (name === "devcrew_continue") {
-            const state = await continueOrchestratedWorkflow((await withActiveRun(args)));
-            return success(`${summarizeState(state)}.`, { state });
+            return await withMutationLock(args, async () => {
+                const state = await continueOrchestratedWorkflow((await withActiveRun(args)));
+                return success(`${summarizeState(state)}.`, { state });
+            });
         }
         if (name === "devcrew_complete_execution") {
-            const state = await completeOrchestratedExecution((await withActiveRun(args)));
-            return success(`${summarizeState(state)}. Native host completion recorded.`, { state });
+            return await withMutationLock(args, async () => {
+                const state = await completeOrchestratedExecution((await withActiveRun(args)));
+                return success(`${summarizeState(state)}. Native host completion recorded.`, { state });
+            });
         }
         if (name === "devcrew_waive_verification") {
-            const state = await waiveOrchestratedVerification((await withActiveRun(args)));
-            return success(`${summarizeState(state)}. Verification waiver recorded.`, { state });
+            return await withMutationLock(args, async () => {
+                const state = await waiveOrchestratedVerification((await withActiveRun(args)));
+                return success(`${summarizeState(state)}. Verification waiver recorded.`, { state });
+            });
         }
         if (name === "devcrew_artifact") {
             const artifact = await getArtifact((await withActiveRun(args)));

package/docs/claude-code.md

@@ -22,13 +22,26 @@ It contains:
 Role behavior is defined by the DevCrew MCP service and its shared runtime role
 schema. The plugin intentionally does not bundle inactive subagent templates.
 
+## Structured role results
+
+SDK roles should return one `<!-- devcrew-role-result -->` marker followed by a
+JSON fenced block with `schemaVersion: 1`, then the human-readable Markdown
+artifact. The JSON carries the role summary, risks, command evidence, and
+role-specific fields such as PM questions, architecture decisions, changed
+files, or test cases. DevCrew removes the marked block before saving the
+Markdown artifact and exposes the validated data through MCP state.
+
+Markdown-only output remains supported as `role_format=legacy`. A missing marker
+uses this compatibility path; a present marker with malformed, ambiguous, or
+schema-invalid JSON is rejected and never silently downgraded.
+
 For local plugin testing:
 
 ```bash
 claude --plugin-dir plugins/devcrew-claude
 ```
 
-Then ask Claude Code to use DevCrew for a feature or product workflow. The generated `.mcp.json` starts the version-locked npm package with an `npm exec --package=@shenlee/devcrew@0.1.3` wrapper.
+Then ask Claude Code to use DevCrew for a feature or product workflow. The generated `.mcp.json` starts the version-locked npm package with an `npm exec --package=@shenlee/devcrew@0.1.5` wrapper.
 
 The default apply policy is `interactive-host`: Claude Code performs implementation and testing with its native controls. Explicit `headless-restricted` and `headless-unattended` policies are independent DevCrew SDK policies and do not inherit the current Claude Code approval session.
 

package/docs/codex.md

@@ -13,7 +13,7 @@ Restart Codex, open the plugin directory, select the DevCrew marketplace, and in
 The plugin launches the MCP server with:
 
 ```bash
-npm exec --silent --yes --package=@shenlee/devcrew@0.1.3 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
+npm exec --silent --yes --package=@shenlee/devcrew@0.1.5 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
 ```
 
 Use this path when you want to use DevCrew without cloning the repository first. The version is locked to the published npm package that matches the plugin manifest.
@@ -42,6 +42,19 @@ It contains:
 Role behavior is defined by the DevCrew MCP service and its shared runtime role
 schema. The plugin intentionally does not bundle inactive subagent templates.
 
+## Structured role results
+
+SDK roles should return one `<!-- devcrew-role-result -->` marker followed by a
+JSON fenced block with `schemaVersion: 1`, then the human-readable Markdown
+artifact. The JSON carries the role summary, risks, command evidence, and
+role-specific fields such as PM questions, architecture decisions, changed
+files, or test cases. DevCrew removes the marked block before saving the
+Markdown artifact and exposes the validated data through MCP state.
+
+Markdown-only output remains supported as `role_format=legacy`. A missing marker
+uses this compatibility path; a present marker with malformed, ambiguous, or
+schema-invalid JSON is rejected and never silently downgraded.
+
 For local development, point a Codex marketplace entry at the generated plugin folder, or copy the plugin into your existing local marketplace workflow.
 
 The DevCrew skill tells Codex to use these MCP tools:
@@ -70,7 +83,7 @@ npm install -g @shenlee/devcrew --include=optional
 
 ## Marketplace smoke test
 
-After publishing `@shenlee/devcrew@0.1.3`, run the real marketplace smoke test. Do not treat this as a pre-publication check because the plugin is locked to that npm version:
+After publishing `@shenlee/devcrew@0.1.5`, run the real marketplace smoke test. Do not treat this as a pre-publication check because the plugin is locked to that npm version:
 
 ```bash
 npm run smoke:codex-plugin

package/docs/quickstart.md

@@ -37,7 +37,7 @@ devcrew serve --stdio
 ```
 
 Normally the generated plugin starts this command for the host agent.
-Codex and Claude plugin bundles use a version-locked `npm exec --package=@shenlee/devcrew@0.1.3` wrapper so the MCP service is locked to the published package version.
+Codex and Claude plugin bundles use a version-locked `npm exec --package=@shenlee/devcrew@0.1.5` wrapper so the MCP service is locked to the published package version.
 
 ## 4. Run A Workflow
 

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.5",
   "description": "Multi-host agent workflow service for Codex and Claude Code.",
   "type": "module",
   "license": "Apache-2.0",
@@ -55,6 +55,6 @@
   },
   "optionalDependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.163",
-    "@openai/codex-sdk": "0.137.0"
+    "@openai/codex-sdk": "0.144.5"
   }
 }