instar 0.9.11 → 0.9.13

package/dist/core/ContextHierarchy.js

@@ -0,0 +1,454 @@
+/**
+ * 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).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** The canonical list of context segments every agent should have. */
+const DEFAULT_SEGMENTS = [
+    {
+        id: 'identity',
+        name: 'Identity & Scope',
+        tier: 0,
+        triggers: ['always'],
+        file: 'identity.md',
+        description: 'Agent name, role, principles, project scope. Always loaded.',
+    },
+    {
+        id: 'safety',
+        name: 'Safety Rules',
+        tier: 0,
+        triggers: ['always'],
+        file: 'safety.md',
+        description: 'Constraints, blocked commands, destructive action rules.',
+    },
+    {
+        id: 'project',
+        name: 'Project Map',
+        tier: 0,
+        triggers: ['always'],
+        file: 'project.md',
+        description: 'Auto-generated project structure, key files, deployment targets.',
+    },
+    {
+        id: 'session',
+        name: 'Session Continuity',
+        tier: 1,
+        triggers: ['session-start', 'compaction', 'resume'],
+        file: 'session.md',
+        description: 'Session lifecycle, ownership, recovery procedures.',
+    },
+    {
+        id: 'relationships',
+        name: 'Relationship Context',
+        tier: 1,
+        triggers: ['session-start', 'messaging'],
+        file: 'relationships.md',
+        description: 'Known people, interaction patterns, relationship maintenance.',
+    },
+    {
+        id: 'development',
+        name: 'Development Patterns',
+        tier: 2,
+        triggers: ['writing-code', 'modifying-files', 'debugging'],
+        file: 'development.md',
+        description: 'Code conventions, testing patterns, architectural decisions for this project.',
+    },
+    {
+        id: 'deployment',
+        name: 'Deployment Guide',
+        tier: 2,
+        triggers: ['deploying', 'building', 'pushing-to-git'],
+        file: 'deployment.md',
+        description: 'Deployment targets, CI/CD setup, environment variables, rollback procedures.',
+    },
+    {
+        id: 'communication',
+        name: 'Communication Patterns',
+        tier: 2,
+        triggers: ['messaging-user', 'sending-email', 'writing-report'],
+        file: 'communication.md',
+        description: 'User preferences, tone guidelines, when to proactively reach out.',
+    },
+];
+export class ContextHierarchy {
+    config;
+    contextDir;
+    constructor(config) {
+        this.config = config;
+        this.contextDir = path.join(config.stateDir, 'context');
+    }
+    /**
+     * Initialize the context directory with default segment files.
+     * Only creates files that don't already exist (additive only).
+     */
+    initialize() {
+        fs.mkdirSync(this.contextDir, { recursive: true });
+        const created = [];
+        const skipped = [];
+        for (const segment of DEFAULT_SEGMENTS) {
+            const filePath = path.join(this.contextDir, segment.file);
+            if (fs.existsSync(filePath)) {
+                skipped.push(segment.file);
+                continue;
+            }
+            const content = this.generateSegmentTemplate(segment);
+            fs.writeFileSync(filePath, content);
+            created.push(segment.file);
+        }
+        // Write the dispatch table
+        this.writeDispatchTable();
+        return { created, skipped };
+    }
+    /**
+     * Get the dispatch table — a mapping of triggers to context files.
+     * This is what agents read to know "when X happens, load Y."
+     */
+    getDispatchTable() {
+        return DEFAULT_SEGMENTS
+            .filter(s => s.tier === 2)
+            .flatMap(s => s.triggers.map(trigger => ({
+            trigger,
+            file: `.instar/context/${s.file}`,
+            reason: s.description,
+        })));
+    }
+    /**
+     * Write the dispatch table to a human-readable file.
+     */
+    writeDispatchTable() {
+        const table = this.getDispatchTable();
+        const lines = [
+            '# Context Dispatch Table',
+            '',
+            '> When certain work arises, deeper context helps you be fully present.',
+            '> This table guides which context to surface.',
+            '',
+            '| When you\'re about to... | Read this context | Why |',
+            '|------------------------|-------------------|-----|',
+        ];
+        for (const entry of table) {
+            lines.push(`| ${entry.trigger} | \`${entry.file}\` | ${entry.reason} |`);
+        }
+        // Add tier 0 and 1 explanations
+        lines.push('');
+        lines.push('## Always-Loaded Context (Tier 0)');
+        lines.push('');
+        lines.push('These are injected automatically at every session start:');
+        for (const s of DEFAULT_SEGMENTS.filter(s => s.tier === 0)) {
+            lines.push(`- \`.instar/context/${s.file}\` — ${s.description}`);
+        }
+        lines.push('');
+        lines.push('## Session-Boundary Context (Tier 1)');
+        lines.push('');
+        lines.push('These are loaded at session start, compaction, and resume:');
+        for (const s of DEFAULT_SEGMENTS.filter(s => s.tier === 1)) {
+            lines.push(`- \`.instar/context/${s.file}\` — ${s.description}`);
+        }
+        lines.push('');
+        lines.push('*Auto-generated by Instar Context Hierarchy.*');
+        fs.writeFileSync(path.join(this.contextDir, 'DISPATCH.md'), lines.join('\n'));
+    }
+    /**
+     * Load all segments for a given tier.
+     * Returns concatenated content suitable for hook injection.
+     */
+    loadTier(tier) {
+        const segments = DEFAULT_SEGMENTS.filter(s => s.tier <= tier);
+        const parts = [];
+        for (const segment of segments) {
+            const filePath = path.join(this.contextDir, segment.file);
+            if (fs.existsSync(filePath)) {
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8').trim();
+                    if (content && !content.startsWith('<!--') || content.includes('\n\n')) {
+                        parts.push(content);
+                    }
+                }
+                catch { /* corrupt file */ }
+            }
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * Load a specific context segment by ID.
+     */
+    loadSegment(segmentId) {
+        const segment = DEFAULT_SEGMENTS.find(s => s.id === segmentId);
+        if (!segment)
+            return null;
+        const filePath = path.join(this.contextDir, segment.file);
+        try {
+            if (fs.existsSync(filePath)) {
+                return fs.readFileSync(filePath, 'utf-8');
+            }
+        }
+        catch { /* corrupt file */ }
+        return null;
+    }
+    /**
+     * List all context segments with their status.
+     */
+    listSegments() {
+        return DEFAULT_SEGMENTS.map(s => {
+            const filePath = path.join(this.contextDir, s.file);
+            let exists = false;
+            let sizeBytes = 0;
+            try {
+                if (fs.existsSync(filePath)) {
+                    exists = true;
+                    sizeBytes = fs.statSync(filePath).size;
+                }
+            }
+            catch { /* ignore */ }
+            return { ...s, exists, sizeBytes };
+        });
+    }
+    /**
+     * Get the context directory path.
+     */
+    getContextDir() {
+        return this.contextDir;
+    }
+    // ── Template Generation ─────────────────────────────────────────
+    generateSegmentTemplate(segment) {
+        switch (segment.id) {
+            case 'identity':
+                return this.identityTemplate();
+            case 'safety':
+                return this.safetyTemplate();
+            case 'project':
+                return this.projectTemplate();
+            case 'session':
+                return this.sessionTemplate();
+            case 'relationships':
+                return this.relationshipsTemplate();
+            case 'development':
+                return this.developmentTemplate();
+            case 'deployment':
+                return this.deploymentTemplate();
+            case 'communication':
+                return this.communicationTemplate();
+            default:
+                return `# ${segment.name}\n\n<!-- Add context for: ${segment.description} -->\n`;
+        }
+    }
+    identityTemplate() {
+        return `# Identity & Scope
+
+<!-- This file is auto-generated by Instar. Customize it for your agent. -->
+
+## Who I Am
+
+Read .instar/AGENT.md for full identity. This is a quick-reference summary.
+
+## Project Scope
+
+- **Project**: ${this.config.projectName}
+- **Directory**: ${this.config.projectDir}
+- Read .instar/project-map.md for full project structure.
+
+## Core Truths
+
+1. I am a builder. When I see work, I do it.
+2. I know my tools. I check /capabilities before saying "I can't."
+3. I verify before claiming. "Did I actually check this, or am I assuming?"
+`;
+    }
+    safetyTemplate() {
+        return `# Safety Rules
+
+## Hard Blocks
+
+These commands are ALWAYS blocked regardless of context:
+- \`rm -rf /\` or \`rm -rf ~\` — catastrophic filesystem destruction
+- \`> /dev/sda\` — disk overwrite
+- Fork bombs, disk formatting commands
+
+## Soft Blocks (Safety Level Dependent)
+
+At Safety Level 1 (default): ask user before running.
+At Safety Level 2 (autonomous): self-verify before running.
+
+- \`git push --force\` — overwrites remote history
+- \`git reset --hard\` — discards uncommitted work
+- \`DROP TABLE/DATABASE\` — irreversible data loss
+- \`rm -rf .\` — project directory destruction
+
+## Coherence Gate
+
+Before deploying, pushing, or modifying files outside this project:
+1. Check coherence: POST /coherence/check
+2. If BLOCK — stop. You're likely in the wrong project.
+3. If WARN — pause and verify.
+
+## Topic-Project Bindings
+
+Each Telegram topic may be bound to a specific project. Verify before acting.
+`;
+    }
+    projectTemplate() {
+        return `# Project Context
+
+<!-- Auto-populated from project-map.json. Refresh: POST /project-map/refresh -->
+
+Read .instar/project-map.md for the full project structure map.
+Read .instar/project-map.json for programmatic access.
+
+Quick reference: GET /project-map?format=compact
+`;
+    }
+    sessionTemplate() {
+        return `# Session Continuity
+
+## On Session Start
+
+1. Note the current topic (if Telegram session)
+2. Read thread history for conversational context
+3. Check for pending upgrade guides
+4. Verify identity (AGENT.md exists and is readable)
+
+## On Compaction
+
+Context was compressed. Recovery priority:
+1. Topic context (what am I working on?)
+2. Identity (who am I?)
+3. Memory (what have I learned?)
+4. Project context (where am I?)
+5. Capabilities (what can I do?)
+
+## On Resume
+
+Re-read recent activity. Check if anything changed while you were paused.
+
+## Session Handoff
+
+When ending a session that another might continue:
+- Update MEMORY.md with anything learned
+- Note any incomplete work
+- Save conversation context via topic memory
+`;
+    }
+    relationshipsTemplate() {
+        return `# Relationship Context
+
+## Before Interacting with Anyone
+
+1. Check if they're tracked: GET /relationships
+2. If tracked, read their file for context before responding
+3. Note the interaction type and update the relationship record after
+
+## Key Patterns
+
+- **First contact**: Be welcoming but verify identity
+- **Returning user**: Reference shared history naturally
+- **Stale contact**: Consider reaching out if significance >= 3
+
+## Relationship Files
+
+All relationship records are in .instar/relationships/*.json
+Each contains: name, interactions, significance, themes, notes
+`;
+    }
+    developmentTemplate() {
+        return `# Development Patterns
+
+<!-- Customize this for your project's specific conventions. -->
+
+## Before Writing Code
+
+1. Read existing code before modifying it
+2. Check the project map for file locations
+3. Follow existing patterns in the codebase
+
+## Testing
+
+- Run tests before committing
+- Match the project's existing test patterns
+- Write tests for new features
+
+## Git Workflow
+
+- Commit with clear messages
+- Check coherence gate before pushing
+- Verify CI passes after push
+
+## Project-Specific Conventions
+
+<!-- Add your project's coding standards, linting rules,
+     naming conventions, architecture patterns, etc. -->
+`;
+    }
+    deploymentTemplate() {
+        return `# Deployment Guide
+
+<!-- Customize this for your project's deployment setup. -->
+
+## Pre-Deployment Checklist
+
+1. Run coherence check: POST /coherence/check with action "deploy"
+2. Verify you're in the correct project directory
+3. Verify the deployment target matches the current topic/project
+4. Run tests
+5. Check CI status: GET /ci
+
+## Deployment Targets
+
+<!-- List your deployment targets here, e.g.:
+- Production: https://myapp.vercel.app (Vercel)
+- Staging: https://staging.myapp.com
+-->
+
+Check project map for auto-detected targets: GET /project-map
+
+## Rollback Procedure
+
+<!-- Document how to rollback if a deployment goes wrong -->
+
+## Environment Variables
+
+<!-- List required environment variables and where they're configured -->
+`;
+    }
+    communicationTemplate() {
+        return `# Communication Patterns
+
+## Telegram
+
+- Always acknowledge messages immediately
+- Relay responses via telegram-reply script
+- Strip [telegram:N] prefix before interpreting
+- Read thread history for context on new sessions
+
+## Reporting
+
+- Use Private Viewer for sensitive content (POST /view)
+- Use Telegraph for public content (POST /publish)
+- Always include artifact links, not just summaries
+
+## User Preferences
+
+<!-- Document your user's communication preferences:
+- Preferred response length
+- When to proactively reach out
+- When to stay silent
+- Topics they care about vs. internal details
+-->
+`;
+    }
+}
+//# sourceMappingURL=ContextHierarchy.js.map

package/dist/core/ContextHierarchy.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"PostUpdateMigrator.d.ts","sourceRoot":"","sources":["../../src/core/PostUpdateMigrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,cAAc;IAIlC;;;OAGG;IACH,OAAO,IAAI,eAAe;IAgB1B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAkCpB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuKvB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAiCtB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAyGvB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAuCrB;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,MAAM;IAOrE,OAAO,CAAC,mBAAmB;IAqL3B,OAAO,CAAC,wBAAwB;IA2ChC,OAAO,CAAC,2BAA2B;IAenC,OAAO,CAAC,qBAAqB;IAmJ7B,OAAO,CAAC,sBAAsB;IAyD9B,OAAO,CAAC,iBAAiB;CAuB1B"}
+{"version":3,"file":"PostUpdateMigrator.d.ts","sourceRoot":"","sources":["../../src/core/PostUpdateMigrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,cAAc;IAIlC;;;OAGG;IACH,OAAO,IAAI,eAAe;IAgB1B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAkCpB;;;OAGG;IACH,OAAO,CAAC,eAAe;IA4NvB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAiCtB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAyGvB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAuCrB;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,MAAM;IAOrE,OAAO,CAAC,mBAAmB;IA8N3B,OAAO,CAAC,wBAAwB;IAkEhC,OAAO,CAAC,2BAA2B;IAenC,OAAO,CAAC,qBAAqB;IAyK7B,OAAO,CAAC,sBAAsB;IAyD9B,OAAO,CAAC,iBAAiB;CAuB1B"}

package/dist/core/PostUpdateMigrator.js

@@ -237,6 +237,60 @@ Strip the \`[telegram:N]\` prefix before interpreting the message. Respond natur
         else {
             result.skipped.push('CLAUDE.md: Dashboard section already present');
         }
+        // Coherence Gate section — pre-action verification for high-risk actions
+        if (!content.includes('Coherence Gate') && !content.includes('/coherence/check')) {
+            const section = `
+### Coherence Gate (Pre-Action Verification)
+
+**BEFORE any high-risk action** (deploying, pushing to git, modifying files outside this project, calling external APIs):
+
+1. **Check coherence**: \`curl -X POST http://localhost:${port}/coherence/check -H 'Content-Type: application/json' -d '{"action":"deploy","context":{"topicId":TOPIC_ID}}'\`
+2. **If result says "block"** — STOP. You may be working on the wrong project for this topic.
+3. **If result says "warn"** — Pause and verify before proceeding.
+4. **Generate a reflection prompt**: \`POST http://localhost:${port}/coherence/reflect\` — produces a self-verification checklist.
+
+**Topic-Project Bindings**: Each Telegram topic can be bound to a specific project. When switching topics, verify the binding matches your current working directory.
+- View bindings: \`GET http://localhost:${port}/topic-bindings\`
+- Create binding: \`POST http://localhost:${port}/topic-bindings\` with \`{"topicId": N, "binding": {"projectName": "...", "projectDir": "..."}}\`
+
+**Project Map**: Your spatial awareness of the working environment.
+- View: \`GET http://localhost:${port}/project-map?format=compact\`
+- Refresh: \`POST http://localhost:${port}/project-map/refresh\`
+`;
+            // Insert before Scripts or append
+            const insertBefore = content.indexOf('**Scripts**');
+            if (insertBefore >= 0) {
+                content = content.slice(0, insertBefore) + section + '\n' + content.slice(insertBefore);
+            }
+            else {
+                content += '\n' + section;
+            }
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Coherence Gate section');
+        }
+        else {
+            result.skipped.push('CLAUDE.md: Coherence Gate section already present');
+        }
+        // Session Continuity — ensure agents know how to handle respawn context
+        if (this.config.hasTelegram && !content.includes('Session Continuity') && !content.includes('CONTINUATION')) {
+            const section = `
+### Session Continuity (CRITICAL)
+
+When your first message starts with \`CONTINUATION\`, you are **resuming an existing conversation**. The inline context contains a summary and recent messages from the prior session. You MUST:
+
+1. **Read the context first** — it tells you what the conversation is about
+2. **Pick up where you left off** — do NOT introduce yourself or ask "how can I help?"
+3. **Reference the prior context** — show the user you know what they were discussing
+
+The user has been talking to you (possibly for days). A generic greeting like "Hey! What can I help you with?" after dozens of messages of conversation history is a critical failure — it signals you lost all context and the user has to repeat everything. The context is right there in your input. Use it.
+`;
+            content += '\n' + section;
+            patched = true;
+            result.upgraded.push('CLAUDE.md: added Session Continuity section');
+        }
+        else if (this.config.hasTelegram && content.includes('Session Continuity')) {
+            result.skipped.push('CLAUDE.md: Session Continuity section already present');
+        }
         if (patched) {
             try {
                 fs.writeFileSync(claudeMdPath, content);
@@ -508,12 +562,53 @@ if [ -f "$INSTAR_DIR/AGENT.md" ]; then
   sed -n '/^## Personality/,/^## [^P]/p' "$INSTAR_DIR/AGENT.md" 2>/dev/null | head -10
 fi
 
+# PROJECT MAP — spatial awareness of the working environment
+if [ -f "$INSTAR_DIR/project-map.json" ]; then
+  echo ""
+  echo "--- PROJECT CONTEXT ---"
+  python3 -c "
+import json, sys
+try:
+    m = json.load(open('$INSTAR_DIR/project-map.json'))
+    print(f'Project: {m[\"projectName\"]} ({m[\"projectType\"]})')
+    print(f'Path: {m[\"projectDir\"]}')
+    r = m.get('gitRemote')
+    b = m.get('gitBranch')
+    if r: print(f'Git: {r}' + (f' [{b}]' if b else ''))
+    t = m.get('deploymentTargets', [])
+    if t: print(f'Deploy targets: {(\", \").join(t)}')
+    d = m.get('directories', [])
+    print(f'Files: {m[\"totalFiles\"]} across {len(d)} directories')
+    for dd in d[:6]:
+        print(f'  {dd[\"name\"]}/ ({dd[\"fileCount\"]}) — {dd[\"description\"]}')
+    if len(d) > 6: print(f'  ... and {len(d) - 6} more')
+except Exception as e:
+    print(f'(project map load failed: {e})', file=sys.stderr)
+" 2>/dev/null
+  echo "--- END PROJECT CONTEXT ---"
+fi
+
+# COHERENCE SCOPE — before ANY high-risk action, verify alignment
+if [ -f "$INSTAR_DIR/config.json" ]; then
+  echo ""
+  echo "--- COHERENCE SCOPE ---"
+  echo "BEFORE deploying, pushing, or modifying files outside this project:"
+  echo "  1. Verify you are in the RIGHT project for the current topic/task"
+  echo "  2. Check: curl -X POST http://localhost:\${PORT:-4040}/coherence/check \\\\"
+  echo "       -H 'Content-Type: application/json' \\\\"
+  echo "       -d '{\"action\":\"deploy\",\"context\":{\"topicId\":N}}'"
+  echo "  3. If the check says BLOCK — STOP. You may be in the wrong project."
+  echo "  4. Read the full reflection: POST /coherence/reflect"
+  echo "--- END COHERENCE SCOPE ---"
+fi
+
 # Key files
 echo ""
 echo "Key files:"
 [ -f "$INSTAR_DIR/AGENT.md" ] && echo "  .instar/AGENT.md — Your identity (read for full context)"
 [ -f "$INSTAR_DIR/USER.md" ] && echo "  .instar/USER.md — Your collaborator"
 [ -f "$INSTAR_DIR/MEMORY.md" ] && echo "  .instar/MEMORY.md — Persistent learnings"
+[ -f "$INSTAR_DIR/project-map.md" ] && echo "  .instar/project-map.md — Project structure map"
 
 # Relationship count
 if [ -d "$INSTAR_DIR/relationships" ]; then
@@ -641,6 +736,29 @@ for pattern in "rm -rf /" "rm -rf ~" "> /dev/sda" "mkfs\\." "dd if=" ":(){:|:&};
   fi
 done
 
+# Deployment/push commands — check coherence gate first
+for pattern in "vercel deploy" "vercel --prod" "git push" "npm publish" "npx wrangler deploy" "fly deploy" "railway up"; do
+  if echo "$INPUT" | grep -qi "$pattern"; then
+    if [ -f "$INSTAR_DIR/config.json" ]; then
+      PORT=$(python3 -c "import json; print(json.load(open('$INSTAR_DIR/config.json')).get('port', 4040))" 2>/dev/null || echo "4040")
+      TOPIC_ID="\${INSTAR_TELEGRAM_TOPIC:-}"
+      ACTION="deploy"
+      echo "$INPUT" | grep -qi "git push" && ACTION="git-push"
+      echo "$INPUT" | grep -qi "npm publish" && ACTION="git-push"
+      CTX="{}"
+      [ -n "$TOPIC_ID" ] && CTX="{\\\"topicId\\\": $TOPIC_ID}"
+      CHECK=$(curl -s -X POST "http://localhost:$PORT/coherence/check" -H 'Content-Type: application/json' -d "{\\\"action\\\":\\\"$ACTION\\\",\\\"context\\\":$CTX}" 2>/dev/null)
+      if echo "$CHECK" | grep -q '"recommendation":"block"'; then
+        SUMMARY=$(echo "$CHECK" | python3 -c "import sys,json; print(json.load(sys.stdin).get('summary','Coherence check failed'))" 2>/dev/null || echo "Coherence check failed")
+        echo "BLOCKED: Coherence gate blocked this action." >&2
+        echo "$SUMMARY" >&2
+        echo "Run POST /coherence/reflect for a detailed self-verification checklist." >&2
+        exit 2
+      fi
+    fi
+  fi
+done
+
 # Risky commands — behavior depends on safety level
 for pattern in "rm -rf \\." "git push --force" "git push -f" "git reset --hard" "git clean -fd" "DROP TABLE" "DROP DATABASE" "TRUNCATE" "DELETE FROM"; do
   if echo "$INPUT" | grep -qi "$pattern"; then
@@ -748,6 +866,28 @@ if [ -f "\$INSTAR_DIR/AGENT.md" ]; then
   echo "--- End Identity ---"
 fi
 
+# ── 2b. PROJECT CONTEXT (where am I working?) ──
+if [ -f "\$INSTAR_DIR/project-map.json" ]; then
+  echo ""
+  echo "--- PROJECT CONTEXT ---"
+  python3 -c "
+import json, sys
+try:
+    m = json.load(open('\$INSTAR_DIR/project-map.json'))
+    print(f'Project: {m[\"projectName\"]} ({m[\"projectType\"]})')
+    print(f'Path: {m[\"projectDir\"]}')
+    r = m.get('gitRemote')
+    b = m.get('gitBranch')
+    if r: print(f'Git: {r}' + (f' [{b}]' if b else ''))
+    t = m.get('deploymentTargets', [])
+    if t: print(f'Deploy targets: {(\", \").join(t)}')
+    print(f'Files: {m[\"totalFiles\"]} across {len(m.get(\"directories\", []))} directories')
+except Exception as e:
+    print(f'(project map load failed: {e})', file=sys.stderr)
+" 2>/dev/null
+  echo "--- END PROJECT CONTEXT ---"
+fi
+
 # ── 3. MEMORY (first 50 lines — what have I learned?) ──
 if [ -f "\$INSTAR_DIR/MEMORY.md" ]; then
   LINES=\$(wc -l < "\$INSTAR_DIR/MEMORY.md" | tr -d ' ')