brainclaw 0.19.14 → 0.21.0

package/dist/core/context.js

@@ -1,7 +1,8 @@
+import path from 'node:path';
 import { loadConfig } from './config.js';
 import { resolveCrossProjectLinks, loadCrossProjectState } from './cross-project.js';
 import { buildContextDiff } from './context-diff.js';
-import { resolveStoreChain } from './store-resolution.js';
+import { resolveContextStoreCwd, resolveStoreChain } from './store-resolution.js';
 import { findAgentIdentityByName, resolveCurrentAgentIdentity } from './agent-registry.js';
 import { hasReusableBootstrapProfile, runBootstrapProfile, selectDerivedSignals } from './bootstrap.js';
 import { buildAgentToolingContext } from './agent-context.js';
@@ -18,26 +19,28 @@ import { isTrapActive, listOperationalTraps } from './traps.js';
 import { buildEstimationReport } from '../commands/estimation-report.js';
 export const CONTEXT_SCHEMA_VERSION = '1.2';
 export function buildContext(options = {}) {
-    const state = loadState(options.cwd);
-    const config = loadConfig(options.cwd);
+    const requestedCwd = options.cwd ?? process.cwd();
+    const contextCwd = resolveContextStoreCwd(requestedCwd, options.target);
+    const state = loadState(contextCwd);
+    const config = loadConfig(contextCwd);
     // Resolve parent stores for multi-store merge (walk-up from cwd)
-    const storeChain = resolveStoreChain(options.cwd ?? process.cwd());
+    const storeChain = resolveStoreChain(contextCwd);
     const profile = options.profile ?? config.profile ?? 'dev';
     const projectMode = config.project_mode ?? 'auto';
     const projectStrategy = config.projects?.strategy ?? 'manual';
     const currentHost = resolveCurrentHostId();
-    const memoryVersion = getVisibleMemoryVersion({ cwd: options.cwd, hostId: options.host, allHosts: options.allHosts });
-    const target = options.target?.trim() ?? '';
+    const memoryVersion = getVisibleMemoryVersion({ cwd: contextCwd, hostId: options.host, allHosts: options.allHosts });
+    const target = normalizeContextTarget(options.target, requestedCwd, contextCwd);
     const project = options.project?.trim() || inferProjectFromTarget(target, config);
     const agent = options.agent?.trim() || config.current_agent?.trim();
     const currentAgentIdentity = agent
-        ? (options.agent?.trim() ? findAgentIdentityByName(agent, options.cwd) : resolveCurrentAgentIdentity(options.cwd))
+        ? (options.agent?.trim() ? findAgentIdentityByName(agent, contextCwd) : resolveCurrentAgentIdentity(contextCwd))
         : undefined;
     const profileMaxItems = { compact: 6, copilot: 5, quick: 3 };
     const maxItems = options.maxItems ?? profileMaxItems[profile] ?? 8;
     const maxChars = options.maxChars && options.maxChars > 0 ? options.maxChars : undefined;
     // Instructions will be resolved after parent-store merge below (line ~460)
-    const rankingLookup = buildReputationRankingLookup(options.cwd);
+    const rankingLookup = buildReputationRankingLookup(contextCwd);
     const profileSections = {
         compact: ['plan', 'constraint'],
         copilot: ['constraint', 'trap'],
@@ -123,7 +126,7 @@ export function buildContext(options = {}) {
             },
         });
     }
