@veewo/gitnexus 1.5.0-rc.4 → 1.5.1

package/scripts/check-sync-manifest-traceability.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const planArg = process.argv[2];
+if (!planArg) {
+  console.error('Usage: node gitnexus/scripts/check-sync-manifest-traceability.mjs <plan.md>');
+  process.exit(1);
+}
+
+const root = process.cwd();
+const planPath = path.resolve(root, planArg);
+
+const requiredCriticalDc = {
+  'DC-01': {
+    semanticCases: [
+      {
+        id: 'directive parsing',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: "resolveEffectiveAnalyzeOptions reads @extensions/@repoAlias/@embeddings from manifest",
+      },
+      {
+        id: 'unknown directive fail-fast',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: 'resolveEffectiveAnalyzeOptions rejects unknown manifest directives',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze-options.test.js'],
+  },
+  'DC-02': {
+    semanticCases: [
+      {
+        id: 'precedence merge case',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: 'resolveEffectiveAnalyzeOptions enforces precedence CLI > manifest > meta',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze-options.test.js'],
+  },
+  'DC-03': {
+    semanticCases: [
+      {
+        id: 'auto default sync-manifest load case',
+        file: 'gitnexus/src/cli/analyze.test.ts',
+        pattern: 'analyze auto-loads .gitnexus/sync-manifest.txt when CLI scope options are omitted',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze.test.js'],
+  },
+  'DC-04': {
+    semanticCases: [
+      {
+        id: 'mismatch prompt decision case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'when explicit CLI values differ from manifest, TTY mode asks whether to update manifest',
+      },
+      {
+        id: 'update decision case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'policy=update rewrites manifest with normalized directives',
+      },
+    ],
+    commandMustInclude: [
+      'gitnexus/dist/cli/sync-manifest.test.js',
+      'gitnexus/dist/cli/analyze.test.js',
+    ],
+  },
+  'DC-05': {
+    semanticCases: [
+      {
+        id: 'unknown directive fail-fast case',
+        file: 'gitnexus/src/cli/analyze-options.test.ts',
+        pattern: 'resolveEffectiveAnalyzeOptions rejects unknown manifest directives',
+      },
+    ],
+    commandMustInclude: ['gitnexus/dist/cli/analyze-options.test.js'],
+  },
+  'DC-08': {
+    semanticCases: [
+      {
+        id: 'placeholder rejection case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'rejects placeholder manifest path values',
+      },
+      {
+        id: 'non-TTY policy gate case',
+        file: 'gitnexus/src/cli/sync-manifest.test.ts',
+        pattern: 'non-TTY without explicit policy exits with actionable error',
+      },
+    ],
+    commandMustInclude: [
+      'gitnexus/dist/cli/sync-manifest.test.js',
+      'gitnexus/dist/cli/analyze.test.js',
+    ],
+  },
+};
+
+function normalizeCell(value) {
+  return value.trim().replace(/^`|`$/g, '').trim();
+}
+
+function parseTraceabilityRows(planText) {
+  const rows = [];
+  for (const line of planText.split(/\r?\n/)) {
+    if (!line.startsWith('DC-')) continue;
+    const parts = line.split(' | ').map((p) => p.trim());
+    if (parts.length < 6) continue;
+
+    const idMatch = parts[0].match(/^(DC-\d+)/);
+    if (!idMatch) continue;
+
+    rows.push({
+      id: idMatch[1],
+      criticality: parts[1],
+      mappedTasks: normalizeCell(parts[2]),
+      verificationCommand: normalizeCell(parts[3]),
+      artifactEvidenceField: normalizeCell(parts[4]),
+      failureSignal: normalizeCell(parts.slice(5).join(' | ')),
+      raw: line,
+    });
+  }
+  return rows;
+}
+
+function validateCriticalRowShape(row, errors) {
+  if (!row.mappedTasks || row.mappedTasks === '-') {
+    errors.push(`${row.id}: missing mapped tasks`);
+  }
+  if (!/Task\s*\d+/i.test(row.mappedTasks)) {
+    errors.push(`${row.id}: mapped tasks do not reference concrete task ids`);
+  }
+  if (!row.verificationCommand || row.verificationCommand === '-') {
+    errors.push(`${row.id}: missing verification command`);
+  }
+  if (!row.artifactEvidenceField || row.artifactEvidenceField === '-') {
+    errors.push(`${row.id}: missing artifact evidence field`);
+  }
+  if (!row.failureSignal || row.failureSignal === '-') {
+    errors.push(`${row.id}: missing failure signal`);
+  }
+}
+
+async function validateSemanticCases(dcId, config, errors) {
+  for (const semanticCase of config.semanticCases) {
+    const casePath = path.resolve(root, semanticCase.file);
+    let content = '';
+    try {
+      content = await fs.readFile(casePath, 'utf-8');
+    } catch {
+      errors.push(`${dcId}: missing semantic case file ${semanticCase.file}`);
+      continue;
+    }
+    if (!content.includes(semanticCase.pattern)) {
+      errors.push(`${dcId}: missing semantic case '${semanticCase.id}' in ${semanticCase.file}`);
+    }
+  }
+}
+
+function validateCommandCoverage(row, config, errors) {
+  for (const requiredFragment of config.commandMustInclude) {
+    if (!row.verificationCommand.includes(requiredFragment)) {
+      errors.push(`${row.id}: verification command missing '${requiredFragment}'`);
+    }
+  }
+}
+
+async function main() {
+  const planText = await fs.readFile(planPath, 'utf-8');
+  const rows = parseTraceabilityRows(planText);
+  const rowById = new Map(rows.map((row) => [row.id, row]));
+  const errors = [];
+
+  for (const dcId of Object.keys(requiredCriticalDc)) {
+    const row = rowById.get(dcId);
+    if (!row) {
+      errors.push(`missing critical row ${dcId} in Design Traceability Matrix`);
+      continue;
+    }
+
+    if (row.criticality !== 'critical') {
+      errors.push(`${dcId}: expected critical criticality, got '${row.criticality}'`);
+    }
+
+    validateCriticalRowShape(row, errors);
+    validateCommandCoverage(row, requiredCriticalDc[dcId], errors);
+    await validateSemanticCases(dcId, requiredCriticalDc[dcId], errors);
+  }
+
+  if (errors.length > 0) {
+    console.error('Sync-manifest traceability check failed:\n');
+    for (const error of errors) {
+      console.error(`- ${error}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Sync-manifest traceability check passed.');
+}
+
+main().catch((error) => {
+  console.error(error?.stack || String(error));
+  process.exit(1);
+});

package/scripts/run-node-tests.mjs

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '..');
+const srcRoot = path.join(repoRoot, 'src');
+const distRoot = path.join(repoRoot, 'dist');
+
+function walk(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, out);
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith('.test.ts')) {
+      out.push(full);
+    }
+  }
+}
+
+const sourceTests = [];
+walk(srcRoot, sourceTests);
+
+const nodeTests = sourceTests
+  .filter((filePath) => {
+    const content = readFileSync(filePath, 'utf8');
+    return content.includes("from 'node:test'") || content.includes('from "node:test"');
+  })
+  .map((filePath) => {
+    const rel = path.relative(srcRoot, filePath).replace(/\.ts$/, '.js');
+    return path.join(distRoot, rel);
+  })
+  .sort();
+
+if (nodeTests.length === 0) {
+  console.error('No node:test suites detected under src/**/*.test.ts');
+  process.exit(1);
+}
+
+const missing = nodeTests.filter((filePath) => !existsSync(filePath));
+if (missing.length > 0) {
+  console.error('Missing compiled node:test files in dist/. Run build first.');
+  for (const filePath of missing.slice(0, 20)) {
+    console.error(`- ${filePath}`);
+  }
+  if (missing.length > 20) {
+    console.error(`... and ${missing.length - 20} more`);
+  }
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, ['--test', ...nodeTests], {
+  stdio: 'inherit',
+  cwd: repoRoot,
+});
+
+process.exit(result.status ?? 1);

package/scripts/tree-sitter-audit-classify.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const CONTAINER_KEYS = ['class', 'interface', 'struct', 'record', 'delegate', 'enum'];
+
+function toNumber(value) {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return 0;
+}
+
+function normalizeContainerCounts(record) {
+  const counts = {
+    class: toNumber(record.class_count),
+    interface: toNumber(record.interface_count),
+    struct: toNumber(record.struct_count),
+    record: toNumber(record.record_count),
+    delegate: toNumber(record.delegate_count),
+    enum: toNumber(record.enum_count),
+  };
+
+  if (record.container_counts && typeof record.container_counts === 'object') {
+    for (const key of CONTAINER_KEYS) {
+      counts[key] = toNumber(record.container_counts[key] ?? counts[key]);
+    }
+  }
+
+  return counts;
+}
+
+function computeClassifiedType(record, containerCounts) {
+  const methodCount = toNumber(record.method_count);
+  const rootHasError = Boolean(record.root_has_error);
+  const rawErrorType = String(record.error_type || '');
+  const totalContainers = CONTAINER_KEYS.reduce((sum, key) => sum + containerCounts[key], 0);
+  const legacyMissingClass = methodCount > 0 && containerCounts.class === 0;
+  const missingContainer = methodCount > 0 && totalContainers === 0;
+  const isFalsePositiveLikely = legacyMissingClass && !missingContainer;
+
+  let errorType = 'ok';
+  if (rawErrorType === 'parse_throw') {
+    errorType = 'parse_throw';
+  } else if (rootHasError || rawErrorType === 'root_has_error') {
+    errorType = 'root_has_error';
+  } else if (missingContainer) {
+    errorType = 'missing_container_with_methods';
+  }
+
+  return {
+    errorType,
+    legacyMissingClass,
+    missingContainer,
+    isFalsePositiveLikely,
+  };
+}
+
+export function classifyTreeSitterAuditRecords(records) {
+  const byType = {
+    parse_throw: 0,
+    root_has_error: 0,
+    missing_container_with_methods: 0,
+    ok: 0,
+  };
+
+  const containerTotals = {
+    class: 0,
+    interface: 0,
+    struct: 0,
+    record: 0,
+    delegate: 0,
+    enum: 0,
+  };
+
+  let compatibilityMissingClassCount = 0;
+  let falsePositiveLikelyCount = 0;
+
+  const classified = records.map((record) => {
+    const containerCounts = normalizeContainerCounts(record);
+    const classification = computeClassifiedType(record, containerCounts);
+    const compatibilityTags = [];
+
+    if (classification.legacyMissingClass) {
+      compatibilityTags.push('missing_class_with_methods');
+      compatibilityMissingClassCount += 1;
+    }
+    if (classification.isFalsePositiveLikely) {
+      falsePositiveLikelyCount += 1;
+    }
+
+    for (const key of CONTAINER_KEYS) {
+      containerTotals[key] += containerCounts[key];
+    }
+
+    byType[classification.errorType] += 1;
+
+    return {
+      ...record,
+      container_counts: containerCounts,
+      classified_error_type: classification.errorType,
+      compatibility_tags: compatibilityTags,
+      is_false_positive_likely: classification.isFalsePositiveLikely,
+    };
+  });
+
+  return {
+    summary: {
+      total: classified.length,
+      byType,
+      compatibility: {
+        missing_class_with_methods: compatibilityMissingClassCount,
+      },
+      falsePositiveLikely: falsePositiveLikelyCount,
+      containerTotals,
+    },
+    records: classified,
+  };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--input') args.input = argv[i + 1];
+    if (arg === '--output') args.output = argv[i + 1];
+  }
+  return args;
+}
+
+async function readJsonl(inputPath) {
+  const raw = await fs.readFile(inputPath, 'utf-8');
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+async function writeOutput(outputPath, data) {
+  const resolved = path.resolve(outputPath);
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  await fs.writeFile(resolved, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (!args.input) {
+    console.error('Usage: node scripts/tree-sitter-audit-classify.mjs --input <diagnostics.jsonl> [--output <report.json>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const records = await readJsonl(path.resolve(args.input));
+  const report = classifyTreeSitterAuditRecords(records);
+
+  if (args.output) {
+    await writeOutput(args.output, report);
+  } else {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 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

@@ -5,7 +5,25 @@ description: "Use when the user needs to run GitNexus CLI commands like analyze/
 
 # GitNexus CLI Commands
 
-Use one command alias in the session so every CLI/MCP call stays on one version line. After `setup`, treat `~/.gitnexus/config.json` as the only npx version source.
+Use one command alias in the session so every CLI/MCP call stays on one version line. After `setup`, use `~/.gitnexus/config.json` as the CLI package spec source (`cliPackageSpec` first, then `cliVersion`). MCP wiring and skill install locations are scope-dependent (`project` vs `global`).
+
+### setup — choose scope explicitly
+
+```bash
+gitnexus setup --scope project --agent codex --cli-spec @veewo/gitnexus@<version>
+```
+
+Rules:
+
+- If user asks "setup this repository" / "本仓库 setup", use `--scope project`.
+- `--scope project` updates repo-local files:
+  - Codex MCP config: `.codex/config.toml`
+  - Skills: `.agents/skills/gitnexus/`
+- `--scope global` updates user-global files:
+  - Codex MCP config: `~/.codex/config.toml`
+  - Skills: `~/.agents/skills/gitnexus/`
+- `--scope global` does not overwrite repo-local `.agents/skills` or `.codex/config.toml`.
+- Never rely on setup defaults for scope; pass `--scope` explicitly to avoid global/project mismatch.
 
 ```bash
 if command -v gitnexus >/dev/null 2>&1; then
@@ -46,16 +64,30 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | -------------------------- | ----------------------------------------------------------------------------------------- |
 | `--force`                  | Force full re-index even if up to date                                                    |
 | `--embeddings`             | Enable embedding generation for semantic search (off by default)                          |
-| `--extensions <ext>`       | Limit parsing to specific file types (e.g., `--extensions ".cs .meta"` for Unity)        |
+| `--extensions <ext>`       | Limit parsing to specific file types (comma-separated, e.g., `--extensions ".cs,.meta"`) |
+| `--csharp-define-csproj <path>` | Load C# `DefineConstants` from a `.csproj` and normalize `#if/#elif/#else/#endif` before parsing |
 | `--scope-prefix <prefix>`  | Limit analysis to a path prefix (e.g., `--scope-prefix Assets/` for Unity)               |
 | `--scope-manifest <file>`  | Read scope rules from a manifest file (e.g., `.gitnexus/sync-manifest.txt`)              |
+| `--sync-manifest-policy <policy>` | Drift policy when explicit CLI values differ from manifest directives: `ask|update|keep|error` |
 | `--skills`                 | Generate repo-specific skill files from detected code communities                         |
 
-**Scope manifest syntax:** Each line is a **path prefix** (not glob). `Assets/Code` matches all files under `Assets/Code/`. Trailing `*` is a wildcard prefix (`Packages/com.veewo.*` matches `Packages/com.veewo.stat/...`). Lines starting with `#` are comments. Do **not** use glob patterns like `**/*.cs` — they will match nothing. Use `--extensions` for file type filtering instead.
+**Scope manifest syntax:** Non-`@` lines are path-prefix scope rules (same semantics as before). `@key=value` directives set analyze options: `@extensions=<csv>`, `@repoAlias=<name>`, `@embeddings=<true|false>`. Unknown directives fail fast.
+
+**Defaulting + drift guard:** If `.gitnexus/sync-manifest.txt` exists and you do not pass `--scope-manifest`/`--scope-prefix`, analyze auto-uses that file. When explicit CLI values (`--extensions`, `--repo-alias`, `--embeddings`) differ from manifest directives, CLI follows `--sync-manifest-policy` (default `ask`; non-TTY requires explicit policy).
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
 
-**Unity projects:** Add `--extensions ".cs .meta"` to ensure Unity asset edges (`UNITY_ASSET_GUID_REF`, `UNITY_COMPONENT_INSTANCE`) are parsed. Add `--scope-prefix Assets/` to limit scope if all code lives under `Assets/`.
+**Unity projects:** Add `--extensions ".cs,.meta"` to ensure Unity asset edges (`UNITY_ASSET_GUID_REF`, `UNITY_COMPONENT_INSTANCE`) are parsed. Add `--scope-prefix Assets/` to limit scope if all code lives under `Assets/`.
+
+**C# conditional-compilation projects (recommended):**
+
+- Unity: pass `--csharp-define-csproj /path/to/Assembly-CSharp.csproj` (for neonspark, use `/Volumes/Shuttle/projects/neonspark/Assembly-CSharp.csproj`).
+- Non-Unity: discover candidate project files first, then pass the intended one explicitly:
+
+```bash
+rg --files -g '*.csproj'
+$GN analyze --extensions ".cs" --csharp-define-csproj <picked-project>.csproj
+```
 
 ### status — Check index freshness
 
@@ -157,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.