@shenlee/devcrew 0.1.4 → 0.1.5

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.

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

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

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

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