brainclaw 0.19.6 → 0.19.10

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/bootstrap.js

@@ -1,12 +1,42 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
 import { memoryExists } from '../core/io.js';
-import { renderBootstrapSummary, runBootstrapProfile } from '../core/bootstrap.js';
-export function runBootstrap(options = {}) {
+import { applyBootstrapImport, renderBootstrapInterview, renderBootstrapSummary, runBootstrapProfile, uninstallBootstrapImport, } from '../core/bootstrap.js';
+export async function runBootstrap(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
     try {
+        if (options.apply && options.uninstall) {
+            console.error('Error: --apply and --uninstall are mutually exclusive.');
+            process.exit(1);
+        }
+        const audience = resolveBootstrapInterviewAudience(options.audience);
+        if (options.uninstall) {
+            await confirmBootstrapAction('Remove the last bootstrap import?', options.yes);
+            const result = uninstallBootstrapImport(cwd);
+            if (!result.receipt) {
+                console.log('No bootstrap import receipt found.');
+                return;
+            }
+            console.log(`✔ Bootstrap uninstall completed: ${result.deactivatedCount} instruction(s) deactivated, ${result.skippedCount} artifact(s) skipped.`);
+            return;
+        }
+        if (options.apply) {
+            await confirmBootstrapAction('Apply the current bootstrap import proposal to canonical memory?', options.yes);
+            const result = applyBootstrapImport({
+                target: options.for,
+                refresh: options.refresh,
+                cwd,
+            });
+            console.log(`✔ Bootstrap import applied: ${result.createdCount} item(s) created, ${result.skippedCount} suggestion(s) skipped.`);
+            if (result.receipt) {
+                console.log(`✔ Receipt saved: ${result.receipt.managed_artifacts.length} managed artifact(s) can be reverted with \`brainclaw bootstrap --uninstall\`.`);
+            }
+            return;
+        }
         const result = runBootstrapProfile({
             target: options.for,
             refresh: options.refresh,
@@ -18,17 +48,56 @@ export function runBootstrap(options = {}) {
                 target: result.profile.target,
                 repo_fingerprint: result.profile.repo_fingerprint,
                 sources_scanned: result.profile.sources_scanned,
+                workspace_kind: result.profile.workspace_kind,
+                confidence: result.profile.confidence,
+                native_instruction_files: result.profile.native_instruction_files,
+                gaps: result.profile.gaps,
                 seed_count: result.profile.seed_count,
                 seeds: result.seeds,
+                import_plan: result.importPlan,
+                last_application: result.lastApplication,
                 reused_profile: result.reusedProfile,
             }, null, 2));
             return;
         }
-        console.log(renderBootstrapSummary(result));
+        console.log(options.interview ? renderBootstrapInterview(result, audience) : renderBootstrapSummary(result));
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
+function resolveBootstrapInterviewAudience(value) {
+    if (!value) {
+        return 'any';
+    }
+    if (value === 'cli' || value === 'ide_chat' || value === 'any') {
+        return value;
+    }
+    throw new Error(`Unsupported bootstrap interview audience '${value}'. Use cli, ide_chat, or any.`);
+}
+async function confirmBootstrapAction(question, yes) {
+    if (yes) {
+        return;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error(`Error: ${question} Re-run with --yes in non-interactive mode.`);
+        process.exit(1);
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        if (answer.trim().toLowerCase() !== 'y') {
+            console.error('Cancelled.');
+            process.exit(1);
+        }
     }
     catch (error) {
         console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
         process.exit(1);
     }
+    finally {
+        rl.close();
+    }
 }
 //# sourceMappingURL=bootstrap.js.map

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/init.js

@@ -10,6 +10,7 @@ import { initMemoryRepo } from '../core/memory-git.js';
 import { buildProjectIdentity, resolveExistingProjectIdentity, saveProjectIdentity } from '../core/project-registry.js';
 import { scanProject, upsertProject } from '../core/global-registry.js';
 import { analyzeRepository, scanWorkspaceBoundaries } from '../core/repo-analysis.js';
+import { renderBootstrapSummary, runBootstrapProfile } from '../core/bootstrap.js';
 import { isAgentIntegrationName, upsertAgentIntegrationDeclaration } from '../core/agent-integrations.js';
 import { describeAutoConfigWrite, ensureAgentFiles, ensureGitignoreEntries, writeDetectedAgentAutoConfig } from '../core/agent-files.js';
 import { detectAiAgent, detectWslEnvironment } from '../core/ai-agent-detection.js';
@@ -228,6 +229,25 @@ export async function runInit(options = {}) {
     if (initMemoryRepo(cwd)) {
         console.log('✔ Initialized memory git repo for versioning');
     }
+    const onboardingPreflight = runBootstrapProfile({ cwd, refresh: true });
+    console.log('');
+    console.log('Onboarding preflight:');
+    for (const line of renderBootstrapSummary(onboardingPreflight).split('\n')) {
+        console.log(`  ${line}`);
+    }
+    if (onboardingPreflight.importPlan.suggestion_count > 0) {
+        console.log('');
+        console.log(`Next step: run 'brainclaw bootstrap --apply' to import ${onboardingPreflight.importPlan.suggestion_count} suggested item(s) into canonical memory.`);
+        console.log(`Rollback: run 'brainclaw bootstrap --uninstall' to deactivate the last bootstrap-managed import.`);
+    }
+    if ((onboardingPreflight.importPlan.interview?.question_count ?? 0) > 0) {
+        console.log('');
+        console.log(`Interview: run 'brainclaw bootstrap --interview --audience cli' for terminal agents or '--audience ide_chat' for IDE chat agents.`);
+    }
+    else if ((onboardingPreflight.profile.gaps?.length ?? 0) > 0) {
+        console.log('');
+        console.log(`Next step: review the onboarding gaps, then use 'brainclaw bootstrap --json' as the basis for an interview/import flow.`);
+    }
     console.log('');
     console.log(`Tip: run 'brainclaw context --json' to load the shared memory into your agent session.`);
 }

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) {