@buaa_smat/hometrans 0.1.15 → 0.1.17

package/skills/hmos-incremental-ui-align/scripts/app_feature_verify.py

@@ -1,22 +1,32 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "openpyxl",
+#     "phone-agent",
+# ]
+# [[tool.uv.index]]
+# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+# ///
 """
 应用页面导航工具 —— 使用 PhoneAgent 按指定路径操作设备，导航到目标页面。
 
 支持 Android (ADB) 和 HarmonyOS (HDC) 两种设备类型。
 
-依赖: pip install openpyxl phone-agent
+依赖: openpyxl、phone-agent —— 已在文件顶部 PEP 723 元数据声明，`uv run` 自动安装（无需手动 pip install）
 运行前需确保: 设备已连接 (HDC/ADB)、模型 API 可用
 
 用法:
   # 自由 prompt 导航
-  python app_feature_verify.py --device adb --app Gallery --package com.example.gallery --prompt "打开相册，进入设置页面"
+  uv run app_feature_verify.py --device adb --app Gallery --package com.example.gallery --prompt "打开相册，进入设置页面"
 
   # 按功能路径导航
-  python app_feature_verify.py --app 简单图库 --package com.simplemobiletools.gallery.pro --task "L1相册详情L2更多L3筛选媒体文件"
+  uv run app_feature_verify.py --app 简单图库 --package com.simplemobiletools.gallery.pro --task "L1相册详情L2更多L3筛选媒体文件"
 """
 
 import argparse
+import json
 import re
 import sys
 import os
@@ -267,25 +277,62 @@ def _apply_phone_agent_patches():
         _swipe._patched = True
         _hdc.swipe = _swipe
 
-    # Patch 2: parse_action — regex fallback when do() contains unescaped quotes
+    # Patch 2: _parse_response — strip <think>/<answer> tags before splitting by do()/finish()
+    import phone_agent.model.client as _client
+    if not getattr(_client.ModelClient._parse_response, '_patched', False):
+        _orig_parse_response = _client.ModelClient._parse_response
+
+        def _patched_parse_response(self, content: str):
+            # Strip <think>...</think> and <answer>...</answer> wrappers first
+            cleaned = re.sub(r'<think>.*?</think>\s*', '', content, flags=re.DOTALL)
+            m = re.search(r'<answer>\s*(.*?)\s*</answer>', cleaned, re.DOTALL)
+            if m:
+                cleaned = m.group(1)
+            # Also strip trailing </answer> if only opening was consumed by rule 2
+            cleaned = cleaned.replace('</answer>', '').strip()
+            if cleaned:
+                return _orig_parse_response(self, cleaned)
+            return _orig_parse_response(self, content)
+
+        _patched_parse_response._patched = True
+        _client.ModelClient._parse_response = _patched_parse_response
+
+    # Patch 3: parse_action — strip thinking tags + regex fallback for malformed do()
     import phone_agent.actions.handler as _handler
     if not getattr(_handler.parse_action, '_patched', False):
         _orig_parse = _handler.parse_action
+        _THINK_RE = re.compile(r'<think>.*?</think>\s*', re.DOTALL)
+        _ANSWER_RE = re.compile(r'<answer>\s*(.*?)\s*</answer>', re.DOTALL)
+
+        def _strip_llm_tags(text: str) -> str:
+            text = _THINK_RE.sub('', text)
+            m = _ANSWER_RE.search(text)
+            if m:
+                text = m.group(1)
+            return text.strip()
+
         def _parse_action(response):
+            cleaned = _strip_llm_tags(response)
             try:
-                return _orig_parse(response)
-            except ValueError as e:
-                if 'Failed to parse do() action' in str(e):
-                    m = re.search(
-                        r'do\s*\(\s*action\s*=\s*"([^"]*)"\s*,\s*message\s*="(.*)"\s*\)\s*$',
-                        response.strip(), re.DOTALL,
-                    )
-                    if m:
-                        msg = m.group(2)
-                        msg = msg.replace("\\n", "\x0a").replace("\\t", "\x09").replace("\\r", "\x0d")
-                        msg = msg.replace('\\"', '"')
-                        return {"_metadata": "do", "action": m.group(1), "message": msg}
-                raise
+                return _orig_parse(cleaned)
+            except ValueError:
+                pass
+            # regex fallback for do() with unescaped quotes
+            for text in (cleaned, response.strip()):
+                m = re.search(
+                    r'do\s*\(\s*action\s*=\s*"([^"]*)"\s*,\s*message\s*="(.*)"\s*\)\s*$',
+                    text, re.DOTALL,
+                )
+                if m:
+                    msg = m.group(2)
+                    msg = msg.replace("\\n", "\x0a").replace("\\t", "\x09").replace("\\r", "\x0d")
+                    msg = msg.replace('\\"', '"')
+                    return {"_metadata": "do", "action": m.group(1), "message": msg}
+            # fallback: extract bare do() from anywhere in the text
+            m = re.search(r'do\s*\(\s*action\s*=\s*"([^"]*)".*?\)', cleaned)
+            if m:
+                return _orig_parse(m.group(0))
+            return _orig_parse(response)
         _parse_action._patched = True
         _handler.parse_action = _parse_action
 
