owflow 0.4.2 → 0.5.0

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

@@ -0,0 +1,184 @@
+---
+name: owflow:migration-verify
+description: Migration — settles all verification options in one gate, delegates the reused verifier, runs the 4 migration compatibility checks, and owns options-chosen then verification-done.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Migration Verify — Options, Verification & Compatibility Checks (options-chosen, verification-done)
+
+Work phase of the migration workflow. Runs in a **fixed order**: options gate → reused `implementation-verifier` → the 4 migration compatibility checks → `verification-done`. Compatibility checks run **after** the verifier so they consume its verified baseline. Compatibility outcomes are persisted as the `verification_context.compatibility_status` state fact; the Exit Gate itself never mutates phase state.
+
+## 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 |
+| Migration executed      | `migration-executed` in `completed_phases` **and** `implementation/work-log.md` exists | `/owflow:migration-implement <task-path>` |
+| Verifier inputs present | `implementation/implementation-plan.md`, `implementation/spec.md`, **and** `implementation/work-log.md` exist (the reused verifier's required inputs) | `/owflow:migration-plan`, `/owflow:migration-spec`, `/owflow:migration-implement` |
+
+### 3. Blocked output
+
+1. Steps that must be completed first (in order), each with its command:
+   - Migration execution (`migration-executed`) → `/owflow:migration-implement <task-path>`
+   - 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 `options-chosen`?" 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-verify (mid-pipeline bootstrap)"`, `orchestrator.started_phase: options-chosen`, `completed_phases: []`, `task.title`/`task.description` from the argument. Run `verify_template` (`orchestrator-state-migration.yml`) immediately. Creates state ONLY — `implementation/work-log.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
+
+- `verification/implementation-verification.md` exists but `verification-done` is missing ⇒ **adopt**: do not re-run the verifier; backfill `verification_context.last_status` and `verification_context.issues_found` from the report summary, continue at the compatibility checks, then append `verification-done`.
+- `verification-done` is present but `verification/implementation-verification.md` is missing ⇒ **drop** `verification-done` from `completed_phases` and re-run.
+- `options-chosen` is present with settled `options.*` values ⇒ never re-ask; report the existing decision and continue at the verifier step (or route to the Exit Gate when `verification-done` is also present).
+- Re-verification (`options-chosen` + `verification-done` already complete, invoked after fixes) ⇒ confirm scope via `question` — full re-run vs only failed checks.
+- A `null` option key is unsettled — include it in the options gate; a `null` tri-state `docs_enabled` means the options gate has not run yet.
+
+### 6. Conditional activation
+
+Not applicable — `migration-verify` runs whenever its prerequisites are met. (Its own outputs activate the downstream conditionals: `migration-fix` and `migration-finalize`.)
+
+### 7. Recovery
+
+| Step                            | Max Attempts | Strategy                                                                                                                                          |
+| ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Options gate (`options-chosen`) | 1            | Re-present one consolidated gate; all 7 keys settle together                                                                                       |
+| Verification (`verification-done`) | 3         | Fix-then-reverify (max 3 cycles). **HALT on data integrity**: a failed data-integrity check is never auto-fixed — record ❌ with evidence and recommend rollback (explicit user confirmation required) |
+
+## Execute
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), then read `../migration-spec/references/migration-strategies.md` (compatibility and rollback/dual-run testing content) and `../migration-target/references/migration-types.md` (per-type verification focus).
+
+| Direction | Artifact                                    | Producer                                                          |
+| --------- | ------------------------------------------- | ----------------------------------------------------------------- |
+| Consumed  | `implementation/implementation-plan.md`, `implementation/work-log.md` | `migration-plan`, `implementation-plan-executor`      |
+| Consumed  | `analysis/rollback-plan.md`, `analysis/dual-run-plan.md` (conditional) | `migration-spec`                               |
+| Produced  | `verification/implementation-verification.md` | `implementation-verifier` (**Skill**, reused 0 changes)         |
+| Produced  | `verification/compatibility-test-results.md` | inline compatibility checks (direct, no delegation)              |
+
+**Fixed order — do not reorder: (1) options gate → (2) `implementation-verifier` → (3) compatibility checks → (4) `verification-done`.**
+
+### 1. Verification Options (`options-chosen`, inline)
+
+**Step 1** — display the plan:
+
+```
+Verification Plan:
+  Obligatory (always run):
+    ✓ Completeness check
+    ✓ Test suite (skipped — passed during implementation; re-enabled after fixes)
+  Recommended (adjustable):
+    ✓ Code review — quality and security analysis
+    ✓ Pragmatic review — detects over-engineering
+    ✓ Reality check — validates the migration solves the problem
+    ✓ Production readiness — deployment readiness checks
+  Conditional:
+    [✓/—] Operator migration guide — [reason]
+```
+
+**Step 2 — one consolidated gate** (2 `question`s, all 7 keys settle together):
+
+- **Q1** (always): `question` (multi-select) — "Which standard verifications to run?" Options: "Code review (Recommended)", "Pragmatic review (Recommended)", "Reality check (Recommended)", "Production readiness (Recommended)". All pre-selected.
+- **Q2** (always): "Generate the operator migration guide in `migration-finalize`?" — "Yes" / "No, skip".
+
+Set **all 7** `options.*` keys in one state write: `code_review_enabled`, `pragmatic_review_enabled`, `reality_check_enabled`, `production_check_enabled` from Q1; `code_review_scope: "all"` when code review is enabled, else `null`; `skip_test_suite: true` (**auto-set** — the full suite passed during implementation; `migration-fix` resets it to `false` after code changes); `docs_enabled` from Q2 (tri-state: `null` only before this gate; never left `null` afterwards).
+
+**State write**: append `options-chosen`; write all 7 `options.*` keys; bump `orchestrator.updated`; re-read + `verify_template`. **This write happens BEFORE the verifier runs** — the verifier reads its flags from state, and `null` keys make it warn-and-prompt once per key.
+
+### 2. Delegate Verification (first `verification-done` step)
+
+Skill tool — `implementation-verifier` (reused, 0 changes). Pass: `task_path`, `task_description`, the chosen options, and `verification_context` when re-verifying. It is read-only (reports, never fixes) and writes `verification/implementation-verification.md`; capture its structured output (`status`, `issues[]`, `issue_counts`).
+
+**Write immediately**: `verification_context.last_status` (`passed` / `passed_with_issues` / `failed`), `verification_context.issues_found` (aggregate counts), `migration_outputs.implementation_verification`; bump `orchestrator.updated`; re-read + `verify_template`. **Do not run the compatibility checks before this write** — they consume this verified baseline.
+
+### 3. Migration Compatibility Checks (`compatibility-test-results.md`, inline)
+
+Author the 4 checks directly (no delegation). Record each check's **Status (Pass / Fail / Not-applicable)**, **Evidence**, and notes; a not-applicable check is recorded explicitly, never silently omitted; close with an overall compatibility verdict.
+
+1. **Dual-run liveness** — the old system still works while dual-run is configured. Read `migration_context.dual_run_configured`; `false` ⇒ **Not-applicable** (recorded explicitly). `true` ⇒ verify both systems stay live and synchronized per `analysis/dual-run-plan.md`.
+2. **Non-destructive rollback test** — exercise the `analysis/rollback-plan.md` procedures in a non-production or isolated context **without destroying current state**; verify the documented validation criteria and time estimate.
+3. **Data integrity** — for data migrations (and any migration that moves/transforms data): 100% row-count, checksum, and business-rule validation against the verified baseline (per-type focus: data). Failure is a **HALT-class result**: record ❌ with evidence, never auto-fix, never retry into a pass; recommend rollback (explicit user confirmation required).
+4. **Before/after performance** — baseline comparison of key metrics before vs after; for code/architecture types this also carries the per-type focus (functional equivalence / system-level behavior).
+
+Write `verification/compatibility-test-results.md`; then write `migration_outputs.compatibility_test_results`, `phase_summaries.verify.summary`, and `verification_context.compatibility_status` — `passed` when no check is ❌, `failed` when any check is ❌ (⚠ concerns do not block) — bump `orchestrator.updated`; re-read + `verify_template`. `compatibility_status` is the persisted overall check verdict consumed by the `migration-fix` / `migration-finalize` gates; it is a check result written during Execute, never an Exit-Gate mutation.
+
+### 4. Complete Verification (`verification-done`)
+
+Append `verification-done` only once the verifier AND all 4 compatibility checks have run. ⚠/❌ verdicts are results shown in the results box; they are **never Exit-Gate state mutations** — the state facts are `verification_context.last_status`, `issues_found`, `compatibility_status`, and the compatibility report. If the verifier itself cannot run or report, do NOT append; use `failed_phases` + `auto_fix_attempts["verification-done"]`.
+
+## State Update Convention (per step)
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as each step completes: options after the options gate (before the verifier); `last_status`/`issues_found` right after the verifier (before the checks); `compatibility_status` + the compatibility paths after the checks; `verification-done` last. Never batch.
+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 VERIFY COMPLETE — <task name>
+
+**Verifier status** — [✅ passed / ⚠ passed_with_issues / ❌ failed]
+**Issues found** — [N] ([C] critical / [W] warning / [I] info)
+**Compatibility checks** — dual-run [✅ / — N/A] · rollback [✅ / ❌] · data integrity [✅ / ❌ / N/A] · performance [✅ / ⚠ / ❌]
+**Overall compatibility** — [✅ compatible / ⚠ compatible with concerns / ❌ not compatible]
+**Data integrity** — [✅ verified / ❌ HALT — recommend user-confirmed rollback]
+**Options** — code review [on/off] · pragmatic [on/off] · production [on/off] · reality [on/off] · operator guide [yes/no]
+
+**Artifacts**
+
+- `verification/implementation-verification.md`
+- `verification/compatibility-test-results.md`
+- `verification/code-review-report.md`, `verification/pragmatic-review.md`, `verification/production-readiness-report.md`, `verification/reality-check.md` [each if run]
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the verification outcome is good (including an approved proceed-with-warnings); continue.
+- **Adjust** — run additional fixes and/or another verification round within the max-3 contract, update state and artifacts, re-present the results box.
+- **Discuss** — walk through specific findings (issue details, compatibility evidence, data-integrity status) in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:migration-verify <task-path>`) and end.
+
+### Next steps (after Accept)
+
+Render ONLY the row whose condition matches the state; list the other branch under Other options:
+
+- `→ /owflow:migration-fix <task-path>` — `required` — only when `verification_context.compatibility_status = failed` **or** (`verification_context.last_status != passed` and no recorded deliberate skip): resolves issues with the data-integrity HALT and re-verifies (max 3 iterations). Remaining after: finalize.
+- `→ /owflow:migration-finalize <task-path>` — `required` — only when `compatibility_status = passed` **and** the fix phase is settled (`last_status = passed`, or `issues-resolved`/approval, or a recorded deliberate skip): author the operator guide when enabled, then complete the task. Remaining after: none — workflow ends.
+
+**Other options**:
+
+- The branch not rendered above (`migration-fix` when the finalize condition holds, or `migration-finalize` when fix is required)
+- `/owflow:migration-verify <task-path>` — `optional` — re-verification after fixes: re-runs the verifier and the 4 compatibility checks (settles `last_status` and `compatibility_status`; confirm full re-run vs only failed checks)
+- `/owflow:goal-migration <task-path>` — `optional` shortcut: runs all remaining phases in one loop (fix when needed → finalize)
+
+Then STOP.

package/dist/skills/orchestrator-framework/references/command-namespacing.md

@@ -2,6 +2,6 @@
 
 How commands and skills are named and referenced. Extracted from `orchestrator-patterns.md` (Section 8) so skills can link to it directly.
 
-- Slash commands registered from `src/commands/*.md` use `name: owflow:<command>` in frontmatter; users invoke `/owflow:<command>`.
+- Slash commands registered from `src/skills/*/SKILL.md` and from the maintained `src/commands/*.md` use `name: owflow:<command>` in frontmatter; users invoke `/owflow:<command>`.
 - **Skill `name:` fields are prefixed too.** Skill-tool invocations (`skill: "owflow:development"`, `skills:` frontmatter preloads, work.md routing) always reference `owflow:`-prefixed skill names.
 - Handoff messages, docs, and cross-references always display the prefixed slash command — never the bare skill name — in user-facing text.

package/dist/skills/orchestrator-framework/references/dispatcher-handoff.md

@@ -19,7 +19,7 @@ Orchestrators MAY delegate phase bodies to user-invocable **subskills** instead
    | development  | `codebase-analysed`, `gap-analysed`, `tdd-red-proven`, `spec-written`, `spec-audited`, `plan-created`, `implementation-done`, `tdd-green-proven`, `options-chosen`, `verification-done`, `e2e-run`, `docs-generated`, `task-completed` | `skills/development/SKILL.md`  | `templates/orchestrator-state-development.yml` |
    | research     | `brief-written`, `plan-created`, `findings-gathered`, `synthesis-complete`, `alternatives-generated`, `approaches-chosen`, `design-generated`, `research-completed`        | `skills/research/SKILL.md`       | `templates/orchestrator-state-research.yml`    |
    | performance  | `phase-N` (legacy holdout — kept internally consistent)                                                                                                                     | `skills/performance/SKILL.md`    | `templates/orchestrator-state-performance.yml` |
-   | migration    | `phase-N` (legacy holdout — kept internally consistent)                                                                                                                     | `skills/migration/SKILL.md`      | `templates/orchestrator-state-migration.yml`   |
+   | migration    | `state-analysed`, `target-planned`, `strategy-specified`, `plan-created`, `migration-executed`, `options-chosen`, `verification-done`, `issues-resolved`, `docs-generated`, `task-completed` | `skills/migration/SKILL.md`      | `templates/orchestrator-state-migration.yml`   |
 2. **Subskills are self-contained.** Each has: an entry check (validate state + prerequisite artifacts), an execute section (delegation via Skill/Task tools per the [Delegation Rules](delegation-rules.md)), and an exit (state update + closing ritual). **State updates are per-step**: a subskill writes `orchestrator-state.yml` immediately after each of its steps completes — appending only the step slug actually performed, bumping `orchestrator.updated`, recording failures in `failed_phases`/`auto_fix_attempts`, and validating with `verify_template` — never as a single end-of-skill write.
 3. **Closing ritual (handoff) → Exit Gate.** Every subskill ends with the **Exit Gate** contract, see [Gate Contract](gate-contract.md) (results box → results-acceptance question → next-step hint on accept → STOP).
 4. **Entry checks replace phase gates in assisted mode.** A subskill invoked directly must validate the same prerequisites a phase gate would (e.g., spec exists before audit) and route to the prerequisite's command if missing — via its **Entry Gate** ([Gate Contract](gate-contract.md)).

package/dist/skills/orchestrator-framework/references/fix-loop-contract.md

@@ -0,0 +1,65 @@
+# Fix Loop Contract — User-Driven Fix-Then-Reverify
+
+Shared contract for skills that resolve verification issues together with the user. It pins the option wording, iteration budget, state-write cadence, and exit conditions so each applying skill describes only its workflow-specific deltas instead of restating the loop.
+
+**Applies to**:
+
+- `dev-verify` — the `verification-done` step after `implementation-verifier` returns `passed_with_issues` or `failed`
+- `migration-fix` — when the verification state facts say fixable issues remain (`issues-resolved`)
+
+Skills that use the loop MUST reference this file and document only their deltas in the "Workflow-Specific Deltas" section.
+
+---
+
+## Loop (max 3 iterations)
+
+1. **Display the detailed issue breakdown** grouped by category and severity, with location, description, and fixability.
+2. **Present critical + warning issues as a numbered list.** Info issues are listed for awareness, not actionable.
+3. **Ask via `question`** — "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.** Immediately after each fix, append it to `verification_context.fixes_applied` in state — never defer to the end of the loop. Bump `orchestrator.updated`; re-read the state file + run `verify_template`.
+5. **After fixes, set `options.skip_test_suite: false`** (code changed — the suite must re-run on re-verification).
+6. **Ask via `question`** — "Re-run verification to check fixes?" with options:
+   - **"Yes, re-run verification"** → re-invoke `implementation-verifier` (Skill tool), then **immediately** update `verification_context.reverify_count` and refresh `verification_context.last_status` + `issues_found` from the verifier's structured return; return to step 1.
+   - **"No, proceed to next phase"** → exit the loop to the Exit Gate.
+7. **Record each user decision** (specific selection, proceed-with-warnings, deliberate skip) in `verification_context.decisions_made`.
+
+The loop is capped at **3 iterations**; at the cap, the question in "Exit Conditions" decides the outcome.
+
+---
+
+## Exit Conditions
+
+| Condition | Action |
+| --------- | ------ |
+| ✅ No critical issues remain | Append the skill's success slug and proceed. |
+| ⚠ Max 3 iterations reached | `question` — "Proceed with known issues?" / stop-or-rollback option. Proceed ⇒ append the success slug with the approval recorded in `decisions_made`; stop/rollback ⇒ do NOT append, record the decision. |
+| Deliberate skip ("Skip fixes, proceed as-is") | A user-chosen skip, not a failure: no success slug, no failure entry; record the reason in `phase_summaries.<fix>.summary` + `decisions_made`. |
+| ❌ Critical issues remain unresolved | **MUST NOT proceed without explicit user approval.** |
+| Verifier itself fails | Do NOT append the success slug; append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["<slug>"]`. |
+
+---
+
+## State Writes (per iteration, never batched)
+
+- `fixes_applied` — after every fix.
+- `reverify_count` + refreshed `last_status` / `issues_found` — right after each verifier run.
+- `decisions_made` — after each user decision.
+- The success slug — only when the loop settles (✅, or an approved ⚠); never on a deliberate skip or a failure.
+
+**Single-writer split**: the verification step owns the initial `last_status` / `issues_found`; the fix loop owns `fixes_applied`, `reverify_count`, `decisions_made`, plus the re-verify refresh of `last_status` / `issues_found`.
+
+---
+
+## Workflow-Specific Deltas
+
+### Development (`dev-verify`)
+
+None beyond this contract.
+
+### Migration (`migration-fix`)
+
+- **Compatibility verdict invalidation**: after fixes, set `verification_context.compatibility_status: null` (field-level fail-closed exception — the compatibility checks ran against pre-fix code). Only `migration-verify` may set a new verdict; when it is not `passed`, the required next step is `/owflow:migration-verify <task-path>`, never finalize.
+- **Data-integrity HALT**: data-integrity issues are NEVER auto-fixed. HALT, present the rollback option with the issue, and append the failure entry; 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.

package/dist/skills/orchestrator-framework/references/gate-contract.md

@@ -1,112 +1,117 @@
-# Gate Contract — Entry Gate & Exit Gate (Skill Contract)
-
-Shared contract for how every user-invocable skill opens and closes. Extracted from `orchestrator-patterns.md` (Section 9) so skills can link to it directly.
-
-Every **user-invocable** skill (orchestrators, subskills, dispatchers, utility commands) opens with an **Entry Gate** and closes with an **Exit Gate**. Internal skills (subagent-invoked, `user-invocable: false`) use lightweight input/structured-output contracts instead and never call `question`.
-
-## Entry Gate
-
-The Entry Gate runs BEFORE any phase work. It validates that this skill is allowed to run and routes to what is missing instead of guessing.
-
-1. **Argument resolution** — resolve the argument in priority order: full path → identifier (directory name under the workflow's task type) → fresh description. If missing, ambiguous, or unmatched:
-   - Print a structured ask: the exact inputs accepted, with format examples, then WAIT.
-   - NEVER guess, auto-pick a task, or proceed with a resolved-by-hope path.
-2. **Prerequisite check** — verify each required upstream artifact, expressed as a table the skill keeps at the top of its body:
-
-   | Required for this skill | Where verified                                                      | Produced by                  |
-   | ----------------------- | ------------------------------------------------------------------- | ---------------------------- |
-   | State file exists       | `<task-path>/orchestrator-state.yml`                                | `/owflow:development <desc>` |
-   | Analysis done           | `gap-analysed` in `completed_phases` + `analysis/gap-analysis.md` exists | `/owflow:dev-analyze`        |
-   | Spec approved           | `implementation/spec.md` exists                                     | `/owflow:dev-spec`           |
-
-   Verify **presence and, where cheap, content** (state field values like `has_reproducible_defect`, marker artifacts like `implementation/tdd-red-gate.md`), not just file existence.
-
-3. **Blocked output** — when a prerequisite is unmet, print the blocked block and STOP:
-   1. Numbered "Steps that must be completed first (in order)", each with its exact prefixed command (`/owflow:dev-analyze <task-path>`).
-   2. List of resumable task identifiers (directories under the workflow's task type), if any exist.
-   3. Fresh-start hint: `Run /owflow:<entry-command> <description> to start a task from scratch.`
-4. **Skip/resume semantics** — when the skill's steps are already in `completed_phases` (validate artifacts before trusting state): report the existing results briefly and route to the Exit Gate instead of re-executing.
-5. **Conditional activation** — skills that only apply under a state condition (e.g., TDD red gate requires `has_reproducible_defect: true`) check it as part of the Entry Gate and route to the correct alternative command when inactive.
-
-### Missing-state bootstrap (mid-pipeline entry)
-
-When a subskill is invoked with a task path/identifier whose `orchestrator-state.yml` exists nowhere (no task, no state file) and the ONLY unmet prerequisite is the state file itself, the skill does not blindly send the user back to the full pipeline — the user chose to enter mid-pipeline. Instead:
-
-1. **Ask** via `question`: "No task exists at this path. Create a fresh standard task and start at `<this skill's first step slug>`?"
-2. **On confirm (bootstrap)**:
-   - Create the task directory `.owflow/tasks/<workflow-type>/YYYY-MM-DD-task-name/` (name derived from the argument or the user's input) — mark `orchestrator.entry_point: "<skill> (mid-pipeline bootstrap)"` and `started_phase` with this skill's starting step slug.
-   - Create `orchestrator-state.yml` from the workflow's template, honoring any of the skill's command flags into their state fields; leave `completed_phases` empty (upstream steps stay unrecorded).
-   - Run `verify_template` against the workflow's template.
-   - Then continue into Execute. Because bootstrapping creates **state only — never upstream artifacts**, later artifact prerequisites (e.g., `implementation/spec.md` before planning) still block with the normal precondition loop, so an incorrectly early bootstrap cannot silently skip work.
-3. **On decline** — print the blocked block with the fresh-start hint and STOP.
-
-#### dev-* bootstrap
-
-- Task directory under `.owflow/tasks/development/`; template `orchestrator-state-development.yml`; fresh-start hint: `Run /owflow:development <description> to start a task from scratch.`
-- Skill starting points (used for the bootstrap question and `started_phase`): dev-analyze → `codebase-analysed`; dev-tdd-red → `tdd-red-proven`; dev-spec → `spec-written`; dev-plan → `plan-created`; dev-implement → `implementation-done`; dev-verify → `options-chosen`; dev-finalize → `e2e-run`.
-
-#### research-* bootstrap
-
-- Task directory under `.owflow/tasks/research/`; template `orchestrator-state-research.yml`; fresh-start hint: `Run /owflow:research <question> to start a task from scratch.`
-- Skill starting points (used for the bootstrap question and `started_phase`): research-plan → `brief-written`; research-gather → `findings-gathered`; research-synthesize → `synthesis-complete`; research-brainstorm → `alternatives-generated`; research-converge → `approaches-chosen`; research-design → `design-generated`; research-finalize → `research-completed`.
-
-### Deterministic entry checks (future)
-
-Entry-gate checks above are currently executed by the agent reading state. For more deterministic routing, future work considers (a) a small script that checks whether `orchestrator-state.yml` exists, parses it, and answers slug/next-step queries, and (b) an OpenCode lifecycle hook that automates these entry-gate checks for dev-* skills before they run. Until then, follow the rules above exactly as written.
-
-## Exit Gate
-
-The Exit Gate runs after all phase work and state updates are final. It presents results, asks the user to confirm them, and only then hands off.
-
-1. **Results box** — one-screen markdown summary (no ASCII borders, markdown headings/bold carry the emphasis):
-
-   ```markdown
-   ## ✅ <SKILL> COMPLETE — <task name>
-
-   **<Field 1>** — [key outcome]
-   **<Field 2>** — [key outcome]
-
-   **Artifacts**
-
-   - `relative/path/to/artifact.md`
-
-   **Next ▸** `/owflow:<next-skill> <task-path>`
-   ```
-
-   Conventions:
-   - Status glyphs follow the outcome: ✅ pass/success, ⚠ pass-with-concerns/partial, ❌ fail.
-   - Set the **Next ▸** line to the suggested next command for this skill; omit it when the next-step hint depends on the Accept response (the handoff block is printed after Accept anyway).
-
-2. **Results-acceptance question** (MANDATORY, fires before any handoff hint):
-
-   Use `question` — "Are these results correct?" with options:
-   - **Accept** — results are good; proceed to the next-step hint.
-   - **Adjust** — user specifies what to change; re-work ONLY the affected parts, update artifacts/state, then re-present the results box and re-ask.
-   - **Discuss** — walk through a specific result in more depth (evidence, reasoning, alternatives); after the discussion, re-ask.
-   - **Stop here** — artifacts persist; print the resume command (`/owflow:<this-skill> <task-path>` or the next phase command) and end.
-
-3. **Next-step hint** — only after Accept: print the suggested next command derived from state, plus an "Other options" block of alternative valid commands. Every suggested command is a **compact annotated entry**:
-   - **Purpose** — one line stating what the proposed skill does.
-   - **Requirement tag** — `required` (mandatory next phase) or `optional` (shortcut, standalone utility, or conditional step) with its activation condition, e.g. `optional — only when has_reproducible_defect: true`.
-   - **Remaining plan** (for optional/alternative paths) — one compact line listing the phases still ahead in execution order, marking which are optional.
-   - Standalone review/utility commands are annotated `optional — does not advance phases`.
-
-   Example shape (~5 lines):
-
-   ```
-   → /owflow:dev-verify <task-path>
-     What: runs the verification pipeline (completeness, code review, fixes) — required before commit. Remaining after: /owflow:dev-finalize (required).
-   Other options:
-   /owflow:reviews-code <task-path> — optional, does not advance phases (standalone re-run of code review)
-   /owflow:goal-development <task-path> — optional shortcut: runs all remaining phases in one loop (… → verify → finalize)
-   ```
-
-   Then STOP. Never auto-invoke the next skill.
-
-4. **Gate ordering** — per the Phase Gate Behavior state ordering rule in `orchestrator-patterns.md`: finish phase work → present results box → acceptance question → user responds → THEN the state is already consistent (per-step writes happened during Execute); the Exit Gate never mutates phase state on its own except recording the user's acceptance decision where the state schema has a field for it.
-
-## Exceptions
-
-- **Dispatchers** (`development`, `research`): the Exit Gate's acceptance question is adapted — the results box is the handoff block, and the question asks how to proceed (hand off to the suggested subskill / switch to autonomous mode / adjust / stop).
-- **Utility skills with explicit no-follow-up contracts** (`agents-md-generator`, `rule-reviewer`): the acceptance question is confirm-or-revise only; follow-up suggestions stay prohibited unless the user asks. See [confirm-or-revise exception](confirm-or-revise-exception.md).
-- **Orchestrated mode** (`goal-development`, `goal-research`): the subskill's own Exit Gate acceptance question IS the loop gate — Accept means "continue to the next subskill". The wrapper MUST NOT add a second consecutive `question`.
+# Gate Contract — Entry Gate & Exit Gate (Skill Contract)
+
+Shared contract for how every user-invocable skill opens and closes. Extracted from `orchestrator-patterns.md` (Section 9) so skills can link to it directly.
+
+Every **user-invocable** skill (orchestrators, subskills, dispatchers, utility commands) opens with an **Entry Gate** and closes with an **Exit Gate**. Internal skills (subagent-invoked, `user-invocable: false`) use lightweight input/structured-output contracts instead and never call `question`.
+
+## Entry Gate
+
+The Entry Gate runs BEFORE any phase work. It validates that this skill is allowed to run and routes to what is missing instead of guessing.
+
+1. **Argument resolution** — resolve the argument in priority order: full path → identifier (directory name under the workflow's task type) → fresh description. If missing, ambiguous, or unmatched:
+   - Print a structured ask: the exact inputs accepted, with format examples, then WAIT.
+   - NEVER guess, auto-pick a task, or proceed with a resolved-by-hope path.
+2. **Prerequisite check** — verify each required upstream artifact, expressed as a table the skill keeps at the top of its body:
+
+   | Required for this skill | Where verified                                                      | Produced by                  |
+   | ----------------------- | ------------------------------------------------------------------- | ---------------------------- |
+   | State file exists       | `<task-path>/orchestrator-state.yml`                                | `/owflow:development <desc>` |
+   | Analysis done           | `gap-analysed` in `completed_phases` + `analysis/gap-analysis.md` exists | `/owflow:dev-analyze`        |
+   | Spec approved           | `implementation/spec.md` exists                                     | `/owflow:dev-spec`           |
+
+   Verify **presence and, where cheap, content** (state field values like `has_reproducible_defect`, marker artifacts like `implementation/tdd-red-gate.md`), not just file existence.
+
+3. **Blocked output** — when a prerequisite is unmet, print the blocked block and STOP:
+   1. Numbered "Steps that must be completed first (in order)", each with its exact prefixed command (`/owflow:dev-analyze <task-path>`).
+   2. List of resumable task identifiers (directories under the workflow's task type), if any exist.
+   3. Fresh-start hint: `Run /owflow:<entry-command> <description> to start a task from scratch.`
+4. **Skip/resume semantics** — when the skill's steps are already in `completed_phases` (validate artifacts before trusting state): report the existing results briefly and route to the Exit Gate instead of re-executing.
+5. **Conditional activation** — skills that only apply under a state condition (e.g., TDD red gate requires `has_reproducible_defect: true`) check it as part of the Entry Gate and route to the correct alternative command when inactive.
+
+### Missing-state bootstrap (mid-pipeline entry)
+
+When a subskill is invoked with a task path/identifier whose `orchestrator-state.yml` exists nowhere (no task, no state file) and the ONLY unmet prerequisite is the state file itself, the skill does not blindly send the user back to the full pipeline — the user chose to enter mid-pipeline. Instead:
+
+1. **Ask** via `question`: "No task exists at this path. Create a fresh standard task and start at `<this skill's first step slug>`?"
+2. **On confirm (bootstrap)**:
+   - Create the task directory `.owflow/tasks/<workflow-type>/YYYY-MM-DD-task-name/` (name derived from the argument or the user's input) — mark `orchestrator.entry_point: "<skill> (mid-pipeline bootstrap)"` and `started_phase` with this skill's starting step slug.
+   - Create `orchestrator-state.yml` from the workflow's template, honoring any of the skill's command flags into their state fields; leave `completed_phases` empty (upstream steps stay unrecorded).
+   - Run `verify_template` against the workflow's template.
+   - Then continue into Execute. Because bootstrapping creates **state only — never upstream artifacts**, later artifact prerequisites (e.g., `implementation/spec.md` before planning) still block with the normal precondition loop, so an incorrectly early bootstrap cannot silently skip work.
+3. **On decline** — print the blocked block with the fresh-start hint and STOP.
+
+#### dev-* bootstrap
+
+- Task directory under `.owflow/tasks/development/`; template `orchestrator-state-development.yml`; fresh-start hint: `Run /owflow:development <description> to start a task from scratch.`
+- Skill starting points (used for the bootstrap question and `started_phase`): dev-analyze → `codebase-analysed`; dev-tdd-red → `tdd-red-proven`; dev-spec → `spec-written`; dev-plan → `plan-created`; dev-implement → `implementation-done`; dev-verify → `options-chosen`; dev-finalize → `e2e-run`.
+
+#### research-* bootstrap
+
+- Task directory under `.owflow/tasks/research/`; template `orchestrator-state-research.yml`; fresh-start hint: `Run /owflow:research <question> to start a task from scratch.`
+- Skill starting points (used for the bootstrap question and `started_phase`): research-plan → `brief-written`; research-gather → `findings-gathered`; research-synthesize → `synthesis-complete`; research-brainstorm → `alternatives-generated`; research-converge → `approaches-chosen`; research-design → `design-generated`; research-finalize → `research-completed`.
+
+#### migration-* bootstrap
+
+- Task directory under `.owflow/tasks/migrations/`; template `orchestrator-state-migration.yml`; fresh-start hint: `Run /owflow:migration <description> to start a migration task from scratch.`
+- Skill starting points (used for the bootstrap question and `started_phase`): migration-analyze → `state-analysed`; migration-target → `target-planned`; migration-spec → `strategy-specified`; migration-plan → `plan-created`; migration-implement → `migration-executed`; migration-verify → `options-chosen`; migration-fix → `issues-resolved`; migration-finalize → `task-completed`.
+
+### Deterministic entry checks (future)
+
+Entry-gate checks above are currently executed by the agent reading state. For more deterministic routing, future work considers (a) a small script that checks whether `orchestrator-state.yml` exists, parses it, and answers slug/next-step queries, and (b) an OpenCode lifecycle hook that automates these entry-gate checks for dev-* skills before they run. Until then, follow the rules above exactly as written.
+
+## Exit Gate
+
+The Exit Gate runs after all phase work and state updates are final. It presents results, asks the user to confirm them, and only then hands off.
+
+1. **Results box** — one-screen markdown summary (no ASCII borders, markdown headings/bold carry the emphasis):
+
+   ```markdown
+   ## ✅ <SKILL> COMPLETE — <task name>
+
+   **<Field 1>** — [key outcome]
+   **<Field 2>** — [key outcome]
+
+   **Artifacts**
+
+   - `relative/path/to/artifact.md`
+
+   **Next ▸** `/owflow:<next-skill> <task-path>`
+   ```
+
+   Conventions:
+   - Status glyphs follow the outcome: ✅ pass/success, ⚠ pass-with-concerns/partial, ❌ fail.
+   - Set the **Next ▸** line to the suggested next command for this skill; omit it when the next-step hint depends on the Accept response (the handoff block is printed after Accept anyway).
+
+2. **Results-acceptance question** (MANDATORY, fires before any handoff hint):
+
+   Use `question` — "Are these results correct?" with options:
+   - **Accept** — results are good; proceed to the next-step hint.
+   - **Adjust** — user specifies what to change; re-work ONLY the affected parts, update artifacts/state, then re-present the results box and re-ask.
+   - **Discuss** — walk through a specific result in more depth (evidence, reasoning, alternatives); after the discussion, re-ask.
+   - **Stop here** — artifacts persist; print the resume command (`/owflow:<this-skill> <task-path>` or the next phase command) and end.
+
+3. **Next-step hint** — only after Accept: print the suggested next command derived from state, plus an "Other options" block of alternative valid commands. Every suggested command is a **compact annotated entry**:
+   - **Purpose** — one line stating what the proposed skill does.
+   - **Requirement tag** — `required` (mandatory next phase) or `optional` (shortcut, standalone utility, or conditional step) with its activation condition, e.g. `optional — only when has_reproducible_defect: true`.
+   - **Remaining plan** (for optional/alternative paths) — one compact line listing the phases still ahead in execution order, marking which are optional.
+   - Standalone review/utility commands are annotated `optional — does not advance phases`.
+
+   Example shape (~5 lines):
+
+   ```
+   → /owflow:dev-verify <task-path>
+     What: runs the verification pipeline (completeness, code review, fixes) — required before commit. Remaining after: /owflow:dev-finalize (required).
+   Other options:
+   /owflow:reviews-code <task-path> — optional, does not advance phases (standalone re-run of code review)
+   /owflow:goal-development <task-path> — optional shortcut: runs all remaining phases in one loop (… → verify → finalize)
+   ```
+
+   Then STOP. Never auto-invoke the next skill.
+
+4. **Gate ordering** — per the Phase Gate Behavior state ordering rule in `orchestrator-patterns.md`: finish phase work → present results box → acceptance question → user responds → THEN the state is already consistent (per-step writes happened during Execute); the Exit Gate never mutates phase state on its own except recording the user's acceptance decision where the state schema has a field for it.
+
+## Exceptions
+
+- **Dispatchers** (`development`, `research`, `migration`): the Exit Gate's acceptance question is adapted — the results box is the handoff block, and the question asks how to proceed (hand off to the suggested subskill / switch to autonomous mode / adjust / stop).
+- **Utility skills with explicit no-follow-up contracts** (`agents-md-generator`, `rule-reviewer`): the acceptance question is confirm-or-revise only; follow-up suggestions stay prohibited unless the user asks. See [confirm-or-revise exception](confirm-or-revise-exception.md).
+- **Orchestrated mode** (`goal-development`, `goal-research`, `goal-migration`): the subskill's own Exit Gate acceptance question IS the loop gate — Accept means "continue to the next subskill". The wrapper MUST NOT add a second consecutive `question`.

package/dist/skills/orchestrator-framework/references/orchestrator-patterns.md

@@ -8,6 +8,7 @@ Some heavily cross-referenced sections live in their own reference files:
 - [Dispatcher & Handoff Pattern](dispatcher-handoff.md) — subskill loop, mode table, per-step state writes (was Section 7)
 - [Command Namespacing](command-namespacing.md) — `owflow:` prefix rules (was Section 8)
 - [Gate Contract](gate-contract.md) — Entry Gate & Exit Gate skill contract, incl. exceptions (was Section 9)
+- [Fix Loop Contract](fix-loop-contract.md) — user-driven fix-then-reverify contract: option wording, iteration budget, exit conditions, per-iteration state writes
 
 Section numbering below is kept as-is so existing cross-references stay valid.
 
@@ -129,7 +130,7 @@ Orchestrators add domain-specific fields using `[domain]_context`:
 | ----------- | --------------------- | -------------------------------------------------- |
 | Development | `task_context`        | risk_level, ui_heavy, architecture_decision        |
 | Performance | `performance_context` | baseline_p95, target_p95, optimizations_completed  |
-| Migration   | `migration_context`   | migration_type, steps_completed                    |
+| Migration   | `migration_context`   | migration_type, target_system, risk_level          |
 | Research    | `research_context`    | research_type, research_question, confidence_level |
 
 See each orchestrator's SKILL.md "Domain Context" section for full schema.
@@ -205,6 +206,8 @@ If prerequisites missing, use question: "Start from Phase 1", "Specify different
 
 ### Fix-Then-Reverify Loop
 
+The canonical user-driven contract — option wording, iteration budget, exit conditions, and per-iteration state writes — lives in [Fix Loop Contract](fix-loop-contract.md); skills with a fix phase reference it and document only their deltas. The generic shape:
+
 1. Read verification results (structured issues)
 2. For each issue: trivial/auto-fixable → fix silently, log action; non-trivial → question
 3. If fixes applied → set `skip_test_suite: false` (code changed) → re-run verification

package/dist/skills/performance/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: owflow:performance
 description: Orchestrates performance optimization workflows using static code analysis to identify bottlenecks (N+1 queries, missing indexes, O(n^2) algorithms, blocking I/O, memory leaks). Accepts optional user-provided profiling data. Reuses standard specification, planning, implementation, and verification phases.
+argument-hint: "[task description]"
 user-invocable: true
 ---