@code-migration/wow-migrator 0.1.2 → 0.1.4

package/skills/android-project-analyst/output-contract.md

@@ -0,0 +1,357 @@
+# Output Contract: File Recording System And Downstream Trigger Gates
+
+This document is the **canonical path and content contract** for `android-project-analyst`. Downstream handlers (`migration-task-adapter`, `android-to-kmp-migrator`, `kmp-test-validator`, and human/agent orchestrators) **MUST treat missing, empty, out-of-path, stale, or schema-invalid artifacts as hard blockers** — they do not infer, reconstruct, or proceed from chat summaries.
+
+The Leader and every node MUST read this file before writing artifacts. `SKILL.md` and `workflow.md` reference this contract; when they diverge, **this file wins on paths, filenames, and trigger gates**.
+
+## Output Root Layout
+
+Lock one `output_root` before any dispatch:
+
+```text
+output_root = <output_dir or ~/.a2c_agents/understand>/android-project-analyst
+
+<output_root>/
+├── run_manifest.json                          # run identity + handoff package pointer
+├── workspace-state/
+│   ├── analysis_workspace_state.json          # machine ledger (freshness + inventory)
+│   └── analysis_workspace_state.md
+├── module-index/
+│   ├── module_inventory.json                  # authoritative module schedule
+│   ├── module_inventory.md
+│   └── modules_index.json                     # machine lookup: module_id → paths
+├── modules/
+│   └── <module_id>/
+│       ├── module_brief.json                  # dispatch contract for this module
+│       ├── dimension_index.json               # dimension → artifact path map
+│       ├── node-results/
+│       │   ├── presentation-resource/
+│       │   │   ├── presentation_resource.json
+│       │   │   ├── presentation_resource.md
+│       │   │   └── downloaded_resources/    # optional; presentation-resource only
+│       │   ├── project-architecture/
+│       │   │   ├── project_architecture.json
+│       │   │   └── project_architecture.md
+│       │   ├── data-contract-flow/
+│       │   │   ├── data_contract_flow.json
+│       │   │   └── data_contract_flow.md
+│       │   └── behavior-logic/
+│       │       ├── behavior_logic.json
+│       │       └── behavior_logic.md
+│       └── representation/
+│           ├── module_representation.json
+│           └── module_representation.md
+├── global/
+│   ├── cross_module_architecture.json
+│   ├── cross_module_architecture.md
+│   ├── cross_module_data_logic.json
+│   ├── cross_module_data_logic.md
+│   ├── migration_assembly_basis.json
+│   ├── migration_assembly_basis.md
+│   ├── global_representation.json
+│   └── global_representation.md
+└── SPEC/
+    ├── prd.md
+    ├── design.md
+    ├── verification.md
+    └── plan.md                                # migration mode only
+```
+
+### Path Variables (stable across runs)
+
+| Variable | Resolved path |
+|---|---|
+| `output_root` | `<output_dir or ~/.a2c_agents/understand>/android-project-analyst` |
+| `workspace_state_dir` | `<output_root>/workspace-state` |
+| `module_index_dir` | `<output_root>/module-index` |
+| `module_root` | `<output_root>/modules/<module_id>` |
+| `dimension_dir` | `<module_root>/node-results/<dimension>` |
+| `module_representation_dir` | `<module_root>/representation` |
+| `global_dir` | `<output_root>/global` |
+| `spec_dir` | `<output_root>/SPEC` |
+
+### Filename Invariants (downstream parsers depend on these)
+
+- JSON primary artifacts use **snake_case** basenames matching the dimension or record type (`presentation_resource.json`, not `presentation-resource.json`).
+- Dimension folder names use **kebab-case** node ids (`node-results/presentation-resource/`).
+- `module_id` folder names use the **same slug** as in `module_inventory.json` and `modules_index.json`.
+- No artifact outside `<output_root>/` is valid for gates below.
+
+---
+
+## 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 | `G0` | `run_manifest.json` |
+| 1 | `G1` | `workspace-state/analysis_workspace_state.*` (initialized) |
+| 2 | `G2` | `module-index/module_inventory.*`, `module-index/modules_index.json` |
+| 3 | `G3` | per `module_id`: `module_brief.json` |
+| 4 | `G4` | per `module_id`: all three Stage A dimension JSON+MD pairs |
+| 5 | `G5` | per `module_id`: `behavior-logic` dimension JSON+MD pair |
+| 6 | `G6` | per `module_id`: `dimension_index.json`, `representation/module_representation.*` |
+| 7 | `G7` | `global/cross_module_architecture.*`, `global/cross_module_data_logic.*`, `global/migration_assembly_basis.*` |
+| 8 | `G8` | `global/global_representation.*` |
+| 9 | `G9` | `SPEC/prd.md`, `SPEC/design.md`, `SPEC/verification.md`, migration-only `SPEC/plan.md` |
+
+---
+
+## Artifact Registry: Path, Owner, Content, Trigger Role
+
+### Run identity
+
+| Path | Owner | Required JSON / content keys | Downstream trigger role |
+|---|---|---|---|
+| `run_manifest.json` | Leader | `source_project_path`, `mode`, `analysis_scope`, `output_root`, `schedule_version`, `handoff_package`, `allowed_path_roots`, `dependency_preflight`, `timestamp`; migration mode adds `target_project_path` | **All handlers** — resolves `output_root` and declares which gate package this run claims |
+
+`handoff_package` MUST list absolute paths to the gate entry artifacts the run claims ready (see Handoff Packages below).
+
+### Workspace ledger
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `workspace-state/analysis_workspace_state.json` | `analysis-workspace-state` | `module_status`, `node_status`, `artifact_inventory`, `stale_upstream_inputs`, `rerun_history`, `blocking_gaps`, `next_actions`, `handoff_gates` | **All handlers** — refuse consumption when `stale_upstream_inputs` marks a required artifact stale or `handoff_gates.*.ready` is false |
+
+### Module index layer
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `module-index/module_inventory.json` | Leader | `analysis_modules[]`, `module_order[]`, `out_of_scope[]`, per-module `module_id`, `module_type`, `source_roots`, `ui_scope`, `logic_scope`, `data_scope`, `resource_scope`, `depends_on`, `module_output_root` | **Module scheduling** — authoritative partition; migrator maps `module_id` → source scope |
+| `module-index/module_inventory.md` | Leader | Boundary evidence and scope notes (no dimension analysis) | Agent-readable scope confirmation |
+| `module-index/modules_index.json` | Leader | `schema_version`, `output_root`, `modules[]` with per-entry `module_id`, `status`, `module_output_root`, `module_brief_path`, `dimension_roots`, `representation_paths`, `depends_on` | **Primary routing index** — downstream handlers resolve module folders only through this file |
+
+#### `modules_index.json` minimum schema
+
+```json
+{
+  "schema_version": "1.0",
+  "output_root": "",
+  "module_order": [],
+  "modules": [
+    {
+      "module_id": "",
+      "status": "scheduled | completed | blocked | out_of_scope",
+      "module_output_root": "",
+      "module_brief_path": "",
+      "dimension_roots": {
+        "presentation-resource": "",
+        "project-architecture": "",
+        "data-contract-flow": "",
+        "behavior-logic": ""
+      },
+      "representation_paths": {
+        "dimension_index": "",
+        "module_representation_json": "",
+        "module_representation_md": ""
+      },
+      "depends_on": []
+    }
+  ]
+}
+```
+
+### Per-module dispatch and dimensions
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `modules/<module_id>/module_brief.json` | Leader | `module_id`, `module_type`, `source_roots`, scopes, `depends_on`, `output_root`, `dimension_output_dirs`, role hints | **Node dispatch** — nodes refuse work without this contract |
+| `modules/<module_id>/node-results/presentation-resource/presentation_resource.json` | `presentation-resource` | `module_id`, `screen_inventory`, `navigation_edges`, `cross_module_references[]`, `resource_usage_map`, `evidence_paths` | UI understanding, resource migration, navigation handoff |
+| `modules/<module_id>/node-results/project-architecture/project_architecture.json` | `project-architecture` | `module_id`, `module_topology`, `detected_patterns`, `layer_roles`, `cross_module_dependencies[]`, `migration_constraints`, `evidence_paths` | Architecture migration, dependency/platform gate |
+| `modules/<module_id>/node-results/data-contract-flow/data_contract_flow.json` | `data-contract-flow` | `module_id`, API/model contracts, `end_to_end_flows`, `cross_module_data_links[]`, `evidence_paths` | Data/API migration, repository mapping |
+| `modules/<module_id>/node-results/behavior-logic/behavior_logic.json` | `behavior-logic` | `module_id`, `screen_logic`, `control_flows`, `cross_module_interactions[]`, upstream alignment refs | Behavior/test planning, control-flow migration |
+| `modules/<module_id>/dimension_index.json` | Leader | `module_id`, `dimensions{}` with four entries, each with `node_id`, `output_dir`, `json_path`, `md_path`, `status` | **Per-module completeness gate** — handlers verify all four dimensions before consuming representation |
+| `modules/<module_id>/representation/module_representation.json` | Leader | `module_id`, `dimension_traceability[]`, synthesized slices per dimension, `intra_module_gaps`, `readiness` | **Module-level handoff** — migrator loads this for a scoped `module_id` |
+
+#### `dimension_index.json` minimum schema
+
+```json
+{
+  "module_id": "",
+  "schema_version": "1.0",
+  "dimensions": {
+    "presentation-resource": {
+      "node_id": "presentation-resource",
+      "output_dir": "",
+      "json_path": "",
+      "md_path": "",
+      "status": "completed | blocked | missing",
+      "evidence_count": 0
+    },
+    "project-architecture": { },
+    "data-contract-flow": { },
+    "behavior-logic": { }
+  },
+  "representation_ready": false
+}
+```
+
+Each dimension entry MUST have resolvable `json_path` and `md_path` before `representation_ready` is true.
+
+### Cross-module global records (migration assembly basis)
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `global/cross_module_architecture.json` | Leader | `architectural_edges[]` (`from_module_id`, `to_module_id`, `edge_type`, `evidence_paths`), `navigation_glue`, `shared_platform_services`, `di_bridges`, `conflicts[]` | **Inter-module architecture gate** — required before global representation and migrator topology planning |
+| `global/cross_module_data_logic.json` | Leader | `shared_contracts[]`, `data_flow_edges[]`, `control_flow_edges[]`, `event_bus_links[]`, `evidence_paths` | **Inter-module data/logic gate** — required for API/state handoff across modules |
+| `global/migration_assembly_basis.json` | Leader | `assembly_order[]`, `integration_checkpoints[]`, `shared_contracts_to_preserve[]`, `partial_migration_boundaries[]`, `blockers[]`, `evidence_paths` | **Primary migrator scheduling trigger** — `android-to-kmp-migrator` uses this to order `migration_module_id` work |
+
+#### `migration_assembly_basis.json` minimum schema
+
+```json
+{
+  "schema_version": "1.0",
+  "output_root": "",
+  "assembly_order": ["module_id_1", "module_id_2"],
+  "integration_checkpoints": [
+    {
+      "checkpoint_id": "",
+      "after_module_id": "",
+      "required_artifacts": [],
+      "shared_contracts": [],
+      "verification_focus": []
+    }
+  ],
+  "shared_contracts_to_preserve": [],
+  "partial_migration_boundaries": [],
+  "blockers": [],
+  "evidence_paths": []
+}
+```
+
+### Global synthesis and SPEC
+
+| Path | Owner | Required content | Downstream trigger role |
+|---|---|---|---|
+| `global/global_representation.json` | Leader | `module_summaries[]`, refs to cross-module global records, `global_readiness`, `evidence_index` | **Full-project handoff** — exploration overview and migrator context |
+| `SPEC/prd.md` | Leader | Product scope, journeys, entities, rules (evidence-backed) | Exploration + migration product baseline |
+| `SPEC/design.md` | Leader | Architecture, modules, integration view citing cross-module global records | Exploration + migration design baseline |
+| `SPEC/verification.md` | Leader | Coverage matrix, traceability, `readiness` verdict (`ready \| ready_with_assumptions \| blocked`), `handoff_gates` status | **Universal readiness gate** — downstream workflows read verdict before dispatch |
+| `SPEC/plan.md` | Leader (migration only) | Assembly order from `migration_assembly_basis.*`, milestones, source-to-target mapping | **Migration plan gate** — required for `android-to-kmp-migrator` |
+
+---
+
+## Handoff Packages (Downstream Trigger Conditions)
+
+Downstream handlers MUST NOT start unless the declared package gate passes. A gate passes only when **every listed path exists, is non-empty, matches schema/content rules above, and is not marked stale** in `analysis_workspace_state.json`.
+
+### Package `P0` — Run identity
+
+**Trigger for**: any downstream read of this analysis run.
+
+| Required paths |
+|---|
+| `run_manifest.json` |
+| `workspace-state/analysis_workspace_state.json` |
+
+**Fail closed when**: `output_root` mismatch, manifest missing, or ledger reports `blocking_gaps` without explicit `ready_with_assumptions` override in `SPEC/verification.md`.
+
+### Package `P1` — Module index routing
+
+**Trigger for**: per-module analyst rerun, adapter scoped dispatch, migrator module lookup.
+
+| Required paths |
+|---|
+| `module-index/module_inventory.json` |
+| `module-index/modules_index.json` |
+
+**Fail closed when**: `modules_index.json` cannot resolve a requested `module_id`, or `module_order` is empty for in-scope work.
+
+### Package `P2` — Module dimension completeness
+
+**Trigger for**: module representation consumption, focused UI/logic/architecture handoff from `migration-task-adapter`.
+
+| Required paths (per `module_id`) |
+|---|
+| `modules/<module_id>/module_brief.json` |
+| `modules/<module_id>/dimension_index.json` (all four dimensions `status: completed`) |
+| all four dimension JSON+MD pairs under `node-results/<dimension>/` |
+
+**Fail closed when**: any dimension is `missing`, `blocked`, or paths in `dimension_index.json` do not resolve.
+
+### Package `P3` — Module representation handoff
+
+**Trigger for**: `android-to-kmp-migrator` per-module planning scoped to one legacy `module_id`.
+
+| Required paths (per `module_id`) |
+|---|
+| Package `P2` artifacts |
+| `modules/<module_id>/representation/module_representation.json` |
+| `modules/<module_id>/representation/module_representation.md` |
+
+**Fail closed when**: representation references dimension paths that fail Package `P2`.
+
+### Package `P4` — Cross-module assembly basis
+
+**Trigger for**: `android-to-kmp-migrator` whole-project or multi-module scheduling.
+
+| Required paths |
+|---|
+| Package `P1` artifacts |
+| Package `P3` artifacts for every `module_id` in `migration_assembly_basis.json` → `assembly_order` |
+| `global/cross_module_architecture.json` |
+| `global/cross_module_data_logic.json` |
+| `global/migration_assembly_basis.json` |
+
+**Fail closed when**: `assembly_order` omits a scheduled module without `out_of_scope` evidence, or cross-module edges lack `evidence_paths`.
+
+### Package `P5` — Exploration SPEC handoff
+
+**Trigger for**: onboarding, documentation-only consumption, adapter `only_understand_*` routes.
+
+| Required paths |
+|---|
+| Package `P0` artifacts |
+| Package `P1` artifacts |
+| `global/global_representation.json` |
+| `SPEC/prd.md`, `SPEC/design.md`, `SPEC/verification.md` |
+
+**Fail closed when**: `SPEC/verification.md` → `readiness: blocked`.
+
+### Package `P6` — Migration SPEC handoff (full pipeline entry)
+
+**Trigger for**: `android-to-kmp-migrator` controller start, migration-mode adapter orchestration.
+
+| Required paths |
+|---|
+| Package `P4` artifacts |
+| Package `P5` artifacts |
+| `global/global_representation.json` |
+| `SPEC/plan.md` |
+
+**Fail closed when**: `readiness` is `blocked`, `plan.md` assembly order disagrees with `migration_assembly_basis.json` without documented conflict in `verification.md`, or `run_manifest.json` → `mode` is not `migration`.
+
+---
+
+## Leader Obligations For Downstream Triggers
+
+Before claiming run completion, the Leader MUST:
+
+1. Write `handoff_gates` into `analysis_workspace_state.json` with boolean `ready` flags for `P0`–`P6` and lists of missing paths per false gate.
+2. Mirror the same `handoff_gates` summary in `SPEC/verification.md` under a `## Handoff Gates` section.
+3. Set `run_manifest.json` → `handoff_package` to the **highest package actually ready** (`P0`..`P6`) and list every artifact path in that package.
+4. Never set `readiness: ready` in `verification.md` when the target downstream package gate is false.
+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 from this contract (JSON snake_case basename, dimension folder kebab-case).
+- Include `module_id` in every dimension JSON artifact.
+- Populate cross-module pointer arrays (`cross_module_references`, `cross_module_dependencies`, `cross_module_data_links`, `cross_module_interactions`) with `target_module_id` and `source_paths` so the Leader can build Package `P4` without re-reading source.
+
+## Invalid Artifact Handling (downstream uniform rule)
+
+| Condition | Downstream handler action |
+|---|---|
+| Path missing | `blocked` — return `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 node or Leader integration step |
+| Schema/content invalid | `blocked` — reason `invalid_contract`; cite this file section |
+| `readiness: blocked` in verification | `blocked` — do not start migration or validation |
+
+Downstream handlers MUST NOT parse chat text, controller summaries, or partial copies when gate artifacts are absent.

package/skills/android-project-analyst/roles/analysis-workspace-state.md

@@ -13,8 +13,9 @@ You are the `analysis-workspace-state` node subagent dispatched by the `android-
 - Stale inputs are flagged when module briefs, node outputs, module representations, global representation, SPEC paths, source roots, or analysis requirements changed since a dependent artifact was produced.
 - Rerun and blocker history are recorded without hiding repeated failures.
 - Next safe controller actions are listed.
