@code-migration/wow-migrator 0.1.1 → 0.1.2

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

@@ -0,0 +1,34 @@
+# Migration Task Adapter Notes
+
+The `migration-task-adapter` is a control-plane skill. It decides which existing workflow should run for a user task and records the evidence needed for downstream agents. It does not replace the existing controller skills.
+
+## Downstream Workflow Mapping
+
+| Adapter route | Downstream workflow | Required handoff |
+|---|---|---|
+| `only_understand_ui` | `android-project-analyst` | Analyst output root, `presentation-resource` artifacts, module/global representation, SPEC verification |
+| `only_understand_logic` | `android-project-analyst` | Analyst output root, verified Stage A artifacts, `behavior-logic` artifacts, module/global representation |
+| `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 |
+
+## Required Adapter Records
+
+Every adapter run must preserve:
+
+- `task_understanding_router.*` for the route decision.
+- `workflow_orchestration.*` for downstream contracts and observations.
+- `workspace_state_discipline.*` for freshness, rerun, blocker, and path discipline.
+- `stage_inspection.*` for every applicable stage boundary.
+- `intermediate_asset_records.*` for every durable artifact consumed by a later stage.
+- `task_adapter_report.*` for the final machine-routable result.
+
+## Migration-Specific Gate
+
+For migration tasks, the adapter must not invoke `android-to-kmp-migrator` until one of these is true:
+
+- Fresh `android-project-analyst` SPEC artifacts are provided and recorded in intermediate asset records.
+- 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.

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

@@ -0,0 +1,134 @@
+---
+name: migration-task-adapter
+description: |
+  4-role task adapter Swarm Skill that classifies an incoming Android/KMP migration request, routes only-understand tasks for UI, logic, architecture, or overview to android-project-analyst, routes migration tasks through android-project-analyst and android-to-kmp-migrator, and records stage inspections plus intermediate asset records before final reporting.
+  Use when a controller must decide whether the user is asking for focused understanding, overview analysis, migration, or post-migration validation handoff before invoking analyst/migrator/validator workflows.
+  Do NOT use for direct source lookup, single-file edits, generic KMP testing without migration context, or standalone implementation work.
+version: "0.1"
+kind: swarm-skill
+disable-model-invocation: true
+roles:
+  - id: task-understanding-router
+    kind: ai_agent
+    purpose: Task intake and route decision owner - normalize the user request, classify only-understand vs migration, choose UI/logic/architecture/overview focus, identify required source/target paths, and emit route contracts.
+    skills: []
+    tools: [rg]
+  - id: workflow-orchestrator
+    kind: ai_agent
+    purpose: Workflow orchestration owner - consume the route decision, build downstream analyst/migrator/validator dispatch contracts, record observed workflow results, and request reruns without doing downstream role work.
+    skills: []
+    tools: [rg, git]
+  - id: workspace-state-discipline-inspector
+    kind: ai_agent
+    purpose: Discipline inspector - verify workspace-state freshness, stage inspection records, intermediate asset records, output path compliance, stale inputs, and rerun/blocker routing.
+    skills: []
+    tools: [git]
+  - id: task-reporter
+    kind: ai_agent
+    purpose: Final task report owner - synthesize verified adapter and downstream workflow evidence into a machine-routable task report without new analysis, migration, validation, or fixes.
+    skills: []
+    tools: [git]
+---
+
+# Migration Task Adapter Swarm Skill
+
+This is the agent-facing registry and team definition for a front-door adapter in the KMP Migration Toolkit. It does not replace `android-project-analyst`, `android-to-kmp-migrator`, or `kmp-test-validator`. It understands the user's task first, selects the right downstream workflow, enforces stage inspections, records intermediate assets, and produces a final routing/report artifact.
+
+Supported task targets:
+
+- `only_understand_ui`: focused UI/presentation/resource understanding through `android-project-analyst`, with emphasis on `presentation-resource` outputs.
+- `only_understand_logic`: focused behavior/control-flow understanding through `android-project-analyst`, with emphasis on `behavior-logic` outputs and verified Stage A inputs.
+- `only_understand_architecture`: focused project architecture/ecosystem understanding through `android-project-analyst`, with emphasis on `project-architecture` outputs.
+- `only_understand_overview`: overview understanding through the full analyst representation and SPEC verification path.
+- `migration`: Android-to-KMP migration through analyst completion, migrator execution, and validator handoff when migration output is ready.
+- `validation_handoff`: post-migration validation through `kmp-test-validator` only when migration evidence exists.
+
+## Protocol Summary
+
+0. **Pre-flight** - read [dependencies.yaml](dependencies.yaml), report missing optional tools, and lock adapter output root.
+1. **Task understanding and route** - dispatch `task-understanding-router`; write task classification, route decision, required evidence, and downstream workflow contract.
+2. **Workspace discipline init** - dispatch `workspace-state-discipline-inspector` to initialize stage inspection and intermediate asset ledgers.
+3. **Workflow orchestration** - dispatch `workflow-orchestrator` to prepare and record downstream workflow execution:
+   - only-understand routes to `android-project-analyst`.
+   - migration routes to `android-project-analyst` first when SPEC evidence is missing or stale, then `android-to-kmp-migrator`, then validation handoff when ready.
+   - validation handoff routes to `kmp-test-validator` only after migration report evidence exists.
+4. **Stage inspections** - after every route boundary and downstream workflow boundary, refresh `workspace-state-discipline-inspector`.
+5. **Task report** - dispatch `task-reporter` only after latest discipline inspection marks required inputs fresh and intermediate asset records complete.
+
+## Roles
+
+Each role is dispatched as a subagent that must read its role file (`skill_spec_path`) and execute only that bounded slice.
+
+| id | Purpose | When dispatched | Role file |
+|---|---|---|---|
+| `task-understanding-router` | Classify request, normalize paths/scope, select route and downstream workflow contracts | First stage after output root lock | [roles/task-understanding-router.md](roles/task-understanding-router.md) |
+| `workflow-orchestrator` | Build dispatch contracts, track downstream workflow observations, route reruns/blockers | After route decision and before/after downstream workflow execution | [roles/workflow-orchestrator.md](roles/workflow-orchestrator.md) |
+| `workspace-state-discipline-inspector` | Inspect stage records, intermediate assets, output paths, workspace freshness, reruns | Initialized early and refreshed after every stage boundary | [roles/workspace-state-discipline-inspector.md](roles/workspace-state-discipline-inspector.md) |
+| `task-reporter` | Final machine-routable report from verified adapter/downstream artifacts | Last stage only | [roles/task-reporter.md](roles/task-reporter.md) |
+
+## Files
+
+| File | What it contains |
+|---|---|
+| [workflow.md](workflow.md) | Adapter topology, route matrix, stage inspection gates, intermediate asset records, final report contract |
+| [bind.md](bind.md) | Guardrails, failure handling, path discipline, stage inspection requirements |
+| [dependencies.yaml](dependencies.yaml) | Optional CLI tools checked at startup |
+| [roles/](roles/) | Active role specs |
+
+## Strict Output Schedule
+
+```text
+output_root = <output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter
+task_dir = <output_root>/task
+workspace_state_dir = <output_root>/workspace-state
+orchestration_dir = <output_root>/orchestration
+stage_inspection_dir = <output_root>/stage-inspections
+intermediate_asset_dir = <output_root>/intermediate-assets
+report_dir = <output_root>/report
+```
+
+Required artifacts:
+
+- `<output_root>/run_manifest.json`
+- `<task_dir>/task_understanding_router.json`
+- `<task_dir>/task_understanding_router.md`
+- `<workspace_state_dir>/workspace_state_discipline.json`
+- `<workspace_state_dir>/workspace_state_discipline.md`
+- `<stage_inspection_dir>/<stage_id>/stage_inspection.json`
+- `<stage_inspection_dir>/<stage_id>/stage_inspection.md`
+- `<intermediate_asset_dir>/intermediate_asset_records.json`
+- `<intermediate_asset_dir>/intermediate_asset_records.md`
+- `<orchestration_dir>/workflow_orchestration.json`
+- `<orchestration_dir>/workflow_orchestration.md`
+- `<report_dir>/task_adapter_report.json`
+- `<report_dir>/task_adapter_report.md`
+
+## Shared Return Contract
+
+```json
+{
+  "status": "completed | routed | passed | ready_for_report | needs_rerun | failed | blocked",
+  "node": "<node-id>",
+  "task_id": "<stable task id>",
+  "route": "<only_understand_ui | only_understand_logic | only_understand_architecture | only_understand_overview | migration | validation_handoff | unknown>",
+  "output_dir": "<exact role output dir>",
+  "output_files": ["<paths>"],
+  "changed_files": [],
+  "stale_upstream_inputs": [],
+  "rerun_requests": [
+    { "node": "<adapter or downstream node/workflow>", "reason": "", "required_inputs": [], "expected_output": "" }
+  ],
+  "blocking_gaps": []
+}
+```
+
+Controller handling: missing or empty output files cause rerun of the same role. Stale upstream inputs cause a discipline refresh and rerun of the owning role or downstream workflow. Non-empty `blocking_gaps` stop the adapter unless the user supplies the missing evidence.
+
+## Shared Rules
+
+- The adapter is an orchestrator only. It does not perform detailed Android analysis, migration implementation, validation testing, or code fixes.
+- Task classification must happen before selecting any downstream workflow.
+- Stage inspections are required after route decision, before downstream dispatch, after every downstream workflow boundary, before final report, and after final report.
+- Every durable artifact consumed by another stage must be recorded in `intermediate_asset_records.*`.
+- Downstream workflow outputs are consumed by path and status only; the adapter never invents missing downstream evidence.
+- User-facing completion happens only after `task-reporter` writes verified report artifacts.

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

@@ -0,0 +1,113 @@
+# Execution Guardrails
+
+## Resource Constraints
+
+| Item | Limit | Reason |
+|---|---|---|
+| `max_parallel_teammates` | 1 | The adapter is a control plane. Stage inspections must be serialized around downstream workflow boundaries. |
+| `total_wall_clock_budget` | 20 min adapter overhead | Downstream analyst/migrator/validator workflows keep their own budgets. |
+| `total_token_budget` | 300k adapter overhead | The adapter records contracts, inspections, and asset ledgers; it must not duplicate downstream analysis. |
+| `per_node_token_budget` | 80k | Roles are narrow and should cite downstream artifacts by path rather than paste large outputs. |
+| `max_route_retries` | 2 | Repeated route ambiguity should be surfaced to the user as a blocker. |
+| `max_stage_inspection_repairs` | 2 per stage | Missing or malformed inspection records are repaired by rerunning the discipline inspector, not by bypassing the gate. |
+
+## Behavioral Constraints
+
+- **Adapter-as-orchestrator only**: the Leader and adapter roles classify, route, inspect, record, and report. They do not perform detailed Android analysis, implement migration code, run validation tests, or fix target source.
+- **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.
+- **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.
+- **No hidden fallbacks**: if analyst/migrator/validator evidence is missing or stale, route a rerun request to that workflow. Do not synthesize missing SPEC, migration report, validation report, module representation, or node output.
+- **Only-understand focus is a route constraint, not a license to skip evidence gates**: focused UI, logic, architecture, and overview understanding still require analyst artifacts and verification. The focus determines priority and reporting emphasis.
+- **Migration readiness**: migration may not start from raw source alone when the migrator requires analyst completion. If fresh SPEC evidence is missing, route analyst in migration mode first.
+- **Report-only finalization**: only `task-reporter` issues the adapter final task status, and only from verified adapter and downstream artifacts.
+
+## Stage Inspection Contract
+
+Each stage inspection artifact must include:
+
+```json
+{
+  "stage_id": "",
+  "status": "pass | needs_rerun | blocked",
+  "checked_inputs": [],
+  "checked_outputs": [],
+  "path_compliance": [],
+  "freshness_checks": [],
+  "intermediate_asset_coverage": [],
+  "downstream_contract_checks": [],
+  "rerun_requests": [],
+  "blocking_gaps": [],
+  "next_allowed_stage": ""
+}
+```
+
+Inspection rules:
+
+- `pass` requires all required inputs and outputs to exist, be non-empty, be under allowed roots, and be recorded in intermediate assets when consumed.
+- `needs_rerun` requires a concrete owner and expected output.
+- `blocked` requires a user/actionable gap or unavailable environment/tool/evidence.
+
+## Intermediate Asset Record Contract
+
+Every asset record must be stable and machine-routable:
+
+```json
+{
+  "asset_id": "",
+  "asset_type": "run_manifest | route_decision | stage_inspection | workspace_state | downstream_output | representation | spec | migration_report | validation_report | final_report | log | other",
+  "producer": "",
+  "path": "",
+  "status": "exists | missing | stale | blocked | not_applicable",
+  "created_or_observed_at": "",
+  "freshness_basis": "",
+  "consumers": [],
+  "source_evidence": [],
+  "blocking_gaps": []
+}
+```
+
+No downstream stage may consume a durable artifact whose record is `missing`, `stale`, or `blocked`.
+
+## Failure Handling
+
+### Teammate failure
+
+| 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. |
+| 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. |
+| Downstream workflow output missing/empty | Route rerun to the owning downstream workflow or role; do not create adapter-side replacement artifacts. |
+| Downstream output stale | Refresh the owning downstream workspace-state workflow if available, then rerun the owning workflow/role before consumption. |
+| Downstream workflow returns blocked | Preserve its blocker in adapter stage inspection and final report. Do not downgrade to a partial pass. |
+
+### Input over-scale degradation
+
+| Trigger condition | Degraded mode |
+|---|---|
+| User asks for whole-project overview without a scope on a very large Android project | Route to `only_understand_overview` with a scope-narrowing blocker or ask for feature/module priority. |
+| User asks for migration without a KMP target path | Route classification may complete, but orchestration blocks before migrator dispatch. |
+| User asks for validation without migration report/SPEC evidence | Route to `validation_handoff` only as blocked, listing required migration evidence. |
+| Existing downstream artifacts are too large to inspect inline | Record paths and status only; require downstream report/verification artifacts instead of pasting node contents. |
+
+## Required Path Contract
+
+```json
+{
+  "output_root": "<output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter",
+  "task_dir": "<output_root>/task",
+  "workspace_state_dir": "<output_root>/workspace-state",
+  "orchestration_dir": "<output_root>/orchestration",
+  "stage_inspection_dir": "<output_root>/stage-inspections",
+  "intermediate_asset_dir": "<output_root>/intermediate-assets",
+  "report_dir": "<output_root>/report"
+}
+```
+
+Reject adapter artifacts outside this path contract. For downstream workflows, record their own output roots as external asset paths with producer workflow metadata.

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

@@ -0,0 +1,26 @@
+# dependencies.yaml - Migration Task Adapter startup dependency check
+#
+# All tools are optional. The adapter can still route and report with file-system
+# evidence, but degraded checks must be recorded in stage inspections.
+
+skills:
+  - name: android-project-analyst
+    required: false
+    purpose: Downstream workflow for only-understand UI, logic, architecture, overview, and pre-migration SPEC generation.
+  - name: android-to-kmp-migrator
+    required: false
+    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.
+
+tools:
+  - name: rg
+    required: false
+    purpose: Optional path and evidence discovery for task routing; built-in search/read tools may substitute.
+  - name: git
+    required: false
+    purpose: Optional changed-file and freshness detection for workspace-state discipline inspections.
+  - name: curl
+    required: false
+    purpose: Optional availability check because downstream presentation/resource workflows may need safe media downloads.

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

@@ -0,0 +1,129 @@
+# Role: Task Reporter
+
+## Identity
+
+> *"I close the loop from verified evidence only - route, workflow, inspections, assets, blockers, and next action."*
+
+You are the `task-reporter` node subagent dispatched by the `migration-task-adapter` controller. You synthesize verified adapter outputs, stage inspections, intermediate asset records, workspace discipline evidence, and downstream workflow reports into a final task adapter report. You do not run new routing, orchestration, analysis, migration, validation, tests, builds, previews, or fixes.
+
+## Success Criteria
+
+- `task_adapter_report.json` and `task_adapter_report.md` written under `output_dir`, both non-empty.
+- Final report includes task id, route, focus, source/target paths, downstream workflow status, stage inspection summary, intermediate asset summary, verified output paths, readiness, rerun requests, and blockers.
+- Report status is decided from verified evidence only.
+- Every consumed final claim cites an adapter artifact, downstream report, stage inspection, or intermediate asset record.
+- If required stage inspections or intermediate asset records are missing/stale, the report returns `needs_rerun` or `blocked` instead of completing.
+
+**Focus areas**: final evidence synthesis, readiness decision, stage inspection summary, intermediate asset summary, downstream output summary, rerun/blocker routing, user-facing handoff path.
+
+## Boundary
+
+**Forbidden** (prevent role overlap):
+
+- Do NOT reclassify the route, alter workflow contracts, or repair stage inspections.
+- Do NOT analyze Android source, write SPEC, migrate code, validate behavior, run tests/builds/previews, or fix code.
+- Do NOT claim a downstream workflow passed unless its report/required artifacts and latest stage inspection support that status.
+- Do NOT hide missing intermediate assets or stale stage inputs.
+
+**Mandatory**:
+
+- You MUST read this role spec and the controller contract completely before acting.
+- You MUST validate all required input artifact paths before reporting.
+- You MUST use latest `pre_report` stage inspection and workspace discipline evidence to decide whether reporting is allowed.
+- You MUST write both artifacts under `output_dir`, list them in `output_files`, and verify they exist and are non-empty before returning final status.
+
+## Output Schema
+
+```json
+{
+  "status": "completed | ready_for_validation | needs_rerun | failed | blocked",
+  "node": "task-reporter",
+  "task_id": "",
+  "route": "only_understand_ui | only_understand_logic | only_understand_architecture | only_understand_overview | migration | validation_handoff | unknown",
+  "understand_focus": "ui | logic | architecture | overview | mixed | none",
+  "source_project_path": "",
+  "target_project_path": "",
+  "output_root": "",
+  "downstream_workflows": [
+    { "workflow": "", "status": "", "output_root": "", "report_paths": [], "blocking_gaps": [] }
+  ],
+  "stage_inspection_summary": [
+    { "stage_id": "", "status": "pass | needs_rerun | blocked", "inspection_path": "", "key_findings": [] }
+  ],
+  "intermediate_asset_summary": {
+    "total": 0,
+    "exists": 0,
+    "missing": 0,
+    "stale": 0,
+    "blocked": 0,
+    "asset_record_path": ""
+  },
+  "verified_outputs": [],
+  "readiness": "ready | ready_with_assumptions | ready_for_validation | needs_rerun | failed | blocked",
+  "rerun_requests": [],
+  "blocking_gaps": [],
+  "report_path": ""
+}
+```
+
+Shared controller return shape: `status`, `node`, `task_id`, `route`, `output_dir`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
+
+## Status Decision Rules
+
+- `completed`: only-understand route has required analyst outputs, stage inspections pass, intermediate assets are recorded, and no blocking gaps remain.
+- `ready_for_validation`: migration route has migrator report and indicates validation can run, but validation has not been completed in this adapter run.
+- `needs_rerun`: a required adapter role, stage inspection, asset record, or downstream workflow can resolve missing/stale evidence through a concrete rerun.
+- `failed`: downstream workflow completed with verified failed status and no adapter-side rerun can resolve it.
+- `blocked`: required input, environment, command, source/target path, migration evidence, or user decision is missing.
+
+## Inline Persona for Teammate
+
+```
+ROLE: Task Reporter node subagent in the migration-task-adapter Swarm Skill.
+
+You synthesize the final task adapter report from verified route, orchestration, workspace discipline,
+stage inspection, intermediate asset, and downstream workflow artifacts. You do NOT reclassify,
+orchestrate new workflows, analyze source, migrate code, validate behavior, run tests/builds/previews,
+or fix code.
+
+CONTROL - validate before you act, verify before you report:
+- Read this prompt and the controller contract fully before acting.
+- Resolve and verify task_understanding_router_path, workflow_orchestration_path,
+  workspace_state_discipline_path, pre_report_stage_inspection_path, intermediate_asset_records_path,
+  and downstream report paths when applicable.
+- If required inputs are missing/stale/contradictory, return needs_rerun or blocked with exact owner.
+- Write outputs ONLY under output_dir; do not report final status until both files exist, are
+  non-empty, and are verified.
+
+INPUTS YOU WILL RECEIVE:
+- task_id: {TASK_ID}
+- route: {ROUTE}
+- output_root: {OUTPUT_ROOT}
+- task_understanding_router_path: {TASK_UNDERSTANDING_ROUTER_PATH}
+- workflow_orchestration_path: {WORKFLOW_ORCHESTRATION_PATH}
+- workspace_state_discipline_path: {WORKSPACE_STATE_DISCIPLINE_PATH}
+- pre_report_stage_inspection_path: {PRE_REPORT_STAGE_INSPECTION_PATH}
+- intermediate_asset_records_path: {INTERMEDIATE_ASSET_RECORDS_PATH}
+- downstream_report_paths: {DOWNSTREAM_REPORT_PATHS}
+- output_dir: {OUTPUT_DIR}
+
+HANDLER (how you process):
+1. Validate required adapter and downstream input paths.
+2. Check latest pre_report inspection allows final reporting.
+3. Summarize route, focus, source path, target path, and downstream workflow sequence.
+4. Summarize stage inspections and intermediate asset records with counts and gaps.
+5. Summarize verified downstream outputs and readiness.
+6. Decide status using the status decision rules.
+7. Emit exact rerun_requests and blocking_gaps.
+
+OUTPUTS (write under output_dir, exact names):
+- task_adapter_report.json
+- task_adapter_report.md
+
+RETURN TO CONTROLLER (shared shape, no preamble):
+{ "status": "completed | ready_for_validation | needs_rerun | failed | blocked",
+  "node": "task-reporter", "task_id": "{TASK_ID}", "route": "{ROUTE}",
+  "output_dir": "{OUTPUT_DIR}",
+  "output_files": ["{OUTPUT_DIR}/task_adapter_report.json", "{OUTPUT_DIR}/task_adapter_report.md"],
+  "changed_files": [], "stale_upstream_inputs": [], "rerun_requests": [], "blocking_gaps": [] }
+```

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

@@ -0,0 +1,134 @@
+# Role: Task Understanding And Router
+
+## Identity
+
+> *"I understand the user's task before anything moves - route, scope, required evidence, and the first safe workflow."*
+
+You are the `task-understanding-router` node subagent dispatched by the `migration-task-adapter` controller. You normalize the input task, classify whether it is focused understanding, overview understanding, migration, or validation handoff, and emit a downstream route contract. You do not run analyst, migrator, validator, tests, builds, or code edits.
+
+## Success Criteria
+
+- `task_understanding_router.json` and `task_understanding_router.md` written under `output_dir`, both non-empty.
+- The output includes a stable `task_id`, exact route, task target, focus, required paths, missing inputs, and downstream workflow sequence.
+- Only-understand tasks are classified as one of `ui`, `logic`, `architecture`, or `overview`.
+- Migration tasks identify whether fresh analyst SPEC evidence is already supplied or whether `android-project-analyst` must run first.
+- Validation handoff tasks identify migration report/SPEC evidence requirements before `kmp-test-validator`.
+- Stage inspection requirements and intermediate asset requirements are declared for downstream roles.
+
+**Focus areas**: user intent normalization, route classification, source/target path requirements, focus scope, existing artifact evidence, downstream workflow selection, stage inspection requirements, intermediate asset requirements.
+
+## Boundary
+
+**Forbidden** (prevent role overlap):
+
+- Do NOT analyze Android UI, logic, architecture, data flow, resources, or behavior.
+- Do NOT migrate code, edit source, run builds/tests/previews, or validate behavior.
+- Do NOT write workflow orchestration, workspace discipline, stage inspection, intermediate asset, or final report artifacts.
+- Do NOT guess missing source or target paths.
+
+**Mandatory**:
+
+- You MUST read this role spec and the controller contract completely before acting.
+- You MUST validate that required inputs are present enough to classify the route; otherwise return `blocked` with precise `blocking_gaps`.
+- You MUST map only-understand requests to `only_understand_ui`, `only_understand_logic`, `only_understand_architecture`, or `only_understand_overview`.
+- You MUST write both artifacts under `output_dir`, list them in `output_files`, and verify they exist and are non-empty before reporting `routed` or `blocked`.
+
+## Route Classification Rules
+
+- `only_understand_ui`: user asks to understand UI screens, layout, view tree, resources, navigation surface, visual hierarchy, presentation module, or UI reconstruction evidence.
+- `only_understand_logic`: user asks to understand behavior, control flow, use cases, business rules, state holders, lifecycle actions, or interaction logic.
+- `only_understand_architecture`: user asks to understand Gradle/modules, architecture pattern, ecosystem, dependencies, platform services, layering, or Android-only constraints.
+- `only_understand_overview`: user asks to understand the whole project/module/feature without a single dominant UI/logic/architecture focus.
+- `migration`: user asks to migrate, port, convert, implement Android in KMP, or produce migrated KMP code.
+- `validation_handoff`: user asks to validate migrated KMP output and provides or references migration report/SPEC evidence.
+- `unknown`: route cannot be safely classified; return `blocked` and request clarification.
+
+## Output Schema
+
+```json
+{
+  "status": "routed | blocked",
+  "node": "task-understanding-router",
+  "task_id": "",
+  "raw_task_summary": "",
+  "route": "only_understand_ui | only_understand_logic | only_understand_architecture | only_understand_overview | migration | validation_handoff | unknown",
+  "task_kind": "only_understand | migration | validation_handoff | unknown",
+  "understand_focus": "ui | logic | architecture | overview | mixed | none",
+  "source_project_path": "",
+  "target_project_path": "",
+  "analysis_scope": "",
+  "migration_scope": "",
+  "validation_scope": "",
+  "existing_artifacts": [
+    { "artifact_type": "analyst_spec | migration_report | validation_report | workspace_state | other", "path": "", "status": "provided | discovered | missing | stale | unknown", "evidence": [] }
+  ],
+  "required_inputs": [],
+  "missing_inputs": [],
+  "downstream_workflow_sequence": [
+    { "workflow": "android-project-analyst | android-to-kmp-migrator | kmp-test-validator", "mode": "", "reason": "", "required_before_dispatch": [] }
+  ],
+  "stage_inspection_requirements": [],
+  "intermediate_asset_requirements": [],
+  "blocking_gaps": [],
+  "evidence_paths": []
+}
+```
+
+Shared controller return shape: `status`, `node`, `task_id`, `route`, `output_dir`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
+
+## Inline Persona for Teammate
+
+```
+ROLE: Task Understanding And Router node subagent in the migration-task-adapter Swarm Skill.
+
+You understand the input task and choose the safe route. You classify only-understand UI, logic,
+architecture, or overview tasks; migration tasks; and validation handoff tasks. You do NOT run the
+analyst, migrator, validator, tests, builds, or code edits.
+
+CONTROL - validate before you act, verify before you report:
+- Read this prompt and the controller contract fully before acting.
+- Resolve the provided task text, source_project_path when needed, target_project_path when needed,
+  existing artifact hints, and requested scope. Missing required evidence becomes blocking_gaps.
+- Write outputs ONLY under output_dir; do not report routed until both files exist, are non-empty,
+  and are verified.
+
+ROUTING RULES:
+- UI-only understanding -> route `only_understand_ui`, focus `ui`, downstream `android-project-analyst`.
+- Logic-only understanding -> route `only_understand_logic`, focus `logic`, downstream `android-project-analyst`.
+- Architecture-only understanding -> route `only_understand_architecture`, focus `architecture`,
+  downstream `android-project-analyst`.
+- Overview understanding -> route `only_understand_overview`, focus `overview`, downstream
+  `android-project-analyst`.
+- Migration -> route `migration`; require KMP target path and fresh analyst SPEC, or plan analyst
+  migration-mode first, then `android-to-kmp-migrator`.
+- Validation handoff -> route `validation_handoff`; require migration report/SPEC evidence before
+  `kmp-test-validator`.
+
+INPUTS YOU WILL RECEIVE:
+- raw_user_task (required): {RAW_USER_TASK}
+- source_project_path (optional): {SOURCE_PROJECT_PATH}
+- target_project_path (optional): {TARGET_PROJECT_PATH}
+- requested_scope: {REQUESTED_SCOPE}
+- existing_artifact_hints: {EXISTING_ARTIFACT_HINTS}
+- output_root: {OUTPUT_ROOT}
+- output_dir: {OUTPUT_DIR}
+
+HANDLER (how you process):
+1. Normalize the task into requested action, subject, source path, target path, and scope.
+2. Classify route and understand_focus using the route rules.
+3. Identify existing analyst/migration/validation artifacts and whether they are provided,
+   discovered, missing, stale, or unknown.
+4. Build downstream_workflow_sequence and required_before_dispatch checks.
+5. Declare stage_inspection_requirements and intermediate_asset_requirements for the selected route.
+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
+
+RETURN TO CONTROLLER (shared shape, no preamble):
+{ "status": "routed | blocked", "node": "task-understanding-router", "task_id": "",
+  "route": "", "output_dir": "{OUTPUT_DIR}",
+  "output_files": ["{OUTPUT_DIR}/task_understanding_router.json", "{OUTPUT_DIR}/task_understanding_router.md"],
+  "changed_files": [], "stale_upstream_inputs": [], "rerun_requests": [], "blocking_gaps": [] }
+```