@veewo/gitnexus 1.4.11-rc.2 → 1.5.0-rc

package/dist/rule-lab/promote.test.js

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promoteCuratedRules } from './promote.js';
+describe('rule-lab promote', () => {
+    it('promotes curated candidate into approved yaml and catalog entry', async () => {
+        const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'rule-lab-promote-'));
+        const rulesRoot = path.join(repoRoot, '.gitnexus', 'rules');
+        const sliceDir = path.join(rulesRoot, 'lab', 'runs', 'run-x', 'slices', 'slice-a');
+        await fs.mkdir(path.join(rulesRoot, 'approved'), { recursive: true });
+        await fs.mkdir(sliceDir, { recursive: true });
+        await fs.writeFile(path.join(rulesRoot, 'catalog.json'), JSON.stringify({ version: 1, rules: [] }, null, 2), 'utf-8');
+        await fs.writeFile(path.join(sliceDir, 'curated.json'), JSON.stringify({
+            run_id: 'run-x',
+            slice_id: 'slice-a',
+            curated: [
+                {
+                    id: 'candidate-1',
+                    rule_id: 'demo.rule.v1',
+                    title: 'demo rule',
+                    match: { trigger_tokens: ['reload'] },
+                    topology: [
+                        { hop: 'resource', from: { entity: 'resource' }, to: { entity: 'script' }, edge: { kind: 'binds_script' } },
+                    ],
+                    closure: {
+                        required_hops: ['resource'],
+                        failure_map: { missing_evidence: 'rule_matched_but_evidence_missing' },
+                    },
+                    claims: {
+                        guarantees: ['can verify startup graph trigger'],
+                        non_guarantees: ['does not prove all runtime states'],
+                        next_action: 'gitnexus query "reload"',
+                    },
+                    confirmed_chain: {
+                        steps: [{ hop_type: 'resource', anchor: 'Assets/Demo.prefab:12', snippet: 'Reload' }],
+                    },
+                    guarantees: ['can verify startup graph trigger'],
+                    non_guarantees: ['does not prove all runtime states'],
+                },
+            ],
+        }, null, 2), 'utf-8');
+        const out = await promoteCuratedRules({ repoPath: repoRoot, runId: 'run-x', sliceId: 'slice-a' });
+        expect(out.catalog.rules.some((r) => r.id === 'demo.rule.v1')).toBe(true);
+        expect(out.promotedFiles[0]).toMatch(/rules\/approved\/.*\.yaml$/);
+        await fs.rm(repoRoot, { recursive: true, force: true });
+    });
+    it('emits stage-aware compiled bundles for analyze, retrieval, and verification', async () => {
+        const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'rule-lab-promote-'));
+        const rulesRoot = path.join(repoRoot, '.gitnexus', 'rules');
+        const sliceDir = path.join(rulesRoot, 'lab', 'runs', 'run-x', 'slices', 'slice-a');
+        await fs.mkdir(path.join(rulesRoot, 'approved'), { recursive: true });
+        await fs.mkdir(sliceDir, { recursive: true });
+        await fs.writeFile(path.join(rulesRoot, 'catalog.json'), JSON.stringify({ version: 1, rules: [] }, null, 2), 'utf-8');
+        await fs.writeFile(path.join(sliceDir, 'curated.json'), JSON.stringify({
+            run_id: 'run-x',
+            slice_id: 'slice-a',
+            curated: [
+                {
+                    id: 'candidate-1',
+                    rule_id: 'demo.rule.v2',
+                    title: 'demo rule',
+                    match: {
+                        trigger_tokens: ['reload'],
+                        resource_types: ['asset'],
+                        host_base_type: ['ReloadBase'],
+                    },
+                    topology: [
+                        { hop: 'resource', from: { entity: 'resource' }, to: { entity: 'script' }, edge: { kind: 'binds_script' } },
+                        { hop: 'code_runtime', from: { entity: 'script' }, to: { entity: 'runtime' }, edge: { kind: 'calls' } },
+                    ],
+                    closure: {
+                        required_hops: ['resource', 'code_runtime'],
+                        failure_map: { missing_evidence: 'rule_matched_but_evidence_missing' },
+                    },
+                    claims: {
+                        guarantees: ['reload_chain_closed'],
+                        non_guarantees: ['no_runtime_execution'],
+                        next_action: 'gitnexus query "reload"',
+                    },
+                    confirmed_chain: {
+                        steps: [{ hop_type: 'resource', anchor: 'Assets/Demo.prefab:12', snippet: 'Reload' }],
+                    },
+                    guarantees: ['reload_chain_closed'],
+                    non_guarantees: ['no_runtime_execution'],
+                },
+            ],
+        }, null, 2), 'utf-8');
+        const out = await promoteCuratedRules({ repoPath: repoRoot, runId: 'run-x', sliceId: 'slice-a', version: '2.0.0' });
+        expect(out).toHaveProperty('compiledPaths');
+        const analyzeBundlePath = path.join(rulesRoot, 'compiled', 'analyze_rules.v2.json');
+        const retrievalBundlePath = path.join(rulesRoot, 'compiled', 'retrieval_rules.v2.json');
+        const verificationBundlePath = path.join(rulesRoot, 'compiled', 'verification_rules.v2.json');
+        const analyzeBundle = JSON.parse(await fs.readFile(analyzeBundlePath, 'utf-8'));
+        const retrievalBundle = JSON.parse(await fs.readFile(retrievalBundlePath, 'utf-8'));
+        const verificationBundle = JSON.parse(await fs.readFile(verificationBundlePath, 'utf-8'));
+        expect(analyzeBundle.family).toBe('analyze_rules');
+        expect(retrievalBundle.family).toBe('retrieval_rules');
+        expect(verificationBundle.family).toBe('verification_rules');
+        expect(analyzeBundle.rules[0].id).toBe('demo.rule.v2');
+        expect(retrievalBundle.rules[0].claims.next_action).toBe('gitnexus query "reload"');
+        expect(verificationBundle.rules[0].closure.required_hops).toEqual(['resource', 'code_runtime']);
+        await fs.rm(repoRoot, { recursive: true, force: true });
+    });
+    it('rejects promote when resource_types or host_base_type are unknown', async () => {
+        const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'rule-lab-promote-'));
+        const rulesRoot = path.join(repoRoot, '.gitnexus', 'rules');
+        const sliceDir = path.join(rulesRoot, 'lab', 'runs', 'run-x', 'slices', 'slice-a');
+        await fs.mkdir(path.join(rulesRoot, 'approved'), { recursive: true });
+        await fs.mkdir(sliceDir, { recursive: true });
+        await fs.writeFile(path.join(rulesRoot, 'catalog.json'), JSON.stringify({ version: 1, rules: [] }, null, 2), 'utf-8');
+        await fs.writeFile(path.join(sliceDir, 'curated.json'), JSON.stringify({
+            run_id: 'run-x',
+            slice_id: 'slice-a',
+            curated: [
+                {
+                    id: 'candidate-unknown',
+                    rule_id: 'demo.rule.v2',
+                    match: { trigger_tokens: ['reload'] },
+                    topology: [
+                        { hop: 'resource', from: { entity: 'resource' }, to: { entity: 'script' }, edge: { kind: 'binds_script' } },
+                    ],
+                    closure: {
+                        required_hops: ['resource'],
+                        failure_map: { missing_evidence: 'rule_matched_but_evidence_missing' },
+                    },
+                    claims: {
+                        guarantees: ['reload_chain_closed'],
+                        non_guarantees: ['no_runtime_execution'],
+                        next_action: 'gitnexus query "reload"',
+                    },
+                    confirmed_chain: {
+                        steps: [{ hop_type: 'resource', anchor: 'Assets/Demo.prefab:9', snippet: 'Reload' }],
+                    },
+                    guarantees: ['reload_chain_closed'],
+                    non_guarantees: ['no_runtime_execution'],
+                },
+            ],
+        }, null, 2), 'utf-8');
+        await fs.writeFile(path.join(sliceDir, 'dsl-draft.json'), JSON.stringify({
+            id: 'demo.rule.v2',
+            version: '2.0.0',
+            match: {
+                trigger_tokens: ['reload'],
+                resource_types: ['unknown'],
+                host_base_type: ['unknown'],
+            },
+            topology: [
+                { hop: 'resource', from: { entity: 'resource' }, to: { entity: 'script' }, edge: { kind: 'binds_script' } },
+            ],
+            closure: {
+                required_hops: ['resource'],
+                failure_map: { missing_evidence: 'rule_matched_but_evidence_missing' },
+            },
+            claims: {
+                guarantees: ['reload_chain_closed'],
+                non_guarantees: ['no_runtime_execution'],
+                next_action: 'gitnexus query "reload"',
+            },
+        }, null, 2), 'utf-8');
+        await expect(promoteCuratedRules({ repoPath: repoRoot, runId: 'run-x', sliceId: 'slice-a' })).rejects.toThrow(/unknown/i);
+        await fs.rm(repoRoot, { recursive: true, force: true });
+    });
+});

