@veewo/gitnexus 1.5.0-rc.4 → 1.5.1

package/skills/gitnexus-exploring.md

@@ -16,30 +16,45 @@ description: "Use when the user asks how code works, wants to understand archite
 ## Workflow
 
 ```
-1. READ gitnexus://repos                          → Discover indexed repos
-2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
-4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
-5. (Unity symbols) rerun context/query with unity params when needed
-6. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+1. (Repo unknown / multi-repo only) READ gitnexus://repos     → Discover indexed repos
+2. READ gitnexus://repo/{name}/context                        → Codebase overview, check staleness
+3. gitnexus_query({query: "<what you want to understand>"})   → Find related execution flows
+4. Narrow with slim hints first                               → `decision.recommended_follow_up`, `missing_proof_targets`, `suggested_context_targets`
+5. gitnexus_context({name|uid: "<symbol>"})                   → Deep dive on specific symbol
+6. (Unity symbols) rerun context/query with unity params when needed
+7. READ gitnexus://repo/{name}/process/{name} or use cypher   → Trace full execution flow or prove a structure
 ```
 
-> If step 2 says "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` and run `npx -y <resolved-cli-spec> analyze`.
+Runtime retrieval mnemonic: `discovery -> seed narrowing -> closure verification`.
+
+Unity runtime retrieval rule of thumb:
+
+- natural-language `query` is discovery-only;
+- do not treat it as the primary retrieval anchor;
+- once you have a symbol or resource seed, switch to `uid` / `resource_path_prefix` narrowing immediately.
+
+> If step 2 says "Index is stale" → run `gitnexus analyze` when local CLI exists; otherwise resolve the pinned npx package spec from `~/.gitnexus/config.json` (`cliPackageSpec` first, then `cliVersion`) and run `npx -y <resolved-spec> analyze` (it reuses previous analyze scope/options by default; add `--no-reuse-options` to reset). If the user declines, explicitly warn that retrieval may not reflect the current codebase.
 
 ## Checklist
 
 ```
 - [ ] READ gitnexus://repo/{name}/context
+- [ ] Only use `gitnexus://repos` / `list_repos` when the target repo is unknown or multiple repos are indexed
 - [ ] gitnexus_query for the concept you want to understand
-- [ ] Review returned processes (execution flows)
+- [ ] Review slim query fields first: `summary`, `candidates`, `process_hints`, `resource_hints`, `resource_chains`, `decision`, `missing_proof_targets`, `suggested_context_targets`, `upgrade_hints`, `runtime_preview`
+- [ ] Prefer narrowing with `decision.recommended_follow_up` and exact `uid`-based context before expanding payload size
 - [ ] gitnexus_context on key symbols for callers/callees
+- [ ] Review slim context fields first: `summary`, `symbol`, `incoming`, `outgoing`, `processes`, `resource_hints`, `resource_chains`, `verification_hint`, `missing_proof_targets`, `suggested_context_targets`, `upgrade_hints`, `runtime_preview`
+- [ ] If you need legacy heavy fields (`processes`, `process_symbols`, `definitions`, `resourceBindings`, `serializedFields`, `next_hops`), rerun with `response_profile: "full"`
 - [ ] For Unity evidence, call context/query with `unity_resources: "on"` and `unity_hydration_mode: "compact"`
-- [ ] If `hydrationMeta.needsParityRetry === true`, rerun with `unity_hydration_mode: "parity"`
+- [ ] If you need `hydrationMeta.needsParityRetry` or strict fallback diagnostics, rerun with `response_profile: "full"` first
+- [ ] If `hydrationMeta.needsParityRetry === true` or `hydrationMeta.fallbackToCompact === true`, rerun with `unity_hydration_mode: "parity"` before closure claims
 - [ ] READ process resource for full execution traces
+- [ ] Use `cypher` when you need a graph-level proof instead of another exploratory hint
 - [ ] Read source files for implementation details
 ```
 
-## Unity Runtime Process Trigger
+## Unity Runtime Process Contract
 
 When exploration touches Unity runtime process semantics (runtime chain closure, lifecycle/loader stitching, confidence-based closure), load and follow:
 
@@ -60,30 +75,50 @@ When exploration touches Unity runtime process semantics (runtime chain closure,
 
 ```
 gitnexus_query({query: "payment processing"})
