@shenlee/devcrew 0.1.1 → 0.1.3

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

@@ -0,0 +1,198 @@
+import { spawn } from "node:child_process";
+import { access, mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { executionWorktreePath, runDir, } from "../../core/src/index.js";
+const REPOSITORY_PATHS = [
+    ".",
+    ":(exclude).devcrew",
+    ":(exclude).devcrew/**",
+    ":(exclude)docs/devcrew",
+    ":(exclude)docs/devcrew/**",
+];
+async function runGit(args, cwd, stdin, env) {
+    return new Promise((resolveResult, rejectResult) => {
+        const child = spawn("git", args, { cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const rejectOnce = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            rejectResult(error);
+        };
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", rejectOnce);
+        child.on("close", (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (code === 0) {
+                resolveResult(stdout);
+                return;
+            }
+            rejectResult(new Error(`git ${args[0]} failed: ${(stderr || stdout).trim()}`));
+        });
+        child.stdin.end(stdin);
+    });
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertCleanRequester(cwd) {
+    const status = await runGit([
+        "status",
+        "--porcelain",
+        "-uall",
+        "--",
+        ...REPOSITORY_PATHS,
+    ], cwd);
+    if (status.trim()) {
+        throw new Error("DevCrew apply promotion requires a clean working tree");
+    }
+}
+function nulPaths(output) {
+    return output.split("\0").filter(Boolean);
+}
+function parseChangedFiles(output) {
+    const fields = nulPaths(output);
+    const paths = [];
+    for (let index = 0; index < fields.length;) {
+        const status = fields[index++];
+        const firstPath = fields[index++];
+        if (!status || !firstPath) {
+            throw new Error("DevCrew could not parse git diff name status output");
+        }
+        paths.push(firstPath);
+        if (status.startsWith("R") || status.startsWith("C")) {
+            const secondPath = fields[index++];
+            if (!secondPath) {
+                throw new Error("DevCrew could not parse renamed git diff path");
+            }
+            paths.push(secondPath);
+        }
+    }
+    return [...new Set(paths)];
+}
+async function markUntrackedIntentToAdd(cwd, env) {
+    const untracked = nulPaths(await runGit(["ls-files", "--others", "--exclude-standard", "-z", "--", ...REPOSITORY_PATHS], cwd, undefined, env));
+    if (untracked.length > 0) {
+        await runGit(["add", "-N", "--", ...untracked], cwd, undefined, env);
+    }
+}
+async function capturePatch(workspace, options = {}) {
+    await markUntrackedIntentToAdd(workspace.path, options.env);
+    const changedFiles = parseChangedFiles(await runGit(["diff", "--name-status", "-z", workspace.baseCommit, "--", ...REPOSITORY_PATHS], workspace.path, undefined, options.env));
+    const patch = await runGit(["diff", "--binary", "--no-ext-diff", workspace.baseCommit, "--", ...REPOSITORY_PATHS], workspace.path, undefined, options.env);
+    if (!options.allowEmpty && !patch.trim()) {
+        throw new Error("DevCrew apply implementer produced no repository changes");
+    }
+    return { changedFiles, patch };
+}
+async function captureRequesterChanges(state, workspace) {
+    const indexPath = join(runDir(state.cwd, state.runId), "promotion.index");
+    await mkdir(dirname(indexPath), { recursive: true });
+    await rm(indexPath, { force: true });
+    const env = { ...process.env, GIT_INDEX_FILE: indexPath };
+    try {
+        await runGit(["read-tree", workspace.baseCommit], state.cwd, undefined, env);
+        return await capturePatch({ path: state.cwd, baseCommit: workspace.baseCommit }, { allowEmpty: true, env });
+    }
+    finally {
+        await rm(indexPath, { force: true });
+    }
+}
+export async function ensureExecutionWorkspace(state) {
+    if (state.executionWorkspace && (await pathExists(state.executionWorkspace.path))) {
+        return state.executionWorkspace;
+    }
+    await assertCleanRequester(state.cwd);
+    const baseCommit = (await runGit(["rev-parse", "HEAD"], state.cwd)).trim();
+    const path = executionWorktreePath(state.cwd, state.runId);
+    await mkdir(dirname(path), { recursive: true });
+    await runGit(["worktree", "add", "--detach", path, baseCommit], state.cwd);
+    return { path, baseCommit };
+}
+export async function captureExecutionChanges(workspace) {
+    const head = (await runGit(["rev-parse", "HEAD"], workspace.path)).trim();
+    if (head !== workspace.baseCommit) {
+        await runGit(["reset", "--mixed", workspace.baseCommit], workspace.path);
+    }
+    return capturePatch(workspace);
+}
+export async function promoteExecutionChanges(state) {
+    const workspace = state.executionWorkspace;
+    if (!workspace || !state.implementationDiff.trim()) {
+        throw new Error("DevCrew apply promotion requires reviewed execution changes");
+    }
+    const requesterHead = (await runGit(["rev-parse", "HEAD"], state.cwd)).trim();
+    if (requesterHead !== workspace.baseCommit) {
+        throw new Error("DevCrew apply promotion refused because requester HEAD changed");
+    }
+    const patchPath = join(runDir(state.cwd, state.runId), "implementation.patch");
+    await mkdir(dirname(patchPath), { recursive: true });
+    await writeFile(patchPath, state.implementationDiff);
+    const current = await captureRequesterChanges(state, workspace);
+    if (current.patch === state.implementationDiff) {
+        return;
+    }
+    if (current.patch.trim()) {
+        throw new Error("DevCrew apply promotion requires a clean working tree");
+    }
+    await assertCleanRequester(state.cwd);
+    await runGit(["apply", "--check", "--binary", patchPath], state.cwd);
+    await runGit(["apply", "--binary", patchPath], state.cwd);
+    const promoted = await captureRequesterChanges(state, workspace);
+    if (promoted.patch !== state.implementationDiff) {
+        try {
+            await runGit(["apply", "--reverse", "--binary", patchPath], state.cwd);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? `: ${error.message}` : "";
+            throw new Error(`DevCrew promoted patch verification failed and rollback failed${detail}`);
+        }
+        throw new Error("DevCrew promoted patch differs from the reviewed implementation diff");
+    }
+}
+export async function rollbackPromotedExecutionChanges(state) {
+    const workspace = state.executionWorkspace;
+    if (!workspace || !state.implementationDiff.trim()) {
+        throw new Error("DevCrew apply rollback requires reviewed execution changes");
+    }
+    const patchPath = join(runDir(state.cwd, state.runId), "implementation.patch");
+    await runGit(["apply", "--reverse", "--check", "--binary", patchPath], state.cwd);
+    await runGit(["apply", "--reverse", "--binary", patchPath], state.cwd);
+    const remaining = await captureRequesterChanges(state, workspace);
+    if (remaining.patch.trim()) {
+        throw new Error("DevCrew apply rollback left requester repository changes");
+    }
+}
+export async function cleanupExecutionWorkspace(state) {
+    const workspace = state.executionWorkspace;
+    if (!workspace) {
+        return;
+    }
+    if (await pathExists(workspace.path)) {
+        await runGit(["worktree", "remove", "--force", workspace.path], state.cwd);
+    }
+    await runGit(["worktree", "prune"], state.cwd);
+}
+export async function executionCwd(state) {
+    if (state.executionMode !== "apply") {
+        return state.cwd;
+    }
+    return (await ensureExecutionWorkspace(state)).path;
+}

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

@@ -2,7 +2,7 @@ import { constants } from "node:fs";
 import { access, copyFile, mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { DEFAULT_CONFIG, DEVCREW_NPM_PACKAGE, DEVCREW_VERSION, ROLE_SECTIONS } from "../../core/src/index.js";
+import { DEFAULT_CONFIG, DEVCREW_NPM_PACKAGE, DEVCREW_VERSION } from "../../core/src/index.js";
 async function writeJson(path, value) {
     await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
@@ -29,36 +29,8 @@ async function writeCodexAssets(pluginRoot) {
     await copyFile(await bundledAssetPath("logo.png"), join(assetDir, "logo.png"));
     await copyFile(await bundledAssetPath("composer-icon.png"), join(assetDir, "composer-icon.png"));
 }
-function roleExpectations(name) {
-    const sections = ROLE_SECTIONS[name];
-    if (!sections || sections.length === 0) {
-        return "";
-    }
-    return sections.map((s) => `- ${s.heading} (${s.description})`).join("\n");
-}
-async function writeRoleAgents(root, format) {
-    const roles = [
-        ["pm", "Product manager. Clarifies requirements, scope boundaries, success criteria, and requester approvals."],
-        ["architect", "technical architecture specialist. Designs implementation, deployment, interfaces, and review criteria."],
-        ["implementer", "Implementation engineer. Writes code according to approved architecture and discovered standards."],
-        ["tester", "Testing and acceptance specialist. Verifies functionality, regressions, and acceptance evidence."],
-    ];
-    if (format === "claude") {
-        const agentDir = join(root, "agents");
-        await mkdir(agentDir, { recursive: true });
-        for (const [name, description] of roles) {
-            await writeFile(join(agentDir, `${name}.md`), `---\nname: ${name}\ndescription: ${description}\ntools: Read, Grep, Glob, Bash\n---\n\nYou are the DevCrew ${name} role. ${description} Return concise Markdown and keep inherited host permissions.\n\nProduce these required sections:\n\n${roleExpectations(name)}\n`, "utf8");
-        }
-        return;
-    }
-    const agentDir = join(root, "agents");
-    await mkdir(agentDir, { recursive: true });
-    for (const [name, description] of roles) {
-        await writeFile(join(agentDir, `${name}.toml`), `name = "${name}"\ndescription = "${description}"\ndeveloper_instructions = """\nYou are the DevCrew ${name} role. ${description}\nReturn concise Markdown and keep inherited host permissions.\n\nProduce these required sections:\n${roleExpectations(name)}\n"""\n`, "utf8");
-    }
-}
 function entrySkill() {
-    return `---\nname: devcrew\ndescription: Run the DevCrew PM -> architecture -> implementation -> testing workflow. Use when the user asks for structured feature or product development, requirements clarification, architecture review, implementation planning, testing acceptance, or Chinese requests such as 完整研发流程, 需求澄清, 产品经理, 架构师, 开发测试流程.\n---\n\nUse the DevCrew MCP tools to manage the workflow:\n\n1. 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\`.\n2. 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.\n3. 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.\n4. Use \`devcrew_status\` to show the current phase and pending gate.\n5. Use \`devcrew_answer\` when the requester gives clarification.\n6. Use \`devcrew_approve\` or \`devcrew_reject\` for each gate.\n7. 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.\n8. Use \`devcrew_artifact\` to read generated requirements, architecture, implementation-plan, implementation-review, test-report, or acceptance files.\n\nDo not bypass host sandbox, approval, or tool permissions.\n`;
+    return `---\nname: devcrew\ndescription: Run the DevCrew PM -> architecture -> implementation -> testing workflow. Use when the user asks for structured feature or product development, requirements clarification, architecture review, implementation planning, testing acceptance, or Chinese requests such as 完整研发流程, 需求澄清, 产品经理, 架构师, 开发测试流程.\n---\n\nUse the DevCrew MCP tools to manage the workflow:\n\n1. 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\`.\n2. 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.\n3. 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.\n4. Use \`devcrew_status\` to show the current phase, pending gate, and any execution instruction.\n5. Use \`devcrew_answer\` when the requester gives clarification.\n6. Use \`devcrew_approve\` or \`devcrew_reject\` for each gate.\n7. 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.\n8. 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.\n9. Use \`devcrew_artifact\` to read generated requirements, architecture, implementation-plan, implementation-review, architecture-review, test-report, or acceptance files.\n\nNever describe a nested SDK session as inheriting the current host's approval decisions.\n`;
 }
 function npmPackageSpecifier() {
     return `${DEVCREW_NPM_PACKAGE}@${DEVCREW_VERSION}`;
@@ -136,7 +108,6 @@ export async function generateCodexPlugin(root) {
             devcrew: mcpServerConfig("codex"),
         },
     });
-    await writeRoleAgents(pluginRoot, "codex");
     return { name: "devcrew", path: pluginRoot };
 }
 export async function generateCodexMarketplace(root) {
@@ -180,7 +151,6 @@ export async function generateClaudePlugin(root) {
             devcrew: mcpServerConfig("claude"),
         },
     });
-    await writeRoleAgents(pluginRoot, "claude");
     return { name: "devcrew", path: pluginRoot };
 }
 export async function initProject(root) {

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

@@ -1,5 +1,12 @@
 import { callDevCrewTool, listDevCrewTools } from "./tools.js";
 import { DEVCREW_VERSION } from "../../core/src/index.js";
+function isJsonRpcRequest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.jsonrpc === "2.0" &&
+        typeof value.method === "string");
+}
 function writeJson(message) {
     process.stdout.write(`${JSON.stringify(message)}\n`);
 }
