@shenlee/devcrew 0.1.1 → 0.1.3

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 explicitly requested before implementer/tester roles can write files or run validation commands.
+- 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: implementation gates include changed files, captured diff, and architecture compliance review notes.
+- 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.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
 ```
 
 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.
@@ -81,12 +82,27 @@ The agent should call `devcrew_start`, show the PM-generated requirements artifa
 
 Plugins set `DEVCREW_HOST` for host detection, so `devcrew_start` can omit `host` unless you want to override it. DevCrew records the latest run as the repository's active run, so follow-up MCP calls can omit `runId`.
 
-By default DevCrew runs in `plan` mode. To allow the implementer/tester phases to make repository changes and run configured verification commands, explicitly request apply mode:
+By default DevCrew runs in `plan` mode. To allow isolated execution to modify files and isolated testing to run configured verification commands, explicitly request apply mode:
 
 ```text
 Use DevCrew in apply mode to implement audit logging for the billing API.
 ```
 
+Apply mode follows this sequence:
+
+```text
+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 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.
 
 You can override discovery with explicit commands in `.devcrew/config.json`:
@@ -98,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
@@ -113,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 the npm version referenced by the Codex plugin, run the real marketplace smoke test:
+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` 时，implementer/tester 阶段才允许写文件或运行验证命令。
+- 支持安全执行模式：默认是 `plan`，`apply` 必须显式开启。apply 默认使用 `interactive-host`，在 DevCrew 管理的 Git worktree 中暂停并交给宿主原生 agent 执行；headless 策略使用单独声明的 SDK 权限。
 - 默认按当前宿主选择后端：在 Codex 中优先使用 Codex，在 Claude Code 中优先使用 Claude。
 - 已接入角色编排：`devcrew_start` 会先运行 PM 角色，`devcrew_continue` 会运行下一阶段角色，然后再打开阶段门禁。
-- 实现评审产物：implementation gate 会附带 changed files、捕获的 diff 和架构符合性审查说明。
+- 实现评审产物：隔离执行会记录 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.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
 ```
 
 插件会锁定到已发布的 npm 包版本，因此用户不需要克隆源码，也不需要在安装时编译 TypeScript；只需要本机有 Node.js，并且 Codex 第一次启动 MCP 服务时可以访问网络。
@@ -95,12 +96,27 @@ devcrew serve --stdio
 
 插件会设置 `DEVCREW_HOST` 用于宿主识别，因此 `devcrew_start` 可以省略 `host`，除非你需要显式覆盖。DevCrew 会把最新 run 记录为当前仓库的 active run，后续 MCP 调用可以省略 `runId`。
 
-默认情况下 DevCrew 使用安全的 `plan` 模式。如果你希望 implementer/tester 阶段真正修改仓库并运行配置好的验证命令，需要明确要求 apply 模式：
+默认情况下 DevCrew 使用安全的 `plan` 模式。如果你希望隔离执行阶段真正修改文件，并在隔离测试阶段运行配置好的验证命令，需要明确要求 apply 模式：
 
 ```text
 使用 DevCrew apply 模式帮我实现 billing API 的审计日志功能。
 ```
 
+apply 模式的固定顺序是：
+
+```text
+需求确认
+-> 架构确认
+-> 实现计划确认
+-> 隔离执行
+-> 架构审查确认
+-> 隔离测试
+-> 测试报告确认
+-> 将补丁晋升到需求方仓库
+```
+
+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`。
 
 你也可以在 `.devcrew/config.json` 中显式覆盖：
@@ -112,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
@@ -127,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 发布公开包。
 
-当 Codex 插件引用的 npm 版本发布完成后，运行真实 marketplace smoke test：
+发布插件锁定的 npm 版本后，再运行真实 marketplace smoke test。由于插件锁定了 npm 版本，这是发布后的检查：
 
 ```bash
 npm run smoke:codex-plugin

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

@@ -41,6 +41,25 @@ 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];
+}
 export function renderRolePrompt(input) {
     const executionMode = input.executionMode ?? "plan";
     const answers = input.answers ?? [];
@@ -70,13 +89,16 @@ export function renderRolePrompt(input) {
             lines.push("", `### ${name}`, content.trim());
         }
     }
