@shenlee/devcrew 0.1.3 → 0.1.4

package/docs/superpowers/plans/2026-07-14-reliability-recovery.md

@@ -0,0 +1,208 @@
+# Configuration Integrity and Run Recovery Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Reject unsafe configuration, prevent concurrent MCP mutations from overwriting one another, and make interrupted runs explicitly abortable and recoverable.
+
+**Architecture:** A strict version-1 parser validates `.devcrew/config.json` and keeps artifact paths inside the requester repository. A repository-wide atomic directory lock wraps MCP mutations while read-only calls remain available. Aborting is a persisted terminal state that preserves audit data; recovery only clears a confirmed stale lock and retries cleanup of a terminal run's residual worktree.
+
+**Tech Stack:** TypeScript, Node.js `fs/promises`, Node test runner, Git worktrees, MCP tool registry.
+
+---
+
+### Task 1: Validate configuration and artifact paths
+
+**Files:**
+- Modify: `packages/core/src/config.ts`
+- Modify: `tests/core.test.ts`
+
+- [ ] **Step 1: Write failing configuration tests**
+
+Add table-driven tests that write `.devcrew/config.json`, then call
+`startWorkflow`. Cover an unknown top-level key, an unknown workflow key, an
+unknown gate, a duplicate gate, an empty command, an absolute
+`artifactDirectory`, and `../outside`. Each test asserts the error identifies
+the invalid field. Add a valid custom artifact directory assertion so the
+existing supported path remains accepted.
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+node --import tsx --test tests/core.test.ts
+```
+
+Expected: new invalid-config cases fail because `readConfig` currently merges
+untyped JSON and `artifactDirectory` is only joined to `cwd`.
+
+- [ ] **Step 3: Implement a strict version-1 parser**
+
+In `config.ts`, parse JSON as `unknown`, require plain objects, reject keys
+outside the documented schema, validate enum values from exported type
+constants, and validate arrays as non-empty trimmed strings with no invalid
+gate entries or duplicates. Resolve `workflow.artifactDirectory` against
+`cwd`; reject absolute values and any resolved path whose relative path leaves
+the repository. Return the normalized validated `DevCrewConfig`.
+
+- [ ] **Step 4: Verify GREEN and commit**
+
+Run:
+
+```bash
+node --import tsx --test tests/core.test.ts
+git add packages/core/src/config.ts tests/core.test.ts
+git commit -m "fix: validate DevCrew configuration strictly"
+```
+
+Expected: all core tests pass and invalid configuration fails before a run is
+created.
+
+### Task 2: Add explicit repository mutation locks
+
+**Files:**
+- Create: `packages/core/src/lock.ts`
+- Modify: `packages/core/src/paths.ts`
+- Modify: `packages/core/src/index.ts`
+- Modify: `packages/service/src/tools.ts`
+- Modify: `tests/core.test.ts`
+- Modify: `tests/service.test.ts`
+
+- [ ] **Step 1: Write failing lock tests**
+
+Add core tests that hold a repository lock while a second acquisition rejects
+with a busy error, then release the first lock and acquire again. Create a
+lock directory with metadata containing a non-running pid and assert normal
+acquisition still refuses it while explicit stale-lock recovery removes it.
+Add a service test that holds the lock, verifies `devcrew_status` still works,
+and verifies a mutating `devcrew_approve` returns a structured busy error.
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+node --import tsx --test tests/core.test.ts tests/service.test.ts
+```
+
+Expected: imports fail because no repository lock API exists and MCP calls do
+not serialize mutations.
+
+- [ ] **Step 3: Implement lock primitives**
+
+Add `repositoryLockPath`, then implement `withRepositoryLock(cwd, action)`
+using atomic `mkdir`. Store `{ ownerId, pid, createdAt }` in `lock.json`,
+remove only the held owner directory in `finally`, and reject existing locks
+without waiting. Implement `recoverRepositoryLock(cwd)` to remove only a
+missing/invalid/dead-local-process lock; it must reject a live owner and must
+never run automatically.
+
+- [ ] **Step 4: Wrap MCP mutation dispatch**
+
+In `callDevCrewTool`, route start, answer, approve, reject, continue,
+complete-execution, waive-verification, abort, and recovery cleanup through a
+single lock wrapper. Resolve an omitted run id inside the lock. Keep status and
+artifact calls unlocked. Ensure start creates its run and sets `active-run`
+under one lock.
+
+- [ ] **Step 5: Verify GREEN and commit**
+
+Run:
+
+```bash
+node --import tsx --test tests/core.test.ts tests/service.test.ts
+git add packages/core/src/lock.ts packages/core/src/paths.ts packages/core/src/index.ts packages/service/src/tools.ts tests/core.test.ts tests/service.test.ts
+git commit -m "fix: serialize DevCrew MCP mutations"
+```
+
+Expected: concurrent writes return a structured busy error and reads remain
+available.
+
+### Task 3: Persist terminal aborts and recover residual worktrees
+
+**Files:**
+- Modify: `packages/core/src/types.ts`
+- Modify: `packages/core/src/active-run.ts`
+- Modify: `packages/core/src/workflow.ts`
+- Modify: `packages/orchestrator/src/index.ts`
+- Modify: `packages/service/src/tools.ts`
+- Modify: `docs/workflow.md`
+- Modify: `tests/core.test.ts`
+- Modify: `tests/orchestrator.test.ts`
+- Modify: `tests/service.test.ts`
+
+- [ ] **Step 1: Write failing abort and recovery tests**
+
+Add a workflow test that aborts a nonterminal state with a reason, asserts
+`status: "aborted"`, persisted reason/timestamp, and that continue/answer/
+complete cannot resume it. Add an apply-worktree test that aborts after
+execution, confirms the requester checkout is unchanged and the isolated
+worktree is removed. Add a service test that `devcrew_abort` clears its active
+run and that a repeated abort is idempotent. Add a recovery test for an
+aborted state retaining a workspace reference: recovery cleans that worktree
+and clears the reference without running a role.
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+node --import tsx --test tests/core.test.ts tests/orchestrator.test.ts tests/service.test.ts
+```
+
+Expected: tests fail because `aborted` is not a run status and no abort or
+recovery tool exists.
+
+- [ ] **Step 3: Implement terminal abort state**
+
+Add `RunAbort` plus `RunStatus: "aborted"`; persist the first non-empty abort
+reason and timestamp. Add `abortWorkflow` with terminal idempotency, and make
+continuation return aborted runs unchanged. Add
+`clearActiveRunIfMatches(cwd, runId)` so an abort never clears another run's
+active pointer.
+
+- [ ] **Step 4: Implement orchestration and MCP lifecycle tools**
+
+Add `abortOrchestratedWorkflow` to persist abort audit state before attempting
+worktree cleanup. On cleanup success clear `executionWorkspace`; on failure
+leave it for recovery. Add `recoverOrchestratedWorkflow` that accepts only
+terminal runs and retries this cleanup. Register `devcrew_abort` and
+`devcrew_recover`, with schemas and structured errors, and apply the lock
+rules from Task 2. Update `docs/workflow.md` with abort/recover semantics.
+
+- [ ] **Step 5: Verify GREEN and commit**
+
+Run:
+
+```bash
+node --import tsx --test tests/core.test.ts tests/orchestrator.test.ts tests/service.test.ts
+git add packages/core/src/types.ts packages/core/src/active-run.ts packages/core/src/workflow.ts packages/orchestrator/src/index.ts packages/service/src/tools.ts docs/workflow.md tests/core.test.ts tests/orchestrator.test.ts tests/service.test.ts
+git commit -m "feat: add DevCrew abort and recovery controls"
+```
+
+Expected: aborted runs retain audit evidence, cannot resume, clean their
+worktrees when possible, and can explicitly retry residual cleanup.
+
+### Task 4: Full verification
+
+**Files:**
+- Verify: all modified files
+
+- [ ] **Step 1: Run repository validation**
+
+```bash
+npm run validate
+```
+
+Expected: TypeScript build succeeds and every test passes.
+
+- [ ] **Step 2: Inspect final state**
+
+```bash
+git diff main...HEAD --check
+git status --short
+git log --oneline main..HEAD
+```
+
+Expected: no whitespace errors, clean worktree, and only the design, plan,
+and implementation commits on the branch.

package/docs/superpowers/plans/2026-07-14-structured-role-results.md

@@ -0,0 +1,231 @@
+# Structured Role Results Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Accept validated, versioned role-result envelopes while preserving Markdown-only SDK outputs and expose structured evidence through run state, artifacts, and MCP.
+
+**Architecture:** The core package owns envelope types and state migration. The adapter recognizes one explicitly marked JSON block, validates role-specific data, and returns Markdown with the protocol block removed. The orchestrator uses the normalized result without changing gates; artifacts render a human-readable appendix, and MCP continues returning the persisted state.
+
+**Tech Stack:** TypeScript strict mode, Node.js built-in test runner, `tsx`.
+
+---
+
+### Task 1: Define normalized envelope types and old-state migration
+
+**Files:**
+- Modify: `packages/core/src/types.ts:91-100`
+- Modify: `packages/core/src/store.ts:24-70`
+- Test: `tests/core.test.ts`
+
+- [ ] **Step 1: Write the failing migration test**
+
+Append this test to `tests/core.test.ts`:
+
+```ts
+test("loadState marks pre-envelope role results as legacy", async () => {
+  const cwd = await tempProject();
+  const started = await startWorkflow({ cwd, host: "codex", mode: "feature", request: "Migrate roles" });
+  const path = runDir(cwd, started.runId);
+  const raw = JSON.parse(await readFile(join(path, "state.json"), "utf8")) as Record<string, unknown>;
+  raw.roles = [{ role: "pm", backend: "codex", summary: "old", markdown: "# Old", usedFallback: false }];
+  await writeFile(join(path, "state.json"), JSON.stringify(raw));
+
+  const role = (await loadState(cwd, started.runId)).roles[0] as unknown as { format?: string };
+  assert.equal(role.format, "legacy");
+});
+```
+
+- [ ] **Step 2: Verify it fails**
+
+Run: `npm test -- --test-name-pattern="pre-envelope role"`
+
+Expected: FAIL because `RoleResult.format` does not exist.
+
+- [ ] **Step 3: Add the smallest normalized types and migration**
+
+Add these exports in `packages/core/src/types.ts` and make `format` mandatory on `RoleResult`:
+
+```ts
+export interface CommandEvidence {
+  command: string;
+  exitCode: number;
+  output?: string;
+}
+
+export interface RoleQuestion {
+  id: string;
+  prompt: string;
+  context?: string;
+}
+
+export interface StructuredRoleData {
+  schemaVersion: 1;
+  role: Exclude<RoleResult["role"], "conductor">;
+  summary: string;
+  risks: string[];
+  evidence: CommandEvidence[];
+  questions?: RoleQuestion[];
+  decisions?: string[];
+  reviewDecision?: ArchitectureReviewDecision;
+  changedFiles?: string[];
+  testCases?: Array<{ id: string; scenario: string; type: "happy" | "edge" | "failure" | "regression"; expected: string }>;
+}
+```
+
+In `loadState`, map each persisted role missing a valid `format` to `{ ...role, format: "legacy" }`, leaving all prior persisted fields intact.
+
+- [ ] **Step 4: Verify it passes**
+
+Run: `npm test -- --test-name-pattern="pre-envelope role"`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/core/src/types.ts packages/core/src/store.ts tests/core.test.ts
+git commit -m "feat: normalize persisted role results"
+```
+
+### Task 2: Parse and validate the marked envelope in adapters
+
+**Files:**
+- Modify: `packages/adapters/src/index.ts:69-102,143-162,424-459`
+- Test: `tests/adapters.test.ts`
+
+- [ ] **Step 1: Write failing parser tests**
+
+Export `parseRoleResultOutput` and add tests that call it with this valid PM output and each invalid variation:
+
+```ts
+const output = `<!-- devcrew-role-result -->
+\`\`\`json
+{"schemaVersion":1,"role":"pm","summary":"Need scope","risks":[],"evidence":[],"questions":[{"id":"format","prompt":"Which formats?"}]}
+\`\`\`
+# Requirements
+
+## Functional Scope
+`;
+const result = parseRoleResultOutput("pm", "requirements", output);
+assert.equal(result.format, "structured");
+assert.deepEqual(result.questions, ["Which formats?"]);
+assert.doesNotMatch(result.markdown, /devcrew-role-result/);
+```
+
+Add separate `assert.throws` tests for malformed marked JSON, two marked blocks, `schemaVersion: 2`, role mismatch, duplicate/blank PM question IDs, and a non-integer command exit code. Add a Markdown-only test proving `format === "legacy"` and existing PM/review parsing remain unchanged.
+
+- [ ] **Step 2: Verify they fail**
+
+Run: `npm test -- --test-name-pattern="role result output"`
+
+Expected: FAIL because `parseRoleResultOutput` is not exported.
+
+- [ ] **Step 3: Implement the protocol parser and prompt contract**
+
+Implement a parser that finds exactly one `<!-- devcrew-role-result -->` followed by a `json` fenced block. When no marker exists, return the original Markdown and `format: "legacy"`; when a marker exists, reject malformed or invalid data. Require all common fields, role-matching field sets, unique PM question IDs, nonempty strings, and integer command exit codes. Return the Markdown with only the marked block removed.
+
+Add this exact prompt guidance before `Required Sections`:
+
+```ts
+"Return this protocol block first:",
+"<!-- devcrew-role-result -->",
+"```json",
+"{\"schemaVersion\":1,\"role\":\"<current role>\",\"summary\":\"...\",\"risks\":[],\"evidence\":[]}",
+"```",
+"Then return the required Markdown H2 sections. Do not include a second marked result block.",
+```
+
+Replace direct Markdown extraction in `runRole` with the parser's normalized result. For legacy output, keep `extractOpenQuestions` and `extractArchitectureReviewDecision`; for structured output, derive those compatibility fields from validated structured data.
+
+- [ ] **Step 4: Verify adapter tests pass**
+
+Run: `npm test -- tests/adapters.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/adapters/src/index.ts tests/adapters.test.ts
+git commit -m "feat: parse structured role result envelopes"
+```
+
+### Task 3: Persist and render structured implementation and test evidence
+
+**Files:**
+- Modify: `packages/orchestrator/src/index.ts:317-344,456-481`
+- Test: `tests/orchestrator.test.ts`
+
+- [ ] **Step 1: Write failing workflow tests**
+
+Add a structured PM runner result with a question and assert `awaiting_input`. Add an implementation result with `format: "structured"` and `structured.changedFiles` plus command evidence, then assert the persisted role retains them and `implementation-review.md` contains `## Structured Role Result` and the command/exit code. Add an analogous tester assertion for `test-report.md` risks and evidence.
+
+- [ ] **Step 2: Verify they fail**
+
+Run: `npm test -- --test-name-pattern="structured (PM|implementation|tester)"`
+
+Expected: FAIL because artifacts do not render structured role data.
+
+- [ ] **Step 3: Render the structured appendix without changing workflow evidence sources**
+
+Add an orchestrator artifact helper used by `appendExecutionSections` that renders `state.roles.at(-1)?.structured` only when `format === "structured"`. It must show schema version, summary, changed files, command evidence, test cases, risks, and questions when present, escaping no data and preserving the role's Markdown body as the primary artifact.
+
+Keep the existing captured Git diff and configured verification as authoritative promotion evidence. Structured implementation `changedFiles` and tester commands are supplemental role assertions, not a way to overwrite `state.changedFiles`, `state.implementationDiff`, or `state.verification`.
+
+In the orchestrator, use structured PM question prompts for `pendingQuestions` and structured review decisions for `architectureReview`; preserve the existing compatibility fields so legacy runners and callers continue to work.
+
+- [ ] **Step 4: Verify workflow tests pass**
+
+Run: `npm test -- tests/orchestrator.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/orchestrator/src/index.ts tests/orchestrator.test.ts
+git commit -m "feat: render structured role evidence"
+```
+
+### Task 4: Surface format and results through MCP and complete regression checks
+
+**Files:**
+- Modify: `packages/service/src/tools.ts:215-320`
+- Test: `tests/service.test.ts`
+- Modify: `docs/codex.md`
+- Modify: `docs/claude-code.md`
+
+- [ ] **Step 1: Write the failing MCP test**
+
+Start a workflow with a structured PM runner, invoke `devcrew_status`, and assert its text includes `role_format=structured` plus `structuredContent.state.roles.at(-1).structured.questions[0].id === "format"`. The test must use `callDevCrewTool`, not inspect the state file directly.
+
+- [ ] **Step 2: Verify it fails**
+
+Run: `npm test -- --test-name-pattern="MCP.*structured role"`
+
+Expected: FAIL until the state summary exposes the normalized role format.
+
+- [ ] **Step 3: Keep MCP state safe and document the migration**
+
+Return the existing state object unchanged except for its newly persisted normalized role fields; do not create a second incompatible tool response shape. Extend `summarizeState` with `role_format=<legacy|structured|none>`.
+
+Document the marker, schema version, legacy fallback rule, and the rule that malformed marked output is rejected rather than downgraded in both host guides.
+
+- [ ] **Step 4: Verify the focused service test passes**
+
+Run: `npm test -- tests/service.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 5: Run complete validation and inspect the patch**
+
+Run: `npm run validate && npm test && git diff main...HEAD --check`
+
+Expected: validation and all tests pass; whitespace check prints no output.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/service/src/tools.ts tests/service.test.ts docs/codex.md docs/claude-code.md
+git commit -m "docs: describe structured role result migration"
+```

