@shenlee/devcrew 0.1.2 → 0.1.3

package/docs/workflow.md

@@ -17,8 +17,8 @@ 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 a read-only implementation plan and coding checklist. The implementation gate approves this plan, not repository changes.
-4. `execution`: internal, nongated apply phase. The implementer works in `.devcrew/worktrees/<run-id>`, and DevCrew captures changed files, a binary-capable patch, lint evidence, and `implementation-review.md`.
-5. `testing`: tester records validation and acceptance evidence. In apply mode, the tester and verification commands run in the same isolated worktree, then DevCrew refreshes the implementation diff and review before opening the testing gate.
+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
@@ -32,14 +32,21 @@ 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`. One `devcrew_continue` call runs the implementer in the isolated worktree and leaves the run at `testing/ready`; another `devcrew_continue` runs the tester and verification commands before opening the testing gate.
+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, a real Codex or Claude SDK backend, and a clean requester worktree both when execution starts and when the reviewed patch is promoted. The requester repository remains unchanged until testing approval. If testing is rejected, `devcrew_answer` records the response and returns the run to `execution/ready` with the isolated worktree intact.
+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
@@ -53,10 +60,17 @@ 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`. 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
 
 Runtime state is stored in:
@@ -83,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.2",
+  "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 ?? [];
@@ -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");
 }
 
@@ -129,6 +170,7 @@ function titleForPhase(phase: Phase): string {
     architecture: "Architecture",
     implementation: "Implementation Plan",
     execution: "Implementation Review",
+    review: "Architecture Review",
     testing: "Test Report",
     acceptance: "Acceptance",
     complete: "Acceptance",
@@ -170,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";
@@ -294,28 +337,51 @@ export function extractClaudeResult(message: ClaudeResultMessage | undefined): s
   return text;
 }
 
-function roleCanApply(input: Pick<RoleRunInput, "executionMode" | "phase">): boolean {
+function isApplyPhase(input: Pick<RoleRunInput, "executionMode" | "phase">): boolean {
   return input.executionMode === "apply" && (input.phase === "execution" || input.phase === "testing");
 }
 
-function codexSandboxForRole(input: RoleRunInput): CodexSandboxMode {
-  return roleCanApply(input) ? "workspace-write" : "read-only";
+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 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);
 }
@@ -356,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);
@@ -375,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

@@ -35,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();
@@ -18,18 +25,44 @@ 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,5 +1,6 @@
 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 = [
@@ -7,29 +8,34 @@ export const PHASES = [
   "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;
@@ -88,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 {
@@ -107,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;
@@ -121,6 +140,13 @@ export interface ExecutionWorkspace {
   baseCommit: string;
 }
 
+export interface ExecutionInstruction {
+  phase: "execution" | "testing";
+  workspacePath: string;
+  instructions: string;
+  createdAt: string;
+}
+
 export interface RunState {
   version: 1;
   runId: string;
@@ -128,7 +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;
@@ -138,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[];
@@ -145,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[];
 }
@@ -156,6 +190,7 @@ export interface StartWorkflowInput {
   request: string;
   backend?: BackendName;
   executionMode?: ExecutionMode;
+  executionPolicy?: ExecutionPolicy;
 }
 
 export interface RunRef {
@@ -177,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.2";
+export const DEVCREW_VERSION = "0.1.3";
 export const DEVCREW_NPM_PACKAGE = "@shenlee/devcrew";