@@ -45,7 +52,7 @@ async function handleRequest(request, write) {
             });
             return;
         }
-        throw new Error(`Unsupported JSON-RPC method: ${request.method ?? "unknown"}`);
+        throw new Error(`Unsupported JSON-RPC method: ${request.method}`);
     }
     catch (error) {
         write({
@@ -77,8 +84,17 @@ export function createStdioLineProcessor(write = writeJson, handler = (request)
             });
             return queue;
         }
-        queue = queue.then(() => handler(request));
-        return queue;
+        if (!isJsonRpcRequest(request)) {
+            write({
+                jsonrpc: "2.0",
+                id: null,
+                error: { code: -32600, message: "Invalid Request" },
+            });
+            return queue;
+        }
+        const task = queue.then(() => handler(request));
+        queue = task.catch(() => undefined);
+        return task;
     };
 }
 export function runStdioServer() {

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

@@ -1,5 +1,5 @@
-import { approveWorkflow, getArtifact, getActiveRunId, getWorkflowStatus, setActiveRun, } from "../../core/src/index.js";
-import { answerOrchestratedWorkflow, continueOrchestratedWorkflow, rejectOrchestratedWorkflow, startOrchestratedWorkflow, } from "../../orchestrator/src/index.js";
+import { getArtifact, getActiveRunId, getWorkflowStatus, setActiveRun, } from "../../core/src/index.js";
+import { answerOrchestratedWorkflow, approveOrchestratedWorkflow, completeOrchestratedExecution, continueOrchestratedWorkflow, rejectOrchestratedWorkflow, 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"];
@@ -39,6 +39,11 @@ export function listDevCrewTools() {
                         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"] },
                 },
@@ -71,7 +76,7 @@ export function listDevCrewTools() {
                 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" },
                 },
             },
@@ -85,7 +90,7 @@ export function listDevCrewTools() {
                 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" },
                 },
             },
