brainclaw 0.19.5 → 0.19.7

package/README.md

@@ -118,7 +118,7 @@ brainclaw plan create "Coordinate auth rollout" --priority high
 brainclaw context --json
 ```
 
-→ [Full quickstart guide](https://github.com/jberdah/brainclaw/blob/master/docs/quickstart.md)
+Detailed Markdown guides are bundled in the npm package under `docs/`.
 
 ---
 
@@ -154,25 +154,27 @@ brainclaw can also expose collaboration views through MCP-readable tools, includ
 
 ---
 
-## Documentation
-
-| | |
-|---|---|
-| [docs/quickstart.md](https://github.com/jberdah/brainclaw/blob/master/docs/quickstart.md) | Get started in 5 minutes |
-| [docs/cli.md](https://github.com/jberdah/brainclaw/blob/master/docs/cli.md) | Full command reference |
-| [docs/concepts/memory.md](https://github.com/jberdah/brainclaw/blob/master/docs/concepts/memory.md) | What "memory" means in brainclaw |
-| [docs/concepts/plans-and-claims.md](https://github.com/jberdah/brainclaw/blob/master/docs/concepts/plans-and-claims.md) | Coordination layer |
-| [docs/concepts/runtime-notes.md](https://github.com/jberdah/brainclaw/blob/master/docs/concepts/runtime-notes.md) | Ephemeral observations |
-| [docs/integrations/overview.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/overview.md) | How to integrate with any agent |
-| [docs/integrations/cursor.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/cursor.md) | Cursor |
-| [docs/integrations/claude-code.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/claude-code.md) | Claude Code |
-| [docs/integrations/copilot.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/copilot.md) | GitHub Copilot |
-| [docs/integrations/codex.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/codex.md) | Codex |
-| [docs/integrations/mcp.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/mcp.md) | MCP tools |
-| [docs/storage.md](https://github.com/jberdah/brainclaw/blob/master/docs/storage.md) | Storage model |
-| [docs/security.md](https://github.com/jberdah/brainclaw/blob/master/docs/security.md) | Security model |
-| [docs/review.md](https://github.com/jberdah/brainclaw/blob/master/docs/review.md) | Reflective review |
-| [docs/reputation.md](https://github.com/jberdah/brainclaw/blob/master/docs/reputation.md) | Reputation signals |
+## Documentation
+
+The npm package includes the Markdown docs below under `docs/`. Public web docs on `brainclaw.dev` are still being rolled out, so the npm README does not depend on private GitHub links.
+
+| | |
+|---|---|
+| `docs/quickstart.md` | Get started in 5 minutes |
+| `docs/cli.md` | Full command reference |
+| `docs/concepts/memory.md` | What "memory" means in brainclaw |
+| `docs/concepts/plans-and-claims.md` | Coordination layer |
+| `docs/concepts/runtime-notes.md` | Ephemeral observations |
+| `docs/integrations/overview.md` | How to integrate with any agent |
+| `docs/integrations/cursor.md` | Cursor |
+| `docs/integrations/claude-code.md` | Claude Code |
+| `docs/integrations/copilot.md` | GitHub Copilot |
+| `docs/integrations/codex.md` | Codex |
+| `docs/integrations/mcp.md` | MCP tools |
+| `docs/storage.md` | Storage model |
+| `docs/security.md` | Security model |
+| `docs/review.md` | Reflective review |
+| `docs/reputation.md` | Reputation signals |
 
 ---
 

package/dist/commands/accept.js

@@ -1,7 +1,6 @@
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { memoryExists, withStoreLock } from '../core/io.js';
 import { loadCandidate, archiveCandidate, resolveIdOrAlias } from '../core/candidates.js';
-import { loadState, saveState } from '../core/state.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { loadState, persistState } from '../core/state.js';
 import { generateIdWithLabel, nowISO } from '../core/ids.js';
 import { generateTrapIdWithLabel } from '../core/traps.js';
 import { requireMinimumTrustLevel, requireRegisteredAgentIdentity } from '../core/agent-registry.js';
@@ -36,109 +35,108 @@ export function acceptCandidate(id, by, cwd, byId) {
     });
     requireMinimumTrustLevel(actorIdentity, 'trusted');
     const actor = actorIdentity.agent_name;
-    const state = loadState(cwd);
     let promotedItemId = '';
-    // Promote candidate into canonical state based on type
-    switch (candidate.type) {
-        case 'constraint': {
-            const { id: entryId, short_label } = generateIdWithLabel('active_constraints', cwd);
-            const entry = {
-                id: entryId,
-                short_label,
-                text: candidate.text,
-                created_at: candidate.created_at,
-                author: candidate.author,
-                author_id: candidate.author_id,
-                project_id: candidate.project_id,
-                host_id: candidate.host_id,
-                session_id: candidate.session_id,
-                status: 'active',
-                tags: candidate.tags,
-            };
-            state.active_constraints.push(entry);
-            promotedItemId = entryId;
-            break;
+    withStoreLock(cwd, () => {
+        const state = loadState(cwd);
+        switch (candidate.type) {
+            case 'constraint': {
+                const { id: entryId, short_label } = generateIdWithLabel('active_constraints', cwd);
+                const entry = {
+                    id: entryId,
+                    short_label,
+                    text: candidate.text,
+                    created_at: candidate.created_at,
+                    author: candidate.author,
+                    author_id: candidate.author_id,
+                    project_id: candidate.project_id,
+                    host_id: candidate.host_id,
+                    session_id: candidate.session_id,
+                    status: 'active',
+                    tags: candidate.tags,
+                };
+                state.active_constraints.push(entry);
+                promotedItemId = entryId;
+                break;
+            }
+            case 'decision': {
+                const { id: entryId, short_label } = generateIdWithLabel('recent_decisions', cwd);
+                const entry = {
+                    id: entryId,
+                    short_label,
+                    text: candidate.text,
+                    created_at: candidate.created_at,
+                    author: candidate.author,
+                    author_id: candidate.author_id,
+                    project_id: candidate.project_id,
+                    host_id: candidate.host_id,
+                    session_id: candidate.session_id,
+                    related_paths: candidate.related_paths,
+                    plan_id: candidate.plan_id,
+                    tags: candidate.tags,
+                };
+                state.recent_decisions.push(entry);
+                promotedItemId = entryId;
+                break;
+            }
+            case 'trap': {
+                const { id: entryId, short_label } = generateTrapIdWithLabel(cwd);
+                const entry = {
+                    id: entryId,
+                    short_label,
+                    text: candidate.text,
+                    created_at: candidate.created_at,
+                    author: candidate.author,
+                    author_id: candidate.author_id,
+                    project_id: candidate.project_id,
+                    host_id: candidate.host_id,
+                    session_id: candidate.session_id,
+                    status: 'active',
+                    severity: candidate.severity ?? 'medium',
+                    tags: candidate.tags,
+                    plan_id: candidate.plan_id,
+                    visibility: 'shared',
+                };
+                state.known_traps.push(entry);
+                promotedItemId = entryId;
+                break;
+            }
+            case 'handoff': {
+                const { id: entryId, short_label } = generateIdWithLabel('open_handoffs', cwd);
+                const entry = {
+                    id: entryId,
+                    short_label,
+                    from: candidate.from ?? 'unknown',
+                    to: candidate.to ?? 'unknown',
+                    text: candidate.text,
+                    created_at: candidate.created_at,
+                    author: candidate.author,
+                    author_id: candidate.author_id,
+                    project_id: candidate.project_id,
+                    host_id: candidate.host_id,
+                    session_id: candidate.session_id,
+                    status: 'open',
+                    tags: candidate.tags,
+                };
+                state.open_handoffs.push(entry);
+                promotedItemId = entryId;
+                break;
+            }
         }
-        case 'decision': {
-            const { id: entryId, short_label } = generateIdWithLabel('recent_decisions', cwd);
-            const entry = {
-                id: entryId,
-                short_label,
-                text: candidate.text,
-                created_at: candidate.created_at,
-                author: candidate.author,
-                author_id: candidate.author_id,
-                project_id: candidate.project_id,
-                host_id: candidate.host_id,
-                session_id: candidate.session_id,
-                related_paths: candidate.related_paths,
-                plan_id: candidate.plan_id,
-                tags: candidate.tags,
-            };
-            state.recent_decisions.push(entry);
-            promotedItemId = entryId;
-            break;
-        }
-        case 'trap': {
-            const { id: entryId, short_label } = generateTrapIdWithLabel(cwd);
-            const entry = {
-                id: entryId,
-                short_label,
-                text: candidate.text,
-                created_at: candidate.created_at,
-                author: candidate.author,
-                author_id: candidate.author_id,
-                project_id: candidate.project_id,
-                host_id: candidate.host_id,
-                session_id: candidate.session_id,
-                status: 'active',
-                severity: candidate.severity ?? 'medium',
-                tags: candidate.tags,
-                plan_id: candidate.plan_id,
-                visibility: 'shared',
-            };
-            state.known_traps.push(entry);
-            promotedItemId = entryId;
-            break;
-        }
-        case 'handoff': {
-            const { id: entryId, short_label } = generateIdWithLabel('open_handoffs', cwd);
-            const entry = {
-                id: entryId,
-                short_label,
-                from: candidate.from ?? 'unknown',
-                to: candidate.to ?? 'unknown',
-                text: candidate.text,
-                created_at: candidate.created_at,
-                author: candidate.author,
-                author_id: candidate.author_id,
-                project_id: candidate.project_id,
-                host_id: candidate.host_id,
-                session_id: candidate.session_id,
-                status: 'open',
-                tags: candidate.tags,
-            };
-            state.open_handoffs.push(entry);
-            promotedItemId = entryId;
-            break;
-        }
-    }
-    saveState(state, cwd);
-    writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state, cwd));
-    // Archive candidate (use resolved hash ID)
-    candidate.status = 'accepted';
-    candidate.resolved_at = nowISO();
-    candidate.resolved_by = actor;
-    archiveCandidate(candidate, 'accepted', cwd);
-    appendAuditEntry({
-        actor,
-        actor_id: actorIdentity.agent_id,
-        action: 'accept',
-        item_id: resolvedId,
-        item_type: candidate.type,
-        after: { type: candidate.type, text: candidate.text },
-        reason: 'trusted-agent',
-    }, cwd);
+        persistState(state, cwd);
+        candidate.status = 'accepted';
+        candidate.resolved_at = nowISO();
+        candidate.resolved_by = actor;
+        archiveCandidate(candidate, 'accepted', cwd);
+        appendAuditEntry({
+            actor,
+            actor_id: actorIdentity.agent_id,
+            action: 'accept',
+            item_id: resolvedId,
+            item_type: candidate.type,
+            after: { type: candidate.type, text: candidate.text },
+            reason: 'trusted-agent',
+        }, cwd);
+    });
     return {
         candidate_id: resolvedId,
         candidate_type: candidate.type,

package/dist/commands/add-step.js

@@ -1,7 +1,6 @@
-import { loadState, saveState } from '../core/state.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { loadState, persistState } from '../core/state.js';
+import { memoryExists } from '../core/io.js';
 import { generateId, nowISO } from '../core/ids.js';
-import { generateMarkdown } from '../core/markdown.js';
 import { validateCliInput } from '../core/input-validation.js';
 export function runAddStep(planId, text, options = {}) {
     if (!memoryExists()) {
@@ -25,8 +24,7 @@ export function runAddStep(planId, text, options = {}) {
     };
     plan.steps = [...(plan.steps ?? []), step];
     plan.updated_at = nowISO();
-    saveState(state);
-    writeFileAtomic(memoryPath('project.md'), generateMarkdown(state));
+    persistState(state);
     const total = plan.steps.length;
     const done = plan.steps.filter((s) => s.status === 'done').length;
     console.log(`✔ Step added: [${step.id}] ${text}`);

package/dist/commands/capability.js

@@ -1,7 +1,6 @@
-import { loadState, saveState } from '../core/state.js';
+import { loadState, persistState } from '../core/state.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { memoryExists } from '../core/io.js';
 import { generateIdWithLabel, nowISO } from '../core/ids.js';
 import { loadConfig } from '../core/config.js';
 import { scanText } from '../core/security.js';
@@ -80,8 +79,7 @@ function runCapabilityAdd(name, description, options, cwd) {
     // For now, store as decision to avoid schema migration
     // Will migrate to separate capability storage in v0.16
     state.recent_decisions.push(entry);
-    saveState(state, cwd);
-    writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state));
+    persistState(state, cwd);
     console.log(`✔ Capability added: [${id}] ${name}`);
     console.log('  (Stored in decisions for now; will move to dedicated registry in v0.16)');
 }

package/dist/commands/claim.js

@@ -1,5 +1,5 @@
 import { buildOperationalIdentity } from '../core/identity.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { memoryExists, memoryPath, withStoreLock, writeFileAtomic } from '../core/io.js';
 import { saveClaim, generateClaimId, listClaims } from '../core/claims.js';
 import { generateMarkdown } from '../core/markdown.js';
 import { loadState, saveState } from '../core/state.js';
@@ -72,18 +72,20 @@ export function runClaim(description, options) {
         status: 'active',
         expires_at: options.ttl ? parseTtl(options.ttl) : undefined,
     };
-    if (plan) {
-        if (!plan.assignee) {
-            plan.assignee = actor.agent;
+    withStoreLock(options.cwd, () => {
+        if (plan) {
+            if (!plan.assignee) {
+                plan.assignee = actor.agent;
+            }
+            if (plan.status === 'todo') {
+                plan.status = 'in_progress';
+            }
+            plan.updated_at = nowISO();
+            saveState(state, options.cwd);
         }
-        if (plan.status === 'todo') {
-            plan.status = 'in_progress';
-        }
-        plan.updated_at = nowISO();
-        saveState(state, options.cwd);
-    }
-    saveClaim(claim, options.cwd);
-    writeFileAtomic(memoryPath('project.md', options.cwd), generateMarkdown(plan ? state : loadState(options.cwd), options.cwd));
+        saveClaim(claim, options.cwd);
+        writeFileAtomic(memoryPath('project.md', options.cwd), generateMarkdown(plan ? state : loadState(options.cwd), options.cwd));
+    });
     const planInfo = claim.plan_id ? ` [plan ${claim.plan_id}]` : '';
     const ttlInfo = claim.expires_at ? ` (expires ${claim.expires_at.slice(0, 16).replace('T', ' ')})` : '';
     const storeLabel = options.store && options.store !== 'local' ? ` [store:${options.store}]` : '';

package/dist/commands/complete-step.js

@@ -1,7 +1,6 @@
-import { loadState, saveState } from '../core/state.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { loadState, persistState } from '../core/state.js';
+import { memoryExists } from '../core/io.js';
 import { nowISO } from '../core/ids.js';
-import { generateMarkdown } from '../core/markdown.js';
 export function runCompleteStep(planId, stepId) {
     if (!memoryExists()) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
@@ -21,8 +20,7 @@ export function runCompleteStep(planId, stepId) {
     step.status = 'done';
     step.updated_at = nowISO();
     plan.updated_at = nowISO();
-    saveState(state);
-    writeFileAtomic(memoryPath('project.md'), generateMarkdown(state));
+    persistState(state);
     const total = plan.steps.length;
     const done = plan.steps.filter((s) => s.status === 'done').length;
     console.log(`✔ Step completed: [${step.id}] ${step.text}`);

package/dist/commands/constraint.js

@@ -1,10 +1,9 @@
-import { loadState, saveState } from '../core/state.js';
+import { loadState, persistState } from '../core/state.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
 import { loadConfig } from '../core/config.js';
-import { generateMarkdown } from '../core/markdown.js';
 import { generateIdWithLabel, nowISO } from '../core/ids.js';
 import { scanText } from '../core/security.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { memoryExists } from '../core/io.js';
 import { validateCliInput } from '../core/input-validation.js';
 import { resolveTargetStore } from '../core/store-resolution.js';
 export function runConstraint(text, options = {}) {
@@ -37,8 +36,7 @@ export function runConstraint(text, options = {}) {
         related_paths: options.path,
     };
     state.active_constraints.push(entry);
-    saveState(state, cwd);
-    writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state));
+    persistState(state, cwd);
     console.log(`✔ Constraint added: [${id}] ${text}`);
 }
 //# sourceMappingURL=constraint.js.map

package/dist/commands/decision.js

@@ -1,10 +1,9 @@
-import { loadState, saveState } from '../core/state.js';
+import { loadState, persistState } from '../core/state.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
 import { loadConfig } from '../core/config.js';
-import { generateMarkdown } from '../core/markdown.js';
 import { generateIdWithLabel, nowISO } from '../core/ids.js';
 import { scanText } from '../core/security.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { memoryExists } from '../core/io.js';
 import { validateCliInput } from '../core/input-validation.js';
 import { resolveTargetStore } from '../core/store-resolution.js';
 export function runDecision(text, options = {}) {
@@ -37,9 +36,7 @@ export function runDecision(text, options = {}) {
         plan_id: options.plan,
     };
     state.recent_decisions.push(entry);
-    saveState(state, cwd);
-    // Rebuild markdown
-    writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state));
+    persistState(state, cwd);
     console.log(`✔ Decision added: [${id}] ${text}`);
 }
 //# sourceMappingURL=decision.js.map

package/dist/commands/delete-plan.js

@@ -1,6 +1,5 @@
-import { loadState, saveState } from '../core/state.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
-import { generateMarkdown } from '../core/markdown.js';
+import { loadState, persistState } from '../core/state.js';
+import { memoryExists } from '../core/io.js';
 export function runDeletePlan(id, options = {}) {
     if (!memoryExists(options.cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
@@ -13,8 +12,7 @@ export function runDeletePlan(id, options = {}) {
         process.exit(1);
     }
     const [plan] = state.plan_items.splice(index, 1);
-    saveState(state, options.cwd);
-    writeFileAtomic(memoryPath('project.md', options.cwd), generateMarkdown(state, options.cwd));
+    persistState(state, options.cwd);
     console.log(`✔ Plan item deleted: [${plan.id}] ${plan.text}`);
 }
 //# sourceMappingURL=delete-plan.js.map

package/dist/commands/handoff.js

@@ -1,11 +1,10 @@
 import { execSync } from 'node:child_process';
-import { loadState, saveState } from '../core/state.js';
+import { loadState, persistState } from '../core/state.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
 import { loadConfig } from '../core/config.js';
-import { generateMarkdown } from '../core/markdown.js';
 import { generateIdWithLabel, nowISO } from '../core/ids.js';
 import { scanText } from '../core/security.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { memoryExists } from '../core/io.js';
 import { validateCliInput } from '../core/input-validation.js';
 import { resolveTargetStore } from '../core/store-resolution.js';
 export function runHandoff(text, options) {
@@ -56,8 +55,7 @@ export function runHandoff(text, options) {
         snapshot: diff ? { diff } : undefined,
     };
     state.open_handoffs.push(entry);
-    saveState(state, cwd);
-    writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(state, cwd));
+    persistState(state, cwd);
     console.log(`✔ Handoff added: [${id}] ${options.from} → ${options.to}: ${text}`);
 }
 //# sourceMappingURL=handoff.js.map

package/dist/commands/instruction.js

@@ -1,7 +1,7 @@
 import { resolveAgentScope, resolveCurrentAgentName } from '../core/agent-registry.js';
 import { loadConfig } from '../core/config.js';
 import { createInstruction } from '../core/instructions.js';
-import { memoryExists, memoryPath, writeFileAtomic } from '../core/io.js';
+import { memoryExists, memoryPath, withStoreLock, writeFileAtomic } from '../core/io.js';
 import { generateMarkdown } from '../core/markdown.js';
 import { loadState } from '../core/state.js';
 import { scanText } from '../core/security.js';
@@ -25,14 +25,21 @@ export function runInstruction(text, options = {}) {
             process.exit(1);
         }
     }
-    const entry = createInstruction(text, {
-        layer,
-        scope,
-        tags: options.tag,
-        author: options.author ?? resolveCurrentAgentName(cwd),
-        supersedes: options.supersedes,
-    }, cwd);
-    writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd)));
+    let entry;
+    withStoreLock(cwd, () => {
+        entry = createInstruction(text, {
+            layer,
+            scope,
+            tags: options.tag,
+            author: options.author ?? resolveCurrentAgentName(cwd),
+            supersedes: options.supersedes,
+        }, cwd);
+        writeFileAtomic(memoryPath('project.md', cwd), generateMarkdown(loadState(cwd)));
+    });
+    if (!entry) {
+        console.error('Error: failed to persist instruction.');
+        process.exit(1);
+    }
     console.log(`✔ Instruction added: [${entry.id}] <${entry.layer}${entry.scope ? `:${entry.scope}` : ''}> ${entry.text}`);
 }
 function resolveScope(layer, options, cwd) {