@jagilber-org/index-server 1.19.1

package/dist/services/handlers.graph.js

@@ -0,0 +1,231 @@
+"use strict";
+// Instruction Graph Export Handler
+// Phase 1 minimal deterministic implementation to satisfy graphExport.spec.ts.
+// Provides a structural graph representation of the current instruction index with:
+//  - Deterministic node ordering (alphabetical by id)
+//  - Two edge types: 'primary' (instruction -> primaryCategory) and 'category' (pairwise co-category)
+//  - Optional exclusion of primary edges via env GRAPH_INCLUDE_PRIMARY_EDGES=0
+//  - Large category pairwise edge skip with note when size exceeds GRAPH_LARGE_CATEGORY_CAP (default: no cap)
+//  - includeEdgeTypes filter (applied before truncation)
+//  - maxEdges truncation (stable ordering then slice)
+//  - format:'dot' emits Graphviz DOT output (undirected graph)
+//  - Shallow caching for default parameter calls (returns identical object reference until index hash changes)
+//  - meta: { graphSchemaVersion:1, nodeCount, edgeCount, truncated?, notes?[] }
+// NOTE: This is intentionally dependency-light; future phases can enrich node/edge metadata.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGraph = buildGraph;
+exports.__resetGraphCache = __resetGraphCache;
+const registry_1 = require("../server/registry");
+const indexContext_1 = require("./indexContext");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// NOTE: For enriched responses we bump schema version to 2 (only when enrich=true)
+const GRAPH_SCHEMA_VERSION_V1 = 1;
+const GRAPH_SCHEMA_VERSION_V2 = 2;
+// Cache now also considers environment-dependent knobs so toggling env vars between tests
+// (e.g. disabling primary edges or applying a large category cap) does not incorrectly
+// reuse a prior result built under different environmental semantics.
+// We keep a small cache map for default param invocations (no format/includeEdgeTypes/maxEdges) keyed by envSig.
+// Each entry invalidated when governance hash changes. Explicit env overrides still bypass caching (determinism focus).
+const cachedDefaults = new Map(); // v1 only cache
+// Exported for dashboard API usage
+function buildGraph(params, graphCfg = (0, runtimeConfig_1.getRuntimeConfig)().graph) {
+    const { includeEdgeTypes, maxEdges, format, enrich, includeCategoryNodes, includeUsage } = params;
+    const st = (0, indexContext_1.ensureLoaded)();
+    const instructions = [...st.list].sort((a, b) => a.id.localeCompare(b.id));
+    const enriched = !!enrich;
+    // Build base instruction nodes (schema-dependent)
+    const nodes = instructions.map(i => {
+        if (!enriched) {
+            return { id: i.id };
+        }
+        const inst = i;
+        const n = {
+            id: i.id,
+            nodeType: 'instruction',
+            categories: Array.isArray(i.categories) ? [...i.categories] : [],
+            primaryCategory: i.primaryCategory || i.categories?.[0],
+            priority: typeof i.priority === 'number' ? i.priority : undefined,
+            priorityTier: inst.priorityTier,
+            requirement: inst.requirement,
+            owner: inst.owner,
+            status: inst.status,
+            createdAt: inst.createdAt,
+            updatedAt: inst.updatedAt,
+        };
+        if (includeUsage) {
+            const usageVal = i.usageCount;
+            n.usageCount = usageVal != null ? usageVal : 0; // real value or 0 fallback
+        }
+        return n;
+    });
+    const includePrimary = graphCfg.includePrimaryEdges;
+    const largeCap = graphCfg.largeCategoryCap;
+    const edges = [];
+    const notes = [];
+    // Primary edges (instruction -> pseudo-node named primaryCategory).
+    // We do not currently add category nodes; tests only assert edge.type membership.
+    if (includePrimary) {
+        for (const inst of instructions) {
+            const primary = inst.primaryCategory || inst.categories?.[0];
+            if (primary) {
+                // In enriched+categoryNodes mode, primary edge points to category node id to unify references
+                const toId = (enriched && includeCategoryNodes) ? `category:${primary}` : `${primary}`;
+                const edge = { from: inst.id, to: toId, type: 'primary' };
+                if (enriched)
+                    edge.weight = 1;
+                edges.push(edge);
+            }
+        }
+    }
+    // Category pairwise edges (instruction id pairs that share a category)
+    // Build index of category -> instruction ids
+    const catMap = new Map();
+    for (const inst of instructions) {
+        const cats = Array.isArray(inst.categories) ? inst.categories : [];
+        for (const c of cats) {
+            const lc = c.toLowerCase();
+            let arr = catMap.get(lc);
+            if (!arr) {
+                arr = [];
+                catMap.set(lc, arr);
+            }
+            arr.push(inst.id);
+        }
+    }
+    const sortedCategories = [...catMap.keys()].sort((a, b) => a.localeCompare(b));
+    for (const cat of sortedCategories) {
+        const ids = catMap.get(cat);
+        ids.sort((a, b) => a.localeCompare(b));
+        if (ids.length > largeCap) {
+            if (Number.isFinite(largeCap)) {
+                notes.push(`skipped pairwise for category '${cat}' size=${ids.length} cap=${largeCap}`);
+            }
+            continue;
+        }
+        // Pairwise category edges remain for backward compatibility even when category nodes materialized
+        for (let i = 0; i < ids.length; i++) {
+            for (let j = i + 1; j < ids.length; j++) {
+                const edge = { from: ids[i], to: ids[j], type: 'category' };
+                if (enriched)
+                    edge.weight = 1;
+                edges.push(edge);
+            }
+        }
+    }
+    // Optional category nodes & belongs edges (enriched mode only)
+    if (enriched && includeCategoryNodes) {
+        const allCats = sortedCategories; // already sorted
+        for (const cat of allCats) {
+            nodes.push({ id: `category:${cat}`, nodeType: 'category' });
+        }
+        // belongs edges: instruction -> category node
+        for (const inst of instructions) {
+            const cats = Array.isArray(inst.categories) ? inst.categories : [];
+            for (const c of cats) {
+                const edge = { from: inst.id, to: `category:${c}`, type: 'belongs' };
+                edge.weight = 1;
+                edges.push(edge);
+            }
+        }
+    }
+    // Filter edge types before truncation
+    let finalEdges = edges;
+    if (includeEdgeTypes && includeEdgeTypes.length) {
+        const allowed = new Set(includeEdgeTypes);
+        finalEdges = edges.filter(e => allowed.has(e.type));
+    }
+    let truncated = false;
+    if (typeof maxEdges === 'number' && maxEdges >= 0 && finalEdges.length > maxEdges) {
+        finalEdges = finalEdges.slice(0, maxEdges);
+        truncated = true;
+    }
+    const meta = { graphSchemaVersion: (enriched ? GRAPH_SCHEMA_VERSION_V2 : GRAPH_SCHEMA_VERSION_V1), nodeCount: nodes.length, edgeCount: finalEdges.length };
+    if (truncated)
+        meta.truncated = true;
+    if (notes.length)
+        meta.notes = notes;
+    const result = { meta, nodes, edges: finalEdges };
+    if (format === 'dot') {
+        // Simple undirected DOT format representation. Include all nodes (instructions + optional category nodes)
+        const lines = ['graph Instructions {'];
+        for (const n of nodes) {
+            lines.push(`  "${n.id}";`);
+        }
+        for (const e of finalEdges) {
+            lines.push(`  "${e.from}" -- "${e.to}" [label="${e.type}"];`);
+        }
+        lines.push('}');
+        result.dot = lines.join('\n');
+    }
+    else if (format === 'mermaid') {
+        // Mermaid undirected graph (flowchart) representation.
+        // We use a simple flowchart with -- links and edge type labels.
+        // Mermaid v10+ requires a direction (TB/LR/RL/BT); previous placeholder 'undirected' caused syntax errors.
+        // Using 'flowchart TB' (top-bottom) while edges use '---' (no arrow) to visually appear undirected.
+        const lines = ['flowchart TB'];
+        for (const n of nodes) {
+            // Escape minimal invalid chars (leave colon and hyphen intact)
+            const safeId = n.id.replace(/[^A-Za-z0-9_:.-]/g, '_');
+            lines.push(`${safeId}["${n.id}"]`);
+        }
+        for (const e of finalEdges) {
+            const fromSafe = e.from.replace(/[^A-Za-z0-9_:.-]/g, '_');
+            const toSafe = e.to.replace(/[^A-Za-z0-9_:.-]/g, '_');
+            lines.push(`${fromSafe} ---|${e.type}| ${toSafe}`);
+        }
+        const mermaidBody = lines.join('\n');
+        // Provide standard YAML frontmatter with theme + layout + themeVariables so tests can assert presence
+        // independent of client dashboard augmentation. Keep single themeVariables block.
+        const fm = [
+            '---',
+            'config:',
+            '  theme: base',
+            '  layout: elk',
+            '  themeVariables:',
+            "    primaryColor: '#58a6ff'",
+            "    primaryTextColor: '#f0f6fc'",
+            "    primaryBorderColor: '#30363d'",
+            "    lineColor: '#484f58'",
+            "    secondaryColor: '#21262d'",
+            "    tertiaryColor: '#161b22'",
+            "    background: '#0d1117'",
+            "    mainBkg: '#161b22'",
+            "    secondBkg: '#21262d'",
+            '---'
+        ].join('\n');
+        result.mermaid = fm + '\n' + mermaidBody;
+    }
+    return result;
+}
+(0, registry_1.registerHandler)('graph_export', (params) => {
+    const p = params || {};
+    const cacheEligible = !p.enrich && !p.format && !p.includeEdgeTypes && (p.maxEdges === undefined);
+    // If either env knob is explicitly set we skip caching to avoid cross-test flakiness where
+    // suites toggle values. Determinism > micro perf for explicit env usage.
+    const graphCfg = (0, runtimeConfig_1.getRuntimeConfig)().graph;
+    const envExplicit = graphCfg.explicitIncludePrimaryEnv || graphCfg.explicitLargeCategoryEnv;
+    const st = (0, indexContext_1.ensureLoaded)();
+    const hash = st.hash || (0, indexContext_1.computeGovernanceHash)(st.list);
+    const envSig = graphCfg.signature;
+    if (cacheEligible && !envExplicit) {
+        const entry = cachedDefaults.get(envSig);
+        if (entry && entry.hash === hash) {
+            return entry.result;
+        }
+    }
+    const graph = buildGraph(p, graphCfg);
+    // Defensive: unexpected undefined safeguard (should never happen). Emit diagnostic once.
+    if (!graph) {
+        // eslint-disable-next-line no-console
+        console.error('[graph_export] buildGraph returned undefined - returning empty graph (diagnostic)');
+        return { meta: { graphSchemaVersion: 1, nodeCount: 0, edgeCount: 0 }, nodes: [], edges: [] };
+    }
+    if (cacheEligible && !envExplicit) {
+        cachedDefaults.set(envSig, { hash, result: graph });
+    }
+    return graph;
+});
+// Test-only helper (not registered as a tool) to clear cached default between suites.
+// Exported with a leading double underscore to discourage production usage.
+function __resetGraphCache() { cachedDefaults.clear(); }
+// Future phases: enrich node metadata (categories, priority, usage metrics), provenance, and export adapters.

