@code-migration/wow-migrator 0.1.3 → 0.1.5

package/skills/migration-task-adapter/output-contract.md

@@ -0,0 +1,276 @@
+# Output Contract: Adapter File Recording, Downstream Roots, And Trigger Gates
+
+This document is the **canonical path and content contract** for `migration-task-adapter`. Downstream controllers and human/agent orchestrators **MUST treat missing, empty, out-of-path, stale, or schema-invalid adapter artifacts as hard blockers** — they do not infer route, stage, or readiness from chat summaries.
+
+The Leader and every node MUST read this file before writing artifacts. When `SKILL.md` or `workflow.md` diverge, **this file wins on paths, filenames, downstream root recording, and trigger gates**.
+
+## Downstream Output Roots (read-only consumption)
+
+The adapter records but does not write into downstream workflow roots:
+
+| Workflow | Default `output_root` |
+|---|---|
+| `android-project-analyst` | `<output_dir or ~/.a2c_agents/understand>/android-project-analyst` |
+| `android-to-kmp-migrator` | `<output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator` |
+| `kmp-test-validator` | `<output_dir or ~/.a2c_agents/validation>/kmp-test-validator` |
+
+Validator artifacts MUST stay under the parallel `validation` root — never under the migration root.
+
+**Fail closed**: adapter roles MUST NOT claim downstream pass without durable report artifacts and matching stage inspection support.
+
+---
+
+## Adapter Output Root Layout
+
+Lock one `output_root` before any dispatch:
+
+```text
+output_root = <output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter
+
+<output_root>/
+├── run_manifest.json
+├── downstream-index/
+│   ├── downstream_workflow_index.json
+│   └── downstream_workflow_index.md
+├── workspace-state/
+│   ├── adapter_workspace_state.json
+│   └── adapter_workspace_state.md
+├── route-orchestration/
+│   ├── route/
+│   │   ├── task_route.json
+│   │   └── task_route.md
+│   └── orchestrate/
+│       ├── workflow_orchestration.json
+│       └── workflow_orchestration.md
+├── stage-inspections/
+│   └── <stage_id>/
+│       ├── stage_inspection.json
+│       └── stage_inspection.md
+├── intermediate-assets/
+│   ├── intermediate_asset_records.json
+│   └── intermediate_asset_records.md
+└── report/
+    ├── adapter_report.json
+    └── adapter_report.md
+```
+
+### Path Variables (stable across runs)
+
+| Variable | Resolved path |
+|---|---|
+| `output_root` | `<output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter` |
+| `downstream_index_dir` | `<output_root>/downstream-index` |
+| `workspace_state_dir` | `<output_root>/workspace-state` |
+| `route_orchestration_dir` | `<output_root>/route-orchestration` |
+| `route_dir` | `<route_orchestration_dir>/route` |
+| `orchestrate_dir` | `<route_orchestration_dir>/orchestrate` |
+| `stage_inspection_dir` | `<output_root>/stage-inspections` |
+| `stage_dir` | `<stage_inspection_dir>/<stage_id>` |
+| `intermediate_asset_dir` | `<output_root>/intermediate-assets` |
+| `report_dir` | `<output_root>/report` |
+
+### Filename Invariants (downstream parsers depend on these)
+
+- JSON primary artifacts use **snake_case** basenames (`task_route.json`, `workflow_orchestration.json`, `adapter_workspace_state.json`).
+- Route/orchestration subfolders use fixed names: `route/`, `orchestrate/`.
+- Stage folders use **kebab-case** `stage_id` values listed below.
+- No adapter artifact outside `<output_root>/` is valid for gates below.
+
+### Stage IDs (folder names under `stage-inspections/`)
+
+| `stage_id` | When required |
+|---|---|
+| `route_decision` | After `task-route-orchestrator` mode `route` |
+| `pre_downstream_dispatch` | Before downstream workflow invoke |
+| `post_analyst` | After analyst workflow when route requires it |
+| `post_migrator` | After migrator workflow when route requires it |
+| `post_validator` | After validator workflow when route requires it |
+| `pre_report` | Before `adapter-report` |
+| `post_report` | After `adapter-report` |
+
+---
+
+## Write Order (Leader Schedule)
+
+Artifacts MUST be produced in this order. Skipping a layer invalidates downstream trigger gates.
+
+| Step | Gate id | Required artifacts before next step |
+|---|---|---|
+| 0 | `AG0` | `run_manifest.json` |
+| 1 | `AG1` | `route-orchestration/route/task_route.*` |
+| 2 | `AG2` | `workspace-state/adapter_workspace_state.*`, `stage-inspections/route_decision/*`, `intermediate-assets/intermediate_asset_records.*` |
+| 3 | `AG3` | `route-orchestration/orchestrate/workflow_orchestration.*`, `downstream-index/downstream_workflow_index.*` |
+| 4 | `AG4` | applicable `stage-inspections/<stage_id>/*` after each route/downstream boundary |
+| 5 | `AG5` | `stage-inspections/pre_report/*` with `status: pass` |
+| 6 | `AG6` | `report/adapter_report.*`, `stage-inspections/post_report/*` |
+
+---
+
+## Artifact Registry: Path, Owner, Content, Trigger Role
+
+### Run identity
+
+| Path | Owner | Required JSON / content keys | Downstream trigger role |
+|---|---|---|---|
+| `run_manifest.json` | Leader | `task_id`, `route`, `source_project_path`, `target_project_path`, `output_root`, `downstream_output_roots`, `dependency_preflight`, `handoff_package`, `timestamp` | **All adapter roles** — resolves roots and declares claimed gate package |
+
+`handoff_package` MUST list absolute paths to the gate entry artifacts the run claims ready (see Handoff Packages below).
+
+### Downstream index
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `downstream-index/downstream_workflow_index.json` | `task-route-orchestrator` mode `orchestrate` | `workflows[]` with `workflow_id`, `output_root`, `handoff_package`, `key_artifact_paths[]`, `status` | **adapter-workspace-state**, **adapter-report** — machine lookup for consumed downstream evidence |
+
+### Workspace ledger
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `workspace-state/adapter_workspace_state.json` | `adapter-workspace-state` | `stage_status`, `artifact_inventory`, `path_compliance`, `freshness_checks`, `stale_upstream_inputs`, `rerun_history`, `blocking_gaps`, `handoff_gates`, `next_actions` | **All adapter roles** — refuse consumption when required artifacts are stale or `handoff_gates.*.ready` is false |
+
+### Route and orchestration
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `route-orchestration/route/task_route.json` | `task-route-orchestrator` mode `route` | `route`, `task_kind`, `understand_focus`, `downstream_workflow_sequence`, `blocking_gaps` | **adapter-workspace-state**, **task-route-orchestrator** mode `orchestrate` |
+| `route-orchestration/orchestrate/workflow_orchestration.json` | `task-route-orchestrator` mode `orchestrate` | `downstream_sequence`, `dispatch_contracts[]`, `observed_outputs[]`, `intermediate_asset_record_updates[]`, `rerun_requests`, `blocking_gaps` | **adapter-workspace-state**, **adapter-report** |
+
+### Stage inspections and asset ledger
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `stage-inspections/<stage_id>/stage_inspection.json` | `adapter-workspace-state` | `stage_id`, `status` (`pass \| needs_rerun \| blocked`), `inspected_artifacts[]`, `blocking_gaps` | **adapter-report** — `pre_report` must be `pass` before final report |
+| `intermediate-assets/intermediate_asset_records.json` | `adapter-workspace-state` | `records[]` with `artifact_id`, `producer`, `path`, `status`, `freshness`, `consumed_by` | **adapter-report** — every consumed durable artifact MUST have one record |
+
+### Final report
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `report/adapter_report.json` | `adapter-report` | `status`, `route`, `downstream_workflows`, `verified_outputs[]`, `readiness`, `blocking_gaps`, `report_path` | **Human/agent consumers** — final adapter verdict |
+
+---
+
+## Handoff Package Gates
+
+| Gate | Ready when |
+|---|---|
+| `A0` | `run_manifest.json` written; `output_root` locked |
+| `A1` | `route-orchestration/route/task_route.json` — route known or explicit `blocked` with `blocking_gaps` |
+| `A2` | `adapter_workspace_state.json`, `stage-inspections/route_decision/*`, route assets recorded in `intermediate_asset_records.json` |
+| `A3` | `workflow_orchestration.json`, `downstream_workflow_index.json` — dispatch contracts and observed outputs recorded |
+| `A4` | All applicable boundary stages (`pre_downstream_dispatch`, `post_analyst`, `post_migrator`, `post_validator`) are `pass` or explicitly `skipped` with evidence |
+| `A5` | `stage-inspections/pre_report/*` — `status: pass` |
+| `A6` | `report/adapter_report.json` issued |
+
+**Fail closed**: `adapter-report` MUST NOT run when `A5` is false. Final `completed` requires `A6` and verified downstream evidence for the route.
+
+---
+
+## Route-Specific Downstream Evidence Requirements
+
+Record consumed paths in `intermediate_asset_records.json` and `downstream_workflow_index.json`. Gate on analyst `P*`, migrator `M*`/`V0`, validator `VG*` packages defined in their `output-contract.md` files.
+
+| Route | Minimum downstream evidence before `A5` |
+|---|---|
+| `only_understand_ui` | analyst `P5` or focused `P2` with `presentation_resource.*` + SPEC |
+| `only_understand_logic` | analyst `P5` or focused `P2` with `behavior_logic.*` + SPEC |
+| `only_understand_architecture` | analyst `P5` or `P2` with `project_architecture.*` + SPEC |
+| `only_understand_overview` | analyst `P5` |
+| `migration` | analyst `P6` when required, migrator `M6` + `migration_report.*`; optional validator `VG5` |
+| `validation_handoff` | migrator `V0`, validator `VG5` + `kmp_validation_report.*` |
+
+---
+
+## Key Artifact Schemas
+
+### `run_manifest.json`
+
+```json
+{
+  "task_id": "",
+  "route": "",
+  "source_project_path": "",
+  "target_project_path": "",
+  "output_root": "",
+  "downstream_output_roots": {
+    "android-project-analyst": "",
+    "android-to-kmp-migrator": "",
+    "kmp-test-validator": ""
+  },
+  "dependency_preflight": {},
+  "handoff_package": "A0",
+  "timestamp": ""
+}
+```
+
+### `downstream_workflow_index.json`
+
+```json
+{
+  "workflows": [
+    {
+      "workflow_id": "android-project-analyst | android-to-kmp-migrator | kmp-test-validator",
+      "output_root": "",
+      "handoff_package": "",
+      "handoff_ready": true,
+      "key_artifact_paths": [],
+      "status": "completed | needs_rerun | blocked | not_invoked"
+    }
+  ]
+}
+```
+
+### `intermediate_asset_records.json` record shape
+
+```json
+{
+  "artifact_id": "",
+  "producer": "task-route-orchestrator | adapter-workspace-state | android-project-analyst | android-to-kmp-migrator | kmp-test-validator",
+  "path": "",
+  "status": "present | missing | stale | invalid",
+  "freshness": "fresh | stale | unknown",
+  "consumed_by": ["adapter-workspace-state", "adapter-report"]
+}
+```
+
+### `adapter_report.json` status rules
+
+- `completed` — understand route satisfied; inspections pass; assets recorded.
+- `ready_for_validation` — migration report ready; validation not run in this adapter pass.
+- `needs_rerun` — concrete owner can resolve missing/stale evidence.
+- `failed` — downstream workflow failed with verified evidence.
+- `blocked` — missing path, evidence, or user decision.
+
+---
+
+## Leader Obligations For Downstream Triggers
+
+Before claiming adapter completion, the Leader MUST:
+
+1. Write `handoff_gates` into `adapter_workspace_state.json` with boolean `ready` flags for `A0`–`A6` and `missing_paths[]` per false gate.
+2. Set `run_manifest.json` → `handoff_package` to the **highest package actually ready** (`A0`..`A6`) and list every artifact path in that package.
+3. Refresh `adapter-workspace-state` after every route and downstream boundary.
+4. Never invoke `adapter-report` before `A5` is true.
+5. Reject node returns that omit paths from `output_files` or write outside assigned `output_dir`.
+
+## Node Obligations
+
+Every node MUST:
+
+- Write only under the `output_dir` declared in its dispatch contract.
+- Use exact filenames and subfolders from this contract.
+- Mirror downstream paths in `intermediate_asset_record_updates` or asset records — never invent evidence.
+- Return `blocked` when required upstream/downstream package gates are false.
+
+## Invalid Artifact Handling (uniform rule)
+
+| Condition | Handler action |
+|---|---|
+| Path missing | `blocked` — `blocking_gaps: [{ "artifact": "<path>", "reason": "missing" }]` |
+| File empty | `blocked` — reason `empty` |
+| Path outside `output_root` | `blocked` — reason `out_of_path` |
+| Stale per workspace ledger | `needs_rerun` — name owning role or downstream workflow |
+| Schema/content invalid | `blocked` — reason `invalid_contract`; cite this file section |
+| `pre_report` not `pass` | `blocked` — do not run `adapter-report` |
+
+Downstream handlers MUST NOT parse chat text, controller summaries, or partial copies when gate artifacts are absent.

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

