@shenlee/devcrew 0.1.2 → 0.1.4

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

@@ -0,0 +1,213 @@
+# P0 Verification and Review Remediation 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:** Prevent unverified apply patches from being promoted and send architecture-review findings back through implementation.
+
+**Architecture:** Keep `verificationStatus` as the single source for testing-gate policy. Treat `failed` and `not_run` identically for blocking, but allow the existing persisted waiver to reopen either state. Reuse the existing testing-rejection recovery pattern for implementation-review findings, preserving the isolated worktree while returning the state machine to `execution/ready`.
+
+**Tech Stack:** TypeScript, Node.js test runner, Git worktrees, existing DevCrew MCP/orchestrator APIs.
+
+---
+
+### Task 1: Block missing verification evidence
+
+**Files:**
+- Modify: `tests/orchestrator.test.ts:483-533`
+- Modify: `packages/orchestrator/src/index.ts:241-253, 552-558`
+- Modify: `packages/core/src/workflow.ts:297-314`
+
+- [ ] **Step 1: Write failing no-verification tests**
+
+Add a test after the failed-verification test that creates an apply fixture with
+an empty `verifyCommands` list and no discoverable manifest. Advance it through
+testing and assert the following:
+
+```ts
+assert.equal(tested.verificationStatus, "not_run");
+assert.equal(tested.gates.testing, "rejected");
+assert.equal(tested.status, "awaiting_input");
+await assert.rejects(
+  () => approveOrchestratedWorkflow({ cwd, runId: tested.runId, gate: "testing" }),
+  /not pending approval/i,
+);
+```
+
+In the same test, call `waiveOrchestratedVerification` with a non-empty reason,
+assert `testing: pending` and `awaiting_approval`, then approve testing and
+assert the reviewed file was promoted. Add a second assertion that directly
+sets a persisted test fixture to `verificationStatus: "not_run"`, a pending
+testing gate, and no waiver, then expects `approveOrchestratedWorkflow` to
+throw `Verification must pass before promotion`.
+
+- [ ] **Step 2: Run the focused test and verify RED**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: the new test fails because `not_run` currently opens a pending gate
+and the waiver operation rejects it.
+
+- [ ] **Step 3: Implement the minimal verification policy**
+
+In `setTestingGateFromVerification`, replace the `failed`-only branch with a
+non-passed branch. Preserve the existing failed message and add a distinct
+missing-evidence message:
+
+```ts
+if (state.verificationStatus !== "passed") {
+  state.gates.testing = "rejected";
+  state.status = "awaiting_input";
+  state.feedback.push({
+    gate: "testing",
+    message: state.verificationStatus === "failed"
+      ? "Automated verification failed. Inspect the test report, revise the implementation, or record an explicit verification waiver with its reason."
+      : "No verification evidence was recorded. Configure or run validation, revise the implementation, or record an explicit verification waiver with its reason.",
+    createdAt: now(),
+  });
+  return;
+}
+```
+
+Update `waiveVerificationWorkflow` to accept either `failed` or `not_run` and
+change its error message to mention failed or missing verification. In
+`approveOrchestratedWorkflow`, replace the failed-only promotion check with:
+
+```ts
+if (before.verificationStatus !== "passed" && !before.verificationWaiver) {
+  throw new Error("Verification must pass before promotion or have an explicit verification waiver");
+}
+```
+
+- [ ] **Step 4: Run focused tests and verify GREEN**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: all orchestrator tests pass, including failed and missing
+verification waiver paths.
+
+- [ ] **Step 5: Commit the verification fix**
+
+```bash
+git add packages/core/src/workflow.ts packages/orchestrator/src/index.ts tests/orchestrator.test.ts
+git commit -m "fix: block promotion without verification evidence"
+```
+
+### Task 2: Return review findings to execution
+
+**Files:**
+- Modify: `tests/orchestrator.test.ts:365-421`
+- Modify: `packages/orchestrator/src/index.ts:639-658`
+- Modify: `docs/workflow.md:45-49`
+
+- [ ] **Step 1: Write the failing review-remediation test**
+
+Extend `architecture review blocks testing when it requires changes` after its
+current rejection assertions. Call `answerOrchestratedWorkflow` with a
+non-empty answer and assert:
+
+```ts
+assert.equal(revised.phase, "execution");
+assert.equal(revised.status, "ready");
+assert.equal(revised.gates["implementation-review"], "not_started");
+assert.equal(revised.executionWorkspace?.path, workspacePath);
+```
+
+Then call `continueOrchestratedWorkflow` with a runner that records its phase
+and assert the next executed role has `phase === "execution"` and
+`role === "implementer"`, not `review`/`architect`.
+
+- [ ] **Step 2: Run the focused test and verify RED**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: the new assertions fail because `devcrew_answer` currently re-runs
+the review phase.
+
+- [ ] **Step 3: Implement the remediation transition**
+
+Add this branch in `answerOrchestratedWorkflow` immediately after the existing
+testing-rejection branch:
+
+```ts
+if (
+  before.executionMode === "apply" &&
+  before.phase === "review" &&
+  before.gates["implementation-review"] === "rejected" &&
+  before.architectureReview?.decision === "changes_required"
+) {
+  state.phase = "execution";
+  state.status = "ready";
+  state.gates["implementation-review"] = "not_started";
+  return saveState(state);
+}
+```
+
+Do not clear `executionWorkspace`, `architectureReview`, feedback, or the
+prior review artifact; they remain audit evidence and the next execution phase
+will refresh the captured diff and create a new review.
+
+- [ ] **Step 4: Update the workflow documentation**
+
+Replace the current claim that feedback must be addressed before another review
+with text stating that `devcrew_answer` returns the run to the isolated
+`execution/ready` state and a later `devcrew_continue` performs the revised
+implementation before a fresh architect review.
+
+- [ ] **Step 5: Run focused tests and verify GREEN**
+
+Run:
+
+```bash
+node --import tsx --test tests/orchestrator.test.ts
+```
+
+Expected: all orchestrator tests pass and the remediation test observes an
+implementer execution before a subsequent review.
+
+- [ ] **Step 6: Commit the remediation fix**
+
+```bash
+git add docs/workflow.md packages/orchestrator/src/index.ts tests/orchestrator.test.ts
+git commit -m "fix: return architecture findings to execution"
+```
+
+### Task 3: Full verification
+
+**Files:**
+- Verify: `packages/core/src/workflow.ts`
+- Verify: `packages/orchestrator/src/index.ts`
+- Verify: `tests/orchestrator.test.ts`
+
+- [ ] **Step 1: Run the complete repository validation**
+
+Run:
+
+```bash
+npm run validate
+```
+
+Expected: TypeScript compilation succeeds and every test passes.
+
+- [ ] **Step 2: Inspect the final diff**
+
+Run:
+
+```bash
+git diff main...HEAD --check
+git status --short
+```
+
+Expected: no whitespace errors; only the two implementation commits and this
+plan/spec commits are present on the branch.

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"
+```