@@ -99,6 +104,32 @@ export function listDevCrewTools() {
                 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.",
@@ -110,7 +141,7 @@ export function listDevCrewTools() {
                     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"],
                     },
                 },
             },
@@ -154,7 +185,7 @@ export async function callDevCrewTool(name, args) {
             return success(`${summarizeState(state)}. Answer recorded.`, { state });
         }
         if (name === "devcrew_approve") {
-            const state = await approveWorkflow((await withActiveRun(args)));
+            const state = await approveOrchestratedWorkflow((await withActiveRun(args)));
             return success(`${summarizeState(state)}. Gate approved.`, { state });
         }
         if (name === "devcrew_reject") {
@@ -165,6 +196,14 @@ export async function callDevCrewTool(name, args) {
             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 });
+        }
+        if (name === "devcrew_waive_verification") {
+            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)));
             return success(artifact.content, { artifact });

package/docs/claude-code.md

@@ -17,18 +17,20 @@ It contains:
 
 - `.claude-plugin/plugin.json`
 - `skills/devcrew/SKILL.md`
-- `agents/*.md`
 - `.mcp.json`
 
+Role behavior is defined by the DevCrew MCP service and its shared runtime role
+schema. The plugin intentionally does not bundle inactive subagent templates.
+
 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.1` 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.3` wrapper.
 