package/dist/rule-lab/regress.d.ts

@@ -0,0 +1,60 @@
+export interface RuleLabRegressInput {
+    precision: number;
+    coverage: number;
+    probes?: Array<{
+        id: string;
+        pass: boolean;
+        replay_command: string;
+        bucket?: 'anchor' | 'holdout' | 'negative';
+        key_resource_hit?: boolean;
+        next_hop_usable?: boolean;
+        hint_drift?: boolean;
+        false_positive_anchor_leak?: boolean;
+    }>;
+    repoPath?: string;
+    runId?: string;
+}
+export interface RuleLabRegressOutput {
+    pass: boolean;
+    failures: string[];
+    metrics: {
+        precision: number;
+        coverage: number;
+        probe_pass_rate: number;
+        key_resource_hit_rate: number;
+        next_hop_usability_rate: number;
+        hint_drift_rate: number;
+    };
+    bucket_metrics: {
+        anchor: {
+            total: number;
+            passed: number;
+            anchor_pass_rate: number;
+        };
+        holdout: {
+            total: number;
+            usable: number;
+            next_hop_usability_rate: number;
+        };
+        negative: {
+            total: number;
+            false_positive: number;
+            false_positive_rate: number;
+        };
+    };
+    threshold_checks: {
+        precision_pass: boolean;
+        coverage_pass: boolean;
+        probe_pass_rate_pass: boolean;
+        anchor_pass: boolean;
+        holdout_pass: boolean;
+        negative_pass: boolean;
+    };
+    probe_results: Array<{
+        id: string;
+        pass: boolean;
+        replay_command: string;
+    }>;
+    reportPath?: string;
+}
+export declare function runRuleLabRegress(input: RuleLabRegressInput): Promise<RuleLabRegressOutput>;