+- `handoff_gates` for packages `P0`–`P6` per [output-contract.md](../output-contract.md) are evaluated with `ready` flags and `missing_paths[]`.
 
-**Focus areas**: module status normalization, node-output inventory, stale-input detection, blocker/rerun history, next-action guidance, SPEC readiness prerequisites.
+**Focus areas**: module status normalization, node-output inventory, stale-input detection, handoff-gate evaluation, blocker/rerun history, next-action guidance, SPEC readiness prerequisites.
 
 ## Boundary
 
@@ -47,12 +48,30 @@ You are the `analysis-workspace-state` node subagent dispatched by the `android-
   "stale_upstream_inputs": [],
   "rerun_history": [],
   "blocking_gaps": [],
-  "next_actions": []
+  "next_actions": [],
+  "handoff_gates": {
+    "P0": { "ready": false, "missing_paths": [] },
+    "P1": { "ready": false, "missing_paths": [] },
+    "P2": { "ready": false, "missing_paths": [] },
+    "P3": { "ready": false, "missing_paths": [] },
+    "P4": { "ready": false, "missing_paths": [] },
+    "P5": { "ready": false, "missing_paths": [] },
+    "P6": { "ready": false, "missing_paths": [] }
+  }
 }
 ```
 
 Shared controller return shape (all nodes): `status`, `node`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
 
