@shenlee/devcrew 0.1.2 → 0.1.4

package/docs/superpowers/specs/2026-07-13-execution-boundaries-design.md

@@ -0,0 +1,126 @@
+# DevCrew Execution Boundaries Design
+
+## Goal
+
+Make DevCrew's approval, verification, and role boundaries match its public
+product claims. Interactive work must execute through the host agent's native
+permission model. Headless work may use host SDKs only under an explicit,
+auditable DevCrew execution policy.
+
+## Scope
+
+This change is delivered in three independently releasable slices:
+
+1. Safety semantics: explicit execution policy and verification-failure
+   promotion blocking.
+2. Workflow semantics: execution-time architecture compliance review and
+   structured role questions/results.
+3. Productisation: effective artifact configuration and real-host integration
+   coverage.
+
+The existing isolated Git worktree and binary patch promotion remain the sole
+mechanism for moving apply-mode changes into the requester repository.
+
+## Execution Planes
+
+### Interactive host plane
+
+Interactive Codex and Claude Code workflows do not invoke the Codex or Claude
+SDK to modify repository files. DevCrew MCP owns durable workflow state,
+artifacts, gate validation, execution worktree creation, patch capture, and
+promotion. It exposes a structured execution instruction containing the role,
+worktree path, approved context, and required result schema. The active host
+agent or a native host subagent performs the work with the host's ordinary
+sandbox and approval UI, then submits the result to DevCrew.
+
+This plane must never claim that a nested SDK session inherits the interactive
+host's current approval decisions.
+
+### Headless SDK plane
+
+Headless and CI workflows retain SDK orchestration, but `apply` requires an
+explicit `executionPolicy`. The initial policy set is:
+
+- `interactive-host`: no nested SDK execution; valid only for an interactive
+  host integration.
+- `headless-restricted`: SDK execution in the DevCrew worktree with a declared
+  minimal tool surface and no hidden user-prompt assumption.
+- `headless-unattended`: an explicitly opted-in unattended SDK policy for CI;
+  its audit record makes the autonomy clear.
+
+The policy, backend, allowed capabilities, and any waiver are recorded in run
+state and shown in review artifacts. `acceptEdits`, bare `allowedTools`, and an
+implicit Codex approval policy are not described as inherited host approvals.
+
+## Verification And Promotion
+
+After isolated testing, DevCrew computes a verification status:
+
+- `passed`: every configured or discovered verification command exited zero.
+- `failed`: at least one command exited nonzero or timed out.
+- `not_run`: no verification command was available.
+
+Only `passed` can open the normal `testing` approval gate. A failed result
+moves the run to `awaiting_input` with the failure evidence and preserves the
+worktree. A requester may either supply feedback that returns the run to
+`execution`, or invoke a dedicated risk-waiver operation with a non-empty
+reason. The waiver is persistent, appears in the test report and acceptance
+artifact, and is the only path that can open a testing approval gate after a
+failed verification.
+
+`not_run` remains reviewable but is visibly distinct from `passed`; it cannot
+be silently represented as successful verification.
+
+## Execution-Time Architecture Review
+
+The current implementation-plan gate approves a plan and cannot approve the
+subsequent code diff. Add an `implementation-review` gate after execution and
+before testing. The architect role receives the approved architecture artifact,
+captured binary diff, changed-file list, lint evidence, and structured
+implementation result. It returns a structured compliance decision.
+
+Only an approved implementation review advances to testing. Rejection records
+feedback and returns to execution with the existing isolated worktree intact.
+The existing `implementation-review.md` remains an artifact, but becomes the
+architect's real review output rather than a rendered checklist.
+
+## Structured Role Results And Clarification
+
+Each role result is a validated JSON envelope with a Markdown body plus
+role-specific fields. At minimum, PM returns `questions`, architect returns a
+compliance decision, implementer returns changed-file and command evidence, and
+tester returns case/evidence summaries. Markdown remains the human-facing
+artifact format.
+
+If PM returns one or more questions, requirements enter `awaiting_input`
+without opening an approval gate. `devcrew_answer` records the answer and
+re-runs PM. A requirements gate opens only when the PM result has no open
+questions.
+
+## Configuration
+
+`workflow.artifactDirectory` is used by all artifact path helpers, relative to
+the repository root and validated to remain within that root. Core safety gates
+are not freely removable. `workflow.gates` is replaced or constrained by a
+validated sequence that must include requirements, architecture,
+implementation, implementation-review, and testing for apply workflows.
+
+## Integration Coverage
+
+Add tests for failed verification, risk waiver, no-verification status,
+architecture-review rejection/revision, structured PM questions, and configured
+artifact output. Preserve existing worktree-promotion coverage.
+
+The production-like Codex marketplace smoke remains plan-mode and must verify
+the published package version. Add isolated integration coverage for the
+interactive execution handoff protocol and a real Claude plugin install/start
+smoke. A real unattended apply smoke uses only a disposable fixture repository
+and an explicitly selected headless policy.
+
+## Non-goals
+
+- Do not remove worktree isolation or binary patch promotion.
+- Do not automatically approve failed verification.
+- Do not make arbitrary workflow graph customisation part of this release.
+- Do not use generated role files as an execution mechanism until a host-native
+  integration consumes them explicitly.

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.

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,30 @@ 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.
+
+`devcrew_abort` stops a nonterminal run with a required reason. It preserves the
+run state and artifacts for audit, removes its isolated worktree when possible,
+and clears the active-run pointer only when it refers to that run. An aborted
+run cannot continue. `devcrew_recover` never runs an agent: it explicitly
+clears only a confirmed stale repository lock and retries cleanup for a
+terminal run that retained an isolated worktree.
+
+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`. Submitting
+`devcrew_answer` then returns the run to `execution/ready` in the same
+isolated worktree, resets that review gate, and requires a new implementation
+pass followed by a later approving review before testing can start.
 
 `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 +69,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 +106,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.4",
   "description": "Multi-host agent workflow service for Codex and Claude Code.",
   "type": "module",
   "license": "Apache-2.0",