owflow 0.4.2 → 0.5.0

package/dist/skills/migration-analyze/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: owflow:migration-analyze
+description: Migration — analyzes the current system and resolves migration-scoped clarifications. First work phase of the migration workflow (state-analysed).
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Analyze — Current State & Clarifications (state-analysed)
+
+Work phase of the migration workflow. Runs current-system analysis via the reused `codebase-analyzer` engine, then resolves migration-scoped clarifications. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Assisted entry point: `/owflow:migration` (dispatcher). Autonomous: `/owflow:goal-migration` (wrapper). Both produce the same state; the modes can be mixed freely.
+
+## Entry Gate
+
+### 1. Argument resolution
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/migrations/` (e.g., `2026-01-12-framework-upgrade`); resolve to its path.
+- Missing argument, a path that does **not exist**, or no identifier match → print the blocked block (part 3), then STOP. Never guess or auto-pick a task.
+
+### 2. Prerequisites
+
+| Required for this skill | Where verified                     | Produced by                                                  |
+| ----------------------- | ---------------------------------- | ------------------------------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml` | `/owflow:migration <description>` (dispatcher init) or mid-pipeline bootstrap |
+
+No upstream migration slug is required — this is the pipeline's first work phase.
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order): **none** — `migration-analyze` is the first work phase. If no task exists yet, initialize one with `/owflow:migration <description>`.
+2. List available migration-task identifiers (directories under `.owflow/tasks/migrations/`) to resume from, if any.
+3. Hint: `Run /owflow:migration <description> to start a migration task from scratch, or pass a task path/identifier to resume.`
+
+Then STOP — never guess or auto-pick a task.
+
+### 4. Missing-state bootstrap
+
+When the only unmet prerequisite is the state file, use `question` — "No task exists at this path. Create a fresh standard migration task and start at `state-analysed`?" with **Create task** / **Decline**.
+
+- **On confirm**: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template with `orchestrator.entry_point: "migration-analyze (mid-pipeline bootstrap)"`, `orchestrator.started_phase: state-analysed`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — never upstream artifacts.
+- **On decline**: print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+
+### 5. Skip/resume — artifacts before state
+
+- `analysis/current-state-analysis.md` exists but `state-analysed` is missing ⇒ **adopt**: append `state-analysed`, backfill `migration_context.current_system`, `migration_context.clarifications_resolved`, `phase_summaries.analyze.summary`, and both `migration_outputs` paths where still null; run only the missing clarifications part.
+- `state-analysed` is present but `analysis/current-state-analysis.md` **or** `analysis/clarifications.md` is missing ⇒ **drop** `state-analysed` from `completed_phases` and re-run only the missing part (re-adopt the existing analysis when it is present; never redo the analysis needlessly).
+- Both artifacts exist and the slug is present ⇒ report the existing results and route to the Exit Gate.
+- `migration_context.clarifications_resolved` is already non-null ⇒ report the existing clarifications instead of re-asking.
+
+### 6. Conditional activation
+
+Not applicable — `migration-analyze` has no activation condition; it runs whenever its state-file prerequisite is met.
+
+### 7. Recovery
+
+| Step                     | Max Attempts | Strategy                                                                                          |
+| ------------------------ | ------------ | ------------------------------------------------------------------------------------------------- |
+| Analysis (`state-analysed`) | 2         | Expand search patterns across the repository; prompt the user for specific file paths              |
+| Clarifications           | 1            | Ask remaining questions in one consolidated round; record unresolved points as explicit assumptions |
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) and the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md).
+
+| Direction | Artifact                            | Producer                                                        |
+| --------- | ----------------------------------- | --------------------------------------------------------------- |
+| Consumed  | `orchestrator-state.yml`            | dispatcher init / mid-pipeline bootstrap                        |
+| Produced  | `analysis/current-state-analysis.md` | `codebase-analyzer` (**Skill**, reused 0 changes) — pass `artifact_name` |
+| Produced  | `analysis/clarifications.md`        | inline `question` round (≤5 questions)                          |
+
+### Current-State Analysis & Clarifications (`state-analysed`)
+
+1. **Skill tool — `codebase-analyzer`** (never inline). Pass: `task_path`, `task_description`, and `artifact_name: "current-state-analysis.md"` (the engine derives the `analysis/` prefix — do not pass a path). The engine's migration-target role is documented in its own mapping — do not restate it here.
+2. **Inline clarifications** — use `question` for up to 5 migration-scoped questions: migration scope/boundaries, current vs target system, constraints, data involvement, downtime tolerance. Frame as confirmable assumptions ("I assume X — is that correct?"). Save to `analysis/clarifications.md`.
+3. **State write**: append `state-analysed` to `completed_phases`; set `migration_context.current_system.description`, `migration_context.current_system.technologies` (**corrected write** — the monolith wrote the undeclared `task_context`), `migration_context.clarifications_resolved: true`, `phase_summaries.analyze.summary`, `migration_outputs.current_state_analysis`, `migration_outputs.clarifications`; bump `orchestrator.updated`. On failure: append `state-analysed` to `failed_phases`, increment `auto_fix_attempts["state-analysed"]`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`state-analysed`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — a failed or abandoned step is NOT appended to `completed_phases`; append its slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-migration.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ MIGRATION ANALYZE COMPLETE — <task name>
+
+**Current system** — [1-line summary from state]
+**Migration scope** — [included / excluded summary]
+**Clarifications** — [N resolved / open assumptions]
+**Analysis confidence** — ✅ solid / ⚠ open gaps recorded
+
+**Artifacts**
+
+- `analysis/current-state-analysis.md`
+- `analysis/clarifications.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the analysis is good; continue.
+- **Adjust** — re-run only the affected part (analysis or clarifications), update state and artifacts, re-present the results box.
+- **Discuss** — walk through the current-system findings or scope assumptions in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-analyze <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:migration-target <task-path>` — `required` next: locks the target state, classifies the migration type, recommends a strategy, and produces the risk-locked target-state plan. Remaining after: spec → plan → implement → verify (→ fix when needed) → finalize.
+
+**Other options**:
+
+- `/owflow:goal-migration <task-path>` — `optional` shortcut: runs all remaining phases in one loop (target → spec → plan → implement → verify → fix when needed → finalize)
+
+Then STOP.