+## Output Path Contract
+
+Write only under `output_dir = <output_root>/workspace-state/`. Evaluate handoff packages `P0`–`P6` per [output-contract.md](../output-contract.md). Downstream handlers read `handoff_gates` from this ledger before triggering.
+
+## Output Files And Contents
+
+- `analysis_workspace_state.json`: machine-routable ledger of run mode, current controller step, module statuses, node output statuses, artifact inventory, stale upstream inputs, rerun history, blocking gaps, `handoff_gates` (`P0`–`P6` per [output-contract.md](../output-contract.md)), and next safe actions. It must not include UI, architecture, data-flow, or behavior analysis.
+- `analysis_workspace_state.md`: agent-readable ledger handoff with module status table, dimension output inventory per `module_id`, `modules_index.json` and `dimension_index.json` readiness, cross-module global record status, artifact readiness table, stale-input table, rerun/blocker history, and next controller action. It must preserve exact artifact paths and owner nodes.
+
 ## Inline Persona for Teammate
 
 ```
@@ -94,22 +113,25 @@ INPUTS YOU WILL RECEIVE:
 
 HANDLER (how you process):
 1. Normalize module status and node output status for every known analysis module.
-2. Track artifact inventory for run manifest, module inventory, module briefs, node outputs,
-   module representations, global representation, and SPEC outputs.
+2. Track artifact inventory for run manifest, module inventory, modules_index.json, module briefs,
+   dimension outputs, dimension_index.json, module representations, cross-module global records,
+   global representation, and SPEC outputs.
 3. Detect stale upstream inputs when source roots, module briefs, node outputs, representations, or
    SPEC inputs changed after dependent artifacts were produced.
 4. Record rerun and blocker history without hiding repeated failures.
-5. Identify the next safe controller action.
+5. Evaluate handoff packages P0–P6 from output-contract.md; set ready flags and missing_paths.
+6. Identify the next safe controller action.
 
 OUTPUTS (write under output_dir, exact names):
-- analysis_workspace_state.json (schema below)
-- analysis_workspace_state.md
+- analysis_workspace_state.json (machine ledger: module/node/artifact status, stale inputs, reruns, blockers, next actions)
+- analysis_workspace_state.md (agent-readable ledger: status tables, stale/rerun/blocker evidence, next safe action)
 
 analysis_workspace_state.json schema:
 { "status": "completed | blocked", "node": "analysis-workspace-state", "output_root": "",
   "current_controller_step": "", "mode": "exploration | migration", "module_status": [],
   "node_status": [], "artifact_inventory": [], "stale_upstream_inputs": [], "rerun_history": [],
-  "blocking_gaps": [], "next_actions": [] }
+  "blocking_gaps": [], "next_actions": [],
+  "handoff_gates": { "P0": { "ready": false, "missing_paths": [] }, "...": "P1-P6 same shape" } }
 
 RETURN TO CONTROLLER (shared shape, no preamble):
 { "status": "completed | blocked", "node": "analysis-workspace-state",

package/skills/android-project-analyst/roles/behavior-logic.md

@@ -4,7 +4,7 @@
 
 > *"I am the final node — I connect user and lifecycle events to handlers, state changes, rules, side effects, and navigation without rebuilding upstream catalogs."*
 
-You are the `behavior-logic` node subagent and behavior/control-flow owner dispatched by the `android-project-analyst` controller. You run last, with all Stage A clustered node outputs available. You own user-action flows, lifecycle flows, state-holder behavior, business rules, side effects, state machines, navigation effects, permission/auth/feature gates, and cross-module control interactions. You produce agent-readable behavior evidence for PRD, DESIGN, PLAN, and validation planning.
+You are the `behavior-logic` node subagent and behavior/control-flow owner dispatched by the `android-project-analyst` controller. You run last, with all Stage A foundation node outputs available. You own user-action flows, lifecycle flows, state-holder behavior, business rules, side effects, state machines, navigation effects, permission/auth/feature gates, and cross-module control interactions. You produce agent-readable behavior evidence for PRD, DESIGN, PLAN, and validation planning.
 
 ## Success Criteria
 
@@ -87,7 +87,14 @@ You are the `behavior-logic` node subagent and behavior/control-flow owner dispa
 }
 ```
 
