@code-migration/wow-migrator 0.1.2 → 0.1.4

package/package.json

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

package/skills/android-project-analyst/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: android-project-analyst
 description: |
-  5-role module-first Swarm Skill that converts a Legacy Android project into module-scoped artifacts, a workspace-state ledger, a global representation, and an integrated SPEC package (PRD/DESIGN/PLAN/verification) under strict output paths.
-  Use when the android-project-analyst controller must understand, document, onboard, or migration-prep an existing Android project by dividing it into modules first, including UI and logic coverage, then combining module representations into a full-project representation.
+  Module-first Swarm Skill that converts a Legacy Android project into module-indexed artifacts, per-module dimension folders, cross-module architecture/data-logic records, a workspace-state ledger, a global representation, and an integrated SPEC package (PRD/DESIGN/PLAN/verification) under strict output paths.
+  Use when the android-project-analyst controller must understand, document, onboard, or migration-prep an existing Android project by dividing it into modules first, analyzing each module across presentation/architecture/data/behavior dimensions, recording inter-module assembly basis separately, then combining module representations into a full-project representation.
   Do NOT use for quick file/symbol lookup, non-Android codebases, or single-agent skill authoring.
-version: "0.4"
+version: "0.6"
 kind: swarm-skill
 disable-model-invocation: true
 roles:
@@ -39,20 +39,63 @@ roles:
 
 This is the agent-facing registry and team definition for the `android-project-analyst` controller (the same-name subagent in `kmp-migration/agents/`). It converts a Legacy Android source project into verified module artifacts, a global project representation, and SPEC artifacts for downstream onboarding, exploration, and migration agents.
 
-The team is **module-first Mixed B+C with a workspace-state ledger**: the Leader partitions the project into `analysis_modules`, maintains `analysis-workspace-state` before downstream consumption, runs three foundation nodes in **parallel** (B) inside each module, then a final **gated specialization** node (C) synthesizes module behavior from verified upstream outputs. The Leader writes a module representation per module before combining them into `global_representation.*` and SPEC. The controller owns routing, strict output-path enforcement, reconciliation, workspace-state refreshes, and SPEC integration; nodes own bounded module analysis only.
+**Canonical file recording system**: [output-contract.md](output-contract.md) defines every output path, required content, write order, and downstream **handoff package gates** (`P0`–`P6`). Downstream handlers (`migration-task-adapter`, `android-to-kmp-migrator`, `kmp-test-validator`) trigger only when the declared package artifacts exist, are non-empty, in-path, and not stale. The Leader MUST read `output-contract.md` before the first dispatch and MUST NOT claim completion without updating `handoff_gates` in the workspace ledger and `SPEC/verification.md`.
+
+The team is **module-first Mixed B+C with a workspace-state ledger**: the Leader partitions the project into `analysis_modules`, writes index artifacts and one `modules/<module_id>/` folder per module, maintains `analysis-workspace-state` before downstream consumption, runs three foundation nodes in **parallel** (B) inside each module, then a final **gated specialization** node (C) synthesizes module behavior from verified upstream outputs. The Leader writes a module representation per module, records cross-module architecture and data/logic separately under `global/`, then combines everything into `global_representation.*` and SPEC. The controller owns routing, strict output-path enforcement, reconciliation, workspace-state refreshes, and SPEC integration; nodes own bounded module analysis only.
+
+## Module Partitioning Model
+
+Analysis follows a three-layer artifact model. Downstream migration agents (`android-to-kmp-migrator`) consume this layout to assemble modules in dependency order.
+
+### Layer 1 — Module index and module ID folders
+
+The Leader divides in-scope source into bounded `analysis_modules` and materializes:
+
+- **Index**: `module-index/module_inventory.*` is the authoritative module schedule; `module-index/modules_index.json` is the machine-routable lookup from `module_id` to folder paths, dimension roots, and representation paths.
+- **Per-module root**: every scheduled `module_id` gets `<output_root>/modules/<module_id>/` before node dispatch. No module analysis may run without its folder and `module_brief.json`.
+
+Partitioning rules:
+
+- Prefer Gradle modules and feature packages; split one Gradle module into multiple `analysis_modules` when independent features/routes/packages warrant it.
+- Every in-scope source root belongs to exactly one scheduled module or `out_of_scope`.
+- `module_id` is a stable slug reused across inventory, folder names, node outputs, representations, global cross-module records, and migration handoff.
+
+### Layer 2 — Multi-dimensional understanding inside each module folder
+
+Each module is understood from four analysis dimensions. Dimension outputs live under the same `module_id` folder and are indexed by `dimension_index.json`:
+
+| Dimension | Node | Storage path under `modules/<module_id>/` |
+|---|---|---|
+| `presentation-resource` | `presentation-resource` | `node-results/presentation-resource/` |
+| `project-architecture` | `project-architecture` | `node-results/project-architecture/` |
+| `data-contract-flow` | `data-contract-flow` | `node-results/data-contract-flow/` |
+| `behavior-logic` | `behavior-logic` | `node-results/behavior-logic/` |
+
+The Leader writes `dimension_index.json` after all four node outputs verify. `representation/module_representation.*` synthesizes only from verified dimension artifacts for that `module_id`. Nodes must not write outside their assigned dimension directory.
+
+### Layer 3 — Cross-module architecture and data/logic (migration assembly basis)
+
+Inter-module relationships are **not** folded only into per-module representations. After every scheduled module has a representation, the Leader writes dedicated global artifacts before `global_representation.*`:
+
+- `global/cross_module_architecture.*` — Gradle/topology glue, layer boundaries, navigation integration, shared platform services, DI scope bridges, and architectural dependency graph across `module_id`s.
+- `global/cross_module_data_logic.*` — shared APIs/models/stores, cross-module data flows, event/callback/bus links, and cross-module control interactions.
+- `global/migration_assembly_basis.*` — ordered module assembly sequence, integration checkpoints, shared contracts each module must preserve, and blockers for partial migration.
+
+`global_representation.*` synthesizes from module representations plus the three cross-module artifacts above. SPEC `design.md` and migration-mode `plan.md` must cite these global cross-module artifacts when describing integration or assembly order.
 
 ## Workflow
 
 The full playbook (Mermaid topology, per-step gates, integration rules, Final Report format) is in [workflow.md](workflow.md). Protocol summary:
 