package/dist/skills/migration-finalize/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: owflow:migration-finalize
+description: Migration — authors the operator migration guide inline when enabled, then completes the task. Workflow-terminal (docs-generated optional, task-completed always).
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Finalize — Operator Guide & Task Completion (docs-generated, task-completed)
+
+Terminal work phase of the migration workflow. When `options.docs_enabled` resolves true it authors `documentation/migration-guide.md` **inline** (operator audience, text-first — no `user-docs-generator`, no Playwright, no agent edits); then it always finalizes: workflow summary, `task.status: completed`, and the `task-completed` slug.
+
+## Entry Gate
+
+### 1. Argument resolution
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/migrations/` (e.g., `2026-01-12-framework-upgrade`); resolve to its path.
+- Missing argument, a path that does **not exist**, or no identifier match → print the blocked block (part 3), then STOP. Never guess or auto-pick a task.
+
+### 2. Prerequisites
+
+| Required for this skill | Where verified                                                                                              | Produced by                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                                                        | `/owflow:migration <description>` (dispatcher init) or mid-pipeline bootstrap |
+| Verification done       | `verification-done` in `completed_phases` **and** `verification/implementation-verification.md` exists       | `/owflow:migration-verify <task-path>`           |
+| Fix phase settled       | `verification_context.compatibility_status = passed` **and** (`issues-resolved` present with non-empty `fixes_applied` or a recorded approval, **or** `verification_context.last_status = passed`, **or** `phase_summaries.fix.summary` records a deliberate skip) | `/owflow:migration-fix`, `/owflow:migration-verify` |
+| Docs toggle known (conditional step) | `options.docs_enabled` in state (`true`/`false`; `null` ⇒ the options gate never ran — treated as not enabled) | `/owflow:migration-verify` (options step) |
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order), each with its command:
+   - Issue resolution (`issues-resolved`) → `/owflow:migration-fix <task-path>` (only when verification left fixable issues)
+   - Verification (`verification-done`) → `/owflow:migration-verify <task-path>`
+   - Migration execution (`migration-executed`) → `/owflow:migration-implement <task-path>` (if also missing)
+   - Implementation planning (`plan-created`) → `/owflow:migration-plan <task-path>` (if also missing)
+   - Strategy specification (`strategy-specified`) → `/owflow:migration-spec <task-path>` (if also missing)
+   - Target state planning (`target-planned`) → `/owflow:migration-target <task-path>` (if also missing)
+   - Current-state analysis (`state-analysed`) → `/owflow:migration-analyze <task-path>` (if also missing)
+   - State initialization → `/owflow:migration <description>` (new task)
+2. List available migration-task identifiers (directories under `.owflow/tasks/migrations/`) to resume from, if any.
+3. Hint: `Run /owflow:migration <description> to start a migration task from scratch, or pass a task path/identifier to resume.`
+
+Then STOP — never guess or auto-pick a task.
+
+### 4. Missing-state bootstrap
+
+When the only unmet prerequisite is the state file, use `question` — "No task exists at this path. Create a fresh standard migration task and start at `task-completed`?" with **Create task** / **Decline**.
+
+- **On confirm**: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template with `orchestrator.entry_point: "migration-finalize (mid-pipeline bootstrap)"`, `orchestrator.started_phase: task-completed`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — `verification/implementation-verification.md` still blocks, so bootstrapping never skips upstream work.
+- **On decline**: print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+
+### 5. Skip/resume — artifacts before state
+
+- `task.status: completed` or `task-completed` in `completed_phases` ⇒ report the existing finalization and STOP — the workflow is terminal; never re-run it.
+- `documentation/migration-guide.md` exists but `docs-generated` is missing ⇒ **adopt**: append `docs-generated`, backfill `migration_outputs.migration_guide`, continue to finalization.
+- `docs-generated` is present but the guide is missing ⇒ **drop** `docs-generated` and re-author (only when enabled).
+- Fix phase unsettled (`compatibility_status != passed` — failed or never written — **or** no `issues-resolved`/approval/skip **and** `last_status != passed`) ⇒ route back to `/owflow:migration-verify <task-path>` (or `/owflow:migration-fix <task-path>` when issues remain) — never finalize unfinished verification. A failed compatibility check is **never waived by a deliberate skip or approval**: re-verify after fixes, or use user-confirmed rollback.
+- A settled `options.docs_enabled` is reported, not re-asked.
+
+### 6. Conditional activation
+
+Read `options.docs_enabled` (tri-state). `true` ⇒ run the Documentation step below. `false` **or** `null` (the options gate never settled it) ⇒ report `Operator guide disabled — skipping documentation.` and skip straight to Finalization: **no `docs-generated` slug, no failure entry** — a docs skip is an option value, not a failure. Do not prompt for the toggle here; its setter is `migration-verify`'s options step.
+
+### 7. Recovery
+
+| Step                            | Max Attempts | Strategy                                                                       |
+| ------------------------------- | ------------ | ------------------------------------------------------------------------------ |
+| Documentation (`docs-generated`) | 1           | Generate text-only — inline markdown, no screenshots or tooling                 |
+| Finalization (`task-completed`)  | 1           | Compose the summary and set `task.status: completed`; state-only — repeat once, then report |
+
+## Execute
+
+**Read first**: no delegation is used in this skill. **Inline authoring by design**: `user-docs-generator` (hard-codes `documentation/user-guide.md` + Playwright) is explicitly out of scope — never invoke it, Playwright, or any agent for the guide.
+
+| Direction | Artifact                              | Producer                                                    |
+| --------- | ------------------------------------- | ----------------------------------------------------------- |
+| Consumed  | all `migration_outputs.*` paths       | upstream phases (analysis → verification)                   |
+| Consumed  | `verification_context.last_status`, `verification_context.compatibility_status` | `migration-verify` (ownership), `migration-fix` (re-verify refresh) |
+| Consumed  | `options.docs_enabled`                | `migration-verify` options step                             |
+| Produced  | `documentation/migration-guide.md` (conditional) | inline authoring (this skill)                     |
+| Produced  | workflow summary + `task.status: completed` | inline authoring (this skill)                         |
+
+### Operator Migration Guide (`docs-generated`, conditional)
+
+**Skip if** `options.docs_enabled` is not `true` (see part 6 — report and skip; no slug, no failure entry).
+
+Author `documentation/migration-guide.md` directly in the main agent — **operator audience, text-first**. Cover exactly:
+
+1. **Migration overview and goals** — what changed, why, current → target.
+2. **Prerequisites and preparation** — access, backups, environment readiness.
+3. **Step-by-step procedure** — ordered operator steps from the implementation plan / work log, with the per-group checkpoints.
+4. **Rollback procedures** — from `analysis/rollback-plan.md` (authoritative) and `analysis/dual-run-plan.md` when present.
+5. **Troubleshooting** — known issues from verification, the compatibility checks, and fix decisions.
+
+**State write**: append `docs-generated`; set `migration_outputs.migration_guide: "documentation/migration-guide.md"`; bump `orchestrator.updated`; re-read + `verify_template`.
+
+### Finalization (`task-completed`, always)
+
+1. **Compose the workflow summary** from state + artifacts: migration type/strategy, steps completed, verification + compatibility outcomes, fixes, guide status. There is no `finalize` key in `phase_summaries` — the omission is deliberate (state-only terminal step); do not add one.
+2. **State write**: set `task.status: completed`; append `task-completed`; bump `orchestrator.updated`; re-read + `verify_template`.
+3. **Workflow-end handoff**: no further owflow phase is required; list the artifacts for the user's own review and commit (the workflow performs no commits).
+
+## State Update Convention (per step)
+
+1. **Write immediately** — append `docs-generated` only when documentation actually ran, then `task-completed` at finalization; never batch and never append `docs-generated` on a skip or failure.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the guide ultimately fails after the one text-only retry, do NOT append `docs-generated`; append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["docs-generated"]`; ask the user whether to continue to finalization without docs. A disabled guide is NOT a failure (no entry at all).
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-migration.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then close the workflow (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ MIGRATION WORKFLOW COMPLETE — <task name>
+
+**Migration** — [current → target, type]
+**Strategy** — [incremental / big-bang / dual-run / phased]
+**Verification** — [final verifier verdict + overall compatibility verdict]
+**Fixes** — [N applied / none required / deliberately skipped]
+**Operator guide** — [✅ `documentation/migration-guide.md` / skipped (`docs_enabled` not enabled)]
+**Rollback plan** — ✅ `analysis/rollback-plan.md` (user-confirmed rollback only)
+
+**Artifacts**
+
+- `analysis/current-state-analysis.md`
+- `analysis/target-state-plan.md`
+- `analysis/requirements.md`
+- `analysis/rollback-plan.md`
+- `analysis/dual-run-plan.md` [conditional]
+- `implementation/spec.md`
+- `implementation/implementation-plan.md`
+- `implementation/work-log.md`
+- `verification/implementation-verification.md`
+- `verification/compatibility-test-results.md`
+- `documentation/migration-guide.md` [conditional]
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the migration is complete; show the workflow-end handoff.
+- **Adjust** — re-run the affected part (operator guide and/or finalization) with the user's corrections, update state, re-present the results box.
+- **Discuss** — walk through the workflow summary, verification outcome, guide contents, or rollback readiness in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-finalize <task-path>`) and end.
+
+### Next steps (after Accept)
+
+**Workflow-end handoff (terminal)** — the migration workflow is finished; no further owflow phase command is required and this skill advances nothing. Remaining: none.
+
+- Review the artifacts above, then commit and open a PR using the operator guide's rollback procedures as the safety reference — `optional` manual step outside owflow (the workflow performs no commits).
+- `/owflow:reviews-pragmatic <task-path>` — `optional` — post-migration over-engineering check; does not advance phases.
+- `/owflow:standards-update "<lesson learned>"` — `optional` — captures migration learnings as project standards; does not advance phases.
+
+Then STOP.

package/dist/skills/migration-fix/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: owflow:migration-fix
+description: Migration — conditional verification-issue resolution with a max-3 fix-then-reverify loop and a data-integrity HALT that is never auto-fixed (issues-resolved).
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Fix — Conditional Issue Resolution (issues-resolved)
+
+Conditional work phase of the migration workflow. Activates only when the verification state fact says fixable issues remain. Runs the shared [Fix Loop Contract](../orchestrator-framework/references/fix-loop-contract.md) — max 3 iterations, re-invoke `implementation-verifier`, `fixes_applied` written immediately per iteration — with the migration deltas (compatibility verdict invalidation, data-integrity HALT). **Data-integrity problems are NEVER auto-fixed.**
+
+## Entry Gate
+
+### 1. Argument resolution
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/migrations/` (e.g., `2026-01-12-framework-upgrade`); resolve to its path.
+- Missing argument, a path that does **not exist**, or no identifier match → print the blocked block (part 3), then STOP. Never guess or auto-pick a task.
+
+### 2. Prerequisites
+
+| Required for this skill | Where verified                                                                                          | Produced by                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                                                    | `/owflow:migration <description>` (dispatcher init) or mid-pipeline bootstrap |
+| Verification done       | `verification-done` in `completed_phases` **and** `verification/implementation-verification.md` exists   | `/owflow:migration-verify <task-path>` |
+| Fixable issues exist    | `verification_context.compatibility_status = failed` **or** (`verification_context.last_status != passed` and no recorded deliberate skip); the verification/compatibility reports list fixable critical/warning issues, **or** a deliberate skip is already recorded with `compatibility_status = passed` (settled — route forward) | `/owflow:migration-verify <task-path>` |
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order), each with its command:
+   - Verification (`verification-done`) → `/owflow:migration-verify <task-path>`
+   - Migration execution (`migration-executed`) → `/owflow:migration-implement <task-path>` (if also missing)
+   - Implementation planning (`plan-created`) → `/owflow:migration-plan <task-path>` (if also missing)
+   - Strategy specification (`strategy-specified`) → `/owflow:migration-spec <task-path>` (if also missing)
+   - Target state planning (`target-planned`) → `/owflow:migration-target <task-path>` (if also missing)
+   - Current-state analysis (`state-analysed`) → `/owflow:migration-analyze <task-path>` (if also missing)
+   - State initialization → `/owflow:migration <description>` (new task)
+2. List available migration-task identifiers (directories under `.owflow/tasks/migrations/`) to resume from, if any.
+3. Hint: `Run /owflow:migration <description> to start a migration task from scratch, or pass a task path/identifier to resume.`
+
+Then STOP — never guess or auto-pick a task.
+
+### 4. Missing-state bootstrap
+
+When the only unmet prerequisite is the state file, use `question` — "No task exists at this path. Create a fresh standard migration task and start at `issues-resolved`?" with **Create task** / **Decline**.
+
+- **On confirm**: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template with `orchestrator.entry_point: "migration-fix (mid-pipeline bootstrap)"`, `orchestrator.started_phase: issues-resolved`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — `verification/implementation-verification.md` still blocks, so bootstrapping never skips upstream work.
+- **On decline**: print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+
+### 5. Skip/resume — artifacts before state
+
+- `issues-resolved` is present with **non-empty** `verification_context.fixes_applied` **or a recorded approval in `verification_context.decisions_made`** (its state-resident marker) ⇒ report the existing fixes/decision and route to the Exit Gate — **except** when `compatibility_status != passed`, where part 6 activation keeps the failed check active and routes to `/owflow:migration-verify <task-path>`.
+- `issues-resolved` is present with neither a non-empty `fixes_applied` nor a recorded approval ⇒ **drop** the slug and re-run — never trust a bare slug.
+- A deliberate skip recorded in `phase_summaries.fix.summary` + `decisions_made` ⇒ **settled for verifier issues**: report it and route to `/owflow:migration-finalize <task-path>` **only when `compatibility_status = passed`**; when `compatibility_status = failed`, the skip does not waive the failed check — present the compatibility failure (data-integrity ⇒ HALT/rollback) and route to `/owflow:migration-verify <task-path>`; never re-open verifier issues.
+- `issues-resolved` is absent while `verification/implementation-verification.md` + `verification-done` hold ⇒ normal entry; when `fixes_applied` is already non-empty from an interrupted run, report those fixes and resume the loop without re-applying them.
+- Settled `verification_context.decisions_made` entries are reported, not re-asked.
+
+### 6. Conditional activation
+
+Read the **state facts** `verification_context.last_status` + `verification_context.compatibility_status` and the verification/compatibility reports. A recorded deliberate skip deactivates with `Fix deliberately skipped — issue resolution settled.` **only when `compatibility_status = passed`**; otherwise, when inactive — `last_status = passed` **and** `compatibility_status = passed`, and the reports list no fixable critical/warning issues — print exactly:
+
+`No fixable issues — issue resolution not required.`
+
+and route to `/owflow:migration-finalize <task-path>` (required next: operator guide when enabled, then task completion), then STOP. **No flag, no user choice** — the state facts decide activation.
+
+### 7. Recovery
+
+| Step                       | Max Attempts | Strategy                                                                                                       |
+| -------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
+| Fix loop (`issues-resolved`) | 3 iterations | Contract, not a retry counter: fix-then-reverify; at 3 ask proceed-with-warnings or rollback. **Data integrity: HALT — never auto-fixed** |
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), the [Fix Loop Contract](../orchestrator-framework/references/fix-loop-contract.md), and [Issue Resolution](../orchestrator-framework/references/orchestrator-patterns.md) (Section 6).
+
+| Direction | Artifact                                        | Producer                                                              |
+| --------- | ----------------------------------------------- | --------------------------------------------------------------------- |
+| Consumed  | `verification/implementation-verification.md`   | `implementation-verifier` via `migration-verify`                      |
+| Consumed  | `verification/compatibility-test-results.md`    | `migration-verify` (data-integrity and rollback evidence)             |
+| Produced  | migrated code fixes + state `fixes_applied`     | direct execution (this skill)                                         |
+| Produced  | updated `verification/implementation-verification.md` | re-invoked `implementation-verifier` (**Skill**)                |
+
+### User-Driven Fix Loop (`issues-resolved`)
+
+1. **Display the detailed issue breakdown** grouped by category and severity (location, description, fixability).
+2. **Present critical + warning issues as a numbered list.**
+3. `question` per the [Fix Loop Contract](../orchestrator-framework/references/fix-loop-contract.md) — "Which issues should I fix?" with exactly three options: **"Fix all fixable issues"** / **"Let me choose specific issues"** / **"Skip fixes, proceed as-is"**.
+4. **Fix the selected issues directly** (the migrated code is this skill's artifact). **Immediately** after each fix, append it to `verification_context.fixes_applied` in state — never deferred to the end; bump `orchestrator.updated`; re-read + `verify_template`. After fixes set `options.skip_test_suite: false` (code changed — the suite must re-run on re-verification) **and invalidate the stale compatibility verdict: `verification_context.compatibility_status: null`** (field-level fail-closed exception — the 4 checks ran against pre-fix code; only `migration-verify` may set a new verdict).
+5. `question` — "Re-run verification to check fixes?" → **"Yes, re-run verification"** / **"No, proceed to next phase"**. On yes: Skill tool — `implementation-verifier`; then **immediately** update `verification_context.reverify_count` **and refresh `verification_context.last_status` + `issues_found` from the verifier's structured return** (field-level re-verify exception — the fix loop replaces the verification result), then return to step 1 (max 3 iterations). `compatibility_status` stays `null` (invalidated by the fixes) or `failed` and remains owned by `migration-verify`: when it is not `passed`, the loop's required next step is `/owflow:migration-verify <task-path>` (its re-verification re-runs the compatibility checks and settles the verdict) — never route a non-passed compatibility status to finalize. On "No", exit the loop to the Exit Gate, where the same required-next rule applies. Single-writer split: `migration-verify` owns `last_status`/`issues_found`/`compatibility_status`; this skill owns `fixes_applied`, `reverify_count`, `decisions_made`, plus the re-verify refresh of `last_status`/`issues_found` and the fail-closed invalidation of `compatibility_status`.
+6. **Record each user decision** (specific selection, proceed-with-warnings, deliberate skip) in `verification_context.decisions_made`.
+
+**Data Safety — HALT**: any data-integrity issue (from the verification report, a compatibility result, or discovered while fixing) → HALT: never auto-fix data problems, never run a destructive data repair. Present the issue with the rollback option. **Rollback happens only on explicit user confirmation — no automatic rollback or revert ever.** A deliberate skip cannot waive a data-integrity failure or any non-passed compatibility check.
+
+**Exit conditions (surfaced as results-box glyphs — never Exit-Gate state mutations)**:
+
+- ✅ no critical issues remain → append `issues-resolved` and proceed.
+- ⚠ max 3 iterations reached → `question` — "Proceed with known issues?" / "Rollback": proceed ⇒ append `issues-resolved` with the approval recorded in `decisions_made`; rollback ⇒ do NOT append, record the decision, and HALT for user-confirmed rollback.
+- ❌ data integrity → HALT immediately, recommend user-confirmed rollback; do NOT append `issues-resolved`; record `failed_phases` + increment `auto_fix_attempts["issues-resolved"]`.
+- Deliberate skip ("Skip fixes, proceed as-is") → a user-chosen skip, not a failure: no `issues-resolved` slug, no failure entry; record the reason in `phase_summaries.fix.summary` + `decisions_made`. `migration-finalize` accepts this settled skip **only when `compatibility_status = passed`**; `compatibility_status = failed` remains an absolute finalize blocker (re-verify after fixes, or user-confirmed rollback).
+
+## State Update Convention (per step)
+
+1. **Write immediately** — `fixes_applied` after every fix (never batched); `reverify_count`/`decisions_made` **and the `last_status`/`issues_found` refresh** right after each verifier run or decision; `issues-resolved` only when the loop settles successfully (✅, or an approved ⚠). Never defer and never append on a deliberate skip.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — a HALT or failed fix iteration is NOT appended to `completed_phases`; append `issues-resolved` to `orchestrator.failed_phases` and increment `auto_fix_attempts["issues-resolved"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-migration.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ MIGRATION FIX COMPLETE — <task name>
+
+**Iterations** — [N of max 3]
+**Fixes applied** — [count + 1-line list]
+**Remaining issues** — [by severity / none]
+**Re-verification** — [✅ passed / ⚠ passed_with_issues / ❌ failed — N re-runs]
+**Data integrity** — [✅ no data issues / ❌ HALT — rollback recommended (user confirmation required)]
+**Decisions** — [proceed-with-warnings / deliberate skip / specific selection]
+
+**Artifacts**
+
+- migrated code fixes
+- `verification/implementation-verification.md` (updated by re-verification runs)
+- state `verification_context.fixes_applied`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the fixes (or the approved proceed-with-warnings / deliberate skip) are good; continue.
+- **Adjust** — fix additional selected issues and/or run another verification round within the max-3 contract, update state and the report, re-present the results box.
+- **Discuss** — walk through specific fixes, remaining issues, or the data-integrity HALT in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-fix <task-path>`) and end.
+
+### Next steps (after Accept)
+
+Render ONLY the row whose condition matches the state:
+
+- `→ /owflow:migration-verify <task-path>` — `required` — only when `verification_context.compatibility_status != passed` (failed, or invalidated to null by applied fixes — a verifier-only re-run cannot settle compatibility): re-verification re-runs the 4 checks and owns `compatibility_status`. Remaining after: finalize.
+- `→ /owflow:migration-finalize <task-path>` — `required` — only when `compatibility_status = passed` (after a ✅ loop, an approved ⚠, or a deliberate skip): closes the workflow (authors the operator guide when `options.docs_enabled` is true, then completes the task). Remaining after: none — workflow ends.
+
+**Other options**:
+
+- After a ❌ data-integrity HALT with **user-confirmed rollback only**: restore to the last known-good state per `analysis/rollback-plan.md`, then re-enter `/owflow:migration-verify <task-path>` — `optional`, manual, never automatic.
+- `/owflow:goal-migration <task-path>` — `optional` shortcut: runs the remaining phases in one loop (finalize)
+
+Then STOP.

