@shenlee/devcrew 0.1.2 → 0.1.4

package/README.md

@@ -12,13 +12,14 @@ The first release is intentionally local-first. DevCrew stores workflow state an
 
 - Gated phases for requirements, architecture, implementation planning, and test reporting.
 - Two workflow modes: `feature` for existing repositories and `greenfield` for new products.
-- Safe execution modes: `plan` is the default; `apply` must be explicit. Implementation planning stays read-only, while implementation and testing run in a DevCrew-owned Git worktree.
+- Safe execution modes: `plan` is the default; `apply` must be explicit. Apply defaults to `interactive-host`, which pauses for the host-native agent in a DevCrew-owned Git worktree; explicit headless policies use separately declared SDK permissions.
 - Host-preferred backend selection: Codex runs default to Codex, Claude Code runs default to Claude.
 - Orchestrated role execution: `devcrew_start` runs the PM role, and `devcrew_continue` runs the next phase role before opening the gate.
 - Implementation review artifact: isolated execution records changed files, a binary-capable diff, lint evidence, and architecture compliance notes; testing refreshes the reviewed diff before promotion.
+- Structured architecture review: execution must receive an architect decision of `approved` or `changes_required`; required changes block testing.
 - Repository artifacts in `.devcrew/runs/<run-id>/state.json` and `docs/devcrew/<run-id>/`.
 - Standards discovery from `.devcrew/standards.md`, `AGENTS.md`, `CLAUDE.md`, README, and common project manifests.
-- MCP tools: `devcrew_start`, `devcrew_status`, `devcrew_answer`, `devcrew_approve`, `devcrew_reject`, `devcrew_continue`, and `devcrew_artifact`.
+- MCP tools: `devcrew_start`, `devcrew_status`, `devcrew_answer`, `devcrew_approve`, `devcrew_reject`, `devcrew_continue`, `devcrew_complete_execution`, `devcrew_waive_verification`, and `devcrew_artifact`.
 - Codex and Claude Code plugin scaffolds generated by `devcrew init`.
 
 ## Install As A Codex Plugin
@@ -34,7 +35,7 @@ Restart Codex, open the plugin directory, choose the DevCrew marketplace, and in
 The plugin starts the DevCrew MCP server with:
 
 ```bash
-npm exec --silent --yes --package=@shenlee/devcrew@0.1.2 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
+npm exec --silent --yes --package=@shenlee/devcrew@0.1.4 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
 ```
 
 The plugin locks the MCP server to the published npm package version, so users do not need to clone the source or build TypeScript at install time. You only need Node.js and network access the first time Codex starts the MCP server.
@@ -94,12 +95,13 @@ requirements approval
 -> architecture approval
 -> implementation plan approval
 -> isolated execution
+-> architecture review approval
 -> isolated testing
 -> testing approval
 -> patch promotion to requester repository
 ```
 
-Apply requires a Git repository, a real Codex or Claude SDK backend, and a clean requester worktree when isolated execution starts and when the patch is promoted. After approving the implementation plan, call `devcrew_continue` once for isolated execution and again for isolated testing. The requester repository is unchanged until the testing gate is approved. Rejecting testing and answering the feedback returns the same isolated workspace to `execution` without changing the requester repository.
+Apply requires a Git repository and a clean requester worktree when isolated execution starts and when the patch is promoted. The default `interactive-host` policy does not start a nested SDK: after each `devcrew_continue`, it waits at `awaiting_execution` for the host-native agent to work in the indicated isolated worktree. Call `devcrew_complete_execution` after implementation, and again after testing with command, exit-code, and output evidence. Explicit `headless-restricted` and `headless-unattended` policies instead use DevCrew-managed SDK permissions; they do not inherit the current host approval session. The requester repository is unchanged until the testing gate is approved. Failed verification moves the run to `awaiting_input` and cannot be promoted unless `devcrew_waive_verification` records an explicit risk reason. Rejecting testing and answering the feedback returns the same isolated workspace to `execution` without changing the requester repository.
 
 DevCrew auto-discovers verification commands from common project manifests. The current rules prefer `package.json` scripts (`validate`, then `test`, then `typecheck`/`lint`), then fall back to `go test ./...`, `cargo test`, or `python -m pytest` when matching manifests are present.
 
@@ -112,12 +114,18 @@ You can override discovery with explicit commands in `.devcrew/config.json`:
   "executionMode": "plan",
   "verifyCommands": ["npm run validate"],
   "workflow": {
-    "gates": ["requirements", "architecture", "implementation", "testing"],
+    "gates": ["requirements", "architecture", "implementation", "implementation-review", "testing"],
     "artifactDirectory": "docs/devcrew"
   }
 }
 ```
 
+`workflow.gates` controls only whether the requester must manually approve the
+`requirements`, `architecture`, and `implementation` artifacts. Omitting one
+of those names still runs its role and writes its artifact, then advances to the
+next phase automatically. `implementation-review` and `testing` are mandatory
+safety gates and are always enabled, even when omitted from the configuration.
+
 ## Development
 
 ```bash
@@ -127,13 +135,13 @@ npm run validate
 npm pack --dry-run
 ```
 
