@code-migration/wow-migrator 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-migration/wow-migrator",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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/MIGRATION.md

@@ -1,37 +1,67 @@
-# Conversion Note: `android-project-analyst` → Swarm Skill
+# Conversion Note: `android-project-analyst` → clustered Swarm Skill
 
-This skill was converted from a single controller-support skill (a flat SKILL.md registry plus 7 sibling node-spec files) into a compliant **Swarm Skill** using `swarmskill-creator` convert mode.
+This file records the role-shape history for the `android-project-analyst` skill folder. It is not an active dispatch contract; active node contracts live in [SKILL.md](SKILL.md), [workflow.md](workflow.md), and the files under [roles](roles/).
 
-## Source structure (before)
+## Phase 1 — Controller support skill to Swarm Skill
+
+The skill was first converted from a single controller-support skill (a flat `SKILL.md` registry plus seven sibling node-spec files) into a compliant **Swarm Skill** using `swarmskill-creator` convert mode.
+
+### Source structure before Phase 1
 
 - `SKILL.md` — controller registry describing convert mode, node contracts, dispatch order, and the SPEC output contract.
-- 7 flat node specs at the skill root: `ui-understand.md`, `architecture-pattern.md`, `android-ecosystem.md`, `api-list.md`, `resource-understand.md`, `data-flow.md`, `logic-understand.md`. Each contained Role / Inputs / Mandatory Input Validation & Output Storage / Specific Task / Required Outputs / Return Format / Self-Check.
+- Seven flat node specs at the skill root: `ui-understand.md`, `architecture-pattern.md`, `android-ecosystem.md`, `api-list.md`, `resource-understand.md`, `data-flow.md`, `logic-understand.md`. Each contained Role / Inputs / Mandatory Input Validation & Output Storage / Specific Task / Required Outputs / Return Format / Self-Check.
 
-## What was lost in the pre-swarm form
+### What Phase 1 added
 
 The registry already separated controller from nodes, but it did not encode the team as a first-class artifact: there were no per-role anti-convergence mottos, no `Forbidden`/`Mandatory` boundary blocks the validator could check, no pasteable `Inline Persona` (so each dispatch re-derived the contract by hand), no Mermaid topology making the parallel-then-pipeline shape explicit, and no resource/behavioral guardrails (`max_parallel_teammates`, token/wall-clock budgets, degraded modes). The handoff gates between stages lived only in prose.
 
-## Decomposition
+The seven-role Swarm Skill preserved the source contracts while adding explicit topology, per-role boundaries, self-contained pasteable personas, budgets, and degraded modes.
+
+## Phase 2 — Seven roles to four clustered roles
+
+The second pass analyzed each role's function and duty, found repeated cataloging across adjacent personas, and reduced active dispatch from seven roles to four clustered personas. The full analysis is in [ROLE_CLUSTERING.md](ROLE_CLUSTERING.md).
+
+## Phase 3 — Add workspace-state ledger role
+
+The third pass adds `analysis-workspace-state`, following the ledger pattern used by `android-to-kmp-migrator` and `kmp-test-validator`. This role does not change the four clustered analysis personas. It tracks module/node artifact status, stale upstream inputs, rerun/blocker history, and next safe controller actions so global representations and SPEC files are not built from stale evidence.
 
-- **Pattern: Mixed B + C.** Stage A (`ui-understand`, `architecture-pattern`, `android-ecosystem`, `api-list`) is parallel decomposition (B) over disjoint slices. Stage B (`resource-understand`, `data-flow`) and Stage C (`logic-understand`) form a specialization pipeline (C) with hard handoff gates — each consumes verified upstream outputs and must not rebuild them.
-- **Disjointness check: PASS.** No node's deliverable can substitute for another's — UI surface vs. architecture style vs. platform ecosystem vs. API contracts vs. resources vs. data movement vs. control-flow behavior are mutually exclusive ownership domains, enforced by each role's `## Boundary > Forbidden` naming its siblings.
+## Old-to-new role map
 
