@virsanghavi/axis-server 1.1.2 → 1.3.0

package/.axis/instructions/conventions.md

@@ -23,40 +23,35 @@
 
 ---
 
-## Agent Behavioral Norms
+## Agent Behavioral Norms (MANDATORY)
 
-### Plan Before Write — The Core Invariant
+These norms apply to all AI coding agents. They are not optional or suggestive — execute them autonomously.
 
-**No agent writes code unless it either owns a file lock OR has explicitly declined the job board for a scoped reason.**
+### Autonomous Execution
 
-On non-trivial tasks (2+ files, new features, refactors):
-1. Break work into jobs → `post_job`
-2. Claim before editing → `claim_next_job`
-3. Lock before writing → `propose_file_access` with a **descriptive intent**
-4. Complete when done → `complete_job` with outcome
+- **NEVER** wait for the user to say "use Axis" or "post a job" or "lock the file." Just do it.
+- **NEVER** pause after analysis to ask permission to proceed. Identify issues → start fixing immediately.
+- **NEVER** leave locks or jobs dangling. Complete jobs and finalize sessions without being told.
+- **IMMEDIATELY** call `get_project_soul` as the first action in any session.
 
-Direct edits without a job are allowed only for:
-- Single-line fixes, typos, config tweaks
-- Clearly scoped changes the user asked for directly
+### Plan Before Write
 
-### Force Unlock Policy
+**No agent writes code unless it either owns a file lock OR has explicitly declined the job board for a scoped reason.**
 
-`force_unlock` is a **last resort, not a convenience tool.**
+On non-trivial tasks (2+ files, new features, refactors):
+1. `post_job` — break into trackable jobs (do this IMMEDIATELY, not after being asked)
+2. `claim_next_job` — claim before starting
+3. `propose_file_access` — lock with a **descriptive intent**
+4. `complete_job` — report outcome when done (this releases the lock)
 
-Rules:
-1. **Never** call `force_unlock` on a file you didn't lock unless:
-   - The lock has been held for >25 minutes (close to TTL expiry), AND
-   - The locking agent is clearly not responding or has crashed
-2. **Always** provide a specific reason (e.g. "Agent claude-code crashed 20 minutes ago, lock on auth.ts is blocking progress")
-3. **Never** force-unlock to skip coordination. If another agent holds a lock, work on something else.
-4. Prefer waiting for TTL expiry (30 min) over force-unlocking.
+Skip jobs ONLY for: single-line fixes, typos, config tweaks.
 
 ### Lock Hygiene
-- Always provide descriptive `intent` when locking (e.g. "Refactor auth middleware to use JWT validation" — not "editing file")
-- Release locks early by completing jobs when done
-- Call `finalize_session` at end of session to clean up all locks
-
-### Shared Memory
-- Call `update_shared_context` after completing meaningful steps
-- Log decisions, not just actions (e.g. "Chose JWT over session tokens because...")
-- Other agents read the notepad in real-time — write for them
+- Descriptive `intent` when locking (not "editing file").
+- Release locks IMMEDIATELY by completing jobs. Never hold a lock while doing unrelated work.
+- `force_unlock` is a **last resort** — only for locks >25 min old from a crashed agent. Always give a reason.
+
+### Session Cleanup (MANDATORY)
+- `complete_job` after EVERY finished task — do not accumulate incomplete jobs.
+- `update_shared_context` after meaningful steps — log decisions, not just actions.
+- `finalize_session` when the user's request is fully complete — this is required, not optional.

package/dist/mcp-server.mjs

@@ -827,6 +827,7 @@ var NerveCenter = class {
         delete this.state.locks[filePath];
         await this.saveState();
       }
+      this.logLockEvent("FORCE_UNLOCKED", filePath, "admin", void 0, reason);
       await this.appendToNotepad(`
 - [FORCE UNLOCK] ${filePath} unlocked by admin. Reason: ${reason}`);
       return `File ${filePath} has been forcibly unlocked.`;
