@shenlee/devcrew 0.1.2 → 0.1.3

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

@@ -1,5 +1,5 @@
 import { getArtifact, getActiveRunId, getWorkflowStatus, setActiveRun, } from "../../core/src/index.js";
-import { answerOrchestratedWorkflow, approveOrchestratedWorkflow, continueOrchestratedWorkflow, rejectOrchestratedWorkflow, startOrchestratedWorkflow, } from "../../orchestrator/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"],
                     },
                 },
             },
@@ -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.2` 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.2 -- 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,11 +52,13 @@ 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. After the implementation gate is approved, call `devcrew_continue` once to run the implementer in `.devcrew/worktrees/<run-id>`, then call it again to run the tester and verification commands in that worktree. Testing approval promotes the exact reviewed patch to the requester repository. Rejecting testing and answering the feedback returns the isolated run to execution without touching the requester repository.
+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.
 
@@ -66,7 +70,7 @@ npm install -g @shenlee/devcrew --include=optional
 
 ## Marketplace smoke test
 
-After publishing `@shenlee/devcrew@0.1.2`, run the real marketplace smoke test. Do not treat this as a pre-publication check because the plugin is locked to that npm version:
+After publishing `@shenlee/devcrew@0.1.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.2` 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
 

package/docs/superpowers/plans/2026-07-13-safety-semantics.md

@@ -0,0 +1,313 @@
+# Safety Semantics Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make apply-mode execution policy explicit and prevent failed or absent verification from silently promoting an isolated patch.
+
+**Architecture:** Add a persistent execution policy and verification outcome to the workflow state. Interactive apply runs pause with a host-execution handoff instead of launching a nested SDK; explicitly selected headless policies retain SDK execution with declared permissions. Testing only opens a normal promotion gate after successful verification; a separate waiver records the reason before an exception can be approved.
+
+**Tech Stack:** TypeScript, Node.js test runner, MCP JSON-RPC tools, Git worktrees.
+
+---
+
+## File Structure
+
+- Modify: `packages/core/src/types.ts` — policy, verification, handoff, and waiver state contracts.
+- Modify: `packages/core/src/validation.ts` — parse policy and waiver input.
+- Modify: `packages/core/src/workflow.ts` — default/apply-policy invariants and waiver transition.
+- Modify: `packages/core/src/store.ts` — migrate persisted legacy runs safely.
+- Modify: `packages/adapters/src/index.ts` — explicit headless SDK options; no implicit approval inheritance.
+- Modify: `packages/orchestrator/src/index.ts` — interactive execution pause/submission and verification gate blocking.
+- Modify: `packages/service/src/tools.ts` — MCP schemas and handlers for execution completion and verification waiver.
+- Modify: `packages/core/src/artifacts.ts` — render policy, verification status, and waiver evidence.
+- Modify: `tests/core.test.ts`, `tests/adapters-sdk.test.ts`, `tests/orchestrator.test.ts`, `tests/service.test.ts` — red/green coverage for every new state transition.
+- Modify: `README.md`, `docs/workflow.md`, `docs/codex.md`, `docs/claude-code.md`, `packages/plugins/src/index.ts` — correct public behavior and generated skill copy.
+
+### Task 1: Persist explicit execution and verification semantics
+
+**Files:**
+- Modify: `packages/core/src/types.ts`
+- Modify: `packages/core/src/validation.ts`
+- Modify: `packages/core/src/store.ts`
+- Test: `tests/core.test.ts`
+
+- [ ] **Step 1: Write failing state-contract tests**
+
+Add tests that start an apply workflow with `executionPolicy: "headless-restricted"`, assert the policy persists through `loadState`, and assert unknown policy values fail validation. Add a migration fixture without the new fields and assert it loads as an interactive-host apply run with `verificationStatus: "not_run"` and no waiver.
+
+```ts
+assert.equal(state.executionPolicy, "headless-restricted");
+await assert.rejects(
+  () => startWorkflow({ ...input, executionMode: "apply", executionPolicy: "unsafe" }),
+  /executionPolicy/,
+);
+assert.equal(loaded.verificationStatus, "not_run");
+```
+
+- [ ] **Step 2: Run the focused core test and verify RED**
+
+Run: `node --import tsx --test tests/core.test.ts`
+
+Expected: FAIL because `executionPolicy` and `verificationStatus` are not yet represented in state or input validation.
+
+- [ ] **Step 3: Add the minimal state and parsing contracts**
+
+In `types.ts`, add:
+
+```ts
+export const EXECUTION_POLICIES = ["interactive-host", "headless-restricted", "headless-unattended"] as const;
+export type ExecutionPolicy = (typeof EXECUTION_POLICIES)[number];
+export type VerificationStatus = "not_run" | "passed" | "failed";
+
+export interface VerificationWaiver { reason: string; createdAt: string; }
+```
+
+Add `executionPolicy` to `StartWorkflowInput` and `RunState`, plus
+`verificationStatus` and optional `verificationWaiver` to `RunState`. Add
+`parseExecutionPolicy()` and `parseWaiverReason()` in `validation.ts`. In
+`loadState`, use `interactive-host` for legacy apply runs and `not_run` for
+missing verification status.
+
+- [ ] **Step 4: Run the focused core test and verify GREEN**
+
+Run: `node --import tsx --test tests/core.test.ts`
+
+Expected: PASS, including new persistence and invalid-policy cases.
+
+- [ ] **Step 5: Commit the state contract**
+
+```bash
+git add packages/core/src/types.ts packages/core/src/validation.ts packages/core/src/store.ts tests/core.test.ts
+git commit -m "feat: record execution and verification policy"
+```
+
+### Task 2: Make SDK execution explicitly headless
+
+**Files:**
+- Modify: `packages/adapters/src/index.ts`
+- Test: `tests/adapters-sdk.test.ts`
+
+- [ ] **Step 1: Write failing adapter-policy tests**
+
+Replace the assertion that Claude apply uses `acceptEdits` with tests proving
+that an interactive-host execution is rejected before SDK invocation and that
+headless policies select explicit SDK options. For Claude restricted mode, the
+test must assert `permissionMode: "dontAsk"` and a narrow tool list. For Codex,
+assert `approvalPolicy: "never"` only for `headless-unattended` and no implicit
+approval-policy value for read-only planning.
+
+```ts
+await assert.rejects(
+  () => runRole({ ...baseInput, phase: "execution", executionMode: "apply", executionPolicy: "interactive-host", backend: "claude" }),
+  /interactive-host execution must be performed by the host/,
+);
+```
+
+- [ ] **Step 2: Run the focused adapter test and verify RED**
+
+Run: `node --import tsx --test tests/adapters-sdk.test.ts`
+
+Expected: FAIL because `RoleRunInput` lacks the policy and Claude currently
+sets `acceptEdits` with bare `Bash` permission.
+
+- [ ] **Step 3: Implement explicit headless profiles**
+
+Add `executionPolicy` to `RoleRunInput`. Make `roleCanApply()` require a
+headless policy. Reject SDK execution for `interactive-host`. Replace the
+Claude restricted profile with `dontAsk`: implementers receive only `Read`,
+`Grep`, `Glob`, `Edit`, and `Write`; testers receive only `Read`, `Grep`, and
+`Glob`. Neither restricted role receives `Bash`; DevCrew's configured command
+runner supplies verification evidence separately. For the explicitly selected
+unattended policy, add the SDK's dangerous-skip opt-in and set Claude to
+`bypassPermissions`; this is an auditable CI-only policy. Pass Codex
+`approvalPolicy: "never"` only for that unattended policy. Document that both
+headless profiles are DevCrew policies, not inherited host approval.
+
+- [ ] **Step 4: Run the focused adapter test and verify GREEN**
+
+Run: `node --import tsx --test tests/adapters-sdk.test.ts`
+
+Expected: PASS with no `acceptEdits` assertion remaining.
+
+- [ ] **Step 5: Commit the adapter boundary**
+
+```bash
+git add packages/adapters/src/index.ts tests/adapters-sdk.test.ts
+git commit -m "fix: make SDK apply policies explicit"
+```
+
+### Task 3: Add the interactive execution handoff
+
+**Files:**
+- Modify: `packages/orchestrator/src/index.ts`
+- Modify: `packages/service/src/tools.ts`
+- Test: `tests/orchestrator.test.ts`
+- Test: `tests/service.test.ts`
+
+- [ ] **Step 1: Write failing handoff tests**
+
+Add an apply workflow with `executionPolicy: "interactive-host"`. After the
+implementation gate is approved, `devcrew_continue` must create the isolated
+worktree but not call the injected `RoleRunner`; it returns
+`status: "awaiting_execution"` and structured instruction data. A new
+`devcrew_complete_execution` call captures the worktree patch and advances to
+testing without modifying the requester repository. Repeat the same handoff
+for the tester: it receives the test-report instruction, returns exact command
+result records, and DevCrew derives the verification status from those records.
+
+```ts
+assert.equal(paused.status, "awaiting_execution");
+assert.equal(runnerCalls.filter((call) => call.phase === "execution").length, 0);
+assert.equal(paused.executionInstruction?.cwd, paused.executionWorkspace?.path);
+```
+
+- [ ] **Step 2: Run focused orchestrator and service tests and verify RED**
+
+Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
+
+Expected: FAIL because the current orchestrator immediately invokes the SDK
+runner and no completion MCP tool exists.
+
+- [ ] **Step 3: Implement pause and completion transitions**
+
+Add `awaiting_execution` to `RunStatus` and an `ExecutionInstruction` state
+object containing role, phase, worktree cwd, request, standards, approved
+artifacts, and required result sections. In the execution and testing branches
+of `runCurrentPhaseRole`, ensure the worktree, write the instruction, persist
+the state, and return without calling `runner` or `runConfiguredVerification`
+when policy is `interactive-host`.
+
+Add `completeInteractiveExecution(input)` to orchestrator. It requires an
+`awaiting_execution` state and a required Markdown summary supplied by the
+host. For execution it captures changes, runs no nested SDK or shell command,
+writes implementation-review evidence, and moves to `testing/ready`. For
+testing it accepts a validated array of `{ command, exitCode, output,
+startedAt, completedAt }`, writes the test report, derives the verification
+status, and either opens the gate or enters the failure path. Expose it as
+`devcrew_complete_execution` with an input schema that includes `summary` and
+optional `verification` records.
+
+- [ ] **Step 4: Run focused handoff tests and verify GREEN**
+
+Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
+
+Expected: PASS; the requester repository remains unchanged until a later
+testing approval.
+
+- [ ] **Step 5: Commit the interactive handoff**
+
+```bash
+git add packages/orchestrator/src/index.ts packages/service/src/tools.ts tests/orchestrator.test.ts tests/service.test.ts
+git commit -m "feat: hand interactive apply execution to host"
+```
+
+### Task 4: Block failed verification and require a recorded waiver
+
+**Files:**
+- Modify: `packages/core/src/workflow.ts`
+- Modify: `packages/orchestrator/src/index.ts`
+- Modify: `packages/service/src/tools.ts`
+- Modify: `packages/core/src/artifacts.ts`
+- Test: `tests/orchestrator.test.ts`
+- Test: `tests/service.test.ts`
+
+- [ ] **Step 1: Write failing verification tests**
+
+Create an apply fixture with `verifyCommands: ["node -e \"process.exit(7)\""]`.
+After testing, assert `verificationStatus === "failed"`, `status ===
+"awaiting_input"`, and that `approveOrchestratedWorkflow({ gate: "testing" })`
+rejects without promoting the patch. Add a second test showing that
+`devcrew_waive_verification` rejects an empty reason, persists a non-empty
+reason, reopens the testing gate, and permits promotion only after normal
+testing approval.
+
+```ts
+await assert.rejects(
+  () => approveOrchestratedWorkflow({ cwd, runId, gate: "testing" }),
+  /verification failed/,
+);
+assert.equal(waived.verificationWaiver?.reason, "Known upstream test outage");
+```
+
+- [ ] **Step 2: Run focused workflow tests and verify RED**
+
+Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
+
+Expected: FAIL because a nonzero command currently still opens the pending
+testing gate and no waiver tool exists.
+
+- [ ] **Step 3: Implement verification outcome and waiver flow**
+
+After `runConfiguredVerification`, set `verificationStatus` from every result:
+empty is `not_run`, all-zero is `passed`, otherwise `failed`. A failed status
+sets `awaiting_input` and does not set the testing gate to pending. Add
+`waiveVerification(input)` that requires failed verification and a non-empty
+reason, records `VerificationWaiver`, changes the testing gate to pending, and
+sets `awaiting_approval`. Add `devcrew_waive_verification` to the MCP schema
+and handler.
+
+Make `approveOrchestratedWorkflow` reject a testing promotion unless status is
+passed or a waiver exists. Render the status, command exit evidence, and waiver
+reason in both the test report and acceptance artifact.
+
+- [ ] **Step 4: Run focused verification tests and verify GREEN**
+
+Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
+
+Expected: PASS; failed verification cannot mutate the requester repository,
+while a recorded waiver remains visible and permits intentional approval.
+
+- [ ] **Step 5: Commit verification safety**
+
+```bash
+git add packages/core/src/workflow.ts packages/orchestrator/src/index.ts packages/service/src/tools.ts packages/core/src/artifacts.ts tests/orchestrator.test.ts tests/service.test.ts
+git commit -m "fix: block failed verification promotion"
+```
+
+### Task 5: Correct generated instructions and user-facing documentation
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/workflow.md`
+- Modify: `docs/codex.md`
+- Modify: `docs/claude-code.md`
+- Modify: `packages/plugins/src/index.ts`
+- Test: `tests/plugins.test.ts`
+
+- [ ] **Step 1: Write failing generated-skill/doc assertions**
+
+Extend plugin tests to require the generated skill to distinguish
+interactive-host execution from headless policy and to mention
+`devcrew_complete_execution` and `devcrew_waive_verification`.
+
+- [ ] **Step 2: Run plugin tests and verify RED**
+
+Run: `node --import tsx --test tests/plugins.test.ts`
+
+Expected: FAIL because the generated skill promises inherited host approvals
+and lacks the new handoff/waiver tools.
+
+- [ ] **Step 3: Update generated skill and docs**
+
+Document that interactive host execution uses the host's native agent after
+DevCrew supplies a worktree instruction; it does not run a nested SDK. Document
+headless policies as explicit DevCrew policies. Replace all claims that DevCrew
+inherits a current host approval boundary. Add the failed-verification and
+recorded-waiver transition to workflow diagrams and tool lists.
+
+- [ ] **Step 4: Run plugin tests and verify GREEN**
+
+Run: `node --import tsx --test tests/plugins.test.ts`
+
+Expected: PASS with the checked-in plugin matching regenerated text.
+
+- [ ] **Step 5: Run full validation and commit documentation**
+
+Run: `npm run validate`
+
+Expected: exit code 0 with all tests passing.
+
+```bash
+git add README.md docs/workflow.md docs/codex.md docs/claude-code.md packages/plugins/src/index.ts plugins/devcrew-codex plugins/devcrew-claude tests/plugins.test.ts
+git commit -m "docs: describe explicit apply execution policies"
+```

