@shenlee/devcrew 0.1.1 → 0.1.3

package/docs/workflow.md

@@ -16,14 +16,38 @@ approval.
 
 1. `requirements`: product manager clarifies scope, users, success criteria, and non-goals.
 2. `architecture`: architect defines technical approach, interfaces, deployment notes, and review criteria.
-3. `implementation`: implementer creates the implementation plan and coding checklist. DevCrew also writes `implementation-review.md` with changed files, captured diff, and architecture compliance review prompts before opening the implementation gate.
-4. `testing`: tester records validation strategy and acceptance evidence.
-5. `acceptance`: generated after the testing gate is approved.
+3. `implementation`: implementer creates a read-only implementation plan and coding checklist. The implementation gate approves this plan, not repository changes.
+4. `execution`: internal, nongated apply phase. `interactive-host` waits for the host-native agent to work in `.devcrew/worktrees/<run-id>` and report completion; explicit headless policies use DevCrew's SDK settings. DevCrew then captures changed files, a binary-capable patch, lint evidence when run headlessly, and `implementation-review.md`.
+5. `testing`: records validation and acceptance evidence in the same isolated worktree. Interactive-host submits command evidence through `devcrew_complete_execution`; headless policies run DevCrew-configured verification. DevCrew refreshes the implementation diff and review before opening the testing gate.
+6. `acceptance`: generated after the testing gate is approved.
 
 `devcrew_start` runs the PM role for `requirements`. After the requester approves
 a gate, `devcrew_continue` runs the role for the next phase before setting that
 phase's gate to `pending`.
 
+Plan mode advances directly from implementation-plan approval to testing. Apply mode uses this sequence:
+
+```text
+requirements approval
+-> architecture approval
+-> implementation plan approval
+-> isolated execution
+-> implementation review approval
+-> isolated testing
+-> testing approval
+-> patch promotion to requester repository
+```
+
+The implementation-plan approval advances the run to `execution`. With the default `interactive-host` policy, each `devcrew_continue` pauses at `awaiting_execution`; the host-native agent works in the reported worktree and calls `devcrew_complete_execution`. Explicit headless policies run the corresponding SDK role and commands directly under their recorded DevCrew policy.
+
+Apply requires Git and a clean requester worktree both when execution starts and when the reviewed patch is promoted. The requester repository remains unchanged until testing approval. A failed verification enters `awaiting_input`, rather than a promotable testing gate; it can be revised with `devcrew_answer` or deliberately reopened only through `devcrew_waive_verification` with a non-empty risk reason. If testing is rejected, `devcrew_answer` records the response and returns the run to `execution/ready` with the isolated worktree intact.
+
+The execution review is also structured: the architect must return either
+`Decision: approved` or `Decision: changes_required` in its
+`architecture-review` artifact. A `changes_required` decision rejects the
+implementation-review gate and keeps the run at `awaiting_input`; it cannot
+enter testing until the feedback is addressed and a later review approves it.
+
 `devcrew_start` records the created run as the active run for the repository.
 Subsequent MCP calls can omit `runId`; DevCrew resolves it from
 `.devcrew/active-run.json`. Plugin MCP configs set `DEVCREW_HOST`, so `host`
@@ -36,9 +60,16 @@ Each main phase has a gate:
 - `requirements`
 - `architecture`
 - `implementation`
+- `implementation-review`
 - `testing`
 
-The requester approves or rejects each gate. Rejection records feedback and returns the workflow to `awaiting_input`.
+The requester approves or rejects each gate. Rejection records feedback and returns the workflow to `awaiting_input`. In apply mode, rejecting testing never rolls changes back in the requester repository because no patch has been promoted yet.
+
+`workflow.gates` may omit `requirements`, `architecture`, or `implementation`
+to make that phase advance automatically after its role has produced an
+artifact. It never skips the role, artifact, execution, architecture review, or
+verification. `implementation-review` and `testing` are mandatory and DevCrew
+adds them back if a configuration omits them.
 
 ## State And Artifacts
 
