@shenlee/devcrew 0.1.2 → 0.1.4

package/packages/service/src/tools.ts

@@ -1,17 +1,24 @@
 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";
 
 export interface DevCrewTool {
@@ -56,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.",
@@ -73,11 +96,25 @@ export function listDevCrewTools(): DevCrewTool[] {
             enum: ["plan", "apply"],
             description: "Execution mode. Defaults to plan; apply must be explicit.",
           },
+          executionPolicy: {
+            type: "string",
+            enum: ["interactive-host", "headless-restricted", "headless-unattended"],
+            description: "Apply execution policy. Defaults to interactive-host; headless policies are explicit DevCrew SDK policies.",
+          },
           request: { type: "string" },
           backend: { type: "string", enum: ["codex", "claude", "local"] },
         },
       },
     },
+    {
+      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.",
@@ -105,7 +142,7 @@ export function listDevCrewTools(): DevCrewTool[] {
         properties: {
           cwd: cwdProperty,
           runId: runIdProperty,
-          gate: { type: "string", enum: ["requirements", "architecture", "implementation", "testing"] },
+          gate: { type: "string", enum: ["requirements", "architecture", "implementation", "implementation-review", "testing"] },
           note: { type: "string" },
         },
       },
@@ -119,7 +156,7 @@ export function listDevCrewTools(): DevCrewTool[] {
         properties: {
           cwd: cwdProperty,
           runId: runIdProperty,
-          gate: { type: "string", enum: ["requirements", "architecture", "implementation", "testing"] },
+          gate: { type: "string", enum: ["requirements", "architecture", "implementation", "implementation-review", "testing"] },
           feedback: { type: "string" },
         },
       },
@@ -133,6 +170,32 @@ export function listDevCrewTools(): DevCrewTool[] {
         properties: { cwd: cwdProperty, runId: runIdProperty },
       },
     },
+    {
+      name: "devcrew_complete_execution",
+      description: "Record completion by the native host for an interactive-host execution or testing step.",
+      inputSchema: {
+        type: "object",
+        required: ["cwd", "summary"],
+        properties: {
+          cwd: cwdProperty,
+          runId: runIdProperty,
+          summary: { type: "string" },
+          verification: {
+            type: "array",
+            description: "Required only when completing testing: command, exitCode, output, startedAt, and completedAt for each validation command.",
+          },
+        },
+      },
+    },
+    {
+      name: "devcrew_waive_verification",
+      description: "Record a reasoned risk waiver after failed apply-mode verification, then reopen the testing gate for approval.",
+      inputSchema: {
+        type: "object",
+        required: ["cwd", "reason"],
+        properties: { cwd: cwdProperty, runId: runIdProperty, reason: { type: "string" } },
+      },
+    },
     {
       name: "devcrew_artifact",
       description: "Read a generated workflow artifact.",
@@ -144,7 +207,7 @@ export function listDevCrewTools(): DevCrewTool[] {
           runId: runIdProperty,
           name: {
             type: "string",
-            enum: ["requirements", "architecture", "implementation-plan", "implementation-review", "test-report", "acceptance"],
+            enum: ["requirements", "architecture", "implementation-plan", "implementation-review", "architecture-review", "test-report", "acceptance"],
           },
         },
       },