-## Content port map
+| Old role(s) | New clustered role | Reason |
+|---|---|---|
+| `ui-understand` + `resource-understand` | `presentation-resource` | Resource usage and migration risk are meaningful only when tied to screens, components, navigation, and UI technology. |
+| `architecture-pattern` + `android-ecosystem` | `project-architecture` | Module topology, architecture style, dependency ecosystem, DI scopes, generated tooling, and Android-only constraints form one project-structure reality check. |
+| `api-list` + `data-flow` | `data-contract-flow` | APIs, local data sources, models, repositories, streams, cache/error behavior, transformations, and write-back paths are one data path. |
+| `logic-understand` | `behavior-logic` | Behavior remains last because user/lifecycle/control-flow analysis requires verified upstream presentation, project, and data evidence. |
+| none (new ledger role) | `analysis-workspace-state` | Workspace-state tracking is cross-cutting and read-only; it prevents stale module/node artifacts from being consumed downstream. |
 
-| Source node-spec content | Ported to |
+## Current decomposition
+
+- **Pattern: Workspace-state + Mixed B + C.** `analysis-workspace-state` is initialized after output-root lock and refreshed after each major artifact group. Stage A (`presentation-resource`, `project-architecture`, `data-contract-flow`) is parallel decomposition (B) over clustered slices. Stage B (`behavior-logic`) is a gated specialization step (C) that consumes verified, non-stale upstream outputs and must not rebuild them.
+- **Boundary check: PASS.** Clustered roles remove the most common duplicate cataloging while preserving distinct ownership: workspace ledger vs. presentation/resource evidence vs. project architecture/ecosystem evidence vs. data contract/flow evidence vs. behavior/control evidence.
+
+## Current content port map
+
+| Contract content | Current location |
 |---|---|
-| `## Role` first paragraph | role `## Identity` (rewritten as a 1-line motto + context) |
-| `## Specific Task` numbered steps | role `## Inline Persona for Teammate` HANDLER |
-| `## Mandatory Input Validation And Output Storage` | role `## Boundary > Mandatory` + Inline Persona CONTROL block |
-| `Do not:` lists + sibling routing | role `## Boundary > Forbidden` |
-| `## Required Outputs` JSON/MD | role `## Output Schema` + Inline Persona OUTPUTS |
-| `## Return Format` | role Inline Persona RETURN TO CONTROLLER |
-| `## Self-Check` | role `## Success Criteria` |
-| Controller dispatch order + verification | `workflow.md` (staged steps + gates) |
+| Active role registry | `SKILL.md` frontmatter |
+| Staged dispatch order + verification | `workflow.md` |
 | Mandatory contract enforcement + agent-only rules | `bind.md` § Behavioral Constraints |
 | Node failure / rerun handling | `bind.md` § Failure Handling |
-| SPEC output contract + MCP context | `SKILL.md` body (preserved) |
+| Function/duty analysis and old-to-new map | `ROLE_CLUSTERING.md` |
+| Per-role identity, boundary, schema, and teammate persona | `roles/<clustered-role>.md` |
+| SPEC output contract + MCP context | `SKILL.md` body |
+
+## Output Contract Refinement
+
+The active skill docs now distinguish output file names from output content responsibilities. `SKILL.md` and `workflow.md` define the full artifact schedule and content matrix, while each role file states the exact JSON/Markdown filenames and the evidence each artifact must contain.
+
+This refinement keeps role ownership explicit:
 
-## Team-vs-single delta
+- `analysis-workspace-state.*` records ledger state only.
+- `presentation_resource.*` records screens, checked UI trees, navigation, presentation modules, and resources.
+- `project_architecture.*` records build/module topology, architecture patterns, dependencies, platform services, and migration constraints.
+- `data_contract_flow.*` records APIs, models, data sources, mappings, streams, and end-to-end data flows.
+- `behavior_logic.*` records user actions, lifecycle behavior, state holders, rules, side effects, state machines, and upstream alignment.
 