package/dist/services/handlers.help.d.ts

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

package/dist/services/handlers.help.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Onboarding / Help Handlers
+ *
+ * Provides a stable read-only tool 'help_overview' that returns structured
+ * onboarding guidance so a naive / first-time agent can self-bootstrap:
+ * - Discover tools & their purpose
+ * - Understand local (P0) vs indexed (P1+) lifecycle & promotion workflow
+ * - Learn safe mutation enabling pattern (INDEX_SERVER_MUTATION)
+ * - Follow a deterministic promotion checklist
+ * - Avoid governance/spec recursion (documents intentionally NOT ingested)
+ */
+const registry_1 = require("../server/registry");
+const toolRegistry_1 = require("./toolRegistry");
+const indexContext_1 = require("./indexContext");
+const HELP_VERSION = '2025-09-14';
+function buildSections() {
+    return [
+        {
+            id: 'intro',
+            title: 'Welcome',
+            content: 'This server exposes a governance-aware instruction index and supporting MCP tools. Use this overview to learn discovery, lifecycle tiers, and safe promotion patterns.'
+        },
+        {
+            id: 'discovery',
+            title: 'Tool Discovery Flow',
+            content: 'Initialize (initialize), then enumerate capabilities via meta_tools or tools/list. Call help_overview for structured guidance before attempting mutations.',
+            bullets: [
+                'initialize → tools/call meta_tools → tools/call help_overview',
+                'index_dispatch (action=list) to enumerate index entries',
+                'index_schema for instruction JSON schema + examples + validation rules',
+                'index_governanceHash for deterministic governance projection',
+                'index_health to assess drift & recursionRisk'
+            ],
+            nextActions: ['Call meta_tools', 'Call help_overview', 'Call index_schema', 'List index via index_dispatch {action:list}']
+        },
+        {
+            id: 'lifecycle',
+            title: 'Lifecycle Tiers',
+            content: 'Instructions progress from local experimental (P0) to indexed stable (P1+) via explicit promotion. Governance documents (constitution, specs) are excluded from ingestion to prevent recursion.',
+            bullets: [
+                'P0 Local: workspace-specific, rapid iteration, not shareable',
+                'P1 Indexed: canonical, versioned, governance-compliant',
+                'Higher tiers (P2+): optional refinement / broader distribution',
+                'Denylist prevents governance/spec ingestion (see recursionRisk metric)'
+            ]
+        },
+        {
+            id: 'promotion',
+            title: 'Promotion Checklist',
+            content: 'Before promoting a P0 instruction to index ensure quality, clarity, and uniqueness benchmarks are satisfied.',
+            bullets: [
+                'Clarity: concise title + semantic summary',
+                'Accuracy: verified against current repo state',
+                'Value: non-duplicative & materially helpful',
+                'Maintainability: minimal volatile references',
+                'Classification & priorityTier assigned',
+                'Owner + review cadence set (lastReviewedAt/nextReviewDue)',
+                'ChangeLog initialized if version > 1'
+            ],
+            nextActions: ['Run prompt_review for large bodies', 'Run integrity_verify', 'Submit via index_add']
+        },
+        {
+            id: 'mutation-safety',
+            title: 'Safe Mutation',
+            content: 'All write operations require INDEX_SERVER_MUTATION=1. Without it, mutation tools return disabled errors ensuring read-only safety by default.'
+        },
+        {
+            id: 'recursion-safeguards',
+            title: 'Recursion Safeguards',
+            content: 'Loader denylist excludes governance/spec seeds. index_health exposes recursionRisk and leakage metrics; expected value is recursionRisk=none.'
+        },
+        {
+            id: 'next-steps',
+            title: 'Suggested Next Steps',
+            content: 'Follow these steps to integrate effectively.',
+            bullets: [
+                '1. Fetch meta_tools and record stable tools',
+                '2. Call index_schema for instruction format guidance',
+                '3. List index entries (index_dispatch list)',
+                '4. Track usage for relevant instructions (usage_track)',
+                '5. Draft local P0 improvements in a separate directory',
+                '6. Evaluate with prompt_review & integrity_verify',
+                '7. Promote via index_add (with mutation enabled)',
+                '8. Monitor drift via index_health and governanceHash'
+            ]
+        }
+    ];
+}
+(0, registry_1.registerHandler)('help_overview', () => {
+    const registry = (0, toolRegistry_1.getToolRegistry)({ tier: 'admin' }).map(t => t.name);
+    const idx = (0, indexContext_1.getIndexState)();
+    return {
+        generatedAt: new Date().toISOString(),
+        version: HELP_VERSION,
+        summary: 'Structured onboarding guidance for new agents: discovery → lifecycle → promotion → safety.',
+        sections: buildSections(),
+        toolDiscovery: {
+            primary: registry.filter(n => !n.startsWith('diagnostics/')),
+            diagnostics: registry.filter(n => n.startsWith('diagnostics/'))
+        },
+        lifecycleModel: {
+            tiers: [
+                { tier: 'P0', purpose: 'Local experimental / workspace-scoped, not indexed' },
+                { tier: 'P1', purpose: 'Indexed baseline, governance compliant' },
+                { tier: 'P2', purpose: 'Refined / broader consumption (optional)' }
+            ],
+            promotionChecklist: [
+                'Ensure uniqueness (no near-duplicate id/body)',
+                'Provide semantic summary & owner',
+                'Assign priorityTier & classification',
+                'Set review dates',
+                'Pass integrity_verify and governanceHash stable'
+            ]
+        },
+        index: { count: idx.list.length, hash: idx.hash }
+    };
+});