package/docs/superpowers/specs/2026-07-13-execution-boundaries-design.md

@@ -0,0 +1,126 @@
+# DevCrew Execution Boundaries Design
+
+## Goal
+
+Make DevCrew's approval, verification, and role boundaries match its public
+product claims. Interactive work must execute through the host agent's native
+permission model. Headless work may use host SDKs only under an explicit,
+auditable DevCrew execution policy.
+
+## Scope
+
+This change is delivered in three independently releasable slices:
+
+1. Safety semantics: explicit execution policy and verification-failure
+   promotion blocking.
+2. Workflow semantics: execution-time architecture compliance review and
+   structured role questions/results.
+3. Productisation: effective artifact configuration and real-host integration
+   coverage.
+
+The existing isolated Git worktree and binary patch promotion remain the sole
+mechanism for moving apply-mode changes into the requester repository.
+
+## Execution Planes
+
+### Interactive host plane
+
+Interactive Codex and Claude Code workflows do not invoke the Codex or Claude
+SDK to modify repository files. DevCrew MCP owns durable workflow state,
+artifacts, gate validation, execution worktree creation, patch capture, and
+promotion. It exposes a structured execution instruction containing the role,
+worktree path, approved context, and required result schema. The active host
+agent or a native host subagent performs the work with the host's ordinary
+sandbox and approval UI, then submits the result to DevCrew.
+
+This plane must never claim that a nested SDK session inherits the interactive
+host's current approval decisions.
+
+### Headless SDK plane
+
+Headless and CI workflows retain SDK orchestration, but `apply` requires an
+explicit `executionPolicy`. The initial policy set is:
+
+- `interactive-host`: no nested SDK execution; valid only for an interactive
+  host integration.
+- `headless-restricted`: SDK execution in the DevCrew worktree with a declared
+  minimal tool surface and no hidden user-prompt assumption.
+- `headless-unattended`: an explicitly opted-in unattended SDK policy for CI;
+  its audit record makes the autonomy clear.
+
+The policy, backend, allowed capabilities, and any waiver are recorded in run
+state and shown in review artifacts. `acceptEdits`, bare `allowedTools`, and an
+implicit Codex approval policy are not described as inherited host approvals.
+
+## Verification And Promotion
+
+After isolated testing, DevCrew computes a verification status:
+
+- `passed`: every configured or discovered verification command exited zero.
+- `failed`: at least one command exited nonzero or timed out.
+- `not_run`: no verification command was available.
+
+Only `passed` can open the normal `testing` approval gate. A failed result
+moves the run to `awaiting_input` with the failure evidence and preserves the
+worktree. A requester may either supply feedback that returns the run to
+`execution`, or invoke a dedicated risk-waiver operation with a non-empty
+reason. The waiver is persistent, appears in the test report and acceptance
+artifact, and is the only path that can open a testing approval gate after a
+failed verification.
+
+`not_run` remains reviewable but is visibly distinct from `passed`; it cannot
+be silently represented as successful verification.
+
+## Execution-Time Architecture Review
+
+The current implementation-plan gate approves a plan and cannot approve the
+subsequent code diff. Add an `implementation-review` gate after execution and
+before testing. The architect role receives the approved architecture artifact,
+captured binary diff, changed-file list, lint evidence, and structured
+implementation result. It returns a structured compliance decision.
+
+Only an approved implementation review advances to testing. Rejection records
+feedback and returns to execution with the existing isolated worktree intact.
+The existing `implementation-review.md` remains an artifact, but becomes the
+architect's real review output rather than a rendered checklist.
+
+## Structured Role Results And Clarification
+
+Each role result is a validated JSON envelope with a Markdown body plus
+role-specific fields. At minimum, PM returns `questions`, architect returns a
+compliance decision, implementer returns changed-file and command evidence, and
+tester returns case/evidence summaries. Markdown remains the human-facing
+artifact format.
+
+If PM returns one or more questions, requirements enter `awaiting_input`
+without opening an approval gate. `devcrew_answer` records the answer and
+re-runs PM. A requirements gate opens only when the PM result has no open
+questions.
+
+## Configuration
+
+`workflow.artifactDirectory` is used by all artifact path helpers, relative to
+the repository root and validated to remain within that root. Core safety gates
+are not freely removable. `workflow.gates` is replaced or constrained by a
+validated sequence that must include requirements, architecture,
+implementation, implementation-review, and testing for apply workflows.
+
+## Integration Coverage
+
+Add tests for failed verification, risk waiver, no-verification status,
+architecture-review rejection/revision, structured PM questions, and configured
+artifact output. Preserve existing worktree-promotion coverage.
+
+The production-like Codex marketplace smoke remains plan-mode and must verify
+the published package version. Add isolated integration coverage for the
+interactive execution handoff protocol and a real Claude plugin install/start
+smoke. A real unattended apply smoke uses only a disposable fixture repository
+and an explicitly selected headless policy.
+
+## Non-goals
+
+- Do not remove worktree isolation or binary patch promotion.
+- Do not automatically approve failed verification.
+- Do not make arbitrary workflow graph customisation part of this release.
+- Do not use generated role files as an execution mechanism until a host-native
+  integration consumes them explicitly.