@@ -66,5 +97,6 @@ The standard artifact set is:
 - `architecture.md`
 - `implementation-plan.md`
 - `implementation-review.md`
+- `architecture-review.md`
 - `test-report.md`
 - `acceptance.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenlee/devcrew",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Multi-host agent workflow service for Codex and Claude Code.",
   "type": "module",
   "license": "Apache-2.0",

package/packages/adapters/src/index.ts

@@ -1,5 +1,15 @@
 import { DEVCREW_NPM_PACKAGE, ROLE_SECTIONS } from "../../core/src/index.js";
-import type { ArtifactName, BackendName, ExecutionMode, Host, Phase, RoleResult, RunState, WorkflowMode } from "../../core/src/index.js";
+import type {
+  ArtifactName,
+  BackendName,
+  ExecutionMode,
+  ExecutionPolicy,
+  Host,
+  Phase,
+  RoleResult,
+  RunState,
+  WorkflowMode,
+} from "../../core/src/index.js";
 
 export interface BackendResolutionInput {
   host: Host;
@@ -13,6 +23,7 @@ export interface RoleRunInput {
   request: string;
   mode: WorkflowMode;
   executionMode?: ExecutionMode;
+  executionPolicy?: ExecutionPolicy;
   cwd: string;
   standards: string;
   artifactPath: string;
@@ -69,6 +80,27 @@ export function assertRoleSections(role: RoleResult["role"], markdown: string):
   }
 }
 
+export function extractOpenQuestions(markdown: string): string[] {
+  const match = /^##\s+Open Questions\s*$(.*?)(?=^##\s|(?![\s\S]))/ims.exec(markdown);
+  if (!match) {
+    return [];
+  }
+  const questions: string[] = [];
+  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: string): "approved" | "changes_required" | undefined {
+  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] as "approved" | "changes_required" | undefined;
+}
+
 export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">): string {
   const executionMode = input.executionMode ?? "plan";
   const answers = input.answers ?? [];
@@ -102,7 +134,7 @@ export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">):
     }
   }
 
-  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."
@@ -113,13 +145,22 @@ export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">):
     "",
     "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.",
+    "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");
 }
 
@@ -128,6 +169,8 @@ function titleForPhase(phase: Phase): string {
     requirements: "Requirements",
     architecture: "Architecture",
     implementation: "Implementation Plan",
+    execution: "Implementation Review",
+    review: "Architecture Review",
     testing: "Test Report",
     acceptance: "Acceptance",
     complete: "Acceptance",
@@ -169,13 +212,14 @@ interface CodexClient {
 
 type CodexConstructor = new () => CodexClient;
 
-export type ClaudePermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan";
+export type ClaudePermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "dontAsk" | "plan";
 
 export interface ClaudeQueryOptions {
   cwd?: string;
   permissionMode?: ClaudePermissionMode;
   allowedTools?: string[];
   disallowedTools?: string[];
+  allowDangerouslySkipPermissions?: boolean;
 }
 
 export type ClaudeResultSubtype = "success" | "error_max_turns" | "error_during_execution";
@@ -293,28 +337,51 @@ export function extractClaudeResult(message: ClaudeResultMessage | undefined): s
   return text;
 }
 
-function roleCanApply(input: RoleRunInput): boolean {
-  return input.executionMode === "apply" && (input.role === "implementer" || input.role === "tester");
+function isApplyPhase(input: Pick<RoleRunInput, "executionMode" | "phase">): boolean {
+  return input.executionMode === "apply" && (input.phase === "execution" || input.phase === "testing");
+}
+
+function effectiveExecutionPolicy(input: Pick<RoleRunInput, "executionPolicy">): ExecutionPolicy {
+  return input.executionPolicy ?? "interactive-host";
+}
+
+function roleCanApply(input: Pick<RoleRunInput, "executionMode" | "executionPolicy" | "phase">): boolean {
+  return isApplyPhase(input) && effectiveExecutionPolicy(input) !== "interactive-host";
 }
 
-function codexSandboxForRole(input: RoleRunInput): CodexSandboxMode {
-  return roleCanApply(input) ? "workspace-write" : "read-only";
+function codexOptionsForRole(input: RoleRunInput): CodexThreadOptions {
+  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: RoleRunInput): ClaudeQueryOptions {
   if (!roleCanApply(input)) {
     return buildClaudeOptions(input.cwd);
   }
+  if (effectiveExecutionPolicy(input) === "headless-unattended") {
+    return {
+      cwd: input.cwd,
+      permissionMode: "bypassPermissions",
+      allowDangerouslySkipPermissions: true,
+    };
+  }
   const allowedTools =
-    input.role === "implementer" ? ["Read", "Grep", "Glob", "Edit", "Write", "Bash"] : ["Read", "Grep", "Glob", "Bash"];
-  return buildClaudeOptions(input.cwd, "acceptEdits", allowedTools);
+    input.role === "implementer" ? ["Read", "Grep", "Glob", "Edit", "Write"] : ["Read", "Grep", "Glob"];
+  return buildClaudeOptions(input.cwd, "dontAsk", allowedTools);
 }
 
 async function runWithCodex(input: RoleRunInput, prompt: string, loadModule: ModuleLoader): Promise<string> {
   const mod = await loadModule(HOST_SDK_PACKAGES.codex);
   const CodexClass = mod.Codex as CodexConstructor;
   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);
 }
@@ -355,6 +422,9 @@ export interface RunRoleDeps {
 }
 
 export async function runRole(input: RoleRunInput, deps: RunRoleDeps = {}): Promise<RoleResult> {
+  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);
@@ -374,12 +444,18 @@ export async function runRole(input: RoleRunInput, deps: RunRoleDeps = {}): Prom
         ? 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) {
     const reason = errorMessage(error);

package/packages/core/src/artifacts.ts

@@ -10,6 +10,7 @@ function headingForArtifact(name: ArtifactName): string {
     architecture: "Architecture",
     "implementation-plan": "Implementation Plan",
     "implementation-review": "Implementation Review",
+    "architecture-review": "Architecture Review",
     "test-report": "Test Report",
     acceptance: "Acceptance",
   }[name];
@@ -60,6 +61,13 @@ function verificationBlock(state: RunState): string {
     .join("\n\n");
 }
 
+function verificationWaiverBlock(state: RunState): string {
+  if (!state.verificationWaiver) {
+    return "No verification waiver has been recorded.";
+  }
+  return `Reason: ${state.verificationWaiver.reason}\nRecorded At: ${state.verificationWaiver.createdAt}`;
+}
+
 function lintResultsBlock(state: RunState): string {
   if (state.lintResults.length === 0) {
     return "No lint or format commands have been executed.";
@@ -99,7 +107,7 @@ function architectureComplianceStatus(state: RunState): string {
 
 export function renderArtifact(name: ArtifactName, state: RunState): string {
   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`;