-    const canApply = executionMode === "apply" && (input.role === "implementer" || input.role === "tester");
+    const canApply = roleCanApply({ ...input, executionMode });
     const permissionInstruction = canApply
         ? input.role === "tester"
             ? "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, "", "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) {
@@ -84,6 +106,8 @@ function titleForPhase(phase) {
         requirements: "Requirements",
         architecture: "Architecture",
         implementation: "Implementation Plan",
+        execution: "Implementation Review",
+        review: "Architecture Review",
         testing: "Test Report",
         acceptance: "Acceptance",
         complete: "Acceptance",
@@ -154,24 +178,45 @@ export function extractClaudeResult(message) {
     }
     return text;
 }
+function isApplyPhase(input) {
+    return input.executionMode === "apply" && (input.phase === "execution" || input.phase === "testing");
+}
+function effectiveExecutionPolicy(input) {
+    return input.executionPolicy ?? "interactive-host";
+}
 function roleCanApply(input) {
-    return input.executionMode === "apply" && (input.role === "implementer" || input.role === "tester");
+    return isApplyPhase(input) && effectiveExecutionPolicy(input) !== "interactive-host";
 }
-function codexSandboxForRole(input) {
-    return roleCanApply(input) ? "workspace-write" : "read-only";
+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);
 }