package/dist/rule-lab/regress.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const PRECISION_THRESHOLD = 0.9;
+const COVERAGE_THRESHOLD = 0.8;
+const PROBE_PASS_RATE_THRESHOLD = 0.85;
+function buildReportMarkdown(output) {
+    const lines = [];
+    lines.push('# Rule Lab Regression Report');
+    lines.push('');
+    lines.push('## Metrics');
+    lines.push(`- metrics.precision: ${output.metrics.precision}`);
+    lines.push(`- metrics.coverage: ${output.metrics.coverage}`);
+    lines.push(`- metrics.probe_pass_rate: ${output.metrics.probe_pass_rate}`);
+    lines.push(`- metrics.key_resource_hit_rate: ${output.metrics.key_resource_hit_rate}`);
+    lines.push(`- metrics.next_hop_usability_rate: ${output.metrics.next_hop_usability_rate}`);
+    lines.push(`- metrics.hint_drift_rate: ${output.metrics.hint_drift_rate}`);
+    lines.push('');
+    lines.push('## Gate');
+    lines.push(`- pass: ${output.pass}`);
+    lines.push(`- failures: ${output.failures.join(', ') || 'none'}`);
+    lines.push(`- threshold_checks: ${JSON.stringify(output.threshold_checks)}`);
+    lines.push('');
+    lines.push('## Buckets');
+    lines.push(`- anchor: ${JSON.stringify(output.bucket_metrics.anchor)}`);
+    lines.push(`- holdout: ${JSON.stringify(output.bucket_metrics.holdout)}`);
+    lines.push(`- negative: ${JSON.stringify(output.bucket_metrics.negative)}`);
+    lines.push('');
+    lines.push('## Probe Results');
+    if (output.probe_results.length === 0) {
+        lines.push('- none');
+    }
+    else {
+        for (const probe of output.probe_results) {
+            lines.push(`- ${probe.id}: pass=${probe.pass} | replay_command=${probe.replay_command}`);
+        }
+    }
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+export async function runRuleLabRegress(input) {
+    const failures = [];
+    const probes = Array.isArray(input.probes) ? input.probes : [];
+    if (input.precision < PRECISION_THRESHOLD) {
+        failures.push('precision_below_threshold');
+    }
+    if (input.coverage < COVERAGE_THRESHOLD) {
+        failures.push('coverage_below_threshold');
+    }
+    const passedProbes = probes.filter((probe) => probe.pass).length;
+    const keyResourceProbeCount = probes.filter((probe) => typeof probe.key_resource_hit === 'boolean').length;
+    const keyResourceHitCount = probes.filter((probe) => probe.key_resource_hit === true).length;
+    const nextHopProbeCount = probes.filter((probe) => typeof probe.next_hop_usable === 'boolean').length;
+    const nextHopUsableCount = probes.filter((probe) => probe.next_hop_usable === true).length;
+    const hintDriftProbeCount = probes.filter((probe) => typeof probe.hint_drift === 'boolean').length;
+    const hintDriftCount = probes.filter((probe) => probe.hint_drift === true).length;
+    const probePassRate = probes.length > 0
+        ? passedProbes / probes.length
+        : 0;
+    if (probePassRate < PROBE_PASS_RATE_THRESHOLD) {
+        failures.push('probe_pass_rate_below_threshold');
+    }
+    const anchorProbes = probes.filter((probe) => probe.bucket === 'anchor');
+    const holdoutProbes = probes.filter((probe) => probe.bucket === 'holdout');
+    const negativeProbes = probes.filter((probe) => probe.bucket === 'negative');
+    const anchorPassed = anchorProbes.filter((probe) => probe.pass).length;
+    const holdoutUsable = holdoutProbes.filter((probe) => probe.next_hop_usable === true).length;
+    const negativeFalsePositive = negativeProbes.filter((probe) => probe.false_positive_anchor_leak === true).length;
+    const anchorPassRate = anchorProbes.length > 0 ? anchorPassed / anchorProbes.length : 0;
+    const holdoutUsabilityRate = holdoutProbes.length > 0 ? holdoutUsable / holdoutProbes.length : 0;
+    const negativeFalsePositiveRate = negativeProbes.length > 0 ? negativeFalsePositive / negativeProbes.length : 0;
+    if (anchorProbes.length === 0) {
+        failures.push('anchor_bucket_missing');
+    }
+    if (holdoutProbes.length === 0) {
+        failures.push('holdout_bucket_missing');
+    }
+    if (negativeProbes.length === 0) {
+        failures.push('negative_bucket_missing');
+    }
+    if (anchorProbes.length > 0 && anchorPassRate < 1) {
+        failures.push('anchor_pass_rate_below_threshold');
+    }
+    if (holdoutProbes.length > 0 && holdoutUsabilityRate < 0.85) {
+        failures.push('holdout_next_hop_usability_below_threshold');
+    }
+    if (negativeProbes.length > 0 && negativeFalsePositiveRate > 0.1) {
+        failures.push('negative_false_positive_rate_above_threshold');
+    }
+    const output = {
+        pass: failures.length === 0,
+        failures,
+        metrics: {
+            precision: input.precision,
+            coverage: input.coverage,
+            probe_pass_rate: probePassRate,
+            key_resource_hit_rate: keyResourceProbeCount > 0 ? keyResourceHitCount / keyResourceProbeCount : 0,
+            next_hop_usability_rate: nextHopProbeCount > 0 ? nextHopUsableCount / nextHopProbeCount : 0,
+            hint_drift_rate: hintDriftProbeCount > 0 ? hintDriftCount / hintDriftProbeCount : 0,
+        },
+        bucket_metrics: {
+            anchor: { total: anchorProbes.length, passed: anchorPassed, anchor_pass_rate: anchorPassRate },
+            holdout: { total: holdoutProbes.length, usable: holdoutUsable, next_hop_usability_rate: holdoutUsabilityRate },
+            negative: { total: negativeProbes.length, false_positive: negativeFalsePositive, false_positive_rate: negativeFalsePositiveRate },
+        },
+        threshold_checks: {
+            precision_pass: input.precision >= PRECISION_THRESHOLD,
+            coverage_pass: input.coverage >= COVERAGE_THRESHOLD,
+            probe_pass_rate_pass: probePassRate >= PROBE_PASS_RATE_THRESHOLD,
+            anchor_pass: anchorProbes.length > 0 && anchorPassRate >= 1,
+            holdout_pass: holdoutProbes.length > 0 && holdoutUsabilityRate >= 0.85,
+            negative_pass: negativeProbes.length > 0 && negativeFalsePositiveRate <= 0.1,
+        },
+        probe_results: probes,
+    };
+    if (input.repoPath && input.runId) {
+        const reportPath = path.join(path.resolve(input.repoPath), '.gitnexus', 'rules', 'reports', `${input.runId}-regress.md`);
+        await fs.mkdir(path.dirname(reportPath), { recursive: true });
+        await fs.writeFile(reportPath, buildReportMarkdown(output), 'utf-8');
+        output.reportPath = reportPath;
+    }
+    return output;
+}

package/dist/rule-lab/regress.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rule-lab/regress.test.js

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { runRuleLabRegress } from './regress.js';
+describe('rule-lab regress', () => {
+    it('fails when precision or coverage is below threshold', async () => {
+        const out = await runRuleLabRegress({ precision: 0.85, coverage: 0.92 });
+        expect(out.pass).toBe(false);
+        expect(out.failures).toContain('precision_below_threshold');
+    });
+    it('fails regress when probe pass-rate is below threshold even if metrics are high', async () => {
+        const out = await runRuleLabRegress({
+            precision: 0.95,
+            coverage: 0.95,
+            probes: [
+                { id: 'p1', pass: false, replay_command: 'gitnexus query "Reload"' },
+            ],
+        });
+        expect(out.pass).toBe(false);
+        expect(out.failures).toContain('probe_pass_rate_below_threshold');
+        expect(out.metrics.probe_pass_rate).toBeLessThan(0.85);
+    });
+    it('reports stage-aware metrics and three-bucket threshold checks', async () => {
+        const out = await runRuleLabRegress({
+            precision: 0.95,
+            coverage: 0.9,
+            probes: [
+                {
+                    id: 'anchor-1',
+                    bucket: 'anchor',
+                    pass: true,
+                    replay_command: 'gitnexus query "anchor"',
+                    key_resource_hit: true,
+                    next_hop_usable: true,
+                    hint_drift: false,
+                    false_positive_anchor_leak: false,
+                },
+                {
+                    id: 'holdout-1',
+                    bucket: 'holdout',
+                    pass: true,
+                    replay_command: 'gitnexus query "holdout"',
+                    key_resource_hit: true,
+                    next_hop_usable: true,
+                    hint_drift: false,
+                    false_positive_anchor_leak: false,
+                },
+                {
+                    id: 'negative-1',
+                    bucket: 'negative',
+                    pass: true,
+                    replay_command: 'gitnexus query "negative"',
+                    key_resource_hit: false,
+                    next_hop_usable: false,
+                    hint_drift: false,
+                    false_positive_anchor_leak: false,
+                },
+            ],
+        });
+        expect(out.metrics).toHaveProperty('key_resource_hit_rate');
+        expect(out.metrics).toHaveProperty('next_hop_usability_rate');
+        expect(out.metrics).toHaveProperty('hint_drift_rate');
+        expect(out.bucket_metrics.anchor.anchor_pass_rate).toBe(1);
+        expect(out.bucket_metrics.holdout.next_hop_usability_rate).toBe(1);
+        expect(out.bucket_metrics.negative.false_positive_rate).toBe(0);
+        expect(out.threshold_checks.anchor_pass).toBe(true);
+        expect(out.threshold_checks.holdout_pass).toBe(true);
+        expect(out.threshold_checks.negative_pass).toBe(true);
+    });
+});

package/dist/rule-lab/review-pack.d.ts

@@ -0,0 +1,31 @@
+import { getRuleLabPaths } from './paths.js';
+export interface ReviewPackInput {
+    repoPath: string;
+    runId: string;
+    sliceId: string;
+    maxTokens: number;
+}
+export interface ReviewPackCard {
+    card_id: string;
+    title: string;
+    candidate_ids: string[];
+    decision_inputs: {
+        required_hops: string[];
+        failure_map: Record<string, string>;
+        guarantees: string[];
+        non_guarantees: string[];
+    };
+}
+export interface ReviewPackMeta {
+    token_budget: number;
+    token_budget_estimate: number;
+    truncated: boolean;
+    total_candidates: number;
+    included_candidates: number;
+}
+export interface ReviewPackOutput {
+    paths: ReturnType<typeof getRuleLabPaths>;
+    meta: ReviewPackMeta;
+    cards: ReviewPackCard[];
+}
+export declare function buildReviewPack(input: ReviewPackInput): Promise<ReviewPackOutput>;

package/dist/rule-lab/review-pack.js

@@ -0,0 +1,125 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getRuleLabPaths } from './paths.js';
+function estimateTokens(value) {
+    return Math.ceil(JSON.stringify(value).length / 4);
+}
+function parseCandidates(raw) {
+    return raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+function unique(values) {
+    return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
+}
+function mergeFailureMaps(candidates) {
+    const out = {};
+    for (const candidate of candidates) {
+        const failureMap = candidate.closure?.failure_map || {};
+        for (const [key, value] of Object.entries(failureMap)) {
+            if (String(key || '').trim() && String(value || '').trim()) {
+                out[key] = value;
+            }
+        }
+    }
+    return out;
+}
+function collectRequiredHops(candidates) {
+    const fromClosure = candidates.flatMap((candidate) => {
+        const closure = candidate.closure;
+        return Array.isArray(closure?.required_hops) ? closure.required_hops : [];
+    });
+    if (fromClosure.length > 0)
+        return unique(fromClosure);
+    return unique(candidates.flatMap((candidate) => (candidate.topology || []).map((hop) => hop.hop)));
+}
+function collectClaims(candidates) {
+    const guarantees = unique(candidates.flatMap((candidate) => {
+        const claims = candidate.claims;
+        return Array.isArray(claims?.guarantees) ? claims.guarantees : [];
+    }));
+    const nonGuarantees = unique(candidates.flatMap((candidate) => {
+        const claims = candidate.claims;
+        return Array.isArray(claims?.non_guarantees) ? claims.non_guarantees : [];
+    }));
+    return {
+        guarantees,
+        non_guarantees: nonGuarantees,
+    };
+}
+function buildCards(candidates) {
+    const cards = [];
+    const chunkSize = 4;
+    for (let i = 0; i < candidates.length; i += chunkSize) {
+        const chunk = candidates.slice(i, i + chunkSize);
+        const claims = collectClaims(chunk);
+        cards.push({
+            card_id: `card-${Math.floor(i / chunkSize) + 1}`,
+            title: `Rule Lab Card ${Math.floor(i / chunkSize) + 1}`,
+            candidate_ids: chunk.map((item) => item.id),
+            decision_inputs: {
+                required_hops: collectRequiredHops(chunk),
+                failure_map: mergeFailureMaps(chunk),
+                guarantees: claims.guarantees,
+                non_guarantees: claims.non_guarantees,
+            },
+        });
+    }
+    return cards;
+}
+function renderReviewPack(meta, cards) {
+    const lines = [];
+    lines.push('# Rule Lab Review Pack');
+    lines.push('');
+    lines.push('## Meta');
+    lines.push(`- token_budget: ${meta.token_budget}`);
+    lines.push(`- token_budget_estimate: ${meta.token_budget_estimate}`);
+    lines.push(`- truncated: ${meta.truncated}`);
+    lines.push(`- total_candidates: ${meta.total_candidates}`);
+    lines.push(`- included_candidates: ${meta.included_candidates}`);
+    lines.push('');
+    for (const card of cards) {
+        lines.push(`## ${card.title}`);
+        lines.push(`- card_id: ${card.card_id}`);
+        lines.push(`- candidate_ids: ${card.candidate_ids.join(', ')}`);
+        lines.push(`- required_hops: ${card.decision_inputs.required_hops.join(', ')}`);
+        lines.push(`- guarantees: ${card.decision_inputs.guarantees.join(', ')}`);
+        lines.push(`- non_guarantees: ${card.decision_inputs.non_guarantees.join(', ')}`);
+        lines.push(`- failure_map: ${JSON.stringify(card.decision_inputs.failure_map)}`);
+        lines.push('');
+    }
+    return `${lines.join('\n')}\n`;
+}
+export async function buildReviewPack(input) {
+    const normalizedRepoPath = path.resolve(input.repoPath);
+    const paths = getRuleLabPaths(normalizedRepoPath, input.runId, input.sliceId);
+    const raw = await fs.readFile(paths.candidatesPath, 'utf-8');
+    const candidates = parseCandidates(raw);
+    const included = [];
+    let tokenEstimate = 0;
+    for (const candidate of candidates) {
+        const nextTokens = estimateTokens(candidate);
+        if (tokenEstimate + nextTokens > input.maxTokens) {
+            break;
+        }
+        included.push(candidate);
+        tokenEstimate += nextTokens;
+    }
+    const meta = {
+        token_budget: input.maxTokens,
+        token_budget_estimate: tokenEstimate,
+        truncated: included.length < candidates.length,
+        total_candidates: candidates.length,
+        included_candidates: included.length,
+    };
+    const cards = buildCards(included);
+    await fs.mkdir(path.dirname(paths.reviewCardsPath), { recursive: true });
+    await fs.writeFile(paths.reviewCardsPath, renderReviewPack(meta, cards), 'utf-8');
+    return {
+        paths,
+        meta,
+        cards,
+    };
+}

package/dist/rule-lab/review-pack.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rule-lab/review-pack.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { buildReviewPack } from './review-pack.js';
+describe('rule-lab review-pack', () => {
+    it('splits cards to keep token budget <= 6000', async () => {
+        const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'rule-lab-review-pack-'));
+        const sliceDir = path.join(repoRoot, '.gitnexus', 'rules', 'lab', 'runs', 'run-x', 'slices', 'slice-a');
+        await fs.mkdir(sliceDir, { recursive: true });
+        const candidate = {
+            id: 'cand-1',
+            title: 'reload candidate',
+            topology: [
+                {
+                    hop: 'resource',
+                    from: { entity: 'resource' },
+                    to: { entity: 'script' },
+                    edge: { kind: 'binds_script' },
+                },
+            ],
+            closure: {
+                required_hops: ['resource'],
+                failure_map: { missing_evidence: 'rule_matched_but_evidence_missing' },
+            },
+            claims: {
+                guarantees: ['reload_chain_closed'],
+                non_guarantees: ['no_runtime_execution'],
+            },
+            evidence: {
+                hops: [
+                    { hop_type: 'resource', anchor: 'Assets/Example.prefab:42', snippet: 'ReloadGraph' },
+                ],
+            },
+        };
+        const lines = Array.from({ length: 12 }).map((_, i) => JSON.stringify({ ...candidate, id: `cand-${i}` }));
+        await fs.writeFile(path.join(sliceDir, 'candidates.jsonl'), `${lines.join('\n')}\n`, 'utf-8');
+        const out = await buildReviewPack({ repoPath: repoRoot, runId: 'run-x', sliceId: 'slice-a', maxTokens: 6000 });
+        expect(out.meta.token_budget_estimate).toBeLessThanOrEqual(6000);
+        expect(out.meta.truncated || out.cards.length > 0).toBe(true);
+        expect(out.cards[0]).toHaveProperty('decision_inputs.required_hops');
+        expect(out.cards[0]).toHaveProperty('decision_inputs.failure_map');
+        expect(out.cards[0]).toHaveProperty('decision_inputs.guarantees');
+        expect(out.cards[0]).toHaveProperty('decision_inputs.non_guarantees');
+        const persisted = await fs.readFile(out.paths.reviewCardsPath, 'utf-8');
+        expect(persisted).toContain('token_budget_estimate');
+        await fs.rm(repoRoot, { recursive: true, force: true });
+    });
+});