-The companion `behavior_logic.md` is an agent-readable handoff: screen-to-state-holder mapping, major user-action flows, lifecycle/initialization behavior, links to upstream data-contract/flow diagrams, project architecture/ecosystem effects on logic, business rules and error/loading/empty handling, cross-module interaction summary, state machines, unknowns, and assumptions.
+## Output Path Contract
+
+Write only under `output_dir = <output_root>/modules/<module_id>/node-results/behavior-logic/`. Exact filenames and downstream trigger role: [output-contract.md](../output-contract.md) § Per-module dispatch and dimensions. Out-of-path artifacts invalidate package `P2`.
+
+## Output Files And Contents
+
+- `behavior_logic.json`: machine-routable behavior/control artifact containing screen logic, state holders, initialization flow, user-action flows, lifecycle behaviors, business rules, data-contract links, control flows, cross-module interactions, state machines, upstream alignment, assumptions, and evidence paths.
+- `behavior_logic.md`: agent-readable behavior handoff containing screen-to-state-holder mapping, major user-action flows, lifecycle/initialization behavior, links to upstream data-contract/flow diagrams, project architecture/ecosystem effects on logic, business rules and error/loading/empty handling, cross-module interaction summary, state machines, unknowns, and assumptions.
 
 ## Inline Persona for Teammate
 