-0. **Pre-flight: check dependencies** — read [dependencies.yaml](dependencies.yaml) and verify `rg` / `curl` / `git`. All are `required: false`; built-in Grep/Read substitute for `rg`, missing `curl` degrades presentation/resource downloads to `download_gaps`, and missing `git` degrades stale-input detection. Report status; **user decides** whether to proceed.
+0. **Pre-flight: check dependencies** — read [dependencies.yaml](dependencies.yaml): `tools[]` (`rg`, `curl`, `git`), `optional_mcp.jetbrains`, and migration-mode `downstream_handoff` **P6** requirements. Report `dependency_preflight` in `run_manifest.json`; **user decides** whether to proceed.
 1. **Trigger + output root lock** — Leader verifies Android evidence and scope, selects `exploration` or `migration`, locks `output_root = <output_dir or ~/.a2c_agents/understand>/android-project-analyst`, and writes `run_manifest.json`.
-2. **Workspace state** — dispatch `analysis-workspace-state` under `<output_root>/workspace-state/`; refresh it after module inventory, each module node group, each module representation, global representation, and SPEC.
-3. **Module inventory** — Leader writes `module-index/module_inventory.json` and `.md`, dividing the project into deterministic `analysis_modules` with UI, logic, data, resource, and dependency scopes.
-4. **Per-module Stage A (parallel, B-pattern)** — for each `module_id`, dispatch `presentation-resource`, `project-architecture`, and `data-contract-flow` under `<output_root>/modules/<module_id>/node-results/<node_id>/`.
+2. **Workspace state** — dispatch `analysis-workspace-state` under `<output_root>/workspace-state/`; refresh it after module inventory, each module node group, each module representation, cross-module global records, global representation, and SPEC.
+3. **Module inventory + index** — Leader writes `module-index/module_inventory.json` and `.md`, plus `module-index/modules_index.json`, dividing the project into deterministic `analysis_modules` and creating each `modules/<module_id>/` folder with scopes and output roots.
+4. **Per-module Stage A (parallel, B-pattern)** — for each `module_id`, dispatch `presentation-resource`, `project-architecture`, and `data-contract-flow` under `<output_root>/modules/<module_id>/node-results/<dimension>/`.
 5. **Per-module Stage B (gated behavior stage, C-pattern)** — after that module's Stage A verifies and workspace-state marks upstream outputs fresh, dispatch `behavior-logic` under the same module root.