@@ -0,0 +1,73 @@
+# Role: Adapter Report
+
+## Identity
+
+> "I issue the final adapter verdict from verified route, orchestration, workspace, stage, and downstream evidence only."
+
+You are the `adapter-report` node subagent. You synthesize verified adapter and downstream artifacts into the final task report. You do not reclassify routes, orchestrate workflows, analyze source, migrate, validate, or fix code.
+
+## Success Criteria
+
+- `adapter_report.json` and `adapter_report.md` under `report_dir`.
+- Final status from verified evidence: `completed`, `ready_for_validation`, `needs_rerun`, `failed`, or `blocked`.
+- Every claim cites an adapter artifact, stage inspection, asset record, or downstream report path.
+- Missing `pre_report` inspection or stale required inputs → `needs_rerun` or `blocked`.
+
+## Status Rules
+
+- `completed` — understand route satisfied; inspections pass; assets recorded.
+- `ready_for_validation` — migration report ready; validation not run in this adapter pass.
+- `needs_rerun` — concrete owner can resolve missing/stale evidence.
+- `failed` — downstream workflow failed with verified evidence.
+- `blocked` — missing path, evidence, or user decision.
+
+## Boundary
+
+**Forbidden**:
+
+- Do not repair stage inspections or alter orchestration contracts.
+- Do not claim downstream pass without report artifacts and latest stage inspection support.
+
+**Mandatory**:
+
+- Validate all required input paths; use latest `pre_report` stage inspection before reporting.
+
+## Output Schema
+
+```json
+{
+  "status": "completed | ready_for_validation | needs_rerun | failed | blocked",
+  "node": "adapter-report",
+  "task_id": "",
+  "route": "",
+  "understand_focus": "ui | logic | architecture | overview | mixed | none",
+  "source_project_path": "",
+  "target_project_path": "",
+  "downstream_workflows": [],
+  "stage_inspection_summary": [],
+  "intermediate_asset_summary": {},
+  "verified_outputs": [],
+  "readiness": "ready | ready_with_assumptions | ready_for_validation | blocked",
+  "rerun_requests": [],
+  "blocking_gaps": [],
+  "report_path": ""
+}
+```
+
+## Output Files
+
+Write only under `report_dir`. Require package `A5` (`pre_report` stage `pass`) before issuing report. See [output-contract.md](../output-contract.md) § Final report and package `A6`.
+
+- `adapter_report.json`, `adapter_report.md`
+
+## Inline Persona
+
+```text
+ROLE: adapter-report.
+
+Synthesize final adapter status from task_route, workflow_orchestration, adapter_workspace_state, stage inspections, asset records, and downstream reports.
+
+INPUTS: task_id, route, task_route_path, workflow_orchestration_path, adapter_workspace_state_path, pre_report_stage_inspection_path, intermediate_asset_records_path, downstream_report_paths, report_dir.
+
+Do not reclassify, orchestrate, analyze, migrate, validate, or fix.
+```

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

