@veewo/gitnexus 1.5.0 → 1.5.1

package/skills/_shared/unity-rule-authoring-contract.md

@@ -0,0 +1,64 @@
+# Unity Rule Authoring Contract
+
+## Scope
+
+This contract defines the stable public authoring workflow for
+`gitnexus-unity-rule-gen`.
+
+The only public path is direct rule authoring and validation:
+
+`approved/*.yaml -> rule-lab compile -> analyze -> CLI validation`
+
+## Workflow Position
+
+1. `gap-lab` is historical context only and not part of the active workflow.
+2. Default authoring path is reduced `rule-lab` for sparse irregular gaps.
+3. Query-time runtime closure remains graph-only.
+
+## Input Schema
+
+Each authoring item must be an exact source/target pair (or explicit pair set):
+
+- `source_class`
+- `source_method`
+- `target_class`
+- `target_method`
+- `expected_missing_hop` (short text)
+
+If multiple anchors match, user must select the intended anchor explicitly.
+Auto-guessing ambiguous anchors is forbidden.
+
+## Mandatory Guards
+
+1. Duplicate-prevention:
+   - Block proposals already covered by `.gitnexus/rules/approved/*.yaml`.
+2. Fail-closed binding resolution:
+   - Unresolved bindings block progress.
+   - `UnknownClass` / `UnknownMethod` placeholders are forbidden.
+3. Non-empty evidence before promote:
+   - `confirmed_chain.steps` (or equivalent) must be non-empty.
+
+## Artifact Expectations
+
+Primary artifacts are under `.gitnexus/rules/lab/runs/<run_id>/...`.
+
+Run/slice identifiers are internal artifact locators. Public operator guidance must
+not require run orchestration as the primary flow.
+
+## Event/Delegate Boundary
+
+Event/delegate system-wide coverage is analyzer-native scope:
+
+- capture `assignment_expression` (`+=`, `-=`)
+- index delegate/action field symbols
+- capture generic event-type metadata (`Raise<T>` / `Listen<T>`)
+
+Rule authoring is only for sparse, explicitly scoped residual gaps.
+
+## Verification Contract
+
+1. Promote only after mandatory guards pass.
+2. Compile approved rules before analyze.
+3. Verify in a fresh CLI process (`gitnexus cypher` / `gitnexus query`).
+4. Under `hydration_policy=strict` with `fallbackToCompact=true`, parity rerun
+   is required before final closure conclusion.

package/skills/_shared/unity-runtime-process-contract.md

@@ -13,11 +13,16 @@ Load this contract when any of the following is true:
 
 ## Required Workflow
 
+Use this order: `discovery -> seed narrowing -> closure verification`.
+
 1. Run `query/context` with `unity_resources: "on"` and `unity_hydration_mode: "compact"` first.
+   - For `response_profile=slim`, read semantic tiers in order: `facts -> closure -> clues`.
+   - In strict-anchor mode, never let `clues` become the first-screen default when `facts` has high/medium leads.
 2. If `hydrationMeta.needsParityRetry === true`, rerun with `unity_hydration_mode: "parity"` before conclusions.
 3. Do not conclude "no runtime chain" from empty `processes` alone.
 4. If Unity evidence exists, continue stitching:
    - `processes`
+   - `resource_chains` for graph-backed `UNITY_ASSET_GUID_REF -> UNITY_GRAPH_NODE_SCRIPT_REF` bridges
    - `resourceBindings`
    - asset/meta mapping anchors
    - runtime candidate symbols
@@ -26,6 +31,8 @@ Load this contract when any of the following is true:
    - `target`
    - `next_command`
 6. Semantic closure requires hop anchors/evidence anchors for each stitched step.
+7. Treat `clues` as narrowing evidence (`clue`) and never as standalone closure proof.
+8. Strong graph hops can coexist with failed closure; report as partial bridge evidence until verifier-core reaches `verified_full`.
 
 ## Optional Strong Verification
 
@@ -33,6 +40,15 @@ For Reload-focused confirmation, request on-demand verification:
 
 - pass `runtime_chain_verify: "on-demand"` in MCP tools, or
 - use CLI `--runtime-chain-verify on-demand`.
+- `queryText` is not a verifier matching signal in graph-only mode; use structured anchors/resource evidence for closure.
 
 When on-demand verification is used, report `runtime_chain.status`, `evidence_level`, `hops`, and `gaps` before final risk/closure statements.
 
+
+## 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-cli.md

@@ -189,3 +189,11 @@ $GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/Patch/PatchItemPreview.ux
 - **"Not inside a git repository"**: Run from a directory inside a git repo
 - **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
 - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
+
+## 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-debugging.md

@@ -107,3 +107,12 @@ RETURN [n IN nodes(path) | n.name] AS chain
 
 4. Root cause: fetchRates calls external API without proper timeout
 ```
+
+## Runtime-Chain Closure Guard
+
+- Query-time runtime closure is **graph-only** and does not require `verification_rules` / `trigger_tokens` matching.
+- 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-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.