package/dist/services/handlers.instructionSchema.d.ts

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

package/dist/services/handlers.instructionSchema.js

@@ -0,0 +1,227 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Instruction Schema Handler
+ *
+ * Provides self-documentation tool 'index_schema' that returns:
+ * - Full JSON schema for instruction entries
+ * - Minimal example template
+ * - Validation rules and constraints
+ * - Field descriptions and requirements
+ *
+ * Addresses Priority 2.1: Self-documentation of instruction schema format
+ * Source: Production feedback entry 1967100008b4b465 (2026-01-25)
+ */
+const registry_1 = require("../server/registry");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const SCHEMA_VERSION = '1.0.0';
+/**
+ * Load the canonical instruction.schema.json from disk
+ */
+function loadInstructionSchema() {
+    const schemaPath = path.join(__dirname, '../../schemas/instruction.schema.json');
+    return JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+}
+/**
+ * Build a minimal valid instruction entry template
+ */
+function buildMinimalExample() {
+    return {
+        id: "example-instruction-id",
+        title: "Example Instruction Title",
+        body: "Detailed instruction content goes here. This is the primary guidance text that agents will follow.\n\nYou can use markdown formatting for clarity.",
+        priority: 50,
+        audience: "all",
+        requirement: "recommended",
+        categories: ["example", "documentation"],
+        primaryCategory: "example",
+        contentType: "instruction",
+        schemaVersion: "4"
+    };
+}
+/**
+ * Build a comprehensive example with governance metadata
+ */
+function _buildComprehensiveExample() {
+    return {
+        id: "comprehensive-example-id",
+        title: "Comprehensive Example with Governance",
+        body: "This example shows all recommended fields for a complete instruction.\n\n## Purpose\nDescribe the purpose and context.\n\n## Usage\nProvide specific usage guidance.\n\n## Examples\nInclude concrete examples.",
+        rationale: "Optional rationale explaining why this instruction exists and what problem it solves.",
+        priority: 30,
+        audience: "all",
+        requirement: "recommended",
+        categories: ["example", "documentation", "governance"],
+        primaryCategory: "governance",
+        contentType: "instruction",
+        schemaVersion: "4",
+        version: "1.0.0",
+        status: "approved",
+        owner: "platform-team",
+        priorityTier: "P2",
+        classification: "internal",
+        reviewIntervalDays: 90,
+        semanticSummary: "Example instruction demonstrating comprehensive governance metadata and best practices.",
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        lastReviewedAt: new Date().toISOString(),
+        nextReviewDue: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString()
+    };
+}
+/**
+ * Define promotion workflow stages
+ */
+function definePromotionWorkflow() {
+    return [
+        {
+            stage: 'P0: Local Development',
+            description: 'Workspace-specific experimental instruction, not indexed',
+            checklistItems: [
+                'Create instruction file in local workspace directory',
+                'Include required fields: id, title, body, priority, audience, requirement, categories',
+                'Test locally with index_dispatch {action: "query", id: "your-id"}',
+                'Iterate rapidly without governance overhead'
+            ]
+        },
+        {
+            stage: 'P1: Pre-Promotion Review',
+            description: 'Quality checks before indexing',
+            checklistItems: [
+                'Ensure uniqueness: no duplicate id or near-duplicate body',
+                'Add semantic summary (semanticSummary field)',
+                'Assign owner and classification',
+                'Set priorityTier (P1/P2/P3/P4)',
+                'Run prompt_review for large bodies to check quality',
+                'Run integrity_verify to confirm no drift',
+                'Establish review cadence (lastReviewedAt, nextReviewDue, reviewIntervalDays)'
+            ]
+        },
+        {
+            stage: 'P1: Indexed Baseline',
+            description: 'Canonical, versioned, governance-compliant instruction',
+            checklistItems: [
+                'Submit via index_dispatch {action: "add", ...}',
+                'Verify instruction appears in index_dispatch {action: "list"}',
+                'Monitor index_health for recursionRisk=none',
+                'Track usage with usage_track',
+                'Maintain via index_dispatch {action: "update"} as needed'
+            ]
+        },
+        {
+            stage: 'P2+: Optional Refinement',
+            description: 'Broader distribution and enhanced governance',
+            checklistItems: [
+                'Accumulate usage metrics over multiple sessions',
+                'Demonstrate cross-category or cross-team relevance',
+                'Bump priorityTier if warranted',
+                'Initialize changeLog for version tracking',
+                'Consider promotion to higher tier (P2, P3, etc.)'
+            ]
+        }
+    ];
+}
+/**
+ * Define key validation rules
+ */
+function defineValidationRules() {
+    return [
+        { field: 'id', rule: 'Pattern', constraint: '^[a-z0-9](?:[a-z0-9-_]{0,118}[a-z0-9])?$ (120 chars max, lowercase, no leading/trailing hyphen/underscore)' },
+        { field: 'id', rule: 'Uniqueness', constraint: 'Must be unique across the index' },
+        { field: 'title', rule: 'Length', constraint: '1-200 characters, non-empty' },
+        { field: 'body', rule: 'Length', constraint: '1-20,000 characters, markdown supported' },
+        { field: 'priority', rule: 'Range', constraint: '1-100 (lower number = higher priority)' },
+        { field: 'audience', rule: 'Enum', constraint: 'One of: individual, group, all' },
+        { field: 'requirement', rule: 'Enum', constraint: 'One of: mandatory, critical, recommended, optional, deprecated' },
+        { field: 'categories', rule: 'Array', constraint: '0-25 items, each 1-49 chars, lowercase, pattern: ^[a-z0-9][a-z0-9-_]{0,48}$' },
+        { field: 'primaryCategory', rule: 'Reference', constraint: 'Must be a member of categories array if present' },
+        { field: 'contentType', rule: 'Enum', constraint: 'One of: instruction (default), template, chat-session, reference, example, agent' },
+        { field: 'schemaVersion', rule: 'Enum', constraint: 'Currently "4"' },
+        { field: 'sourceHash', rule: 'Pattern', constraint: 'SHA256 hex string (64 chars) when present' },
+        { field: 'version', rule: 'Pattern', constraint: 'Semantic version: ^\\d+\\.\\d+\\.\\d+$ (e.g., "1.0.0")' },
+        { field: 'status', rule: 'Enum', constraint: 'One of: draft, review, approved, deprecated' },
+        { field: 'priorityTier', rule: 'Enum', constraint: 'One of: P1, P2, P3, P4' },
+        { field: 'classification', rule: 'Enum', constraint: 'One of: public, internal, restricted' },
+        { field: 'reviewIntervalDays', rule: 'Range', constraint: '1-365 days' }
+    ];
+}
+(0, registry_1.registerHandler)('index_schema', () => {
+    const schema = loadInstructionSchema();
+    const response = {
+        generatedAt: new Date().toISOString(),
+        version: SCHEMA_VERSION,
+        summary: 'Instruction schema template with validation rules, examples, and promotion workflow guidance.',
+        schema,
+        minimalExample: buildMinimalExample(),
+        requiredFields: [
+            'id',
+            'title',
+            'body',
+            'priority',
+            'audience',
+            'requirement',
+            'categories'
+        ],
+        optionalFieldsCommon: [
+            'rationale',
+            'primaryCategory',
+            'contentType',
+            'schemaVersion',
+            'version',
+            'status',
+            'owner',
+            'priorityTier',
+            'classification',
+            'semanticSummary',
+            'reviewIntervalDays',
+            'lastReviewedAt',
+            'nextReviewDue'
+        ],
+        promotionWorkflow: definePromotionWorkflow(),
+        validationRules: defineValidationRules(),
+        nextSteps: [
+            '1. Review the minimalExample for required fields',
+            '2. Study promotionWorkflow stages (P0 → P1 → P2+)',
+            '3. Validate against validationRules before submission',
+            '4. Use index_dispatch {action: "add"} to create (requires INDEX_SERVER_MUTATION=1)',
+            '5. Monitor index_health for recursionRisk and drift',
+            '6. Track usage with usage_track',
+            '7. Iterate via index_dispatch {action: "update"} as needed',
+            '8. Consult help_overview for broader lifecycle guidance'
+        ]
+    };
+    return response;
+});