@@ -849,6 +850,31 @@ ${lockSummary || "No active locks."}
 ## Live Notepad
 ${notepad}`;
   }
+  // --- Lock Event Logging ---
+  async logLockEvent(eventType, filePath, requestingAgent, blockingAgent, intent) {
+    try {
+      if (this.contextManager.apiUrl) {
+        await this.callCoordination("lock-events", "POST", {
+          eventType,
+          filePath,
+          requestingAgent,
+          blockingAgent: blockingAgent || null,
+          intent: intent || null
+        });
+      } else if (this.useSupabase && this.supabase && this._projectId) {
+        await this.supabase.from("lock_events").insert({
+          project_id: this._projectId,
+          event_type: eventType,
+          file_path: filePath,
+          requesting_agent: requestingAgent,
+          blocking_agent: blockingAgent || null,
+          intent: intent || null
+        });
+      }
+    } catch (e) {
+      logger.warn(`[logLockEvent] Failed to log ${eventType} event: ${e.message}`);
+    }
+  }
   // --- Decision & Orchestration ---
   async proposeFileAccess(agentId, filePath, intent, userPrompt) {
     return await this.mutex.runExclusive(async () => {
@@ -864,6 +890,7 @@ ${notepad}`;
           });
           if (result.status === "DENIED") {
             logger.info(`[proposeFileAccess] DENIED by server: ${result.message}`);
+            this.logLockEvent("BLOCKED", filePath, agentId, result.current_lock?.agent_id, intent);
             return {
               status: "REQUIRES_ORCHESTRATION",
               message: result.message || `File '${filePath}' is locked by another agent`,
@@ -871,6 +898,7 @@ ${notepad}`;
             };
           }
           logger.info(`[proposeFileAccess] GRANTED by server`);
+          this.logLockEvent("GRANTED", filePath, agentId, void 0, intent);
           await this.appendToNotepad(`
 - [LOCK] ${agentId} locked ${filePath}
   Intent: ${intent}`);
@@ -900,6 +928,7 @@ ${notepad}`;
           if (error) throw error;
           const row = Array.isArray(data) ? data[0] : data;
           if (row && row.status === "DENIED") {
+            this.logLockEvent("BLOCKED", filePath, agentId, row.owner_id, intent);
             return {
               status: "REQUIRES_ORCHESTRATION",
               message: `Conflict: File '${filePath}' is locked by '${row.owner_id}'`,
@@ -911,6 +940,7 @@ ${notepad}`;
               }
             };
           }
+          this.logLockEvent("GRANTED", filePath, agentId, void 0, intent);
           await this.appendToNotepad(`
 - [LOCK] ${agentId} locked ${filePath}
   Intent: ${intent}`);
@@ -923,6 +953,7 @@ ${notepad}`;
       if (existing) {
         const isStale = Date.now() - existing.timestamp > this.lockTimeout;
         if (!isStale && existing.agentId !== agentId) {
+          this.logLockEvent("BLOCKED", filePath, agentId, existing.agentId, intent);
           return {
             status: "REQUIRES_ORCHESTRATION",
             message: `Conflict: File '${filePath}' is currently locked by '${existing.agentId}'`,
@@ -932,6 +963,7 @@ ${notepad}`;
       }
       this.state.locks[filePath] = { agentId, filePath, intent, userPrompt, timestamp: Date.now() };
       await this.saveState();
+      this.logLockEvent("GRANTED", filePath, agentId, void 0, intent);
       await this.appendToNotepad(`
 - [LOCK] ${agentId} locked ${filePath}
   Intent: ${intent}`);
@@ -1254,23 +1286,26 @@ can work on the same codebase without conflicts.
 - Tailwind CSS for styling; no raw CSS unless unavoidable.
 - Functional React components; prefer server components in Next.js App Router.
 
-## Agent Behavioral Norms
+## Agent Behavioral Norms (MANDATORY)
+
+### Autonomous Execution
+Agents MUST execute the full Axis workflow without being told:
+- NEVER wait for the user to say "use Axis" or "post a job." Just do it.
+- NEVER pause after analysis to ask permission. Identify issues \u2192 start fixing immediately.
+- NEVER leave locks or jobs dangling. Complete jobs and finalize sessions automatically.
+- IMMEDIATELY call get_project_soul as the first action in every session.
 
 ### Plan Before Write
-Every non-trivial task must follow: post_job -> claim_next_job -> propose_file_access -> (edit) -> complete_job.
-Skip only for single-line typo fixes.
+Every non-trivial task MUST follow: post_job \u2192 claim_next_job \u2192 propose_file_access \u2192 (edit) \u2192 complete_job.
+Skip ONLY for single-line typo fixes.
 
-### Force-Unlock Policy
-force_unlock is a LAST RESORT. Before using it:
-1. Verify the lock is > 25 minutes old.
-2. Confirm the locking agent is unresponsive.
-3. Provide a specific reason string.
-Never casually unlock files \u2014 always try propose_file_access first.
+### Session Cleanup (MANDATORY)
+- complete_job IMMEDIATELY after finishing each task.
+- update_shared_context after meaningful steps.
+- finalize_session when the user's request is fully complete \u2014 do not wait to be told.
 
-### Proactive Tool Usage
-Agents must use Axis MCP tools by default \u2014 do not wait for the user to say "use Axis".
-On session start, call get_project_soul or read_context to load project state.
-After significant progress, call update_shared_context.
+### Force-Unlock Policy
+force_unlock is a LAST RESORT \u2014 only for locks >25 min old from a crashed agent. Always give a reason.
 `],
         ["activity.md", "# Activity Log\n\n"]
       ];
@@ -1426,7 +1461,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     // --- Decision & Orchestration ---
     {
       name: "propose_file_access",
-      description: "**CRITICAL: REQUEST FILE LOCK**.\n- **MUST** be called *before* editing any file to prevent conflicts with other agents.\n- Checks if another agent currently holds a lock.\n- Returns `GRANTED` if safe to proceed, or `REQUIRES_ORCHESTRATION` if someone else is editing.\n- Usage: Provide your `agentId` (e.g., 'cursor-agent'), `filePath` (absolute), and `intent` (what you are doing).\n- Note: Locks expire after 30 minutes. Use `force_unlock` only if you are certain a lock is stale and blocking progress.",
+      description: "**CRITICAL: REQUEST FILE LOCK** \u2014 call this before EVERY file edit, no exceptions.\n- Checks if another agent currently holds a lock.\n- Returns `GRANTED` if safe to proceed, or `REQUIRES_ORCHESTRATION` if someone else is editing.\n- Usage: Provide your `agentId` (e.g., 'cursor-agent'), `filePath` (absolute), and `intent` (descriptive \u2014 e.g. 'Refactor auth to use JWT', NOT 'editing file').\n- Locks expire after 30 minutes. Use `force_unlock` only as a last resort for crashed agents.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1453,18 +1488,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     // --- Permanent Memory ---
     {
       name: "finalize_session",
-      description: "**END OF SESSION HOUSEKEEPING**.\n- Archives the current Live Notepad to a permanent session log.\n- Clears all active locks and completed jobs.\n- Resets the Live Notepad for the next session.\n- Call this when the user says 'we are done' or 'start fresh'.",
+      description: "**MANDATORY SESSION CLEANUP** \u2014 call this automatically when the user's request is fully complete.\n- Archives the current Live Notepad to a permanent session log.\n- Clears all active locks and completed jobs.\n- Resets the Live Notepad for the next session.\n- Do NOT wait for the user to say 'we are done.' When all tasks are finished, call this yourself.",
       inputSchema: { type: "object", properties: {}, required: [] }
     },
     {
       name: "get_project_soul",
-      description: "**HIGH-LEVEL INTENT**: Returns the 'Soul' of the project.\n- Combines `context.md`, `conventions.md`, and other core directives into a single prompt.\n- Use this at the *start* of a conversation to ground yourself in the project's reality.",
+      description: "**MANDATORY FIRST CALL**: Returns the project's goals, architecture, conventions, and active state.\n- Combines `context.md`, `conventions.md`, and other core directives into a single prompt.\n- You MUST call this as your FIRST action in every new session or task \u2014 before reading files, before responding to the user, before anything else.\n- Skipping this call means you are working without context and will make wrong decisions.",
       inputSchema: { type: "object", properties: {}, required: [] }
     },
     // --- Job Board (Task Orchestration) ---
     {
       name: "post_job",
-      description: "**CREATE TICKET**: Post a new task to the Job Board.\n- Use this when you identify work that needs to be done but *cannot* be done right now (e.g., refactoring, new feature).\n- Supports `dependencies` (list of other Job IDs that must be done first).\n- Priority: low, medium, high, critical.",
+      description: "**CREATE TICKET**: Post a new task to the Job Board.\n- Call this IMMEDIATELY when you receive a non-trivial task (2+ files, new features, refactors). Do not wait to be asked.\n- Break work into trackable jobs BEFORE you start coding.\n- Supports `dependencies` (list of other Job IDs that must be done first).\n- Priority: low, medium, high, critical.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1502,7 +1537,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "claim_next_job",
-      description: "**AUTO-ASSIGNMENT**: Ask the Job Board for the next most important task.\n- Respects priority (Critical > High > ...) and dependencies (won't assign a job if its deps aren't done).\n- Returns the Job object if successful, or 'NO_JOBS_AVAILABLE'.\n- Use this when you are idle and looking for work.",
+      description: "**CLAIM WORK**: Claim the next job from the Job Board before starting it.\n- You MUST claim a job before editing files for that job.\n- Respects priority (Critical > High > ...) and dependencies (won't assign a job if its deps aren't done).\n- Returns the Job object if successful, or 'NO_JOBS_AVAILABLE'.\n- Call this immediately after posting jobs, and again after completing each job to pick up the next one.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1513,7 +1548,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "complete_job",
-      description: "**CLOSE TICKET**: Mark a job as done.\n- Requires `outcome` (what was done).\n- If you are not the assigned agent, you must provide the `completionKey`.",
+      description: "**CLOSE TICKET**: Mark a job as done and release file locks.\n- Call this IMMEDIATELY after finishing each job \u2014 do not accumulate completed-but-unclosed jobs.\n- Requires `outcome` (what was done).\n- If you are not the assigned agent, you must provide the `completionKey`.\n- Leaving jobs open holds locks and blocks other agents.",
       inputSchema: {
         type: "object",
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@virsanghavi/axis-server",
-    "version": "1.1.2",
+    "version": "1.3.0",
     "description": "Axis MCP Server CLI",
     "main": "dist/index.js",
     "bin": {