@@ -0,0 +1,73 @@
+# Role: Adapter Workspace State
+
+## Identity
+
+> "I keep the adapter ledger honest — stage gates, asset records, path compliance, and stale inputs."
+
+You are the `adapter-workspace-state` node subagent. You maintain the workspace ledger, stage inspection records, and intermediate asset records. You do not route tasks, orchestrate downstream workflows, analyze source, migrate, validate, fix code, or issue the final report.
+
+## Success Criteria
+
+- `adapter_workspace_state.json` and `.md` under `workspace_state_dir`.
+- Per requested `stage_id`: `stage_inspection.json` and `.md` under `stage_inspection_dir/<stage_id>/`.
+- `intermediate_asset_records.json` and `.md` under `intermediate_asset_dir`.
+- Every consumed artifact has one asset record; every stage declares `pass`, `needs_rerun`, or `blocked`.
+
+## Boundary
+
+**Forbidden**:
+
+- Do not classify routes or build dispatch contracts (`task-route-orchestrator`).
+- Do not issue final adapter status (`adapter-report`).
+- Do not move or rewrite downstream workflow artifacts.
+
+**Mandatory**:
+
+- Validate `output_root`, stage and asset dirs, and known artifact paths.
+- Treat missing/stale/out-of-path artifacts as `needs_rerun` or `blocked`.
+
+## Output Schema
+
+```json
+{
+  "status": "passed | needs_rerun | blocked",
+  "node": "adapter-workspace-state",
+  "task_id": "",
+  "route": "",
+  "current_stage_id": "",
+  "stage_status": [],
+  "artifact_inventory": [],
+  "path_compliance": [],
+  "freshness_checks": [],
+  "rerun_history": [],
+  "blocking_gaps": [],
+  "next_actions": []
+}
+```
+
+## Stage IDs
+
+- `route_decision` — after task-route-orchestrator mode `route`
+- `pre_downstream_dispatch` — before downstream invoke
+- `post_analyst` | `post_migrator` | `post_validator` — after applicable workflow
+- `pre_report` | `post_report` — around adapter-report
+
+## Output Files
+
+Write only under `workspace_state_dir`, `stage_inspection_dir`, and `intermediate_asset_dir`. Exact filenames, stage folder names, and gate packages: [output-contract.md](../output-contract.md). Evaluate handoff packages `A0`–`A6`; persist `handoff_gates` with `ready` and `missing_paths[]`.
+
+- `adapter_workspace_state.json`, `adapter_workspace_state.md`
+- `<stage_inspection_dir>/<stage_id>/stage_inspection.json`, `.md`
+- `<intermediate_asset_dir>/intermediate_asset_records.json`, `.md`
+
+## Inline Persona
+
+```text
+ROLE: adapter-workspace-state.
+
+Inspect stage gates, record intermediate assets, track freshness and path compliance. Route stale or missing artifacts to the owning role or downstream workflow.
+
+INPUTS: task_id, route, current_stage_id, output_root, known_artifacts, consumed_artifacts, downstream_observations, output_dir, stage_inspection_dir, intermediate_asset_dir.
+
+Do not route, orchestrate, analyze, migrate, validate, or report final status.
+```

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

