npm - @code-migration/wow-migrator - Versions diffs - 0.1.4 → 0.1.5 - Mend

@code-migration/wow-migrator 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@code-migration/wow-migrator",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Install KMP migration skills into Claude Code, Codex, Cursor, Gemini, OpenCode, OpenClaw, and JiuwenSwarm via npm install.",
   "keywords": [
     "android",

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

@@ -29,6 +29,8 @@ roles:
 Front-door adapter for the KMP Migration Toolkit. It does not replace `android-project-analyst`, `android-to-kmp-migrator`, or `kmp-test-validator`. It classifies the user task, invokes the right downstream workflow, enforces stage gates, records consumed artifacts, and produces a final adapter report.
+**Canonical file recording system**: [output-contract.md](output-contract.md) defines every adapter output path, required content, write order, and **handoff package gates** (`A0`–`A6`). The Leader MUST read `output-contract.md` before the first dispatch and MUST NOT claim completion without updating `handoff_gates` in `adapter_workspace_state.json`.
 ## Task Routes
 | Route | Downstream |
@@ -61,6 +63,7 @@ Front-door adapter for the KMP Migration Toolkit. It does not replace `android-p
 | File | Contents |
 |---|---|
+| [output-contract.md](output-contract.md) | Canonical path tree, artifact registry, gates `A0`–`A6`, downstream root recording |
 | [workflow.md](workflow.md) | Topology, route matrix, stage gates, report shape |
 | [bind.md](bind.md) | Guardrails, path contract, failure handling |
 | [dependencies.yaml](dependencies.yaml) | Downstream skills and optional tools |
@@ -68,8 +71,11 @@ Front-door adapter for the KMP Migration Toolkit. It does not replace `android-p
 ## Output Layout
+See [output-contract.md](output-contract.md) for the full folder tree, filename invariants, and handoff packages `A0`–`A6`. Summary path variables:
 ```text
 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
 stage_inspection_dir = <output_root>/stage-inspections
@@ -77,24 +83,16 @@ intermediate_asset_dir = <output_root>/intermediate-assets
 report_dir = <output_root>/report
 ```
-Required artifacts:
-- `run_manifest.json`
-- `route-orchestration/route/task_route.json`, `.md`
-- `workspace-state/adapter_workspace_state.json`, `.md`
-- `route-orchestration/orchestrate/workflow_orchestration.json`, `.md`
-- `stage-inspections/<stage_id>/stage_inspection.json`, `.md`
-- `intermediate-assets/intermediate_asset_records.json`, `.md`
-- `report/adapter_report.json`, `.md`
+Downstream workflows write only to their own output roots; the adapter records paths in `downstream-index/` and `intermediate-assets/`.
-Downstream workflows write only to their own output roots; the adapter records paths in asset records.
+Any artifact written outside the path tree in `output-contract.md` is **invalid** — adapter roles MUST return `blocked` with `reason: out_of_path`.
 ## Artifact Owners
 | Owner | Artifacts |
 |---|---|
 | Leader | `run_manifest.json` |
-| `task-route-orchestrator` | `task_route.*`, `workflow_orchestration.*` |
+| `task-route-orchestrator` | `task_route.*`, `workflow_orchestration.*`, `downstream_workflow_index.*` |
 | `adapter-workspace-state` | `adapter_workspace_state.*`, `stage_inspection.*`, `intermediate_asset_records.*` |
 | `adapter-report` | `adapter_report.*` |

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

@@ -15,7 +15,7 @@
 - **Orchestrator only** — classify, route, inspect, record, report. No analysis, migration, validation, or code edits.
 - **Route before downstream** — `task-route-orchestrator` mode `route` completes before workflow invoke.
-- **Strict output root** — `output_root = <output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter`.
+- **Strict output root** — `output_root = <output_dir or ~/.a2c_agents/task-adapter>/migration-task-adapter`; paths and gates per [output-contract.md](output-contract.md).
 - **Downstream boundary** — analyst/migrator/validator artifacts stay in their output roots; adapter records paths in asset ledger.
 - **Validator root** — validation artifacts under parallel `validation` root, not migration root.
 - **Stage gates** — every route and downstream boundary gets `stage_inspection.*` with `pass | needs_rerun | blocked`.
@@ -37,9 +37,12 @@
 ## Path Contract
+Canonical paths and handoff gates `A0`–`A6`: [output-contract.md](output-contract.md).
 ```json
 {
   "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",
   "stage_inspection_dir": "<output_root>/stage-inspections",

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

@@ -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 CHANGED Viewed

@@ -56,6 +56,8 @@ You are the `adapter-report` node subagent. You synthesize verified adapter and
 ## 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

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

@@ -54,6 +54,8 @@ You are the `adapter-workspace-state` node subagent. You maintain the workspace
 ## 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`

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

@@ -86,8 +86,11 @@ Shared return shape applies.
 ## Output Files
-- `route/task_route.json`, `route/task_route.md`
-- `orchestrate/workflow_orchestration.json`, `orchestrate/workflow_orchestration.md`
+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

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

@@ -2,6 +2,8 @@
 The adapter classifies intent, records contracts and stage gates, and emits a verified report. It does not perform analysis, migration, or validation itself.
+**File recording system**: every adapter output path, content requirement, and trigger gate is defined in [output-contract.md](output-contract.md). Adapter roles MUST fail closed when handoff package artifacts are missing, empty, out-of-path, stale, or schema-invalid.
 ## Overview
 ```mermaid
@@ -25,8 +27,11 @@ graph TD
 ## Output Paths
+The canonical path tree, stage folder names, and handoff packages `A0`–`A6` are in [output-contract.md](output-contract.md). Summary:
 ```text
 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
 stage_inspection_dir = <output_root>/stage-inspections
@@ -106,6 +111,7 @@ Lock `output_root`; write `run_manifest.json` with task id, paths, scope, depend
 - Route classified before downstream invoke.
 - Stage inspections at each applicable boundary.
-- Every consumed artifact in `intermediate_asset_records.*`.
-- `adapter-report` runs only after fresh `pre_report` gate.
+- Every consumed artifact in `intermediate_asset_records.*` and downstream roots indexed in `downstream_workflow_index.*`.
+- `handoff_gates` in `adapter_workspace_state.json` accurately reflect [output-contract.md](output-contract.md) package readiness (`A0`–`A6`).
+- `adapter-report` runs only after fresh `pre_report` gate (`A5`).
 - Final report cites verified paths; gaps listed, not filled in.