@shenlee/devcrew 0.1.3 → 0.1.5

package/docs/superpowers/plans/2026-07-13-safety-semantics.md

@@ -1,313 +0,0 @@
-# Safety Semantics 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:** Make apply-mode execution policy explicit and prevent failed or absent verification from silently promoting an isolated patch.
-
-**Architecture:** Add a persistent execution policy and verification outcome to the workflow state. Interactive apply runs pause with a host-execution handoff instead of launching a nested SDK; explicitly selected headless policies retain SDK execution with declared permissions. Testing only opens a normal promotion gate after successful verification; a separate waiver records the reason before an exception can be approved.
-
-**Tech Stack:** TypeScript, Node.js test runner, MCP JSON-RPC tools, Git worktrees.
-
----
-
-## File Structure
-
-- Modify: `packages/core/src/types.ts` — policy, verification, handoff, and waiver state contracts.
-- Modify: `packages/core/src/validation.ts` — parse policy and waiver input.
-- Modify: `packages/core/src/workflow.ts` — default/apply-policy invariants and waiver transition.
-- Modify: `packages/core/src/store.ts` — migrate persisted legacy runs safely.
-- Modify: `packages/adapters/src/index.ts` — explicit headless SDK options; no implicit approval inheritance.
-- Modify: `packages/orchestrator/src/index.ts` — interactive execution pause/submission and verification gate blocking.
-- Modify: `packages/service/src/tools.ts` — MCP schemas and handlers for execution completion and verification waiver.
-- Modify: `packages/core/src/artifacts.ts` — render policy, verification status, and waiver evidence.
-- Modify: `tests/core.test.ts`, `tests/adapters-sdk.test.ts`, `tests/orchestrator.test.ts`, `tests/service.test.ts` — red/green coverage for every new state transition.
-- Modify: `README.md`, `docs/workflow.md`, `docs/codex.md`, `docs/claude-code.md`, `packages/plugins/src/index.ts` — correct public behavior and generated skill copy.
-
-### Task 1: Persist explicit execution and verification semantics
-
-**Files:**
-- Modify: `packages/core/src/types.ts`
-- Modify: `packages/core/src/validation.ts`
-- Modify: `packages/core/src/store.ts`
-- Test: `tests/core.test.ts`
-
-- [ ] **Step 1: Write failing state-contract tests**
-
-Add tests that start an apply workflow with `executionPolicy: "headless-restricted"`, assert the policy persists through `loadState`, and assert unknown policy values fail validation. Add a migration fixture without the new fields and assert it loads as an interactive-host apply run with `verificationStatus: "not_run"` and no waiver.
-
-```ts
-assert.equal(state.executionPolicy, "headless-restricted");
-await assert.rejects(
-  () => startWorkflow({ ...input, executionMode: "apply", executionPolicy: "unsafe" }),
-  /executionPolicy/,
-);
-assert.equal(loaded.verificationStatus, "not_run");
-```
-
-- [ ] **Step 2: Run the focused core test and verify RED**
-
-Run: `node --import tsx --test tests/core.test.ts`
-
-Expected: FAIL because `executionPolicy` and `verificationStatus` are not yet represented in state or input validation.
-
-- [ ] **Step 3: Add the minimal state and parsing contracts**
-
-In `types.ts`, add:
-
-```ts
-export const EXECUTION_POLICIES = ["interactive-host", "headless-restricted", "headless-unattended"] as const;
-export type ExecutionPolicy = (typeof EXECUTION_POLICIES)[number];
-export type VerificationStatus = "not_run" | "passed" | "failed";
-
-export interface VerificationWaiver { reason: string; createdAt: string; }
-```
-
-Add `executionPolicy` to `StartWorkflowInput` and `RunState`, plus
-`verificationStatus` and optional `verificationWaiver` to `RunState`. Add
-`parseExecutionPolicy()` and `parseWaiverReason()` in `validation.ts`. In
-`loadState`, use `interactive-host` for legacy apply runs and `not_run` for
-missing verification status.
-
-- [ ] **Step 4: Run the focused core test and verify GREEN**
-
-Run: `node --import tsx --test tests/core.test.ts`
-
-Expected: PASS, including new persistence and invalid-policy cases.
-
-- [ ] **Step 5: Commit the state contract**
-
-```bash
-git add packages/core/src/types.ts packages/core/src/validation.ts packages/core/src/store.ts tests/core.test.ts
-git commit -m "feat: record execution and verification policy"
-```
-
-### Task 2: Make SDK execution explicitly headless
-
-**Files:**
-- Modify: `packages/adapters/src/index.ts`
-- Test: `tests/adapters-sdk.test.ts`
-
-- [ ] **Step 1: Write failing adapter-policy tests**
-
-Replace the assertion that Claude apply uses `acceptEdits` with tests proving
-that an interactive-host execution is rejected before SDK invocation and that
-headless policies select explicit SDK options. For Claude restricted mode, the
-test must assert `permissionMode: "dontAsk"` and a narrow tool list. For Codex,
-assert `approvalPolicy: "never"` only for `headless-unattended` and no implicit
-approval-policy value for read-only planning.
-
-```ts
-await assert.rejects(
-  () => runRole({ ...baseInput, phase: "execution", executionMode: "apply", executionPolicy: "interactive-host", backend: "claude" }),
-  /interactive-host execution must be performed by the host/,
-);
-```
-
-- [ ] **Step 2: Run the focused adapter test and verify RED**
-
-Run: `node --import tsx --test tests/adapters-sdk.test.ts`
-
-Expected: FAIL because `RoleRunInput` lacks the policy and Claude currently
-sets `acceptEdits` with bare `Bash` permission.
-
-- [ ] **Step 3: Implement explicit headless profiles**
-
-Add `executionPolicy` to `RoleRunInput`. Make `roleCanApply()` require a
-headless policy. Reject SDK execution for `interactive-host`. Replace the
-Claude restricted profile with `dontAsk`: implementers receive only `Read`,
-`Grep`, `Glob`, `Edit`, and `Write`; testers receive only `Read`, `Grep`, and
-`Glob`. Neither restricted role receives `Bash`; DevCrew's configured command
-runner supplies verification evidence separately. For the explicitly selected
-unattended policy, add the SDK's dangerous-skip opt-in and set Claude to
-`bypassPermissions`; this is an auditable CI-only policy. Pass Codex
-`approvalPolicy: "never"` only for that unattended policy. Document that both
-headless profiles are DevCrew policies, not inherited host approval.
-
-- [ ] **Step 4: Run the focused adapter test and verify GREEN**
-
-Run: `node --import tsx --test tests/adapters-sdk.test.ts`
-
-Expected: PASS with no `acceptEdits` assertion remaining.
-
-- [ ] **Step 5: Commit the adapter boundary**
-
-```bash
-git add packages/adapters/src/index.ts tests/adapters-sdk.test.ts
-git commit -m "fix: make SDK apply policies explicit"
-```
-
-### Task 3: Add the interactive execution handoff
-
-**Files:**
-- Modify: `packages/orchestrator/src/index.ts`
-- Modify: `packages/service/src/tools.ts`
-- Test: `tests/orchestrator.test.ts`
-- Test: `tests/service.test.ts`
-
-- [ ] **Step 1: Write failing handoff tests**
-
-Add an apply workflow with `executionPolicy: "interactive-host"`. After the
-implementation gate is approved, `devcrew_continue` must create the isolated
-worktree but not call the injected `RoleRunner`; it returns
-`status: "awaiting_execution"` and structured instruction data. A new
-`devcrew_complete_execution` call captures the worktree patch and advances to
-testing without modifying the requester repository. Repeat the same handoff
-for the tester: it receives the test-report instruction, returns exact command
-result records, and DevCrew derives the verification status from those records.
-
-```ts
-assert.equal(paused.status, "awaiting_execution");
-assert.equal(runnerCalls.filter((call) => call.phase === "execution").length, 0);
-assert.equal(paused.executionInstruction?.cwd, paused.executionWorkspace?.path);
-```
-
-- [ ] **Step 2: Run focused orchestrator and service tests and verify RED**
-
-Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
-
-Expected: FAIL because the current orchestrator immediately invokes the SDK
-runner and no completion MCP tool exists.
-
-- [ ] **Step 3: Implement pause and completion transitions**
-
-Add `awaiting_execution` to `RunStatus` and an `ExecutionInstruction` state
-object containing role, phase, worktree cwd, request, standards, approved
-artifacts, and required result sections. In the execution and testing branches
-of `runCurrentPhaseRole`, ensure the worktree, write the instruction, persist
-the state, and return without calling `runner` or `runConfiguredVerification`
-when policy is `interactive-host`.
-
-Add `completeInteractiveExecution(input)` to orchestrator. It requires an
-`awaiting_execution` state and a required Markdown summary supplied by the
-host. For execution it captures changes, runs no nested SDK or shell command,
-writes implementation-review evidence, and moves to `testing/ready`. For
-testing it accepts a validated array of `{ command, exitCode, output,
-startedAt, completedAt }`, writes the test report, derives the verification
-status, and either opens the gate or enters the failure path. Expose it as
-`devcrew_complete_execution` with an input schema that includes `summary` and
-optional `verification` records.
-
-- [ ] **Step 4: Run focused handoff tests and verify GREEN**
-
-Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
-
-Expected: PASS; the requester repository remains unchanged until a later
-testing approval.
-
-- [ ] **Step 5: Commit the interactive handoff**
-
-```bash
-git add packages/orchestrator/src/index.ts packages/service/src/tools.ts tests/orchestrator.test.ts tests/service.test.ts
-git commit -m "feat: hand interactive apply execution to host"
-```
-
-### Task 4: Block failed verification and require a recorded waiver
-
-**Files:**
-- Modify: `packages/core/src/workflow.ts`
-- Modify: `packages/orchestrator/src/index.ts`
-- Modify: `packages/service/src/tools.ts`
-- Modify: `packages/core/src/artifacts.ts`
-- Test: `tests/orchestrator.test.ts`
-- Test: `tests/service.test.ts`
-
-- [ ] **Step 1: Write failing verification tests**
-
-Create an apply fixture with `verifyCommands: ["node -e \"process.exit(7)\""]`.
-After testing, assert `verificationStatus === "failed"`, `status ===
-"awaiting_input"`, and that `approveOrchestratedWorkflow({ gate: "testing" })`
-rejects without promoting the patch. Add a second test showing that
-`devcrew_waive_verification` rejects an empty reason, persists a non-empty
-reason, reopens the testing gate, and permits promotion only after normal
-testing approval.
-
-```ts
-await assert.rejects(
-  () => approveOrchestratedWorkflow({ cwd, runId, gate: "testing" }),
-  /verification failed/,
-);
-assert.equal(waived.verificationWaiver?.reason, "Known upstream test outage");
-```
-
-- [ ] **Step 2: Run focused workflow tests and verify RED**
-
-Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
-
-Expected: FAIL because a nonzero command currently still opens the pending
-testing gate and no waiver tool exists.
-
-- [ ] **Step 3: Implement verification outcome and waiver flow**
-
-After `runConfiguredVerification`, set `verificationStatus` from every result:
-empty is `not_run`, all-zero is `passed`, otherwise `failed`. A failed status
-sets `awaiting_input` and does not set the testing gate to pending. Add
-`waiveVerification(input)` that requires failed verification and a non-empty
-reason, records `VerificationWaiver`, changes the testing gate to pending, and
-sets `awaiting_approval`. Add `devcrew_waive_verification` to the MCP schema
-and handler.
-
-Make `approveOrchestratedWorkflow` reject a testing promotion unless status is
-passed or a waiver exists. Render the status, command exit evidence, and waiver
-reason in both the test report and acceptance artifact.
-
-- [ ] **Step 4: Run focused verification tests and verify GREEN**
-
-Run: `node --import tsx --test tests/orchestrator.test.ts tests/service.test.ts`
-
-Expected: PASS; failed verification cannot mutate the requester repository,
-while a recorded waiver remains visible and permits intentional approval.
-
-- [ ] **Step 5: Commit verification safety**
-
-```bash
-git add packages/core/src/workflow.ts packages/orchestrator/src/index.ts packages/service/src/tools.ts packages/core/src/artifacts.ts tests/orchestrator.test.ts tests/service.test.ts
-git commit -m "fix: block failed verification promotion"
-```
-
-### Task 5: Correct generated instructions and user-facing documentation
-
-**Files:**
-- Modify: `README.md`
-- Modify: `docs/workflow.md`
-- Modify: `docs/codex.md`
-- Modify: `docs/claude-code.md`
-- Modify: `packages/plugins/src/index.ts`
-- Test: `tests/plugins.test.ts`
-
-- [ ] **Step 1: Write failing generated-skill/doc assertions**
-
-Extend plugin tests to require the generated skill to distinguish
-interactive-host execution from headless policy and to mention
-`devcrew_complete_execution` and `devcrew_waive_verification`.
-
-- [ ] **Step 2: Run plugin tests and verify RED**
-
-Run: `node --import tsx --test tests/plugins.test.ts`
-
-Expected: FAIL because the generated skill promises inherited host approvals
-and lacks the new handoff/waiver tools.
-
-- [ ] **Step 3: Update generated skill and docs**
-
-Document that interactive host execution uses the host's native agent after
-DevCrew supplies a worktree instruction; it does not run a nested SDK. Document
-headless policies as explicit DevCrew policies. Replace all claims that DevCrew
-inherits a current host approval boundary. Add the failed-verification and
-recorded-waiver transition to workflow diagrams and tool lists.
-
-- [ ] **Step 4: Run plugin tests and verify GREEN**
-
-Run: `node --import tsx --test tests/plugins.test.ts`
-
-Expected: PASS with the checked-in plugin matching regenerated text.
-
-- [ ] **Step 5: Run full validation and commit documentation**
-
-Run: `npm run validate`
-
-Expected: exit code 0 with all tests passing.
-
-```bash
-git add README.md docs/workflow.md docs/codex.md docs/claude-code.md packages/plugins/src/index.ts plugins/devcrew-codex plugins/devcrew-claude tests/plugins.test.ts
-git commit -m "docs: describe explicit apply execution policies"
-```

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

@@ -1,182 +0,0 @@
-# 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/superpowers/specs/2026-07-13-execution-boundaries-design.md

@@ -1,126 +0,0 @@
-# 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.