-→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
-→ Symbols grouped by flow with file locations
+→ Slim response: summary + candidates + process_hints + resource_hints + resource_chains + decision + missing_proof_targets + suggested_context_targets + upgrade_hints + runtime_preview
+→ Use `decision.recommended_follow_up` first; if `suggested_context_targets[]` includes `uid`, prefer the matching `context --uid` upgrade hint
+→ Rerun with response_profile: "full" only if you need grouped process rows (`processes`, `process_symbols`, `definitions`, `next_hops`) or full `runtime_claim`
 ```
 
 **gitnexus_context** — 360-degree view of a symbol:
 
 ```
 gitnexus_context({name: "validateUser"})
-→ Incoming calls: loginHandler, apiMiddleware
-→ Outgoing calls: checkToken, getUserById
-→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+→ Slim response: symbol + incoming/outgoing refs + processes + resource_hints + resource_chains + verification_hint + missing_proof_targets + suggested_context_targets + upgrade_hints + runtime_preview
+→ Use structured `suggested_context_targets[]` and `uid` disambiguation before rerunning full
+→ Rerun with response_profile: "full" for Unity hydration diagnostics, `next_hops`, `runtime_claim`, or larger categorized ref payloads
 ```
 
-**Unity-focused context/query** — use compact first, parity only when needed:
+**Unity-focused context/query** — use compact first, inspect slim hints, then parity/full only when needed:
 
 ```
