@code-migration/wow-migrator 0.1.2 → 0.1.3

package/skills/migration-task-adapter/MIGRATION.md

@@ -11,7 +11,7 @@ The `migration-task-adapter` is a control-plane skill. It decides which existing
 | `only_understand_architecture` | `android-project-analyst` | Analyst output root, `project-architecture` artifacts, module/global representation |
 | `only_understand_overview` | `android-project-analyst` | Analyst output root, module inventory, module/global representation, SPEC package |
 | `migration` | `android-project-analyst` then `android-to-kmp-migrator` | Fresh analyst SPEC before migrator; migration report before validation handoff |
-| `validation_handoff` | `kmp-test-validator` | Migration report plus Android source/SPEC and KMP target evidence |
+| `validation_handoff` | `kmp-test-validator` | Migration report plus Android source/SPEC and KMP target evidence; validator output root is the parallel `validation` location |
 
 ## Required Adapter Records
 
@@ -32,3 +32,18 @@ For migration tasks, the adapter must not invoke `android-to-kmp-migrator` until
 - The adapter first routes and observes an `android-project-analyst` migration-mode run that produces fresh SPEC artifacts.
 
 If the migrator returns `ready_for_validation`, the adapter records the migration report and either routes `kmp-test-validator` or returns `ready_for_validation` with an explicit validation handoff requirement.
+
+## Output Contract Refinement
+
+The active adapter docs now distinguish output filenames from output content responsibilities. `SKILL.md` and `workflow.md` define the artifact schedule and content matrix, while each role file states the exact JSON/Markdown filenames and the evidence each artifact must contain.
+
+Role ownership is explicit:
+
+- `task_understanding_router.*` records the task interpretation, route, focus, inputs, artifact evidence, downstream sequence, and required inspections/assets.
+- `workflow_orchestration.*` records downstream dispatch contracts, output roots, expected/observed artifacts, stage requests, asset updates, reruns, and blockers.
+- `workspace_state_discipline.*` records adapter discipline state, artifact inventory, path/freshness checks, reruns, blockers, and next actions.
+- `stage_inspection.*` records a single stage gate with checked inputs/outputs, compliance, freshness, asset coverage, reruns, blockers, and next stage.
+- `intermediate_asset_records.*` records every consumed adapter/downstream artifact with producer, path, status, freshness, consumers, evidence, and gaps.
+- `task_adapter_report.*` records the final verified adapter status, downstream summaries, stage/asset summaries, readiness, reruns, blockers, and next action.
+
+The adapter must reject artifacts that have the correct filename but contain another role's work, generic downstream summaries without machine-routable evidence, or downstream validator paths written under the migration output root instead of the parallel `validation` output root.

package/skills/migration-task-adapter/SKILL.md

@@ -103,6 +103,24 @@ Required artifacts:
 - `<report_dir>/task_adapter_report.json`
 - `<report_dir>/task_adapter_report.md`
 