package/dist/services/handlers.instructions.d.ts

@@ -0,0 +1,8 @@
+import './handlers/instructions.add';
+import './handlers/instructions.import';
+import './handlers/instructions.remove';
+import './handlers/instructions.patch';
+import './handlers/instructions.reload';
+import './handlers/instructions.groom';
+import './handlers/instructions.query';
+export { instructionActions } from './handlers/instructions.query';

package/dist/services/handlers.instructions.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instructionActions = void 0;
+// handlers.instructions.ts — barrel re-export (thin coordinator)
+require("./handlers/instructions.add");
+require("./handlers/instructions.import");
+require("./handlers/instructions.remove");
+require("./handlers/instructions.patch");
+require("./handlers/instructions.reload");
+require("./handlers/instructions.groom");
+require("./handlers/instructions.query");
+// Re-export instructionActions for instructions.dispatcher.ts back-compat
+var instructions_query_1 = require("./handlers/instructions.query");
+Object.defineProperty(exports, "instructionActions", { enumerable: true, get: function () { return instructions_query_1.instructionActions; } });

package/dist/services/handlers.instructionsDiagnostics.d.ts

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

package/dist/services/handlers.instructionsDiagnostics.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const registry_1 = require("../server/registry");
+const indexContext_1 = require("./indexContext");
+// Read-only diagnostics tool exposing loader acceptance vs rejection reasoning.
+// Stable, side-effect free. Optional includeTrace param surfaces a capped trace sample.
+(0, registry_1.registerHandler)('index_diagnostics', (p = {}) => {
+    try {
+        return (0, indexContext_1.getIndexDiagnostics)({ includeTrace: !!p.includeTrace });
+    }
+    catch (e) {
+        return { error: e?.message || 'diagnostics-failed' };
+    }
+});