-The SDK adapters use deterministic local fallback output when Codex or Claude SDK packages are not installed. This keeps local tests reliable while preserving the adapter boundary for real host integration. In `apply` mode, DevCrew still inherits the host sandbox and approval boundaries.
+The SDK adapters use deterministic local fallback output when Codex or Claude SDK packages are not installed. This keeps local tests reliable while preserving the adapter boundary for real host integration. Nested SDK apply runs use the recorded DevCrew headless policy; they never inherit the current host sandbox or approval session.
 
 For published installs, the host SDK packages are pinned optional dependencies so the version-locked `npm exec --package=@shenlee/devcrew@<version>` wrapper can resolve them from the DevCrew package itself. Plan mode can still fall back to deterministic artifacts, but apply mode fails with a clear SDK resolution error if the selected host SDK is unavailable.
 
 Public npm publishing is handled by the `npm publish` GitHub Actions workflow. It runs validation, checks the package with `npm pack --dry-run`, and publishes with npm provenance when a GitHub Release is published or the workflow is manually dispatched with `NPM_TOKEN` configured.
 
-After publishing `@shenlee/devcrew@0.1.2`, run the real marketplace smoke test. This is a post-publication check because the plugin is version-locked to the npm package:
+After publishing the version locked by the plugin, run the real marketplace smoke test. This is a post-publication check because the plugin is version-locked to the npm package:
 
 ```bash
 npm run smoke:codex-plugin

package/README.zh-CN.md

@@ -12,13 +12,14 @@ DevCrew 是一个面向 Codex、Claude Code 等编程 Agent 的本地工作流
 
 - 内置阶段门禁：需求确认、架构确认、实现计划确认、测试报告确认。
 - 支持两种工作流：`feature` 用于已有项目功能开发，`greenfield` 用于从零开始的新产品。
-- 支持安全执行模式：默认是 `plan`，`apply` 必须显式开启。实现计划阶段始终只读，真正的实现和测试在 DevCrew 管理的 Git worktree 中隔离执行。
+- 支持安全执行模式：默认是 `plan`，`apply` 必须显式开启。apply 默认使用 `interactive-host`，在 DevCrew 管理的 Git worktree 中暂停并交给宿主原生 agent 执行；headless 策略使用单独声明的 SDK 权限。
 - 默认按当前宿主选择后端：在 Codex 中优先使用 Codex，在 Claude Code 中优先使用 Claude。
 - 已接入角色编排：`devcrew_start` 会先运行 PM 角色，`devcrew_continue` 会运行下一阶段角色，然后再打开阶段门禁。
 - 实现评审产物：隔离执行会记录 changed files、支持二进制的 diff、lint 证据和架构符合性说明；测试结束后会重新生成评审 diff，再等待晋升。
+- 架构复审结果结构化：执行后架构师必须给出 `approved` 或 `changes_required`；需要修改时会阻断 testing。
 - 运行状态写入 `.devcrew/runs/<run-id>/state.json`，评审产物写入 `docs/devcrew/<run-id>/`。
 - 自动发现项目规范：`.devcrew/standards.md`、`AGENTS.md`、`CLAUDE.md`、README 以及常见项目配置文件。
-- 提供 MCP 工具：`devcrew_start`、`devcrew_status`、`devcrew_answer`、`devcrew_approve`、`devcrew_reject`、`devcrew_continue`、`devcrew_artifact`。
+- 提供 MCP 工具：`devcrew_start`、`devcrew_status`、`devcrew_answer`、`devcrew_approve`、`devcrew_reject`、`devcrew_continue`、`devcrew_complete_execution`、`devcrew_waive_verification`、`devcrew_artifact`。
 - 可通过 `devcrew init` 生成 Codex 和 Claude Code 插件骨架。
 
 ## 作为 Codex 插件安装
@@ -34,7 +35,7 @@ codex plugin marketplace add lishen802/devcrew
 插件会用下面的命令启动 DevCrew MCP 服务：
 
 ```bash
-npm exec --silent --yes --package=@shenlee/devcrew@0.1.2 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
+npm exec --silent --yes --package=@shenlee/devcrew@0.1.4 -- node -e "<DevCrew CLI wrapper>" -- serve --stdio
 ```
 
 插件会锁定到已发布的 npm 包版本，因此用户不需要克隆源码，也不需要在安装时编译 TypeScript；只需要本机有 Node.js，并且 Codex 第一次启动 MCP 服务时可以访问网络。
@@ -108,12 +109,13 @@ apply 模式的固定顺序是：
 -> 架构确认
 -> 实现计划确认
 -> 隔离执行
+-> 架构审查确认
 -> 隔离测试
 -> 测试报告确认
 -> 将补丁晋升到需求方仓库
 ```
 
