@shenlee/devcrew 0.1.1 → 0.1.2

package/docs/superpowers/specs/2026-07-10-p0-foundation-repair-design.md

@@ -0,0 +1,182 @@
+# DevCrew P0 Foundation Repair Design
+
+## Objective
+
+Repair the P0 workflow and execution-safety defects identified in the 0.1.1 review without expanding into the P1 role-model, semantic architecture review, or configurable workflow work.
+
+The repaired workflow must guarantee that requester approval happens before code changes, apply-mode changes remain isolated until final approval, malformed MCP input cannot poison the server, gate mutations are valid and idempotent, local fallback cannot impersonate apply execution, and the checked-in plugin cannot drift from the package version.
+
+## Scope
+
+This design includes:
+
+- Move real implementation after the existing `implementation` gate.
+- Execute apply-mode implementation and verification in a run-owned Git worktree.
+- Capture committed, staged, unstaged, renamed, deleted, binary, and new-file changes as one reviewable patch.
+- Apply the reviewed patch to the requester's repository only after the `testing` gate is approved.
+- Keep rejected testing work isolated and allow the implementer to revise it.
+- Enforce legal, idempotent `approve`, `reject`, and `answer` transitions.
+- Validate JSON-RPC request shape and recover the stdio queue after handler failures.
+- Reject `executionMode=apply` with the `local` backend.
+- Synchronize package, generated plugin, checked-in plugin, and MCP runtime versions.
+
+This design does not include:
+
+- Real architect-driven semantic diff review.
+- Structured PM questions and machine-readable role verdicts.
+- Host-native role/subagent integration.
+- Configurable gates or artifact directories.
+- Claude marketplace packaging or smoke coverage.
+- Cross-process run locking or HTTP transport.
+
+## Workflow Model
+
+The public gate names remain unchanged for MCP compatibility:
+
+1. `requirements`
+2. `architecture`
+3. `implementation`
+4. `testing`
+
+The internal phase sequence becomes:
+
+```text
+requirements
+  -> architecture
+  -> implementation
+  -> execution (apply only)
+  -> testing
+  -> acceptance
+  -> complete
+```
+
+The existing `implementation` phase becomes plan-only in both execution modes. The implementer receives a read-only role prompt and writes `implementation-plan.md`. Approving the `implementation` gate advances plan mode directly to `testing`, while apply mode advances to the new nongated `execution` phase.
+
+The `execution` phase runs the implementer in an isolated worktree, writes `implementation-review.md`, and advances to `testing` with status `ready`. The next `continue` runs the tester and verification commands in the same worktree, then opens the `testing` gate.
+
+Approving the `testing` gate applies the captured patch to the original repository, removes the worktree, and advances to acceptance. Rejecting the testing gate leaves the worktree isolated. The rejection feedback can be answered, after which the run returns to `execution` so the implementer can revise the existing isolated changes.
+
+## Apply Isolation
+
+### Workspace creation
+
+Before the first execution attempt DevCrew must:
+
+1. Confirm the requester repository is a Git repository with a clean working tree, excluding DevCrew runtime and artifact paths.
+2. Record the current `HEAD` as `baseCommit`.
+3. Create a detached worktree under `.devcrew/worktrees/<run-id>`.
+4. Persist the worktree path and base commit before invoking the SDK role.
+
+All implementation, lint, test, and coverage commands run with the worktree as their working directory. Artifacts and state remain in the original repository.
+
+### Capturing all changes
+
+After the implementer returns DevCrew must normalize any commits created by the role back into worktree changes relative to `baseCommit`. This is safe because the worktree is owned by the run and has not been promoted.
+
+DevCrew then marks untracked files as intent-to-add inside the worktree and captures:
+
+- `git status --porcelain=v1 -z -uall` for changed paths.
+- `git diff --binary --no-ext-diff <baseCommit> --` for the complete patch.
+
+Using the base commit includes staged and unstaged changes. Intent-to-add makes new files visible in the patch. NUL-delimited status parsing avoids filename quoting and rename parsing bugs.
+
+### Promotion
+
+Before applying an approved patch DevCrew must re-check that the requester repository is clean and still points at `baseCommit`. If either condition changed, approval fails without deleting the worktree or mutating the requester repository.
+
+Promotion writes the captured patch under the run directory, applies it to the requester repository with `git apply --binary`, verifies the resulting requester diff matches the reviewed patch, and then removes the worktree. The promoted files remain uncommitted so the requester retains normal review and commit control.
+
+An empty apply patch is an error. Apply mode must never report successful implementation when no repository change was produced.
+
+## State Changes
+
+`RunState` gains optional execution workspace metadata:
+
+```ts
+interface ExecutionWorkspace {
+  path: string;
+  baseCommit: string;
+}
+```
+
+The `execution` phase is added to `PHASES`. Older state files without execution workspace metadata continue to load.
+
+Gate mutations use these rules:
+
+- Approving an already approved gate returns the unchanged state and does not append another approval.
+- Rejecting an already rejected gate returns the unchanged state and does not append duplicate feedback.
+- A pending gate can only be approved or rejected when it is the current phase gate and status is `awaiting_approval`.
+- `answer` is only legal while status is `awaiting_input` and the current gate is rejected.
+- Calls against `acceptance` or `complete` cannot move the run backwards.
+
+The service uses a new orchestrated approval entry point so testing approval can promote the patch before the core state advances.
+
+## Backend Rules
+
+After host/config backend resolution, workflow creation rejects this combination:
+
+```text
+executionMode=apply, backend=local
+```
+
+Plan mode keeps deterministic local fallback. Apply mode requires a real Codex or Claude SDK backend at every role phase.
+
+The implementation-plan role is forced to read-only behavior even when the run execution mode is apply. Only the new execution phase and apply-mode tester receive write/Bash capabilities.
+
+## Stdio Reliability
+
+The line processor validates that parsed JSON is a non-array object with `jsonrpc: "2.0"` and a string `method`. Invalid request objects receive JSON-RPC error `-32600` with `id: null` and do not enter the request queue.
+
+For queued requests, each returned task may reject to its caller, but the internal queue stores a recovered promise. One handler failure therefore cannot prevent later requests from executing.
+
+Existing parse error behavior remains `-32700`. Notifications without an ID remain response-free.
+
+## Version Discipline
+
+The next implementation version is `0.1.2`. The following must agree:
+
+- `package.json`
+- `package-lock.json`
+- `DEVCREW_VERSION`
+- generated Codex and Claude manifests
+- checked-in Codex manifest
+- checked-in Codex MCP npm package specifier
+- smoke client metadata and version assertions
+
+CI adds a checked-in plugin drift test that generates a fresh Codex plugin in a temporary directory and compares all generated text files with the checked-in bundle. Binary assets are checked by hash. Publication order is npm `0.1.2` first, then marketplace push, so the public plugin never references an unavailable npm version.
+
+## Error Handling
+
+- Worktree creation failure leaves the run in `execution/ready` with no role result recorded.
+- SDK failure leaves the isolated worktree available for diagnosis and retry.
+- Empty implementation patch fails before testing.
+- Verification failures remain visible in the testing artifact; automatic test verdict blocking remains P1.
+- Promotion precondition failure leaves the worktree and state intact for manual resolution.
+- Worktree cleanup runs only after successful promotion or explicit run rejection cleanup added in a later lifecycle feature.
+
+## Testing Strategy
+
+Tests are added before implementation and must demonstrate the original failures:
+
+- Implementation-plan approval occurs before the first writable role invocation.
+- Local apply start is rejected.
+- An implementer-created commit is converted into a complete reviewed patch.
+- Staged, unstaged, renamed, deleted, binary, and untracked files appear in review evidence.
+- Rejecting testing keeps changes outside the requester repository and supports revision.
+- Approving testing promotes exactly the reviewed patch.
+- Changed requester `HEAD` or dirty requester worktree blocks promotion.
+- Empty apply output fails.
+- Duplicate approvals/rejections are idempotent.
+- Complete runs cannot be reopened.
+- Answer outside `awaiting_input` fails.
+- JSON `null`, arrays, missing methods, and wrong JSON-RPC versions return `-32600`.
+- A rejected request handler does not block the next stdio request.
+- Checked-in plugin version and generated bundle match `DEVCREW_VERSION`.
+
+The final verification command remains `npm run validate`, followed by the isolated Codex marketplace smoke after `@shenlee/devcrew@0.1.2` is published.
+
+## Compatibility
+
+MCP tool names and gate names remain stable. Existing plan-mode callers continue using the same approve/continue sequence. Apply-mode sequencing gains one additional `continue` call for the execution phase before testing.
+
+Existing 0.1.1 run files remain loadable. Runs already in the old `implementation` phase are treated as implementation planning and cannot write code until their implementation gate is approved under the new state transition.