package/docs/superpowers/specs/2026-07-14-p0-remediation-design.md

@@ -0,0 +1,52 @@
+# P0 Verification and Review Remediation Design
+
+## Goal
+
+Close two apply-mode safety gaps: a run with no verification evidence must not
+be promoted without an explicit waiver, and an architecture review that requires
+changes must return to implementation before it can be reviewed again.
+
+## Verification Gate Semantics
+
+`passed` is the only verification status that opens the normal `testing` gate.
+Both `failed` and `not_run` set the testing gate to `rejected` and move the run
+to `awaiting_input` with evidence explaining the condition.
+
+The existing `devcrew_waive_verification` operation is the sole exception path
+for either `failed` or `not_run`. It requires a non-empty requester risk reason,
+persists the waiver, and reopens the testing gate. Promotion additionally
+defends this invariant: any status other than `passed` requires a recorded
+waiver, even if an invalid state was written by an older client.
+
+## Architecture Review Remediation
+
+When the architect returns `changes_required`, DevCrew continues to record the
+decision, artifact, and feedback, while keeping the isolated execution
+worktree. The implementation-review gate becomes `rejected` and the run enters
+`awaiting_input`.
+
+After `devcrew_answer`, DevCrew records the response then transitions the same
+run to `execution/ready`. It resets the implementation-review gate to
+`not_started`; it does not run another architect review. A subsequent
+`devcrew_continue` invokes the implementer in the existing worktree, captures a
+new diff, and schedules a fresh architecture review. This mirrors the existing
+testing-rejection remediation flow.
+
+## Error Handling and Compatibility
+
+Existing persisted runs remain readable. A legacy run with `not_run` cannot be
+promoted unless it has a waiver. The waiver tool's error message and validation
+are expanded from "failed verification" to "failed or missing verification".
+No new MCP tool or public state field is required.
+
+## Acceptance Tests
+
+1. Apply-mode testing with no discovered or configured commands results in
+   `verificationStatus: not_run`, `testing: rejected`, and `awaiting_input`.
+2. A non-empty waiver can reopen that `not_run` testing gate; an empty reason or
+   a run outside `failed`/`not_run` is rejected.
+3. Promotion rejects `not_run` without a waiver even if a caller manufactured a
+   pending testing gate.
+4. An architect `changes_required` decision followed by `devcrew_answer`
+   transitions to `execution/ready` in the existing worktree, and the next
+   continuation invokes the implementer rather than the architect.