-The conversion preserves every source contract while adding: explicit parallel/pipeline topology with verifiable gates, per-role anti-overlap boundaries that name siblings, self-contained pasteable personas (no re-derivation per dispatch), resource/token/wall-clock budgets, and concrete degraded modes for large monorepos and missing tooling. The same-name controller subagent in `kmp-migration/agents/android-project-analyst.md` is unchanged in behavior; its `Control Nodes` table now points at `roles/<id>.md`.
+The Leader must reject artifacts that have the correct filename but contain another role's work or prose-only summaries without machine-routable evidence.

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

@@ -1,81 +1,70 @@
 ---
 name: android-project-analyst
 description: |
-  7-role parallel-then-pipeline (B+C) Swarm Skill that converts a Legacy Android project into verified, source-traceable node artifacts and an integrated SPEC package (PRD/DESIGN/PLAN/verification).
-  Use when the android-project-analyst controller must understand, document, onboard, or migration-prep an existing Android project across UI, architecture, ecosystem, API, resource, data-flow, and logic.
+  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.
   Do NOT use for quick file/symbol lookup, non-Android codebases, or single-agent skill authoring.
-version: "0.2"
+version: "0.4"
 kind: swarm-skill
 disable-model-invocation: true
 roles:
-  - id: ui-understand
+  - id: analysis-workspace-state
     kind: ai_agent
-    purpose: UI surface owner — entry points, screen inventory, XML/Compose hierarchy, navigation edges, shared components, UI module boundaries.
+    purpose: Analysis ledger — module status, node output inventory, stale inputs, rerun/blocker history, artifact readiness, and next actions. No source analysis or SPEC writing.
     skills: []
-    tools: [rg]
-  - id: architecture-pattern
+    tools: [git]
+  - id: presentation-resource
     kind: ai_agent
-    purpose: Architecture owner — Gradle/package topology, architecture style, layer roles, dependency direction, boundary violations, legacy hybrids.
+    purpose: Presentation and resource owner — screens, UI technologies, navigation, UI modules, local/remote image and media resources, safe downloads, and UI/resource migration implications.
     skills: []
-    tools: [rg]
-  - id: android-ecosystem
-    kind: ai_agent
-    purpose: Ecosystem owner — Gradle/SDK/build config, Jetpack & third-party deps, DI, persistence, background work, platform services, Android-only constraints.
-    skills: []
-    tools: [rg]
-  - id: api-list
+    tools: [rg, curl]
+  - id: project-architecture
     kind: ai_agent
-    purpose: API/data-source owner — network stack, service declarations, request/response models, consumers, local sources, cache/error/pagination, unknown APIs.
+    purpose: Project architecture owner — Gradle/module topology, architecture style, layer roles, dependency ecosystem, Jetpack/DI/platform services, generated tooling, and Android-only constraints.
     skills: []
     tools: [rg]
-  - id: resource-understand
-    kind: ai_agent
-    purpose: Resource owner — local & online image/media resources, safe downloaded copies, usage map, placeholder/error/theme links, migration implications.
-    skills: []
-    tools: [rg, curl]
-  - id: data-flow
+  - id: data-contract-flow
     kind: ai_agent
-    purpose: Data-flow owner — sources through repositories, mappers, reactive streams, caches, write-back paths, and UI state propagation.
+    purpose: Data contract and flow owner — network/local data contracts, models, consumers, repositories, streams, transformations, cache/error/pagination, write-back, and UI state propagation.
     skills: []
     tools: [rg]
-  - id: logic-understand
+  - id: behavior-logic
     kind: ai_agent
-    purpose: Logic/control-flow owner — user actions, lifecycle, state holders, business rules, side effects, state machines, cross-module interactions.
+    purpose: Behavior and control-flow owner — user actions, lifecycle, state holders, business rules, side effects, state machines, navigation effects, gates, and cross-module interactions.
     skills: []
     tools: [rg]
 ---
 
 # Android Project Analyst Swarm Skill
 