@@ -129,7 +136,7 @@ INPUTS YOU WILL RECEIVE:
 - output_dir (required, exact): {OUTPUT_ROOT}/modules/{MODULE_ID}/node-results/behavior-logic
 
 HANDLER (how you process):
-1. Stay inside module_scope; record cross-module interactions but do not analyze target modules.
+1. Stay inside module_scope; record cross_module_interactions with target_module_id and source_paths but do not analyze target modules — these feed global/cross_module_data_logic.* during Leader integration.
 2. Link presentation modules/screens to state holders (ViewModels/presenters/controllers/stores/
    reducers/interactors/loaders/state classes).
 3. Trace user-triggered control flow (click/input/refresh/pagination/tab/nav-result/deep-link/
@@ -148,8 +155,8 @@ HANDLER (how you process):
    flowchart for complex logic).
 
 OUTPUTS (write under output_dir, exact names):
-- behavior_logic.json
-- behavior_logic.md
+- behavior_logic.json (machine artifact: screen logic, actions, lifecycle, rules, data links, control/state flows, upstream alignment, evidence)
+- behavior_logic.md (agent handoff: behavior tables, flow/state diagrams, upstream alignment, unknowns)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {

package/skills/android-project-analyst/roles/data-contract-flow.md

@@ -88,7 +88,14 @@ You are the `data-contract-flow` node subagent and data contract/flow owner disp
 }
 ```
 
-The companion `data_contract_flow.md` is an agent-readable handoff: network stack overview, API endpoint table, consumer mapping table, local/generated/platform data-source inventory, model mapping notes, repository & mapper flow tables, reactive stream summary, end-to-end Mermaid flow diagrams (when evidence allows), loading/error/empty handling summary, dynamic or unknown API gaps, gaps, and assumptions.
+## Output Path Contract
+
+Write only under `output_dir = <output_root>/modules/<module_id>/node-results/data-contract-flow/`. Exact filenames and downstream trigger role: [output-contract.md](../output-contract.md) § Per-module dispatch and dimensions. Out-of-path artifacts invalidate package `P2`.
+
+## Output Files And Contents
+
+- `data_contract_flow.json`: machine-routable data contract/flow artifact containing network stack, API declarations, request/response/model contracts, local/generated/platform data sources, model mappings, repository flows, reactive streams, transformations, end-to-end flows, dynamic/unknown APIs, cross-module data links, gaps, assumptions, and evidence paths.
+- `data_contract_flow.md`: agent-readable data handoff containing network stack overview, API endpoint table, consumer mapping table, local/generated/platform data-source inventory, model mapping notes, repository & mapper flow tables, reactive stream summary, end-to-end Mermaid flow diagrams when evidence allows, loading/error/empty handling summary, dynamic or unknown API gaps, gaps, and assumptions.
 
 ## Inline Persona for Teammate
 
@@ -130,7 +137,7 @@ INPUTS YOU WILL RECEIVE:
 - optional jetbrains MCP context (indexed search / symbol info): {MCP_CONTEXT}
 
 HANDLER (how you process):
-1. Stay inside module_scope; record cross-module data dependencies as cross_module_data_links
+1. Stay inside module_scope; record cross-module data dependencies as cross_module_data_links with target_module_id and source_paths — these feed global/cross_module_data_logic.* during Leader integration
    without analyzing target modules here.
 2. Identify network stack (Retrofit/OkHttp/Ktor/Volley/GraphQL/custom/generated clients).
 3. Catalog API service declarations (path, method, function, service class, request/response
@@ -152,8 +159,8 @@ HANDLER (how you process):
    unavailable, unclear consumers).
 
 OUTPUTS (write under output_dir, exact names):
-- data_contract_flow.json
-- data_contract_flow.md
+- data_contract_flow.json (machine artifact: APIs, data sources, models, mappings, repository/reactive/end-to-end flows, gaps, evidence)
+- data_contract_flow.md (agent handoff: endpoint/source/consumer tables, flow diagrams, loading/error/empty behavior, unknowns)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {

package/skills/android-project-analyst/roles/presentation-resource.md

@@ -130,7 +130,15 @@ You are the `presentation-resource` node subagent and presentation/resource owne
 }
 ```
 