+## Output Artifact Content Matrix
+
+The adapter verifies both artifact names and role-aligned content before any downstream stage consumes an artifact.
+
+| Stage / owner | Output file(s) | Required content |
+|---|---|---|
+| Output root lock / Leader | `run_manifest.json` | Task id, raw task summary, requested scope, source/target paths when provided, adapter output root, allowed roots, downstream workflow candidates, dependency-preflight status, schedule version, timestamp. |
+| Task route / `task-understanding-router` | `task_understanding_router.json`, `task_understanding_router.md` | Normalized task, route, task kind, understand focus, source/target/scope fields, existing artifact evidence, required/missing inputs, downstream workflow sequence, stage inspection requirements, intermediate asset requirements, blockers. |
+| Orchestration / `workflow-orchestrator` | `workflow_orchestration.json`, `workflow_orchestration.md` | Downstream workflow sequence, dispatch contracts, expected output roots/artifacts, route constraints, stage inspection requests, observed downstream outputs, intermediate asset updates, rerun requests, blockers. |
+| Workspace discipline / `workspace-state-discipline-inspector` | `workspace_state_discipline.json`, `workspace_state_discipline.md` | Adapter artifact inventory, stage status, path compliance, freshness checks, intermediate asset coverage, rerun history, blockers, next safe actions. No task routing or downstream analysis. |
+| Stage inspections / `workspace-state-discipline-inspector` | `<stage_inspection_dir>/<stage_id>/stage_inspection.json`, `.md` | Checked inputs/outputs, path compliance, freshness checks, intermediate asset coverage, downstream contract checks, stage status, rerun requests, blockers, next allowed stage. |
+| Intermediate assets / `workspace-state-discipline-inspector` | `intermediate_asset_records.json`, `intermediate_asset_records.md` | Stable records for every consumed adapter/downstream artifact: asset id/type, producer, path, status, freshness basis, consumers, source evidence, coverage gaps, blockers. |
+| Final task report / `task-reporter` | `task_adapter_report.json`, `task_adapter_report.md` | Final route/status/readiness, source/target paths, downstream workflow summaries, stage inspection summary, intermediate asset summary, verified outputs, rerun requests, blockers, report path. |
+
+Downstream output roots are external asset paths. The adapter records them but does not write into them: `android-project-analyst` writes to its understand output root, `android-to-kmp-migrator` writes to its migration output root, and `kmp-test-validator` writes to its parallel validation output root.
+
+JSON artifacts are the machine-routable source of truth. Markdown artifacts are agent-readable handoffs that preserve exact paths, route decisions, stage evidence, asset records, rerun context, blockers, and downstream routing. Adapter Markdown must not be prose-only summaries.
+
 ## Shared Return Contract
 
 ```json

package/skills/migration-task-adapter/bind.md

@@ -17,6 +17,8 @@
 - **Task-first routing**: `task-understanding-router` must complete before any downstream workflow is selected. A guessed route is invalid.
 - **Strict output root**: the Leader must lock `output_root = <output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter` before role dispatch. Adapter roles write only under this root.
 - **Downstream boundary**: analyst, migrator, and validator artifacts stay under their own declared output roots. The adapter records their paths and statuses in intermediate asset records.
+- **Downstream output-root alignment**: validator outputs must be recorded under the validator's parallel `validation` output root, not under the migration output root. The adapter may route to `kmp-test-validator`, but it must record validator artifacts as external downstream assets.
+- **Role-output content discipline**: required adapter artifacts must contain the content owned by their role, not just the correct filename. `task_understanding_router.*` must contain route/evidence requirements, `workflow_orchestration.*` must contain downstream contracts/observations, `workspace_state_discipline.*` and `stage_inspection.*` must contain inspection evidence, `intermediate_asset_records.*` must contain asset records, and `task_adapter_report.*` must contain the final verified report.
 - **Stage inspection discipline**: every route boundary and downstream workflow boundary must have a `stage_inspection.json` and `.md`. A stage inspection must say whether the next stage is `pass`, `needs_rerun`, or `blocked`.
 - **Intermediate asset discipline**: every durable artifact consumed by another stage must have one asset record with producer, path, status, freshness basis, consumers, and gaps.
 - **Workspace-state freshness**: the adapter must refresh `workspace-state-discipline-inspector` after task routing, after downstream workflow completion, before report, and after report.
@@ -79,7 +81,8 @@ No downstream stage may consume a durable artifact whose record is `missing`, `s
 | Failure mode | Response |
 |---|---|
 | Node timeout | Retry once with the same contract. On second timeout, record `[ROLE MISSING - node timed out]` in workspace discipline and block any stage that hard-requires it. |
-| Malformed output or missing JSON/MD artifacts | Rerun the same role once with the expected schema and output paths inlined. On second failure, record `[ROLE MISSING - malformed output]` and block downstream consumption. |
+| Malformed output or missing JSON/MD artifacts | Rerun the same role once with the expected schema, output paths, and role-owned output content inlined. On second failure, record `[ROLE MISSING - malformed output]` and block downstream consumption. |
+| Adapter output written outside `output_root` or downstream validator output recorded under migration root | Reject the output as out-of-path; rerun the owning adapter role with the path contract and downstream output-root rules inlined. |
 | Route is ambiguous | Rerun `task-understanding-router` with the ambiguity. If still ambiguous, ask the user for source path, target path, task target, or scope. |
 | Stage inspection missing or malformed | Rerun `workspace-state-discipline-inspector` for that `stage_id`. Do not proceed past the stage. |
 | Intermediate asset record missing for consumed artifact | Rerun `workspace-state-discipline-inspector` to repair the asset ledger before downstream consumption. |

