@shenlee/devcrew 0.1.3 → 0.1.4

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.4` 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.4 -- 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.4`, 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.4` wrapper so the MCP service is locked to the published package version.
 
 ## 4. Run A Workflow
 

package/docs/superpowers/plans/2026-07-14-p0-remediation.md

@@ -0,0 +1,213 @@
+# P0 Verification and Review Remediation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Prevent unverified apply patches from being promoted and send architecture-review findings back through implementation.
+
+**Architecture:** Keep `verificationStatus` as the single source for testing-gate policy. Treat `failed` and `not_run` identically for blocking, but allow the existing persisted waiver to reopen either state. Reuse the existing testing-rejection recovery pattern for implementation-review findings, preserving the isolated worktree while returning the state machine to `execution/ready`.
+
+**Tech Stack:** TypeScript, Node.js test runner, Git worktrees, existing DevCrew MCP/orchestrator APIs.
+
+---
+
+### Task 1: Block missing verification evidence
+
+**Files:**
+- Modify: `tests/orchestrator.test.ts:483-533`
+- Modify: `packages/orchestrator/src/index.ts:241-253, 552-558`
+- Modify: `packages/core/src/workflow.ts:297-314`
+
+- [ ] **Step 1: Write failing no-verification tests**
+
+Add a test after the failed-verification test that creates an apply fixture with
+an empty `verifyCommands` list and no discoverable manifest. Advance it through
+testing and assert the following:
+
+```ts
+assert.equal(tested.verificationStatus, "not_run");
+assert.equal(tested.gates.testing, "rejected");
+assert.equal(tested.status, "awaiting_input");
+await assert.rejects(
+  () => approveOrchestratedWorkflow({ cwd, runId: tested.runId, gate: "testing" }),
+  /not pending approval/i,
+);
+```
+
+In the same test, call `waiveOrchestratedVerification` with a non-empty reason,
+assert `testing: pending` and `awaiting_approval`, then approve testing and
+assert the reviewed file was promoted. Add a second assertion that directly
+sets a persisted test fixture to `verificationStatus: "not_run"`, a pending
+testing gate, and no waiver, then expects `approveOrchestratedWorkflow` to
+throw `Verification must pass before promotion`.
+
+- [ ] **Step 2: Run the focused test and verify RED**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: the new test fails because `not_run` currently opens a pending gate
+and the waiver operation rejects it.
+
+- [ ] **Step 3: Implement the minimal verification policy**
+
+In `setTestingGateFromVerification`, replace the `failed`-only branch with a
+non-passed branch. Preserve the existing failed message and add a distinct
+missing-evidence message:
+
+```ts
+if (state.verificationStatus !== "passed") {
+  state.gates.testing = "rejected";
+  state.status = "awaiting_input";
+  state.feedback.push({
+    gate: "testing",
+    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;
+}
+```
+
+Update `waiveVerificationWorkflow` to accept either `failed` or `not_run` and
+change its error message to mention failed or missing verification. In
+`approveOrchestratedWorkflow`, replace the failed-only promotion check with:
+
+```ts
+if (before.verificationStatus !== "passed" && !before.verificationWaiver) {
+  throw new Error("Verification must pass before promotion or have an explicit verification waiver");
+}
+```
+
+- [ ] **Step 4: Run focused tests and verify GREEN**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: all orchestrator tests pass, including failed and missing
+verification waiver paths.
+
+- [ ] **Step 5: Commit the verification fix**
+
+```bash
+git add packages/core/src/workflow.ts packages/orchestrator/src/index.ts tests/orchestrator.test.ts
+git commit -m "fix: block promotion without verification evidence"
+```
+
+### Task 2: Return review findings to execution
+
+**Files:**
+- Modify: `tests/orchestrator.test.ts:365-421`
+- Modify: `packages/orchestrator/src/index.ts:639-658`
+- Modify: `docs/workflow.md:45-49`
+
+- [ ] **Step 1: Write the failing review-remediation test**
+
+Extend `architecture review blocks testing when it requires changes` after its
+current rejection assertions. Call `answerOrchestratedWorkflow` with a
+non-empty answer and assert:
+
+```ts
+assert.equal(revised.phase, "execution");
+assert.equal(revised.status, "ready");
+assert.equal(revised.gates["implementation-review"], "not_started");
+assert.equal(revised.executionWorkspace?.path, workspacePath);
+```
+
+Then call `continueOrchestratedWorkflow` with a runner that records its phase
+and assert the next executed role has `phase === "execution"` and
+`role === "implementer"`, not `review`/`architect`.
+
+- [ ] **Step 2: Run the focused test and verify RED**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: the new assertions fail because `devcrew_answer` currently re-runs
+the review phase.
+
+- [ ] **Step 3: Implement the remediation transition**
+
+Add this branch in `answerOrchestratedWorkflow` immediately after the existing
+testing-rejection branch:
+
+```ts
+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);
+}
+```
+
+Do not clear `executionWorkspace`, `architectureReview`, feedback, or the
+prior review artifact; they remain audit evidence and the next execution phase
+will refresh the captured diff and create a new review.
+
+- [ ] **Step 4: Update the workflow documentation**
+
+Replace the current claim that feedback must be addressed before another review
+with text stating that `devcrew_answer` returns the run to the isolated
+`execution/ready` state and a later `devcrew_continue` performs the revised
+implementation before a fresh architect review.
+
+- [ ] **Step 5: Run focused tests and verify GREEN**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: all orchestrator tests pass and the remediation test observes an
+implementer execution before a subsequent review.
+
+- [ ] **Step 6: Commit the remediation fix**
+
+```bash
+git add docs/workflow.md packages/orchestrator/src/index.ts tests/orchestrator.test.ts
+git commit -m "fix: return architecture findings to execution"
+```
+
+### Task 3: Full verification
+
+**Files:**
+- Verify: `packages/core/src/workflow.ts`
+- Verify: `packages/orchestrator/src/index.ts`
+- Verify: `tests/orchestrator.test.ts`
+
+- [ ] **Step 1: Run the complete repository validation**
+
+Run:
+
+```bash
+npm run validate
+```
+
+Expected: TypeScript compilation succeeds and every test passes.
+
+- [ ] **Step 2: Inspect the final diff**
+
+Run:
+
+```bash
+git diff main...HEAD --check
+git status --short
+```
+
+Expected: no whitespace errors; only the two implementation commits and this
+plan/spec commits are present on the branch.