@shenlee/devcrew 0.1.2 → 0.1.4

package/packages/adapters/src/index.ts

@@ -1,5 +1,16 @@
 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,
+  StructuredRoleData,
+  RoleResult,
+  RunState,
+  WorkflowMode,
+} from "../../core/src/index.js";
 
 export interface BackendResolutionInput {
   host: Host;
@@ -8,11 +19,12 @@ export interface BackendResolutionInput {
 
 export interface RoleRunInput {
   backend: BackendName;
-  role: RoleResult["role"];
+  role: Exclude<RoleResult["role"], "conductor">;
   phase: Phase;
   request: string;
   mode: WorkflowMode;
   executionMode?: ExecutionMode;
+  executionPolicy?: ExecutionPolicy;
   cwd: string;
   standards: string;
   artifactPath: string;
@@ -69,6 +81,177 @@ 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;
+}
+
+const STRUCTURED_RESULT_MARKER = "<!-- devcrew-role-result -->";
+const STRUCTURED_RESULT_BLOCK = /<!--\s*devcrew-role-result\s*-->\s*```json\s*\r?\n([\s\S]*?)\r?\n```/g;
+
+function structuredOutputError(role: RoleResult["role"], reason: string): RoleOutputValidationError {
+  return new RoleOutputValidationError(role, [`marked structured role result: ${reason}`]);
+}
+
+function asRecord(value: unknown, role: RoleResult["role"], field: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw structuredOutputError(role, `${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asNonEmptyString(value: unknown, role: RoleResult["role"], field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw structuredOutputError(role, `${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function asStringArray(value: unknown, role: RoleResult["role"], field: string): string[] {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.trim().length === 0)) {
+    throw structuredOutputError(role, `${field} must be an array of non-empty strings`);
+  }
+  return value.map((entry) => (entry as string).trim());
+}
+
+function asEvidence(value: unknown, role: RoleResult["role"]): StructuredRoleData["evidence"] {
+  if (!Array.isArray(value)) {
+    throw structuredOutputError(role, "evidence must be an array");
+  }
+  return value.map((entry, index) => {
+    const evidence = asRecord(entry, role, `evidence[${index}]`);
+    const command = asNonEmptyString(evidence.command, role, `evidence[${index}].command`);
+    if (!Number.isInteger(evidence.exitCode)) {
+      throw structuredOutputError(role, `evidence[${index}].exitCode must be an integer`);
+    }
+    if (evidence.output !== undefined && typeof evidence.output !== "string") {
+      throw structuredOutputError(role, `evidence[${index}].output must be a string`);
+    }
+    return { command, exitCode: evidence.exitCode as number, output: evidence.output as string | undefined };
+  });
+}
+
+function asQuestions(value: unknown, role: RoleResult["role"]): NonNullable<StructuredRoleData["questions"]> {
+  if (!Array.isArray(value)) {
+    throw structuredOutputError(role, "questions must be an array");
+  }
+  const ids = new Set<string>();
+  return value.map((entry, index) => {
+    const question = asRecord(entry, role, `questions[${index}]`);
+    const id = asNonEmptyString(question.id, role, `questions[${index}].id`);
+    if (ids.has(id)) {
+      throw structuredOutputError(role, `questions[${index}].id must be unique`);
+    }
+    ids.add(id);
+    const prompt = asNonEmptyString(question.prompt, role, `questions[${index}].prompt`);
+    if (question.context !== undefined && typeof question.context !== "string") {
+      throw structuredOutputError(role, `questions[${index}].context must be a string`);
+    }
+    return { id, prompt, context: question.context as string | undefined };
+  });
+}
+
+function parseStructuredRoleData(
+  role: Exclude<RoleResult["role"], "conductor">,
+  phase: Phase,
+  raw: unknown,
+): StructuredRoleData {
+  const value = asRecord(raw, role, "result");
+  if (value.schemaVersion !== 1) {
+    throw structuredOutputError(role, "schemaVersion must be 1");
+  }
+  if (value.role !== role) {
+    throw structuredOutputError(role, `role must be ${role}`);
+  }
+  const data: StructuredRoleData = {
+    schemaVersion: 1,
+    role,
+    summary: asNonEmptyString(value.summary, role, "summary"),
+    risks: asStringArray(value.risks, role, "risks"),
+    evidence: asEvidence(value.evidence, role),
+  };
+  if (role === "pm") {
+    data.questions = asQuestions(value.questions, role);
+  } else if (role === "architect") {
+    data.decisions = asStringArray(value.decisions, role, "decisions");
+    if (phase === "review") {
+      if (value.reviewDecision !== "approved" && value.reviewDecision !== "changes_required") {
+        throw structuredOutputError(role, "reviewDecision must be approved or changes_required");
+      }
+      data.reviewDecision = value.reviewDecision;
+    }
+  } else if (role === "implementer") {
+    data.changedFiles = asStringArray(value.changedFiles, role, "changedFiles");
+  } else {
+    if (!Array.isArray(value.testCases)) {
+      throw structuredOutputError(role, "testCases must be an array");
+    }
+    data.testCases = value.testCases.map((entry, index) => {
+      const testCase = asRecord(entry, role, `testCases[${index}]`);
+      const type = testCase.type;
+      if (type !== "happy" && type !== "edge" && type !== "failure" && type !== "regression") {
+        throw structuredOutputError(role, `testCases[${index}].type is invalid`);
+      }
+      return {
+        id: asNonEmptyString(testCase.id, role, `testCases[${index}].id`),
+        scenario: asNonEmptyString(testCase.scenario, role, `testCases[${index}].scenario`),
+        type,
+        expected: asNonEmptyString(testCase.expected, role, `testCases[${index}].expected`),
+      };
+    });
+  }
+  return data;
+}
+
+export function parseRoleResultOutput(
+  role: Exclude<RoleResult["role"], "conductor">,
+  phase: Phase,
+  output: string,
+): Pick<RoleResult, "format" | "markdown" | "structured" | "questions" | "reviewDecision"> {
+  if (!output.includes(STRUCTURED_RESULT_MARKER)) {
+    return {
+      format: "legacy",
+      markdown: output,
+      questions: role === "pm" ? extractOpenQuestions(output) : undefined,
+      reviewDecision: phase === "review" ? extractArchitectureReviewDecision(output) : undefined,
+    };
+  }
+  const blocks = [...output.matchAll(STRUCTURED_RESULT_BLOCK)];
+  if (blocks.length !== 1) {
+    throw structuredOutputError(role, blocks.length === 0 ? "must use a JSON fenced block" : "must appear exactly once");
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(blocks[0]?.[1] ?? "");
+  } catch {
+    throw structuredOutputError(role, "contains invalid JSON");
+  }
+  const structured = parseStructuredRoleData(role, phase, raw);
+  return {
+    format: "structured",
+    markdown: output.slice(0, blocks[0]?.index).concat(output.slice((blocks[0]?.index ?? 0) + (blocks[0]?.[0].length ?? 0))).trim(),
+    structured,
+    questions: structured.questions?.map((question) => question.prompt),
+    reviewDecision: structured.reviewDecision,
+  };
+}
+
 export function renderRolePrompt(input: Omit<RoleRunInput, "backend" | "cwd">): string {
   const executionMode = input.executionMode ?? "plan";
   const answers = input.answers ?? [];
@@ -113,13 +296,29 @@ 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,
     "",
+    "Return this protocol block first:",
+    STRUCTURED_RESULT_MARKER,
+    "```json",
+    `{\"schemaVersion\":1,\"role\":\"${input.role}\",\"summary\":\"...\",\"risks\":[],\"evidence\":[]}`,
+    "```",
+    "Then return the required Markdown H2 sections. Do not include a second marked result block.",
+    "",
     "Required Sections:",
     ...roleGuidance(input.role),
   );
 
+  if (input.phase === "review") {
+    lines.push(
+      "",
+      "Architecture Review Decision:",
+      "Add an exact H2 `## Review Decision` section containing exactly `Decision: approved` or `Decision: changes_required`.",
+      "Use `changes_required` for any mismatch with the approved architecture; summarize the blocking mismatch in that section.",
+    );
+  }
+
   return lines.join("\n");
 }
 
@@ -129,6 +328,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 +370,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 +495,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);
 }