-gitnexus_context({
-  name: "DoorObj",
+gitnexus_query({
+  query: "ReloadBase",
+  resource_path_prefix: "Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset",
   unity_resources: "on",
   unity_hydration_mode: "compact"
 })
+→ Use symbol/resource anchors for Unity runtime retrieval; do not rely on broad natural-language phrasing
+→ Slim output gives resource/process narrowing hints first
+→ If you need hydration diagnostics, rerun with response_profile: "full"
 → hydrationMeta.needsParityRetry ? rerun with unity_hydration_mode: "parity" : continue
 ```
 
+Unity runtime example:
+
+```
+1. READ gitnexus://repo/neonspark-core/context
+2. gitnexus_query({
+     query: "ReloadBase",
+     resource_path_prefix: "Assets/NEON/Graphs/PlayerGun/Gungraph_use/1_weapon_orb_key.asset",
+     unity_resources: "on",
+     unity_hydration_mode: "compact"
+   })
+3. Follow `decision.recommended_follow_up` immediately
+4. gitnexus_context({uid: "<exact uid>", unity_resources: "on", runtime_chain_verify: "on-demand"})
+5. READ process resource or use cypher if you need graph proof
+```
+
 ## Example: "How does payment processing work?"
 
 ```
@@ -96,3 +131,16 @@ gitnexus_context({
    → Outgoing: validateCard, chargeStripe, saveTransaction
 4. Read src/payments/processor.ts for implementation details
 ```
+
+## Runtime-Chain Closure Guard
+
+- Query-time runtime closure is **graph-only** and does not require `verification_rules` / `trigger_tokens` matching.
+- For Unity runtime retrieval, prefer symbol/resource anchors over business-description phrasing; use natural-language `query` only to discover the first anchor.
+- `response_profile=slim` is sufficient for normal workflows; use `runtime_preview` as the default status summary.
+- `response_profile=full` is for debugging and deep evidence inspection (`runtime_claim.hops`, `runtime_claim.gaps`, hydration diagnostics).
+- Strong graph hops can coexist with failed closure when verifier-core still reports `failed`; this is partial bridge evidence, not contradiction.
+- Treat runtime-chain outputs as two layers:
+  - `verifier-core`: binary verifier result (`verified_full` | `failed`)
+  - `policy-adjusted`: user-visible result after hydration policy is applied
+- If `hydration_policy=strict` and `hydrationMeta.fallbackToCompact=true`, the result is downgraded policy-adjusted output and is not closure.
+- In that downgraded state, rerun with parity before final conclusions.

package/skills/gitnexus-guide.md

@@ -44,6 +44,19 @@ For any task involving code understanding, debugging, impact analysis, or refact
 
 ### Unity Retrieval Contract (query/context)
 
+Default `query/context` responses are now slim for agent use:
+
+- `query`: `summary`, `candidates`, `process_hints`, `resource_hints`, `resource_chains`, `decision`, `missing_proof_targets`, `suggested_context_targets`, `upgrade_hints`, `runtime_preview`
+- `context`: `summary`, `symbol`, `incoming`, `outgoing`, `processes`, `resource_hints`, `resource_chains`, `verification_hint`, `missing_proof_targets`, `suggested_context_targets`, `upgrade_hints`, `runtime_preview`
+- `suggested_context_targets[]` now returns structured objects: `{ name, uid?, filePath?, why }`
+- `upgrade_hints[]` may include exact `gitnexus context --uid <uid>` commands for same-name disambiguation
+- `resource_chains[]` returns graph-backed Unity seed chains such as `sourceResourcePath -> intermediateResourcePath -> targetSymbol` when a resource seed can be bridged through `UNITY_ASSET_GUID_REF -> UNITY_GRAPH_NODE_SCRIPT_REF`.
+
+When you need the legacy heavy payloads (`processes`, `process_symbols`, `definitions`, `resourceBindings`, `serializedFields`, `next_hops`), pass:
+
+- `response_profile: "full"` in MCP calls
+- `--response-profile full` in CLI calls
+
 When you need Unity resource evidence, pass:
 
 - `unity_resources: "on"` (or `"auto"` when you want adaptive behavior)
@@ -51,11 +64,29 @@ When you need Unity resource evidence, pass:
 
 Recommended default workflow:
 
-1. Call `context/query` with `unity_hydration_mode: "compact"` for speed.
-2. Inspect `hydrationMeta` in the response:
+1. Follow `discovery -> seed narrowing -> closure verification`.
+2. Call `context/query` with `unity_hydration_mode: "compact"` for speed.
+3. Inspect `hydrationMeta` in the response:
    - `needsParityRetry: true` → rerun same call with `unity_hydration_mode: "parity"`
    - `isComplete: true` → keep compact result
-3. Treat parity as the completeness path for advanced verification.
+4. Treat parity as the completeness path for advanced verification.
+
+Agent-safe upgrade path:
+
+- inspect `resource_chains[]` first for graph-backed Unity resource bridges, then `resource_hints[]` / `process_hints[]` and narrow with `resource_path_prefix=` or symbol-targeted context
+- use `decision.recommended_follow_up` as the default narrow-first next step
+- inspect `missing_proof_targets[]` and structured `suggested_context_targets[]` before considering payload expansion
+- when `suggested_context_targets[]` includes `uid`, prefer the matching `upgrade_hints[]` `context --uid` command over same-name `context(name=...)`
+- `response_profile=slim` is the default and sufficient for normal workflows
+- use `response_profile: "full"` only for debugging/deep evidence inspection when narrowing cannot close the proof gap
+
+Runtime claim closure reminder:
+
+- Query-time runtime closure is **graph-only** and does not require `verification_rules` / `trigger_tokens` matching.
+- `verification_rules` remains an offline governance/report artifact family.
+- Strong graph hops can coexist with failed closure when verifier-core stays `failed`; report as partial bridge evidence.
+- `gitnexus-unity-rule-gen` public flow is `approved -> compile -> analyze -> CLI validation`; this does not change query-time graph-only closure semantics.
+- If `hydration_policy=strict` and `hydrationMeta.fallbackToCompact=true`, rerun parity before closure claims.
 
 When task scope includes Unity runtime process semantics, load and follow:
 
@@ -106,3 +137,11 @@ Lightweight reads (~100-500 tokens) for navigation:
 MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
 RETURN caller.name, caller.filePath
 ```
+
+## Runtime-Chain Closure Guard
+
+- Treat runtime-chain outputs as two layers:
+  - `verifier-core`: binary verifier result (`verified_full` | `failed`)
+  - `policy-adjusted`: user-visible result after hydration policy is applied
+- If `hydration_policy=strict` and `hydrationMeta.fallbackToCompact=true`, the result is downgraded policy-adjusted output and is not closure.
+- In that downgraded state, rerun with parity before final conclusions.

package/skills/gitnexus-impact-analysis.md

@@ -103,3 +103,11 @@ gitnexus_detect_changes({scope: "staged"})
 
 3. Risk: 2 direct callers, 2 processes = MEDIUM
 ```
+
+## Runtime-Chain Closure Guard
+
+- Treat runtime-chain outputs as two layers:
+  - `verifier-core`: binary verifier result (`verified_full` | `failed`)
+  - `policy-adjusted`: user-visible result after hydration policy is applied
+- If `hydration_policy=strict` and `hydrationMeta.fallbackToCompact=true`, the result is downgraded policy-adjusted output and is not closure.
+- In that downgraded state, rerun with parity before final conclusions.

package/skills/gitnexus-pr-review.md

@@ -166,3 +166,11 @@ Structure your review as:
 ### Recommendation
 APPROVE / REQUEST CHANGES / NEEDS DISCUSSION
 ```
+
+## Runtime-Chain Closure Guard
+
+- Treat runtime-chain outputs as two layers:
+  - `verifier-core`: binary verifier result (`verified_full` | `failed`)
+  - `policy-adjusted`: user-visible result after hydration policy is applied
+- If `hydration_policy=strict` and `hydrationMeta.fallbackToCompact=true`, the result is downgraded policy-adjusted output and is not closure.
+- In that downgraded state, rerun with parity before final conclusions.

package/skills/gitnexus-refactoring.md

@@ -127,3 +127,11 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
    → Affected: LoginFlow, TokenRefresh
    → Risk: MEDIUM — run tests for these flows
 ```
+
+## Runtime-Chain Closure Guard
+
+- Treat runtime-chain outputs as two layers:
+  - `verifier-core`: binary verifier result (`verified_full` | `failed`)
+  - `policy-adjusted`: user-visible result after hydration policy is applied
+- If `hydration_policy=strict` and `hydrationMeta.fallbackToCompact=true`, the result is downgraded policy-adjusted output and is not closure.
+- In that downgraded state, rerun with parity before final conclusions.

package/skills/gitnexus-unity-rule-gen.md

@@ -1,353 +1,107 @@
 ---
 name: gitnexus-unity-rule-gen
-description: "Interactive workflow for generating Unity analyze_rules: collect chain clues from user, explore graph to fill parameters, generate rule YAML, compile to bundle, analyze, and verify. Use when: 'create unity rules', 'generate analyze rules', 'add resource binding rules', 'unity rule gen'."
+description: "Reduced rule-lab workflow for Unity analyze_rules authoring from exact source/target gaps. Use when: 'create unity rules', 'generate analyze rules', 'fill sparse runtime gap'."
 ---
 
-# Unity Analyze Rules 交互式生成工作流
+# Unity Reduced Rule-Lab Authoring
 
-本技能引导 agent 从用户描述的自然语言调用链路线索出发，通过图谱探索补全参数，交互式生成 `analyze_rules` 规则。支持一次录入多条规则，一次性 analyze 后逐一验证。
+This skill is the post-rollback workflow.
 
-## Phase 0: 初始化
+Primary path:
 
-```
-1. 确认 gitnexus CLI 可用（gitnexus --version）
-2. 确认目标仓库路径（询问用户或从 cwd 推断）
-3. 确认仓库已索引（gitnexus status），未索引则先 analyze
-4. 确认 UNITY_ASSET_GUID_REF 和 UNITY_COMPONENT_INSTANCE 边存在：
-```
-
-```
-mcp__gitnexus__cypher:
-  query: |
-    MATCH ()-[r:CodeRelation]->()
-    WHERE r.type IN ['UNITY_ASSET_GUID_REF', 'UNITY_COMPONENT_INSTANCE']
-    RETURN r.type AS edgeType, count(*) AS cnt
-  repo: <repo-name>
-```
-
-如果这两种边不存在，说明索引时未启用 Unity 资源解析，需要重新 analyze，**必须加 Unity 参数**：
-
-```bash
-gitnexus analyze --force --extensions ".cs .meta"
-# 如果所有代码都在 Assets/ 下，可加 --scope-prefix Assets/ 缩短分析时间
-```
-
----
-
-## Phase 1: 规则录入循环
-
-```
-loop:
-  1.1 收集用户链路线索
-  1.2 图谱探索补全
-  1.3 多路径确认
-  1.4 binding 类型判定
-  1.5 生成规则 YAML 并暂存
-  1.6 询问用户：是否继续录入下一条规则？
-      - 是 → 回到 1.1
-      - 否 → 进入 Phase 2
-```
-
-### 1.1 收集用户链路线索
-
-向用户询问：
-
-| 信息 | 问题 | 示例 |
-|------|------|------|
-| 场景名称 | 你想验证哪个资源→代码链路？ | weapon-powerup-gungraph |
-| 资源引用字段 | 哪些序列化字段名触发资源加载？ | `gungraph\|graph` |
-| 目标入口方法 | 加载的资源上哪些方法会被触发？ | OnEnable, Awake |
-| 持有字段的类 | 哪些类持有触发加载的字段？ | WeaponPowerUp |
-| 加载方法 | 哪些方法触发资源加载？ | Equip |
-| 动态跳转 | 链路中是否有事件派发或回调（C# Action/SyncList/delegate）？ | `NetEventHub.OnPickUpItem → OnClientPickItUp` |
-| 额外 lifecycle | 项目有自定义入口方法吗？ | Init |
-| lifecycle 范围 | 自定义入口方法的作用范围？ | Assets/Code/Graph |
-
-### 1.2 图谱探索补全
-
-用户不确定某些字段时，按优先级探索：**Cypher 直查 > gitnexus context > 文件 grep**
-
-```
-# 查找资源引用字段名
-mcp__gitnexus__cypher:
-  query: |
-    MATCH ()-[r:CodeRelation {type:'UNITY_ASSET_GUID_REF'}]->()
-    RETURN DISTINCT r.reason
-    LIMIT 20
-  repo: <repo-name>
-
-# 查找挂载在资源上的组件类
-mcp__gitnexus__cypher:
-  query: |
-    MATCH (c:Class)-[r:CodeRelation {type:'UNITY_COMPONENT_INSTANCE'}]->(f:File)
-    WHERE f.filePath CONTAINS '.asset'
-    RETURN c.name, f.filePath
-    LIMIT 20
-  repo: <repo-name>
-
-# 查找特定类的方法列表
-mcp__gitnexus__context:
-  name: <ClassName>
-  repo: <repo-name>
-```
-
-如果图谱查询无结果，回退到文件直读：
-
-```
-# 查找 [SerializeField] 字段
-Grep: pattern="\[SerializeField\]" path=<Assets目录>
-
-# 查找特定方法定义
-Grep: pattern="void Init\b|void Setup\b" path=<Assets目录>
-```
-
-### 1.3 多路径确认
-
-- 同一位置 ≥2 候选路径 → **向用户确认**选择哪条
-- 探索 3 步无结果 → **向用户补充提问**
-
-### 1.4 binding 类型判定
-
-| 链路特征 | binding kind | 说明 |
-|---------|-------------|------|
-| asset GUID 引用 → 目标资源组件激活 | `asset_ref_loads_components` | 序列化字段引用 asset，加载时触发组件 lifecycle |
-| 方法调用 → 字段引用的资源加载 | `method_triggers_field_load` | 特定方法触发序列化字段引用的资源加载 |
-| 方法调用 → SceneManager.LoadScene → 场景组件激活 | `method_triggers_scene_load` | 特定方法触发场景加载，场景中组件 lifecycle 被触发 |
-| 动态跳转（事件派发/回调/delegate，静态分析不可见） | `method_triggers_method` | 声明"方法 A 动态触发方法 B"，注入合成 CALLS 边桥接 gap |
-| 项目自定义入口方法 | `lifecycle_overrides` | 非标准 Unity lifecycle 的自定义入口 |
-
-### 1.5 生成规则 YAML
-
-使用以下模板，根据收集的线索填充：
+1. Gather user-confirmed exact source/target pair(s).
+2. Curate/promote to `rules/approved/*.yaml`.
+3. Compile approved rules.
+4. Re-run analyze and verify via CLI graph checks (not MCP session query/context).
 
-```yaml
-id: unity.<scenario-name>.v2
-version: 2.0.0
-family: analyze_rules
-description: >-
-  （可选）描述该规则覆盖的业务场景和调用链背景，
-  包括动态跳转的机制说明（事件派发/回调绑定等）。
-trigger_family: <scenario-name>
-resource_types:
-  - asset
-host_base_type:
-  - MonoBehaviour
-  - ScriptableObject
+`gap-lab` is migration history only and is not part of active operator guidance.
 
-match:
-  trigger_tokens:
-    - <token1>
-    - <token2>
-  host_base_type:
-    - MonoBehaviour
-    - ScriptableObject
-  resource_types:
-    - asset
+Read first:
 
-topology:
+- `gitnexus/skills/_shared/unity-rule-authoring-contract.md`
+- `docs/unity-runtime-process-source-of-truth.md`
+- `docs/gap-lab-rule-lab-architecture.md`
 
-resource_bindings:
-  - kind: asset_ref_loads_components
-    ref_field_pattern: "<field_pattern>"
-    target_entry_points:
-      - OnEnable
-      - Awake
+## Hard Boundaries
 
-  - kind: method_triggers_field_load
-    host_class_pattern: "<class_pattern>"
-    field_name: "<field_name>"
-    loader_methods:
-      - <method_name>
+1. Query-time runtime closure remains graph-only.
+2. Event/delegate large-scale gaps are analyzer work, not rule-authoring work.
+3. This skill is for sparse irregular gaps only.
 
-  # 类型 C（可选）：方法触发场景加载，场景中组件 lifecycle 被触发
-  - kind: method_triggers_scene_load
-    host_class_pattern: "<class_pattern>"
-    loader_methods:
-      - <method_name>
-    scene_name: "<scene_name>"           # 匹配 .unity 文件名（不含扩展名）
-    target_entry_points:
-      - Awake
-      - Start
-      - OnEnable
+## Input Contract (required)
 
-  # 类型 D（可选）：声明静态分析无法捕获的动态跳转（事件派发/回调/delegate）
-  # 适用场景：C# Action/UnityEvent 事件派发、Mirror SyncList 回调、delegate 绑定等
-  # 注入一条 source_method → target_method 的合成 CALLS 边（精确匹配，一条边）
-  - kind: method_triggers_method
-    description: >-
-      说明动态跳转的机制：例如"A 通过 EventHub.OnXxx?.Invoke() 触发，
-      B 在初始化时订阅该事件"，或"A 调用 SyncList.Add()，
-      触发 SyncList.Callback 回调到 B"
-    source_class_pattern: "<source_class_regex>"   # 例如 "^PlayerActor$"
-    source_method: "<source_method_name>"           # 例如 "ProcessInteractables"
-    target_class_pattern: "<target_class_regex>"   # 例如 "^NetPlayer$"
-    target_method: "<target_method_name>"           # 例如 "OnClientPickItUp"
+Provide exact pair intent for each candidate:
 
-lifecycle_overrides:
-  additional_entry_points:
-    - <custom_entry>
-  scope: "<path_prefix>"
+- source class + source method
+- target class + target method
+- expected missing runtime hop
 
-closure:
-  required_hops:
-    - resource
-    - guid_map
-    - code_loader
-    - code_runtime
+If anchors are ambiguous (multiple candidate methods/classes), stop and ask user to choose explicit options. Do not auto-guess.
 
-claims:
-  guarantees:
-    - resource_to_runtime_chain_closed
-  non_guarantees:
-    - no_runtime_execution
-    - no_dynamic_data_flow_proof
-```
-
-### 1.6 暂存并询问
-
-将生成的 YAML 暂存（不写入文件），向用户确认：
+## Direct Public Flow
 
-> 规则 `<ruleId>` 已生成。是否继续录入下一条规则？
+### Phase A: Prepare exact pairs
 
-- 是 → 回到 1.1
-- 否 → 进入 Phase 2
-
----
-
-## Phase 2: 写入 + compile + analyze
-
-### 2.1 写入规则文件
-
-```bash
-mkdir -p "$TARGET_REPO/.gitnexus/rules/approved"
-# 将每条暂存的 YAML 写入对应文件
-# 文件名: approved/<ruleId>.yaml
-```
+1. Confirm repo and index freshness.
+2. Normalize candidate pairs into explicit source/target tuples.
+3. Run duplicate precheck against `.gitnexus/rules/approved/*.yaml`.
 
-### 2.2 更新 catalog.json
+### Phase B: Review and curate
 
 ```bash
-# 如果 catalog.json 不存在，创建初始结构
-if [ ! -f "$TARGET_REPO/.gitnexus/rules/catalog.json" ]; then
-  echo '{"version":1,"rules":[]}' > "$TARGET_REPO/.gitnexus/rules/catalog.json"
-fi
+gitnexus rule-lab analyze --repo-path "$REPO_PATH"
+RUN_ID="$(ls -1t "$REPO_PATH/.gitnexus/rules/lab/runs" | head -n 1)"
+SLICE_ID="$(find "$REPO_PATH/.gitnexus/rules/lab/runs/$RUN_ID/slices" -name 'slice.json' -maxdepth 2 | head -n 1 | xargs -I{} basename "$(dirname "{}")")"
+gitnexus rule-lab review-pack --repo-path "$REPO_PATH" --run-id "$RUN_ID" --slice-id "$SLICE_ID"
+gitnexus rule-lab curate --repo-path "$REPO_PATH" --run-id "$RUN_ID" --slice-id "$SLICE_ID" --input-path "$CURATION_JSON_PATH"
 ```
 
-向 `rules` 数组追加每条规则的条目：
-
-```json
-{
-  "id": "<ruleId>",
-  "version": "2.0.0",
-  "enabled": true,
-  "file": "approved/<ruleId>.yaml",
-  "family": "analyze_rules"
-}
-```
+Use `analyze` as proposal generation for exact pairs, then curate/promote only proposals that pass guards.
+Do not ask users to provide `run-id`/`slice-id`; resolve them from generated artifacts.
 
-### 2.3 编译规则
+### Phase C: Promote approved rule
 
 ```bash
-gitnexus rule-lab compile --repo-path "$TARGET_REPO"
+gitnexus rule-lab promote --repo-path "$REPO_PATH" --run-id "$RUN_ID" --slice-id "$SLICE_ID"
 ```
 
-### 2.4 重建索引
+### Phase D: Compile and re-index
 
 ```bash
-gitnexus analyze "$TARGET_REPO" --force --extensions ".cs .meta"
-# 如果所有代码都在 Assets/ 下，可加 --scope-prefix Assets/
-```
-
----
-
-## Phase 3: 逐一验证
-
-对每条规则执行 4 项验证，每项给出 PASS/FAIL 判定。
-
-### 验证 1: 合成边存在性
-
-```
-mcp__gitnexus__cypher:
-  query: |
-    MATCH (a)-[r:CodeRelation {type: 'CALLS'}]->(b)
-    WHERE r.reason STARTS WITH 'unity-rule-'
-    RETURN r.reason AS reason, count(*) AS cnt
-    ORDER BY cnt DESC
-  repo: <repo-name>
+gitnexus rule-lab compile --repo-path "$REPO_PATH" --family analyze_rules
+gitnexus analyze -f "$REPO_PATH"
 ```
 
-**PASS**: 返回 ≥1 行，且 `reason` 包含规则 ID。
-**FAIL 诊断**: 规则未被 pipeline 加载 → 检查 catalog.json 的 `family` 字段。
-
-### 验证 2: 运行时链路验证
+## Three Mandatory Guards
 
-```
-mcp__gitnexus__query:
-  query: "<trigger_token>"
-  runtime_chain_verify: "on-demand"
-  repo: <repo-name>
-```
+1. Duplicate-prevention:
+   - Block if pair already covered by `rules/approved/*.yaml`.
+2. Fail-closed binding resolution:
+   - Block if unresolved binding remains.
+   - `UnknownClass` / `UnknownMethod` placeholders are forbidden.
+3. Non-empty evidence before promote:
+   - `confirmed_chain.steps` (or equivalent) must be non-empty.
 
-**PASS**: `runtime_chain.status === 'verified_full'` 且 `evidence_level === 'verified_chain'`。
-**FAIL 诊断**:
-- `rule_not_matched` → 规则的 `trigger_tokens` 未匹配查询文本
-- `verification_failed` → 图谱中无匹配的 `unity-rule-*` 合成边
-
-### 验证 3: Process 完整性
-
-```
-mcp__gitnexus__context:
-  name: "<target_class>"
-  repo: <repo-name>
-```
+## Verification
 
-**PASS**: `processes` 中至少有一个包含跨越资源层和代码层的步骤。
-**FAIL 诊断**: 合成边 confidence 过低 → 检查 `RULE_EDGE_CONFIDENCE`（应为 0.75）。
+1. Verify synthetic edges with **CLI in a fresh process** (for example `gitnexus cypher` / `gitnexus query`).
+2. Do not use current MCP session `query/context` as synthetic-edge acceptance evidence immediately after analyze/rebuild.
+3. Inspect analyze summary `rule_binding.*` diagnostics:
+   - `rule_binding.agent_report: should_report=false` → no anomaly to report.
+   - `rule_binding.agent_report: should_report=true` → summarize `rule_binding.anomaly:*` in your run report.
+4. Keep closure claims aligned to graph-only semantics.
+5. Under `hydration_policy=strict` with `fallbackToCompact=true`, run parity before final closure conclusion.
 
-### 验证 4: 合成边分布
+Suggested acceptance check (example):
 
+```bash
+gitnexus cypher --repo "$REPO_ALIAS" \
+  "MATCH (a)-[r:CodeRelation {type:'CALLS'}]->(b)
+   WHERE r.reason STARTS WITH 'unity-rule-'
+   RETURN a.name, b.name, r.reason
+   LIMIT 50"
 ```
-mcp__gitnexus__cypher:
-  query: |
-    MATCH (a)-[r:CodeRelation {type: 'CALLS'}]->(b)
-    WHERE r.reason STARTS WITH 'unity-rule-'
-    RETURN
-      CASE
-        WHEN r.reason CONTAINS 'resource-load' THEN 'resource-load'
-        WHEN r.reason CONTAINS 'lifecycle-override' THEN 'lifecycle-override'
-        WHEN r.reason CONTAINS 'loader-bridge' THEN 'loader-bridge'
-        WHEN r.reason CONTAINS 'scene-load' THEN 'scene-load'
-        WHEN r.reason CONTAINS 'method-bridge' THEN 'method-bridge'
-        ELSE 'other'
-      END AS edgeKind,
-      count(*) AS cnt
-  repo: <repo-name>
-```
-
-**PASS**: 规则涉及的边类型均有产出（`method_triggers_method` 对应 `method-bridge`）。
-
----
-
-## 失败诊断路径
-
-| 症状 | 可能原因 | 修复方向 |
-|------|---------|---------|
-| 验证 1 失败（0 合成边） | 规则未被 compile 或 family 不对 | 检查 catalog.json + compiled bundle |
-| 验证 1 部分（只有 resource-load） | method_triggers_field_load 参数错误 | 检查 host_class_pattern / loader_methods |
-| 验证 1 部分（无 scene-load） | method_triggers_scene_load 参数错误 | 检查 scene_name 是否匹配 .unity 文件名 |
-| 验证 1 部分（无 method-bridge） | method_triggers_method 类名/方法名不匹配 | 检查 source/target_class_pattern 和 source/target_method 是否与图谱中节点名一致 |
-| 验证 2 失败（rule_not_matched） | trigger_tokens 未匹配查询文本 | 调整 match.trigger_tokens |
-| 验证 2 失败（verification_failed） | 合成边 reason 中的 ruleId 不匹配 | 检查规则 ID 一致性 |
-| 验证 3 失败（无 Process） | 合成边 confidence 过低 | 检查 RULE_EDGE_CONFIDENCE（应为 0.75） |
-| 验证 4 链路断裂（中间有动态跳转） | 事件派发/回调/delegate 无静态 CALLS 边 | 添加 `method_triggers_method` binding 桥接动态跳转 |
-| lifecycle_overrides 无效 | scope 值不是文件路径前缀 | scope 应匹配 filePath 而非类名 |
-
----
 
-## 参考文档
+## Legacy Note
 
-- 设计文档：`docs/plans/2026-04-04-unity-rule-gen-skill-design.md`
-- YAML 格式定义：设计文档 section 3.3
-- 注入逻辑：`gitnexus/src/core/ingestion/unity-runtime-binding-rules.ts`
-- 规则类型定义：`gitnexus/src/rule-lab/types.ts:90-114`
-- 编译命令：`gitnexus rule-lab compile --repo-path <path>`
+If historical `.gitnexus/gap-lab/runs/**` artifacts exist, treat them as migration evidence only. Do not require gap-lab parity/coverage gates for direct `approved -> compile -> analyze -> CLI validation` loops.