-    for (const trap of listOperationalTraps({ hostId: options.host, includeAllHosts: options.allHosts }, options.cwd).filter((entry) => isTrapActive(entry))) {
+    for (const trap of listOperationalTraps({ hostId: options.host, includeAllHosts: options.allHosts }, contextCwd).filter((entry) => isTrapActive(entry))) {
         items.push({
             id: trap.id,
             section: 'trap',
@@ -157,7 +160,7 @@ export function buildContext(options = {}) {
     const runtimeNotes = listRuntimeNotes({
         hostId: options.host,
         includeAllHosts: options.allHosts,
-    }, options.cwd);
+    }, contextCwd);
     for (const note of runtimeNotes) {
         if (project && note.project && note.project !== project) {
             continue;
@@ -191,7 +194,7 @@ export function buildContext(options = {}) {
         });
     }
     if (options.includePending) {
-        for (const p of listCandidates('pending', options.cwd)) {
+        for (const p of listCandidates('pending', contextCwd)) {
             const meta = [`${p.type}`, `stars:${p.star_count ?? 0}`, `uses:${p.usage_count ?? 0}`];
             if (p.author_id)
                 meta.push(`author_id:${p.author_id}`);
@@ -294,7 +297,7 @@ export function buildContext(options = {}) {
         catch { /* non-fatal */ }
     }
     // Merge instructions from all stores in the chain
-    const allInstructions = [...loadInstructions(options.cwd)];
+    const allInstructions = [...loadInstructions(contextCwd)];
     for (const parentStore of storeChain.slice(1)) {
         try {
             const parentInstrs = loadInstructions(parentStore.cwd);
@@ -330,34 +333,34 @@ export function buildContext(options = {}) {
         .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
         .slice(0, maxItems);
     const selected = maxChars ? applyCharBudget(ranked, maxChars) : ranked;
-    const resumeSummary = buildCurrentAgentResumeSummary(options.cwd);
+    const resumeSummary = buildCurrentAgentResumeSummary(contextCwd);
     const scopedActivity = buildScopedActivity({
         target,
         project,
         state,
         runtimeNotes,
-        pendingCandidates: listCandidates('pending', options.cwd),
+        pendingCandidates: listCandidates('pending', contextCwd),
     });
     const memoryDensity = classifyMemoryDensity(selected.length);
     const bootstrapEnabled = options.bootstrap !== false;
-    let bootstrapAvailable = hasReusableBootstrapProfile(target, options.cwd);
+    let bootstrapAvailable = hasReusableBootstrapProfile(target, contextCwd);
     let derivedSignals;
     if (bootstrapEnabled && (options.refreshBootstrap || memoryDensity === 'low')) {
         const bootstrap = runBootstrapProfile({
             target,
             refresh: options.refreshBootstrap,
-            cwd: options.cwd,
+            cwd: contextCwd,
         });
         bootstrapAvailable = bootstrap.profile.seed_count > 0;
         if (memoryDensity === 'low') {
-            const signals = selectDerivedSignals(target, 5, options.cwd);
+            const signals = selectDerivedSignals(target, 5, contextCwd);
             if (signals.length > 0) {
                 derivedSignals = signals;
             }
         }
     }
     else if (bootstrapEnabled && bootstrapAvailable && memoryDensity === 'low') {
-        const signals = selectDerivedSignals(target, 5, options.cwd);
+        const signals = selectDerivedSignals(target, 5, contextCwd);
         if (signals.length > 0) {
             derivedSignals = signals;
         }
@@ -365,7 +368,7 @@ export function buildContext(options = {}) {
     const executionSensitive = isExecutionSensitiveTarget(target);
     const derivedUsesExecution = derivedSignals?.some((signal) => signal.source_kind === 'machine') ?? false;
     const derivedUsesTooling = derivedSignals?.some((signal) => signal.source_kind === 'skill' || signal.source_kind === 'mcp') ?? false;
-    const rawAgentTooling = buildAgentToolingContext({ cwd: options.cwd });
+    const rawAgentTooling = buildAgentToolingContext({ cwd: contextCwd });
     const actionableAgentRules = rawAgentTooling.agents_rules.length > 0;
     const blockingTooling = rawAgentTooling.mcp_servers.some((server) => server.availability === 'missing_command');
     const shouldExposeExecution = memoryDensity === 'low' || executionSensitive || derivedUsesExecution;
@@ -375,7 +378,7 @@ export function buildContext(options = {}) {
         || actionableAgentRules
         || blockingTooling;
     const executionContext = shouldExposeExecution
-        ? compactExecutionContext(buildExecutionContext({ cwd: options.cwd }))
+        ? compactExecutionContext(buildExecutionContext({ cwd: contextCwd }))
         : undefined;
     const agentTooling = shouldExposeAgentTooling
         ? summariseAgentTooling(rawAgentTooling)
@@ -385,7 +388,7 @@ export function buildContext(options = {}) {
     if (currentAgentIdentity || agent) {
         const agentName = agent;
         const agentId = currentAgentIdentity?.agent_id;
-        const allClaims = [...listClaims(options.cwd), ...parentStoreClaims];
+        const allClaims = [...listClaims(contextCwd), ...parentStoreClaims];
         const activeClaims = allClaims.filter((c) => c.status === 'active' && (agentId ? c.agent_id === agentId : c.agent === agentName));
         const claimPlanIds = new Set(activeClaims.map((c) => c.plan_id).filter(Boolean));
         const inProgressPlans = state.plan_items.filter((p) => p.status === 'in_progress' &&
@@ -399,7 +402,7 @@ export function buildContext(options = {}) {
     }
     // Cross-project items (subscriber links — read-only, always injected, bypass scoring)
     const crossProjectItems = [];
-    for (const link of resolveCrossProjectLinks(options.cwd)) {
+    for (const link of resolveCrossProjectLinks(contextCwd)) {
         if (!link.available)
             continue;
         try {
@@ -448,7 +451,7 @@ export function buildContext(options = {}) {
         context_diff: options.sinceSession
             ? buildContextDiff({
                 session: options.sinceSession,
-                cwd: options.cwd,
+                cwd: contextCwd,
                 includeItems: true,
             })
             : undefined,
@@ -460,7 +463,7 @@ export function buildContext(options = {}) {
             : undefined,
         estimation_calibration: (() => {
             try {
-                const report = buildEstimationReport({ agent, cwd: options.cwd });
+                const report = buildEstimationReport({ agent, cwd: contextCwd });
                 return report.summary.with_both >= 3 ? report.summary.calibration_hint : undefined;
             }
             catch {
@@ -1053,6 +1056,26 @@ function tokenise(input) {
         .map((x) => x.trim())
         .filter(Boolean);
 }
+function normalizeContextTarget(target, requestedCwd, contextCwd) {
+    const trimmed = target?.trim() ?? '';
+    if (!trimmed) {
+        return '';
+    }
+    if (path.resolve(requestedCwd) === path.resolve(contextCwd)) {
+        return trimmed;
+    }
+    if (!(path.isAbsolute(trimmed) || trimmed.includes('/') || trimmed.includes('\\') || trimmed.startsWith('.'))) {
+        return trimmed;
+    }
+    const absoluteTarget = path.isAbsolute(trimmed)
+        ? path.resolve(trimmed)
+        : path.resolve(requestedCwd, trimmed);
+    const relativeToContext = path.relative(contextCwd, absoluteTarget);
+    if (relativeToContext.startsWith('..') || path.isAbsolute(relativeToContext)) {
+        return trimmed;
+    }
+    return relativeToContext.split(path.sep).join('/');
+}
 function matchesPath(pattern, target) {
     if (pattern === target)
         return true;

package/dist/core/instruction-templates.js

@@ -0,0 +1,308 @@
+/**
+ * Adaptive instruction file templates — generates brainclaw section content
+ * based on the agent's capability profile (tier A/B/C).
+ *
+ * Core (static) vs Run (dynamic) separation:
+ *   Core: protocol, "why brainclaw", constraints, instructions, estimation rule
+ *   Run:  traps, plans, decisions, claims, handoffs, runtime notes
+ *
+ * Tier A (MCP + hooks): lightweight — hooks inject run content automatically
+ * Tier B (MCP, no hooks): directive — includes top traps, forces MCP calls
+ * Tier C (no MCP): rich — includes plans, traps, decisions (only source)
+ */
+/**
+ * Render the brainclaw section content for an instruction file,
+ * adapted to the agent's capability profile.
+ */
+export function renderBrainclawSection(input) {
+    const { profile } = input;
+    switch (profile.templateTier) {
+        case 'A': return renderTierA(input);
+        case 'B': return renderTierB(input);
+        case 'C': return renderTierC(input);
+    }
+}
+// ─── Tier A: Full integration (MCP + hooks) ─────────────────────────────────
+function renderTierA(input) {
+    const sections = [];
+    const included = [];
+    sections.push(renderHeader(input));
+    included.push('header');
+    sections.push(renderWhySection(input.profile));
+    included.push('why');
+    sections.push(renderProtocolTierA());
+    included.push('protocol');
+    sections.push(renderEstimationRule());
+    included.push('estimation');
+    sections.push(renderVersionCheckRule());
+    included.push('version-check');
+    const constraints = renderConstraints(input.state);
+    if (constraints) {
+        sections.push(constraints);
+        included.push('constraints');
+    }
+    const instructions = renderInstructions(input.resolvedInstructions);
+    if (instructions) {
+        sections.push(instructions);
+        included.push('instructions');
+    }
+    return {
+        content: sections.join('\n\n'),
+        tier: 'A',
+        sectionsIncluded: included,
+    };
+}
+// ─── Tier B: Standard integration (MCP, no hooks) ───────────────────────────
+function renderTierB(input) {
+    const sections = [];
+    const included = [];
+    sections.push(renderHeader(input));
+    included.push('header');
+    sections.push(renderWhySection(input.profile));
+    included.push('why');
+    sections.push(renderProtocolTierB());
+    included.push('protocol');
+    sections.push(renderEstimationRule());
+    included.push('estimation');
+    sections.push(renderVersionCheckRule());
+    included.push('version-check');
+    const constraints = renderConstraints(input.state);
+    if (constraints) {
+        sections.push(constraints);
+        included.push('constraints');
+    }
+    const instructions = renderInstructions(input.resolvedInstructions);
+    if (instructions) {
+        sections.push(instructions);
+        included.push('instructions');
+    }
+    // Tier B includes top traps statically (agent has no hooks to get them)
+    const traps = renderTopTraps(input.state, input.maxTraps ?? 5);
+    if (traps) {
+        sections.push(traps);
+        included.push('traps');
+    }
+    return {
+        content: sections.join('\n\n'),
+        tier: 'B',
+        sectionsIncluded: included,
+    };
+}
+// ─── Tier C: Limited integration (no MCP) ────────────────────────────────────
+function renderTierC(input) {
+    const sections = [];
+    const included = [];
+    sections.push(renderHeader(input));
+    included.push('header');
+    sections.push(renderWhySection(input.profile));
+    included.push('why');
+    sections.push(renderProtocolTierC(input.profile));
+    included.push('protocol');
+    sections.push(renderEstimationRule());
+    included.push('estimation');
+    const constraints = renderConstraints(input.state);
+    if (constraints) {
+        sections.push(constraints);
+        included.push('constraints');
+    }
+    const instructions = renderInstructions(input.resolvedInstructions);
+    if (instructions) {
+        sections.push(instructions);
+        included.push('instructions');
+    }
+    // Tier C includes everything statically — it's the only source of context
+    const traps = renderTopTraps(input.state, input.maxTraps ?? 10);
+    if (traps) {
+        sections.push(traps);
+        included.push('traps');
+    }
+    const plans = renderActivePlans(input.state, input.maxPlans ?? 10);
+    if (plans) {
+        sections.push(plans);
+        included.push('plans');
+    }
+    const decisions = renderRecentDecisions(input.state);
+    if (decisions) {
+        sections.push(decisions);
+        included.push('decisions');
+    }
+    return {
+        content: sections.join('\n\n'),
+        tier: 'C',
+        sectionsIncluded: included,
+    };
+}
+// ─── Shared section renderers ────────────────────────────────────────────────
+function renderHeader(input) {
+    return [
+        `> Managed by brainclaw v${input.brainclawVersion} — do not edit manually.`,
+        `> Regenerate: brainclaw export --format ${formatForAgent(input.profile.name)} --write`,
+    ].join('\n');
+}
+function renderWhySection(profile) {
+    const lines = [
+        '## brainclaw — why this matters',
+        '',
+        'This project uses brainclaw for shared memory and multi-agent coordination.',
+    ];
+    if (profile.hasMcp) {
+        lines.push('Other agents and developers work in this repo. Without brainclaw context:', '- You may edit files another agent is actively working on', '- You will miss known traps and architectural decisions', '- You will duplicate or contradict planned work');
+    }
+    else {
+        lines.push('Project context is maintained in brainclaw memory. This includes:', '- Active constraints that must be respected', '- Known traps to avoid repeating mistakes', '- Plans and decisions for ongoing work coordination');
+    }
+    return lines.join('\n');
+}
+function renderProtocolTierA() {
+    return [
+        '## brainclaw — session protocol',
+        '',
+        'Brainclaw context is injected automatically via hooks at each prompt.',
+        '',
+        '1. Read the injected board state before acting',
+        '2. Call `bclaw_get_context(target)` for deeper memory on a specific scope',
+        '3. Call `bclaw_claim(scope)` before editing if other agents are active',
+        '4. Call `bclaw_session_end(auto_release: true)` when done',
+    ].join('\n');
+}
+function renderProtocolTierB() {
+    return [
+        '## brainclaw — session protocol (REQUIRED)',
+        '',
+        'You MUST follow this protocol before any work in this project.',
+        '',
+        '1. Call `bclaw_session_start` — identify yourself and see the active board',
+        '2. Call `bclaw_get_context(target: "<file or dir>")` — load relevant memory',
+        '3. Call `bclaw_get_execution_context` — check for brainclaw updates',
+        '4. Check that no other agent has claimed your target scope',
+        '5. Call `bclaw_claim(scope)` before editing',
+        '6. Call `bclaw_write_note(text)` to record observations',
+        '7. Call `bclaw_session_end(auto_release: true)` when done',
+    ].join('\n');
+}
+function renderProtocolTierC(profile) {
+    const lines = [
+        '## brainclaw — project coordination',
+        '',
+    ];
+    if (profile.hasSkills) {
+        lines.push('Use the brainclaw-context skill to refresh project memory.', 'Trigger: "refresh project memory", "load brainclaw context", "inspect active plans"', '');
+    }
+    lines.push('Before working:', '- Review the constraints and active plans below', '- Check the known traps section for pitfalls in your scope', '', 'The sections below are regenerated from brainclaw memory.', 'For the freshest state, use the brainclaw skill or ask the developer to run `brainclaw context`.');
+    return lines.join('\n');
+}
+function renderEstimationRule() {
+    return [
+        '## brainclaw — plans and estimation',
+        '',
+        'When creating a plan or step, always estimate duration in minutes.',
+        'When completing, report actual effort. This calibrates future estimates.',
+    ].join('\n');
+}
+function renderVersionCheckRule() {
+    return [
+        '## brainclaw — version check',
+        '',
+        'Call `bclaw_get_execution_context` at session start to check for brainclaw updates.',
+        'If a newer version is available, inform the developer and suggest updating.',
+        'Brainclaw updates may include new features, bug fixes, and improved coordination.',
+    ].join('\n');
+}
+function renderConstraints(state) {
+    const active = state.active_constraints.filter((c) => c.status === 'active');
+    if (active.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — active constraints',
+        '',
+        ...active.map((c) => `- ${c.text}`),
+    ].join('\n');
+}
+function renderInstructions(instructions) {
+    if (instructions.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — active instructions',
+        '',
+        ...instructions.map((text) => `- ${text}`),
+    ].join('\n');
+}
+function renderTopTraps(state, limit) {
+    const traps = state.known_traps
+        .filter((t) => t.visibility === 'shared' && (!t.status || t.status === 'active') && !t.platform_scope)
+        .sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity))
+        .slice(0, limit);
+    if (traps.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — known traps',
+        '',
+        ...traps.map((t) => `- [${t.severity}] ${t.text}`),
+    ].join('\n');
+}
+function renderActivePlans(state, limit) {
+    const active = state.plan_items
+        .filter((p) => p.status === 'in_progress' || p.status === 'todo')
+        .sort((a, b) => {
+        if (a.status === 'in_progress' && b.status !== 'in_progress')
+            return -1;
+        if (b.status === 'in_progress' && a.status !== 'in_progress')
+            return 1;
+        return priorityOrder(b.priority) - priorityOrder(a.priority);
+    })
+        .slice(0, limit);
+    if (active.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — active plans',
+        '',
+        ...active.map((p) => {
+            const assignee = p.assignee ? ` (@${p.assignee})` : '';
+            return `- [${p.status}] ${p.text}${assignee}`;
+        }),
+    ].join('\n');
+}
+function renderRecentDecisions(state) {
+    const decisions = state.recent_decisions.slice(-5);
+    if (decisions.length === 0)
+        return undefined;
+    return [
+        '## brainclaw — recent decisions',
+        '',
+        ...decisions.map((d) => `- ${d.text}`),
+    ].join('\n');
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function severityOrder(severity) {
+    switch (severity) {
+        case 'high': return 3;
+        case 'medium': return 2;
+        case 'low': return 1;
+        default: return 0;
+    }
+}
+function priorityOrder(priority) {
+    switch (priority) {
+        case 'critical': return 4;
+        case 'high': return 3;
+        case 'medium': return 2;
+        case 'low': return 1;
+        default: return 0;
+    }
+}
+function formatForAgent(agentName) {
+    switch (agentName) {
+        case 'claude-code': return 'claude-md';
+        case 'cursor': return 'cursor-rules';
+        case 'github-copilot': return 'copilot-instructions';
+        case 'opencode':
+        case 'codex': return 'agents-md';
+        case 'antigravity': return 'gemini-md';
+        case 'windsurf': return 'windsurf';
+        case 'cline': return 'cline';
+        case 'roo': return 'roo';
+        case 'continue': return 'continue';
+        default: return 'agents-md';
+    }
+}
+//# sourceMappingURL=instruction-templates.js.map

package/dist/core/schema.js

@@ -96,6 +96,7 @@ export const TrapSchema = z.object({
     visibility: MemoryVisibilitySchema.default('shared'),
     host_id: z.string().optional(),
     expires_at: z.string().optional(),
+    platform_scope: z.string().optional(),
 });
 export const HandoffSchema = z.object({
     schema_version: z.number().int().positive().optional(),
@@ -484,6 +485,12 @@ export const MemorySeedSourceKindSchema = z.enum([
     'machine',
     'skill',
     'mcp',
+    'ci_config',
+    'contributing',
+    'changelog',
+    'docker',
+    'env_example',
+    'adr',
 ]);
 export const MemorySeedConfidenceSchema = z.enum(['low', 'medium', 'high']);
 export const MemorySeedDocumentSchema = z.object({
@@ -617,6 +624,7 @@ export const AgentIntegrationNameSchema = z.enum([
     'antigravity',
     'continue',
     'roo',
+    'openclaw',
 ]);
 export const AgentIntegrationSurfaceKindSchema = z.enum(['instructions', 'mcp', 'skill', 'rule', 'hook']);
 export const AgentIntegrationLocationSchema = z.enum(['workspace', 'machine']);
@@ -626,9 +634,11 @@ export const AgentIntegrationSurfaceSchema = z.object({
     location: AgentIntegrationLocationSchema,
     path: z.string().optional(),
 });
+export const AgentIntegrationLevelSchema = z.enum(['full', 'standard', 'limited', 'custom']);
 export const AgentIntegrationDeclarationSchema = z.object({
     agent_name: AgentIntegrationNameSchema,
     declaration_source: AgentIntegrationDeclarationSourceSchema.default('manual'),
+    level: AgentIntegrationLevelSchema.optional(),
     surfaces: z.array(AgentIntegrationSurfaceSchema).default([]),
     notes: z.string().optional(),
 });