package/dist/services/handlers.integrity.d.ts

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

package/dist/services/handlers.integrity.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registry_1 = require("../server/registry");
+const indexContext_1 = require("./indexContext");
+const features_1 = require("./features");
+(0, registry_1.registerHandler)('integrity_verify', () => { const st = (0, indexContext_1.ensureLoaded)(); const issues = []; for (const e of st.list) {
+    const actual = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+    if (actual !== e.sourceHash)
+        issues.push({ id: e.id, expected: e.sourceHash, actual });
+} return { hash: st.hash, count: st.list.length, issues, issueCount: issues.length }; });
+(0, registry_1.registerHandler)('integrity_manifest', () => { const manifestPath = path_1.default.join(process.cwd(), 'snapshots', 'index-manifest.json'); if (!fs_1.default.existsSync(manifestPath))
+    return { manifest: 'missing' }; let manifest; try {
+    manifest = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
+}
+catch (e) {
+    return { manifest: 'invalid', error: e instanceof Error ? e.message : String(e) };
+} const entries = Array.isArray(manifest.entries) ? manifest.entries : []; const map = new Map(entries.map(e => [e.id, e])); const st = (0, indexContext_1.ensureLoaded)(); const drift = []; for (const e of st.list) {
+    const entry = map.get(e.id);
+    const bodyHash = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+    if (!entry)
+        drift.push({ id: e.id, change: 'added' });
+    else if (entry.sourceHash !== e.sourceHash || entry.bodyHash !== bodyHash)
+        drift.push({ id: e.id, change: 'hash-mismatch' });
+} for (const id of map.keys()) {
+    if (!st.byId.has(id))
+        drift.push({ id, change: 'removed' });
+} return { manifest: 'present', drift: drift.length, details: drift }; });
+// Phase 0: feature flags status
+(0, registry_1.registerHandler)('feature_status', () => (0, features_1.featureStatus)());