package/docs/superpowers/specs/2026-07-14-reliability-recovery-design.md

@@ -0,0 +1,92 @@
+# Configuration Integrity and Run Recovery Design
+
+## Goal
+
+Reject unsafe DevCrew configuration before a workflow starts, serialize every
+repository-mutating MCP operation, and give a requester an explicit, auditable
+way to stop or recover an interrupted run without executing work automatically.
+
+## Scope
+
+This change covers configuration validation, repository mutation locking,
+terminal aborted runs, `devcrew_abort`, and `devcrew_recover`. It does not add
+automatic run resumption, change execution permissions, or introduce a remote
+lock service.
+
+## Configuration Contract
+
+`readConfig` validates the complete version-1 shape rather than merging
+untyped JSON into defaults.
+
+- Top-level keys are limited to `version`, `defaultBackend`, `executionMode`,
+  `verifyCommands`, `lintCommands`, `coverageCommands`, and `workflow`.
+- `defaultBackend`, `executionMode`, and every workflow gate must be members
+  of their exported enums.
+- Command lists, when supplied, must be arrays of non-empty strings. Empty
+  lists remain valid; omitted command lists retain their version-1 default of
+  an empty array for backward compatibility.
+- `workflow` may contain only `gates` and `artifactDirectory`; gates must be
+  unique. The existing runtime rule still makes implementation review and
+  testing mandatory.
+- `artifactDirectory` must be a non-empty relative path whose resolved target
+  is inside the requester repository. Absolute paths and traversal outside the
+  repository are rejected before any artifact is written.
+
+Unknown keys and invalid values fail closed with an error that names the
+offending field. Existing default configuration remains valid.
+
+## Repository Mutation Lock
+
+All MCP operations that can write a run, active-run pointer, artifact, or
+execution worktree take one repository-wide lock at `.devcrew/lock` for their
+full operation. This includes start, answer, approve, reject, continue,
+complete-execution, waive-verification, abort, and recovery cleanup. Status
+and artifact reads remain unlocked.
+
+The lock is an atomically-created directory containing owner metadata:
+process id, a random owner id, and creation time. A second mutating request
+does not wait or retry; it returns a clear busy error and cannot overwrite the
+first operation's state. The holder removes only its own lock in `finally`.
+
+Normal operations never remove a lock they did not create. A lock whose owner
+metadata is absent, invalid, or refers to a non-running local process is
+considered stale, but it still requires the explicit recovery operation to
+remove it. This prevents a timeout heuristic from treating a long-running SDK
+call as abandoned.
+
+## Abort and Recovery Lifecycle
+
+`RunStatus` gains terminal `aborted`, and `RunState` records an abort reason
+and timestamp. An aborted run remains readable for audit but cannot continue,
+approve, reject, answer, or complete execution. Repeating abort is idempotent
+and preserves the first reason.
+
+`devcrew_abort` accepts `cwd`, optional `runId`, and a non-empty `reason`.
+Under the repository lock it records the abort, removes any isolated execution
+worktree, and clears `active-run.json` only when it points at that run. If
+worktree cleanup fails, the aborted state and audit evidence still persist;
+the workspace reference remains for recovery.
+
+`devcrew_recover` is explicit and never runs an agent or validation command.
+It may remove a confirmed stale lock. When given a terminal run that retains
+an execution workspace after an interrupted cleanup, it retries only that
+worktree cleanup and clears the persisted workspace reference on success. A
+live lock is never overridden.
+
+## MCP and Error Semantics
+
+The service exposes `devcrew_abort` and `devcrew_recover`. Both use the
+existing optional-run-id resolution where applicable. Tool results retain the
+current state summary; an aborted run reports `status=aborted`. Busy locks,
+invalid configuration, live-lock recovery, and invalid abort/recovery targets
+return normal structured MCP errors.
+
+## Tests
+
+- Config tests cover unknown fields, invalid enum/gate/command values,
+  duplicate gates, absolute artifact directories, and parent traversal.
+- Service tests cover lock contention between mutation calls, while reads stay
+  available.
+- Orchestrator/service tests cover abort audit persistence, worktree cleanup,
+  active-run clearing, idempotency, terminal-state blocking, stale-lock
+  recovery, and recovery cleanup after a simulated failed abort cleanup.

