@harmonyos-arkts/d2h 0.1.11 → 0.1.13

package/skills/d2h-utg-ai-generate/references/facts-contract.md

@@ -1,96 +1,96 @@
-# `utg-facts.json` contract
-
-The facts file is the only AI-authored data input. It describes source evidence; it is not the final UTG format.
-
-```json
-{
-  "schema_version": "d2h-utg-facts/v1",
-  "graph": {
-    "app": "Example",
-    "package": "com.example.app",
-    "architecture": "jetpack-compose/navigation-compose",
-    "root": "MainActivity",
-    "start_destination": "home",
-    "version_name": "1.4.2",
-    "build_variant": "debug"
-  },
-  "nodes": [
-    {
-      "id": "MainActivity",
-      "kind": "activity",
-      "label": "MainActivity (launcher)",
-      "declared_at": "app/src/main/java/com/example/MainActivity.kt:20",
-      "widgets": [],
-      "expected": {"activity_any": ["com.example.app/.MainActivity"]},
-      "required_state": [],
-      "extra": {"launcher": true},
-      "confidence": 1.0
-    }
-  ],
-  "edges": [
-    {
-      "source": "MainActivity",
-      "target": "home",
-      "mechanism": "navhost-start",
-      "trigger": "app/src/main/java/com/example/MainActivity.kt:45",
-      "guard": null,
-      "args": {
-        "action": "default",
-        "label": "Example",
-        "label_source": "string"
-      },
-      "confidence": 0.98
-    }
-  ],
-  "unresolved": [
-    {
-      "subject": "dynamic route from server config",
-      "reason": "target value is not present in source",
-      "evidence": "app/src/main/java/com/example/Router.kt:81"
-    }
-  ]
-}
-```
-
-## Graph
-
-Required fields are `app`, `architecture`, and `root`. `package` and `start_destination` may be empty only when the source ecosystem genuinely has no equivalent. Record `version_name` and `build_variant` when they are determinable from the analyzed source/build configuration; runtime replay refuses a non-empty version that differs from the installed package. Additional graph metadata is preserved.
-
-## Nodes
-
-Required:
-
-- `id`: stable, unique code identity. Do not use display text as identity.
-- `kind`: framework-independent semantic kind such as `activity`, `fragment`, `compose-route`, `voyager-screen`, `dialog`, `sheet`, `menu`, `mode`, `nav-graph`, `hybrid`, or `hybrid-page`.
-- `label`: human-readable description.
-- `declared_at`: project-relative `file:line` that declares or hosts the UI.
-
-Optional fields default to `status="static-only"`, `provenance="ai-source-analysis"`, empty `widgets`, empty `expected`, empty `required_state`, and `extra=null`. Use an object for `extra` only when the node has extension metadata. A node intended for runtime capture must not leave `expected` empty. Supported arrival rules are string arrays: `text_any`, `text_all`, `content_desc_any`, `resource_id_any`, and `activity_any`. Derive them from source literals/resources or stable component identities, not guesses.
-
-Use `required_state` only for a node-level state axis, such as `content`, `login`, `permission`, or `network`. Put edge-specific conditions on the edge guard.
-
-## Edges
-
-Required:
-
-- `source`, `target`: existing node IDs.
-- `mechanism`: navigation mechanism, not a prose summary.
-- `trigger`: project-relative navigation call-site `file:line`.
-- `confidence`: numeric `[0, 1]`.
-
-`guard` is either `null` or an object containing non-empty `kind` and `text`. `args` may contain:
-
-- `action`: `tap`, `back`, `default`, `launch`, `home`, `swipe`, or another concrete driver action.
-- `label`: visible text or URI. It is a compatibility selector only when `selector` is absent.
-- `label_source`: normally `string`, `content-description`, `system`, `code-name`, or `nl_hint`.
-- `label_ambiguous`: boolean.
-- `nl_hint`: source-grounded instruction for human interpretation. It is not executable.
-- `selector`: deterministic ADB selector. It may contain `text`, `text_any`, `content_desc`, `content_desc_any`, `resource_id`, or `resource_id_any`. `normalized_point: [x, y]` uses 0–1 screen fractions and is an explicitly enabled last resort, never an inferred default.
-- `direction`, `distance`, `duration_ms`, and `max_scrolls`: optional deterministic parameters for swipe/search behavior.
-- route arguments or other mechanism-specific metadata.
-
-The generator assigns parallel-edge `key` values. Do not supply them.
-
-## Unresolved findings
-
-Use `unresolved` when the source proves a boundary but not a safe graph fact: runtime/server routes, reflection, computed destinations, missing bundles, build-flavor-only pages, or ambiguous callback ownership. These entries remain in `generation-report.json` and never enter the graph silently.
+# `utg-facts.json` contract
+
+The facts file is the only AI-authored data input. It describes source evidence; it is not the final UTG format.
+
+```json
+{
+  "schema_version": "d2h-utg-facts/v1",
+  "graph": {
+    "app": "Example",
+    "package": "com.example.app",
+    "architecture": "jetpack-compose/navigation-compose",
+    "root": "MainActivity",
+    "start_destination": "home",
+    "version_name": "1.4.2",
+    "build_variant": "debug"
+  },
+  "nodes": [
+    {
+      "id": "MainActivity",
+      "kind": "activity",
+      "label": "MainActivity (launcher)",
+      "declared_at": "app/src/main/java/com/example/MainActivity.kt:20",
+      "widgets": [],
+      "expected": {"activity_any": ["com.example.app/.MainActivity"]},
+      "required_state": [],
+      "extra": {"launcher": true},
+      "confidence": 1.0
+    }
+  ],
+  "edges": [
+    {
+      "source": "MainActivity",
+      "target": "home",
+      "mechanism": "navhost-start",
+      "trigger": "app/src/main/java/com/example/MainActivity.kt:45",
+      "guard": null,
+      "args": {
+        "action": "default",
+        "label": "Example",
+        "label_source": "string"
+      },
+      "confidence": 0.98
+    }
+  ],
+  "unresolved": [
+    {
+      "subject": "dynamic route from server config",
+      "reason": "target value is not present in source",
+      "evidence": "app/src/main/java/com/example/Router.kt:81"
+    }
+  ]
+}
+```
+
+## Graph
+
+Required fields are `app`, `architecture`, and `root`. `package` and `start_destination` may be empty only when the source ecosystem genuinely has no equivalent. Record `version_name` and `build_variant` when they are determinable from the analyzed source/build configuration; runtime replay refuses a non-empty version that differs from the installed package. Additional graph metadata is preserved.
+
+## Nodes
+
+Required:
+
+- `id`: stable, unique code identity. Do not use display text as identity.
+- `kind`: framework-independent semantic kind such as `activity`, `fragment`, `compose-route`, `voyager-screen`, `dialog`, `sheet`, `menu`, `mode`, `nav-graph`, `hybrid`, or `hybrid-page`.
+- `label`: human-readable description.
+- `declared_at`: project-relative `file:line` that declares or hosts the UI.
+
+Optional fields default to `status="static-only"`, `provenance="ai-source-analysis"`, empty `widgets`, empty `expected`, empty `required_state`, and `extra=null`. Use an object for `extra` only when the node has extension metadata. A node intended for runtime capture must not leave `expected` empty. Supported arrival rules are string arrays: `text_any`, `text_all`, `content_desc_any`, `resource_id_any`, and `activity_any`. Derive them from source literals/resources or stable component identities, not guesses.
+
+Use `required_state` only for a node-level state axis, such as `content`, `login`, `permission`, or `network`. Put edge-specific conditions on the edge guard.
+
+## Edges
+
+Required:
+
+- `source`, `target`: existing node IDs.
+- `mechanism`: navigation mechanism, not a prose summary.
+- `trigger`: project-relative navigation call-site `file:line`.
+- `confidence`: numeric `[0, 1]`.
+
+`guard` is either `null` or an object containing non-empty `kind` and `text`. `args` may contain:
+
+- `action`: `tap`, `back`, `default`, `launch`, `home`, `swipe`, or another concrete driver action.
+- `label`: visible text or URI. It is a compatibility selector only when `selector` is absent.
+- `label_source`: normally `string`, `content-description`, `system`, `code-name`, or `nl_hint`.
+- `label_ambiguous`: boolean.
+- `nl_hint`: source-grounded instruction for human interpretation. It is not executable.
+- `selector`: deterministic ADB selector. It may contain `text`, `text_any`, `content_desc`, `content_desc_any`, `resource_id`, or `resource_id_any`. `normalized_point: [x, y]` uses 0–1 screen fractions and is an explicitly enabled last resort, never an inferred default.
+- `direction`, `distance`, `duration_ms`, and `max_scrolls`: optional deterministic parameters for swipe/search behavior.
+- route arguments or other mechanism-specific metadata.
+
+The generator assigns parallel-edge `key` values. Do not supply them.
+
+## Unresolved findings
+
+Use `unresolved` when the source proves a boundary but not a safe graph fact: runtime/server routes, reflection, computed destinations, missing bundles, build-flavor-only pages, or ambiguous callback ownership. These entries remain in `generation-report.json` and never enter the graph silently.

