@harmonyos-arkts/d2h 0.1.2 → 0.1.5

package/skills/d2h-utg-static-generate/scripts/generate.py

@@ -0,0 +1,499 @@
+#!/usr/bin/env python3
+"""Project read-only AppGraph facts and apply source-grounded discovery overlays."""
+from __future__ import annotations
+
+import argparse
+import copy
+import hashlib
+import json
+import shutil
+import subprocess
+import sys
+from xml.parsers import expat
+from pathlib import Path
+
+SHARED = Path(__file__).resolve().parents[2] / 'd2h-utg-ai-generate' / 'scripts'
+sys.path.insert(0, str(SHARED))
+from utg_common import UtgError, atomic_write_json, load_json, normalize_location, normalize_facts, build_click_paths
+
+
+def digest(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False,
+                                     separators=(',', ':')).encode()).hexdigest()
+
+
+def source_digest(root):
+    extensions = {'.kt', '.java', '.xml', '.gradle', '.kts', '.json', '.properties'}
+    ignored = {'.git', '.migration', '.appgraph', '.codegraph', '.codegraph-appgraph', 'node_modules', 'build', '.gradle'}
+    records = []
+    for p in sorted(root.rglob('*')):
+        relative = p.relative_to(root)
+        if p.is_file() and not any(part in ignored for part in relative.parts) and p.suffix in extensions:
+            records.append((relative.as_posix(), hashlib.sha256(p.read_bytes()).hexdigest()))
+    return digest(records)
+
+
+def project_legacy(graph, root):
+    if graph.get('schemaVersion') != 1 or graph.get('platform') != 'android':
+        raise UtgError('expected Android AppGraph schemaVersion=1')
+    raw_nodes = graph.get('nodes', [])
+    ui = graph.get('uiComponents') or {}
+    all_nodes = raw_nodes + ui.get('nodes', [])
+    if len({n['id'] for n in all_nodes}) != len(all_nodes):
+        raise UtgError('duplicate AppGraph node identity')
+    index = {n['id']: n for n in all_nodes}
+    diagnostics, nodes, edges = [], {}, []
+
+    def issue(subject, reason, evidence=None):
+        finding = {'subject': subject, 'reason': reason, 'evidence': evidence}
+        finding['id'] = 'review:' + digest(finding)[:20]
+        diagnostics.append(finding)
+
+    def location(obj):
+        refs = obj.get('evidence') or [obj.get('platformRef') or obj.get('origin') or {}]
+        if isinstance(refs, dict):
+            refs = [refs]
+        for ref in refs:
+            if not isinstance(ref, dict):
+                continue
+            # Manifest facts carry a symbol but older producers omit a line.
+            # Resolve that exact XML declaration, never a guessed class-name hit.
+            if ref.get('file', '').endswith('.xml') and ref.get('symbol') and not ref.get('line'):
+                path = (root / ref['file']).resolve()
+                if path.is_relative_to(root) and path.is_file():
+                    parser = expat.ParserCreate()
+                    matches = []
+                    def start(tag, attrs):
+                        if attrs.get('android:name') == ref['symbol']:
+                            matches.append(parser.CurrentLineNumber)
+                    parser.StartElementHandler = start
+                    try:
+                        parser.Parse(path.read_bytes(), True)
+                        if len(matches) == 1:
+                            return normalize_location(f"{ref['file']}:{matches[0]}", root, 'XML declaration')
+                    except expat.ExpatError:
+                        pass
+            if ref.get('file') and ref.get('line'):
+                try:
+                    return normalize_location(f"{ref['file']}:{ref['line']}", root, 'AppGraph evidence')
+                except UtgError:
+                    pass
+        return None
+
+    kinds = {'compose': 'compose-route', 'activity': 'activity', 'fragment': 'fragment',
+             'dialog': 'dialog', 'dialog-fragment': 'dialog', 'sheet': 'sheet', 'bottom-sheet': 'sheet',
+             'menu': 'menu', 'voyager': 'voyager-screen'}
+    for raw in sorted(all_nodes, key=lambda n: n['id']):
+        if raw.get('kind') not in {'Screen', 'page'}:
+            continue
+        if raw.get('evidenceLevel') == 'candidate' or raw.get('platform', 'android') != 'android':
+            issue(raw['id'], 'candidate or non-Android page requires review')
+            continue
+        loc = location(raw)
+        if not loc:
+            issue(raw['id'], 'page has no valid source line evidence')
+            continue
+        attrs = raw.get('attrs') or {}
+        # Fine pages explicitly referencing the same Screen are aliases, not new screens.
+        alias = attrs.get('screenId')
+        if alias in nodes:
+            continue
+        nodes[raw['id']] = {'id': raw['id'], 'kind': kinds.get(raw.get('subtype'), 'page'),
+            'label': raw.get('name') or raw['id'], 'declared_at': loc,
+            'provenance': 'appgraph', 'status': 'static-only', 'expected': {}, 'widgets': [],
+            'extra': {'appgraph_id': raw['id'], 'appgraph_evidence': raw.get('evidence', []),
+                      'capture_policy': 'strict'}}
+    aliases = {n['id']: (n.get('attrs') or {}).get('screenId') for n in all_nodes
+               if (n.get('attrs') or {}).get('screenId') in nodes}
+    for alias in aliases:
+        nodes.pop(alias, None)
+    # A source page can carry the stable Screen ID even when that coarse Screen
+    # has no line evidence (notably a Manifest activity declaration).
+    for raw in all_nodes:
+        if raw.get('kind') != 'page' or raw['id'] not in nodes:
+            continue
+        screen_id = (raw.get('attrs') or {}).get('screenId')
+        if screen_id and screen_id not in nodes:
+            aliases[screen_id] = raw['id']
+    # Compose destination registrations may also produce a synthetic Screen at
+    # the NavHost file's first line. Prefer the unique source-backed page for
+    # the same Screen match key, preserving both IDs as aliases.
+    source_pages = {}
+    for raw in all_nodes:
+        attrs = raw.get('attrs') or {}
+        if raw.get('kind') == 'page' and attrs.get('classificationRule') == 'COMPOSE-SCREEN-AST' and raw['id'] in nodes:
+            source_pages.setdefault(attrs.get('screenMatchKey'), []).append(raw['id'])
+    for raw in all_nodes:
+        attrs = raw.get('attrs') or {}
+        if raw.get('kind') != 'Screen' or attrs.get('classificationRule') != 'compose.destination.register':
+            continue
+        match_key = raw.get('matchKey', '')
+        candidates = source_pages.get(match_key.removesuffix(':compose'), [])
+        if len(candidates) == 1 and candidates[0] != raw['id']:
+            aliases[raw['id']] = candidates[0]
+            nodes.pop(raw['id'], None)
+    relations = graph.get('edges', []) + ui.get('edges', [])
+    parent = {}
+    for e in relations:
+        if e.get('kind') in {'contains', 'hosts', 'includes', 'renders'}:
+            parent.setdefault(e['to'], set()).add(e['from'])
+
+    def owners(identity):
+        seen, result, queue = set(), set(), [identity]
+        while queue:
+            current = queue.pop()
+            if current in seen:
+                continue
+            seen.add(current)
+            current = aliases.get(current, current)
+            if current in index and index[current].get('kind') == 'AppEntry':
+                queue.append((index[current].get('attrs') or {}).get('screen'))
+                continue
+            if current in nodes:
+                result.add(current)
+            else:
+                queue.extend(parent.get(current, []))
+        return sorted(result)
+
+    for raw in all_nodes:
+        if raw.get('kind') == 'control':
+            own = owners(raw['id'])
+            if len(own) == 1:
+                nodes[own[0]]['widgets'].append({'id': raw['id'], 'name': raw.get('name'),
+                    'evidence': raw.get('evidence', []), 'attrs': raw.get('attrs', {})})
+            else:
+                issue(raw['id'], 'control owner missing or ambiguous', raw.get('evidence'))
+
+    def navigation(e, source, target, evidence):
+        src, dst = owners(source), owners(target)
+        loc = location(evidence)
+        if len(src) != 1 or len(dst) != 1 or not loc:
+            issue(e.get('id', source), 'navigation owner/target/evidence unresolved', evidence)
+            return
+        attrs = e.get('attrs') or {}
+        branch = e.get('branchCondition')
+        guard = attrs.get('guard')
+        if branch and branch.get('expression'):
+            guard = {'kind': 'source-branch', 'text': ('!(' + branch['expression'] + ')') if branch.get('branch') == 'else' else branch['expression']}
+        edges.append({'id': e.get('id') or 'appgraph:' + digest(e)[:20],
+            'source': src[0], 'target': dst[0],
+            'mechanism': attrs.get('mechanism') or 'appgraph-navigation',
+            'trigger': loc, 'confidence': e.get('confidence', 1), 'provenance': 'appgraph',
+            'status': 'static-only', 'guard': guard,
+            'args': {'appgraph_edge_id': e.get('id'), 'appgraph_attrs': attrs}})
+
+    for e in sorted(graph.get('edges', []), key=lambda e: e['id']):
+        if e.get('kind') == 'navigates_to':
+            attrs = e.get('attrs') or {}
+            navigation(e, e['from'], e['to'], {'evidence': attrs.get('evidence', []),
+                'platformRef': attrs.get('platformRef') or attrs.get('origin') or {}})
+    entries = {e['id']: e for e in graph.get('entryPoints', [])}
+    roots = set()
+    for raw in raw_nodes:
+        if raw.get('kind') == 'AppEntry' and raw.get('subtype') == 'launcher-activity':
+            roots.update(owners(raw['id']))
+    for entry in entries.values():
+        if entry.get('kind') == 'app-launch' and entry.get('resolution') == 'resolved':
+            roots.update(owners(entry.get('ownerRef') or entry.get('sourceRef')))
+    for trace in sorted(graph.get('callTraces', []), key=lambda t: t['id']):
+        entry = entries.get(trace.get('entryPointId'), {})
+        if entry.get('resolution') != 'resolved':
+            issue(trace.get('id'), 'entry unresolved; trace cannot establish navigation')
+            continue
+        for effect in trace.get('effects', []):
+            if effect.get('kind') == 'navigation':
+                targets = effect.get('targetRefs', [])
+                if len(targets) != 1:
+                    issue(effect.get('id'), 'navigation effect target missing or ambiguous', effect.get('origin'))
+                    continue
+                for target in targets:
+                    navigation(effect, entry.get('ownerRef') or entry.get('sourceRef'), target,
+                               {'platformRef': effect.get('origin') or {}})
+    for warning in graph.get('coverageWarnings', []):
+        issue('appgraph-coverage', warning.get('message'), warning.get('ref'))
+    if len(roots) != 1:
+        issue('root', 'exactly one proven app-launch page is required', sorted(roots))
+    connected = {e['source'] for e in edges} | {e['target'] for e in edges}
+    for node in nodes.values():
+        if node['id'] not in connected:
+            issue(node['id'], 'isolated page: inspect navigation registry and call sites')
+        issue(node['id'], 'arrival rules and executable selectors require source review')
+    return {'schema_version': 'd2h-utg-facts/v1',
+        'graph': {'app': graph.get('app', {}).get('name') or root.name,
+                  'package': graph.get('app', {}).get('packageName', ''),
+                  'architecture': 'appgraph/android', 'root': next(iter(roots)) if len(roots) == 1 else ''},
+        'nodes': sorted(nodes.values(), key=lambda n: n['id']),
+        'edges': sorted(edges, key=lambda e: (e['id'], e['source'], e['target'])),
+        'unresolved': diagnostics}
+
+
+def project(graph, root):
+    interaction = graph.get('interactionGraph')
+    if interaction is None:
+        return project_legacy(graph, root)
+    if interaction.get('schemaVersion') != 1:
+        raise UtgError('unsupported interactionGraph schemaVersion')
+    surfaces = interaction.get('surfaces', [])
+    if len({s['id'] for s in surfaces}) != len(surfaces):
+        raise UtgError('duplicate interaction surface identity')
+    bindings = interaction.get('controlBindings', [])
+    raw_index = {n['id']: n for n in (graph.get('uiComponents') or {}).get('nodes', [])}
+    projected = dict(graph, nodes=[{'id': s['id'], 'kind': 'Screen', 'name': s['name'],
+        'subtype': s['kind'], 'evidence': s.get('evidence', []),
+        **({'evidenceLevel': 'candidate'} if s.get('resolution') in {'ambiguous', 'unresolved'} else {}),
+        'attrs': {}} for s in surfaces],
+        edges=[], entryPoints=[], callTraces=[], uiComponents={'nodes': [], 'edges': []})
+    for binding in bindings:
+        original = raw_index.get(binding['controlRef'], {})
+        projected['uiComponents']['nodes'].append(dict(original, id=binding['id'], kind='control'))
+        projected['uiComponents']['edges'].append({'id': binding['id'], 'kind': 'contains',
+            'from': binding['surfaceId'], 'to': binding['id']})
+    for transition in interaction.get('transitions', []):
+        target = transition.get('target', {})
+        if transition.get('resolution') != 'resolved' or target.get('kind') != 'internal':
+            continue
+        attrs = {'evidence': transition.get('evidence', []), 'mechanism': transition['operation'],
+                 'supportingRefs': transition.get('supportingRefs', []),
+                 'actionRef': transition.get('actionRef'), 'arguments': transition.get('arguments', {})}
+        conditions = transition.get('conditions', [])
+        if conditions:
+            attrs['guard'] = {'kind': 'source-branch', 'text': ' && '.join(('!(' + c['expression'] + ')') if c.get('branch') == 'else' else '(' + c['expression'] + ')' for c in conditions), 'conditions': conditions}
+        projected['edges'].append({'id': transition['id'], 'kind': 'navigates_to',
+            'from': transition.get('sourceSurfaceId'), 'to': target['surfaceId'],
+            'confidence': transition.get('confidence', 1), 'attrs': attrs})
+    entries = [e for e in interaction.get('entries', [])
+               if e.get('kind') in {'app-launch', 'deep-link', 'external-entry'} and e.get('resolution') == 'resolved']
+    for entry in entries:
+        for identity in entry.get('surfaceIds', []):
+            projected['entryPoints'].append({'id': entry['id'], 'kind': 'app-launch',
+                'resolution': 'resolved', 'ownerRef': identity})
+    base = project_legacy(projected, root)
+    base['graph']['path_policy'] = 'source-executable-first'
+    interaction_entries = {e['id']: e for e in interaction.get('entries', [])}
+    for edge in base['edges']:
+        if edge['mechanism'] == 'navhost-start':
+            edge['args']['action'] = 'default'
+            continue
+        metadata = edge['args'].get('appgraph_attrs', {})
+        entry = interaction_entries.get(metadata.get('actionRef'), {})
+        applicable = [b for b in bindings if b['surfaceId'] == edge['source']
+                      and b['controlRef'] == entry.get('sourceRef')]
+        candidates = [s for b in applicable for s in b.get('selectorCandidates', [])
+                      if s.get('kind') == 'resource-id' and isinstance(s.get('value'), str)]
+        event = entry.get('event')
+        action = {'click': 'tap', 'onClick': 'tap', 'compose-click': 'tap',
+                  'long-click': 'long-press', 'onLongClick': 'long-press', 'compose-long-click': 'long-press'}.get(event)
+        if action and len(candidates) == 1:
+            edge['args'].update(action=action, selector={'resource_id': candidates[0]['value']},
+                                selector_evidence=candidates[0].get('evidence', []))
+    proven_ids = {n['id'] for n in base['nodes']}
+    root_ids = sorted({identity for entry in entries for identity in entry.get('surfaceIds', [])
+                       if identity in proven_ids})
+    # A logical root is a contract adapter for multiple source-proven entries,
+    # never an observed page. Unknown launch operands remain non-executable.
+    if len(root_ids) > 1 or (root_ids and any(e['kind'] != 'app-launch' for e in entries)):
+        logical_root = 'utg:entry-root'
+        if logical_root in proven_ids:
+            raise UtgError('reserved logical entry root identity collision')
+        anchor = next(n['declared_at'] for n in base['nodes'] if n['id'] in root_ids)
+        base['nodes'].append({'id': logical_root, 'kind': 'sentinel', 'label': 'Application entries',
+            'declared_at': anchor, 'provenance': 'appgraph', 'status': 'static-only',
+            'expected': {}, 'widgets': [], 'extra': {'capture_policy': 'strict', 'logical_entry': True}})
+        base['graph']['root'] = logical_root
+        base['graph']['entry_roots'] = root_ids
+        base['unresolved'] = [item for item in base['unresolved'] if item.get('subject') != 'root']
+        for entry in entries:
+            for identity in entry.get('surfaceIds', []):
+                if identity not in proven_ids:
+                    continue
+                launch = entry.get('launch') or {}
+                args = {'appgraph_entry_id': entry['id'], 'action': 'unresolved-entry',
+                        'evidence_role': 'entry-target-declaration', 'appgraph_entry_evidence': entry.get('evidence', [])}
+                if launch.get('action') == 'start-activity' and isinstance(launch.get('component'), str):
+                    args.update(action='start-activity', component=launch['component'])
+                elif launch.get('action') == 'deep-link' and isinstance(launch.get('uri'), str):
+                    args.update(action='deep-link', label=launch['uri'], label_source='source-uri')
+                if args['action'] == 'unresolved-entry':
+                    base['unresolved'].append({'id': 'entry-operands:' + entry['id'], 'subject': entry['id'],
+                        'reason': 'entry destination is known but source-proven intent or launch operands are missing',
+                        'evidence': entry.get('evidence', [])})
+                base['edges'].append({'id': 'utg:entry:' + entry['id'], 'source': logical_root,
+                    'target': identity, 'mechanism': 'deep-link' if entry['kind'] == 'deep-link' else 'app-launch-entry',
+                    'trigger': next(n['declared_at'] for n in base['nodes'] if n['id'] == identity),
+                    'confidence': 1, 'provenance': 'appgraph', 'status': 'static-only', 'args': args})
+    surface_index = {s['id']: s for s in surfaces}
+    for node in base['nodes']:
+        if node['id'] not in surface_index:
+            continue
+        surface = surface_index[node['id']]
+        node['extra'].update(source_refs=surface.get('sourceRefs', []),
+            host_surface_ids=surface.get('hostSurfaceIds', []), presentation=surface.get('presentation'))
+        if surface.get('presentation') == 'host-only':
+            node['kind'] = 'host-activity'
+    base['alignment'] = {'schema_version': 'd2h-appgraph-utg-alignment/v1',
+        'nodes': [{'utg_id': n['id'], 'source_refs': surface_index.get(n['id'], {}).get('sourceRefs', []),
+                   'mapping': 'surface-projection' if n['id'] in surface_index else 'logical-entry'} for n in base['nodes']],
+        'edges': [{'utg_id': e['id'], 'source_refs': e['args'].get('appgraph_attrs', {}).get('supportingRefs', [])
+                   or ([e['args']['appgraph_entry_id']] if 'appgraph_entry_id' in e['args'] else []),
+                   'mapping': 'transition-projection' if 'appgraph_attrs' in e['args'] else 'entry-projection'} for e in base['edges']],
+        'control_bindings': bindings,
+        'unmapped_surfaces': [s for s in surfaces if s['id'] not in {n['id'] for n in base['nodes']}],
+        'unmapped_transitions': [t for t in interaction.get('transitions', [])
+                               if t['id'] not in {e['id'] for e in base['edges']}]}
+    base['graph']['boundary_transitions'] = [t for t in interaction.get('transitions', [])
+        if t.get('target', {}).get('kind') in {'back', 'external'}]
+    for item in interaction.get('unresolved', []):
+        base['unresolved'].append({'id': 'interaction:' + item['id'], 'subject': item.get('subjectRefs'),
+                                   'reason': item['reason'], 'evidence': item.get('evidence', [])})
+    base['nodes'].sort(key=lambda n: n['id'])
+    base['edges'].sort(key=lambda e: e['id'])
+    return base
+
+
+def apply_discoveries(base, discoveries, root, fingerprint):
+    if discoveries.get('schema_version') != 'd2h-utg-discoveries/v1' or discoveries.get('input_fingerprint') != fingerprint:
+        raise UtgError('invalid or stale discoveries input fingerprint')
+    if not isinstance(discoveries.get('operations'), list) or not isinstance(discoveries.get('unresolved', []), list):
+        raise UtgError('discoveries operations and unresolved must be arrays')
+    result, audit, touched = copy.deepcopy(base), [], set()
+    for item in discoveries.get('operations', []):
+        if not isinstance(item, dict):
+            raise UtgError('discovery operation must be an object')
+        kind, operation, identity = item.get('kind'), item.get('op'), item.get('id')
+        if kind not in {'node', 'edge', 'graph'} or operation not in {'add', 'replace', 'exclude'}:
+            raise UtgError('unsupported discovery operation')
+        if not identity or not isinstance(item.get('reason'), str) or not item['reason'].strip():
+            raise UtgError('discovery needs id and reason')
+        if not isinstance(identity, str):
+            raise UtgError('discovery id must be a string')
+        normalize_location(item.get('evidence'), root, 'discovery.evidence')
+        key = (kind, identity)
+        if key in touched:
+            raise UtgError('conflicting operations on ' + str(key))
+        touched.add(key)
+        if kind == 'graph':
+            if identity != 'root' or operation != 'replace' or not isinstance(item.get('value'), str):
+                raise UtgError('only graph root replacement is supported')
+            before = result['graph']['root']
+            result['graph']['root'] = item['value']
+        else:
+            collection = result['nodes' if kind == 'node' else 'edges']
+            matches = [x for x in collection if x['id'] == identity]
+            if (operation == 'add' and matches) or (operation != 'add' and len(matches) != 1):
+                raise UtgError('duplicate or missing discovery target: ' + identity)
+            before = copy.deepcopy(matches[0]) if matches else None
+            if matches:
+                collection.remove(matches[0])
+            if operation != 'exclude':
+                value = copy.deepcopy(item.get('value'))
+                if not isinstance(value, dict) or value.get('id') != identity:
+                    raise UtgError('discovery value identity mismatch')
+                value.update(provenance='ai-source-review', status='static-only')
+                if kind == 'node':
+                    value.setdefault('extra', {})['capture_policy'] = 'strict'
+                else:
+                    value.setdefault('args', {})['discovery_id'] = identity
+                collection.append(value)
+        audit.append({'operation': copy.deepcopy(item), 'before': before})
+    resolved = set()
+    known = {item['id'] for item in base['unresolved']}
+    resolved_findings = discoveries.get('resolved_findings', [])
+    if not isinstance(resolved_findings, list):
+        raise UtgError('resolved_findings must be an array')
+    for finding in resolved_findings:
+        if not isinstance(finding, dict) or finding.get('id') not in known or finding['id'] in resolved:
+            raise UtgError('resolved finding must reference one unique worklist item')
+        if not isinstance(finding.get('reason'), str) or not finding['reason'].strip():
+            raise UtgError('resolved finding requires a reason')
+        normalize_location(finding.get('evidence'), root, 'resolved finding evidence')
+        resolved.add(finding['id'])
+    result['unresolved'] = [item for item in result['unresolved'] if item['id'] not in resolved]
+    result['unresolved'].extend(discoveries.get('unresolved', []))
+    result['nodes'].sort(key=lambda n: n['id'])
+    result['edges'].sort(key=lambda e: e['id'])
+    result['graph'].update(method='appgraph+source-review' if audit or resolved else 'appgraph', input_fingerprint=fingerprint,
+                           discovery_audit=audit, resolved_findings=discoveries.get('resolved_findings', []),
+                           projection_summary={'base_nodes': len(base['nodes']), 'base_edges': len(base['edges']),
+                                               'operations': len(audit), 'resolved_findings': len(resolved)},
+                           unresolved=result['unresolved'])
+    normalize_facts(result, root)  # Reject dangling edges, root, duplicate nodes and invalid evidence.
+    if len({e['id'] for e in result['edges']}) != len(result['edges']):
+        raise UtgError('duplicate edge identity')
+    if 'alignment' in result:
+        result['alignment']['effective_nodes'] = [{'id': n['id'], 'provenance': n.get('provenance')} for n in result['nodes']]
+        result['alignment']['effective_edges'] = [{'id': e['id'], 'provenance': e.get('provenance')} for e in result['edges']]
+        result['alignment']['discovery_audit'] = audit
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--project-root', required=True, type=Path)
+    parser.add_argument('--workspace', type=Path)
+    parser.add_argument('--appgraph', type=Path)
+    parser.add_argument('--discoveries', type=Path)
+    parser.add_argument('--force', action='store_true')
+    args = parser.parse_args()
+    root = args.project_root.resolve()
+    ws = (args.workspace or root.parent / (root.name + '-migration') / '.migration' / 'utg').resolve()
+    try:
+        if not root.is_dir():
+            raise UtgError('source directory does not exist')
+        if (ws / 'appgraph-utg-facts.json').exists() and not args.force:
+            raise UtgError('workspace already exists; use --force for explicit regeneration')
+        graph_path = args.appgraph.resolve() if args.appgraph else ws / 'app-graph.json'
+        if not args.appgraph:
+            executable = shutil.which('appgraph')
+            if not executable:
+                raise UtgError('appgraph is missing; configure the existing CLI before retrying')
+            ws.mkdir(parents=True, exist_ok=True)
+            subprocess.run([executable, 'build', str(root), '--platform', 'android', '--out', str(graph_path)], check=True)
+        graph = load_json(graph_path)
+        fingerprint = digest({'appgraph': graph, 'source': source_digest(root)})
+        base = project(graph, root)
+        base['graph']['input_fingerprint'] = fingerprint
+        base['graph']['appgraph_source'] = str(graph_path)
+        discovery_path = args.discoveries or ws / 'discoveries.json'
+        discoveries = load_json(discovery_path) if discovery_path.exists() else {
+            'schema_version': 'd2h-utg-discoveries/v1', 'input_fingerprint': fingerprint,
+            'operations': [], 'unresolved': []}
+        atomic_write_json(ws / 'appgraph-utg-facts.json', base)
+        if 'alignment' in base:
+            atomic_write_json(ws / 'appgraph-utg-alignment.json', base['alignment'])
+        navigation_findings = [item for item in base['unresolved']
+            if item.get('reason') == 'navigation owner/target/evidence unresolved']
+        resolved_ids = {item.get('id') for item in discoveries.get('resolved_findings', [])}
+        raw_names = {node['id']: node.get('name', node['id']) for node in graph.get('nodes', [])}
+        navigation_candidates = [{'id': edge['id'], 'source_id': edge['from'], 'target_id': edge['to'],
+            'source_name': raw_names.get(edge['from']), 'target_name': raw_names.get(edge['to']),
+            'route_key': (edge.get('attrs') or {}).get('routeKey'),
+            'evidence': (edge.get('attrs') or {}).get('evidence', [])}
+            for edge in graph.get('edges', []) if edge.get('kind') == 'navigates_to']
+        atomic_write_json(ws / 'review-worklist.json', {'input_fingerprint': fingerprint,
+            'appgraph': str(graph_path), 'items': base['unresolved'],
+            'navigation_candidates': navigation_candidates,
+            'navigation_review': {'total_findings': len(navigation_findings),
+                'remaining_findings': len([item for item in navigation_findings if item['id'] not in resolved_ids]),
+                'status': 'reviewed' if all(item['id'] in resolved_ids for item in navigation_findings) else 'pending'},
+            'required_review': ['route registries', 'wrapper calls', 'method references', 'entry points', 'guards', 'selectors']})
+        if not discovery_path.exists():
+            atomic_write_json(discovery_path, discoveries)
+        if not base['nodes'] or (not base['graph']['root'] and not discoveries['operations']):
+            raise UtgError('no proven pages or unique root; review-worklist.json requires source-grounded discoveries')
+        merged = apply_discoveries(base, discoveries, root, fingerprint)
+        if 'alignment' in merged:
+            atomic_write_json(ws / 'appgraph-utg-alignment.json', merged['alignment'])
+        atomic_write_json(ws / 'utg-facts.json', merged)
+        command = [sys.executable, str(SHARED / 'build_utg.py'), '--facts', str(ws / 'utg-facts.json'),
+                   '--project-root', str(root), '--workspace', str(ws)]
+        if args.force:
+            command.append('--force')
+        subprocess.run(command, check=True)
+        return 0
+    except (UtgError, OSError, subprocess.CalledProcessError) as exc:
+        print('ERROR: ' + str(exc), file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())