package/dist/skills/migration-implement/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: owflow:migration-implement
+description: Migration — executes the approved implementation plan via isolated per-group delegation (normal lane only), producing the work log and the migration-executed slug.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Implement — Plan Execution & Work Log (migration-executed)
+
+Work phase of the migration workflow. Executes `implementation/implementation-plan.md` task group by task group through isolated per-group delegation — **normal lane only, no quick lane** — and records the execution in state. The delegation owns checkboxes, the work log, incremental tests, standards discovery, and its own user-confirmed failure handling; this shell owns the state write.
+
+## Entry Gate
+
+### 1. Argument resolution
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/migrations/` (e.g., `2026-01-12-framework-upgrade`); resolve to its path.
+- Missing argument, a path that does **not exist**, or no identifier match → print the blocked block (part 3), then STOP. Never guess or auto-pick a task.
+
+### 2. Prerequisites
+
+| Required for this skill | Where verified                                                          | Produced by                          |
+| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                    | `/owflow:migration <description>` (dispatcher init) or mid-pipeline bootstrap |
+| Plan created            | `plan-created` in `completed_phases` **and** `implementation/implementation-plan.md` exists | `/owflow:migration-plan <task-path>` |
+| Spec present            | `implementation/spec.md` exists (the executor's input contract)          | `/owflow:migration-spec <task-path>` |
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order), each with its command:
+   - Implementation planning (`plan-created`) → `/owflow:migration-plan <task-path>`
+   - Strategy specification (`strategy-specified`) → `/owflow:migration-spec <task-path>` (if also missing)
+   - Target state planning (`target-planned`) → `/owflow:migration-target <task-path>` (if also missing)
+   - Current-state analysis (`state-analysed`) → `/owflow:migration-analyze <task-path>` (if also missing)
+   - State initialization → `/owflow:migration <description>` (new task)
+2. List available migration-task identifiers (directories under `.owflow/tasks/migrations/`) to resume from, if any.
+3. Hint: `Run /owflow:migration <description> to start a migration task from scratch, or pass a task path/identifier to resume.`
+
+Then STOP — never guess or auto-pick a task.
+
+### 4. Missing-state bootstrap
+
+When the only unmet prerequisite is the state file, use `question` — "No task exists at this path. Create a fresh standard migration task and start at `migration-executed`?" with **Create task** / **Decline**.
+
+- **On confirm**: create `.owflow/tasks/migrations/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the migration template with `orchestrator.entry_point: "migration-implement (mid-pipeline bootstrap)"`, `orchestrator.started_phase: migration-executed`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — `implementation/implementation-plan.md` still blocks, so bootstrapping never skips upstream work.
+- **On decline**: print `No migration task found at <path>. Run /owflow:migration <description> to start a migration task from scratch.` and STOP.
+
+### 5. Skip/resume — artifacts before state
+
+- `implementation/work-log.md` exists but `migration-executed` is missing ⇒ **adopt**: append `migration-executed`, backfill `phase_summaries.implement.summary` and `migration_outputs.work_log` where still null.
+- `migration-executed` is present but `implementation/work-log.md` is missing ⇒ **drop** `migration-executed` from `completed_phases` and re-run.
+- Both artifact and slug exist ⇒ report the existing execution summary and route to the Exit Gate.
+- A partially executed plan (unchecked groups remain) is NOT complete: resume with `/owflow:migration-implement <task-path>` so the per-group execution picks up the uncompleted groups.
+
+### 6. Conditional activation
+
+Not applicable — `migration-implement` has no activation condition; it runs whenever its prerequisites are met.
+
+### 7. Recovery
+
+| Step                          | Max Attempts | Strategy                                                                                                        |
+| ----------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
+| Plan execution (`migration-executed`) | 5    | Fix syntax/import errors and re-run the failed group's tests; prompt the user on repeated failure. **Never auto-rollback — rollback requires explicit user confirmation** |
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md). The per-group execution applies its own test-driven order and continuous standards discovery.
+
+| Direction | Artifact                            | Producer                                                             |
+| --------- | ----------------------------------- | -------------------------------------------------------------------- |
+| Consumed  | `implementation/implementation-plan.md` | `migration-plan` (approved plan with per-group rollback steps)   |
+| Consumed  | `implementation/spec.md`            | `migration-spec` (approved specification)                            |
+| Produced  | `implementation/work-log.md`        | per-group delegation to `task-group-implementer` (**Task tool**, normal lane only) |
+
+### Plan Execution (`migration-executed`)
+
+> **ANTI-PATTERN — never execute the plan's task groups inline. "The groups are straightforward" is NOT a reason to skip delegation.**
+
+1. **Execute the plan — per-group delegation** (normal lane only; migration has no quick lane). For each task group in order: prepare context (task path, task description, the `implementation/spec.md` + `implementation/implementation-plan.md` paths, `migration_context.*` — type, strategy, risk level, breaking changes — and accumulated `phase_summaries` from analyze → plan), delegate the group via the **Task tool** to `task-group-implementer`, then process its report: mark the group's checkboxes in `implementation/implementation-plan.md`, append the work-log entry to `implementation/work-log.md`, and run the group's incremental tests before moving on. Apply lazy standards loading per group; after the last group, run the full test suite once.
+2. **No post-continuation glue block** — the per-group execution's return is not a handoff to be glued: do NOT "re-read state to confirm you are the orchestrator", do NOT add a numbered phase marker, do NOT auto-proceed to verification. The monolith's post-continuation block existed only because the monolith owned the state writes; here the per-step write below is the only continuation.
+3. **State write**: append `migration-executed` to `completed_phases`; set `phase_summaries.implement.summary`, `migration_outputs.work_log: "implementation/work-log.md"`; bump `orchestrator.updated`. On failure (per-group execution fails after its retries, user stops): do NOT append; append `migration-executed` to `failed_phases` and increment `auto_fix_attempts["migration-executed"]`; partial progress stays in `implementation/work-log.md`. Then re-read state + run `verify_template`.
+
+## State Update Convention (per step)
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`migration-executed`) plus that step's fields. Never batch or defer to the end of the skill.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — a failed or abandoned step is NOT appended to `completed_phases`; append its slug to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-migration.yml`. Fix any reported issue immediately.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run.
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill.
+
+### Results box
+
+```markdown
+## ✅ MIGRATION IMPLEMENT COMPLETE — <task name>
+
+**Task groups** — [completed / total]
+**Files changed** — [count + key files, 1-2 lines]
+**Tests** — [incremental results + full-suite status from the executor]
+**Work log** — ✅ `implementation/work-log.md`
+**Rollback readiness** — [per-group checkpoints completed / deferred items]
+
+**Artifacts**
+
+- implemented migration changes
+- `implementation/work-log.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the implementation matches the plan; continue.
+- **Adjust** — re-work the affected task groups (fix code, re-run their tests), update state and the work log, re-present the results box.
+- **Discuss** — walk through implementation decisions, files changed, or deferred items in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-implement <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:migration-verify <task-path>` — `required` next: runs the verification options gate, the reused verifier, and the 4 migration compatibility checks. Remaining after: fix (only when verification finds issues) → finalize.
+
+**Other options**:
+
+- `/owflow:goal-migration <task-path>` — `optional` shortcut: runs all remaining phases in one loop (verify → fix when needed → finalize)
+
+Then STOP.