package/skills/migration-task-adapter/dependencies.yaml

@@ -12,7 +12,7 @@ skills:
     purpose: Downstream workflow for Android-to-KMP migration after analyst evidence is fresh.
   - name: kmp-test-validator
     required: false
-    purpose: Downstream workflow for post-migration validation when migration report evidence is ready.
+    purpose: Downstream workflow for post-migration validation when migration report evidence is ready; outputs must be recorded under the validator's parallel validation root.
 
 tools:
   - name: rg

package/skills/migration-task-adapter/roles/task-reporter.md

@@ -68,6 +68,11 @@ You are the `task-reporter` node subagent dispatched by the `migration-task-adap
 
 Shared controller return shape: `status`, `node`, `task_id`, `route`, `output_dir`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `task_adapter_report.json`: machine-routable final adapter report containing final status, task id, route, understand focus, source/target paths, output root, downstream workflow summary, stage inspection summary, intermediate asset summary, verified outputs, readiness, rerun requests, blockers, and report path.
+- `task_adapter_report.md`: agent-readable final handoff containing route decision, downstream workflow evidence, stage inspection status, intermediate asset coverage, verified outputs, readiness decision, rerun requests, blockers, and next action. It must not re-run or reinterpret downstream workflows.
+
 ## Status Decision Rules
 
 - `completed`: only-understand route has required analyst outputs, stage inspections pass, intermediate assets are recorded, and no blocking gaps remain.
@@ -117,8 +122,8 @@ HANDLER (how you process):
 7. Emit exact rerun_requests and blocking_gaps.
 
 OUTPUTS (write under output_dir, exact names):
-- task_adapter_report.json
-- task_adapter_report.md
+- task_adapter_report.json (machine final report: status, route, downstream/stage/asset summaries, verified outputs, reruns, blockers)
+- task_adapter_report.md (agent final handoff: evidence-backed route result, readiness, next actions)
 
 RETURN TO CONTROLLER (shared shape, no preamble):
 { "status": "completed | ready_for_validation | needs_rerun | failed | blocked",

package/skills/migration-task-adapter/roles/task-understanding-router.md

@@ -76,6 +76,11 @@ You are the `task-understanding-router` node subagent dispatched by the `migrati
 
 Shared controller return shape: `status`, `node`, `task_id`, `route`, `output_dir`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `task_understanding_router.json`: machine-routable route decision artifact containing task id, normalized task summary, route, task kind, understand focus, source/target/scope fields, existing artifact status, required inputs, missing inputs, downstream workflow sequence, stage inspection requirements, intermediate asset requirements, blockers, and evidence paths.
+- `task_understanding_router.md`: agent-readable routing handoff containing task interpretation, selected route and rationale, input/path requirements, existing artifact evidence, missing inputs, downstream workflow sequence, stage inspection requirements, intermediate asset requirements, and blockers.
+
 ## Inline Persona for Teammate
 
 ```
@@ -123,8 +128,8 @@ HANDLER (how you process):
 6. Return blocked when required route inputs are missing or contradictory.
 
 OUTPUTS (write under output_dir, exact names):
-- task_understanding_router.json
-- task_understanding_router.md
+- task_understanding_router.json (machine route decision: task, route, focus, evidence, required/missing inputs, downstream sequence)
+- task_understanding_router.md (agent handoff: route rationale, input requirements, artifact evidence, blockers)
 
 RETURN TO CONTROLLER (shared shape, no preamble):
 { "status": "routed | blocked", "node": "task-understanding-router", "task_id": "",

package/skills/migration-task-adapter/roles/workflow-orchestrator.md

@@ -70,6 +70,11 @@ You are the `workflow-orchestrator` node subagent dispatched by the `migration-t
 
 Shared controller return shape: `status`, `node`, `task_id`, `route`, `output_dir`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `workflow_orchestration.json`: machine-routable orchestration artifact containing route, focus, downstream sequence, dispatch contracts, expected output roots, expected artifacts, observed downstream outputs, route constraints, stage inspection requests, intermediate asset record updates, rerun requests, and blockers.