-6. **Module representation** — Leader writes `<output_root>/modules/<module_id>/representation/module_representation.json` and `.md` before moving to the next module.
-7. **Global representation + SPEC** — Leader combines module representations into `<output_root>/global/global_representation.json` and `.md`, then writes SPEC under `<output_root>/SPEC`.
+6. **Module dimension index + representation** — Leader writes `dimension_index.json`, then `representation/module_representation.json` and `.md`, synthesizing all four dimensions for that `module_id` before moving to the next module.
+7. **Cross-module global records** — Leader aggregates verified module outputs into `global/cross_module_architecture.*`, `global/cross_module_data_logic.*`, and `global/migration_assembly_basis.*`.
+8. **Global representation + SPEC** — Leader combines module representations and cross-module global records into `global/global_representation.json` and `.md`, then writes SPEC under `<output_root>/SPEC`.
 
 ## Roles
 
@@ -74,13 +117,13 @@ Each node is dispatched as a subagent that must read its role file (`skill_spec_
 
 | File | What it contains | When to read |
 |---|---|---|
+| [output-contract.md](output-contract.md) | Canonical path tree, artifact registry, JSON schemas, handoff packages `P0`–`P6`, downstream trigger rules | **Before first dispatch and before claiming handoff** — downstream handlers gate on this file |
 | [workflow.md](workflow.md) | Mermaid B+C topology, step-by-step protocol with gates, integration rules, Final Report format | Before first dispatch — the complete playbook |
 | [bind.md](bind.md) | Resource limits, team behavioral constraints, contract enforcement, failure & degraded modes | When hitting limits, handling failures, or scoping a large project |
-| [ROLE_CLUSTERING.md](ROLE_CLUSTERING.md) | Function/duty analysis, old-to-new role mapping, and clustering rationale | When auditing role ownership or updating personas |
 | [roles/\*.md](roles/) | Per-node identity, success criteria, boundary, output schema, Inline Persona for Teammate | Before dispatching each teammate — extract Inline Persona |
-| [dependencies.yaml](dependencies.yaml) | External CLI tools (`rg`, `curl`, `git`) checked at startup | Step 0 — verify deps, report missing items, user decides go/no-go |
+| [dependencies.yaml](dependencies.yaml) | CLI tools, optional `jetbrains` MCP, migration **P6** downstream handoff | Step 0 — verify deps, record `dependency_preflight`, user decides go/no-go |
 
-## Converted SPEC Output Contract
+## SPEC Output Contract
 
 The Leader integrates verified module representations and the global representation into a SPEC package under `<output_root>/SPEC`:
 
@@ -93,24 +136,23 @@ The Leader integrates verified module representations and the global representat
 
 SPEC documents must synthesize, not paste node summaries. Every important claim maps to node output + source-path evidence, or is marked an assumption or gap. Node Markdown outputs are agent-readable handoffs that preserve exact paths, evidence, gaps, and routing context.
 
-## Strict Output Schedule
+## Strict Output Schedule And Handoff Gates
+
+The Leader MUST follow the write-order gates `G0`–`G9` and handoff packages `P0`–`P6` in [output-contract.md](output-contract.md). Summary:
+
+| Gate | Artifacts | Unlocks |
+|---|---|---|
+| `G0`–`G2` | `run_manifest.json`, workspace ledger, `module_inventory.*`, `modules_index.json` | Module dispatch (`P1`) |
+| `G3`–`G5` | per-module `module_brief.json` + four dimension JSON/MD pairs | Dimension completeness (`P2`) |
+| `G6` | per-module `dimension_index.json`, `module_representation.*` | Module handoff (`P3`) |
+| `G7` | `cross_module_architecture.*`, `cross_module_data_logic.*`, `migration_assembly_basis.*` | Migrator scheduling (`P4`) |
+| `G8`–`G9` | `global_representation.*`, `SPEC/*` | Exploration (`P5`) or migration (`P6`) pipeline entry |
 
-The Leader MUST write artifacts in this order and MUST NOT skip directly from raw source to global SPEC:
+Any artifact written outside the path tree in `output-contract.md` is **invalid** — downstream handlers MUST return `blocked` with `reason: out_of_path`.
 
-1. `<output_root>/run_manifest.json`
-2. `<output_root>/workspace-state/analysis_workspace_state.json` and `.md` (initialized and refreshed after each major group)
-3. `<output_root>/module-index/module_inventory.json` and `.md`
-4. For each `module_id` in deterministic `module_order`:
-   - `<output_root>/modules/<module_id>/module_brief.json`
-   - `<output_root>/modules/<module_id>/node-results/presentation-resource/presentation_resource.json` and `.md`
-   - `<output_root>/modules/<module_id>/node-results/project-architecture/project_architecture.json` and `.md`
-   - `<output_root>/modules/<module_id>/node-results/data-contract-flow/data_contract_flow.json` and `.md`
-   - `<output_root>/modules/<module_id>/node-results/behavior-logic/behavior_logic.json` and `.md`
-   - `<output_root>/modules/<module_id>/representation/module_representation.json` and `.md`
-5. `<output_root>/global/global_representation.json` and `.md`
-6. `<output_root>/SPEC/prd.md`, `design.md`, `verification.md`, and migration-only `plan.md`
+Before final completion, the Leader MUST set `handoff_gates` in `analysis_workspace_state.json` and mirror them in `SPEC/verification.md` → `## Handoff Gates`. Set `run_manifest.json` → `handoff_package` to the highest ready package (`P0`..`P6`).
 
-Any artifact written outside these paths is invalid for downstream gates.
+JSON artifacts are the machine-routable source of truth. Markdown artifacts are agent-readable handoffs. Full per-file content requirements live in [output-contract.md](output-contract.md) § Artifact Registry.
 
 ## Optional Android Studio MCP Context
 
@@ -123,3 +165,4 @@ When the `jetbrains` MCP server is available, the controller may pass indexed An
 - Each node output must include source-path evidence for important claims; unknowns are marked explicitly, never guessed.
 - Node outputs are intermediate artifacts for SPEC generation, not final user-facing documentation.
 - No node or the Leader modifies the analyzed source project.
+- Downstream handlers gate on file artifacts only — never on chat summaries. Missing package artifacts MUST yield `blocked`, not best-effort continuation.

package/skills/android-project-analyst/bind.md

@@ -6,7 +6,7 @@
 |---|---|---|
 | `max_parallel_teammates` | 3 | Matches the Stage A foundation fan-out (`presentation-resource`, `project-architecture`, `data-contract-flow`); Stage B is single. |
 | `total_wall_clock_budget` | 30 min | Upper bound for one full module-first run; large monorepos should be scoped down per § (b). |
-| `total_token_budget` | 560k tokens | Budget across 5 roles + Leader integration; workspace-state adds ledger checks while clustered roles avoid duplicate cataloging. |
+| `total_token_budget` | 560k tokens | Budget across active roles + Leader integration; workspace-state adds ledger checks. |
 | `per_node_token_budget` | 120k tokens | Per node soft cap; `behavior-logic` and `data-contract-flow` may use the upper end because they consume or trace broad flow evidence. |
 | `resource_download_budget` | 50 files / 50 MB | `presentation-resource` only — caps safe online-resource downloads; excess is recorded in `download_gaps`. |
 | `max_modules_per_run` | 20 | Keeps module-first analysis bounded; larger projects must narrow `analysis_scope` or explicitly run multiple scoped passes. |
@@ -16,15 +16,17 @@
 Team-level rules — distinct from each role's own `## Boundary`.
 
 - **Leader-as-orchestrator only**: the Leader (`android-project-analyst` controller) verifies the trigger, builds the shared brief, dispatches nodes, verifies their outputs, refreshes `analysis-workspace-state`, reconciles, and writes SPEC. The Leader does NOT perform a node's detailed analysis, and does NOT invent any presentation/resource/architecture/ecosystem/data/behavior claim that no node traced to a source path.
-- **Strict output schedule and paths**: the Leader MUST lock `output_root` before dispatch and write only the declared schedule artifacts: `run_manifest`, `workspace-state`, `module-index`, per-module `module_brief`, per-module `node-results`, per-module `representation`, `global`, and `SPEC`. Any node output outside its assigned directory is invalid.
+- **Strict output schedule and paths**: the Leader MUST lock `output_root` before dispatch and write only the declared schedule artifacts: `run_manifest`, `workspace-state`, `module-index` (including `modules_index.json`), per-module `module_brief`, per-module dimension outputs under `node-results/<dimension>/`, per-module `dimension_index.json`, per-module `representation`, cross-module global records (`cross_module_architecture`, `cross_module_data_logic`, `migration_assembly_basis`), `global_representation`, and `SPEC`. Any node output outside its assigned directory is invalid.
 - **Workspace-state discipline**: `analysis-workspace-state` is refreshed after module inventory, each module node group, each module representation, global representation, and SPEC. Downstream roles must not consume artifacts that the ledger marks stale; rerun the responsible node/module or mark the affected scope `blocked`.
-- **Module-first invariant**: every in-scope source root belongs to an `analysis_modules[]` entry before node dispatch. A module representation must exist for every scheduled module before global representation is written. The Leader must not build global SPEC directly from raw source or standalone node outputs.
-- **Clustered slices, dispatch-time fixed (B-pattern, Stage A)**: each foundation node works ONLY on its assigned clustered slice. Slices are fixed at dispatch and are not renegotiated between nodes; nodes do not see each other's working state during Stage A.
+- **Module-first invariant**: every in-scope source root belongs to an `analysis_modules[]` entry before node dispatch. Every scheduled `module_id` must have a materialized folder under `modules/<module_id>/` and a resolvable entry in `modules_index.json`. Each module must store all four dimension outputs in its module folder before `dimension_index.json` and `module_representation.*` are written. Cross-module architecture and data/logic must be recorded in dedicated `global/` artifacts before `global_representation.*`. The Leader must not build global SPEC directly from raw source or standalone node outputs.
+- **Foundation slices, dispatch-time fixed (B-pattern, Stage A)**: each foundation node works ONLY on its assigned slice. Slices are fixed at dispatch and are not renegotiated between nodes; nodes do not see each other's working state during Stage A.
 - **Gated handoff, no upstream mutation (C-pattern, Stage B)**: `behavior-logic` references upstream node outputs (by path) and enriches only where behavior analysis requires; it MUST NOT rebuild or overwrite an upstream node's catalog. If upstream data is missing/stale, it returns `needs_rerun`/`blocked` rather than reconstructing it.
 - **Mandatory contract enforcement**: every node is dispatched with a complete module-scoped contract (`source_project_path`, `module_id`, `module_scope`, `module_brief_path`, required upstream artifacts, `analysis_scope`, `skill_spec_path`, exact `output_dir`). The Leader rejects any return that lacks required JSON/MD artifacts, omits produced files from `output_files`, writes outside the assigned path, or claims `completed`/`ready_*` without proven output storage.
+- **Role-output content discipline**: required artifacts must contain the content owned by their role, not just the correct filename. For example, `presentation_resource.*` must contain screens/resources/navigation/UI-tree evidence, `project_architecture.*` must contain topology/build/dependency/platform evidence, `data_contract_flow.*` must contain APIs/data-source/model/flow evidence, and `behavior_logic.*` must contain action/lifecycle/rule/control-flow evidence. If content belongs to another role, rerun or route rather than accepting it.
 - **Conflict handling**: when nodes disagree on a fact affecting architecture, data flow, resources, ecosystem constraints, behavior, or migration, the Leader surfaces it verbatim as `Needs confirmation` in `verification.md`. The Leader does NOT silently pick a winner or average findings.
 - **No source modification**: no node and not the Leader may edit the analyzed Android project. `presentation-resource` writes downloads only under `<output_dir>/node-results/presentation-resource/downloaded_resources/` and never stores secrets/cookies/tokens.
 - **Agent-only artifacts**: node outputs and SPEC files are structured for downstream agents/controllers, not human presentation; any user-facing summary is produced only after durable artifacts exist.
+- **Downstream trigger discipline**: adherence to [output-contract.md](output-contract.md) is a hard trigger condition for downstream handlers. The Leader must evaluate handoff packages `P0`–`P6`, persist `handoff_gates` in the workspace ledger and `SPEC/verification.md`, and set `run_manifest.json` → `handoff_package`. Downstream workflows (`migration-task-adapter`, `android-to-kmp-migrator`, `kmp-test-validator`) MUST return `blocked` when required package paths are missing, empty, out-of-path, stale, or contract-invalid — they MUST NOT infer from chat or partial summaries.
 
 ## Failure Handling
 
@@ -33,12 +35,16 @@ Team-level rules — distinct from each role's own `## Boundary`.
 | Failure mode | Response |
 |---|---|
 | Node timeout | Retry once with the same contract. On 2nd timeout, mark the node's slice `[ROLE MISSING — node timed out]` in `verification.md` and proceed with remaining outputs (downstream nodes that hard-require it return `blocked`). |
-| Malformed output (does not match role `## Output Schema`, or files missing/empty) | Re-dispatch once with the schema inlined and a "previous output was malformed/missing" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
+| Malformed output (does not match role `## Output Schema`, files missing/empty, or artifact content does not match the role duty) | Re-dispatch once with the schema and role-owned output content inlined plus a "previous output was malformed/missing/out-of-duty" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
 | Node returns `blocked` / `needs_rerun` (missing or stale upstream input) | Refresh `analysis-workspace-state`, resolve the named upstream gap first (re-run the upstream node), then re-dispatch this node. If unresolvable, record the `blocking_gap` and set readiness accordingly. |
 | Node attempts to rebuild another node's catalog | Reject the return as out-of-scope; re-dispatch with the role `## Boundary > Forbidden` restated. |
 | Node writes outside assigned path | Reject the return as invalid; re-dispatch with the exact assigned `output_dir`. Do not move or reuse out-of-path artifacts. |
 | Workspace state marks a required artifact stale | Re-run the owning node or rebuild the owning representation before downstream consumption; do not synthesize around the stale artifact. |
-| Global representation requested before module representations exist | STOP; write/repair missing module representations first, or mark affected modules `blocked` before global integration. |
+| Global representation requested before module representations exist | STOP; write/repair missing module representations first, or mark affected modules `blocked` before cross-module global records. |
+| Cross-module global records requested before all module representations exist | STOP; complete per-module `dimension_index.json` and `module_representation.*` first. |
+| `modules_index.json` missing or cannot resolve a scheduled `module_id` | STOP; repair module inventory and index before node dispatch. |
+| Completion claimed while target handoff package `P*` is false | Reject completion; update `handoff_gates`, set `readiness: blocked`, list `missing_paths` per [output-contract.md](output-contract.md). |
+| Downstream handler invoked without required package artifacts | Downstream returns `blocked` with `blocking_gaps`; analyst Leader does not auto-repair unless rerun is requested. |
 
 ### (b) Input over-scale degradation
 

package/skills/android-project-analyst/dependencies.yaml

@@ -1,20 +1,76 @@
-# dependencies.yaml — Swarm Skill startup dependency check
+# dependencies.yaml — Swarm Skill startup dependency check (android-project-analyst)
 #
-# Leader reads this file in SKILL.md Workflow Step 0 (pre-flight) and reports missing items.
-# Populated from Stage 2 auto-matching (local CLI scan): rg, curl, git found locally.
-# All entries are required: false — the team degrades gracefully (built-in Grep/Read
-# substitute for rg; presentation/resource downloads become download_gaps without curl;
-# workspace-state stale detection degrades without git).
+# Leader reads this in Workflow Step 0 and records results in run_manifest.json
+# → dependency_preflight. All CLI entries are required: false.
+# Android Studio MCP is optional auxiliary evidence for the Legacy Android source project —
+# it never replaces durable node artifacts or handoff package gates (P0–P6).
 
-skills: []   # Stage 2 auto-matching confirmed no local domain-specific skill matches for any role.
+skills: []   # No local domain-specific skill packages required for active roles.
+
+optional_mcp:
+  - server: jetbrains
+    required: false
+    used_by:
+      - Leader
+      - project-architecture
+      - presentation-resource
+      - data-contract-flow
+      - behavior-logic
+    purpose: |
+      Optional indexed Legacy Android project context from Android Studio / JetBrains IDE.
+      Typical tools: get_project_modules, get_project_dependencies, get_repositories,
+      find_files_by_glob, search_in_files_by_regex, get_symbol_info, get_file_problems.
+      Always pass projectPath = source_project_path (Legacy project open in IDE).
+      Supports module inventory, Gradle topology, entry-point discovery, symbol ownership,
+      and diagnostics context. MCP output is supporting evidence only — major claims still
+      require source-path evidence in per-module dimension JSON artifacts and representations.
 
 tools:
   - name: rg
     required: false
-    purpose: Fast source search across the Android project for every clustered analysis node; built-in Grep/Read substitute if unavailable.
+    used_by:
+      - presentation-resource
+      - project-architecture
+      - data-contract-flow
+      - behavior-logic
+    purpose: Fast source search across the Legacy Android project. Built-in Grep/Read substitute if unavailable.
   - name: curl
     required: false
-    purpose: Used only by presentation-resource to download concrete online image/icon/media URLs for analysis; without it, those URLs are recorded as download_gaps instead.
+    used_by:
+      - presentation-resource
+    purpose: |
+      Download concrete online image/icon/media URLs for analysis under
+      node-results/presentation-resource/downloaded_resources/; without curl, record download_gaps.
   - name: git
     required: false
-    purpose: Used by analysis-workspace-state to inspect changed-file sets, timestamps, and stale upstream artifacts; without it, stale checks fall back to artifact path/status evidence.
+    used_by:
+      - analysis-workspace-state
+    purpose: |
+      Changed-file sets, timestamps, and stale upstream detection for the analysis ledger;
+      without git, fall back to artifact path/status comparison.
+
+# Analyst does not compile or build the Legacy Android project during analysis runs.
+
+downstream_handoff:
+  - consumer: android-to-kmp-migrator
+    handoff_package: P6
+    when: mode migration
+    required: true
+    purpose: |
+      Migration-mode runs must produce package P6 artifacts before migrator dispatch:
+      modules_index.json, migration_assembly_basis.json, cross_module_architecture.json,
+      cross_module_data_logic.json, global_representation.json, per-module representations,
+      dimension outputs, SPEC (prd, design, plan, verification). Record paths and
+      handoff_gates in analysis_workspace_state.json and verification.md.
+
+degraded_modes:
+  - trigger: rg missing
+    effect: Use built-in Grep/Read; record in run_manifest dependency_preflight
+  - trigger: curl missing
+    effect: presentation-resource records download_gaps for remote media URLs
+  - trigger: git missing
+    effect: analysis-workspace-state uses artifact timestamps only; stale detection less precise
+  - trigger: jetbrains MCP missing or wrong open project
+    effect: Continue on file-system evidence only; record MCP gap in verification.md
+  - trigger: migration mode without target_project_path
+    effect: Ask user before writing plan.md; exploration mode unaffected