@@ -344,6 +568,7 @@ function fallbackResult(
     summary,
     markdown: `# ${title}\n\n${summary}\n`,
     usedFallback: true,
+    format: "legacy",
   };
 }
 
@@ -356,6 +581,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,13 +602,22 @@ export async function runRole(input: RoleRunInput, deps: RunRoleDeps = {}): Prom
       input.backend === "codex"
         ? await runWithCodex(input, prompt, loadModule)
         : await runWithClaude(input, prompt, loadModule);
-    assertRoleSections(input.role, markdown);
+    const parsed = parseRoleResultOutput(input.role, input.phase, markdown);
+    assertRoleSections(input.role, parsed.markdown);
+    const reviewDecision = parsed.reviewDecision;
+    if (input.phase === "review" && !reviewDecision) {
+      throw new RoleOutputValidationError(input.role, ["Review Decision"]);
+    }
     return {
       role: input.role,
       backend: input.backend,
-      summary: `${input.role} produced ${title} using the ${input.backend} SDK.`,
-      markdown,
+      summary: parsed.structured?.summary ?? `${input.role} produced ${title} using the ${input.backend} SDK.`,
+      markdown: parsed.markdown,
       usedFallback: false,
+      format: parsed.format,
+      structured: parsed.structured,
+      questions: parsed.questions,
+      reviewDecision,
     };
   } catch (error) {
     const reason = errorMessage(error);

package/packages/core/src/active-run.ts

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

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

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

package/packages/core/src/index.ts

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