package/docs/superpowers/specs/2026-07-14-structured-role-results-design.md

@@ -0,0 +1,96 @@
+# Structured Role Results Design
+
+## Objective
+
+Make DevCrew role output machine-readable without breaking existing Markdown-only
+SDK output or the human-readable artifact workflow. A structured result becomes
+the canonical source for workflow decisions and evidence when it is present;
+Markdown remains the reviewable artifact body and the compatibility fallback.
+
+## Scope
+
+This change covers the PM, architect, implementer, and tester role results used
+by the SDK adapters and orchestrator. It does not remove Markdown artifacts,
+change MCP tool names, change execution policies, or require existing installed
+plugins to update simultaneously.
+
+## Result Envelope
+
+The core package will define a versioned role-result envelope with common fields:
+
+- `schemaVersion: 1`
+- `role`
+- `summary`
+- `risks`
+- `evidence`
+
+Role-specific fields are validated by role:
+
+- PM: `questions`, where each question has a stable `id`, prompt, and optional
+  context.
+- Architect: `decisions`; during the post-execution review phase,
+  `reviewDecision` is `approved` or `changes_required`.
+- Implementer: `changedFiles` and `commands`, including command, exit code, and
+  captured output.
+- Tester: `testCases`, `commands`, and `risks`.
+
+The canonical TypeScript representation stores a `format` discriminator:
+`structured` for a validated envelope and `legacy` for a Markdown-only result.
+This allows callers and MCP clients to identify migration state without parsing
+text.
+
+## Adapter Parsing And Compatibility
+
+SDK prompts will request one `<!-- devcrew-role-result -->` marker followed by a
+fenced `json` block containing the DevCrew result, then the existing required
+Markdown H2 sections. The marker avoids treating incidental JSON examples in a
+human artifact as protocol data. The adapter extracts and validates that JSON
+before accepting a structured result, removes the marked block, and uses the
+remaining Markdown as the role result's `markdown` field.
+
+If a JSON block is absent, the adapter preserves existing Markdown validation and
+the current PM-question and architecture-review decision parsing. It returns a
+`legacy` result and no new structured fields are inferred from arbitrary prose.
+
+If a DevCrew JSON block is present but malformed, has an unsupported schema
+version, does not match the active role, or fails field validation, the adapter
+rejects the SDK output. It must not silently downgrade malformed claimed
+structured output to legacy Markdown. Existing plan-mode fallback and apply-mode
+failure rules remain unchanged.
+
+## Workflow And Artifact Behaviour
+
+The orchestrator consumes validated structured fields when available. PM
+questions continue to route the run to `awaiting_input`; legacy Markdown
+questions retain the current behavior. Architecture review decisions retain
+their blocking semantics. Implementer and tester evidence is persisted in the
+role result, surfaced by MCP state, and rendered into the corresponding Markdown
+artifact as a readable structured-results appendix.
+
+The role result stored in run state must remain loadable when older saved states
+lack the new fields. Missing fields migrate to `format: legacy` and empty
+optional arrays. No saved state becomes invalid merely because it predates this
+feature.
+
+## Error Handling
+
+- No JSON envelope: accept the valid legacy Markdown result.
+- Multiple candidate envelopes: reject as ambiguous.
+- Invalid envelope: report field-specific validation errors.
+- Envelope role/phase mismatch: reject before state or artifact writes.
+- Structured PM questions: require nonempty unique IDs and nonempty prompts.
+- Command evidence: require a command and integer exit code; output is optional.
+
+## Testing
+
+Tests will be written before production code and prove:
+
+1. A valid envelope parses and exposes each role's structured fields.
+2. Missing envelope preserves legacy Markdown behavior.
+3. Malformed, ambiguous, version-invalid, and role-invalid envelopes fail rather
+   than downgrade.
+4. Structured PM questions enter `awaiting_input`.
+5. Structured architecture review decisions gate testing correctly.
+6. Implementer and tester evidence persists and is visible in generated
+   artifacts and structured MCP state.
+7. Loading a prior state without the new fields migrates safely.