@@ -117,17 +125,21 @@ export function renderArtifact(name: ArtifactName, state: RunState): string {
     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: ArtifactName, state: RunState): Promise<string> {
-  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/packages/core/src/config.ts

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

package/packages/core/src/paths.ts

@@ -15,6 +15,10 @@ export function runDir(cwd: string, runId: string): string {
   return join(runsDir(cwd), runId);
 }
 
+export function executionWorktreePath(cwd: string, runId: string): string {
+  return join(devcrewDir(cwd), "worktrees", runId);
+}
+
 export function statePath(cwd: string, runId: string): string {
   return join(runDir(cwd, runId), "state.json");
 }
@@ -31,24 +35,25 @@ export function standardsPath(cwd: string): string {
   return join(devcrewDir(cwd), "standards.md");
 }
 
-export function docsRoot(cwd: string): string {
-  return join(cwd, "docs", "devcrew");
+export function docsRoot(cwd: string, artifactDirectory: string = "docs/devcrew"): string {
+  return join(cwd, artifactDirectory);
 }
 
-export function docsRunDir(cwd: string, runId: string): string {
-  return join(docsRoot(cwd), runId);
+export function docsRunDir(cwd: string, runId: string, artifactDirectory: string = "docs/devcrew"): string {
+  return join(docsRoot(cwd, artifactDirectory), runId);
 }
 
-export function artifactPath(cwd: string, runId: string, artifact: ArtifactName): string {
+export function artifactPath(cwd: string, runId: string, artifact: ArtifactName, artifactDirectory: string = "docs/devcrew"): string {
   const filenameByArtifact: Record<ArtifactName, string> = {
     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: string, runId: string): Promise<void> {

package/packages/core/src/store.ts

@@ -2,7 +2,14 @@ import { readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import { ensureRunDirectories, statePath } from "./paths.js";
-import type { RunState } from "./types.js";
+import { GATES, type GateName, type RunState } from "./types.js";
+
+function enabledGatesFromState(value: unknown): GateName[] {
+  const configured = Array.isArray(value)
+    ? value.filter((gate): gate is GateName => typeof gate === "string" && GATES.includes(gate as GateName))
+    : [...GATES];
+  return [...new Set<GateName>([...configured, "implementation-review", "testing"])];
+}
 
 export async function saveState(state: RunState): Promise<RunState> {
   state.updatedAt = new Date().toISOString();
@@ -17,12 +24,45 @@ export async function saveState(state: RunState): Promise<RunState> {
 export async function loadState(cwd: string, runId: string): Promise<RunState> {
   const raw = await readFile(statePath(cwd, runId), "utf8");
   const parsed = JSON.parse(raw) as RunState;
+  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): question is string => 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/packages/core/src/types.ts

@@ -1,34 +1,41 @@
 export const WORKFLOW_MODES = ["feature", "greenfield"] as const;
 export const EXECUTION_MODES = ["plan", "apply"] as const;
+export const EXECUTION_POLICIES = ["interactive-host", "headless-restricted", "headless-unattended"] as const;
 export const HOSTS = ["codex", "claude"] as const;
 export const BACKENDS = ["codex", "claude", "local"] as const;
 export const PHASES = [
   "requirements",
   "architecture",
   "implementation",
+  "execution",
+  "review",
   "testing",
   "acceptance",
   "complete",
 ] as const;
-export const GATES = ["requirements", "architecture", "implementation", "testing"] as const;
+export const GATES = ["requirements", "architecture", "implementation", "implementation-review", "testing"] as const;
 export const ARTIFACTS = [
   "requirements",
   "architecture",
   "implementation-plan",
   "implementation-review",
+  "architecture-review",
   "test-report",
   "acceptance",
 ] as const;
 
 export type WorkflowMode = (typeof WORKFLOW_MODES)[number];
 export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+export type ExecutionPolicy = (typeof EXECUTION_POLICIES)[number];
+export type VerificationStatus = "not_run" | "passed" | "failed";
+export type ArchitectureReviewDecision = "approved" | "changes_required";
 export type Host = (typeof HOSTS)[number];
 export type BackendName = (typeof BACKENDS)[number];
 export type Phase = (typeof PHASES)[number];
 export type GateName = (typeof GATES)[number];
 export type ArtifactName = (typeof ARTIFACTS)[number];
 export type GateStatus = "not_started" | "pending" | "approved" | "rejected";
-export type RunStatus = "ready" | "awaiting_input" | "awaiting_approval" | "complete";
+export type RunStatus = "ready" | "awaiting_input" | "awaiting_approval" | "awaiting_execution" | "complete";
 
 export interface RoleSection {
   heading: string;
@@ -87,6 +94,14 @@ export interface RoleResult {
   summary: string;
   markdown: string;
   usedFallback: boolean;
+  questions?: string[];
+  reviewDecision?: ArchitectureReviewDecision;
+}
+
+export interface ArchitectureReview {
+  decision: ArchitectureReviewDecision;
+  summary: string;
+  reviewedAt: string;
 }
 
 export interface WorkflowFeedback {
@@ -106,6 +121,11 @@ export interface WorkflowAnswer {
   createdAt: string;
 }
 
+export interface VerificationWaiver {
+  reason: string;
+  createdAt: string;
+}
+
 // Reused for both verification and lint results — the command shape is identical.
 export interface VerificationResult {
   command: string;
@@ -115,6 +135,18 @@ export interface VerificationResult {
   completedAt: string;
 }
 
+export interface ExecutionWorkspace {
+  path: string;
+  baseCommit: string;
+}
+
+export interface ExecutionInstruction {
+  phase: "execution" | "testing";
+  workspacePath: string;
+  instructions: string;
+  createdAt: string;
+}
+
 export interface RunState {
   version: 1;
   runId: string;
@@ -122,6 +154,11 @@ export interface RunState {
   host: Host;
   mode: WorkflowMode;
   executionMode: ExecutionMode;
+  executionPolicy: ExecutionPolicy;
+  enabledGates: GateName[];
+  artifactDirectory: string;
+  executionWorkspace?: ExecutionWorkspace;
+  executionInstruction?: ExecutionInstruction;
   backend: BackendName;
   request: string;
   phase: Phase;
@@ -131,6 +168,8 @@ export interface RunState {
   gates: Record<GateName, GateStatus>;
   artifacts: Partial<Record<ArtifactName, string>>;
   roles: RoleResult[];
+  architectureReview?: ArchitectureReview;
+  pendingQuestions: string[];
   answers: WorkflowAnswer[];
   approvals: WorkflowApproval[];
   feedback: WorkflowFeedback[];
@@ -138,6 +177,8 @@ export interface RunState {
   changedFiles: string[];
   implementationDiff: string;
   verification: VerificationResult[];
+  verificationStatus: VerificationStatus;
+  verificationWaiver?: VerificationWaiver;
   // VerificationResult is reused for lint output — same shape, different semantics.
   lintResults: VerificationResult[];
 }
@@ -149,6 +190,7 @@ export interface StartWorkflowInput {
   request: string;
   backend?: BackendName;
   executionMode?: ExecutionMode;
+  executionPolicy?: ExecutionPolicy;
 }
 
 export interface RunRef {
@@ -170,6 +212,15 @@ export interface AnswerWorkflowInput extends RunRef {
   answer: string;
 }
 
+export interface WaiveVerificationInput extends RunRef {
+  reason: string;
+}
+
+export interface CompleteExecutionInput extends RunRef {
+  summary: string;
+  verification?: VerificationResult[];
+}
+
 export interface ArtifactRef extends RunRef {
   name: ArtifactName;
 }

package/packages/core/src/validation.ts

@@ -2,12 +2,14 @@ import {
   ARTIFACTS,
   BACKENDS,
   EXECUTION_MODES,
+  EXECUTION_POLICIES,
   GATES,
   HOSTS,
   WORKFLOW_MODES,
   type ArtifactName,
   type BackendName,
   type ExecutionMode,
+  type ExecutionPolicy,
   type GateName,
   type Host,
   type WorkflowMode,
@@ -35,6 +37,10 @@ export function parseExecutionMode(value: unknown): ExecutionMode {
   return oneOf(value, "executionMode", EXECUTION_MODES);
 }
 
+export function parseExecutionPolicy(value: unknown): ExecutionPolicy {
+  return oneOf(value, "executionPolicy", EXECUTION_POLICIES);
+}
+
 export function parseHost(value: unknown): Host {
   return oneOf(value, "host", HOSTS);
 }
@@ -77,3 +83,7 @@ export function parseFeedback(value: unknown): string {
 export function parseAnswer(value: unknown): string {
   return assertString(value, "answer");
 }
+
+export function parseWaiverReason(value: unknown): string {
+  return assertString(value, "reason");
+}

package/packages/core/src/version.ts

@@ -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";