-apply 模式要求项目是 Git 仓库、使用真实的 Codex 或 Claude SDK 后端，并且在开始隔离执行和最终晋升补丁时，需求方工作树都必须保持干净。实现计划审批后，需要额外调用一次 `devcrew_continue` 完成隔离执行，再调用一次进入隔离测试。测试门禁批准前，需求方仓库不会出现实现改动；如果驳回测试并提交反馈答案，流程会回到同一个隔离工作树的 `execution` 阶段，不会修改需求方仓库。
+apply 模式要求项目是 Git 仓库，并且在开始隔离执行和最终晋升补丁时，需求方工作树都必须保持干净。默认的 `interactive-host` 不会启动嵌套 SDK：每次 `devcrew_continue` 后会在 `awaiting_execution` 等待宿主原生 agent 在指定隔离 worktree 中工作；实现完成后调用 `devcrew_complete_execution`，测试完成时还要提交命令、退出码和输出证据。显式的 `headless-restricted` 与 `headless-unattended` 才使用 DevCrew 管理的 SDK 权限，它们不会继承当前宿主的审批会话。测试门禁批准前，需求方仓库不会出现实现改动；验证失败会进入 `awaiting_input`，只有通过 `devcrew_waive_verification` 记录明确风险原因后才可重新打开审批。驳回测试并提交反馈答案会回到同一个隔离工作树的 `execution` 阶段，不会修改需求方仓库。
 
 DevCrew 会自动从常见项目清单中发现验证命令。当前规则会优先读取 `package.json` scripts（`validate`，然后是 `test`，再到 `typecheck`/`lint`），再按项目清单回退到 `go test ./...`、`cargo test` 或 `python -m pytest`。
 
@@ -126,12 +128,15 @@ DevCrew 会自动从常见项目清单中发现验证命令。当前规则会优
   "executionMode": "plan",
   "verifyCommands": ["npm run validate"],
   "workflow": {
-    "gates": ["requirements", "architecture", "implementation", "testing"],
+    "gates": ["requirements", "architecture", "implementation", "implementation-review", "testing"],
     "artifactDirectory": "docs/devcrew"
   }
 }
 ```
 
+`workflow.gates` 只控制是否需要人工审批 `requirements`、`architecture` 和
+`implementation` 产物。省略其中任意项仍会执行相应角色并写入产物，只是不再停下来等待审批，而是自动进入下一阶段。`implementation-review` 与 `testing` 是强制安全门禁：即使配置中省略，也始终启用。
+
 ## 开发命令
 
 ```bash
@@ -141,13 +146,13 @@ npm run validate
 npm pack --dry-run
 ```
 
-当前适配器在未安装 Codex SDK 或 Claude SDK 时会使用确定性的本地 fallback 输出。这样可以保证测试和演示稳定，同时保留接入真实宿主 SDK 的边界。即使在 `apply` 模式下，DevCrew 仍然继承宿主的 sandbox、审批和工具权限。
+当前适配器在未安装 Codex SDK 或 Claude SDK 时会使用确定性的本地 fallback 输出。这样可以保证测试和演示稳定，同时保留接入真实宿主 SDK 的边界。嵌套 SDK 的 apply 运行使用记录在状态中的 DevCrew headless 策略，不会继承当前宿主的 sandbox、审批或工具会话。
 
 对于发布安装，宿主 SDK 包会作为精确锁定的 optional dependencies 随 DevCrew 一起安装，因此锁定版本的 `npm exec --package=@shenlee/devcrew@<version>` wrapper 可以从 DevCrew 包自身解析这些 SDK。plan 模式仍允许 deterministic fallback；但 apply 模式在选定宿主 SDK 不可用时会直接失败，并给出明确的 SDK 解析错误。
 
 公开 npm 发布由 `npm publish` GitHub Actions 工作流处理。发布 GitHub Release 或手动触发 workflow 时，它会先运行验证，再执行 `npm pack --dry-run` 检查包内容，最后在配置 `NPM_TOKEN` 后使用 npm provenance 发布公开包。
 
-发布 `@shenlee/devcrew@0.1.2` 后，再运行真实 marketplace smoke test。由于插件锁定了 npm 版本，这是发布后的检查：
+发布插件锁定的 npm 版本后，再运行真实 marketplace smoke test。由于插件锁定了 npm 版本，这是发布后的检查：
 
 ```bash
 npm run smoke:codex-plugin

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

@@ -41,6 +41,162 @@ export function assertRoleSections(role, markdown) {
         throw new RoleOutputValidationError(role, missingSections);
     }
 }