package/skills/d2h-utg-ai-generate/references/page-schema.json

@@ -1,61 +1,61 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://hometrans.local/schemas/page-plan-v1.json",
-  "title": "HomeTrans UTG-directed runtime capture plan",
-  "type": "object",
-  "required": ["schema_version", "source", "summary", "pages"],
-  "properties": {
-    "schema_version": {"const": "d2h-page-plan/v1"},
-    "source": {
-      "type": "object",
-      "required": ["utg", "click_paths", "root", "app", "package", "architecture", "version_name", "build_variant"],
-      "properties": {
-        "utg": {"type": "string", "minLength": 1},
-        "click_paths": {"type": "string", "minLength": 1},
-        "root": {"type": "string", "minLength": 1},
-        "app": {"type": "string", "minLength": 1},
-        "package": {"type": "string"},
-        "architecture": {"type": "string", "minLength": 1},
-        "version_name": {"type": "string"},
-        "build_variant": {"type": "string"}
-      },
-      "additionalProperties": false
-    },
-    "summary": {
-      "type": "object",
-      "required": ["nodes", "capture_planned", "unreachable", "excluded_by_kind"],
-      "properties": {
-        "nodes": {"type": "integer", "minimum": 1},
-        "capture_planned": {"type": "integer", "minimum": 0},
-        "unreachable": {"type": "integer", "minimum": 0},
-        "excluded_by_kind": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}}
-      },
-      "additionalProperties": false
-    },
-    "pages": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["node_id", "kind", "label", "declared_at", "required_state", "expected", "reachable", "capture", "capture_key", "depth", "ui_sequence", "path_text", "steps", "skip_reason"],
-        "properties": {
-          "node_id": {"type": "string", "minLength": 1},
-          "kind": {"type": "string", "minLength": 1},
-          "label": {"type": "string", "minLength": 1},
-          "declared_at": {"type": "string", "pattern": ":[1-9][0-9]*$"},
-          "required_state": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-          "expected": {"type": "object"},
-          "reachable": {"type": "boolean"},
-          "capture": {"type": "boolean"},
-          "capture_key": {"type": ["string", "null"]},
-          "depth": {"type": ["integer", "null"], "minimum": 0},
-          "ui_sequence": {"type": "string", "minLength": 1},
-          "path_text": {"type": ["string", "null"]},
-          "steps": {"type": "array"},
-          "skip_reason": {"type": ["string", "null"]}
-        },
-        "additionalProperties": false
-      }
-    }
-  },
-  "additionalProperties": false
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hometrans.local/schemas/page-plan-v1.json",
+  "title": "HomeTrans UTG-directed runtime capture plan",
+  "type": "object",
+  "required": ["schema_version", "source", "summary", "pages"],
+  "properties": {
+    "schema_version": {"const": "d2h-page-plan/v1"},
+    "source": {
+      "type": "object",
+      "required": ["utg", "click_paths", "root", "app", "package", "architecture", "version_name", "build_variant"],
+      "properties": {
+        "utg": {"type": "string", "minLength": 1},
+        "click_paths": {"type": "string", "minLength": 1},
+        "root": {"type": "string", "minLength": 1},
+        "app": {"type": "string", "minLength": 1},
+        "package": {"type": "string"},
+        "architecture": {"type": "string", "minLength": 1},
+        "version_name": {"type": "string"},
+        "build_variant": {"type": "string"}
+      },
+      "additionalProperties": false
+    },
+    "summary": {
+      "type": "object",
+      "required": ["nodes", "capture_planned", "unreachable", "excluded_by_kind"],
+      "properties": {
+        "nodes": {"type": "integer", "minimum": 1},
+        "capture_planned": {"type": "integer", "minimum": 0},
+        "unreachable": {"type": "integer", "minimum": 0},
+        "excluded_by_kind": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}}
+      },
+      "additionalProperties": false
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["node_id", "kind", "label", "declared_at", "required_state", "expected", "reachable", "capture", "capture_key", "depth", "ui_sequence", "path_text", "steps", "skip_reason"],
+        "properties": {
+          "node_id": {"type": "string", "minLength": 1},
+          "kind": {"type": "string", "minLength": 1},
+          "label": {"type": "string", "minLength": 1},
+          "declared_at": {"type": "string", "pattern": ":[1-9][0-9]*$"},
+          "required_state": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+          "expected": {"type": "object"},
+          "reachable": {"type": "boolean"},
+          "capture": {"type": "boolean"},
+          "capture_key": {"type": ["string", "null"]},
+          "depth": {"type": ["integer", "null"], "minimum": 0},
+          "ui_sequence": {"type": "string", "minLength": 1},
+          "path_text": {"type": ["string", "null"]},
+          "steps": {"type": "array"},
+          "skip_reason": {"type": ["string", "null"]}
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/skills/d2h-utg-ai-generate/references/utg-schema.json

@@ -1,89 +1,89 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://hometrans.local/schemas/utg-v2.json",
-  "title": "HomeTrans source-derived UTG",
-  "type": "object",
-  "required": ["directed", "multigraph", "graph", "nodes", "links"],
-  "properties": {
-    "directed": {"const": true},
-    "multigraph": {"const": true},
-    "graph": {
-      "type": "object",
-      "required": ["app", "architecture", "root"],
-      "properties": {
-        "app": {"type": "string", "minLength": 1},
-        "package": {"type": "string"},
-        "architecture": {"type": "string", "minLength": 1},
-        "root": {"type": "string", "minLength": 1},
-        "start_destination": {"type": "string"},
-        "version_name": {"type": "string"},
-        "build_variant": {"type": "string"}
-      },
-      "additionalProperties": true
-    },
-    "nodes": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["id", "kind", "label", "declared_at", "status", "provenance", "widgets", "expected", "required_state", "extra"],
-        "properties": {
-          "id": {"type": "string", "minLength": 1},
-          "kind": {"type": "string", "minLength": 1},
-          "label": {"type": "string", "minLength": 1},
-          "declared_at": {"type": "string", "pattern": ":[1-9][0-9]*$"},
-          "status": {"type": "string", "minLength": 1},
-          "provenance": {"type": "string", "minLength": 1},
-          "widgets": {"type": "array"},
-          "expected": {
-            "type": "object",
-            "properties": {
-              "text_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
-              "text_all": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
-              "content_desc_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
-              "resource_id_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
-              "activity_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
-            },
-            "additionalProperties": false
-          },
-          "required_state": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-          "extra": {"type": ["object", "null"]}
-        },
-        "additionalProperties": true
-      }
-    },
-    "links": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["source", "target", "mechanism", "trigger", "guard", "args", "confidence", "provenance", "key", "status"],
-        "properties": {
-          "source": {"type": "string", "minLength": 1},
-          "target": {"type": "string", "minLength": 1},
-          "mechanism": {"type": "string", "minLength": 1},
-          "trigger": {"type": "string", "pattern": ":[1-9][0-9]*$"},
-          "guard": {
-            "oneOf": [
-              {"type": "null"},
-              {
-                "type": "object",
-                "required": ["kind", "text"],
-                "properties": {
-                  "kind": {"type": "string", "minLength": 1},
-                  "text": {"type": "string", "minLength": 1}
-                },
-                "additionalProperties": true
-              }
-            ]
-          },
-          "args": {"type": "object"},
-          "confidence": {"type": "number", "minimum": 0, "maximum": 1},
-          "provenance": {"type": "string", "minLength": 1},
-          "key": {"type": "integer", "minimum": 0},
-          "status": {"type": "string", "minLength": 1}
-        },
-        "additionalProperties": true
-      }
-    }
-  },
-  "additionalProperties": false
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hometrans.local/schemas/utg-v2.json",
+  "title": "HomeTrans source-derived UTG",
+  "type": "object",
+  "required": ["directed", "multigraph", "graph", "nodes", "links"],
+  "properties": {
+    "directed": {"const": true},
+    "multigraph": {"const": true},
+    "graph": {
+      "type": "object",
+      "required": ["app", "architecture", "root"],
+      "properties": {
+        "app": {"type": "string", "minLength": 1},
+        "package": {"type": "string"},
+        "architecture": {"type": "string", "minLength": 1},
+        "root": {"type": "string", "minLength": 1},
+        "start_destination": {"type": "string"},
+        "version_name": {"type": "string"},
+        "build_variant": {"type": "string"}
+      },
+      "additionalProperties": true
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "label", "declared_at", "status", "provenance", "widgets", "expected", "required_state", "extra"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "kind": {"type": "string", "minLength": 1},
+          "label": {"type": "string", "minLength": 1},
+          "declared_at": {"type": "string", "pattern": ":[1-9][0-9]*$"},
+          "status": {"type": "string", "minLength": 1},
+          "provenance": {"type": "string", "minLength": 1},
+          "widgets": {"type": "array"},
+          "expected": {
+            "type": "object",
+            "properties": {
+              "text_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "text_all": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "content_desc_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "resource_id_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+              "activity_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
+            },
+            "additionalProperties": false
+          },
+          "required_state": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+          "extra": {"type": ["object", "null"]}
+        },
+        "additionalProperties": true
+      }
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target", "mechanism", "trigger", "guard", "args", "confidence", "provenance", "key", "status"],
+        "properties": {
+          "source": {"type": "string", "minLength": 1},
+          "target": {"type": "string", "minLength": 1},
+          "mechanism": {"type": "string", "minLength": 1},
+          "trigger": {"type": "string", "pattern": ":[1-9][0-9]*$"},
+          "guard": {
+            "oneOf": [
+              {"type": "null"},
+              {
+                "type": "object",
+                "required": ["kind", "text"],
+                "properties": {
+                  "kind": {"type": "string", "minLength": 1},
+                  "text": {"type": "string", "minLength": 1}
+                },
+                "additionalProperties": true
+              }
+            ]
+          },
+          "args": {"type": "object"},
+          "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+          "provenance": {"type": "string", "minLength": 1},
+          "key": {"type": "integer", "minimum": 0},
+          "status": {"type": "string", "minLength": 1}
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}