package/docs/workflow.md

@@ -16,14 +16,31 @@ 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. 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.
+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
+-> 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.
+
+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.
+
 `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`
@@ -38,7 +55,7 @@ Each main phase has a gate:
 - `implementation`
 - `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.
 
 ## State And Artifacts
 

package/package.json

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

package/packages/adapters/src/index.ts

@@ -102,7 +102,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."
@@ -128,6 +128,7 @@ function titleForPhase(phase: Phase): string {
     requirements: "Requirements",
     architecture: "Architecture",
     implementation: "Implementation Plan",
+    execution: "Implementation Review",
     testing: "Test Report",
     acceptance: "Acceptance",
     complete: "Acceptance",
@@ -293,8 +294,8 @@ 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 roleCanApply(input: Pick<RoleRunInput, "executionMode" | "phase">): boolean {
+  return input.executionMode === "apply" && (input.phase === "execution" || input.phase === "testing");
 }
 
 function codexSandboxForRole(input: RoleRunInput): CodexSandboxMode {

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");
 }

package/packages/core/src/store.ts

@@ -17,9 +17,16 @@ 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;
   return {
     ...parsed,
     executionMode: parsed.executionMode ?? "plan",
+    executionWorkspace:
+      executionWorkspace &&
+      typeof executionWorkspace.path === "string" &&
+      typeof executionWorkspace.baseCommit === "string"
+        ? executionWorkspace
+        : undefined,
     changedFiles: Array.isArray(parsed.changedFiles) ? parsed.changedFiles : [],
     implementationDiff: typeof parsed.implementationDiff === "string" ? parsed.implementationDiff : "",
     verification: Array.isArray(parsed.verification) ? parsed.verification : [],

package/packages/core/src/types.ts

@@ -6,6 +6,7 @@ export const PHASES = [
   "requirements",
   "architecture",
   "implementation",
+  "execution",
   "testing",
   "acceptance",
   "complete",
@@ -115,6 +116,11 @@ export interface VerificationResult {
   completedAt: string;
 }
 
+export interface ExecutionWorkspace {
+  path: string;
+  baseCommit: string;
+}
+
 export interface RunState {
   version: 1;
   runId: string;
@@ -122,6 +128,7 @@ export interface RunState {
   host: Host;
   mode: WorkflowMode;
   executionMode: ExecutionMode;
+  executionWorkspace?: ExecutionWorkspace;
   backend: BackendName;
   request: string;
   phase: Phase;

package/packages/core/src/version.ts

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

package/packages/core/src/workflow.ts

@@ -39,14 +39,17 @@ function newRunId(): string {
   return `dc-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
 }
 