+- `workflow_orchestration.md`: agent-readable orchestration handoff containing downstream workflow plan, dispatch contracts by workflow, expected/observed artifact tables, validator validation-root note when applicable, rerun/blocker routing, and stage inspection requests.
+
 ## Dispatch Contract Requirements
 
 For `android-project-analyst`:
@@ -129,8 +134,8 @@ HANDLER (how you process):
    output.
 
 OUTPUTS (write under output_dir, exact names):
-- workflow_orchestration.json
-- workflow_orchestration.md
+- workflow_orchestration.json (machine orchestration: downstream sequence/contracts, expected/observed outputs, asset updates, reruns)
+- workflow_orchestration.md (agent handoff: workflow plan, output roots, artifact tables, rerun/blocker routing)
 
 RETURN TO CONTROLLER (shared shape, no preamble):
 { "status": "completed | needs_rerun | blocked", "node": "workflow-orchestrator",

package/skills/migration-task-adapter/roles/workspace-state-discipline-inspector.md

@@ -58,6 +58,15 @@ You are the `workspace-state-discipline-inspector` node subagent dispatched by t
 
 Shared controller return shape: `status`, `node`, `task_id`, `route`, `output_dir`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Files And Contents
+
+- `workspace_state_discipline.json`: machine-routable discipline ledger containing task id, route, output root, current stage id, stage status inventory, artifact inventory, intermediate asset records summary, path compliance, freshness checks, rerun history, blockers, and next actions.
+- `workspace_state_discipline.md`: agent-readable discipline handoff containing stage status table, artifact inventory, path/freshness findings, rerun/blocker history, and next safe action.
+- `<stage_inspection_dir>/<current_stage_id>/stage_inspection.json`: machine-routable stage gate artifact containing checked inputs/outputs, path compliance, freshness checks, intermediate asset coverage, downstream contract checks, rerun requests, blockers, and next allowed stage.
+- `<stage_inspection_dir>/<current_stage_id>/stage_inspection.md`: agent-readable stage inspection handoff with the same checks as evidence tables.
+- `<intermediate_asset_dir>/intermediate_asset_records.json`: machine-routable asset ledger containing every consumed adapter/downstream artifact record, status, freshness basis, consumers, source evidence, and coverage gaps.
+- `<intermediate_asset_dir>/intermediate_asset_records.md`: agent-readable asset handoff listing consumed artifacts, producer, path, status, freshness, consumers, gaps, and blockers.
+
 ## Stage Inspection Schema
 
 ```json
@@ -167,12 +176,12 @@ HANDLER (how you process):
 6. Identify the next safe controller action.
 
 OUTPUTS (write under output_dir and shared dirs, exact names):
-- workspace_state_discipline.json
-- workspace_state_discipline.md
-- <stage_inspection_dir>/<current_stage_id>/stage_inspection.json
-- <stage_inspection_dir>/<current_stage_id>/stage_inspection.md
-- <intermediate_asset_dir>/intermediate_asset_records.json
-- <intermediate_asset_dir>/intermediate_asset_records.md
+- workspace_state_discipline.json (machine discipline ledger: stage/artifact/path/freshness/rerun/blocker state)
+- workspace_state_discipline.md (agent handoff: discipline tables, findings, next safe action)
+- <stage_inspection_dir>/<current_stage_id>/stage_inspection.json (machine stage gate: checked inputs/outputs, compliance, freshness, assets)
+- <stage_inspection_dir>/<current_stage_id>/stage_inspection.md (agent stage inspection handoff)
+- <intermediate_asset_dir>/intermediate_asset_records.json (machine asset ledger for consumed adapter/downstream artifacts)
+- <intermediate_asset_dir>/intermediate_asset_records.md (agent asset handoff with coverage gaps)
 
 RETURN TO CONTROLLER (shared shape, no preamble):
 { "status": "passed | needs_rerun | blocked", "node": "workspace-state-discipline-inspector",

package/skills/migration-task-adapter/workflow.md

@@ -55,15 +55,15 @@ Required durable artifacts:
 
 | Schedule point | Required artifacts |
 |---|---|
-| Output root lock | `<output_root>/run_manifest.json` |
-| Task understanding | `<task_dir>/task_understanding_router.json`, `<task_dir>/task_understanding_router.md` |
-| Workspace discipline | `<workspace_state_dir>/workspace_state_discipline.json`, `<workspace_state_dir>/workspace_state_discipline.md` |
-| Stage inspection | `<stage_inspection_dir>/<stage_id>/stage_inspection.json`, `<stage_inspection_dir>/<stage_id>/stage_inspection.md` |
-| Intermediate assets | `<intermediate_asset_dir>/intermediate_asset_records.json`, `<intermediate_asset_dir>/intermediate_asset_records.md` |
-| Orchestration | `<orchestration_dir>/workflow_orchestration.json`, `<orchestration_dir>/workflow_orchestration.md` |
-| Final report | `<report_dir>/task_adapter_report.json`, `<report_dir>/task_adapter_report.md` |
+| Output root lock | `<output_root>/run_manifest.json` - task id, raw task, paths/scope, output roots, dependency status, schedule version |
+| Task understanding | `<task_dir>/task_understanding_router.json`, `<task_dir>/task_understanding_router.md` - route decision, focus, evidence, required/missing inputs, downstream sequence |
+| Workspace discipline | `<workspace_state_dir>/workspace_state_discipline.json`, `<workspace_state_dir>/workspace_state_discipline.md` - artifact inventory, path/freshness checks, rerun/blocker history, next actions |
+| Stage inspection | `<stage_inspection_dir>/<stage_id>/stage_inspection.json`, `<stage_inspection_dir>/<stage_id>/stage_inspection.md` - checked inputs/outputs, path/freshness/asset coverage, rerun/blocker routing |
+| Intermediate assets | `<intermediate_asset_dir>/intermediate_asset_records.json`, `<intermediate_asset_dir>/intermediate_asset_records.md` - stable records for every adapter/downstream artifact consumed later |
+| Orchestration | `<orchestration_dir>/workflow_orchestration.json`, `<orchestration_dir>/workflow_orchestration.md` - downstream contracts, expected/observed outputs, stage requests, rerun/blocker routing |
+| Final report | `<report_dir>/task_adapter_report.json`, `<report_dir>/task_adapter_report.md` - final route/status/readiness, verified outputs, stage/asset summaries, blockers |
 
-No adapter role may write inside downstream workflow output roots except by invoking the downstream controller with its own declared `output_dir`. Downstream artifacts are referenced by path in intermediate asset records.
+No adapter role may write inside downstream workflow output roots except by invoking the downstream controller with its own declared `output_dir`. Downstream artifacts are referenced by path in intermediate asset records. The validator output root must be the downstream validator's parallel `validation` location, not the migration output root.
 
 ## Route Matrix
 
@@ -82,7 +82,7 @@ No adapter role may write inside downstream workflow output roots except by invo
 
 - **Executor**: Leader.
 - **Input**: [dependencies.yaml](dependencies.yaml), user task, optional source/target/output paths.
-- **Action**: verify optional tools and lock `output_root`. Write `run_manifest.json` with task id, timestamp, requested scope, allowed roots, downstream workflow candidates, and schedule version.
+- **Action**: verify optional tools and lock `output_root`. Write `run_manifest.json` with task id, raw task summary, timestamp, requested scope, source/target paths, allowed roots, downstream workflow candidates, dependency status, and schedule version.
 - **Gate**: `run_manifest.json` exists and is non-empty before any role runs.
 
 ### Step 1 - Task Understanding And Router
@@ -90,14 +90,14 @@ No adapter role may write inside downstream workflow output roots except by invo
 - **Executor**: `task-understanding-router`.
 - **Input**: raw user task, paths, current workspace hints, optional existing analyst/migrator/validator artifact paths.
 - **Action**: normalize request, classify route, select focus, identify missing evidence, create downstream route contract.
-- **Output**: `task_understanding_router.json`, `task_understanding_router.md`.
+- **Output**: `task_understanding_router.json`, `task_understanding_router.md`. Artifacts must contain normalized task summary, route, task kind, focus, source/target/scope fields, existing artifact evidence, required/missing inputs, downstream workflow sequence, stage inspection requirements, intermediate asset requirements, and blockers.
 - **Gate**: route must be one of the route matrix values or `blocked` with missing inputs. No downstream workflow starts on `unknown`.
 
 ### Step 2 - Workspace State Discipline Init
 
 - **Executor**: `workspace-state-discipline-inspector`.
 - **Action**: initialize or refresh workspace discipline ledger, stage inspection index, intermediate asset records, rerun/blocker history.
-- **Output**: `workspace_state_discipline.*`, first `stage_inspection.*`, and `intermediate_asset_records.*`.
+- **Output**: `workspace_state_discipline.json`, `.md`, first `stage_inspection.json`, `.md`, and `intermediate_asset_records.json`, `.md`. Artifacts must record adapter artifact inventory, path compliance, freshness, consumed assets, rerun history, blockers, and next safe action.
 - **Gate**: task understanding artifacts and run manifest are recorded as intermediate assets before orchestration.
 
 ### Step 3 - Workflow Orchestration
@@ -108,7 +108,7 @@ No adapter role may write inside downstream workflow output roots except by invo
   - Record downstream output roots and expected artifacts.
   - After downstream workflow completion, record observed outputs, statuses, blockers, and required reruns.
   - Route stale or missing downstream outputs back to the owning workflow.
-- **Output**: `workflow_orchestration.json`, `workflow_orchestration.md`.
+- **Output**: `workflow_orchestration.json`, `workflow_orchestration.md`. Artifacts must contain downstream dispatch contracts, expected output roots/artifacts, observed downstream outputs, stage inspection requests, intermediate asset updates, rerun requests, and blockers.
 - **Gate**: orchestration cannot claim `completed` until downstream workflow status and required artifact paths are recorded or blockers are explicit.
 
 ### Step 4 - Stage Inspections
@@ -123,13 +123,13 @@ No adapter role may write inside downstream workflow output roots except by invo
   - `pre_report`
   - `post_report`
 - **Action**: for each applicable point, verify current stage inputs, outputs, freshness, path compliance, intermediate asset coverage, and rerun/blocker routing.
-- **Output**: one `stage_inspection.json` and `.md` per stage id plus refreshed workspace discipline and asset ledgers.
+- **Output**: one `stage_inspection.json` and `.md` per stage id plus refreshed workspace discipline and asset ledgers. Stage inspection artifacts must list checked inputs/outputs, path compliance, freshness checks, intermediate asset coverage, downstream contract checks, rerun requests, blockers, and next allowed stage.
 - **Gate**: final report cannot run unless `pre_report` stage inspection passes or explicitly reports `blocked`.
 
 ### Step 5 - Intermediate Asset Records
 
 - **Executor**: `workspace-state-discipline-inspector` with updates from `workflow-orchestrator`.
-- **Action**: record every durable artifact consumed across stages.
+- **Action**: record every durable adapter and downstream artifact consumed across stages.
 - **Required fields**:
   - `asset_id`
   - `asset_type`
@@ -148,7 +148,7 @@ No adapter role may write inside downstream workflow output roots except by invo
 - **Executor**: `task-reporter`.
 - **Input**: run manifest, task understanding, workflow orchestration, latest workspace discipline, stage inspections, intermediate asset records, downstream reports.
 - **Action**: synthesize a final machine-routable task report. Do not run new analysis, migration, validation, tests, or fixes.
-- **Output**: `task_adapter_report.json`, `task_adapter_report.md`.
+- **Output**: `task_adapter_report.json`, `task_adapter_report.md`. Artifacts must summarize final status, route, focus, source/target paths, downstream workflow results, stage inspections, intermediate assets, verified outputs, readiness, rerun requests, blockers, and report path.
 - **Gate**: report status is `completed`, `ready_for_validation`, `failed`, or `blocked` only from verified evidence.
 
 ## Final Report Shape