@@ -374,6 +421,63 @@ def navigate(
             agent.reset()
 
 
+# ---------------------------------------------------------------------------
+# 模型配置加载：UI 对齐与自测共用同一个多模态模型。
+#   优先级：CLI --api-key > HOMETRANS_MODEL_* 环境变量 > ~/.hometrans/config.json
+#   的 autotest.unified_model（由 `ht init` 写入，两端共用）> 老版本 GLM_API_KEY（兼容）。
+# ---------------------------------------------------------------------------
+
+def _load_model_config(cli_api_key: str = ""):
+    """加载统一多模态模型配置（UI 对齐 + 自测共用）。
+
+    `ht init` 把模型四要素（api_key / name / base_url / provider）写入
+    `autotest.unified_model`，并导出为 HOMETRANS_MODEL_* 环境变量。这里优先读
+    环境变量，缺字段时回落到 config.json，单个字段可被 CLI/环境变量覆盖；
+    都没有时再兼容老版本的 GLM_API_KEY（走智谱 GLM 端点）。
+    """
+    from phone_agent.model import ModelConfig
+
+    # 1) 环境变量（ht init 导出）+ CLI 覆盖
+    api_key = (cli_api_key or os.environ.get("HOMETRANS_MODEL_API_KEY", "")).strip()
+    base_url = os.environ.get("HOMETRANS_MODEL_BASE_URL", "").strip()
+    model_name = os.environ.get("HOMETRANS_MODEL_NAME", "").strip()
+    temperature = 0.1
+
+    # 2) 回落 ~/.hometrans/config.json 的 autotest.unified_model（补齐缺失字段）
+    config_path = Path.home() / ".hometrans" / "config.json"
+    if config_path.exists():
+        try:
+            cfg = json.loads(config_path.read_text(encoding="utf-8"))
+            um = cfg.get("autotest", {}).get("unified_model", {})
+            api_key = api_key or str(um.get("api_key", "")).strip()
+            base_url = base_url or str(um.get("base_url", "")).strip()
+            model_name = model_name or str(um.get("name", "")).strip()
+            if um.get("temperature") is not None:
+                temperature = um.get("temperature")
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    if api_key:
+        return ModelConfig(
+            base_url=base_url or "http://localhost:8000/v1",
+            api_key=api_key,
+            model_name=model_name,
+            temperature=temperature,
+        )
+
+    # 3) 向后兼容老版本：仅设置了 GLM_API_KEY 时，回落到智谱 GLM 端点。
+    glm_key = os.environ.get("GLM_API_KEY", "").strip()
+    if glm_key:
+        return ModelConfig(
+            base_url="https://open.bigmodel.cn/api/paas/v4",
+            api_key=glm_key,
+            model_name="autoglm-phone",
+            temperature=0.1,
+        )
+
+    return ModelConfig(temperature=temperature)
+
+
 # ---------------------------------------------------------------------------
 # CLI 入口
 # ---------------------------------------------------------------------------
@@ -395,7 +499,7 @@ def main():
     parser.add_argument("--limit", type=int, default=None, help="仅导航前 N 条")
     parser.add_argument("--offset", type=int, default=1, help="从第几条开始（1-based）")
     parser.add_argument("--sheet", type=int, default=0, help="Excel 工作表索引")
-    parser.add_argument("--api-key", type=str, default="", help="智谱 API Key")
+    parser.add_argument("--api-key", type=str, default="", help="API Key（可选，不传则读取 HOMETRANS_MODEL_* 环境变量 / ~/.hometrans/config.json）")
     parser.add_argument("--max-steps", type=int, default=30, help="Agent 最大步数")
     parser.add_argument("--app-hints", type=str, default=None, help="应用上下文提示")
     parser.add_argument("-q", "--quiet", action="store_true", help="减少输出")
@@ -404,19 +508,14 @@ def main():
     if not args.prompt and not args.task and not args.feature:
         parser.error("必须指定 --feature、--task 或 --prompt 之一")
 
-    api_key = args.api_key or os.environ.get("GLM_API_KEY", "")
-    if not api_key and not args.quiet:
-        print("提示: 未设置 API Key，请通过 --api-key 或环境变量 GLM_API_KEY 配置")
-        print("继续运行可能因鉴权失败而报错\n")
-
     from phone_agent.model import ModelConfig
 
-    model_config = ModelConfig(
-        base_url="https://open.bigmodel.cn/api/paas/v4",
-        api_key=api_key,
-        model_name="autoglm-phone",
-        temperature=0.1,
-    )
+    model_config = _load_model_config(args.api_key)
+    if not model_config.api_key or model_config.api_key == "EMPTY":
+        if not args.quiet:
+            print("提示: 未找到可用的模型配置。请运行 `ht init` 配置统一模型（UI 对齐 + 自测共用），")
+            print("它会写入 ~/.hometrans/config.json 的 autotest.unified_model 并导出 HOMETRANS_MODEL_* 环境变量；")
+            print("或通过 --api-key 传入 API Key。\n")
 
     device_label = "ADB (Android)" if args.device == "adb" else "HDC (HarmonyOS)"
     print(f"设备: {device_label}, 应用: {args.app} ({args.package})")

package/skills/hmos-incremental-ui-align/scripts/navigation-capure.md

@@ -1,37 +1,37 @@
-Create a timestamped output directory under `capture_output_dir`:
-```
-task_dir = capture_output_dir / "task_{timestamp}"
-android_capture_dir = task_dir / "android_page_{i}_{name}"
-hmos_capture_dir = task_dir / "hmos_page_{i}_{name}"
-```
-Each paired hmos-android page-pair should have the same `i`
-
-## Navigation prompt rules
-
-Each page's `android_nav_path` / `hmos_nav_path` is used as the `--prompt` for `app_feature_verify.py`.
-The `--prompt` mode auto-prepends "打开{app_name}，" so do not include "打开{app_name}" in the prompt.
-
-## Navigate to Android page and Capture (If navigated Success)
-```bash
-PYTHONIOENCODING=utf-8 python ./app_feature_verify.py \
-  --device adb \
-  --app "{android.app_name}" \
-  --package "{android.package}" \
-  --prompt "{pages[i].android_nav_path}" \
-  --api-key "{glm_api_key}" \
-  --max-steps 15
-```
-
-**Capture Android page** (if navigation succeeded)
-```bash
-PYTHONIOENCODING=utf-8 python ./page_capture.py --device adb -o "{android_capture_dir}"
-```
-
-## Navigate & Capture HarmonyOS Pages
-
-Same as Andorid but with `--device hdc` and HarmonyOS config values. Directory pattern:
-```
-hmos_capture_dir = task_dir / "hmos_page_{i}_{name}"
-```
-For pages missed in harmony OS app, navigation will certainly fail — `hmos_capture_dir` will be empty, which is expected. Skip navigation for these pages and leave the directory empty.
-
+Create a timestamped output directory under `capture_output_dir`:
+```
+task_dir = capture_output_dir / "task_{timestamp}"
+android_capture_dir = task_dir / "android_page_{i}_{name}"
+hmos_capture_dir = task_dir / "hmos_page_{i}_{name}"
+```
+Each paired hmos-android page-pair should have the same `i`
+
+## Navigation prompt rules
+
+Each page's `android_nav_path` / `hmos_nav_path` is used as the `--prompt` for `app_feature_verify.py`.
+The `--prompt` mode auto-prepends "打开{app_name}，" so do not include "打开{app_name}" in the prompt.
+
+## Navigate to Android page and Capture (If navigated Success)
+```bash
+PYTHONIOENCODING=utf-8 uv run ./app_feature_verify.py \
+  --device adb \
+  --app "{android.app_name}" \
+  --package "{android.package}" \
+  --prompt "{pages[i].android_nav_path}" \
+  \
+  --max-steps 15
+```
+
+**Capture Android page** (if navigation succeeded)
+```bash
+PYTHONIOENCODING=utf-8 uv run ./page_capture.py --device adb -o "{android_capture_dir}"
+```
+
+## Navigate & Capture HarmonyOS Pages
+
+Same as Andorid but with `--device hdc` and HarmonyOS config values. Directory pattern:
+```
+hmos_capture_dir = task_dir / "hmos_page_{i}_{name}"
+```
+For pages missed in harmony OS app, navigation will certainly fail — `hmos_capture_dir` will be empty, which is expected. Skip navigation for these pages and leave the directory empty.
+

package/skills/hmos-incremental-ui-align/scripts/page_capture.py

@@ -1,5 +1,10 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+# /// script
+# requires-python = ">=3.10"
+# [[tool.uv.index]]
+# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+# ///
 """
 统一页面采集工具 —— 单次采集当前设备页面的 View Tree (XML)、截图，支持滚动采集。
 
@@ -7,10 +12,10 @@
 
 用法:
   # HarmonyOS
-  python page_capture.py --device hdc -o ./output
+  uv run page_capture.py --device hdc -o ./output
 
   # Android
-  python page_capture.py --device adb -o ./output --serial emulator-5554
+  uv run page_capture.py --device adb -o ./output --serial emulator-5554
 """
 
 import argparse

package/skills/hmos-integration-test/README.md

@@ -159,7 +159,7 @@
 | 达到最大轮数 | `max_rounds_reached` | 已完成配置的最大轮数循环（`max_rounds`，默认 3），仍有失败未解决 |
 | 编译未产出 HAP（异常） | `no_signed_hap` | build-fixer 未产出签名 HAP，无法继续测试 |
 | 用例列表为空（异常） | `no_testcases` | `testcases.json` 里 0 条用例，没有可跑的内容。常见原因：解析阶段没识别到 `### Scenario:` 区块 |
-| 自测 agent 早退（异常） | `agent_early_exit` | `self-tester` 在跑用例之前就退出了（设备没连、autotest api_key 没配（`~/.hometrans/config.json` 的 autotest 块或 `TEST_API_KEY` 环境变量）、`test-tools/autotest` 目录找不到（`HOMETRANS_TOOL_PATH` 环境变量未配置或失效）、batch 启动失败 / 超时 / 崩溃、`setup=false` 但所需 JSON 缺失等）。报告首行会是 `status: FAIL`，第二行 `reason: <原因>`。**这种情况下不会进入 fix 循环**——这些是环境/前置条件问题，不是应用缺陷 |
+| 自测 agent 早退（异常） | `agent_early_exit` | `self-tester` 在跑用例之前就退出了（设备没连、模型 api_key 没配（`HOMETRANS_MODEL_API_KEY` 环境变量或 `~/.hometrans/config.json` 的 `autotest.unified_model.api_key`）、`test-tools/autotest` 目录找不到（`HOMETRANS_TOOL_PATH` 环境变量未配置或失效）、batch 启动失败 / 超时 / 崩溃、`setup=false` 但所需 JSON 缺失等）。报告首行会是 `status: FAIL`，第二行 `reason: <原因>`。**这种情况下不会进入 fix 循环**——这些是环境/前置条件问题，不是应用缺陷 |
 
 ---
 
@@ -242,7 +242,7 @@ build-fixer 的输出摘要：编译状态、签名类型、迭代次数、修
 - 操作系统：**Windows** 是主要测试目标；macOS/Linux 上的核心命令（`hdc`、`uv`、POSIX 工具链）也能跑，Skill 里涉及到的复制操作会按可用 shell 自适应
 - `hdc` 已安装并在 PATH 中
 - `uv` 已安装（Python 包管理）
-- `~/.hometrans/config.json` 的 `autotest` 块已配置真实 api_key。`api_key` 来源：`ht init` 填好 `TEST_API_KEY` 后自动写入该块；若仍是占位符，`self_test_runner.py` 会在跑用例前用 OS 环境变量 `TEST_API_KEY` 自动补全。运行时由脚本读取该块、物化成临时 YAML 交给 `AutoTest.batch`，不再需要 `config.yaml`
+- api_key 已配置（与 UI 对齐共用同一个多模态模型）。统一链路「环境变量 → config.json → 询问」：`self_test_runner.py` 跑用例前优先读 OS 环境变量 `HOMETRANS_MODEL_API_KEY`（由 `ht init` 导出），缺失时回落 `~/.hometrans/config.json` 的 `autotest.unified_model.api_key`；环境变量存在时会覆盖 config.json 里的对应字段。运行时由脚本读取整个 `autotest` 块、物化成临时 YAML 交给 `AutoTest.batch`，不再需要 `config.yaml`
 - 鸿蒙真机通过 USB 连接，`hdc list targets` 能看到设备
 - 签名后的 `.hap` 文件
 
@@ -262,7 +262,7 @@ A: 检查 USB 连接，跑 `hdc list targets` 看看有没有设备 SN。重新
 
 **Q: 报 autotest 配置缺失 或 api_key 没填？**
 
-A: 三选一：① 设置环境变量 `TEST_API_KEY`（`self_test_runner.py` 跑用例前会自动用它填充）；② 重新跑 `ht init` 并填入 `TEST_API_KEY`，它会自动写入 `~/.hometrans/config.json` 的 `autotest` 块；③ 手动编辑 `~/.hometrans/config.json`，把 `autotest.unified_model.api_key` 的 `YOUR_API_KEY_HERE` 替换成真实的 API Key。
+A: 按统一链路「环境变量 → config.json → 询问」配置 api_key，三选一：① 设置环境变量 `HOMETRANS_MODEL_API_KEY`（优先级最高，`self_test_runner.py` 跑用例前会用它覆盖 config.json）；② 重新跑 `ht init` 配置统一模型，它会写入 `~/.hometrans/config.json` 的 `autotest.unified_model` 并导出 `HOMETRANS_MODEL_*` 环境变量；③ 手动编辑 `~/.hometrans/config.json`，把 `autotest.unified_model.api_key` 的 `YOUR_API_KEY_HERE` 替换成真实的 API Key。
 
 **Q: 前置用例失败了要不要修代码？**
 

package/skills/hmos-integration-test/SKILL.md

@@ -25,14 +25,14 @@ A signed `.hap` file is required (this is a device test — the HAP will be inst
 
 ## Step 0 — Environment Variables Check (run first)
 
-This skill (via `self-tester`) reads its settings **directly from the OS environment variables**. Before parsing inputs, verify (read each from the OS environment: `echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
+This skill (via `self-tester`) resolves each setting along the standard chain — **OS environment variable first, then `~/.hometrans/config.json`, then ask the user**. Before parsing inputs, verify (read env vars with `echo "$VAR"` on macOS/Linux; `$env:VAR` in PowerShell on Windows):
 
-| Variable | Purpose | Valid when |
-|---|---|---|
-| `TEST_API_KEY` | LLM API key AutoTest uses to drive test cases | non-empty |
-| `HOMETRANS_TOOL_PATH` | HomeTrans tools dir (`<HOMETRANS_TOOL_PATH>/test-tools/autotest`) | path exists on disk; if unset, falls back to `~/.hometrans/tools` |
+| Variable | config.json fallback | Purpose | Valid when |
+|---|---|---|---|
+| `HOMETRANS_MODEL_API_KEY` *(legacy `TEST_API_KEY` still honored as a fallback)* | `autotest.unified_model.api_key` | multimodal LLM key AutoTest uses to drive test cases (shared with UI alignment) | non-empty / not the placeholder |
+| `HOMETRANS_TOOL_PATH` | `env.HOMETRANS_TOOL_PATH` | HomeTrans tools dir (`<HOMETRANS_TOOL_PATH>/test-tools/autotest`) | path exists on disk; if unset everywhere, falls back to `~/.hometrans/tools` |
 
-If `TEST_API_KEY` is missing/empty, **stop and ask the user to provide it** before proceeding (suggest running `ht init` to persist it as a machine environment variable). `HOMETRANS_TOOL_PATH` may be left unset (it defaults to `~/.hometrans/tools`).
+The runner (`self_test_runner.py`) applies this same chain at run time (env `HOMETRANS_MODEL_API_KEY` overrides `autotest.unified_model.api_key`). If **neither** the env var **nor** `autotest.unified_model.api_key` in `~/.hometrans/config.json` provides a real key, **stop and ask the user to provide it** before proceeding (suggest running `ht init` to persist it as a machine environment variable). `HOMETRANS_TOOL_PATH` may be left unset (it defaults to `~/.hometrans/tools`).
 
 ## Step 1 — Parse Inputs
 
@@ -336,7 +336,7 @@ If failures remain (for `max_rounds_reached`), list them briefly (scenario names
 | `test_case_path` does not exist | Ask user for correct path, do not proceed |
 | `hap_path` does not exist | Ask user for correct HAP path, do not proceed |
 | `output_path` parent does not exist | Create it, proceed |
-| Agent returns error / times out | Report the error to user. Suggest: check device connection (`hdc list targets`), verify HAP is valid, check the `autotest` block in `~/.hometrans/config.json` (or the `TEST_API_KEY` env var) has a real api_key |
+| Agent returns error / times out | Report the error to user. Suggest: check device connection (`hdc list targets`), verify HAP is valid, check the `HOMETRANS_MODEL_API_KEY` env var or `autotest.unified_model.api_key` in `~/.hometrans/config.json` has a real api_key |
 | `<output_path>/self-test-report.md` missing after agent completes | Report: "Agent completed but no report was generated. Check agent output at <output_path>." |
 | `self-test-report.md` exists but format is unrecognizable | Show the file path, report the first 80 lines as context, let user investigate |
 | Device not found (agent reports "No device") | Remind user: connect device via USB, verify `hdc list targets` shows the device |

package/skills/hmos-spec-generate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hmos-spec-generate
-description: "Generate atomic-scenario requirement specs (markdown) from raw .txt requirement batches for Android-to-HarmonyOS migration. Reads a single .txt holding multiple REQ blocks (blank-line separated), explores the Android code graph via GitNexus, writes per-REQ trace files first then synthesizes specs from the trace. Triggers: spec generation, generate spec, requirement to spec, atomic scenarios, scenario decomposition, decompose scenarios, req to spec, code-trace-first, batch req txt."
+description: "Generate atomic-scenario requirement specs (markdown) from raw .txt requirement batches for Android-to-HarmonyOS migration. Reads a single .txt holding multiple REQ blocks (blank-line separated), explores the Android code graph via homegraph, writes per-REQ trace files first then synthesizes specs from the trace. Triggers: spec generation, generate spec, requirement to spec, atomic scenarios, scenario decomposition, decompose scenarios, req to spec, code-trace-first, batch req txt."
 license: MIT
 allowed-tools:
   - Read
@@ -9,23 +9,24 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
-  - Skill
   - AskUserQuestion
   - TaskCreate
   - TaskList
   - TaskUpdate
-  - mcp__gitnexus__query
-  - mcp__gitnexus__context
-  - mcp__gitnexus__impact
-  - mcp__gitnexus__cypher
-  - mcp__gitnexus__list_repos
+  - mcp__homegraph__search
+  - mcp__homegraph__explore
+  - mcp__homegraph__node
+  - mcp__homegraph__impact
+  - mcp__homegraph__callers
+  - mcp__homegraph__callees
+  - mcp__homegraph__files
 ---
 
 # Spec Generator Skill
 
 Produce atomic-scenario requirement specs from Android source code for Android-to-HarmonyOS migration. The input is a single `.txt` carrying multiple REQ blocks (blank-line separated); each block is processed end-to-end (3.1 → 3.5) before the next block starts.
 
-This skill uses GitNexus as the code-graph backend: the `gitnexus-cli` skill for index management, and `mcp__gitnexus__*` tools for code queries. Spec synthesis MUST go through a trace file written in 3.3 — never synthesize from conversation context.
+This skill uses homegraph as the code-graph backend: the `homegraph` CLI for index management, and `mcp__homegraph__*` tools for code queries. Spec synthesis MUST go through a trace file written in 3.3 — never synthesize from conversation context.
 
 ## Expected Input
 
@@ -82,9 +83,9 @@ Android source layers:
 
 ### Replayable fact
 
-**Rule**: Every fact in the trace MUST be **replayable verbatim** from a tool response. `file:line` anchors come from `mcp__gitnexus__context` / `cypher` results or the line-number prefix of a `Read` output. Phrases with counts or ordering ("called N times", "first X then Y", "synchronously then asynchronously", "again") MUST be derivable from precise tool-driven counting and sequencing (e.g. `mcp__gitnexus__cypher` aggregating callers, or repeated `mcp__gitnexus__impact` calls). Delete any fact that cannot be replayed.
+**Rule**: Every fact in the trace MUST be **replayable verbatim** from a tool response. `file:line` anchors come from `mcp__homegraph__explore` / `node` results or the line-number prefix of a `Read` output. Phrases with counts or ordering ("called N times", "first X then Y", "synchronously then asynchronously", "again") MUST be derivable from precise tool-driven counting and sequencing (e.g. `mcp__homegraph__callers` / `callees` enumeration, or repeated `mcp__homegraph__impact` calls). Delete any fact that cannot be replayed.
 
-**Common failure mode**: Hallucinate detail by analogy with common patterns ("synchronous write then asynchronous overwrite", "set X again"); estimate a line number from a `mcp__gitnexus__context` snippet and drift to a neighbouring symbol; make negative assertions from intuition instead of reverse-lookup with `mcp__gitnexus__impact` / `cypher` / `Grep`.
+**Common failure mode**: Hallucinate detail by analogy with common patterns ("synchronous write then asynchronous overwrite", "set X again"); estimate a line number from a `mcp__homegraph__node` / `explore` snippet and drift to a neighbouring symbol; make negative assertions from intuition instead of reverse-lookup with `mcp__homegraph__impact` / `callers` / `Grep`.
 
 ---
 
@@ -125,45 +126,33 @@ Step 0 output: an ordered list of `(title, body, feature)` tuples plus a skip li
 
 ### Step 1 — Confirm the Android project is a Git repo
 
-Run `git rev-parse --is-inside-work-tree` inside `android_project_dir`.
+`git rev-parse --is-inside-work-tree` in `android_project_dir`: `true` → Step 2; otherwise STOP — tell the user to `git init` the project first, then re-invoke. Do NOT auto-init / modify the user's repo.
 
-- Output is `true` → proceed to Step 2.
-- Otherwise → STOP. Tell the user:
+### Step 2 — Ensure homegraph has a fresh index for the project
 
-  > `android_project_dir` is not a Git repository. GitNexus indexes by Git identity. Please run:
-  >
-  > ```
-  > cd <android_project_dir>
-  > git init && git add . && git commit -m "init"
-  > ```
-  >
-  > then re-invoke this skill.
+homegraph exposes two surfaces:
 
-Do NOT auto-`init` / `add` / `commit` the user's project. Do NOT modify `git config`.
+- **Index management** (`init`, `index`, `sync`, `status`) → run the `homegraph` CLI via `Bash`.
+- **Code queries** (`search`, `explore`, `node`, `impact`, `callers`, `callees`, `files`) → call `mcp__homegraph__*` tools directly.
 
-### Step 2 — Ensure GitNexus has a fresh index for the project
-
-GitNexus exposes two surfaces:
-
-- **Index management** (`status`, `analyze`) → invoke the `gitnexus-cli` skill (CLI wrapper, returns text).
-- **Code queries** (`query`, `context`, `impact`, `cypher`, `list_repos`) → call `mcp__gitnexus__*` tools directly.
+homegraph indexes per-project into a local `.homegraph/` directory; there is no central repo registry. Scope every MCP call to the Android project with `projectPath: "<android_project_dir>"` (the skill's working directory is the spec project, NOT the Android project, so the parameter is mandatory — omitting it queries the wrong project).
 
 Procedure:
 
-1. Invoke `gitnexus-cli` skill with `status` against `android_project_dir`.
+1. Run `homegraph status <android_project_dir>` to check index state.
 2. Decide based on the output:
-   - **Not registered** or **stale** → invoke `gitnexus-cli` with `analyze`, wait for completion.
+   - **Not indexed** (no `.homegraph/`) → run `homegraph init -i <android_project_dir>`, wait for completion.
+   - **Stale** → run `homegraph sync <android_project_dir>` (incremental; use `homegraph index <android_project_dir> --force` for a full rebuild), wait for completion.
    - **Fresh** → proceed.
-3. Obtain `<repo-id>` via `mcp__gitnexus__list_repos()`; find the entry whose `path` matches `android_project_dir`; take its `repo` (or equivalent identifier) field.
 
 **Hard fail policy** — any of the following stops the skill and surfaces the error to the user; do NOT degrade to `Read` + `Grep`:
 
-- `gitnexus-cli` skill is unavailable → ask the user to run `/setup` first.
-- `gitnexus-cli status` or `analyze` returns an error → surface the error verbatim.
-- `mcp__gitnexus__list_repos` returns no matching entry → ask the user to verify that `analyze` registered the project.
-- Any `mcp__gitnexus__*` call in Step 3 fails unexpectedly → surface the error; stop the skill.
+- `homegraph` CLI is not found on PATH → ask the user to install it (`npm install -g homegraph`).
+- `homegraph status`, `init`, `sync`, or `index` returns an error → surface the error verbatim.
+- Any `mcp__homegraph__*` call reports the project is not indexed → verify `init -i` ran against `android_project_dir`.
+- Any `mcp__homegraph__*` call in Step 3 fails unexpectedly → surface the error; stop the skill.
 
-> All `mcp__gitnexus__*` calls in Step 3 MUST carry `repo=<repo-id>` (or equivalent scope parameter). Cross-repo results poison the trace.
+> All `mcp__homegraph__*` calls in Step 3 MUST carry `projectPath: "<android_project_dir>"`. A missing or wrong `projectPath` poisons the trace.
 
 ### Step 3 — Process each REQ block end-to-end
 
@@ -179,22 +168,22 @@ Order matters: build the trace from Android source first, then synthesize the sp
 
 #### 3.2 Recall — Locate entry points (dual-path union)
 
-Run both paths in parallel within the same turn (emit all mcp calls together); the deduplicated union is the recall result. All mcp calls MUST carry `repo=<repo-id>`.
+Run both paths in parallel within the same turn (emit all mcp calls together); the deduplicated union is the recall result. All mcp calls MUST carry `projectPath: "<android_project_dir>"`.
 
 | Path | Approach | Value |
 |---|---|---|
-| **Path 1 · By-concept lookup** | For each entity / UI anchor / intent verb from 3.1, call `mcp__gitnexus__query({ query: "<concept>", repo: "<repo-id>" })` and `mcp__gitnexus__context({ name: "<symbol>", repo: "<repo-id>" })` to find candidate symbols (Activities / Fragments / Composables / ViewModels / Services / Repositories / DAOs). Cross-validate symbol name, file path, and context against `REQ_DESC`. | Direct hits: pages obviously implementing the REQ; data models named after REQ entities. |
-| **Path 2 · Reverse-by-usage** | Take the most discriminative keyword (a settings key literal, a persistence column / preference key, a unique business term). `query` → candidate symbol → `mcp__gitnexus__impact({ name: "<symbol>", repo: "<repo-id>" })` returns callers (nested). Walk callers upward until hitting an `Activity` / `Fragment` / `@Composable` host. That host is an entry point. If the walk passes through intermediate dialog / popup / bottom-sheet / inner-composable components that directly reference the target key, record each as a **separate entry point** — these represent distinct user-facing surfaces within the host. | Covers structural blind spots Path 1 misses: deeply nested consumers, pass-through navigation pages, manifest-declared receivers. |
+| **Path 1 · By-concept lookup** | For each entity / UI anchor / intent verb from 3.1, call `mcp__homegraph__search({ query: "<concept>", projectPath: "<android_project_dir>" })` to locate candidate symbols, then `mcp__homegraph__explore({ query: "<symbols / file names>", projectPath: "<android_project_dir>" })` to pull their source + call relations (Activities / Fragments / Composables / ViewModels / Services / Repositories / DAOs). Cross-validate symbol name, file path, and context against `REQ_DESC`. | Direct hits: pages obviously implementing the REQ; data models named after REQ entities. |
+| **Path 2 · Reverse-by-usage** | Take the most discriminative keyword (a settings key literal, a persistence column / preference key, a unique business term). `search` → candidate symbol → `mcp__homegraph__callers({ symbol: "<symbol>", projectPath: "<android_project_dir>" })` (or `mcp__homegraph__impact` for the wider blast radius) returns who reaches it. Walk callers upward until hitting an `Activity` / `Fragment` / `@Composable` host. That host is an entry point. If the walk passes through intermediate dialog / popup / bottom-sheet / inner-composable components that directly reference the target key, record each as a **separate entry point** — these represent distinct user-facing surfaces within the host. | Covers structural blind spots Path 1 misses: deeply nested consumers, pass-through navigation pages, manifest-declared receivers. |
 
-**Behavioral REQ anchor extraction**: when `REQ_DESC` has no explicit literal keyword (e.g. "after track-change X refreshes synchronously"), extract anchors as `(action verb, affected entity)` tuples — e.g. `(track-change, X)` — and feed both into Path 1's `query` and Path 2's seed symbol search.
+**Behavioral REQ anchor extraction**: when `REQ_DESC` has no explicit literal keyword (e.g. "after track-change X refreshes synchronously"), extract anchors as `(action verb, affected entity)` tuples — e.g. `(track-change, X)` — and feed both into Path 1's `search` and Path 2's seed symbol search.
 
 **Both paths hit zero** → ask the user via `AskUserQuestion` whether to manually specify an entry point. If declined → write `status: no_recall` in the trace, skip 3.3 / 3.4 / 3.5, flag in Step 4 report. Do NOT fabricate entry points.
 
 **Terse REQ handling** — if the REQ body has fewer than ~20 substantive characters, OR contains only topical keywords (e.g. "multi-device", "landscape/portrait") with no concrete action verb / entity:
 
 1. **MUST** run two broad enumeration passes (both mandatory, not optional):
-   - **Pass A · Feature code**: `mcp__gitnexus__cypher` enumeration — find all Activity / Fragment / Composable hosts whose `configChanges` manifest attribute is non-default (for orientation / resize cases) or whose layout has a resource qualifier matching the REQ topic (e.g. `-land`, `-sw600dp`, `-night`).
-   - **Pass B · Settings breadth**: For EACH distinct keyword in the REQ body, run `mcp__gitnexus__query` + `Grep` to enumerate ALL settings / configuration screens that reference that keyword or a semantically related term. Terse REQs frequently span multiple unrelated settings pages; anchoring on the single most obvious page is the primary failure mode. The union of Pass A and Pass B is the recall result.
+   - **Pass A · Feature code**: enumerate hosts via `mcp__homegraph__search({ kind: "class" | "component", projectPath })` (Activities / Fragments / Composables), then `Grep` `AndroidManifest.xml` for non-default `configChanges` (orientation / resize cases) and `mcp__homegraph__files({ pattern, projectPath })` / `Grep` over `res/` for layout resource qualifiers matching the REQ topic (e.g. `-land`, `-sw600dp`, `-night`). Manifest attributes and resource qualifiers live outside the code graph, so `Grep` is authoritative there.
+   - **Pass B · Settings breadth**: For EACH distinct keyword in the REQ body, run `mcp__homegraph__search` + `Grep` to enumerate ALL settings / configuration screens that reference that keyword or a semantically related term. Terse REQs frequently span multiple unrelated settings pages; anchoring on the single most obvious page is the primary failure mode. The union of Pass A and Pass B is the recall result.
 2. If ≥3 plausible candidates → list them in the trace's `Status` section as `candidate_hosts: [...]` and proceed normally.
 3. If <3 candidates → invoke `AskUserQuestion`: show the candidate list, ask which are in-scope for this REQ. Do NOT silently guess.
 4. Mark in trace `Status` block: `terse_req: true` (this signal feeds 3.4 review).
@@ -210,16 +199,20 @@ Run both paths in parallel within the same turn (emit all mcp calls together); t
 
 The trace file is the sole machine-readable contract delivered to 3.5. Exploration and writing form a single unit.
 
-**Exploration checklist — execution order** (all mcp calls carry `repo: "<repo-id>"`):
+**Exploration checklist — execution order** (all mcp calls carry `projectPath: "<android_project_dir>"`):
 
 | Step | Action | Tool |
 |---|---|---|
-| 1 | Survey candidate symbols for each anchor from 3.1 | `mcp__gitnexus__query` / `context` |
-| 2 | Full call chain (callers / callees, up and down) | `mcp__gitnexus__impact` |
-| 3 | Cross-class graph traversal / reverse-lookup state writers / aggregation | `mcp__gitnexus__cypher` |
+| 1 | Survey candidate symbols for each anchor from 3.1 | `mcp__homegraph__search` → `mcp__homegraph__explore` / `node` |
+| 2 | Full call chain (callers / callees, up and down) | `mcp__homegraph__callers` / `callees` / `impact` |
+| 3 | Cross-class traversal / reverse-lookup state writers / aggregation | `mcp__homegraph__impact` (deep reverse closure; raise `depth`), then `Grep` for literal keys |
 | 4 | Exact literal positioning (settings keys, DAO columns, intent actions, preference `android:key`) | `Grep` |
 | 5 | Final `file:line` verification / zero-hit counter-evidence | `Read` (small window) / `Grep` |
 
+> **homegraph has no `cypher`.** Split its two roles by whether you have a seed symbol:
+> - **Reverse-lookup from a known symbol** (who writes / reaches this state, cross-class closure, aggregation) → prefer `mcp__homegraph__impact({ symbol, depth, projectPath })` and raise `depth` for multi-hop. It traverses the full reverse-dependency closure — deeper than `callers` (depth-1). Use `callers` / `callees` only for a single hop.
+> - **Seedless enumeration** (all hosts of a kind, anything matching a pattern / manifest attribute / resource qualifier) → `impact` cannot help (it needs a starting symbol); use `mcp__homegraph__search({ kind })` + `mcp__homegraph__files` + `Grep`.
+
 **Exploration dimensions — information coverage** (orthogonal to the checklist; checklist = order, dimensions = what to capture). Apply each to every recall entry:
 
 - **Trigger code** — UI control + event callback (click / long-press / swipe / lifecycle / broadcast receiver) invoking the REQ behavior. Fill Entry's `code` and `resource` layer fields.
@@ -238,8 +231,8 @@ The trace file is the sole machine-readable contract delivered to 3.5. Explorati
 
 ## Status
 status: ok | no_recall | error
-repo-id: <repo-id>
-backend: gitnexus
+project-path: <android_project_dir>
+backend: homegraph
 
 ## Recalled entry points (Path 1 + Path 2 union, deduplicated)
 - Entry 1: <UI path / page name> — file:line — recalled by: path 1 | path 2 | both
@@ -285,7 +278,7 @@ backend: gitnexus
 ### Non-consumers (boundary counter-examples with evidence)
 - claim:          <e.g. "App widget does not read this key">
   closure_layers: [code, resource, manifest]
-  tools:          [Grep "<pattern>", mcp__gitnexus__cypher "<...>", Read "<path>"]
+  tools:          [Grep "<pattern>", mcp__homegraph__impact "<symbol>", Read "<path>"]
   zero_hits:      <verbatim zero-hit evidence — file globs searched, regex used, hit count>
 
 ## Same-source cross-reference (if applicable)
@@ -298,9 +291,9 @@ backend: gitnexus
 
 Run the checks below against the trace from 3.3; every check must pass before proceeding to 3.5.
 
-- **No fabrication** — every declared `file:line` actually exists (sample-verify via `mcp__gitnexus__context` or `Read`); every behavioral claim is source-supported; every boundary claim has tool evidence.
+- **No fabrication** — every declared `file:line` actually exists (sample-verify via `mcp__homegraph__node` or `Read`); every behavioral claim is source-supported; every boundary claim has tool evidence.
 - **No omission** — every detail in `REQ_DESC` has a counterpart in the trace (Entry / behavior / deviation). If REQ mentions a feature code does not implement, record as deviation, not omission.
-- **Method-discipline compliance** (Multi-layer claim + Replayable fact) — sample-verify random `file:line` anchors via `mcp__gitnexus__context` / `Read` (≥1 line drift → fail); sample-verify every count / ordering phrase against source (unreplayable → fail); every Entry / Touched-entry has all three layer fields filled (hit or `N/A: <reason>`); every Non-consumer claim has all four structured fields (`claim` / `closure_layers` / `tools` / `zero_hits`).
+- **Method-discipline compliance** (Multi-layer claim + Replayable fact) — sample-verify random `file:line` anchors via `mcp__homegraph__node` / `Read` (≥1 line drift → fail); sample-verify every count / ordering phrase against source (unreplayable → fail); every Entry / Touched-entry has all three layer fields filled (hit or `N/A: <reason>`); every Non-consumer claim has all four structured fields (`claim` / `closure_layers` / `tools` / `zero_hits`).
 - **Implicit triggers coverage** — the trace's `Implicit triggers` section is present and explicitly filled (≥1 trigger OR `None`). Absence of the section = fail review.
 - **Trace section presence audit** — every trace MUST contain these H2 sections (with `None` if truly empty; absence = fail): `Status` / `Recalled entry points` / per `Entry` (all 4 fields: `claim` / `layers` / `interaction` / `data_flow`) / `Implicit triggers` / `Core business entities` / `Cross-entry shared declarations` / `Deviations from REQ_DESC` / `Scope / Boundary` / `Same-source cross-reference`.
 
@@ -328,5 +321,5 @@ Once all REQ blocks are processed (or skipped with warnings), produce a brief re
 
 ## Forbidden
 
-- **No nested LLM-agent skill calls** — no `gitnexus-exploring`, no `gitnexus-debugging`, no `gitnexus-refactoring`, no `gitnexus-impact-analysis`. They override this SKILL's instructions and cause role drift. **Exception**: `gitnexus-cli` is a CLI wrapper (not an LLM agent); using it for index management is allowed.
+- **No nested LLM-agent skill calls** — no `homegraph-exploring`, no `homegraph-debugging`, no `homegraph-refactoring`, no `homegraph-impact-analysis`. They override this SKILL's instructions and cause role drift. Index management uses the `homegraph` CLI directly (`Bash`), not a skill.
 - **No modification of the Android project** — `.gradle`, `AndroidManifest.xml`, source files. This skill is read-only.