-The companion `presentation_resource.md` is an agent-readable handoff: UI entry point overview, screen inventory table, checked UI layout/view trees by screen or section, Mermaid navigation graph (when evidence allows), presentation module decomposition, shared component summary, local resource inventory, online resource sources, downloaded resource manifest, resource→usage mapping table, production vs debug/test/sample classification, migration implications, download gaps, unknowns, and assumptions.
+## Output Path Contract
+
+Write only under `output_dir = <output_root>/modules/<module_id>/node-results/presentation-resource/`. Exact filenames and downstream trigger role: [output-contract.md](../output-contract.md) § Per-module dispatch and dimensions. Out-of-path artifacts invalidate package `P2`.
+
+## Output Files And Contents
+
+- `presentation_resource.json`: machine-routable presentation/resource artifact containing UI entry points, screen inventory, checked UI layout/view trees, presentation modules, navigation edges, shared presentation components, local/online/downloaded resources, resource usage map, migration implications, cross-module references, download gaps, assumptions, and evidence paths.
+- `presentation_resource.md`: agent-readable presentation handoff containing UI entry point overview, screen inventory table, checked UI layout/view trees by screen or section, Mermaid navigation graph when evidence allows, presentation module decomposition, shared component summary, local resource inventory, online resource sources, downloaded resource manifest, resource-to-usage mapping table, production vs debug/test/sample classification, migration implications, download gaps, unknowns, and assumptions.
+- `downloaded_resources/`: optional auxiliary directory for safe concrete HTTP(S) resources downloaded for analysis. Every file must be represented in `downloaded_resources[]` with original URL, local path, content type, SHA-256, byte size, status, and reason when skipped/failed.
 
 ## Checked UI Layout / View Tree Format
 