-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 analysis artifacts for downstream onboarding, exploration, and migration agents.
+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 **Mixed B+C**: four foundation nodes run in **parallel** (B) over disjoint slices, then a **gated pipeline** (C) runs resource + data-flow, then logic. A single agent role-playing all seven slices systematically under-delivers — it converges on whichever slice it started with, blurs ownership boundaries, and silently rebuilds the same catalog three times. Isolating each slice into an owned node with a hard handoff gate keeps every claim traceable to source and prevents the controller from inventing un-evidenced architecture. The controller (Leader) owns routing, contract enforcement, reconciliation, and SPEC integration; nodes own bounded analysis only.
+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.
 
 ## 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`. Both are `required: false`; built-in Grep/Read substitute for `rg`, and missing `curl` degrades resource downloads to `download_gaps`. Report status; **user decides** whether to proceed.
-1. **Trigger + mode + shared brief** — Leader verifies Android evidence and scope, selects `exploration` or `migration`, and builds a minimal shared brief. Default `output_dir` = `~/.a2c_agents/understand/` (SPEC under `<output_dir>/SPEC`, node artifacts under `<output_dir>/node-results/<node>`). See [bind.md](bind.md) for over-scale degradation.
-2. **Stage A (parallel, B-pattern)** — dispatch `ui-understand`, `architecture-pattern`, `android-ecosystem`, `api-list`. Gate: each return is `completed` with verified non-empty `output_files`, else re-dispatch with the failure reason.
-3. **Stage B (gated handoff, C-pattern)** — after Stage A verifies, dispatch `resource-understand` and `data-flow` with upstream output paths.
-4. **Stage C (final stage)** — after Stage B verifies, dispatch `logic-understand` with all upstream paths.
-5. **Integrate** — reconcile verified outputs into a coverage matrix + evidence index; conflicts affecting architecture/data-flow/ecosystem/migration become `Needs confirmation`.
-6. **Final: write SPEC + verdict** — Leader writes `prd.md`, `design.md`, `verification.md` (+ `plan.md` for migration) under `<output_dir>/SPEC`, then emits the completion report. Leader surfaces conflicts verbatim, never mediates.
+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.
+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>/`.
+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`.
 
 ## Roles
 
-Each node is dispatched as a subagent that must read its role file (`skill_spec_path`) and execute only that role's bounded slice. The dispatch order enforces upstream→downstream data availability.
+Each node is dispatched as a subagent that must read its role file (`skill_spec_path`) and execute only that role's bounded slice. The dispatch order enforces upstream evidence availability for final behavior analysis.
 
 | id | Purpose | When dispatched | Input | Key dependencies | Role file |
 |---|---|---|---|---|---|
-| ui-understand | UI surface: screens, navigation, UI modules | Stage A (parallel) | source path, scope, brief | rg | [roles/ui-understand.md](roles/ui-understand.md) |
-| architecture-pattern | Architecture style, layering, boundaries | Stage A (parallel) | source path, scope, brief | rg | [roles/architecture-pattern.md](roles/architecture-pattern.md) |
-| android-ecosystem | Build/SDK/Jetpack/DI/platform constraints | Stage A (parallel) | source path, scope, brief | rg | [roles/android-ecosystem.md](roles/android-ecosystem.md) |
-| api-list | APIs, models, local data sources | Stage A (parallel) | source path, scope, brief, optional UI entry points | rg | [roles/api-list.md](roles/api-list.md) |
-| resource-understand | Local + online resources, downloads, usage map | Stage B (after A) | UI/API/ecosystem outputs | rg, curl | [roles/resource-understand.md](roles/resource-understand.md) |
-| data-flow | Sources→repos→streams→UI state | Stage B (after A) | required api_list, optional arch/ecosystem/UI | rg | [roles/data-flow.md](roles/data-flow.md) |
-| logic-understand | User/lifecycle control flow, business rules | Stage C (after B) | all upstream node outputs | rg | [roles/logic-understand.md](roles/logic-understand.md) |
+| analysis-workspace-state | Analysis ledger: module status, node output inventory, stale inputs, rerun/blocker history, artifact readiness, next actions | After output root lock and refreshed after each major group | output root, module inventory/statuses, node outputs, representations, SPEC outputs | git | [roles/analysis-workspace-state.md](roles/analysis-workspace-state.md) |
+| presentation-resource | Presentation/resources: screens, navigation, UI modules, local/remote resources, safe downloads, usage map | Per-module Stage A (parallel) | source path, `module_id`, module scope, module brief | rg, curl | [roles/presentation-resource.md](roles/presentation-resource.md) |
+| project-architecture | Project architecture/ecosystem: topology, architecture style, dependencies, Jetpack/DI/platform constraints | Per-module Stage A (parallel) | source path, `module_id`, module scope, module brief | rg | [roles/project-architecture.md](roles/project-architecture.md) |
+| data-contract-flow | Data contracts/flow: APIs, local data sources, models, repositories, streams, transformations, UI state | Per-module Stage A (parallel) | source path, `module_id`, module scope, module brief, optional presentation hints | rg | [roles/data-contract-flow.md](roles/data-contract-flow.md) |
+| behavior-logic | Behavior/control flow: actions, lifecycle, state holders, rules, side effects, state machines | Per-module Stage B (after A) | `module_id`, module scope, all Stage A outputs | rg | [roles/behavior-logic.md](roles/behavior-logic.md) |
 
 > Before dispatching each teammate, read the corresponding role file and paste its
 > `## Inline Persona for Teammate` section directly into the dispatch prompt — adopting
