instar 0.9.11 → 0.9.13

package/dist/core/CoherenceGate.js

@@ -0,0 +1,347 @@
+/**
+ * Coherence Gate — Pre-action verification for agent coherence.
+ *
+ * Before high-risk actions (deployment, git push, external API calls),
+ * the agent pauses to verify: "Am I in the right project? Does this
+ * action match my identity and mission?"
+ *
+ * Born from the Luna incident (2026-02-25): An agent deployed to the
+ * wrong production target because nothing validated that the intended
+ * action matched the agent's current context.
+ *
+ * Design principle: Not a dumb pattern match — an intelligent
+ * self-verification that gives the agent the ability to step back,
+ * review what it's doing, and catch incoherence before it manifests.
+ *
+ * Three verification levels:
+ * 1. Structural — git remote, working directory, project name match
+ * 2. Contextual — action aligns with current topic/conversation scope
+ * 3. Intent — action aligns with stated mission/boundaries in AGENT.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+export class CoherenceGate {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Run a full coherence check for a proposed action.
+     */
+    check(action, context) {
+        const checks = [];
+        // Check 1: Working directory matches expected project
+        checks.push(this.checkWorkingDirectory());
+        // Check 2: Git remote matches expected project
+        checks.push(this.checkGitRemote());
+        // Check 3: If topic is specified, verify topic-project alignment
+        if (context?.topicId) {
+            checks.push(this.checkTopicProjectAlignment(context.topicId));
+        }
+        // Check 4: If deploying, verify deployment target
+        if ((action === 'deploy' || action === 'production-change') && context?.targetUrl) {
+            checks.push(this.checkDeploymentTarget(context.targetUrl, context.topicId));
+        }
+        // Check 5: If modifying files, verify path is within project scope
+        if (context?.targetPath) {
+            checks.push(this.checkPathScope(context.targetPath));
+        }
+        // Check 6: Agent identity consistency
+        checks.push(this.checkAgentIdentity());
+        // Determine overall result
+        const hasErrors = checks.some(c => !c.passed && c.severity === 'error');
+        const hasWarnings = checks.some(c => !c.passed && c.severity === 'warning');
+        const passed = !hasErrors;
+        const recommendation = hasErrors ? 'block' : hasWarnings ? 'warn' : 'proceed';
+        const failedChecks = checks.filter(c => !c.passed);
+        const summary = passed
+            ? `All ${checks.length} coherence checks passed.`
+            : `${failedChecks.length}/${checks.length} checks failed: ${failedChecks.map(c => c.message).join('; ')}`;
+        return {
+            passed,
+            checks,
+            summary,
+            recommendation,
+            checkedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Generate a self-verification prompt for the agent to reflect before acting.
+     * This is the "step back and review" mechanism.
+     */
+    generateReflectionPrompt(action, context) {
+        const result = this.check(action, context);
+        const lines = [];
+        lines.push('=== PRE-ACTION COHERENCE CHECK ===');
+        lines.push('');
+        lines.push('Before proceeding, verify these assertions are correct:');
+        lines.push('');
+        // Identity
+        lines.push(`1. I am working on: ${this.config.projectName}`);
+        lines.push(`   Project directory: ${this.config.projectDir}`);
+        // Git
+        const gitRemote = this.detectGitRemote();
+        if (gitRemote) {
+            lines.push(`   Git remote: ${gitRemote}`);
+        }
+        // Topic context
+        if (context?.topicId && context?.topicName) {
+            const binding = this.getTopicBinding(context.topicId);
+            if (binding) {
+                lines.push(`2. This topic (${context.topicName}) is for: ${binding.projectName}`);
+                lines.push(`   Expected project dir: ${binding.projectDir}`);
+            }
+            else {
+                lines.push(`2. This topic (${context.topicName}) has NO project binding.`);
+                lines.push(`   WARNING: Verify which project this topic is for before proceeding.`);
+            }
+        }
+        // Action
+        lines.push('');
+        lines.push(`Action: ${action}`);
+        if (context?.description) {
+            lines.push(`Description: ${context.description}`);
+        }
+        if (context?.targetUrl) {
+            lines.push(`Target URL: ${context.targetUrl}`);
+        }
+        if (context?.targetPath) {
+            lines.push(`Target path: ${context.targetPath}`);
+        }
+        // Check results
+        if (!result.passed) {
+            lines.push('');
+            lines.push('WARNING — COHERENCE ISSUES DETECTED:');
+            for (const check of result.checks.filter(c => !c.passed)) {
+                const icon = check.severity === 'error' ? '[BLOCK]' : '[WARN]';
+                lines.push(`  ${icon} ${check.message}`);
+                lines.push(`    Expected: ${check.expected}`);
+                lines.push(`    Found: ${check.actual}`);
+            }
+        }
+        lines.push('');
+        lines.push('If any of the above is incorrect, STOP and verify before proceeding.');
+        lines.push('=== END COHERENCE CHECK ===');
+        return lines.join('\n');
+    }
+    /**
+     * Get the topic-project binding for a specific topic.
+     */
+    getTopicBinding(topicId) {
+        return this.config.topicProjects?.[String(topicId)] ?? null;
+    }
+    /**
+     * Register a topic-to-project binding.
+     */
+    setTopicBinding(topicId, binding) {
+        if (!this.config.topicProjects) {
+            this.config.topicProjects = {};
+        }
+        this.config.topicProjects[String(topicId)] = binding;
+        this.saveTopicBindings();
+    }
+    /**
+     * Load topic-project bindings from disk.
+     */
+    loadTopicBindings() {
+        const bindingsPath = path.join(this.config.stateDir, 'topic-project-bindings.json');
+        try {
+            if (fs.existsSync(bindingsPath)) {
+                const data = JSON.parse(fs.readFileSync(bindingsPath, 'utf-8'));
+                this.config.topicProjects = data;
+                return data;
+            }
+        }
+        catch { /* corrupt file */ }
+        return {};
+    }
+    /**
+     * Save topic-project bindings to disk.
+     */
+    saveTopicBindings() {
+        const bindingsPath = path.join(this.config.stateDir, 'topic-project-bindings.json');
+        fs.mkdirSync(path.dirname(bindingsPath), { recursive: true });
+        fs.writeFileSync(bindingsPath, JSON.stringify(this.config.topicProjects || {}, null, 2));
+    }
+    // ── Individual Checks ──────────────────────────────────────────
+    checkWorkingDirectory() {
+        let cwd;
+        try {
+            cwd = process.cwd();
+        }
+        catch {
+            cwd = 'unknown';
+        }
+        const expected = this.config.projectDir;
+        const isWithin = cwd.startsWith(expected);
+        return {
+            name: 'working-directory',
+            passed: isWithin,
+            expected: `Within ${expected}`,
+            actual: cwd,
+            severity: 'warning',
+            message: isWithin
+                ? `Working directory is within project scope`
+                : `Working directory (${cwd}) is outside project scope (${expected})`,
+        };
+    }
+    checkGitRemote() {
+        const actual = this.detectGitRemote();
+        const expected = this.config.expectedGitRemote;
+        // If no expected remote configured, just report what we found
+        if (!expected) {
+            return {
+                name: 'git-remote',
+                passed: true,
+                expected: 'any (no expected remote configured)',
+                actual: actual || 'no git remote',
+                severity: 'info',
+                message: actual ? `Git remote: ${actual}` : 'No git remote detected',
+            };
+        }
+        const matches = actual !== null && this.normalizeGitUrl(actual) === this.normalizeGitUrl(expected);
+        return {
+            name: 'git-remote',
+            passed: matches,
+            expected,
+            actual: actual || 'no git remote',
+            severity: 'error',
+            message: matches
+                ? `Git remote matches expected project`
+                : `Git remote MISMATCH: expected ${expected}, found ${actual || 'none'}`,
+        };
+    }
+    checkTopicProjectAlignment(topicId) {
+        const binding = this.getTopicBinding(topicId);
+        if (!binding) {
+            return {
+                name: 'topic-project-alignment',
+                passed: false,
+                expected: `Topic ${topicId} bound to a specific project`,
+                actual: 'No topic-project binding exists',
+                severity: 'warning',
+                message: `Topic ${topicId} has no project binding — verify which project this topic is for`,
+            };
+        }
+        // Check if current project matches the topic's expected project
+        const currentProject = this.config.projectDir;
+        const expectedProject = binding.projectDir;
+        const matches = this.normalizePath(currentProject) === this.normalizePath(expectedProject);
+        return {
+            name: 'topic-project-alignment',
+            passed: matches,
+            expected: `${binding.projectName} (${expectedProject})`,
+            actual: `${this.config.projectName} (${currentProject})`,
+            severity: 'error',
+            message: matches
+                ? `Topic is correctly bound to ${binding.projectName}`
+                : `WRONG PROJECT: Topic ${topicId} is for ${binding.projectName} but current project is ${this.config.projectName}`,
+        };
+    }
+    checkDeploymentTarget(targetUrl, topicId) {
+        // If we have a topic binding with deployment targets, check against those
+        if (topicId) {
+            const binding = this.getTopicBinding(topicId);
+            if (binding?.deploymentTargets && binding.deploymentTargets.length > 0) {
+                const allowed = binding.deploymentTargets.some(t => targetUrl.includes(t) || t.includes(targetUrl));
+                return {
+                    name: 'deployment-target',
+                    passed: allowed,
+                    expected: binding.deploymentTargets.join(', '),
+                    actual: targetUrl,
+                    severity: 'error',
+                    message: allowed
+                        ? `Deployment target matches project configuration`
+                        : `WRONG DEPLOY TARGET: ${targetUrl} is not in allowed targets for ${binding.projectName}`,
+                };
+            }
+        }
+        // No specific check possible without bindings
+        return {
+            name: 'deployment-target',
+            passed: true,
+            expected: 'any (no deployment targets configured)',
+            actual: targetUrl,
+            severity: 'warning',
+            message: `Deploying to ${targetUrl} — no deployment target restrictions configured`,
+        };
+    }
+    checkPathScope(targetPath) {
+        const resolvedPath = path.resolve(targetPath);
+        const projectDir = path.resolve(this.config.projectDir);
+        const isWithin = resolvedPath.startsWith(projectDir);
+        return {
+            name: 'path-scope',
+            passed: isWithin,
+            expected: `Within ${projectDir}`,
+            actual: resolvedPath,
+            severity: 'error',
+            message: isWithin
+                ? `Target path is within project scope`
+                : `PATH OUTSIDE PROJECT: ${resolvedPath} is outside ${projectDir}`,
+        };
+    }
+    checkAgentIdentity() {
+        const agentMdPath = path.join(this.config.stateDir, 'AGENT.md');
+        if (!fs.existsSync(agentMdPath)) {
+            return {
+                name: 'agent-identity',
+                passed: false,
+                expected: 'AGENT.md exists with identity',
+                actual: 'AGENT.md not found',
+                severity: 'warning',
+                message: 'No AGENT.md found — agent identity not established',
+            };
+        }
+        try {
+            const content = fs.readFileSync(agentMdPath, 'utf-8');
+            const hasName = /^#\s+.+/m.test(content);
+            const hasIntent = /##\s+Intent/i.test(content);
+            return {
+                name: 'agent-identity',
+                passed: hasName,
+                expected: 'AGENT.md with name and intent',
+                actual: `Name: ${hasName ? 'yes' : 'no'}, Intent: ${hasIntent ? 'yes' : 'no'}`,
+                severity: hasName ? 'info' : 'warning',
+                message: hasName
+                    ? `Agent identity established${hasIntent ? ' with intent section' : ''}`
+                    : 'AGENT.md exists but has no agent name',
+            };
+        }
+        catch {
+            return {
+                name: 'agent-identity',
+                passed: false,
+                expected: 'Readable AGENT.md',
+                actual: 'Failed to read AGENT.md',
+                severity: 'warning',
+                message: 'Failed to read AGENT.md',
+            };
+        }
+    }
+    // ── Helpers ──────────────────────────────────────────
+    detectGitRemote() {
+        try {
+            return execFileSync('git', ['remote', 'get-url', 'origin'], {
+                cwd: this.config.projectDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            }).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    normalizeGitUrl(url) {
+        return url
+            .replace(/\.git$/, '')
+            .replace(/^https:\/\/github\.com\//, '')
+            .replace(/^git@github\.com:/, '')
+            .toLowerCase();
+    }
+    normalizePath(p) {
+        return path.resolve(p).replace(/\/+$/, '');
+    }
+}
+//# sourceMappingURL=CoherenceGate.js.map

package/dist/core/CoherenceGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoherenceGate.js","sourceRoot":"","sources":["../../src/core/CoherenceGate.ts"],"names":[],"mappings":"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"}

package/dist/core/ContextHierarchy.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Context Hierarchy — Tiered context loading for efficient agent awareness.
+ *
+ * Inspired by Dawn's context dispatch system (PROP-088): right context at
+ * the right moment > all context all the time.
+ *
+ * Three tiers:
+ *   Tier 0: Always loaded (identity, project scope, safety rules)
+ *   Tier 1: Session boundaries (continuity, compaction recovery, topic context)
+ *   Tier 2: On-demand (task-specific depth when context matches)
+ *
+ * The hierarchy creates a `.instar/context/` directory with structured
+ * segment files that hooks and sessions can load selectively.
+ *
+ * Born from the Luna incident (2026-02-25): An agent had no systematic
+ * way to load task-relevant context efficiently. Without a hierarchy,
+ * agents either load everything (context bloat) or nothing (incoherence).
+ */
+export interface ContextSegment {
+    /** Unique identifier for this segment */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Context tier: 0 = always, 1 = session boundaries, 2 = on-demand */
+    tier: 0 | 1 | 2;
+    /** When to load this context (for tier 2) */
+    triggers: string[];
+    /** File path relative to .instar/context/ */
+    file: string;
+    /** Description of what this context provides */
+    description: string;
+}
+export interface ContextHierarchyConfig {
+    /** Instar state directory */
+    stateDir: string;
+    /** Project root directory */
+    projectDir: string;
+    /** Project name */
+    projectName: string;
+}
+export interface ContextDispatchTable {
+    /** When this task arises... */
+    trigger: string;
+    /** Load this context file */
+    file: string;
+    /** Why this context helps */
+    reason: string;
+}
+export declare class ContextHierarchy {
+    private config;
+    private contextDir;
+    constructor(config: ContextHierarchyConfig);
+    /**
+     * Initialize the context directory with default segment files.
+     * Only creates files that don't already exist (additive only).
+     */
+    initialize(): {
+        created: string[];
+        skipped: string[];
+    };
+    /**
+     * Get the dispatch table — a mapping of triggers to context files.
+     * This is what agents read to know "when X happens, load Y."
+     */
+    getDispatchTable(): ContextDispatchTable[];
+    /**
+     * Write the dispatch table to a human-readable file.
+     */
+    writeDispatchTable(): void;
+    /**
+     * Load all segments for a given tier.
+     * Returns concatenated content suitable for hook injection.
+     */
+    loadTier(tier: 0 | 1 | 2): string;
+    /**
+     * Load a specific context segment by ID.
+     */
+    loadSegment(segmentId: string): string | null;
+    /**
+     * List all context segments with their status.
+     */
+    listSegments(): Array<ContextSegment & {
+        exists: boolean;
+        sizeBytes: number;
+    }>;
+    /**
+     * Get the context directory path.
+     */
+    getContextDir(): string;
+    private generateSegmentTemplate;
+    private identityTemplate;
+    private safetyTemplate;
+    private projectTemplate;
+    private sessionTemplate;
+    private relationshipsTemplate;
+    private developmentTemplate;
+    private deploymentTemplate;
+    private communicationTemplate;
+}
+//# sourceMappingURL=ContextHierarchy.d.ts.map

package/dist/core/ContextHierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextHierarchy.d.ts","sourceRoot":"","sources":["../../src/core/ContextHierarchy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAsED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,sBAAsB;IAK1C;;;OAGG;IACH,UAAU,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IAwBtD;;;OAGG;IACH,gBAAgB,IAAI,oBAAoB,EAAE;IAY1C;;OAEG;IACH,kBAAkB,IAAI,IAAI;IA0C1B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM;IAmBjC;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAa7C;;OAEG;IACH,YAAY,IAAI,KAAK,CAAC,cAAc,GAAG;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAe9E;;OAEG;IACH,aAAa,IAAI,MAAM;IAMvB,OAAO,CAAC,uBAAuB;IAuB/B,OAAO,CAAC,gBAAgB;IAuBxB,OAAO,CAAC,cAAc;IAiCtB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,eAAe;IAgCvB,OAAO,CAAC,qBAAqB;IAsB7B,OAAO,CAAC,mBAAmB;IA8B3B,OAAO,CAAC,kBAAkB;IAgC1B,OAAO,CAAC,qBAAqB;CA0B9B"}