-Claude Code permissions, hooks, and approval settings remain authoritative. DevCrew inherits the host boundary.
+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.
 
 For apply mode, `@anthropic-ai/claude-agent-sdk` must be resolvable from the installed DevCrew package. Published DevCrew packages declare it as an optional dependency, which npm installs by default. If `devcrew doctor` reports it as missing, reinstall DevCrew with optional dependencies enabled:
 

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.1 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
+npm exec --silent --yes --package=@shenlee/devcrew@0.1.3 -- 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.
@@ -38,7 +38,9 @@ It contains:
 - `.codex-plugin/plugin.json`
 - `skills/devcrew/SKILL.md`
 - `.mcp.json`
-- role agent TOML templates under `agents/`
+
+Role behavior is defined by the DevCrew MCP service and its shared runtime role
+schema. The plugin intentionally does not bundle inactive subagent templates.
 
 For local development, point a Codex marketplace entry at the generated plugin folder, or copy the plugin into your existing local marketplace workflow.
 
@@ -50,9 +52,15 @@ The DevCrew skill tells Codex to use these MCP tools:
 - `devcrew_approve`
 - `devcrew_reject`
 - `devcrew_continue`
+- `devcrew_complete_execution`
+- `devcrew_waive_verification`
 - `devcrew_artifact`
 
-Codex sandbox and approval settings remain authoritative. DevCrew does not bypass them.
+The default apply policy is `interactive-host`: Codex performs the implementation and testing with its native controls. A DevCrew nested SDK is not used in this path. Explicit `headless-restricted` and `headless-unattended` policies are separate DevCrew policies and do not inherit the current Codex approval session.
+
+Apply mode keeps implementation planning read-only. With `interactive-host`, after the implementation gate is approved, call `devcrew_continue`; DevCrew creates `.devcrew/worktrees/<run-id>` and waits at `awaiting_execution`. Use Codex natively in that worktree, then call `devcrew_complete_execution`. Repeat for testing and include command, exit-code, and output evidence. A failed verification cannot open the testing gate; revise it or record an explicit reason through `devcrew_waive_verification`. Testing approval promotes the exact reviewed patch to the requester repository.
+
+Apply mode requires a Git repository, a clean requester worktree at execution and promotion, and a real Codex SDK backend.
 
 For apply mode, `@openai/codex-sdk` must be resolvable from the installed DevCrew package. Published DevCrew packages declare it as an optional dependency, which npm installs by default. If `devcrew doctor` reports it as missing, reinstall DevCrew with optional dependencies enabled:
 
@@ -62,7 +70,7 @@ npm install -g @shenlee/devcrew --include=optional
 
 ## Marketplace smoke test
 
-After publishing the npm package version referenced by the plugin, run the real 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:
 
 ```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.1` 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.3` wrapper so the MCP service is locked to the published package version.
 
 ## 4. Run A Workflow