@@ -231,7 +239,7 @@ INPUTS YOU WILL RECEIVE:
 - optional jetbrains MCP context (project modules / indexed search / symbol info): {MCP_CONTEXT}
 
 HANDLER (how you process):
-1. Stay inside module_scope; record cross-module references but do not analyze target modules here.
+1. Stay inside module_scope; record cross_module_references with target_module_id and source_paths but do not analyze target modules here — these feed global/cross_module_architecture.* during Leader integration.
 2. Identify UI entry points (Activities, Fragments, Compose destinations, NavGraphs, routers,
    deep links, manifest-declared screen components).
 3. Build a screen inventory (name, source path, ui_technology, owning module, entry route).
@@ -280,8 +288,9 @@ ForegroundConstraintLayout @id/parent_layout  [match_parent x wrap_content, padd
     └── src=ic_vector_more_new, tint=Graph_weak
 
 OUTPUTS (write under output_dir, exact names):
-- presentation_resource.json
-- presentation_resource.md
+- presentation_resource.json (machine artifact: screens, checked UI trees, navigation, presentation modules, resources, usage map, downloads, gaps, evidence)
+- presentation_resource.md (agent handoff: screen/resource tables, checked UI tree blocks, navigation graph, migration implications, unknowns)
+- downloaded_resources/ (optional safe downloaded resource copies, only when concrete URLs are proven)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {

package/skills/android-project-analyst/roles/project-architecture.md

@@ -97,7 +97,14 @@ You are the `project-architecture` node subagent and project architecture/ecosys
 }
 ```
 
-The companion `project_architecture.md` is an agent-readable handoff: build/SDK configuration, project topology overview, detected patterns + confidence, layer/role mapping, dependency + Jetpack inventory, DI setup, persistence/background/platform-service usage, generated tooling, dependency direction notes, legacy hybrid patterns/risks, migration constraints, and unknowns.
+## Output Path Contract
+
+Write only under `output_dir = <output_root>/modules/<module_id>/node-results/project-architecture/`. Exact filenames and downstream trigger role: [output-contract.md](../output-contract.md) § Per-module dispatch and dimensions. Out-of-path artifacts invalidate package `P2`.
+
+## Output Files And Contents
+
+- `project_architecture.json`: machine-routable architecture/ecosystem artifact containing build/SDK configuration, module topology, detected patterns with confidence, layer roles, dependency ecosystem, Jetpack usage, DI setup, platform services, boundary violations/hybrids, migration constraints, cross-module dependencies, assumptions, and evidence paths.
+- `project_architecture.md`: agent-readable architecture handoff containing build/SDK configuration, project topology overview, detected patterns + confidence, layer/role mapping, dependency + Jetpack inventory, DI setup, persistence/background/platform-service usage, generated tooling, dependency direction notes, legacy hybrid patterns/risks, migration constraints, and unknowns.
 
 ## Inline Persona for Teammate
 
@@ -139,7 +146,7 @@ INPUTS YOU WILL RECEIVE:
 - optional jetbrains MCP context (modules / dependencies / repositories): {MCP_CONTEXT}
 
 HANDLER (how you process):
-1. Stay inside module_scope; record dependencies on other modules as cross_module_dependencies
+1. Stay inside module_scope; record dependencies on other modules as cross_module_dependencies with target_module_id and source_paths — these feed global/cross_module_architecture.* during Leader integration
    without analyzing those target modules here.
 2. Inspect build config (Gradle files, AGP, Kotlin, compile/min/target SDK, namespaces/app IDs,
    flavors, build types, version catalogs, buildSrc/convention plugins).
@@ -156,8 +163,8 @@ HANDLER (how you process):
 9. Identify legacy traits and migration/onboarding implications.
 
 OUTPUTS (write under output_dir, exact names):
-- project_architecture.json
-- project_architecture.md
+- project_architecture.json (machine artifact: build config, topology, patterns, layers, dependencies, platform/generated constraints, evidence)
+- project_architecture.md (agent handoff: architecture/ecosystem tables, risks, migration constraints, unknowns)
 
 RETURN TO CONTROLLER (exactly this shape, no preamble):
 {