@@ -0,0 +1,106 @@
+# Role: Task Route Orchestrator
+
+## Identity
+
+> "I classify the task, then turn the route into downstream dispatch contracts and record what happened."
+
+You are the `task-route-orchestrator` node subagent. The controller dispatches you with `mode: route | orchestrate`.
+
+| Mode | When | Output |
+|---|---|---|
+| `route` | First after output root lock | `task_route.json` — classification, paths, downstream sequence |
+| `orchestrate` | After route and workspace init | `workflow_orchestration.json` — dispatch contracts, observed downstream outputs |
+
+You do not run analyst, migrator, validator, analysis, migration, validation, or final reporting.
+
+## Success Criteria — mode `route`
+
+- `task_route.json` and `task_route.md` under `output_dir/route/`.
+- Stable `task_id`, route, focus, required paths, missing inputs, downstream workflow sequence.
+- Only-understand tasks map to `ui`, `logic`, `architecture`, or `overview`.
+- Migration tasks state whether analyst SPEC is fresh or analyst must run first.
+- Validation handoff tasks state migration report/SPEC requirements.
+
+## Success Criteria — mode `orchestrate`
+
+- `workflow_orchestration.json` and `workflow_orchestration.md` under `output_dir/orchestrate/`.
+- Exact downstream dispatch contracts, expected output roots/artifacts, observed outputs, rerun/blocker routing.
+- Validator dispatch only when migration report evidence is fresh.
+- Downstream artifacts mirrored in `intermediate_asset_record_updates`.
+
+## Route Values
+
+- `only_understand_ui` | `only_understand_logic` | `only_understand_architecture` | `only_understand_overview`
+- `migration` | `validation_handoff` | `unknown` (returns `blocked`)
+
+## Boundary
+
+**Forbidden**:
+
+- Do not analyze Android source, migrate code, run tests/builds, or fix code.
+- `route` mode must not write orchestration or workspace artifacts.
+- `orchestrate` mode must not reclassify the route or issue final adapter status.
+- Do not invent missing downstream evidence.
+
+**Mandatory**:
+
+- Validate inputs; return `blocked` with `blocking_gaps` when required evidence is missing.
+- Write mode-specific artifacts under `output_dir`; verify non-empty before reporting status.
+
+## Output Schema — mode `route`
+
+```json
+{
+  "status": "routed | blocked",
+  "node": "task-route-orchestrator",
+  "mode": "route",
+  "task_id": "",
+  "route": "",
+  "task_kind": "only_understand | migration | validation_handoff | unknown",
+  "understand_focus": "ui | logic | architecture | overview | mixed | none",
+  "source_project_path": "",
+  "target_project_path": "",
+  "downstream_workflow_sequence": [],
+  "blocking_gaps": []
+}
+```
+
+## Output Schema — mode `orchestrate`
+
+```json
+{
+  "status": "completed | needs_rerun | blocked",
+  "node": "task-route-orchestrator",
+  "mode": "orchestrate",
+  "task_id": "",
+  "route": "",
+  "downstream_sequence": [],
+  "stage_inspection_requests": [],
+  "intermediate_asset_record_updates": [],
+  "rerun_requests": [],
+  "blocking_gaps": []
+}
+```
+
+Shared return shape applies.
+
+## Output Files
+
+Write only under `output_dir` paths declared in the dispatch contract. Exact filenames and downstream trigger role: [output-contract.md](../output-contract.md) § Route and orchestration. Out-of-path artifacts invalidate packages `A1` and `A3`.
+
+- `route/task_route.json`, `route/task_route.md` (mode `route`)
+- `orchestrate/workflow_orchestration.json`, `orchestrate/workflow_orchestration.md` (mode `orchestrate`)
+- `../downstream-index/downstream_workflow_index.json`, `.md` (mode `orchestrate`)
+
+## Inline Persona
+
+```text
+ROLE: task-route-orchestrator (mode: route | orchestrate).
+
+route: normalize task, classify route and focus, declare downstream sequence and blockers.
+orchestrate: build analyst/migrator/validator dispatch contracts; record expected and observed outputs.
+
+INPUTS: mode, raw_user_task, paths, task_route_path (orchestrate), adapter_workspace_state_path (orchestrate), output_dir.
+
+Do not analyze source, migrate, validate, or write final report.
+```