-export function nextPhaseAfterGate(gate: GateName): RunState["phase"] {
-  const nextByGate: Record<GateName, RunState["phase"]> = {
-    requirements: "architecture",
-    architecture: "implementation",
-    implementation: "testing",
-    testing: "acceptance",
-  };
-  return nextByGate[gate];
+export function nextPhaseAfterGate(state: RunState, gate: GateName): RunState["phase"] {
+  switch (gate) {
+    case "requirements":
+      return "architecture";
+    case "architecture":
+      return "implementation";
+    case "implementation":
+      return state.executionMode === "apply" ? "execution" : "testing";
+    case "testing":
+      return "acceptance";
+  }
 }
 
 export function artifactForPhase(phase: RunState["phase"]): ArtifactName {
@@ -54,6 +57,7 @@ export function artifactForPhase(phase: RunState["phase"]): ArtifactName {
     requirements: "requirements",
     architecture: "architecture",
     implementation: "implementation-plan",
+    execution: "implementation-review",
     testing: "test-report",
     acceptance: "acceptance",
     complete: "acceptance",
@@ -68,10 +72,17 @@ export function gateForPhase(phase: RunState["phase"]): GateName | undefined {
   return undefined;
 }
 
-function assertCurrentGate(state: RunState, gate: GateName): void {
+function assertPendingCurrentGate(state: RunState, gate: GateName): void {
   const expected = gateForPhase(state.phase);
-  if (expected && expected !== gate) {
-    throw new Error(`Cannot act on ${gate} while current gate is ${expected}`);
+  if (expected !== gate) {
+    throw new Error(
+      expected
+        ? `Cannot act on ${gate} while current gate is ${expected}`
+        : `Cannot act on ${gate} while workflow phase is ${state.phase}`,
+    );
+  }
+  if (state.status !== "awaiting_approval" || state.gates[gate] !== "pending") {
+    throw new Error(`Gate ${gate} is not pending approval`);
   }
 }
 
@@ -94,6 +105,9 @@ export async function startWorkflow(input: StartWorkflowInput, options: Workflow
   const config = await ensureConfig(cwd);
   const backend = input.backend ? parseBackend(input.backend) : config.defaultBackend === "host-preferred" ? host : config.defaultBackend;
   const executionMode = input.executionMode ? parseExecutionMode(input.executionMode) : config.executionMode;
+  if (executionMode === "apply" && backend === "local") {
+    throw new Error("DevCrew apply mode requires a codex or claude backend; local is plan-only");
+  }
   const createdAt = now();
   const state: RunState = {
     version: 1,
@@ -149,6 +163,10 @@ export async function continueWorkflow(input: RunRef): Promise<RunState> {
     return saveState(state);
   }
 
+  if (state.phase === "execution") {
+    throw new Error("DevCrew execution phase requires orchestrated continuation");
+  }
+
   const gate = gateForPhase(state.phase);
   if (!gate) {
     state.status = "complete";
@@ -160,10 +178,23 @@ export async function continueWorkflow(input: RunRef): Promise<RunState> {
   return saveState(state);
 }
 
-export async function approveWorkflow(input: ApproveWorkflowInput): Promise<RunState> {
+export async function validateWorkflowApproval(input: ApproveWorkflowInput): Promise<RunState> {
   const state = await getWorkflowStatus(input);
   const gate = parseGate(input.gate);
-  assertCurrentGate(state, gate);
+  if (state.gates[gate] === "approved") {
+    return state;
+  }
+  assertPendingCurrentGate(state, gate);
+  parseOptionalNote(input.note);
+  return state;
+}
+
+export async function approveWorkflow(input: ApproveWorkflowInput): Promise<RunState> {
+  const state = await validateWorkflowApproval(input);
+  const gate = parseGate(input.gate);
+  if (state.gates[gate] === "approved") {
+    return state;
+  }
   state.gates[gate] = "approved";
   state.approvals.push({
     gate,
@@ -171,7 +202,7 @@ export async function approveWorkflow(input: ApproveWorkflowInput): Promise<RunS
     createdAt: now(),
   });
 
-  const nextPhase = nextPhaseAfterGate(gate);
+  const nextPhase = nextPhaseAfterGate(state, gate);
   state.phase = nextPhase;
   state.status = "ready";
   return saveState(state);
@@ -180,7 +211,10 @@ export async function approveWorkflow(input: ApproveWorkflowInput): Promise<RunS
 export async function rejectWorkflow(input: RejectWorkflowInput): Promise<RunState> {
   const state = await getWorkflowStatus(input);
   const gate = parseGate(input.gate);
-  assertCurrentGate(state, gate);
+  if (state.gates[gate] === "rejected") {
+    return state;
+  }
+  assertPendingCurrentGate(state, gate);
   state.gates[gate] = "rejected";
   state.status = "awaiting_input";
   state.feedback.push({
@@ -193,15 +227,16 @@ export async function rejectWorkflow(input: RejectWorkflowInput): Promise<RunSta
 
 export async function answerWorkflow(input: AnswerWorkflowInput, options: WorkflowMutationOptions = {}): Promise<RunState> {
   const state = await getWorkflowStatus(input);
+  const gate = gateForPhase(state.phase);
+  if (state.status !== "awaiting_input" || !gate || state.gates[gate] !== "rejected") {
+    throw new Error("Workflow must be awaiting_input at a rejected current gate before recording an answer");
+  }
   state.answers.push({
     answer: parseAnswer(input.answer),
     createdAt: now(),
   });
-  const gate = gateForPhase(state.phase);
-  if (gate) {
-    state.gates[gate] = "pending";
-    state.status = "awaiting_approval";
-  }
+  state.gates[gate] = "pending";
+  state.status = "awaiting_approval";
   if (!options.skipArtifactWrite) {
     await writeCurrentArtifact(state);
   }