+export function extractOpenQuestions(markdown) {
+    const match = /^##\s+Open Questions\s*$(.*?)(?=^##\s|(?![\s\S]))/ims.exec(markdown);
+    if (!match) {
+        return [];
+    }
+    const questions = [];
+    for (const line of match[1].split("\n")) {
+        const question = /^\s*[-*]\s+(.+?)\s*$/u.exec(line)?.[1]?.trim();
+        if (question && !/^(none|n\/a|no open questions)\.?$/i.test(question)) {
+            questions.push(question);
+        }
+    }
+    return questions;
+}
+export function extractArchitectureReviewDecision(markdown) {
+    const section = /^##\s+Review Decision\s*$(.*?)(?=^##\s|(?![\s\S]))/ims.exec(markdown)?.[1] ?? "";
+    const match = /^Decision:\s*(approved|changes_required)\s*$/im.exec(section);
+    return match?.[1];
+}
+const STRUCTURED_RESULT_MARKER = "<!-- devcrew-role-result -->";
+const STRUCTURED_RESULT_BLOCK = /<!--\s*devcrew-role-result\s*-->\s*```json\s*\r?\n([\s\S]*?)\r?\n```/g;
+function structuredOutputError(role, reason) {
+    return new RoleOutputValidationError(role, [`marked structured role result: ${reason}`]);
+}
+function asRecord(value, role, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw structuredOutputError(role, `${field} must be an object`);
+    }
+    return value;
+}
+function asNonEmptyString(value, role, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw structuredOutputError(role, `${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function asStringArray(value, role, field) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+        throw structuredOutputError(role, `${field} must be an array of non-empty strings`);
+    }
+    return value.map((entry) => entry.trim());
+}
+function asEvidence(value, role) {
+    if (!Array.isArray(value)) {
+        throw structuredOutputError(role, "evidence must be an array");
+    }
+    return value.map((entry, index) => {
+        const evidence = asRecord(entry, role, `evidence[${index}]`);
+        const command = asNonEmptyString(evidence.command, role, `evidence[${index}].command`);
+        if (!Number.isInteger(evidence.exitCode)) {
+            throw structuredOutputError(role, `evidence[${index}].exitCode must be an integer`);
+        }
+        if (evidence.output !== undefined && typeof evidence.output !== "string") {
+            throw structuredOutputError(role, `evidence[${index}].output must be a string`);
+        }
+        return { command, exitCode: evidence.exitCode, output: evidence.output };
+    });
+}
+function asQuestions(value, role) {
+    if (!Array.isArray(value)) {
+        throw structuredOutputError(role, "questions must be an array");
+    }
+    const ids = new Set();
+    return value.map((entry, index) => {
+        const question = asRecord(entry, role, `questions[${index}]`);
+        const id = asNonEmptyString(question.id, role, `questions[${index}].id`);
+        if (ids.has(id)) {
+            throw structuredOutputError(role, `questions[${index}].id must be unique`);
+        }
+        ids.add(id);
+        const prompt = asNonEmptyString(question.prompt, role, `questions[${index}].prompt`);
+        if (question.context !== undefined && typeof question.context !== "string") {
+            throw structuredOutputError(role, `questions[${index}].context must be a string`);
+        }
+        return { id, prompt, context: question.context };
+    });
+}
+function parseStructuredRoleData(role, phase, raw) {
+    const value = asRecord(raw, role, "result");
+    if (value.schemaVersion !== 1) {
+        throw structuredOutputError(role, "schemaVersion must be 1");
+    }
+    if (value.role !== role) {
+        throw structuredOutputError(role, `role must be ${role}`);
+    }
+    const data = {
+        schemaVersion: 1,
+        role,
+        summary: asNonEmptyString(value.summary, role, "summary"),
+        risks: asStringArray(value.risks, role, "risks"),
+        evidence: asEvidence(value.evidence, role),
+    };
+    if (role === "pm") {
+        data.questions = asQuestions(value.questions, role);
+    }
+    else if (role === "architect") {
+        data.decisions = asStringArray(value.decisions, role, "decisions");
+        if (phase === "review") {
+            if (value.reviewDecision !== "approved" && value.reviewDecision !== "changes_required") {
+                throw structuredOutputError(role, "reviewDecision must be approved or changes_required");
+            }
+            data.reviewDecision = value.reviewDecision;
+        }
+    }
+    else if (role === "implementer") {
+        data.changedFiles = asStringArray(value.changedFiles, role, "changedFiles");
+    }
+    else {
+        if (!Array.isArray(value.testCases)) {
+            throw structuredOutputError(role, "testCases must be an array");
+        }
+        data.testCases = value.testCases.map((entry, index) => {
+            const testCase = asRecord(entry, role, `testCases[${index}]`);
+            const type = testCase.type;
+            if (type !== "happy" && type !== "edge" && type !== "failure" && type !== "regression") {
+                throw structuredOutputError(role, `testCases[${index}].type is invalid`);
+            }
+            return {
+                id: asNonEmptyString(testCase.id, role, `testCases[${index}].id`),
+                scenario: asNonEmptyString(testCase.scenario, role, `testCases[${index}].scenario`),
+                type,
+                expected: asNonEmptyString(testCase.expected, role, `testCases[${index}].expected`),
+            };
+        });
+    }
+    return data;
+}
+export function parseRoleResultOutput(role, phase, output) {
+    if (!output.includes(STRUCTURED_RESULT_MARKER)) {
+        return {
+            format: "legacy",
+            markdown: output,
+            questions: role === "pm" ? extractOpenQuestions(output) : undefined,
+            reviewDecision: phase === "review" ? extractArchitectureReviewDecision(output) : undefined,
+        };
+    }
+    const blocks = [...output.matchAll(STRUCTURED_RESULT_BLOCK)];
+    if (blocks.length !== 1) {
+        throw structuredOutputError(role, blocks.length === 0 ? "must use a JSON fenced block" : "must appear exactly once");
+    }
+    let raw;
+    try {
+        raw = JSON.parse(blocks[0]?.[1] ?? "");
+    }
+    catch {
+        throw structuredOutputError(role, "contains invalid JSON");
+    }
+    const structured = parseStructuredRoleData(role, phase, raw);
+    return {
+        format: "structured",
+        markdown: output.slice(0, blocks[0]?.index).concat(output.slice((blocks[0]?.index ?? 0) + (blocks[0]?.[0].length ?? 0))).trim(),
+        structured,
+        questions: structured.questions?.map((question) => question.prompt),
+        reviewDecision: structured.reviewDecision,
+    };
+}
 export function renderRolePrompt(input) {
     const executionMode = input.executionMode ?? "plan";
     const answers = input.answers ?? [];
@@ -76,7 +232,10 @@ export function renderRolePrompt(input) {
             ? "You may run validation commands needed for the approved scope and report exact evidence."
             : "You may modify repository files needed for the approved scope and report changed files."
         : "Do not modify repository files. Return only the Markdown document content for the artifact.";
-    lines.push("", "Instructions:", `Act as the DevCrew ${input.role} role and produce a complete, well-structured Markdown document for the ${input.phase} phase.`, "Keep scope aligned with the approved gates and inherited host permissions.", permissionInstruction, "", "Required Sections:", ...roleGuidance(input.role));
+    lines.push("", "Instructions:", `Act as the DevCrew ${input.role} role and produce a complete, well-structured Markdown document for the ${input.phase} phase.`, "Keep scope aligned with the approved gates and the selected DevCrew execution policy.", permissionInstruction, "", "Return this protocol block first:", STRUCTURED_RESULT_MARKER, "```json", `{\"schemaVersion\":1,\"role\":\"${input.role}\",\"summary\":\"...\",\"risks\":[],\"evidence\":[]}`, "```", "Then return the required Markdown H2 sections. Do not include a second marked result block.", "", "Required Sections:", ...roleGuidance(input.role));
+    if (input.phase === "review") {
+        lines.push("", "Architecture Review Decision:", "Add an exact H2 `## Review Decision` section containing exactly `Decision: approved` or `Decision: changes_required`.", "Use `changes_required` for any mismatch with the approved architecture; summarize the blocking mismatch in that section.");
+    }
     return lines.join("\n");
 }
 function titleForPhase(phase) {
@@ -85,6 +244,7 @@ function titleForPhase(phase) {
         architecture: "Architecture",
         implementation: "Implementation Plan",
         execution: "Implementation Review",
+        review: "Architecture Review",
         testing: "Test Report",
         acceptance: "Acceptance",
         complete: "Acceptance",
@@ -155,24 +315,45 @@ export function extractClaudeResult(message) {
     }
     return text;
 }
-function roleCanApply(input) {
+function isApplyPhase(input) {
     return input.executionMode === "apply" && (input.phase === "execution" || input.phase === "testing");
 }
-function codexSandboxForRole(input) {
-    return roleCanApply(input) ? "workspace-write" : "read-only";
+function effectiveExecutionPolicy(input) {
+    return input.executionPolicy ?? "interactive-host";
+}
+function roleCanApply(input) {
+    return isApplyPhase(input) && effectiveExecutionPolicy(input) !== "interactive-host";
+}
+function codexOptionsForRole(input) {
+    if (!roleCanApply(input)) {
+        return buildCodexThreadOptions(input.cwd);
+    }
+    const executionPolicy = effectiveExecutionPolicy(input);
+    return {
+        ...buildCodexThreadOptions(input.cwd, "workspace-write"),
+        approvalPolicy: executionPolicy === "headless-unattended" ? "never" : "on-request",
+        networkAccessEnabled: false,
+    };
 }
 function claudeOptionsForRole(input) {
     if (!roleCanApply(input)) {
         return buildClaudeOptions(input.cwd);
     }
-    const allowedTools = input.role === "implementer" ? ["Read", "Grep", "Glob", "Edit", "Write", "Bash"] : ["Read", "Grep", "Glob", "Bash"];
-    return buildClaudeOptions(input.cwd, "acceptEdits", allowedTools);
+    if (effectiveExecutionPolicy(input) === "headless-unattended") {
+        return {
+            cwd: input.cwd,
+            permissionMode: "bypassPermissions",
+            allowDangerouslySkipPermissions: true,
+        };
+    }
+    const allowedTools = input.role === "implementer" ? ["Read", "Grep", "Glob", "Edit", "Write"] : ["Read", "Grep", "Glob"];
+    return buildClaudeOptions(input.cwd, "dontAsk", allowedTools);
 }
 async function runWithCodex(input, prompt, loadModule) {
     const mod = await loadModule(HOST_SDK_PACKAGES.codex);
     const CodexClass = mod.Codex;
     const codex = new CodexClass();
-    const thread = codex.startThread(buildCodexThreadOptions(input.cwd, codexSandboxForRole(input)));
+    const thread = codex.startThread(codexOptionsForRole(input));
     const turn = await thread.run(prompt);
     return extractCodexText(turn);
 }
@@ -194,12 +375,16 @@ function fallbackResult(role, backend, title, summary) {
         summary,
         markdown: `# ${title}\n\n${summary}\n`,
         usedFallback: true,
+        format: "legacy",
     };
 }
 function shouldFailOnSdkError(input) {
     return input.executionMode === "apply" && input.backend !== "local";
 }
 export async function runRole(input, deps = {}) {
+    if (isApplyPhase(input) && effectiveExecutionPolicy(input) === "interactive-host") {
+        throw new Error("DevCrew interactive-host execution must be performed by the host, not a nested SDK");
+    }
     const loadModule = deps.loadModule ?? importOptional;
     const title = titleForPhase(input.phase);
     const prompt = renderRolePrompt(input);
@@ -210,13 +395,22 @@ export async function runRole(input, deps = {}) {
         const markdown = input.backend === "codex"
             ? await runWithCodex(input, prompt, loadModule)
             : await runWithClaude(input, prompt, loadModule);
-        assertRoleSections(input.role, markdown);
+        const parsed = parseRoleResultOutput(input.role, input.phase, markdown);
+        assertRoleSections(input.role, parsed.markdown);
+        const reviewDecision = parsed.reviewDecision;
+        if (input.phase === "review" && !reviewDecision) {
+            throw new RoleOutputValidationError(input.role, ["Review Decision"]);
+        }
         return {
             role: input.role,
             backend: input.backend,
-            summary: `${input.role} produced ${title} using the ${input.backend} SDK.`,
-            markdown,
+            summary: parsed.structured?.summary ?? `${input.role} produced ${title} using the ${input.backend} SDK.`,
+            markdown: parsed.markdown,
             usedFallback: false,
+            format: parsed.format,
+            structured: parsed.structured,
+            questions: parsed.questions,
+            reviewDecision,
         };
     }
     catch (error) {

package/dist/packages/core/src/active-run.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, unlink, writeFile } from "node:fs/promises";
 import { activeRunPath, ensureProjectDirectories } from "./paths.js";
 export async function setActiveRun(cwd, runId) {
     await ensureProjectDirectories(cwd);
@@ -22,3 +22,15 @@ export async function getActiveRunId(cwd) {
     }
     throw new Error("No active DevCrew run. Pass runId or start a workflow first.");
 }
+export async function clearActiveRunIfMatches(cwd, runId) {
+    try {
+        if ((await getActiveRunId(cwd)) !== runId) {
+            return false;
+        }
+        await unlink(activeRunPath(cwd));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/packages/core/src/artifacts.js

@@ -7,6 +7,7 @@ function headingForArtifact(name) {
         architecture: "Architecture",
         "implementation-plan": "Implementation Plan",
         "implementation-review": "Implementation Review",
+        "architecture-review": "Architecture Review",
         "test-report": "Test Report",
         acceptance: "Acceptance",
     }[name];
@@ -47,6 +48,12 @@ function verificationBlock(state) {
         .map((result) => `### ${result.command}\n\nExit Code: ${result.exitCode}\n\nOutput:\n\n\`\`\`text\n${result.output || "(no output)"}\n\`\`\``)
         .join("\n\n");
 }
+function verificationWaiverBlock(state) {
+    if (!state.verificationWaiver) {
+        return "No verification waiver has been recorded.";
+    }
+    return `Reason: ${state.verificationWaiver.reason}\nRecorded At: ${state.verificationWaiver.createdAt}`;
+}
 function lintResultsBlock(state) {
     if (state.lintResults.length === 0) {
         return "No lint or format commands have been executed.";
@@ -79,7 +86,7 @@ function architectureComplianceStatus(state) {
 }
 export function renderArtifact(name, state) {
     const title = headingForArtifact(name);
-    const common = `# ${title}\n\nRun: ${state.runId}\nMode: ${state.mode}\nExecution Mode: ${state.executionMode}\nHost: ${state.host}\nBackend: ${state.backend}\nRequest: ${state.request}\n\n`;
+    const common = `# ${title}\n\nRun: ${state.runId}\nMode: ${state.mode}\nExecution Mode: ${state.executionMode}\nExecution Policy: ${state.executionPolicy}\nVerification Status: ${state.verificationStatus}\nHost: ${state.host}\nBackend: ${state.backend}\nRequest: ${state.request}\n\n`;
     if (name === "requirements") {
         return `${common}## Functional Scope\n\n### In Scope\n\n- Capture the requested outcome in user-facing terms.\n\n### Out of Scope\n\n- Make explicit what is intentionally excluded before implementation.\n\n## Users and Scenarios\n\n- Identify the primary users and their key scenarios.\n\n## Acceptance Criteria\n\n- Express each criterion as Given / When / Then so it stays testable.\n\n## Priorities\n\n- Classify each requirement as Must / Should / Could / Won't (MoSCoW).\n\n## Current Requester Answers\n\n${answerBlock(state)}\n\n## Discovered Standards\n\n${standardsExcerpt(state)}\n\n## Open Questions\n\n- Confirm primary users and success criteria.\n- Confirm scope boundaries and non-goals.\n- Confirm deployment or environment constraints.\n\n## Rejection Feedback\n\n${feedbackBlock(state)}\n`;
     }
@@ -92,15 +99,18 @@ export function renderArtifact(name, state) {
     if (name === "implementation-review") {
         return `${common}${workflowContextBlock(state)}\n## Implementation Diff Review\n\n### Changed Files\n\n${changedFilesBlock(state)}\n\n### Captured Diff\n\n${implementationDiffBlock(state)}\n\n## Lint Results\n\n${lintResultsBlock(state)}\n\n## Architecture Compliance Inputs\n\n${architectureComplianceInputsBlock(state)}\n\n## Architecture Compliance Review\n\nStatus: ${architectureComplianceStatus(state)}\n\n- Confirm changed files map back to the approved architecture artifact.\n- Confirm public interfaces, data flow, and deployment assumptions remain consistent with the architecture.\n- Confirm implementation scope does not include unapproved requirements or unrelated refactors.\n- Record any mismatch as rejection feedback before approving the implementation gate.\n`;
     }
+    if (name === "architecture-review") {
+        return `${common}${workflowContextBlock(state)}\n## Technical Decisions\n\nReview the captured implementation diff against the approved architecture. State whether the implementation keeps its approved interfaces, data flow, deployment, and rollback assumptions.\n\n## Interface Contracts\n\nIdentify each changed public interface and whether it conforms to the approved architecture artifact.\n\n## Data Flow and Deployment\n\nReview the implementation diff for data-flow, deployment, migration, and rollback deviations.\n\n## Architecture Review Checklist\n\n- Review the captured implementation diff and changed-files list.\n- Trace each material change to an approved architectural decision.\n- Record any mismatch as rejection feedback before the testing phase begins.\n`;
+    }
     if (name === "test-report") {
-        return `${common}${workflowContextBlock(state)}\n## Test Cases\n\nEnumerate cases as a table covering happy, edge, failure, and regression paths.\n\n| ID | Scenario | Type | Expected |\n| --- | --- | --- | --- |\n| TC-1 | Primary success path | happy | Behaves as specified |\n| TC-2 | Boundary input | edge | Handled without error |\n| TC-3 | Invalid input | failure | Fails safely with clear error |\n\n## Coverage\n\nRun the coverage command and report the coverage summary plus any gaps. Evidence is captured under Acceptance Evidence.\n\n## Acceptance Evidence\n\n${verificationBlock(state)}\n\n## Known Risks\n\n- Host SDK availability may vary by user environment.\n- Agent permissions are inherited from the host and must be reviewed there.\n`;
+        return `${common}${workflowContextBlock(state)}\n## Test Cases\n\nEnumerate cases as a table covering happy, edge, failure, and regression paths.\n\n| ID | Scenario | Type | Expected |\n| --- | --- | --- | --- |\n| TC-1 | Primary success path | happy | Behaves as specified |\n| TC-2 | Boundary input | edge | Handled without error |\n| TC-3 | Invalid input | failure | Fails safely with clear error |\n\n## Coverage\n\nRun the coverage command and report the coverage summary plus any gaps. Evidence is captured under Acceptance Evidence.\n\n## Acceptance Evidence\n\n${verificationBlock(state)}\n\n## Verification Waiver\n\n${verificationWaiverBlock(state)}\n\n## Known Risks\n\n- Headless SDK capabilities are governed by the recorded DevCrew execution policy.\n- Interactive-host work is performed through the host's native agent controls.\n`;
     }
-    return `${common}${workflowContextBlock(state)}\n## Acceptance Summary\n\nThe requester approved requirements, architecture, implementation planning, and test reporting gates for this run.\n\n## Approved Gates\n\n${Object.entries(state.gates)
+    return `${common}${workflowContextBlock(state)}\n## Acceptance Summary\n\nThe requester approved requirements, architecture, implementation planning, and test reporting gates for this run.\n\n## Verification Waiver\n\n${verificationWaiverBlock(state)}\n\n## Approved Gates\n\n${Object.entries(state.gates)
         .map(([gate, status]) => `- ${gate}: ${status}`)
         .join("\n")}\n`;
 }
 export async function writeArtifact(name, state) {
-    const path = artifactPath(state.cwd, state.runId, name);
+    const path = artifactPath(state.cwd, state.runId, name, state.artifactDirectory);
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, renderArtifact(name, state), "utf8");
     return path;

package/dist/packages/core/src/config.js

@@ -1,5 +1,7 @@
 import { access, readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { configPath, ensureProjectDirectories } from "./paths.js";
+import { BACKENDS, EXECUTION_MODES, GATES } from "./types.js";
 export const DEFAULT_CONFIG = {
     version: 1,
     defaultBackend: "host-preferred",
@@ -8,7 +10,7 @@ export const DEFAULT_CONFIG = {
     lintCommands: [],
     coverageCommands: [],
     workflow: {
-        gates: ["requirements", "architecture", "implementation", "testing"],
+        gates: ["requirements", "architecture", "implementation", "implementation-review", "testing"],
         artifactDirectory: "docs/devcrew",
     },
 };
@@ -21,6 +23,90 @@ async function exists(path) {
         return false;
     }
 }
+function asRecord(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid .devcrew/config.json: ${field} must be an object`);
+    }
+    return value;
+}
+function assertKnownKeys(value, field, allowed) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            throw new Error(`Invalid .devcrew/config.json: ${field} has unknown key ${key}`);
+        }
+    }
+}
+function requiredString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`Invalid .devcrew/config.json: ${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function parseCommandList(value, field) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`Invalid .devcrew/config.json: ${field} must be an array`);
+    }
+    return value.map((entry, index) => requiredString(entry, `${field}[${index}]`));
+}
+function parseGates(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("Invalid .devcrew/config.json: workflow.gates must be an array");
+    }
+    const gates = [];
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "string" || !GATES.includes(entry)) {
+            throw new Error(`Invalid .devcrew/config.json: workflow.gates[${index}] must be a known gate, received ${String(entry)}`);
+        }
+        if (gates.includes(entry)) {
+            throw new Error(`Invalid .devcrew/config.json: workflow.gates contains duplicate ${entry}`);
+        }
+        gates.push(entry);
+    }
+    return gates;
+}
+function parseArtifactDirectory(cwd, value) {
+    const artifactDirectory = requiredString(value, "workflow.artifactDirectory");
+    if (isAbsolute(artifactDirectory)) {
+        throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must be relative to the repository");
+    }
+    const projectRoot = resolve(cwd);
+    const target = resolve(projectRoot, artifactDirectory);
+    const fromProject = relative(projectRoot, target);
+    if (fromProject === ".." || fromProject.startsWith(`..${sep}`) || isAbsolute(fromProject)) {
+        throw new Error("Invalid .devcrew/config.json: workflow.artifactDirectory must resolve inside the repository");
+    }
+    return artifactDirectory;
+}
+function parseConfig(cwd, value) {
+    const parsed = asRecord(value, "root");
+    assertKnownKeys(parsed, "root", ["version", "defaultBackend", "executionMode", "verifyCommands", "lintCommands", "coverageCommands", "workflow"]);
+    if (parsed.version !== 1) {
+        throw new Error("Unsupported .devcrew/config.json version");
+    }
+    if (typeof parsed.defaultBackend !== "string" || (parsed.defaultBackend !== "host-preferred" && !BACKENDS.includes(parsed.defaultBackend))) {
+        throw new Error("Invalid .devcrew/config.json: defaultBackend must be host-preferred, codex, claude, or local");
+    }
+    if (typeof parsed.executionMode !== "string" || !EXECUTION_MODES.includes(parsed.executionMode)) {
+        throw new Error("Invalid .devcrew/config.json: executionMode must be plan or apply");
+    }
+    const workflow = asRecord(parsed.workflow, "workflow");
+    assertKnownKeys(workflow, "workflow", ["gates", "artifactDirectory"]);
+    return {
+        version: 1,
+        defaultBackend: parsed.defaultBackend,
+        executionMode: parsed.executionMode,
+        verifyCommands: parseCommandList(parsed.verifyCommands, "verifyCommands"),
+        lintCommands: parseCommandList(parsed.lintCommands, "lintCommands"),
+        coverageCommands: parseCommandList(parsed.coverageCommands, "coverageCommands"),
+        workflow: {
+            gates: parseGates(workflow.gates),
+            artifactDirectory: parseArtifactDirectory(cwd, workflow.artifactDirectory),
+        },
+    };
+}
 export async function ensureConfig(cwd) {
     await ensureProjectDirectories(cwd);
     const path = configPath(cwd);
@@ -32,20 +118,5 @@ export async function ensureConfig(cwd) {
 }
 export async function readConfig(cwd) {
     const raw = await readFile(configPath(cwd), "utf8");
-    const parsed = JSON.parse(raw);
-    if (parsed.version !== 1) {
-        throw new Error("Unsupported .devcrew/config.json version");
-    }
-    return {
-        ...DEFAULT_CONFIG,
-        ...parsed,
-        executionMode: parsed.executionMode ?? "plan",
-        verifyCommands: Array.isArray(parsed.verifyCommands) ? parsed.verifyCommands : [],
-        lintCommands: Array.isArray(parsed.lintCommands) ? parsed.lintCommands : [],
-        coverageCommands: Array.isArray(parsed.coverageCommands) ? parsed.coverageCommands : [],
-        workflow: {
-            ...DEFAULT_CONFIG.workflow,
-            ...parsed.workflow,
-        },
-    };
+    return parseConfig(cwd, JSON.parse(raw));
 }

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

@@ -1,6 +1,7 @@
 export * from "./active-run.js";
 export * from "./artifacts.js";
 export * from "./config.js";
+export * from "./lock.js";
 export * from "./paths.js";
 export * from "./standards.js";
 export * from "./store.js";