clearctx 3.1.0 → 3.2.0

package/src/notebook-store.js

@@ -0,0 +1,391 @@
+/**
+ * notebook-store.js
+ * Cognition Layer: Shared knowledge scratchpad for worker collaboration.
+ *
+ * Provides a team wiki where any worker can write and read free-form markdown
+ * notes organized by category. Unlike artifacts (structured, versioned, immutable),
+ * notebook entries are informal, collaborative, and appendable — a worker can
+ * start a note and another worker can append to it.
+ *
+ * Storage structure:
+ * team/{teamName}/notebook/
+ *   notebook-index.json       - registry of all notes
+ *   entries/{noteId}.jsonl    - append-only entry log per note
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { atomicWriteJson, readJsonSafe } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
+
+/**
+ * Valid note categories.
+ * Exported so mcp-server.js can validate tool inputs.
+ */
+const NOTEBOOK_CATEGORIES = [
+  'research',
+  'decision',
+  'gotcha',
+  'pattern',
+  'plan',
+  'investigation',
+  'reference'
+];
+
+/**
+ * Validate a note ID.
+ * Must be lowercase, alphanumeric + hyphens only, max 80 chars.
+ * @param {string} noteId - Note ID to validate
+ * @throws {Error} If noteId is invalid
+ * @private
+ */
+function _validateNoteId(noteId) {
+  if (!noteId || typeof noteId !== 'string') {
+    throw new Error('Note ID is required and must be a string');
+  }
+
+  if (noteId.length > 80) {
+    throw new Error(`Note ID '${noteId}' exceeds 80 character limit`);
+  }
+
+  if (!/^[a-z0-9-]+$/.test(noteId)) {
+    throw new Error(`Note ID '${noteId}' must be lowercase alphanumeric with hyphens only`);
+  }
+}
+
+/**
+ * NotebookStore manages a shared knowledge scratchpad for worker collaboration.
+ *
+ * Directory structure:
+ * team/{teamName}/notebook/
+ *   notebook-index.json       - note registry (locked for writes)
+ *   entries/{noteId}.jsonl    - append-only entry log per note
+ */
+class NotebookStore {
+  /**
+   * Create a new NotebookStore instance
+   * @param {string} teamName - Name of the team (default: 'default')
+   */
+  constructor(teamName = 'default') {
+    const baseDir = path.join(os.homedir(), '.clearctx');
+    this.teamDir = path.join(baseDir, 'team', teamName);
+    this.notebookDir = path.join(this.teamDir, 'notebook');
+    this.entriesDir = path.join(this.notebookDir, 'entries');
+    this.indexPath = path.join(this.notebookDir, 'notebook-index.json');
+    this.locksDir = path.join(this.teamDir, 'locks');
+
+    this._ensureDirectories();
+  }
+
+  /**
+   * Ensure all required directories exist
+   * @private
+   */
+  _ensureDirectories() {
+    [this.notebookDir, this.entriesDir, this.locksDir].forEach(dir => {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+    });
+  }
+
+  /**
+   * Get the JSONL file path for a note
+   * @param {string} noteId - The note ID
+   * @returns {string} Absolute path to the note's JSONL file
+   * @private
+   */
+  _entryPath(noteId) {
+    return path.join(this.entriesDir, `${noteId}.jsonl`);
+  }
+
+  /**
+   * Read and parse all JSONL entries for a note
+   * @param {string} noteId - The note ID
+   * @returns {Array} Parsed entry objects
+   * @private
+   */
+  _readEntries(noteId) {
+    const jsonlPath = this._entryPath(noteId);
+    let entries = [];
+
+    try {
+      const content = fs.readFileSync(jsonlPath, 'utf-8');
+      const lines = content.split('\n').filter(line => line.trim());
+
+      for (const line of lines) {
+        try {
+          entries.push(JSON.parse(line));
+        } catch (parseErr) {
+          // Skip corrupted lines
+        }
+      }
+    } catch (err) {
+      // File doesn't exist or can't be read — return empty
+      entries = [];
+    }
+
+    return entries;
+  }
+
+  /**
+   * Write a note or append to an existing one
+   * @param {string} noteId - Unique note ID (lowercase, alphanumeric + hyphens, max 80 chars)
+   * @param {Object} options - Write options
+   * @param {string} options.author - Session name writing the note
+   * @param {string} options.category - Note category (must be in NOTEBOOK_CATEGORIES)
+   * @param {string} options.title - Human-readable title
+   * @param {string} options.content - Markdown content
+   * @param {string[]} [options.tags=[]] - Tags for categorization
+   * @returns {Object} { noteId, entryId, appended: boolean }
+   */
+  write(noteId, { author, category, title, content, tags = [] }) {
+    // Step 1: Validate inputs
+    _validateNoteId(noteId);
+
+    if (!author || typeof author !== 'string') {
+      throw new Error('Note author is required');
+    }
+
+    if (!NOTEBOOK_CATEGORIES.includes(category)) {
+      throw new Error(`Invalid category '${category}'. Must be one of: ${NOTEBOOK_CATEGORIES.join(', ')}`);
+    }
+
+    if (!title || typeof title !== 'string') {
+      throw new Error('Note title is required');
+    }
+
+    if (!content || typeof content !== 'string') {
+      throw new Error('Note content is required');
+    }
+
+    // Step 2: Build entry object
+    const entryId = `entry_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const entry = {
+      entryId,
+      author,
+      content,
+      timestamp: new Date().toISOString()
+    };
+
+    // Step 3: Acquire lock on the notebook index
+    acquireLock(this.locksDir, 'notebook-index');
+
+    try {
+      // Step 4: Read the current index
+      const index = readJsonSafe(this.indexPath, {});
+      let appended = false;
+
+      if (index[noteId]) {
+        // Existing note — collaborative append
+        appended = true;
+        index[noteId].updatedAt = new Date().toISOString();
+        index[noteId].entryCount += 1;
+
+        // Merge new tags (no duplicates)
+        if (tags.length > 0) {
+          const existingTags = index[noteId].tags || [];
+          const merged = [...new Set([...existingTags, ...tags])];
+          index[noteId].tags = merged;
+        }
+      } else {
+        // New note — create index entry
+        appended = false;
+        index[noteId] = {
+          noteId,
+          category,
+          title,
+          creator: author,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+          tags,
+          entryCount: 1
+        };
+      }
+
+      // Step 5: Save the index atomically
+      atomicWriteJson(this.indexPath, index);
+
+      // Step 6: Release index lock before JSONL append
+      releaseLock(this.locksDir, 'notebook-index');
+
+      // Step 7: Acquire per-note lock for JSONL append
+      acquireLock(this.locksDir, `notebook-${noteId}`);
+
+      try {
+        // Step 8: Append JSONL line
+        const jsonlPath = this._entryPath(noteId);
+        fs.appendFileSync(jsonlPath, JSON.stringify(entry) + '\n', 'utf-8');
+
+        // Step 9: Release the per-note lock
+        releaseLock(this.locksDir, `notebook-${noteId}`);
+
+        return { noteId, entryId, appended };
+
+      } catch (err) {
+        releaseLock(this.locksDir, `notebook-${noteId}`);
+        throw err;
+      }
+
+    } catch (err) {
+      // Ensure index lock is released on error (may already be released)
+      releaseLock(this.locksDir, 'notebook-index');
+      throw err;
+    }
+  }
+
+  /**
+   * Read a note with all its entries
+   * @param {string} noteId - The note to read
+   * @returns {Object} { noteId, category, title, creator, createdAt, updatedAt, tags, entries: [...], entryCount }
+   */
+  read(noteId) {
+    // Step 1: Validate note exists
+    const index = readJsonSafe(this.indexPath, {});
+    if (!index[noteId]) {
+      throw new Error(`Note '${noteId}' does not exist`);
+    }
+
+    // Step 2: Read all JSONL entries
+    const entries = this._readEntries(noteId);
+
+    // Step 3: Assemble full note
+    const meta = index[noteId];
+    return {
+      noteId: meta.noteId,
+      category: meta.category,
+      title: meta.title,
+      creator: meta.creator,
+      createdAt: meta.createdAt,
+      updatedAt: meta.updatedAt,
+      tags: meta.tags || [],
+      entries,
+      entryCount: meta.entryCount
+    };
+  }
+
+  /**
+   * Search notes by title, tags, and content
+   * @param {string} query - Search string (case-insensitive)
+   * @param {Object} [filters={}] - Optional filters
+   * @param {string} [filters.category] - Filter by category
+   * @param {string} [filters.author] - Filter by creator
+   * @param {string} [filters.tag] - Filter by tag
+   * @returns {Object} { query, results: [...], total }
+   */
+  search(query, { category, author, tag } = {}) {
+    if (!query || typeof query !== 'string') {
+      throw new Error('Search query is required');
+    }
+
+    const index = readJsonSafe(this.indexPath, {});
+    const lowerQuery = query.toLowerCase();
+    const results = [];
+    const contentScanNeeded = [];
+
+    // Step 1: Search index first (title and tag matches)
+    for (const meta of Object.values(index)) {
+      // Apply filters
+      if (category && meta.category !== category) continue;
+      if (author && meta.creator !== author) continue;
+      if (tag && (!meta.tags || !meta.tags.includes(tag))) continue;
+
+      // Check title match
+      if (meta.title && meta.title.toLowerCase().includes(lowerQuery)) {
+        results.push({
+          noteId: meta.noteId,
+          category: meta.category,
+          title: meta.title,
+          creator: meta.creator,
+          matchType: 'title'
+        });
+        continue;
+      }
+
+      // Check tag match
+      if (meta.tags && meta.tags.some(t => t.toLowerCase().includes(lowerQuery))) {
+        results.push({
+          noteId: meta.noteId,
+          category: meta.category,
+          title: meta.title,
+          creator: meta.creator,
+          matchType: 'tag'
+        });
+        continue;
+      }
+
+      // No index match — queue for content scan
+      contentScanNeeded.push(meta);
+    }
+
+    // Step 2: Scan JSONL files for content matches (only for unmatched notes)
+    for (const meta of contentScanNeeded) {
+      const entries = this._readEntries(meta.noteId);
+
+      const hasContentMatch = entries.some(entry =>
+        entry.content && entry.content.toLowerCase().includes(lowerQuery)
+      );
+
+      if (hasContentMatch) {
+        results.push({
+          noteId: meta.noteId,
+          category: meta.category,
+          title: meta.title,
+          creator: meta.creator,
+          matchType: 'content'
+        });
+      }
+    }
+
+    return { query, results, total: results.length };
+  }
+
+  /**
+   * List notes from index with optional filters
+   * @param {Object} [options={}] - List options
+   * @param {string} [options.category] - Filter by category
+   * @param {string} [options.author] - Filter by creator
+   * @param {string} [options.tag] - Filter by tag
+   * @param {number} [options.limit=50] - Max notes to return
+   * @returns {Object} { notes: [...], total }
+   */
+  list({ category, author, tag, limit = 50 } = {}) {
+    const index = readJsonSafe(this.indexPath, {});
+
+    // Convert index to array
+    let notes = Object.values(index);
+
+    // Apply filters
+    if (category) {
+      notes = notes.filter(n => n.category === category);
+    }
+
+    if (author) {
+      notes = notes.filter(n => n.creator === author);
+    }
+
+    if (tag) {
+      notes = notes.filter(n => n.tags && n.tags.includes(tag));
+    }
+
+    const total = notes.length;
+
+    // Sort by updatedAt descending (most recent first)
+    notes.sort((a, b) => {
+      const dateA = a.updatedAt || a.createdAt || '';
+      const dateB = b.updatedAt || b.createdAt || '';
+      return dateB.localeCompare(dateA);
+    });
+
+    // Apply limit
+    if (limit && notes.length > limit) {
+      notes = notes.slice(0, limit);
+    }
+
+    return { notes, total };
+  }
+}
+
+module.exports = { NotebookStore, NOTEBOOK_CATEGORIES };

package/src/prompts.js

@@ -141,6 +141,28 @@ mcp__multi-session__team_broadcast({ from: "${name}", content: "Completed: <what
 | \`contract_start\` | Begin working on an assigned contract |
 | \`contract_complete\` | Mark your contract as done |
 
+### Channels (persistent topic-based discussion — use for decisions, discoveries, blockers):
+| Tool | When to Use |
+|------|-------------|
+| \`channel_create\` | Create a new discussion channel (rarely needed — defaults exist) |
+| \`channel_post\` | Post a message to a channel (\`#design-decisions\`, \`#blockers\`, \`#discoveries\`, \`#conventions\`, \`#questions\`) |
+| \`channel_read\` | Read recent messages from a channel |
+| \`channel_subscribe\` | Subscribe to a channel for updates |
+| \`channel_list\` | List all available channels |
+
+### Notebook (shared knowledge scratchpad — use for research, gotchas, patterns):
+| Tool | When to Use |
+|------|-------------|
+| \`notebook_write\` | Write or append to a note (categories: research, decision, gotcha, pattern, plan, investigation, reference) |
+| \`notebook_read\` | Read a note with all its entries |
+| \`notebook_search\` | Search notes by keyword, category, or tag |
+| \`notebook_list\` | List all notebook entries |
+
+### Human Escalation (LAST RESORT — only when teammates + artifacts + channels can't resolve):
+| Tool | When to Use |
+|------|-------------|
+| \`ask_user\` | Ask the human user a question when genuinely stuck on an ambiguous decision |
+
 ## RULES
 
 IMPORTANT: Follow these rules strictly. Violating them causes coordination failures.
@@ -213,6 +235,66 @@ This is wrong because no one knows you're done, your work isn't discoverable via
 - Do NOT publish artifacts for incomplete or draft work. Publish when a unit of work is DONE.
 - Do NOT create contracts for tasks you can do yourself. Only create contracts for work that belongs to another session's domain.
 
+## COGNITIVE PROTOCOL: Think Before You Code
+
+You are not just a task executor — you are a thinking collaborator. Follow this protocol for every task:
+
+### Phase 1: Orient (before writing any code)
+- Read your inbox (\`team_check_inbox\`) — what context exists?
+- Read shared artifacts (\`artifact_get\`) — what conventions, schemas, contracts exist?
+- Read relevant channels (\`channel_read\` on \`#design-decisions\`, \`#conventions\`, \`#discoveries\`)
+- Read the project notebook (\`notebook_list\`, \`notebook_read\`) — what has the team learned?
+- Understand the WHY behind your task, not just the WHAT
+
+### Phase 2: Think (research and analyze)
+- If requirements are ambiguous, check channels and notebook first
+- If still unclear, use \`team_ask\` to consult a teammate
+- If genuinely stuck on a decision only a human can make, use \`ask_user\` (LAST RESORT)
+- Document your research in the notebook (\`notebook_write\`, category: \`research\` or \`investigation\`)
+
+### Phase 3: Plan (share your approach)
+- Post your implementation plan to \`#design-decisions\` channel before coding
+- If your plan affects other workers, post to relevant channels
+- Write your plan to the notebook (\`notebook_write\`, category: \`plan\`)
+- Wait briefly — if a teammate has concerns, they'll respond in the channel
+
+### Phase 4: Execute (implement with awareness)
+- Follow shared conventions from the conventions artifact
+- When you discover something unexpected, post to \`#discoveries\` channel
+- When you hit a blocker, post to \`#blockers\` channel immediately
+- When you find a gotcha (something that could trip up others), write it to the notebook (category: \`gotcha\`)
+
+### Phase 5: Verify (self-review)
+- Review your work against the conventions artifact
+- Check that your output matches expected formats
+- Verify your changes don't break assumptions other workers depend on
+
+### Phase 6: Deliver (publish and share)
+- Publish your artifact (\`artifact_publish\`)
+- Post a summary of what you built and any decisions you made to \`#design-decisions\`
+- Document any patterns worth reusing (\`notebook_write\`, category: \`pattern\`)
+- Broadcast completion (\`team_broadcast\`)
+
+### Channel Usage Guide
+
+| Channel | Purpose |
+|---------|---------|
+| \`#design-decisions\` | Post plans, architectural choices, approach changes |
+| \`#blockers\` | When you're stuck and need help (check here to help others too) |
+| \`#discoveries\` | Unexpected findings, API behaviors, edge cases |
+| \`#conventions\` | Convention questions, proposed changes, clarifications |
+| \`#questions\` | General questions for the team |
+
+### When to Escalate to Human (\`ask_user\`)
+
+ONLY use \`ask_user\` when ALL of these are true:
+1. The question involves a genuine ambiguity (not a technical problem)
+2. You've checked artifacts, conventions, channels, and notebook
+3. You've asked teammates via \`team_ask\` and they couldn't resolve it
+4. The decision has significant impact and guessing wrong would be costly
+
+Examples: "Should this API be public or internal?", "Which payment provider to use?", "Is PII allowed in logs?"
+
 ## BLAST RADIUS AWARENESS
 
 Before making any change, evaluate its impact on your teammates' work:
@@ -691,6 +773,10 @@ When all workers are done:
 | List available skills | \`skill_list\` |
 | Read a skill's content | \`skill_get\` |
 | Spawn worker with skills | \`team_spawn\` with \`skills\` parameter |
+| Monitor team discussions | \`channel_read\`, \`channel_list\` |
+| Monitor team knowledge | \`notebook_read\`, \`notebook_list\` |
+| Check pending user questions | \`user_list_pending\` |
+| Answer a worker's question | \`user_respond\` |
 | Clean up between runs | \`team_reset\` |
 
 ## WHAT GOES WRONG (And How to Avoid It)
@@ -817,6 +903,29 @@ When spawning workers, assign relevant expertise skills to improve output qualit
 - devops → devops
 - security → security
 - fullstack → nodejs-backend, react-frontend, typescript
+
+### Rule 9: Surface worker questions to the user
+
+Workers can ask the human user questions via \`ask_user\` when genuinely stuck on ambiguous decisions.
+
+- After spawning workers, periodically check for pending questions: use \`user_list_pending\` to see unanswered escalations
+- When you see a pending question, present it to the user clearly with the worker's context
+- After the user answers, relay it with \`user_respond\`
+- Do NOT answer on behalf of the user — relay their actual response
+- If multiple questions are pending, prioritize by priority level (urgent > high > normal > low)
+
+### Monitoring Channels and Notebook
+
+As orchestrator, you can monitor team collaboration through channels and the notebook:
+
+| Tool | Purpose |
+|------|---------|
+| \`channel_list\` | See all active channels and subscriber counts |
+| \`channel_read\` | Read channel messages to monitor discussions, decisions, and blockers |
+| \`notebook_list\` | See all notebook entries by category |
+| \`notebook_read\` | Read specific notes for research, decisions, or gotchas workers documented |
+| \`user_list_pending\` | Check for unanswered worker questions that need human input |
+| \`user_respond\` | Relay the human user's answer to a worker's question |
 `;
 }