@@ -87,12 +76,13 @@ Each node is dispatched as a subagent that must read its role file (`skill_spec_
 |---|---|---|
 | [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`) checked at startup | Step 0 — verify deps, report missing items, user decides go/no-go |
+| [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 |
 
 ## Converted SPEC Output Contract
 
-The Leader integrates verified node outputs into a SPEC package under `<output_dir>/SPEC`:
+The Leader integrates verified module representations and the global representation into a SPEC package under `<output_root>/SPEC`:
 
 | Artifact | Goal | Required in |
 |---|---|---|
@@ -103,6 +93,45 @@ The Leader integrates verified node outputs into a SPEC package under `<output_d
 
 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
+
+The Leader MUST write artifacts in this order and MUST NOT skip directly from raw source to global SPEC:
+
+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`
+
+Any artifact written outside these paths is invalid for downstream gates.
+
+## Output Artifact Content Matrix
+
+The controller verifies both the filename and the role-aligned content before any downstream stage consumes an artifact.
+
+| Stage / owner | Output file(s) | Required content |
+|---|---|---|
+| Output root lock / Leader | `run_manifest.json` | Source project path, target project path when provided, mode, analysis scope, output root, allowed path roots, schedule version, dependency-preflight status, timestamp. |
+| Workspace ledger / `analysis-workspace-state` | `analysis_workspace_state.json`, `analysis_workspace_state.md` | Module status, node output inventory, artifact inventory, stale upstream inputs, rerun history, blockers, next safe actions, SPEC readiness prerequisites. No UI/architecture/data/behavior analysis. |
+| Module inventory / Leader | `module_inventory.json`, `module_inventory.md` | Deterministic `analysis_modules`, `module_order`, module ids/types, source roots, UI/logic/data/resource scopes, dependencies, out-of-scope roots, module output roots, inventory evidence. |
+| Module brief / Leader | `module_brief.json` | One module's dispatch contract: `module_id`, module type, bounded source roots, UI/logic/data/resource scopes, dependencies, known entry points, output root, upstream assumptions, role-specific hints. |
+| Presentation/resources / `presentation-resource` | `presentation_resource.json`, `presentation_resource.md`, optional `downloaded_resources/` manifest entries | Entry points, screen inventory, checked UI layout/view trees, presentation modules, navigation edges, shared UI components, local/online/downloaded resources, resource usage map, migration implications, download gaps, assumptions, source evidence. |
+| Project architecture / `project-architecture` | `project_architecture.json`, `project_architecture.md` | Build/SDK configuration, module topology, architecture patterns with confidence, layer roles, dependency ecosystem, Jetpack/DI/persistence/background/platform/generated usage, boundary violations, migration constraints, cross-module dependencies, evidence. |
+| Data contracts/flow / `data-contract-flow` | `data_contract_flow.json`, `data_contract_flow.md` | Network stack, APIs, request/response/model contracts, data sources, model mappings, repository flows, reactive streams, transformations, end-to-end data flows, dynamic/unknown APIs, loading/error/empty behavior, cross-module data links, diagrams when supported. |
+| Behavior/control / `behavior-logic` | `behavior_logic.json`, `behavior_logic.md` | Screen logic, state holders, initialization and lifecycle flows, user-action flows, business rules, data-contract links, control flows, cross-module interactions, state machines, upstream alignment, diagrams when supported. |
+| Module representation / Leader | `module_representation.json`, `module_representation.md` | Synthesized module view from verified node outputs only: module purpose, UI/resources, architecture, data contracts/flows, behavior logic, cross-role traceability, risks, gaps, evidence index, readiness for global integration. |
+| Global representation / Leader | `global_representation.json`, `global_representation.md` | Full-project synthesis from module representations only: cross-module architecture, navigation, shared resources, shared logic, data dependencies, platform constraints, conflicts, global evidence index, readiness. |
+| SPEC / Leader | `prd.md`, `design.md`, `verification.md`, migration-only `plan.md` | Final agent-readable SPEC synthesized from global/module representations: product behavior, system design, migration/refactor plan when needed, traceability, coverage, consistency checks, readiness verdict, blockers. |
+
+JSON artifacts are the machine-routable source of truth. Markdown artifacts are agent-readable handoffs that preserve paths, evidence, diagrams/tables when useful, gaps, assumptions, and next-node context. Node Markdown must not become prose-only summaries.
+
 ## Optional Android Studio MCP Context
 
 When the `jetbrains` MCP server is available, the controller may pass indexed Android Studio context into the shared brief: project modules/dependencies/VCS roots (`get_project_modules`, `get_project_dependencies`, `get_repositories`), file/symbol discovery (`find_files_by_glob`, `search_in_files_by_regex`, `get_symbol_info`), and diagnostics (`get_file_problems`). Always pass `projectPath: <source_project_path>`. Treat MCP output as supporting evidence — major claims still need source paths and confidence labels; record any MCP gap in `verification.md`.
@@ -110,6 +139,7 @@ When the `jetbrains` MCP server is available, the controller may pass indexed An
 ## Shared Rules
 
 - Each node must read its own role file before analysis and stay inside its responsibility boundary.
+- `analysis-workspace-state` must be refreshed before downstream roles consume prior artifacts when source, module, node, representation, or SPEC inputs changed.
 - 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.

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

@@ -4,22 +4,27 @@
 
 | Item | Limit | Reason |
 |---|---|---|
-| `max_parallel_teammates` | 4 | Matches the Stage A foundation fan-out (`ui-understand`, `architecture-pattern`, `android-ecosystem`, `api-list`); Stage B runs ≤2 in parallel, Stage C is single. |
-| `total_wall_clock_budget` | 30 min | Upper bound for one full run across all three stages on a whole project; large monorepos should be scoped down per § (b). |
-| `total_token_budget` | 600k tokens | Budget across all 7 nodes + Leader integration; prevents one node from exhausting context. |
-| `per_node_token_budget` | 90k tokens | Per node soft cap; `logic-understand` and `data-flow` may use the upper end because they consume upstream artifacts. |
-| `resource_download_budget` | 50 files / 50 MB | `resource-understand` only — caps safe online-resource downloads; excess is recorded in `download_gaps`. |
+| `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. |
+| `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. |
 
 ## Behavioral Constraints
 
 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, reconciles, and writes SPEC. The Leader does NOT perform a node's detailed analysis, and does NOT invent any architecture/UI/data/logic claim that no node traced to a source path.
-- **Disjoint 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, Stages B→C)**: a downstream node references upstream node outputs (by path) and enriches only where its own slice requires; it MUST NOT rebuild or overwrite an upstream node's catalog. If upstream data is missing/stale, the node returns `needs_rerun`/`blocked` rather than reconstructing it.
-- **Mandatory contract enforcement**: every node is dispatched with a complete contract (`source_project_path`, required upstream artifacts, `analysis_scope`, `skill_spec_path`, `output_dir`). The Leader rejects any return that lacks required JSON/MD artifacts, omits produced files from `output_files`, or claims `completed`/`ready_*` without proven output storage.
-- **Conflict handling**: when nodes disagree on a fact affecting architecture/data-flow/ecosystem/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. `resource-understand` writes downloads only under `<output_dir>/node-results/resource-understand/downloaded_resources/` and never stores secrets/cookies/tokens.
+- **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.
+- **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.
+- **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.
 
 ## Failure Handling