@@ -157,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 {
@@ -180,29 +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") {
+      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") {
+      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.2",
+  "version": "0.1.4",
   "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.2",
+        "--package=@shenlee/devcrew@0.1.4",
         "--",
         "node",
         "-e",

package/plugins/devcrew-codex/skills/devcrew/SKILL.md

@@ -5,13 +5,14 @@ description: Run the DevCrew PM -> architecture -> implementation -> testing wor
 
 Use the DevCrew MCP tools to manage the workflow:
 
-1. Start with `devcrew_start` using the current repository cwd, mode, request, and optional executionMode. Host is inferred from the plugin's `DEVCREW_HOST`; pass host only for an explicit override. Omit executionMode unless the requester explicitly asks DevCrew to apply changes; the default safe mode is `plan`.
-2. After start, DevCrew records the active run for this repository. For follow-up tools, omit runId unless you need to target a different run explicitly.
-3. Use `executionMode: "apply"` only when the requester explicitly wants DevCrew to write code or run validation commands. This still inherits host sandbox, approval, and tool permissions.
-4. Use `devcrew_status` to show the current phase and pending gate.
+1. Start with `devcrew_start` using the current repository cwd, mode, request, and optional `executionMode`. Host is inferred from the plugin's `DEVCREW_HOST`; pass host only for an explicit override. Omit `executionMode` unless the requester explicitly asks DevCrew to apply changes; the default safe mode is `plan`.
+2. After start, DevCrew records the active run for this repository. For follow-up tools, omit `runId` unless you need to target a different run explicitly.
+3. For `executionMode: "apply"`, choose an explicit `executionPolicy`. The default `interactive-host` pauses at implementation and testing for the host's native agent to work in DevCrew's isolated worktree. `headless-restricted` and `headless-unattended` are DevCrew SDK policies; they do not inherit the current host approval session.
+4. Use `devcrew_status` to show the current phase, pending gate, and any execution instruction.
 5. Use `devcrew_answer` when the requester gives clarification.
 6. Use `devcrew_approve` or `devcrew_reject` for each gate.
-7. Use `devcrew_continue` after approvals. This executes the next phase role, writes the phase artifact, and opens the next gate. The implementation phase also writes `implementation-review` for diff and architecture compliance review.
-8. Use `devcrew_artifact` to read generated requirements, architecture, implementation-plan, implementation-review, test-report, or acceptance files.
+7. Use `devcrew_continue` after approvals. Apply runs enter an `implementation-review` gate after execution: review the architect's `architecture-review` artifact before testing. For `interactive-host`, if status becomes `awaiting_execution`, perform the native-host work in the indicated worktree then call `devcrew_complete_execution`. For testing, include command, exit code, output, startedAt, and completedAt evidence.
+8. Failed verification is not approvable. Revise through `devcrew_answer`, or use `devcrew_waive_verification` only when the requester explicitly accepts the recorded risk and provides a reason.
+9. Use `devcrew_artifact` to read generated requirements, architecture, implementation-plan, implementation-review, architecture-review, test-report, or acceptance files.
 
-Do not bypass host sandbox, approval, or tool permissions.
+Never describe a nested SDK session as inheriting the current host's approval decisions.

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.2" },
+        clientInfo: { name: "devcrew-codex-plugin-smoke", version: "0.1.4" },
       });
       client.notify("notifications/initialized", {});
       const tools = await client.request("tools/list", {});

package/plugins/devcrew-codex/agents/architect.toml

@@ -1,12 +0,0 @@
-name = "architect"
-description = "technical architecture specialist. Designs implementation, deployment, interfaces, and review criteria."
-developer_instructions = """
-You are the DevCrew architect role. technical architecture specialist. Designs implementation, deployment, interfaces, and review criteria.
-Return concise Markdown and keep inherited host permissions.
-
-Produce these required sections:
-- Technical Decisions (for each key decision record Decision, Options Considered, Choice, Rationale, and Trade-offs)
-- Interface Contracts (for each interface give the signature, request/response schema, error contract, and data model)
-- Data Flow and Deployment (data flow, deployment expectations, and rollback strategy)
-- Architecture Review Checklist (how the design traces back to the approved requirements)
-"""

package/plugins/devcrew-codex/agents/implementer.toml

@@ -1,12 +0,0 @@
-name = "implementer"
-description = "Implementation engineer. Writes code according to approved architecture and discovered standards."
-developer_instructions = """
-You are the DevCrew implementer role. Implementation engineer. Writes code according to approved architecture and discovered standards.
-Return concise Markdown and keep inherited host permissions.
-
-Produce these required sections:
-- Implementation Summary (the smallest change that satisfies the approved architecture)
-- Standards Compliance (follow discovered standards and lint/format rules; run available lint/format/typecheck and report results)
-- Changed Files (every file you created or modified)
-- Tests Added or Updated (tests covering success, edge, and failure paths)
-"""

package/plugins/devcrew-codex/agents/pm.toml

@@ -1,13 +0,0 @@
-name = "pm"
-description = "Product manager. Clarifies requirements, scope boundaries, success criteria, and requester approvals."
-developer_instructions = """
-You are the DevCrew pm role. Product manager. Clarifies requirements, scope boundaries, success criteria, and requester approvals.
-Return concise Markdown and keep inherited host permissions.
-
-Produce these required sections:
-- Functional Scope (explicit In Scope and Out of Scope lists)
-- Users and Scenarios (primary users and their key scenarios)
-- Acceptance Criteria (testable criteria written as Given / When / Then)
-- Priorities (classify each requirement as Must / Should / Could / Won't (MoSCoW))
-- Open Questions (unresolved clarifications for the requester)
-"""

package/plugins/devcrew-codex/agents/tester.toml

@@ -1,12 +0,0 @@
-name = "tester"
-description = "Testing and acceptance specialist. Verifies functionality, regressions, and acceptance evidence."
-developer_instructions = """
-You are the DevCrew tester role. Testing and acceptance specialist. Verifies functionality, regressions, and acceptance evidence.
-Return concise Markdown and keep inherited host permissions.
-
-Produce these required sections:
-- Test Cases (enumerate cases as a table with ID, Scenario, Type (happy/edge/failure/regression), and Expected result)
-- Coverage (run the coverage command and report the coverage summary plus any gaps)
-- Verification Evidence (exact commands, exit codes, and key output)
-- Known Risks (residual risks and follow-ups)
-"""