@@ -199,6 +244,9 @@ 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,12 +258,18 @@ export async function runRole(input, deps = {}) {
             ? await runWithCodex(input, prompt, loadModule)
             : await runWithClaude(input, prompt, loadModule);
         assertRoleSections(input.role, markdown);
+        const reviewDecision = input.phase === "review" ? extractArchitectureReviewDecision(markdown) : undefined;
+        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,
             usedFallback: false,
+            questions: input.role === "pm" ? extractOpenQuestions(markdown) : undefined,
+            reviewDecision,
         };
     }
     catch (error) {

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

@@ -8,7 +8,7 @@ export const DEFAULT_CONFIG = {
     lintCommands: [],
     coverageCommands: [],
     workflow: {
-        gates: ["requirements", "architecture", "implementation", "testing"],
+        gates: ["requirements", "architecture", "implementation", "implementation-review", "testing"],
         artifactDirectory: "docs/devcrew",
     },
 };

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

@@ -9,6 +9,9 @@ export function runsDir(cwd) {
 export function runDir(cwd, runId) {
     return join(runsDir(cwd), runId);
 }
+export function executionWorktreePath(cwd, runId) {
+    return join(devcrewDir(cwd), "worktrees", runId);
+}
 export function statePath(cwd, runId) {
     return join(runDir(cwd, runId), "state.json");
 }
@@ -21,22 +24,23 @@ export function activeRunPath(cwd) {
 export function standardsPath(cwd) {
     return join(devcrewDir(cwd), "standards.md");
 }
-export function docsRoot(cwd) {
-    return join(cwd, "docs", "devcrew");
+export function docsRoot(cwd, artifactDirectory = "docs/devcrew") {
+    return join(cwd, artifactDirectory);
 }
-export function docsRunDir(cwd, runId) {
-    return join(docsRoot(cwd), runId);
+export function docsRunDir(cwd, runId, artifactDirectory = "docs/devcrew") {
+    return join(docsRoot(cwd, artifactDirectory), runId);
 }
-export function artifactPath(cwd, runId, artifact) {
+export function artifactPath(cwd, runId, artifact, artifactDirectory = "docs/devcrew") {
     const filenameByArtifact = {
         requirements: "requirements.md",
         architecture: "architecture.md",
         "implementation-plan": "implementation-plan.md",
         "implementation-review": "implementation-review.md",
+        "architecture-review": "architecture-review.md",
         "test-report": "test-report.md",
         acceptance: "acceptance.md",
     };
-    return join(docsRunDir(cwd, runId), filenameByArtifact[artifact]);
+    return join(docsRunDir(cwd, runId, artifactDirectory), filenameByArtifact[artifact]);
 }
 export async function ensureRunDirectories(cwd, runId) {
     await mkdir(runDir(cwd, runId), { recursive: true });

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

@@ -1,6 +1,13 @@
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { ensureRunDirectories, statePath } from "./paths.js";
+import { GATES } from "./types.js";
+function enabledGatesFromState(value) {
+    const configured = Array.isArray(value)
+        ? value.filter((gate) => typeof gate === "string" && GATES.includes(gate))
+        : [...GATES];
+    return [...new Set([...configured, "implementation-review", "testing"])];
+}
 export async function saveState(state) {
     state.updatedAt = new Date().toISOString();
     await ensureRunDirectories(state.cwd, state.runId);
@@ -13,12 +20,41 @@ export async function saveState(state) {
 export async function loadState(cwd, runId) {
     const raw = await readFile(statePath(cwd, runId), "utf8");
     const parsed = JSON.parse(raw);
+    const executionWorkspace = parsed.executionWorkspace;
+    const executionInstruction = parsed.executionInstruction;
+    const verificationWaiver = parsed.verificationWaiver;
     return {
         ...parsed,
         executionMode: parsed.executionMode ?? "plan",
+        executionPolicy: parsed.executionPolicy ?? "interactive-host",
+        enabledGates: enabledGatesFromState(parsed.enabledGates),
+        artifactDirectory: typeof parsed.artifactDirectory === "string" && parsed.artifactDirectory.trim().length > 0
+            ? parsed.artifactDirectory
+            : "docs/devcrew",
+        executionWorkspace: executionWorkspace &&
+            typeof executionWorkspace.path === "string" &&
+            typeof executionWorkspace.baseCommit === "string"
+            ? executionWorkspace
+            : undefined,
+        executionInstruction: executionInstruction &&
+            (executionInstruction.phase === "execution" || executionInstruction.phase === "testing") &&
+            typeof executionInstruction.workspacePath === "string" &&
+            typeof executionInstruction.instructions === "string" &&
+            typeof executionInstruction.createdAt === "string"
+            ? executionInstruction
+            : undefined,
         changedFiles: Array.isArray(parsed.changedFiles) ? parsed.changedFiles : [],
+        pendingQuestions: Array.isArray(parsed.pendingQuestions)
+            ? parsed.pendingQuestions.filter((question) => typeof question === "string" && question.trim().length > 0)
+            : [],
         implementationDiff: typeof parsed.implementationDiff === "string" ? parsed.implementationDiff : "",
         verification: Array.isArray(parsed.verification) ? parsed.verification : [],
+        verificationStatus: parsed.verificationStatus === "passed" || parsed.verificationStatus === "failed" ? parsed.verificationStatus : "not_run",
+        verificationWaiver: verificationWaiver &&
+            typeof verificationWaiver.reason === "string" &&
+            typeof verificationWaiver.createdAt === "string"
+            ? verificationWaiver
+            : undefined,
         lintResults: Array.isArray(parsed.lintResults) ? parsed.lintResults : [],
     };
 }

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

@@ -1,21 +1,25 @@
 export const WORKFLOW_MODES = ["feature", "greenfield"];
 export const EXECUTION_MODES = ["plan", "apply"];
+export const EXECUTION_POLICIES = ["interactive-host", "headless-restricted", "headless-unattended"];
 export const HOSTS = ["codex", "claude"];
 export const BACKENDS = ["codex", "claude", "local"];
 export const PHASES = [
     "requirements",
     "architecture",
     "implementation",
+    "execution",
+    "review",
     "testing",
     "acceptance",
     "complete",
 ];
-export const GATES = ["requirements", "architecture", "implementation", "testing"];
+export const GATES = ["requirements", "architecture", "implementation", "implementation-review", "testing"];
 export const ARTIFACTS = [
     "requirements",
     "architecture",
     "implementation-plan",
     "implementation-review",
+    "architecture-review",
     "test-report",
     "acceptance",
 ];

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

@@ -1,4 +1,4 @@
-import { ARTIFACTS, BACKENDS, EXECUTION_MODES, GATES, HOSTS, WORKFLOW_MODES, } from "./types.js";
+import { ARTIFACTS, BACKENDS, EXECUTION_MODES, EXECUTION_POLICIES, GATES, HOSTS, WORKFLOW_MODES, } from "./types.js";
 function assertString(value, field) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throw new Error(`${field} must be a non-empty string`);
@@ -17,6 +17,9 @@ export function parseWorkflowMode(value) {
 export function parseExecutionMode(value) {
     return oneOf(value, "executionMode", EXECUTION_MODES);
 }
+export function parseExecutionPolicy(value) {
+    return oneOf(value, "executionPolicy", EXECUTION_POLICIES);
+}
 export function parseHost(value) {
     return oneOf(value, "host", HOSTS);
 }
@@ -50,3 +53,6 @@ export function parseFeedback(value) {
 export function parseAnswer(value) {
     return assertString(value, "answer");
 }
+export function parseWaiverReason(value) {
+    return assertString(value, "reason");
+}

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

@@ -1,2 +1,2 @@
-export const DEVCREW_VERSION = "0.1.1";
+export const DEVCREW_VERSION = "0.1.3";
 export const DEVCREW_NPM_PACKAGE = "@shenlee/devcrew";