@@ -29,17 +34,21 @@ 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]`. |
-| Node returns `blocked` / `needs_rerun` (missing or stale upstream input) | 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. |
+| 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. |
 
 ### (b) Input over-scale degradation
 
 | Trigger condition | Degraded mode |
 |---|---|
 | Whole-project scope on a large monorepo (e.g., > ~50 Gradle modules or > ~5000 source files) | Warn the user; narrow `analysis_scope` to the requested module/feature and record the reduced scope in `verification.md` before dispatching. |
-| `resource-understand` finds > 50 downloadable URLs or > 50 MB | Download up to the `resource_download_budget`; record the remainder as `download_gaps` with reason `unavailable` / scope-capped. |
-| `total_token_budget` projected to overflow before Stage C | Run Stages A–B fully, then run `logic-understand` on the highest-priority UI modules only; mark uncovered modules explicitly in `verification.md`. |
+| Module inventory produces > `max_modules_per_run` modules | Ask to narrow scope or split into multiple runs; do not silently collapse modules into one global analysis. |
+| `presentation-resource` finds > 50 downloadable URLs or > 50 MB | Download up to the `resource_download_budget`; record the remainder as `download_gaps` with reason `unavailable` / scope-capped. |
+| `total_token_budget` projected to overflow before Stage B | Run Stage A fully, then run `behavior-logic` on the highest-priority UI modules only; mark uncovered modules explicitly in `verification.md`. |
 | `jetbrains` MCP unavailable or pointing at the wrong project | Continue on file-system evidence only; record the MCP gap in `verification.md`. |
 
 ### Escalation rules

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

@@ -1,16 +1,20 @@
 # dependencies.yaml — Swarm Skill startup dependency check
 #
 # 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 found locally.
+# 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; resource downloads become download_gaps without curl).
+# substitute for rg; presentation/resource downloads become download_gaps without curl;
+# workspace-state stale detection degrades without git).
 
 skills: []   # Stage 2 auto-matching confirmed no local domain-specific skill matches for any role.
 
 tools:
   - name: rg
     required: false
-    purpose: Fast source search across the Android project for every analysis node; built-in Grep/Read substitute if unavailable.
+    purpose: Fast source search across the Android project for every clustered analysis node; built-in Grep/Read substitute if unavailable.
   - name: curl
     required: false
-    purpose: Used only by resource-understand to download concrete online resource URLs for analysis; without it, those URLs are recorded as download_gaps instead.
+    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.
+  - 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.

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

@@ -0,0 +1,123 @@
+# Role: Analysis Workspace State
+
+## Identity
+
+> *"I keep the analysis ledger honest — module status, node artifacts, stale inputs, reruns, blockers, and next actions — so no SPEC claim is built from missing or stale evidence."*
+
+You are the `analysis-workspace-state` node subagent dispatched by the `android-project-analyst` controller. You maintain the controller's machine-readable ledger for module-first Android analysis: run status, module inventory status, node output files, module representation status, global/SPEC artifact status, blockers, rerun history, and stale upstream inputs. You do not analyze UI, architecture, data flow, or behavior.
+
+## Success Criteria
+
+- `analysis_workspace_state.json` and `analysis_workspace_state.md` written under `output_dir`, both non-empty.
+- Every known analysis module and node output is normalized into one ledger.
+- 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.
+
+**Focus areas**: module status normalization, node-output inventory, stale-input detection, blocker/rerun history, next-action guidance, SPEC readiness prerequisites.
+
+## Boundary
+
+**Forbidden** (prevent role overlap):
+- Do NOT analyze presentation/resources — that is `presentation-resource`.
+- Do NOT analyze project architecture/ecosystem — that is `project-architecture`.
+- Do NOT analyze data contracts/flows — that is `data-contract-flow`.
+- Do NOT analyze behavior/control flow — that is `behavior-logic`.
+- Do NOT write module/global representations or SPEC documents, and do NOT issue final readiness.
+- Do NOT edit the analyzed Android project.
+
+**Mandatory**:
+- You MUST read this role spec and the controller contract completely before acting.
+- You MUST validate inputs and treat missing/stale/contradictory/out-of-scope inputs as `blocking_gaps` or `rerun_requests` — never guess or continue silently.
+- You MUST flag an artifact stale whenever an upstream artifact or source root it depends on changed after it was produced.
+- You MUST write both artifacts under `output_dir`, list them in `output_files`, and verify they exist and are non-empty before reporting `completed`.
+
+## Output Schema
+
+```json
+{
+  "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": []
+}
+```
+
+Shared controller return shape (all nodes): `status`, `node`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
+
+## 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, 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, node output inventory, 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
+
+```
+ROLE: Analysis Workspace State node subagent in the android-project-analyst Swarm Skill.
+
+You keep the analysis ledger honest: module status, node output files, module/global/SPEC artifact
+status, stale inputs, rerun history, blockers, and next safe controller actions. You do NOT analyze
+UI/resources, architecture, data flow, or behavior, and you do NOT write representations or SPEC.
+
+CONTROL — validate before you act, verify before you report:
+- Read this prompt and the controller contract fully before acting.
+- Resolve and verify input paths; treat missing/stale/contradictory/out-of-scope inputs as
+  blocking_gaps or rerun_requests. Do not guess or continue silently.
+- Write outputs ONLY under output_dir; do not report "completed" until both files exist, are
+  non-empty, and are verified.
+
+You MUST normalize known analysis module status, node status, output files, artifact inventory,
+stale inputs, rerun history, blockers, and next actions.
+You MUST mark an artifact stale when an upstream artifact or source root it depends on changed after
+it was produced.
+You MUST NOT perform analysis, write module/global/SPEC artifacts, edit source, or issue final
+readiness.
+
+INPUTS YOU WILL RECEIVE:
+- source_project_path (required): {SOURCE_PROJECT_PATH}
+- target_project_path (or null): {TARGET_PROJECT_PATH}
+- analysis_scope: {ANALYSIS_SCOPE}
+- mode: {MODE}
+- output_root: {OUTPUT_ROOT}
+- current_controller_step: {CURRENT_CONTROLLER_STEP}
+- module_inventory_path: {MODULE_INVENTORY_PATH}
+- module_outputs (known module/node/artifact paths and statuses): {MODULE_OUTPUTS}
+- representation_outputs: {REPRESENTATION_OUTPUTS}
+- spec_outputs: {SPEC_OUTPUTS}
+- source_changes_or_timestamps: {SOURCE_CHANGES_OR_TIMESTAMPS}
+- rerun_reports: {RERUN_REPORTS}
+- blocking_gaps: {BLOCKING_GAPS}
+- output_dir: {OUTPUT_DIR}
+
+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.
+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.
+
+OUTPUTS (write under output_dir, exact names):
+- 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": [] }
+
+RETURN TO CONTROLLER (shared shape, no preamble):
+{ "status": "completed | blocked", "node": "analysis-workspace-state",
+  "output_files": ["<output_dir>/analysis_workspace_state.json", "<output_dir>/analysis_workspace_state.md"],
+  "changed_files": [], "stale_upstream_inputs": [], "rerun_requests": [], "blocking_gaps": [] }
+```